@unlink-xyz/core 0.1.0 → 0.1.3-canary.01ac52d

package/dist/state/store/note-store.js

@@ -1,142 +0,0 @@
-import { CoreError } from "../../errors.js";
-import { keys } from "../../keys.js";
-import { decodeJson, encodeJson, getJson, } from "../../utils/json-codec.js";
-import { ensureBigIntString, ensureChainId, ensureMpk, ensurePositiveInt, } from "../../utils/validators.js";
-export const emptyBytes = () => new Uint8Array(0);
-export function createNoteStore(storage) {
-    const persistNote = async (record) => {
-        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(storage, noteKey);
-        const ops = [
-            { put: [noteKey, encodeJson(record)] },
-        ];
-        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) {
-            const noteKey = keys.note(note.chainId, note.index);
-            const existing = await getJson(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, index) {
-            ensureChainId(chainId);
-            ensurePositiveInt("note index", index);
-            return getJson(storage, keys.note(chainId, index));
-        },
-        /**
-         * List notes matching optional filters (by chainId, mpk) and spent state.
-         */
-        async listNotes(options = {}) {
-            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(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, index, 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 = { ...existing, spentAt };
-            await persistNote(updated);
-            return updated;
-        },
-        /**
-         * Drop the spent marker from a cached note, returning it to the unspent index.
-         */
-        async markNoteUnspent(chainId, index) {
-            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 = { ...existing };
-            delete updated.spentAt;
-            await persistNote(updated);
-            return updated;
-        },
-        /**
-         * Aggregate unspent note balances per token for a given master public key.
-         */
-        async getZkBalances(mpk, options = {}) {
-            ensureMpk(mpk);
-            const notes = await store.listNotes({
-                chainId: options.chainId,
-                mpk,
-                includeSpent: false,
-            });
-            const totals = {};
-            for (const note of notes) {
-                const amount = BigInt(note.value);
-                totals[note.token] = (totals[note.token] ?? 0n) + amount;
-            }
-            return totals;
-        },
-    };
-    return store;
-}

package/dist/state/store/nullifier-store.js

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

package/dist/state/store/records.js

@@ -1 +0,0 @@
-export {};

package/dist/state/store/root-store.js

@@ -1,30 +0,0 @@
-import { CoreError } from "../../errors.js";
-import { keys, validateKey } from "../../keys.js";
-import { getJson, putJson } from "../../utils/json-codec.js";
-import { ensureChainId } from "../../utils/validators.js";
-export function createRootStore(storage) {
-    return {
-        /**
-         * Persist a historical root snapshot for proof generation.
-         */
-        async putRoot(root) {
-            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, value) {
-            ensureChainId(chainId);
-            if (typeof value !== "string" || value.length === 0) {
-                throw new CoreError("root value must be a non-empty string");
-            }
-            return getJson(storage, keys.root(chainId, value));
-        },
-    };
-}

package/dist/state/store/store.js

@@ -1,22 +0,0 @@
-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) {
-    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/dist/state/store.d.ts

@@ -1,26 +0,0 @@
-import type { Storage } from "../types.js";
-export declare function createStateStore(storage: Storage): {
-    putCiphertext(chainId: number, index: number, payload: Uint8Array): Promise<void>;
-    getCiphertext(chainId: number, index: number): Promise<Uint8Array<ArrayBuffer> | null>;
-    putRoot(root: import("./records.js").RootRecord): Promise<void>;
-    getRoot(chainId: number, value: string): Promise<import("./records.js").RootRecord | null>;
-    putLeaf(leaf: import("./records.js").LeafRecord): Promise<void>;
-    getLeaf(chainId: number, index: number): Promise<import("./records.js").LeafRecord | null>;
-    clearLeaves(chainId: number): Promise<void>;
-    putNullifier(nullifier: import("./records.js").NullifierRecord): Promise<void>;
-    getNullifier(chainId: number, value: string): Promise<import("./records.js").NullifierRecord | null>;
-    putNote(note: import("./records.js").NoteInsert): Promise<void>;
-    getNote(chainId: number, index: number): Promise<import("./records.js").NoteRecord | null>;
-    listNotes(options?: {
-        chainId?: number;
-        mpk?: string;
-        token?: string;
-        includeSpent?: boolean;
-    }): Promise<import("./records.js").NoteRecord[]>;
-    markNoteSpent(chainId: number, index: number, spentAt?: number): Promise<import("./records.js").NoteRecord>;
-    markNoteUnspent(chainId: number, index: number): Promise<import("./records.js").NoteRecord>;
-    getZkBalances(mpk: string, options?: {
-        chainId?: number;
-    }): Promise<Record<string, bigint>>;
-};
-//# sourceMappingURL=store.d.ts.map

package/dist/state/store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../state/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAO3C,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO;;;;;;;;;;;;;eAe6/C,CAAC;WAAqB,CAAC;aAAuB,CAAC;oBAA8B,CAAC;;;;;eAA+qE,CAAC;;EAD3yH"}

package/dist/state/store.js

@@ -1,19 +0,0 @@
-import { createCiphertextStore } from "./ciphertext-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) {
-    const notes = createNoteStore(storage);
-    const nullifiers = createNullifierStore(storage);
-    const leaves = createLeafStore(storage);
-    const roots = createRootStore(storage);
-    const ciphertexts = createCiphertextStore(storage);
-    return {
-        ...notes,
-        ...nullifiers,
-        ...leaves,
-        ...roots,
-        ...ciphertexts,
-    };
-}

package/dist/storage/index.js

@@ -1,2 +0,0 @@
-export { createMemoryStorage } from "./memory.js";
-export { createIndexedDbStorage } from "./indexeddb.js";

package/dist/storage/indexeddb.js

@@ -1,205 +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";
-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) => new Uint8Array(value);
-function assertIndexedDb() {
-    if (typeof indexedDB === "undefined") {
-        throw new CoreError("indexedDB is not available in this environment");
-    }
-    return indexedDB;
-}
-// Translate IndexedDB's event-based transaction API into a promise that resolves
-// when the transaction completes or rejects on failure/abort.
-function txDone(tx) {
-    return new Promise((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(request) {
-    return new Promise((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) {
-    if (raw instanceof Uint8Array)
-        return copy(raw);
-    if (raw instanceof ArrayBuffer)
-        return copy(new Uint8Array(raw));
-    if (ArrayBuffer.isView(raw)) {
-        const view = raw;
-        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 = {}) {
-    const name = opts.name ?? DEFAULT_DB_NAME;
-    let db = null;
-    // Lazy-open the database so we only touch IndexedDB when needed.
-    async function ensureOpen() {
-        if (db)
-            return db;
-        // Guard for environments without IndexedDB (unit tests or SSR).
-        const idb = 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((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, mode) => {
-        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) {
-            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, value) {
-            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) {
-            validateKey(key);
-            const { store, done } = await getStore(KV_STORE, "readwrite");
-            await wrapRequest(store.delete(key));
-            await done;
-        },
-        async batch(ops) {
-            // 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 = {}) {
-            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(store.getAllKeys()),
-                wrapRequest(store.getAll()),
-            ]);
-            await done;
-            const pairs = 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(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/dist/storage/memory.js

@@ -1,87 +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";
-const copy = (value) => new Uint8Array(value);
-export function createMemoryStorage() {
-    const data = new Map();
-    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) {
-            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 = {}) {
-            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) {
-            schema = n;
-        },
-    };
-}