@unlink-xyz/core 0.1.3 → 0.1.4

package/state.test.ts

@@ -1,235 +0,0 @@
-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

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

package/storage/indexeddb.test.ts

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

package/storage/indexeddb.ts

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

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