@unlink-xyz/core 0.1.0 → 0.1.2

package/storage/indexeddb.ts

@@ -0,0 +1,235 @@
+/**
+ * IndexedDB-backed key/value storage for Unlink Core.
+ *
+ * What this is
+ * - A durable, transactional KV store implemented on top of the browser's IndexedDB.
+ * - Two object stores: "kv" for app data, "meta" for schema/versioning.
+ *
+ * Why we implement it
+ * - We need persistent client-side state (notes, leaves, nullifiers, cfg, etc.) that survives reloads
+ *   and works in both web apps and browser extensions without introducing a new backend.
+ *
+ * When to use
+ * - Browser UIs and extensions (MV2/MV3) where persistence is required.
+ * - Any environment with a real IndexedDB (tests use `fake-indexeddb`).
+ *
+ * Trade-offs
+ * - 👍 Durable, quota-managed, non-blocking, transactional writes (atomic batch).
+ * - 👍 Works offline; no server dependency.
+ * - ⚠️ Not natively available in Node/SSR; needs a polyfill for tests only.
+ *
+ */
+
+import { CoreError } from "../errors.js";
+import { validateKey } from "../keys.js";
+import type { BatchOp, Bytes, IterOptions, KvPair, Storage } from "../types.js";
+
+const DEFAULT_DB_NAME = "unlink-core";
+const DB_VERSION = 1;
+const KV_STORE = "kv";
+const META_STORE = "meta";
+const SCHEMA_KEY = "schema_version";
+
+const copy = (value: Bytes) => new Uint8Array(value);
+
+function assertIndexedDb(): IDBFactory {
+  if (typeof indexedDB === "undefined") {
+    throw new CoreError("indexedDB is not available in this environment");
+  }
+  return indexedDB;
+}
+
+export type IndexedDbOptions = {
+  name?: string;
+};
+
+// Translate IndexedDB's event-based transaction API into a promise that resolves
+// when the transaction completes or rejects on failure/abort.
+function txDone(tx: IDBTransaction): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () =>
+      reject(tx.error ?? new CoreError("indexedDB transaction failed"));
+    tx.onabort = () =>
+      reject(tx.error ?? new CoreError("indexedDB transaction aborted"));
+  });
+}
+
+function wrapRequest<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () =>
+      reject(request.error ?? new CoreError("indexedDB request failed"));
+  });
+}
+
+// Coerce whatever IndexedDB gives us back into our Bytes type.
+function asBytes(raw: unknown): Bytes {
+  if (raw instanceof Uint8Array) return copy(raw);
+  if (raw instanceof ArrayBuffer) return copy(new Uint8Array(raw));
+  if (ArrayBuffer.isView(raw)) {
+    const view = raw as ArrayBufferView;
+    const buf = view.buffer.slice(
+      view.byteOffset,
+      view.byteOffset + view.byteLength,
+    );
+    return copy(new Uint8Array(buf));
+  }
+  throw new CoreError("indexedDB value is not binary data");
+}
+
+// IndexedDB-backed implementation implementing the storage API.
+export function createIndexedDbStorage(opts: IndexedDbOptions = {}): Storage {
+  const name = opts.name ?? DEFAULT_DB_NAME;
+  let db: IDBDatabase | null = null;
+
+  // Lazy-open the database so we only touch IndexedDB when needed.
+  async function ensureOpen(): Promise<IDBDatabase> {
+    if (db) return db;
+
+    // Guard for environments without IndexedDB (unit tests or SSR).
+    const idb: IDBFactory = assertIndexedDb();
+
+    const request = idb.open(name, DB_VERSION);
+    // Versioned schema: create one store for kv entries and one for metadata.
+    request.onupgradeneeded = () => {
+      const upgradeDb = request.result;
+      if (!upgradeDb.objectStoreNames.contains(KV_STORE)) {
+        upgradeDb.createObjectStore(KV_STORE);
+      }
+      if (!upgradeDb.objectStoreNames.contains(META_STORE)) {
+        upgradeDb.createObjectStore(META_STORE);
+      }
+    };
+    db = await new Promise<IDBDatabase>((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () =>
+        reject(request.error ?? new CoreError("indexedDB open failed"));
+      request.onblocked = () =>
+        reject(new CoreError("indexedDB open request was blocked"));
+    });
+    return db!;
+  }
+
+  // Start a transaction and give callers both the store and a completion promise.
+  const getStore = async (
+    storeName: string,
+    mode: IDBTransactionMode,
+  ): Promise<{ store: IDBObjectStore; done: Promise<void> }> => {
+    const database = await ensureOpen();
+    const tx = database.transaction(storeName, mode);
+    const done = txDone(tx);
+    return { store: tx.objectStore(storeName), done };
+  };
+
+  return {
+    async open() {
+      await ensureOpen();
+    },
+
+    async get(key: string) {
+      validateKey(key);
+      const { store, done } = await getStore(KV_STORE, "readonly");
+      const result = await wrapRequest(store.get(key));
+      await done;
+      if (result === undefined) return null;
+      return asBytes(result);
+    },
+
+    async put(key: string, value: Bytes) {
+      validateKey(key);
+      const { store, done } = await getStore(KV_STORE, "readwrite");
+      await wrapRequest(store.put(copy(value), key)); // copy avoids shared mutation; revisit if this becomes costly
+      await done;
+    },
+
+    async delete(key: string) {
+      validateKey(key);
+      const { store, done } = await getStore(KV_STORE, "readwrite");
+      await wrapRequest(store.delete(key));
+      await done;
+    },
+
+    async batch(ops: BatchOp[]) {
+      // Execute the batch within a single transaction to preserve atomicity.
+      const database = await ensureOpen();
+      const tx = database.transaction(KV_STORE, "readwrite");
+      const store = tx.objectStore(KV_STORE);
+      const done = txDone(tx);
+      try {
+        // Replay the batch within a single transaction; validation failure aborts everything.
+        for (const op of ops) {
+          if (op.put) {
+            const [key, value] = op.put;
+            validateKey(key);
+            store.put(copy(value), key); // copy avoids shared mutation; revisit if this becomes costly
+          }
+          if (op.del) {
+            validateKey(op.del);
+            store.delete(op.del);
+          }
+        }
+        await done;
+      } catch (err) {
+        try {
+          tx.abort();
+        } catch (_) {
+          /* noop */
+        }
+        await done.catch(() => {});
+        throw err;
+      }
+    },
+
+    async iter(options: IterOptions = {}) {
+      if (options.start && options.end && options.start > options.end) {
+        throw new CoreError("iter start bound must not exceed end bound");
+      }
+      // Pull everything into memory for now. TODO: stream w/ cursor when needed for perf
+      const database = await ensureOpen();
+      const tx = database.transaction(KV_STORE, "readonly");
+      const store = tx.objectStore(KV_STORE);
+      const done = txDone(tx);
+      const [keys, values] = await Promise.all([
+        wrapRequest<IDBValidKey[]>(store.getAllKeys()),
+        wrapRequest<unknown[]>(store.getAll()),
+      ]);
+      await done;
+
+      const pairs: KvPair[] = keys.map((key, idx) => {
+        if (typeof key !== "string") {
+          throw new CoreError("encountered non-string key in indexedDB");
+        }
+        const raw = values[idx];
+        return { key, value: asBytes(raw) };
+      });
+
+      let filtered = pairs.filter(({ key }) => {
+        if (options.prefix && !key.startsWith(options.prefix)) return false;
+        if (options.start && key < options.start) return false;
+        if (options.end && key > options.end) return false;
+        return true;
+      });
+
+      filtered.sort((a, b) => a.key.localeCompare(b.key));
+      if (options.reverse) filtered = filtered.reverse();
+      if (options.limit) filtered = filtered.slice(0, options.limit);
+      return filtered;
+    },
+
+    async getSchemaVersion() {
+      const { store, done } = await getStore(META_STORE, "readonly");
+      const value = await wrapRequest<number | undefined>(
+        store.get(SCHEMA_KEY),
+      );
+      await done;
+      return value ?? 0;
+    },
+
+    async setSchemaVersion(version) {
+      const { store, done } = await getStore(META_STORE, "readwrite");
+      await wrapRequest(store.put(version, SCHEMA_KEY));
+      await done;
+    },
+  };
+}

