@unlink-xyz/core 0.1.3 → 0.1.4

package/storage/memory.ts

@@ -1,93 +0,0 @@
-/**
- * In-memory key/value storage for Unlink Core.
- *
- * What this is
- * - A minimal, process-local KV store backed by a `Map<string, Uint8Array>`.
- *
- * Why we implement it
- * - Fast, dependency-free storage for unit tests, demos, and ephemeral runs.
- * - Useful as a reference driver for the Storage interface.
- *
- * When to use
- * - Unit tests (deterministic, zero I/O).
- * - CLI/Node scripts that do not need persistence beyond process lifetime.
- * - Prototyping or sandboxing Core logic.
- *
- * Trade-offs
- * - 👍 Extremely fast; zero external APIs; simple to reason about.
- * - 👍 Great for isolation in tests; easy to snapshot/clone.
- * - ⚠️ No durability (data is lost on process exit).
- * - ⚠️ Per-process only; no cross-tab or reload survival.
- *
- */
-
-import { CoreError } from "../errors.js";
-import { validateKey } from "../keys.js";
-import { BatchOp, Bytes, IterOptions, KvPair, Storage } from "../types.js";
-
-const copy = (value: Bytes) => new Uint8Array(value);
-
-export function createMemoryStorage(): Storage {
-  const data = new Map<string, Bytes>();
-  let schema = 0;
-
-  return {
-    async open() {},
-    async get(k) {
-      validateKey(k);
-      return data.has(k) ? copy(data.get(k)!) : null;
-    },
-    async put(k, v) {
-      validateKey(k);
-      data.set(k, copy(v));
-    },
-    async delete(k) {
-      validateKey(k);
-      data.delete(k);
-    },
-    async batch(ops: BatchOp[]) {
-      const draft = new Map(data);
-      for (const op of ops) {
-        if (op.put) {
-          const [k, v] = op.put;
-          validateKey(k);
-          draft.set(k, copy(v));
-        }
-        if (op.del) {
-          validateKey(op.del);
-          draft.delete(op.del);
-        }
-      }
-      data.clear();
-      for (const [k, v] of draft.entries()) {
-        data.set(k, copy(v));
-      }
-    },
-    async iter(o: IterOptions = {}): Promise<KvPair[]> {
-      if (o.start && o.end && o.start > o.end) {
-        throw new CoreError("iter start bound must not exceed end bound");
-      }
-      const all = [...data.entries()].map(([key, value]) => ({
-        key,
-        value: copy(value),
-      }));
-      let ks = all
-        .filter(
-          ({ key }) =>
-            (!o.prefix || key.startsWith(o.prefix)) &&
-            (!o.start || key >= o.start) &&
-            (!o.end || key <= o.end),
-        )
-        .sort((a, b) => a.key.localeCompare(b.key));
-      if (o.reverse) ks.reverse();
-      if (o.limit) ks = ks.slice(0, o.limit);
-      return ks;
-    },
-    async getSchemaVersion() {
-      return schema;
-    },
-    async setSchemaVersion(n: number) {
-      schema = n;
-    },
-  };
-}

package/transactions/deposit.test.ts

