@unlink-xyz/core 0.1.0 → 0.1.2

package/state/store/note-store.ts

@@ -0,0 +1,177 @@
+import { CoreError } from "../../errors.js";
+import { keys } from "../../keys.js";
+import type { BatchOp, Storage } from "../../types.js";
+import {
+  decodeJson,
+  encodeJson,
+  getJson,
+  type JsonRecord,
+} from "../../utils/json-codec.js";
+import {
+  ensureBigIntString,
+  ensureChainId,
+  ensureMpk,
+  ensurePositiveInt,
+} from "../../utils/validators.js";
+import type { NoteInsert, NoteRecord } from "../store/records.js";
+
+export const emptyBytes = () => new Uint8Array(0);
+
+export function createNoteStore(storage: Storage) {
+  const persistNote = async (record: NoteRecord) => {
+    ensureChainId(record.chainId);
+    ensurePositiveInt("note index", record.index);
+    ensureMpk(record.mpk);
+    ensureBigIntString("note value", record.value);
+    if (record.spentAt !== undefined) {
+      ensurePositiveInt("note spentAt", record.spentAt);
+    }
+
+    const noteKey = keys.note(record.chainId, record.index);
+    const previous = await getJson<NoteRecord>(storage, noteKey);
+
+    const ops: BatchOp[] = [
+      { put: [noteKey, encodeJson(record as JsonRecord)] },
+    ];
+
+    if (previous && previous.spentAt === undefined) {
+      ops.push({
+        del: keys.unspent(previous.chainId, previous.mpk, previous.index),
+      });
+    }
+
+    if (record.spentAt === undefined) {
+      // idx:notes:unspent functions as a set, so we only persist the sentinel bytes.
+      ops.push({
+        put: [
+          keys.unspent(record.chainId, record.mpk, record.index),
+          emptyBytes(),
+        ],
+      });
+    } else {
+      ops.push({
+        del: keys.unspent(record.chainId, record.mpk, record.index),
+      });
+    }
+
+    await storage.batch(ops);
+  };
+
+  const store = {
+    /**
+     * Upsert a note record and maintain the unspent-note index for fast balance queries.
+     * If the note already exists and is marked as spent, preserve the spentAt field.
+     */
+    async putNote(note: NoteInsert) {
+      const noteKey = keys.note(note.chainId, note.index);
+      const existing = await getJson<NoteRecord>(storage, noteKey);
+      if (existing?.spentAt !== undefined) {
+        // Preserve spentAt if note was already marked as spent
+        await persistNote({ ...note, spentAt: existing.spentAt });
+      } else {
+        await persistNote({ ...note });
+      }
+    },
+
+    /**
+     * Fetch a note by (chainId, index) if it exists in local storage.
+     */
+    async getNote(chainId: number, index: number) {
+      ensureChainId(chainId);
+      ensurePositiveInt("note index", index);
+      return getJson<NoteRecord>(storage, keys.note(chainId, index));
+    },
+
+    /**
+     * List notes matching optional filters (by chainId, mpk) and spent state.
+     */
+    async listNotes(
+      options: {
+        chainId?: number;
+        mpk?: string;
+        token?: string;
+        includeSpent?: boolean;
+      } = {},
+    ) {
+      const { chainId, mpk, token, includeSpent = true } = options;
+      if (chainId !== undefined) {
+        ensureChainId(chainId);
+      }
+      if (mpk !== undefined) {
+        ensureMpk(mpk);
+      }
+
+      const prefix = chainId !== undefined ? `notes:${chainId}:` : "notes:";
+      const entries = await storage.iter({ prefix });
+      const filtered = entries
+        .map(({ value }) => decodeJson<NoteRecord>(value))
+        .filter(
+          (note) =>
+            (chainId === undefined || note.chainId === chainId) &&
+            (mpk === undefined || note.mpk === mpk) &&
+            (token === undefined || note.token === token) &&
+            (includeSpent || note.spentAt === undefined),
+        );
+      filtered.sort((a, b) => a.index - b.index);
+      return filtered;
+    },
+
+    /**
+     * Mark a cached note as spent by setting its timestamp and re-indexing metadata.
+     */
+    async markNoteSpent(chainId: number, index: number, spentAt = Date.now()) {
+      ensureChainId(chainId);
+      ensurePositiveInt("note index", index);
+      ensurePositiveInt("note spentAt", spentAt);
+      const existing = await store.getNote(chainId, index);
+      if (!existing) {
+        throw new CoreError("note not found");
+      }
+      if (existing.spentAt === spentAt) {
+        return existing;
+      }
+      const updated: NoteRecord = { ...existing, spentAt };
+      await persistNote(updated);
+      return updated;
+    },
+
+    /**
+     * Drop the spent marker from a cached note, returning it to the unspent index.
+     */
+    async markNoteUnspent(chainId: number, index: number) {
+      ensureChainId(chainId);
+      ensurePositiveInt("note index", index);
+      const existing = await store.getNote(chainId, index);
+      if (!existing) {
+        throw new CoreError("note not found");
+      }
+      if (existing.spentAt === undefined) {
+        return existing;
+      }
+      const updated: NoteRecord = { ...existing };
+      delete updated.spentAt;
+      await persistNote(updated);
+      return updated;
+    },
+
+    /**
+     * Aggregate unspent note balances per token for a given master public key.
+     */
+    async getZkBalances(mpk: string, options: { chainId?: number } = {}) {
+      ensureMpk(mpk);
+      const notes = await store.listNotes({
+        chainId: options.chainId,
+        mpk,
+        includeSpent: false,
+      });
+      const totals: Record<string, bigint> = {};
+      for (const note of notes) {
+        const amount = BigInt(note.value);
+        totals[note.token] = (totals[note.token] ?? 0n) + amount;
+      }
+      return totals;
+    },
+  };
+
+  return store;
+}

