@unlink-xyz/core 0.1.3 → 0.1.4

package/dist/state.js

@@ -1,171 +0,0 @@
-import { CoreError } from './errors.js';
-import { keys, validateKey } from './keys.js';
-import { decodeJson, encodeJson, getJson, putJson, } from './utils/json-codec.js';
-export function ensurePositiveInt(label, value) {
-    if (!Number.isInteger(value) || value < 0) {
-        throw new CoreError(`${label} must be a non-negative integer`);
-    }
-}
-export function ensureChainId(chainId) {
-    if (!Number.isInteger(chainId) || chainId <= 0) {
-        throw new CoreError('chainId must be a positive integer');
-    }
-}
-function ensureMpk(mpk) {
-    if (typeof mpk !== 'string' || mpk.length === 0) {
-        throw new CoreError('note mpk must be a non-empty string');
-    }
-}
-function ensureBigIntString(label, value) {
-    try {
-        BigInt(value);
-    }
-    catch {
-        throw new CoreError(`${label} must be a base-10 bigint string`);
-    }
-}
-const emptyBytes = () => new Uint8Array(0);
-export function createStateStore(storage) {
-    const store = {
-        async putNote(note) {
-            ensureChainId(note.chainId);
-            ensurePositiveInt('note index', note.index);
-            ensureMpk(note.mpk);
-            ensureBigIntString('note value', note.value);
-            if (note.spentAt !== undefined) {
-                ensurePositiveInt('note spentAt', note.spentAt);
-            }
-            const noteKey = keys.note(note.chainId, note.index);
-            const previous = await getJson(storage, noteKey);
-            const ops = [
-                { put: [noteKey, encodeJson(note)] },
-            ];
-            if (previous && previous.spentAt === undefined) {
-                ops.push({
-                    del: keys.unspent(previous.chainId, previous.mpk, previous.index),
-                });
-            }
-            if (note.spentAt === undefined) {
-                ops.push({
-                    put: [
-                        keys.unspent(note.chainId, note.mpk, note.index),
-                        emptyBytes(),
-                    ],
-                });
-            }
-            else {
-                ops.push({
-                    del: keys.unspent(note.chainId, note.mpk, note.index),
-                });
-            }
-            await storage.batch(ops);
-        },
-        async getNote(chainId, index) {
-            ensureChainId(chainId);
-            ensurePositiveInt('note index', index);
-            return getJson(storage, keys.note(chainId, index));
-        },
-        async listNotes(options = {}) {
-            const { chainId, mpk, 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 });
-            return entries
-                .map(({ value }) => decodeJson(value))
-                .filter((note) => (chainId === undefined || note.chainId === chainId) &&
-                (mpk === undefined || note.mpk === mpk) &&
-                (includeSpent || note.spentAt === undefined));
-        },
-        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 store.putNote(updated);
-            return updated;
-        },
-        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 store.putNote(updated);
-            return updated;
-        },
-        async getShieldedBalance(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;
-        },
-        async putNullifier(nullifier) {
-            ensureChainId(nullifier.chainId);
-            await putJson(storage, keys.nullifier(nullifier.chainId, nullifier.nullifier), nullifier);
-        },
-        async getNullifier(chainId, value) {
-            ensureChainId(chainId);
-            return getJson(storage, keys.nullifier(chainId, value));
-        },
-        async putLeaf(leaf) {
-            ensureChainId(leaf.chainId);
-            ensurePositiveInt('leaf index', leaf.index);
-            await putJson(storage, keys.leaf(leaf.chainId, leaf.index), leaf);
-        },
-        async getLeaf(chainId, index) {
-            ensureChainId(chainId);
-            ensurePositiveInt('leaf index', index);
-            return getJson(storage, keys.leaf(chainId, index));
-        },
-        async putRoot(root) {
-            ensureChainId(root.chainId);
-            ensurePositiveInt('root sequence', root.sequence);
-            await putJson(storage, keys.root(root.chainId, root.sequence), root);
-        },
-        async getRoot(chainId, sequence) {
-            ensureChainId(chainId);
-            ensurePositiveInt('root sequence', sequence);
-            return getJson(storage, keys.root(chainId, sequence));
-        },
-        async putCiphertext(chainId, index, payload) {
-            ensureChainId(chainId);
-            ensurePositiveInt('ciphertext index', index);
-            const key = keys.ciphertext(chainId, index);
-            validateKey(key);
-            await storage.put(key, new Uint8Array(payload));
-        },
-        async getCiphertext(chainId, index) {
-            ensureChainId(chainId);
-            ensurePositiveInt('ciphertext index', index);
-            const data = await storage.get(keys.ciphertext(chainId, index));
-            return data ? new Uint8Array(data) : null;
-        },
-    };
-    return store;
-}

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;
-        },
-    };
-}

package/dist/transactions/deposit.js

