@unlink-xyz/core 0.1.3-canary.fd5dddf → 0.1.4

package/dist/state/store/store.js

@@ -1,113 +0,0 @@
-import { keys } from "../../keys.js";
-import { encodeJson } from "../../utils/json-codec.js";
-import { createCiphertextStore } from "./ciphertext-store.js";
-import { createHistoryStore } from "./history-store.js";
-import { createJobStore } from "./job-store.js";
-import { createLeafStore } from "./leaf-store.js";
-import { createNoteStore, emptyBytes } 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);
-    const history = createHistoryStore(storage);
-    /**
-     * Atomically store a commitment's leaf, ciphertext, root, and optionally note.
-     * Uses storage.batch() for all-or-nothing semantics.
-     */
-    async function syncCommitment(params) {
-        const { leaf, ciphertext, root, note } = params;
-        const ops = [
-            // Leaf
-            {
-                put: [
-                    keys.leaf(leaf.chainId, leaf.index),
-                    encodeJson(leaf),
-                ],
-            },
-            // Ciphertext (raw bytes, not JSON)
-            {
-                put: [
-                    keys.ciphertext(ciphertext.chainId, ciphertext.index),
-                    ciphertext.payload,
-                ],
-            },
-            // Root
-            {
-                put: [
-                    keys.root(root.chainId, root.root),
-                    encodeJson(root),
-                ],
-            },
-        ];
-        // Note (if decryption succeeded)
-        if (note) {
-            ops.push({
-                put: [
-                    keys.note(note.chainId, note.index),
-                    encodeJson(note),
-                ],
-            });
-            // Maintain unspent index
-            if (note.spentAt === undefined) {
-                ops.push({
-                    put: [keys.unspent(note.chainId, note.mpk, note.index), emptyBytes()],
-                });
-            }
-        }
-        await storage.batch(ops);
-    }
-    /**
-     * Clear notes, leaves, ciphertexts, and unspent indices for indices >= fromIndex.
-     * Used by partial resync to remove stale tail data while preserving the valid prefix.
-     *
-     * Key formats (see keys.ts): notes:${c}:${i}, leaves:${c}:${i},
-     * ciphertexts:${c}:${i}, idx:notes:unspent:${c}:${mpk}:${i}.
-     * The index is always the last colon-separated segment.
-     */
-    async function clearChainDataFromIndex(chainId, fromIndex) {
-        const prefixes = [
-            `notes:${chainId}:`,
-            `leaves:${chainId}:`,
-            `ciphertexts:${chainId}:`,
-        ];
-        const ops = [];
-        for (const prefix of prefixes) {
-            const entries = await storage.iter({ prefix });
-            for (const { key } of entries) {
-                // Index is always the last colon-segment (see keys.ts key builders)
-                const idx = parseInt(key.slice(key.lastIndexOf(":") + 1), 10);
-                if (!isNaN(idx) && idx >= fromIndex) {
-                    ops.push({ del: key });
-                }
-            }
-        }
-        // Clear unspent index entries (key: idx:notes:unspent:${c}:${mpk}:${index})
-        const unspentPrefix = `idx:notes:unspent:${chainId}:`;
-        const unspentEntries = await storage.iter({ prefix: unspentPrefix });
-        for (const { key } of unspentEntries) {
-            // Index is always the last colon-segment (see keys.ts key builders)
-            const idx = parseInt(key.slice(key.lastIndexOf(":") + 1), 10);
-            if (!isNaN(idx) && idx >= fromIndex) {
-                ops.push({ del: key });
-            }
-        }
-        if (ops.length > 0)
-            await storage.batch(ops);
-    }
-    return {
-        ...notes,
-        ...nullifiers,
-        ...leaves,
-        ...roots,
-        ...ciphertexts,
-        ...jobs,
-        ...history,
-        syncCommitment,
-        clearChainDataFromIndex,
-    };
-}

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,91 +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);
-            const value = data.get(k);
-            if (value) {
-                // We don't zeroize here by default since we don't know if this is sensitive data.
-                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;
-        },
-    };
-}

package/dist/transactions/deposit.js