package/state/store/nullifier-store.ts

@@ -0,0 +1,39 @@
+import { keys } from "../../keys.js";
+import type { Storage } from "../../types.js";
+import { getJson, putJson } from "../../utils/json-codec.js";
+import { ensureChainId } from "../../utils/validators.js";
+import type { NullifierRecord } from "../store/records.js";
+
+export function createNullifierStore(storage: Storage) {
+  return {
+    /**
+     * Record a nullifier observation so later syncs can de-duplicate work.
+     */
+    async putNullifier(nullifier: NullifierRecord) {
+      ensureChainId(nullifier.chainId);
+      await putJson(
+        storage,
+        keys.nullifier(nullifier.chainId, nullifier.nullifier),
+        nullifier,
+      );
+    },
+
+    /**
+     * Lookup a previously observed nullifier by value.
+     */
+    async getNullifier(chainId: number, value: string) {
+      ensureChainId(chainId);
+      return getJson<NullifierRecord>(storage, keys.nullifier(chainId, value));
+    },
+
+    /**
+     * Count all nullifiers stored locally for a given chain.
+     */
+    async countNullifiers(chainId: number): Promise<number> {
+      ensureChainId(chainId);
+      const prefix = `nullifiers:${chainId}:`;
+      const entries = await storage.iter({ prefix });
+      return entries.length;
+    },
+  };
+}

package/state/store/records.ts

@@ -0,0 +1,61 @@
+/**
+ * Locally cached metadata for a deposit note we consider owned.
+ */
+export type NoteRecord = {
+  chainId: number;
+  /** Leaf index within the on-chain tree (zero-based, monotonic). */
+  index: number;
+  /** Canonical asset identifier, typically the ERC-20 address lowercased. */
+  token: string;
+  /** Amount expressed as an unsigned BigInt serialized to a base-10 string. */
+  value: string;
+  /** Commitment stored on-chain (Poseidon(note)). */
+  commitment: string;
+  /** Note public key derived from the master public key. */
+  npk: string;
+  /**
+   * Master public key for the account (Poseidon(spendingPk.public, nullifyingKey)).
+   * Acts as the stable account identifier when grouping notes locally.
+   */
+  mpk: string;
+  /** Randomizer used when committing the note. */
+  random: string;
+  /** Nullifier that will be revealed when the note is spent. */
+  nullifier: string;
+  /** Optional timestamp when the note was marked as spent. */
+  spentAt?: number;
+};
+
+// prettier-ignore
+export type NoteInsert = Omit<NoteRecord, 'spentAt'>;
+
+/**
+ * Details about a nullifier observed on-chain, whether or not we own the note.
+ */
+export type NullifierRecord = {
+  chainId: number;
+  /** Nullifier value (expected to match NoteRecord.nullifier). */
+  nullifier: string;
+  /** Leaf index of the corresponding note when known. */
+  noteIndex?: number;
+};
+
+/**
+ * Public information about a leaf commitment inserted into the pool's tree.
+ */
+export type LeafRecord = {
+  chainId: number;
+  /** Leaf index inside the tree (zero-based). */
+  index: number;
+  /** Commitment value stored in the tree. */
+  commitment: string;
+};
+
+/**
+ * Historical merkle root snapshot used for proof construction.
+ */
+export type RootRecord = {
+  chainId: number;
+  /** Merkle root value committed on-chain. */
+  root: string;
+};