@@ -1,169 +0,0 @@
-import { Interface } from "ethers";
-import { v4 as uuidv4 } from "uuid";
-import { createIndexerClient } from "../clients/indexer.js";
-import { serviceConfig } from "../config.js";
-import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
-import { createMerkleTrees, DEFAULT_JOB_TIMEOUT_MS, rebuildTreeFromStore, } from "../state/index.js";
-import { isNotFoundError, sleep } from "../utils/async.js";
-import { parseHexToBigInt } from "../utils/bigint.js";
-import { computeCommitment, deriveNpk, encryptNote } from "../utils/crypto.js";
-import { DEFAULT_POLL_INTERVAL_MS, DEFAULT_POLL_TIMEOUT_MS, MAX_POLL_INTERVAL_MS, } from "../utils/polling.js";
-import { ensureAddress, ensureChainId } from "../utils/validators.js";
-export const DEPOSIT_ABI = [
-    "function deposit(address _depositor, (uint256 npk, uint256 amount, address token)[] notes, (uint256[3] data)[] ciphertexts)",
-];
-const depositInterface = new Interface(DEPOSIT_ABI);
-function validateDepositRequest(request) {
-    ensureChainId(request.chainId);
-    ensureAddress("pool address", request.poolAddress);
-    ensureAddress("depositor", request.depositor);
-    ensureAddress("token", request.note.token);
-    if (request.note.mpk < 0n) {
-        throw new Error("mpk must be non-negative");
-    }
-    if (request.note.random < 0n) {
-        throw new Error("random must be non-negative");
-    }
-    if (request.note.amount < 0n) {
-        throw new Error("amount must be non-negative");
-    }
-    const tokenScalar = BigInt(request.note.token);
-    if (tokenScalar < 0n) {
-        throw new Error("token must map to non-negative scalar");
-    }
-}
-export function createDepositClient(stateStore, options) {
-    if (!stateStore) {
-        throw new Error("stateStore dependency is required");
-    }
-    const merkleTrees = options.merkleTrees ?? createMerkleTrees();
-    const indexerClient = createIndexerClient(serviceConfig.indexerBaseUrl, {
-        fetch: options.fetch,
-    });
-    function buildCalldata(request, npk) {
-        return depositInterface.encodeFunctionData("deposit", [
-            request.depositor,
-            [
-                // TODO(julienbrs) handle multiple notes
-                {
-                    npk: npk,
-                    amount: request.note.amount,
-                    token: request.note.token,
-                },
-            ],
-            [
-                {
-                    data: encryptNote(request.note).data,
-                },
-            ],
-        ]);
-    }
-    async function persistDepositSuccess(job, record, indexedRoot) {
-        await Promise.all([
-            stateStore.putLeaf({
-                chainId: job.chainId,
-                index: record.index,
-                commitment: record.commitment,
-            }),
-            stateStore.putRoot({
-                chainId: job.chainId,
-                root: indexedRoot,
-            }),
-            stateStore.putPendingJob({
-                ...job,
-                status: "succeeded",
-                lastCheckedAt: Date.now(),
-                txHash: record.txHash ?? job.txHash ?? null,
-                predictedCommitment: {
-                    ...job.predictedCommitment,
-                    index: record.index,
-                    root: indexedRoot,
-                },
-            }),
-        ]);
-    }
-    return {
-        async request(request) {
-            validateDepositRequest(request);
-            const npk = deriveNpk(request);
-            const calldata = buildCalldata(request, npk);
-            const commitment = computeCommitment(request, npk);
-            const commitmentHex = ByteUtils.nToHex(commitment, ByteLength.UINT_256, true);
-            const relayId = uuidv4();
-            const job = {
-                relayId,
-                kind: "deposit",
-                chainId: request.chainId,
-                status: "pending",
-                broadcasterRelayId: null,
-                txHash: null,
-                createdAt: Date.now(),
-                timeoutMs: DEFAULT_JOB_TIMEOUT_MS,
-                predictedCommitment: {
-                    hex: commitmentHex,
-                },
-            };
-            await stateStore.putPendingJob(job);
-            return { relayId, calldata, commitment: commitmentHex };
-        },
-        async syncPendingDeposit(relayId) {
-            const job = await stateStore.getPendingJob(relayId);
-            if (!job || job.kind !== "deposit") {
-                throw new Error(`unknown deposit relay ${relayId}`);
-            }
-            await rebuildTreeFromStore({
-                chainId: job.chainId,
-                trees: merkleTrees,
-                loadLeaf: stateStore.getLeaf.bind(stateStore),
-            });
-            const commitmentHex = job.predictedCommitment.hex;
-            const record = await waitForCommitment(job.chainId, commitmentHex);
-            const { index, root: indexedRoot } = record;
-            const commitmentValue = parseHexToBigInt(commitmentHex);
-            const { index: localIndex, root: localRoot } = merkleTrees.addLeaf(job.chainId, commitmentValue);
-            // TODO: if local state drift detected, need to re-sync since last correct state
-            if (localIndex !== index) {
-                throw new Error("local merkle tree desynchronized (index mismatch), local index: " +
-                    localIndex +
-                    ", indexed index: " +
-                    index);
-            }
-            if (localRoot.toLowerCase() !== indexedRoot.toLowerCase()) {
-                throw new Error("local merkle tree desynchronized (root mismatch), local root: " +
-                    localRoot +
-                    ", indexed root: " +
-                    indexedRoot);
-            }
-            await persistDepositSuccess(job, record, indexedRoot);
-            return {
-                chainId: job.chainId,
-                index,
-                commitment: record.commitment,
-                root: indexedRoot,
-            };
-        },
-    };
-    async function waitForCommitment(chainId, commitmentHex) {
-        const timeout = options.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
-        const startedAt = Date.now();
-        let delay = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        while (Date.now() - startedAt <= timeout) {
-            try {
-                const record = await indexerClient.getCommitment({
-                    chainId,
-                    commitment: commitmentHex,
-                });
-                if (record)
-                    return record;
-            }
-            catch (err) {
-                if (!isNotFoundError(err)) {
-                    throw err;
-                }
-            }
-            await sleep(delay);
-            delay = Math.min(delay * 2, MAX_POLL_INTERVAL_MS);
-        }
-        throw new Error("commitment not found in indexer before timeout");
-    }
-}

package/dist/transactions/index.js

@@ -1,4 +0,0 @@
-export { createDepositClient } from "./deposit.js";
-export { createTransactService } from "./transact.js";
-export { createJobReconciler } from "./reconcile.js";
-export { createNoteSyncService } from "./note-sync.js";