package/storage/memory.test.ts

@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { CoreError, KeyValidationError } from "../errors.js";
+import { MAX_KEY_LEN } from "../keys.js";
+import type { Storage } from "../types.js";
+import { createMemoryStorage } from "./memory.js";
+
+const encoder = new TextEncoder();
+
+describe("createMemoryStorage", () => {
+  let storage: Storage;
+
+  beforeEach(async () => {
+    storage = createMemoryStorage();
+    await storage.open();
+  });
+
+  it("returns null when key is missing", async () => {
+    const value = await storage.get("meta:missing");
+    expect(value).toBeNull();
+  });
+
+  it("roundtrips put/get values", async () => {
+    await storage.put("meta:key", encoder.encode("value"));
+    const value = await storage.get("meta:key");
+    expect(value).toEqual(encoder.encode("value"));
+  });
+
+  it("roundtrips schema version", async () => {
+    await storage.setSchemaVersion(2);
+    const version = await storage.getSchemaVersion();
+    expect(version).toBe(2);
+  });
+
+  it("rejects iter calls when start bound exceeds end bound", async () => {
+    await expect(
+      storage.iter({ start: "notes:z", end: "notes:a" }),
+    ).rejects.toBeInstanceOf(CoreError);
+  });
+
+  it("keeps batch atomic when validation fails", async () => {
+    await storage.put("meta:ok", encoder.encode("1"));
+
+    const oversizedKey = "a".repeat(MAX_KEY_LEN + 1);
+    await expect(
+      storage.batch([
+        { del: "meta:ok" },
+        { put: ["notes:new", encoder.encode("value")] },
+        { put: [oversizedKey, encoder.encode("bad")] },
+      ]),
+    ).rejects.toBeInstanceOf(KeyValidationError);
+
+    const original = await storage.get("meta:ok");
+    expect(original).toEqual(encoder.encode("1"));
+
+    const missing = await storage.get("notes:new");
+    expect(missing).toBeNull();
+  });
+});

package/storage/memory.ts

@@ -0,0 +1,93 @@
+/**
+ * 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

@@ -0,0 +1,160 @@
+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");
+  });
+});