@@ -1,160 +0,0 @@
-import { eddsa, poseidon } from "@railgun-community/circomlibjs";
-import { Interface } from "ethers";
-import { beforeEach, describe, expect, it } from "vitest";
-
-import {
-  createMockFetch,
-  createMockIndexer,
-} from "../../test-utils/mock-indexer.js";
-import { ZkAccount } from "../account/zkAccount.js";
-import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
-import { createStateStore } from "../state/index.js";
-import { createMemoryStorage } from "../storage/index.js";
-import { createDepositClient, DEPOSIT_ABI } from "./deposit.js";
-
-const chainId = 1;
-const poolAddress = "0x1111111111111111111111111111111111111111";
-const depositor = "0x2222222222222222222222222222222222222222";
-const token = "0x3333333333333333333333333333333333333333";
-
-const mockPrivateKey = Buffer.from(new Uint8Array(32).fill(1));
-const mockPublicKey = eddsa.prv2pub(mockPrivateKey);
-const mockNullifyingKey = 987n;
-const mockMpk = poseidon([
-  mockPublicKey[0],
-  mockPublicKey[1],
-  mockNullifyingKey,
-]);
-const mockZkAccount: ZkAccount = {
-  spendingKeyPair: {
-    privateKey: mockPrivateKey,
-    pubkey: mockPublicKey,
-  },
-  viewingKeyPair: {
-    privateKey: Buffer.from(new Uint8Array(32).fill(2)),
-    pubkey: Buffer.from(new Uint8Array(32).fill(3)),
-  },
-  nullifyingKey: mockNullifyingKey,
-  masterPublicKey: mockMpk,
-};
-
-const depositInterface = new Interface(DEPOSIT_ABI);
-
-describe.skip("deposit client", () => {
-  let state: ReturnType<typeof createStateStore>;
-  let client: ReturnType<typeof createDepositClient>;
-  let fetchMock: ReturnType<typeof createMockFetch>;
-  let indexer: ReturnType<typeof createMockIndexer>;
-
-  beforeEach(async () => {
-    const storage = createMemoryStorage();
-    await storage.open();
-    state = createStateStore(storage);
-    indexer = createMockIndexer();
-    fetchMock = createMockFetch(indexer);
-    client = createDepositClient(state, { fetch: fetchMock });
-  });
-
-  it("builds calldata, enqueues relay, and syncs state via indexer", async () => {
-    const request = {
-      zkAccount: mockZkAccount,
-      chainId,
-      poolAddress,
-      depositor,
-      note: {
-        mpk: 7n,
-        random: 8n,
-        amount: 5n,
-        token,
-      },
-    } as const;
-
-    const expectedNpk = poseidon([request.note.mpk, request.note.random]);
-    const expectedCommitment = poseidon([
-      expectedNpk,
-      BigInt(token),
-      request.note.amount,
-    ]);
-    const expectedCommitmentHex = ByteUtils.nToHex(
-      expectedCommitment,
-      ByteLength.UINT_256,
-      true,
-    );
-
-    const relay = await client.request(request);
-    expect(relay.commitment).toBe(expectedCommitmentHex);
-    indexer.publish(chainId, relay.commitment);
-    const result = await client.syncPendingDeposit(relay.relayId);
-
-    expect(result.chainId).toBe(chainId);
-    expect(result.index).toBe(0);
-    expect(result.commitment).toBe(expectedCommitmentHex);
-    expect(result.root).toMatch(/^0x[0-9a-f]+$/);
-
-    const decoded = depositInterface.decodeFunctionData(
-      "deposit",
-      relay.calldata,
-    );
-    expect(decoded[0]).toBe(depositor);
-    expect(decoded[1][0].npk).toBe(expectedNpk);
-    expect(decoded[1][0].amount).toBe(request.note.amount);
-    expect(decoded[1][0].token).toBe(token);
-
-    const storedLeaf = await state.getLeaf(chainId, result.index);
-    expect(storedLeaf?.commitment).toBe(result.commitment);
-
-    const storedRoot = await state.getRoot(chainId, result.root);
-    expect(storedRoot?.root).toBe(result.root);
-  });
-
-  it("tracks indexes per chain independently", async () => {
-    const firstNote = { mpk: 1n, random: 2n, amount: 2n, token };
-    const firstRequest = await client.request({
-      zkAccount: mockZkAccount,
-      chainId,
-      poolAddress,
-      depositor,
-      note: firstNote,
-    });
-    indexer.publish(chainId, firstRequest.commitment);
-    const first = await client.syncPendingDeposit(firstRequest.relayId);
-
-    const secondNote = { mpk: 3n, random: 4n, amount: 4n, token };
-    const secondRequest = await client.request({
-      zkAccount: mockZkAccount,
-      chainId,
-      poolAddress,
-      depositor,
-      note: secondNote,
-    });
-    indexer.publish(chainId, secondRequest.commitment);
-    const second = await client.syncPendingDeposit(secondRequest.relayId);
-
-    const otherNote = { mpk: 5n, random: 6n, amount: 6n, token };
-    const otherRequest = await client.request({
-      zkAccount: mockZkAccount,
-      chainId: 10,
-      poolAddress,
-      depositor,
-      note: otherNote,
-    });
-    indexer.publish(10, otherRequest.commitment);
-    const otherChain = await client.syncPendingDeposit(otherRequest.relayId);
-
-    expect(first.index).toBe(0);
-    expect(second.index).toBe(1);
-    expect(otherChain.index).toBe(0);
-  });
-
-  it("rejects invalid chain ids", async () => {
-    await expect(
-      client.request({
-        zkAccount: mockZkAccount,
-        chainId: 0,
-        poolAddress,
-        depositor,
-        note: { mpk: 1n, random: 1n, amount: 1n, token },
-      }),
-    ).rejects.toThrow("chainId must be a positive integer");
-  });
-});