package/state/store/root-store.ts

@@ -0,0 +1,34 @@
+import { CoreError } from "../../errors.js";
+import { keys, validateKey } from "../../keys.js";
+import type { Storage } from "../../types.js";
+import { getJson, putJson } from "../../utils/json-codec.js";
+import { ensureChainId } from "../../utils/validators.js";
+import type { RootRecord } from "../store/records.js";
+
+export function createRootStore(storage: Storage) {
+  return {
+    /**
+     * Persist a historical root snapshot for proof generation.
+     */
+    async putRoot(root: RootRecord) {
+      ensureChainId(root.chainId);
+      if (typeof root.root !== "string" || root.root.length === 0) {
+        throw new CoreError("root value must be a non-empty string");
+      }
+      const key = keys.root(root.chainId, root.root);
+      validateKey(key);
+      await putJson(storage, key, root);
+    },
+
+    /**
+     * Retrieve a root snapshot by Merkle root value.
+     */
+    async getRoot(chainId: number, value: string) {
+      ensureChainId(chainId);
+      if (typeof value !== "string" || value.length === 0) {
+        throw new CoreError("root value must be a non-empty string");
+      }
+      return getJson<RootRecord>(storage, keys.root(chainId, value));
+    },
+  };
+}

package/state/store/store.ts

@@ -0,0 +1,25 @@
+import type { Storage } from "../../types.js";
+import { createCiphertextStore } from "./ciphertext-store.js";
+import { createJobStore } from "./job-store.js";
+import { createLeafStore } from "./leaf-store.js";
+import { createNoteStore } from "./note-store.js";
+import { createNullifierStore } from "./nullifier-store.js";
+import { createRootStore } from "./root-store.js";
+
+export function createStateStore(storage: Storage) {
+  const notes = createNoteStore(storage);
+  const nullifiers = createNullifierStore(storage);
+  const leaves = createLeafStore(storage);
+  const roots = createRootStore(storage);
+  const ciphertexts = createCiphertextStore(storage);
+  const jobs = createJobStore(storage);
+
+  return {
+    ...notes,
+    ...nullifiers,
+    ...leaves,
+    ...roots,
+    ...ciphertexts,
+    ...jobs,
+  };
+}

package/state.test.ts

