@unlink-xyz/core 0.1.0

package/dist/transactions/deposit.js

@@ -0,0 +1,173 @@
+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");
+    }
+    if (!options?.fetch) {
+        throw new Error("fetch dependency is required");
+    }
+    const merkleTrees = options.merkleTrees ?? createMerkleTrees();
+    const indexerClient = options.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 commitmentValue = computeCommitment(request, npk);
+            const commitmentHex = ByteUtils.nToHex(commitmentValue, ByteLength.UINT_256, true);
+            const calldata = buildCalldata(request, npk);
+            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.d.ts

@@ -0,0 +1,7 @@
+export { createDepositClient } from "./deposit.js";
+export { createTransactService } from "./transact.js";
+export { createJobReconciler } from "./reconcile.js";
+export { createNoteSyncService } from "./note-sync.js";
+export type { NoteSyncStateStore } from "./note-sync.js";
+export type { DepositRelayResult, DepositNoteInput, DepositRequest, DepositSyncResult, DepositStateStore, Proof, OutputNoteInput, SpendNoteReference, TransactRelayResult, TransactRequest, TransactSyncResult, TransactStateStore, WithdrawalNoteInput, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/transactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../transactions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,YAAY,CAAC"}

package/dist/transactions/index.js

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

package/dist/transactions/note-sync.d.ts

@@ -0,0 +1,46 @@
+import type { ZkAccount } from "../account/zkAccount.js";
+import type { FetchLike } from "../clients/http.js";
+import { createIndexerClient } from "../clients/indexer.js";
+import { type LeafRecord, type LocalMerkleTrees, type NoteRecord, type RootRecord } from "../state/index.js";
+export type NoteSyncStateStore = {
+    putLeaf(record: LeafRecord): Promise<void>;
+    getLeaf(chainId: number, index: number): Promise<LeafRecord | null>;
+    clearLeaves(chainId: number): Promise<void>;
+    putRoot(record: RootRecord): Promise<void>;
+    putNote(record: NoteRecord): Promise<void>;
+    getNote(chainId: number, index: number): Promise<NoteRecord | null>;
+    markNoteSpent(chainId: number, index: number, spentAt?: number): Promise<NoteRecord>;
+    putCiphertext(chainId: number, index: number, payload: Uint8Array): Promise<void>;
+    countNullifiers(chainId: number): Promise<number>;
+    putNullifier(record: {
+        chainId: number;
+        nullifier: string;
+        noteIndex?: number;
+    }): Promise<void>;
+};
+export type NoteSyncOptions = {
+    merkleTrees?: LocalMerkleTrees;
+    indexerClient?: ReturnType<typeof createIndexerClient>;
+    fetch?: FetchLike;
+    limit?: number;
+};
+type ChainSyncStatus = {
+    inFlight: boolean;
+    lastSuccess: number | null;
+    lastError?: string;
+};
+export declare function createNoteSyncService(stateStore: NoteSyncStateStore, options?: NoteSyncOptions): {
+    sync: (chainId: number, account: ZkAccount, opts?: {
+        start?: number;
+        forceFullScan?: boolean;
+    }) => Promise<NoteRecord[]>;
+    syncChain: (chainId: number, account: ZkAccount, opts?: {
+        forceFullResync?: boolean;
+    }) => Promise<void>;
+    syncChains: (chainIds: number[], account: ZkAccount, opts?: {
+        forceFullResync?: boolean;
+    }) => Promise<void>;
+    getStatus: () => Map<number, ChainSyncStatus>;
+};
+export {};
+//# sourceMappingURL=note-sync.d.ts.map

package/dist/transactions/note-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-sync.d.ts","sourceRoot":"","sources":["../../transactions/note-sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAK5D,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAQ3B,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACpE,aAAa,CACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,aAAa,CACX,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,YAAY,CAAC,MAAM,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IACvD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAqBF,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,kBAAkB,EAC9B,OAAO,GAAE,eAAoB;oBAgUlB,MAAM,WACN,SAAS,SACX;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,KACjD,OAAO,CAAC,UAAU,EAAE,CAAC;yBAnEb,MAAM,WACN,SAAS,SACZ;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,KAClC,OAAO,CAAC,IAAI,CAAC;2BA+CJ,MAAM,EAAE,WACT,SAAS,SACX;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC;;EAqEjB"}

package/dist/transactions/note-sync.js

@@ -0,0 +1,320 @@
+import { poseidon } from "@railgun-community/circomlibjs";
+import { createIndexerClient } from "../clients/indexer.js";
+import { serviceConfig } from "../config.js";
+import { CoreError } from "../errors.js";
+import { ByteLength, ByteUtils } from "../key-derivation/bytes.js";
+import { createMerkleTrees, rebuildTreeFromStore, } from "../state/index.js";
+import { formatUint256, parseHexToBigInt } from "../utils/bigint.js";
+import { decryptNote } from "../utils/crypto.js";
+import { ensureChainId } from "../utils/validators.js";
+const DEFAULT_BATCH_SIZE = 256;
+function buildCiphertext(bytes) {
+    return {
+        data: [
+            parseHexToBigInt(bytes[0]),
+            parseHexToBigInt(bytes[1]),
+            parseHexToBigInt(bytes[2]),
+        ],
+    };
+}
+function encodeCiphertext(ciphertext) {
+    const payload = new Uint8Array(ByteLength.UINT_256 * ciphertext.data.length);
+    ciphertext.data.forEach((value, index) => {
+        const start = index * ByteLength.UINT_256;
+        payload.set(ByteUtils.hexStringToBytes(formatUint256(value)), start);
+    });
+    return payload;
+}
+export function createNoteSyncService(stateStore, options = {}) {
+    const trees = options.merkleTrees ?? createMerkleTrees();
+    const limit = options.limit ?? DEFAULT_BATCH_SIZE;
+    const status = new Map();
+    // Initialize indexer client
+    let indexerClient = options.indexerClient;
+    if (!indexerClient) {
+        const fetchImpl = options.fetch ?? (typeof fetch === "function" ? fetch : undefined);
+        if (!fetchImpl) {
+            throw new Error("fetch dependency is required to sync indexer commitments");
+        }
+        indexerClient = createIndexerClient(serviceConfig.indexerBaseUrl, {
+            fetch: fetchImpl,
+        });
+    }
+    // Count-based optimization: avoid per-nullifier lookups when counts are unchanged
+    async function shouldQueryNullifiers(chainId) {
+        const [onChainCount, localCount] = await Promise.all([
+            indexerClient.getNullifierCount(chainId),
+            stateStore.countNullifiers(chainId),
+        ]);
+        return onChainCount !== localCount;
+    }
+    function createNoteRecord(params) {
+        const { chainId, index, commitment, token, amount, npk, mpk, random, nullifier, spentAt, } = params;
+        const base = {
+            chainId,
+            index,
+            token,
+            value: amount.toString(),
+            commitment,
+            npk: formatUint256(npk),
+            mpk: formatUint256(mpk),
+            random: formatUint256(random),
+            nullifier,
+        };
+        return spentAt === undefined ? base : { ...base, spentAt };
+    }
+    async function recordCommitment(chainId, record, allowRelaxedOrder = false) {
+        const value = parseHexToBigInt(record.commitment);
+        const currentLeafCount = trees.getLeafCount(chainId);
+        if (record.index >= currentLeafCount) {
+            const { index } = trees.addLeaf(chainId, value);
+            if (index !== record.index && !allowRelaxedOrder) {
+                throw new CoreError("indexed commitments out of order");
+            }
+            await stateStore.putLeaf({
+                chainId,
+                index: record.index,
+                commitment: record.commitment,
+            });
+        }
+        await stateStore.putRoot({ chainId, root: record.root });
+    }
+    async function tryStoreNote(chainId, record, account, shouldCheckNullifiers) {
+        const ciphertext = buildCiphertext(record.ciphertext);
+        let note;
+        try {
+            note = decryptNote(ciphertext, account.masterPublicKey);
+        }
+        catch (err) {
+            if (err instanceof CoreError) {
+                return null;
+            }
+            throw err;
+        }
+        const random = note.random;
+        const amount = note.amount;
+        const token = note.token;
+        const npk = poseidon([account.masterPublicKey, random]);
+        const commitment = poseidon([npk, BigInt(token), amount]);
+        if (commitment !== parseHexToBigInt(record.commitment)) {
+            return null;
+        }
+        const nullifier = poseidon([account.nullifyingKey, BigInt(record.index)]);
+        const nullifierHex = formatUint256(nullifier);
+        const ciphertextBytes = encodeCiphertext(ciphertext);
+        await stateStore.putCiphertext(chainId, record.index, ciphertextBytes);
+        const baseNoteParams = {
+            chainId,
+            index: record.index,
+            commitment: record.commitment,
+            token,
+            amount,
+            npk,
+            mpk: account.masterPublicKey,
+            random,
+            nullifier: nullifierHex,
+        };
+        // Check if this note already exists in local storage
+        const existingNote = await stateStore.getNote(chainId, record.index);
+        // If note is already marked as spent locally, don't query indexer
+        // to ask for nullifier because we already know it's spent
+        if (existingNote?.spentAt !== undefined) {
+            // Ensure nullifier is stored for count optimization (idempotent)
+            await stateStore.putNullifier({
+                chainId,
+                nullifier: nullifierHex,
+                noteIndex: record.index,
+            });
+            return existingNote;
+        }
+        // Skip indexer nullifier query if nullifier counts match
+        if (!shouldCheckNullifiers) {
+            if (existingNote) {
+                return existingNote;
+            }
+            const stored = createNoteRecord(baseNoteParams);
+            await stateStore.putNote(stored);
+            return stored;
+        }
+        // Counts mismatched: query individual nullifier to check if this note was spent
+        const onChainNullifier = await indexerClient.getNullifier({
+            chainId,
+            nullifier: nullifierHex,
+        });
+        if (onChainNullifier) {
+            const spentAtMs = onChainNullifier.spentAt * 1000;
+            // Store nullifier
+            await stateStore.putNullifier({
+                chainId,
+                nullifier: nullifierHex,
+                noteIndex: record.index,
+            });
+            if (existingNote) {
+                // Update existing unspent note to mark as spent
+                await stateStore.markNoteSpent(chainId, record.index, spentAtMs);
+                return existingNote;
+            }
+            const stored = createNoteRecord({
+                ...baseNoteParams,
+                spentAt: spentAtMs,
+            });
+            await stateStore.putNote(stored);
+            return stored;
+        }
+        // Skip re-storing unspent notes that already exist
+        if (existingNote) {
+            return existingNote;
+        }
+        const stored = createNoteRecord(baseNoteParams);
+        await stateStore.putNote(stored);
+        return stored;
+    }
+    // Pulls commitments from the indexer starting at `start`, updating local tree and notes.
+    async function ingestFrom(chainId, start, account) {
+        const shouldCheckNullifiers = await shouldQueryNullifiers(chainId);
+        let cursor = start;
+        for (;;) {
+            const batch = await indexerClient.fetchCommitmentBatch({
+                chainId,
+                start: cursor,
+                limit,
+            });
+            if (batch.commitments.length === 0) {
+                break;
+            }
+            for (const record of batch.commitments) {
+                const expectedIndex = trees.getLeafCount(chainId);
+                if (record.index !== expectedIndex) {
+                    throw new Error("indexed commitments out of order");
+                }
+                const value = ByteUtils.hexToBigInt(record.commitment);
+                const { index } = trees.addLeaf(chainId, value);
+                if (index !== record.index) {
+                    throw new Error("local merkle tree desynchronized");
+                }
+                await stateStore.putLeaf({
+                    chainId,
+                    index: record.index,
+                    commitment: record.commitment,
+                });
+                await stateStore.putRoot({ chainId, root: record.root });
+                await tryStoreNote(chainId, record, account, shouldCheckNullifiers);
+                cursor = record.index + 1;
+            }
+            if (batch.commitments.length < limit) {
+                break;
+            }
+        }
+    }
+    // Clears local state for a chain and rehydrates fully from the indexer.
+    async function fullResync(chainId, account) {
+        trees.reset(chainId);
+        await stateStore.clearLeaves(chainId);
+        await ingestFrom(chainId, 0, account);
+    }
+    /**
+     * Syncs a single chain into local state, optionally forcing a full rebuild.
+     * Skips overlapping runs via `inFlight` and falls back to full resync on
+     * ordering/root inconsistencies.
+     */
+    async function syncChain(chainId, account, opts = {}) {
+        ensureChainId(chainId);
+        const current = status.get(chainId) ?? {
+            inFlight: false,
+            lastSuccess: null,
+        };
+        if (current.inFlight) {
+            return;
+        }
+        status.set(chainId, { ...current, inFlight: true, lastError: undefined });
+        try {
+            const start = opts.forceFullResync
+                ? 0
+                : await rebuildTreeFromStore({
+                    chainId,
+                    trees,
+                    loadLeaf: stateStore.getLeaf.bind(stateStore),
+                });
+            if (opts.forceFullResync) {
+                await fullResync(chainId, account);
+            }
+            else {
+                try {
+                    await ingestFrom(chainId, start, account);
+                }
+                catch (err) {
+                    // Fallback to full resync on ordering/root mismatch.
+                    await fullResync(chainId, account);
+                }
+            }
+            status.set(chainId, {
+                inFlight: false,
+                lastSuccess: Date.now(),
+            });
+        }
+        catch (err) {
+            status.set(chainId, {
+                inFlight: false,
+                lastSuccess: current.lastSuccess ?? null,
+                lastError: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+    }
+    /**
+     * Syncs multiple chains sequentially.
+     */
+    async function syncChains(chainIds, account, opts) {
+        for (const chainId of chainIds) {
+            await syncChain(chainId, account, opts);
+        }
+    }
+    /**
+     * Legacy sync method that returns synced notes.
+     * Kept for backward compatibility.
+     */
+    async function sync(chainId, account, opts) {
+        ensureChainId(chainId);
+        await rebuildTreeFromStore({
+            chainId,
+            trees,
+            loadLeaf: stateStore.getLeaf.bind(stateStore),
+        });
+        const synced = [];
+        let start = opts?.start ?? 0;
+        const shouldCheckNullifiers = await shouldQueryNullifiers(chainId);
+        let keepFetching = true;
+        while (keepFetching) {
+            const batch = await indexerClient.fetchCommitmentBatch({
+                chainId,
+                start,
+                limit,
+            });
+            if (batch.commitments.length === 0) {
+                keepFetching = false;
+                continue;
+            }
+            for (const record of batch.commitments) {
+                await recordCommitment(chainId, record, !!opts?.forceFullScan);
+                const storedNote = await tryStoreNote(chainId, record, account, shouldCheckNullifiers);
+                if (storedNote) {
+                    synced.push(storedNote);
+                }
+                start = record.index + 1;
+            }
+            if (batch.commitments.length < limit) {
+                keepFetching = false;
+            }
+        }
+        return synced;
+    }
+    function getStatus() {
+        return status;
+    }
+    return {
+        sync,
+        syncChain,
+        syncChains,
+        getStatus,
+    };
+}

package/dist/transactions/reconcile.d.ts

@@ -0,0 +1,22 @@
+import type { JobStatus, PendingJobKind } from "../state/index.js";
+import type { BaseStateStore, DepositSyncResult, TransactSyncResult } from "./types.js";
+type DepositClient = {
+    syncPendingDeposit(relayId: string): Promise<DepositSyncResult>;
+};
+type TransactService = {
+    syncPendingTransact(relayId: string): Promise<TransactSyncResult>;
+};
+type ReconcilerDeps = {
+    stateStore: BaseStateStore;
+    depositClient: DepositClient;
+    transactService: TransactService;
+};
+export declare function createJobReconciler(deps: ReconcilerDeps): {
+    reconcileRelay: (relayId: string) => Promise<DepositSyncResult | TransactSyncResult>;
+    reconcileAll: (filter?: {
+        kind?: PendingJobKind;
+        statuses?: JobStatus[];
+    }) => Promise<unknown[]>;
+};
+export {};
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/transactions/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../transactions/reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EAEf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,KAAK,aAAa,GAAG;IACnB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACjE,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnE,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,UAAU,EAAE,cAAc,CAAC;IAC3B,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;CAClC,CAAC;AAIF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc;8BAUf,MAAM;4BASnC;QACN,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;KACxB;EAuBJ"}

package/dist/transactions/reconcile.js

@@ -0,0 +1,39 @@
+const ACTIVE_STATUSES = ["pending", "submitted", "broadcasting"];
+export function createJobReconciler(deps) {
+    const { stateStore, depositClient, transactService } = deps;
+    async function reconcileJob(job) {
+        if (job.kind === "deposit") {
+            return depositClient.syncPendingDeposit(job.relayId);
+        }
+        return transactService.syncPendingTransact(job.relayId);
+    }
+    async function reconcileRelay(relayId) {
+        const job = await stateStore.getPendingJob(relayId);
+        if (!job) {
+            throw new Error(`unknown relay ${relayId}`);
+        }
+        return reconcileJob(job);
+    }
+    async function reconcileAll(filter = {}) {
+        const jobs = await stateStore.listPendingJobs({
+            kind: filter.kind,
+            statuses: filter.statuses ?? ACTIVE_STATUSES,
+        });
+        const results = [];
+        for (const job of jobs) {
+            try {
+                const res = await reconcileJob(job);
+                results.push(res);
+            }
+            catch (err) {
+                // Allow caller to decide how to handle errors; we keep going.
+                results.push(err);
+            }
+        }
+        return results;
+    }
+    return {
+        reconcileRelay,
+        reconcileAll,
+    };
+}

package/dist/transactions/transact.d.ts

@@ -0,0 +1,34 @@
+import { IMTMerkleProof } from "@zk-kit/imt";
+import { FetchLike } from "../clients/http.js";
+import { LocalMerkleTrees } from "../state/index.js";
+import { TransactRelayResult, TransactRequest, TransactStateStore, TransactSyncResult } from "./types.js";
+export declare const TRANSACT_ABI = "function transact(((uint256[2] pA, uint256[2][2] pB, uint256[2] pC) proof, uint256 merkleRoot, uint256[] nullifierHashes, uint256[] newCommitments, (uint64 chainID, address poolAddress) context, (uint256 npk, uint256 amount, address token) withdrawal, (uint256[3] data)[] ciphertexts)[] _transactions)";
+type TransactServiceOptions = {
+    merkleTrees?: LocalMerkleTrees;
+    fetch?: FetchLike;
+    pollIntervalMs?: number;
+    pollTimeoutMs?: number;
+};
+/**
+ * Computes the bound parameters hash from chain ID, pool address, and withdrawal parameters.
+ * This hash binds the transaction to specific chain and withdrawal context.
+ */
+export declare function computeBoundParamsHash(chainId: number, poolAddress: string): bigint;
+export type SerializedWitness = {
+    root: string;
+    leaf: string;
+    pathElements: string[][];
+    pathIndices: number[];
+    leafIndex: number;
+};
+export declare function serializeWitness(proof: IMTMerkleProof, index: number): SerializedWitness;
+export declare function deserializeWitness(serialized: SerializedWitness): IMTMerkleProof;
+/**
+ * Simulates the transact pipeline: builds Merkle witnesses, derives nullifiers, and updates local state.
+ */
+export declare function createTransactService(stateStore: TransactStateStore, options?: TransactServiceOptions): {
+    transact(request: TransactRequest): Promise<TransactRelayResult>;
+    syncPendingTransact(relayId: string): Promise<TransactSyncResult>;
+};
+export {};
+//# sourceMappingURL=transact.d.ts.map

package/dist/transactions/transact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transact.d.ts","sourceRoot":"","sources":["../../transactions/transact.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAK/C,OAAO,EAGL,gBAAgB,EAGjB,MAAM,mBAAmB,CAAC;AAqB3B,OAAO,EAGL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,YAAY,kTACwR,CAAC;AA8ClT,KAAK,sBAAsB,GAAG;IAC5B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAoCF;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,GACZ,iBAAiB,CAUnB;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,iBAAiB,GAC5B,cAAc,CAUhB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,kBAAkB,EAC9B,OAAO,GAAE,sBAA2B;sBA0VV,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;iCA+LnC,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;EAoF1E"}