@@ -1,220 +0,0 @@
-import { Interface } from "ethers";
-import { resolveFetch } from "../clients/http.js";
-import { createIndexerClient } from "../clients/indexer.js";
-import { createServiceConfig } from "../config.js";
-import { ETH_TOKEN } from "../constants.js";
-import { CoreError, InitializationError, ValidationError } from "../errors.js";
-import { FieldSize, Hex } from "../keys/hex.js";
-import { DEFAULT_JOB_TIMEOUT_MS, rebuildTreeFromStore, resolveMerkleTrees, } from "../state/index.js";
-import { sleep } from "../utils/async.js";
-import { computeCommitment, deriveNpk, encryptNote } from "../utils/crypto.js";
-import { DEFAULT_INITIAL_POLL_DELAY_MS, DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, MAX_POLL_INTERVAL_MS, } from "../utils/polling.js";
-export const DEPOSIT_ABI = [
-    "function deposit(address _depositor, (uint256 npk, uint256 amount, address token)[] notes, (uint256[3] data)[] ciphertexts) payable",
-];
-const depositInterface = new Interface(DEPOSIT_ABI);
-/**
- * Process notes: derive npk, compute commitment, and encrypt.
- */
-function processNotes(_account, _chainId, _poolAddress, _depositor, notes) {
-    return notes.map((note) => {
-        const npk = deriveNpk(note);
-        const commitment = computeCommitment(note, npk);
-        const commitmentHex = Hex.fromBigInt(commitment, FieldSize.SCALAR, true);
-        const encrypted = encryptNote(note);
-        return {
-            npk,
-            commitmentHex,
-            token: note.token,
-            amount: note.amount,
-            encrypted,
-        };
-    });
-}
-/**
- * Build deposit calldata from processed notes.
- */
-function buildDepositCalldata(depositor, processedNotes) {
-    return depositInterface.encodeFunctionData("deposit", [
-        depositor,
-        processedNotes.map((d) => ({
-            npk: d.npk,
-            amount: d.amount,
-            token: d.token,
-        })),
-        processedNotes.map((d) => ({ data: d.encrypted.data })),
-    ]);
-}
-/**
- * Generate a relay ID for tracking.
- */
-function generateRelayId(prefix) {
-    return (globalThis.crypto?.randomUUID?.() ?? `${prefix}-${Date.now().toString(16)}`);
-}
-// ============================================================================
-// Public API
-// ============================================================================
-/**
- * Prepare a deposit: compute commitments, build calldata, and persist pending job.
- * Accepts 1 or more notes in a single transaction.
- */
-export async function deposit(store, req) {
-    if (!req.notes?.length) {
-        throw new ValidationError("At least one note is required for deposit");
-    }
-    const processedNotes = processNotes(req.account, req.chainId, req.poolAddress, req.depositor, req.notes);
-    const calldata = buildDepositCalldata(req.depositor, processedNotes);
-    const relayId = generateRelayId("dep");
-    const value = processedNotes
-        .filter((n) => n.token.toLowerCase() === ETH_TOKEN.toLowerCase())
-        .reduce((sum, n) => sum + n.amount, 0n);
-    const job = {
-        relayId,
-        kind: "deposit",
-        chainId: req.chainId,
-        status: "pending",
-        txHash: null,
-        createdAt: Date.now(),
-        timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
-        predictedCommitments: processedNotes.map((d) => ({
-            hex: d.commitmentHex,
-            token: d.token,
-            amount: d.amount.toString(),
-        })),
-    };
-    await store.putJob(job);
-    return {
-        relayId,
-        to: req.poolAddress,
-        calldata,
-        value,
-        commitments: processedNotes.map((d) => ({
-            commitment: d.commitmentHex,
-            token: d.token,
-            amount: d.amount,
-        })),
-    };
-}
-/**
- * Poll for a single commitment and verify/persist it.
- */
-async function pollAndVerifyCommitment(ctx, commitmentHex) {
-    let delay = ctx.pollInterval;
-    let record = null;
-    while (Date.now() <= ctx.deadline) {
-        record = await ctx.indexer.tryGetCommitment({
-            chainId: ctx.chainId,
-            commitment: commitmentHex,
-        });
-        if (record)
-            break;
-        await sleep(delay);
-        delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
-    }
-    if (!record) {
-        throw new CoreError(`commitment ${commitmentHex} not found before timeout`);
-    }
-    // Note: We intentionally do NOT verify or store the leaf here. The syncChain
-    // flow handles leaf storage, merkle verification, and note decryption together.
-    // If we verified the tree here, we'd need to keep it in sync across multiple
-    // reconcile calls, and if we stored the leaf, syncChain would skip this index
-    // and notes wouldn't be decrypted.
-    //
-    // The indexer's commitment record already contains the verified index and root,
-    // which we return to the caller. The subsequent sync will verify consistency
-    // when it processes this commitment.
-    return {
-        index: record.index,
-        commitment: record.commitment,
-        root: record.root,
-        txHash: record.txHash,
-    };
-}
-/**
- * Create sync context with common setup.
- */
-async function createSyncContext(store, chainId, createdAt, opts) {
-    const fetchFn = resolveFetch(opts.fetch);
-    if (!fetchFn)
-        throw new InitializationError("fetch is required for sync");
-    const serviceConfig = createServiceConfig(opts.rpcUrl);
-    const trees = resolveMerkleTrees(opts);
-    const indexer = createIndexerClient(serviceConfig.indexerBaseUrl, {
-        fetch: fetchFn,
-    });
-    const pollInterval = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-    const pollTimeout = opts.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-    await rebuildTreeFromStore({
-        chainId,
-        trees,
-        loadLeaf: store.getLeaf.bind(store),
-    });
-    // Calculate deadline BEFORE initial delay so pollTimeout is the total wait time
-    const deadline = Date.now() + pollTimeout;
-    // Wait initial delay for fresh deposits to reduce wasted 404 polls
-    const initialDelay = opts.initialPollDelayMs ?? DEFAULT_INITIAL_POLL_DELAY_MS;
-    const jobAge = Date.now() - createdAt;
-    if (initialDelay > 0 && jobAge < initialDelay) {
-        await sleep(initialDelay - jobAge);
-    }
-    return {
-        store,
-        chainId,
-        indexer,
-        trees,
-        pollInterval,
-        deadline,
-    };
-}
-// ============================================================================
-// Sync Public API
-// ============================================================================
-/**
- * Wait for all commitments in a deposit to be indexed and update local state.
- * Works for both single and multi-note deposits.
- */
-export async function syncDeposit(store, relayId, opts) {
-    const jobRecord = await store.getJob(relayId);
-    if (!jobRecord || jobRecord.kind !== "deposit")
-        throw new CoreError(`unknown deposit relay ${relayId}`);
-    const job = jobRecord;
-    const ctx = await createSyncContext(store, job.chainId, job.createdAt, opts);
-    try {
-        const syncedCommitments = [];
-        for (const predicted of job.predictedCommitments) {
-            const synced = await pollAndVerifyCommitment(ctx, predicted.hex);
-            syncedCommitments.push(synced);
-        }
-        const finalRoot = syncedCommitments[syncedCommitments.length - 1].root;
-        // Update job status (syncChain handles root storage)
-        await store.putJob({
-            ...job,
-            status: "succeeded",
-            lastCheckedAt: Date.now(),
-            txHash: syncedCommitments[0]?.txHash ?? job.txHash ?? null,
-            predictedCommitments: job.predictedCommitments.map((p, i) => ({
-                ...p,
-                index: syncedCommitments[i]?.index,
-                root: syncedCommitments[i]?.root,
-            })),
-        });
-        return {
-            chainId: job.chainId,
-            commitments: syncedCommitments.map((s) => ({
-                index: s.index,
-                commitment: s.commitment,
-                root: s.root,
-            })),
-            finalRoot,
-        };
-    }
-    catch (error) {
-        await store.putJob({
-            ...job,
-            status: "failed",
-            lastCheckedAt: Date.now(),
-            error: error instanceof Error ? error.message : String(error),
-        });
-        throw error;
-    }
-}

package/dist/transactions/index.js

@@ -1,9 +0,0 @@
-// Primary API
-export { deposit, syncDeposit } from "./deposit.js";
-export { transact, syncTransact } from "./transact.js";
-export { planTransaction } from "./transaction-planner.js";
-export { planWithdrawals, } from "./withdrawal-planner.js";
-export { planTransfers } from "./transfer-planner.js";
-export { selectNotesForAmount } from "./note-selection.js";
-export { createJobReconciler } from "./reconcile.js";
-export { createNoteSyncService } from "./note-sync.js";