package/transactions/deposit.ts

@@ -1,227 +0,0 @@
-import { Interface } from "ethers";
-import { v4 as uuidv4 } from "uuid";
-
-import { FetchLike } from "../clients/http.js";
-import { CommitmentRecord, createIndexerClient } from "../clients/indexer.js";
-import { serviceConfig } from "../config.js";
-import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
-import {
-  createMerkleTrees,
-  DEFAULT_JOB_TIMEOUT_MS,
-  LocalMerkleTrees,
-  rebuildTreeFromStore,
-  type PendingDepositJob,
-} from "../state/index.js";
-import { isNotFoundError, sleep } from "../utils/async.js";
-import { parseHexToBigInt } from "../utils/bigint.js";
-import { computeCommitment, deriveNpk, encryptNote } from "../utils/crypto.js";
-import {
-  DEFAULT_POLL_INTERVAL_MS,
-  DEFAULT_POLL_TIMEOUT_MS,
-  MAX_POLL_INTERVAL_MS,
-} from "../utils/polling.js";
-import { ensureAddress, ensureChainId } from "../utils/validators.js";
-import type {
-  DepositRelayResult,
-  DepositRequest,
-  DepositStateStore,
-  DepositSyncResult,
-} from "./types.js";
-
-export const DEPOSIT_ABI = [
-  "function deposit(address _depositor, (uint256 npk, uint256 amount, address token)[] notes, (uint256[3] data)[] ciphertexts)",
-] as const;
-const depositInterface = new Interface(DEPOSIT_ABI);
-
-type DepositClientOptions = {
-  merkleTrees?: LocalMerkleTrees;
-  fetch: FetchLike;
-  pollIntervalMs?: number;
-  pollTimeoutMs?: number;
-};
-
-function validateDepositRequest(request: DepositRequest) {
-  ensureChainId(request.chainId);
-  ensureAddress("pool address", request.poolAddress);
-  ensureAddress("depositor", request.depositor);
-  ensureAddress("token", request.note.token);
-
-  if (request.note.mpk < 0n) {
-    throw new Error("mpk must be non-negative");
-  }
-  if (request.note.random < 0n) {
-    throw new Error("random must be non-negative");
-  }
-  if (request.note.amount < 0n) {
-    throw new Error("amount must be non-negative");
-  }
-  const tokenScalar = BigInt(request.note.token);
-  if (tokenScalar < 0n) {
-    throw new Error("token must map to non-negative scalar");
-  }
-}
-
-export function createDepositClient(
-  stateStore: DepositStateStore,
-  options: DepositClientOptions,
-) {
-  if (!stateStore) {
-    throw new Error("stateStore dependency is required");
-  }
-
-  const merkleTrees = options.merkleTrees ?? createMerkleTrees();
-  const indexerClient = createIndexerClient(serviceConfig.indexerBaseUrl, {
-    fetch: options.fetch,
-  });
-
-  function buildCalldata(request: DepositRequest, npk: bigint) {
-    return depositInterface.encodeFunctionData("deposit", [
-      request.depositor,
-      [
-        // TODO(julienbrs) handle multiple notes
-        {
-          npk: npk,
-          amount: request.note.amount,
-          token: request.note.token,
-        },
-      ],
-      [
-        {
-          data: encryptNote(request.note).data,
-        },
-      ],
-    ]);
-  }
-
-  async function persistDepositSuccess(
-    job: PendingDepositJob,
-    record: CommitmentRecord,
-    indexedRoot: string,
-  ) {
-    await Promise.all([
-      stateStore.putLeaf({
-        chainId: job.chainId,
-        index: record.index,
-        commitment: record.commitment,
-      }),
-      stateStore.putRoot({
-        chainId: job.chainId,
-        root: indexedRoot,
-      }),
-      stateStore.putPendingJob({
-        ...job,
-        status: "succeeded",
-        lastCheckedAt: Date.now(),
-        txHash: record.txHash ?? job.txHash ?? null,
-        predictedCommitment: {
-          ...job.predictedCommitment,
-          index: record.index,
-          root: indexedRoot,
-        },
-      }),
-    ]);
-  }
-
-  return {
-    async request(request: DepositRequest): Promise<DepositRelayResult> {
-      validateDepositRequest(request);
-
-      const npk = deriveNpk(request);
-      const calldata = buildCalldata(request, npk);
-      const commitment = computeCommitment(request, npk);
-      const commitmentHex = ByteUtils.nToHex(
-        commitment,
-        ByteLength.UINT_256,
-        true,
-      );
-      const relayId = uuidv4();
-      const job: PendingDepositJob = {
-        relayId,
-        kind: "deposit",
-        chainId: request.chainId,
-        status: "pending",
-        broadcasterRelayId: null,
-        txHash: null,
-        createdAt: Date.now(),
-        timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
-        predictedCommitment: {
-          hex: commitmentHex,
-        },
-      };
-      await stateStore.putPendingJob(job);
-      return { relayId, calldata, commitment: commitmentHex };
-    },
-
-    async syncPendingDeposit(relayId: string): Promise<DepositSyncResult> {
-      const job = await stateStore.getPendingJob(relayId);
-      if (!job || job.kind !== "deposit") {
-        throw new Error(`unknown deposit relay ${relayId}`);
-      }
-      await rebuildTreeFromStore({
-        chainId: job.chainId,
-        trees: merkleTrees,
-        loadLeaf: stateStore.getLeaf.bind(stateStore),
-      });
-      const commitmentHex = job.predictedCommitment.hex;
-      const record = await waitForCommitment(job.chainId, commitmentHex);
-      const { index, root: indexedRoot } = record;
-
-      const commitmentValue = parseHexToBigInt(commitmentHex);
-      const { index: localIndex, root: localRoot } = merkleTrees.addLeaf(
-        job.chainId,
-        commitmentValue,
-      );
-      // TODO: if local state drift detected, need to re-sync since last correct state
-      if (localIndex !== index) {
-        throw new Error(
-          "local merkle tree desynchronized (index mismatch), local index: " +
-            localIndex +
-            ", indexed index: " +
-            index,
-        );
-      }
-      if (localRoot.toLowerCase() !== indexedRoot.toLowerCase()) {
-        throw new Error(
-          "local merkle tree desynchronized (root mismatch), local root: " +
-            localRoot +
-            ", indexed root: " +
-            indexedRoot,
-        );
-      }
-
-      await persistDepositSuccess(job, record, indexedRoot);
-      return {
-        chainId: job.chainId,
-        index,
-        commitment: record.commitment,
-        root: indexedRoot,
-      };
-    },
-  };
-
-  async function waitForCommitment(
-    chainId: number,
-    commitmentHex: string,
-  ): Promise<CommitmentRecord> {
-    const timeout = options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-    const startedAt = Date.now();
-    let delay = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-
-    while (Date.now() - startedAt <= timeout) {
-      try {
-        const record = await indexerClient.getCommitment({
-          chainId,
-          commitment: commitmentHex,
-        });
-        if (record) return record;
-      } catch (err) {
-        if (!isNotFoundError(err)) {
-          throw err;
-        }
-      }
-      await sleep(delay);
-      delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
-    }
-    throw new Error("commitment not found in indexer before timeout");
-  }
-}