@@ -0,0 +1,235 @@
+import "fake-indexeddb/auto";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { createStateStore } from "./state/index.js";
+import {
+  createIndexedDbStorage,
+  createMemoryStorage,
+} from "./storage/index.js";
+import type { Storage } from "./types.js";
+
+type StoreFactory = {
+  name: string;
+  setup(): Promise;
+};
+
+async function deleteIndexeddbDatabase(name: string) {
+  await new Promise<void>((resolve, reject) => {
+    const request = indexedDB.deleteDatabase(name);
+    request.onsuccess = () => resolve();
+    request.onerror = () =>
+      reject(request.error ?? new Error("failed to delete indexedDB"));
+    request.onblocked = () =>
+      reject(new Error("indexedDB deletion was blocked"));
+  });
+}
+
+const factories: StoreFactory[] = [
+  {
+    name: "memory",
+    async setup() {
+      const storage = createMemoryStorage();
+      await storage.open();
+      return { storage };
+    },
+  },
+  {
+    name: "indexeddb",
+    async setup() {
+      const dbName = `unlink-state-test-${Math.random().toString(6)}`;
+      await deleteIndexeddbDatabase(dbName).catch(() => {});
+      const storage = createIndexedDbStorage({ name: dbName });
+      await storage.open();
+      return {
+        storage,
+        cleanup: () => deleteIndexeddbDatabase(dbName).catch(() => {}),
+      };
+    },
+  },
+];
+
+describe.each(factories)("state store (%s)", ({ name, setup }) => {
+  let storage: Storage;
+  let cleanup: (() => Promise) | undefined;
+  let state: ReturnType;
+
+  beforeEach(async () => {
+    const prepared = await setup();
+    storage = prepared.storage;
+    cleanup = prepared.cleanup;
+    state = createStateStore(storage);
+  });
+
+  afterEach(async () => {
+    await cleanup?.();
+  });
+
+  it(`stores and loads note records [${name}]`, async () => {
+    const inserted = {
+      chainId: 1,
+      index: 5,
+      token: "0xToken",
+      value: "42",
+      commitment: "0xcommitment",
+      npk: "0xnpk",
+      mpk: "0xmpk",
+      random: "0xrandom",
+      nullifier: "0xnullifier",
+    };
+
+    await state.putNote(inserted);
+
+    const fetched = await state.getNote(1, 5);
+    expect(fetched).toEqual(inserted);
+  });
+
+  it(`stores and loads nullifier records [${name}]`, async () => {
+    const inserted = {
+      chainId: 1,
+      nullifier: "0xdeadbeef",
+      noteIndex: 12,
+    };
+
+    await state.putNullifier(inserted);
+
+    const fetched = await state.getNullifier(1, "0xdeadbeef");
+    expect(fetched).toEqual(inserted);
+  });
+
+  it(`stores and loads leaf records [${name}]`, async () => {
+    const inserted = {
+      chainId: 137,
+      index: 2,
+      commitment: "0xleaf",
+    };
+
+    await state.putLeaf(inserted);
+
+    const fetched = await state.getLeaf(137, 2);
+    expect(fetched).toEqual(inserted);
+  });
+
+  it(`stores and loads root records [${name}]`, async () => {
+    const inserted = {
+      chainId: 10,
+      root: "0xroot",
+    };
+
+    await state.putRoot(inserted);
+
+    const fetched = await state.getRoot(10, "0xroot");
+    expect(fetched).toEqual(inserted);
+  });
+
+  it(`stores ciphertext payloads [${name}]`, async () => {
+    const payload = new Uint8Array([1, 2, 3, 4]);
+
+    await state.putCiphertext(1, 7, payload);
+
+    const fetched = await state.getCiphertext(1, 7);
+    expect(fetched).not.toBeNull();
+    expect(fetched).toEqual(payload);
+
+    if (fetched) {
+      fetched[0] = 99;
+      const second = await state.getCiphertext(1, 7);
+      expect(second).toEqual(payload);
+    }
+  });
+
+  it(`lists notes by account and spent status [${name}]`, async () => {
+    const mpkA = "0xmpkA";
+    const mpkB = "0xmpkB";
+
+    const base = {
+      chainId: 1,
+      token: "0xToken",
+      value: "5",
+      commitment: "0xcommitment",
+      npk: "0xnpk",
+      random: "0xrandom",
+    } as const;
+
+    await state.putNote({
+      ...base,
+      index: 1,
+      nullifier: "0xnullifier1",
+      mpk: mpkA,
+    });
+    await state.putNote({
+      ...base,
+      index: 2,
+      nullifier: "0xnullifier2",
+      mpk: mpkA,
+    });
+    await state.putNote({
+      ...base,
+      index: 3,
+      nullifier: "0xnullifier3",
+      mpk: mpkB,
+    });
+
+    await state.markNoteSpent(1, 2, 123);
+
+    const allForA = await state.listNotes({ mpk: mpkA });
+    expect(allForA.map((n) => n.index).sort((a, b) => a - b)).toEqual([1, 2]);
+
+    const activeForA = await state.listNotes({
+      mpk: mpkA,
+      includeSpent: false,
+    });
+    expect(activeForA.map((n) => n.index)).toEqual([1]);
+
+    const allForB = await state.listNotes({ mpk: mpkB });
+    expect(allForB).toHaveLength(1);
+    expect(allForB[0]?.index).toBe(3);
+  });
+
+  it(`aggregates zk balances per asset [${name}]`, async () => {
+    const mpk = "0xmpkBalance";
+
+    const note = (index: number, overrides: Partial = {}) => ({
+      chainId: 1,
+      index,
+      token: "0xTokenA",
+      value: `${index * 10}`,
+      commitment: `0xcommit-${index}`,
+      npk: `0xnpk-${index}`,
+      mpk,
+      random: `0xrandom-${index}`,
+      nullifier: `0xnullifier-${index}`,
+      ...overrides,
+    });
+
+    await state.putNote(note(1, { value: "100" }));
+    await state.putNote(note(2, { value: "50" }));
+    await state.putNote(
+      note(3, { token: "0xTokenB", value: "5", nullifier: "0xnullifier-b" }),
+    );
+    await state.putNote(
+      note(4, {
+        mpk: "0xother",
+        nullifier: "0xnullifier-other",
+        value: "999",
+      }),
+    );
+
+    await state.markNoteSpent(1, 2, 456);
+
+    const balances = await state.getZkBalances(mpk, { chainId: 1 });
+    expect(balances).toEqual({
+      "0xTokenA": 100n,
+      "0xTokenB": 5n,
+    });
+
+    await state.markNoteUnspent(1, 2);
+    const balancesAfterReopen = await state.getZkBalances(mpk, {
+      chainId: 1,
+    });
+    expect(balancesAfterReopen).toEqual({
+      "0xTokenA": 150n,
+      "0xTokenB": 5n,
+    });
+  });
+});