package/transactions/index.ts

@@ -1,20 +0,0 @@
-export { createDepositClient } from "./deposit.js";
-export { createTransactService } from "./transact.js";
-export { createJobReconciler } from "./reconcile.js";
-export { createNoteSyncService } from "./note-sync.js";
-export type { NoteSyncStateStore } from "./note-sync.js";
-export type {
-  DepositRelayResult,
-  DepositNoteInput,
-  DepositRequest,
-  DepositSyncResult,
-  DepositStateStore,
-  Proof,
-  OutputNoteInput,
-  SpendNoteReference,
-  TransactRelayResult,
-  TransactRequest,
-  TransactSyncResult,
-  TransactStateStore,
-  WithdrawalNoteInput,
-} from "./types.js";

package/transactions/note-sync.test.ts

@@ -1,155 +0,0 @@
-import "fake-indexeddb/auto";
-
-import { poseidon } from "@railgun-community/circomlibjs";
-import { createMemoryStorage, createStateStore, ZkAccount } from "@unlink/core";
-import { describe, expect, it } from "vitest";
-
-import {
-  createMockFetch,
-  createMockIndexer,
-} from "../../test-utils/mock-indexer.js";
-import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
-import { formatUint256 } from "../utils/bigint.js";
-import { encryptNote } from "../utils/crypto.js";
-import { createNoteSyncService } from "./note-sync.js";
-
-const chainId = 1;
-const token = "0x1111111111111111111111111111111111111111";
-const random = 0x5n;
-const amount = 10n;
-const masterPublicKey = 0x1234567890abcdefn;
-const account: ZkAccount = {
-  spendingKeyPair: {
-    privateKey: new Uint8Array(32),
-    pubkey: [0n, 0n],
-  },
-  viewingKeyPair: {
-    privateKey: new Uint8Array(32),
-    pubkey: new Uint8Array(32),
-  },
-  nullifyingKey: 777n,
-  masterPublicKey,
-};
-
-function cipherToHexSet(ciphertext: ReturnType<typeof encryptNote>) {
-  return ciphertext.data.map((value) => formatUint256(value)) as [
-    string,
-    string,
-    string,
-  ];
-}
-
-function ciphertextToBytes(ciphertext: ReturnType<typeof encryptNote>) {
-  const payload = new Uint8Array(ByteLength.UINT_256 * ciphertext.data.length);
-  ciphertext.data.forEach((value, index) => {
-    const start = index * ByteLength.UINT_256;
-    payload.set(ByteUtils.hexStringToBytes(formatUint256(value)), start);
-  });
-  return payload;
-}
-
-describe("note sync service", () => {
-  it("stores decryptable notes", async () => {
-    const storage = createMemoryStorage();
-    await storage.open();
-    const state = createStateStore(storage);
-    const indexer = createMockIndexer();
-    const fetchMock = createMockFetch(indexer);
-    const service = createNoteSyncService(state, { fetch: fetchMock });
-
-    const npk = poseidon([masterPublicKey, random]);
-    const commitmentValue = poseidon([npk, BigInt(token), amount]);
-    const commitmentHex = formatUint256(commitmentValue);
-    const ciphertext = encryptNote({
-      mpk: masterPublicKey,
-      random,
-      amount,
-      token,
-    });
-    const ciphertextHex = cipherToHexSet(ciphertext);
-
-    indexer.publish(chainId, commitmentHex, ciphertextHex);
-    const syncedNotes = await service.sync(chainId, account);
-
-    expect(syncedNotes).toHaveLength(1);
-    const storedNote = await state.getNote(chainId, 0);
-    expect(storedNote?.commitment).toBe(commitmentHex);
-    expect(storedNote?.mpk).toBe(formatUint256(masterPublicKey));
-    expect(storedNote?.token).toBe(token);
-    expect(storedNote?.value).toBe(amount.toString());
-
-    const storedCiphertext = await state.getCiphertext(chainId, 0);
-    expect(storedCiphertext).not.toBeNull();
-    expect(storedCiphertext).toEqual(ciphertextToBytes(ciphertext));
-
-    const leaf = await state.getLeaf(chainId, 0);
-    expect(leaf?.commitment).toBe(commitmentHex);
-
-    expect(syncedNotes[0]?.commitment).toBe(commitmentHex);
-  });
-
-  it("ignores ciphertexts for other accounts", async () => {
-    const storage = createMemoryStorage();
-    await storage.open();
-    const state = createStateStore(storage);
-    const indexer = createMockIndexer();
-    const fetchMock = createMockFetch(indexer);
-    const service = createNoteSyncService(state, { fetch: fetchMock });
-
-    const otherMpk = masterPublicKey + 1n;
-    const npk = poseidon([otherMpk, random]);
-    const commitmentValue = poseidon([npk, BigInt(token), amount]);
-    const commitmentHex = formatUint256(commitmentValue);
-    const ciphertext = encryptNote({
-      mpk: otherMpk,
-      random,
-      amount,
-      token,
-    });
-    const ciphertextHex = cipherToHexSet(ciphertext);
-
-    indexer.publish(chainId, commitmentHex, ciphertextHex);
-    const syncedNotes = await service.sync(chainId, account);
-
-    expect(syncedNotes).toHaveLength(0);
-    expect(await state.getNote(chainId, 0)).toBeNull();
-    expect(await state.getCiphertext(chainId, 0)).toBeNull();
-  });
-
-  it("marks notes as spent when nullifier exists on-chain", async () => {
-    const storage = createMemoryStorage();
-    await storage.open();
-    const state = createStateStore(storage);
-    const indexer = createMockIndexer();
-    const fetchMock = createMockFetch(indexer);
-    const service = createNoteSyncService(state, { fetch: fetchMock });
-
-    const npk = poseidon([masterPublicKey, random]);
-    const commitmentValue = poseidon([npk, BigInt(token), amount]);
-    const commitmentHex = formatUint256(commitmentValue);
-    const ciphertext = encryptNote({
-      mpk: masterPublicKey,
-      random,
-      amount,
-      token,
-    });
-    const ciphertextHex = cipherToHexSet(ciphertext);
-
-    // Compute the nullifier that would be created for this note
-    const nullifier = poseidon([account.nullifyingKey, BigInt(0)]);
-    const nullifierHex = formatUint256(nullifier);
-
-    // Publish commitment and mark nullifier as spent on-chain
-    indexer.publish(chainId, commitmentHex, ciphertextHex);
-    indexer.spendNullifier(chainId, nullifierHex);
-
-    // Sync and verify note is marked as spent
-    const syncedNotes = await service.sync(chainId, account);
-    expect(syncedNotes).toHaveLength(1);
-
-    const storedNote = await state.getNote(chainId, 0);
-    expect(storedNote?.commitment).toBe(commitmentHex);
-    expect(storedNote?.spentAt).toBeDefined();
-    expect(storedNote?.spentAt).toBeGreaterThan(0);
-  });
-});