package/storage/index.ts

@@ -0,0 +1,3 @@
+export { createMemoryStorage } from "./memory.js";
+export { createIndexedDbStorage, type IndexedDbOptions } from "./indexeddb.js";
+export type { Storage } from "../types.js";

package/storage/indexeddb.test.ts

@@ -0,0 +1,99 @@
+import "fake-indexeddb/auto";
+
+import { afterEach, 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 { createIndexedDbStorage } from "./indexeddb.js";
+
+const encoder = new TextEncoder();
+let dbName = "unlink-core-test";
+
+function deleteDatabase(name: string) {
+  return new Promise<void>((resolve, reject) => {
+    const request = indexedDB.deleteDatabase(name);
+    request.onsuccess = () => resolve();
+    request.onerror = () =>
+      reject(request.error ?? new Error("failed to delete indexedDB"));
+    request.onblocked = () =>
+      reject(new Error("indexedDB deletion was blocked"));
+  });
+}
+
+describe("createIndexedDbStorage", () => {
+  let storage: Storage;
+
+  beforeEach(async () => {
+    dbName = `unlink-core-test-${Math.random().toString(6)}`;
+    await deleteDatabase(dbName).catch(() => {});
+    storage = createIndexedDbStorage({ name: dbName });
+    await storage.open();
+  });
+
+  afterEach(async () => {
+    await deleteDatabase(dbName).catch(() => {});
+  });
+
+  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(3);
+    const version = await storage.getSchemaVersion();
+    expect(version).toBe(3);
+  });
+
+  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("supports prefix, limit, and reverse iteration", async () => {
+    await storage.put("notes:a", encoder.encode("1"));
+    await storage.put("notes:b", encoder.encode("2"));
+    await storage.put("notes:c", encoder.encode("3"));
+    await storage.put("meta:other", encoder.encode("x"));
+
+    const forward = await storage.iter({
+      prefix: "notes:",
+      limit: 2,
+    });
+    expect(forward.map((p) => p.key)).toEqual(["notes:a", "notes:b"]);
+
+    const reverse = await storage.iter({
+      prefix: "notes:",
+      reverse: true,
+      limit: 1,
+    });
+    expect(reverse.map((p) => p.key)).toEqual(["notes:c"]);
+  });
+
+  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();
+  });
+});