@unlink-xyz/core 0.1.2 → 0.1.3-canary.0877bfe

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

@@ -1,46 +1,18 @@
-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;
-};
+import type { Account } from "../account/account.js";
+import type { NoteSyncOptions, NoteSyncStateStore } from "./types/index.js";
+export type { NoteSyncOptions, NoteSyncStateStore };
 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?: {
+    syncChain: (chainId: number, account: Account, opts?: {
         forceFullResync?: boolean;
     }) => Promise<void>;
-    syncChains: (chainIds: number[], account: ZkAccount, opts?: {
+    syncChains: (chainIds: number[], account: Account, opts?: {
         forceFullResync?: boolean;
     }) => Promise<void>;
     getStatus: () => Map<number, ChainSyncStatus>;
 };
-export {};
 //# sourceMappingURL=note-sync.d.ts.map

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

@@ -1 +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;oBAsTlB,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"}
+{"version":3,"file":"note-sync.d.ts","sourceRoot":"","sources":["../../transactions/note-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAkBrD,OAAO,KAAK,EAEV,eAAe,EACf,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAI1B,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC;AAEpD,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;yBA8elB,MAAM,WACN,OAAO,SACV;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,KAClC,OAAO,CAAC,IAAI,CAAC;2BA6FJ,MAAM,EAAE,WACT,OAAO,SACT;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,KACnC,OAAO,CAAC,IAAI,CAAC;;EAejB"}

package/dist/transactions/note-sync.js

@@ -1,8 +1,8 @@
-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 { createServiceConfig } from "../config.js";
+import { poseidon } from "../crypto-adapters/index.js";
+import { CoreError, InitializationError } from "../errors.js";
+import { FieldSize, Hex } from "../keys/hex.js";
 import { createMerkleTrees, rebuildTreeFromStore, } from "../state/index.js";
 import { formatUint256, parseHexToBigInt } from "../utils/bigint.js";
 import { decryptNote } from "../utils/crypto.js";
@@ -18,10 +18,10 @@ function buildCiphertext(bytes) {
     };
 }
 function encodeCiphertext(ciphertext) {
-    const payload = new Uint8Array(ByteLength.UINT_256 * ciphertext.data.length);
+    const payload = new Uint8Array(FieldSize.SCALAR * ciphertext.data.length);
     ciphertext.data.forEach((value, index) => {
-        const start = index * ByteLength.UINT_256;
-        payload.set(ByteUtils.hexStringToBytes(formatUint256(value)), start);
+        const start = index * FieldSize.SCALAR;
+        payload.set(Hex.toBytes(formatUint256(value)), start);
     });
     return payload;
 }
@@ -34,22 +34,18 @@ export function createNoteSyncService(stateStore, options = {}) {
     if (!indexerClient) {
         const fetchImpl = options.fetch ?? (typeof fetch === "function" ? fetch : undefined);
         if (!fetchImpl) {
-            throw new Error("fetch dependency is required to sync indexer commitments");
+            throw new InitializationError("fetch dependency is required to sync indexer commitments");
         }
+        if (!options.rpcUrl) {
+            throw new InitializationError("rpcUrl is required to sync indexer commitments");
+        }
+        const serviceConfig = createServiceConfig(options.rpcUrl);
         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 { chainId, index, commitment, token, amount, npk, mpk, random, nullifier, createdTxHash, createdEventType, createdAt, spentAt, spentTxHash, } = params;
         const base = {
             chainId,
             index,
@@ -60,26 +56,15 @@ export function createNoteSyncService(stateStore, options = {}) {
             mpk: formatUint256(mpk),
             random: formatUint256(random),
             nullifier,
+            createdTxHash,
+            createdEventType,
+            createdAt,
+            spentTxHash,
         };
         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) {
+    // Try to decrypt a note. Returns the note record if successful, null otherwise.
+    function tryDecryptNoteRecord(chainId, record, account) {
         const ciphertext = buildCiphertext(record.ciphertext);
         let note;
         try {
@@ -101,9 +86,7 @@ export function createNoteSyncService(stateStore, options = {}) {
         }
         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 = {
+        return createNoteRecord({
             chainId,
             index: record.index,
             commitment: record.commitment,
@@ -113,65 +96,14 @@ export function createNoteSyncService(stateStore, options = {}) {
             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,
+            createdTxHash: record.txHash,
+            createdEventType: record.eventType,
+            createdAt: record.insertedAt != null ? record.insertedAt * 1000 : undefined,
         });
-        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.
+    // Pulls commitments from the indexer, updating local tree and notes atomically.
+    // Uses batch nullifier check to avoid individual 404-generating queries.
     async function ingestFrom(chainId, start, account) {
-        const shouldCheckNullifiers = await shouldQueryNullifiers(chainId);
         let cursor = start;
         for (;;) {
             const batch = await indexerClient.fetchCommitmentBatch({
@@ -182,40 +114,276 @@ export function createNoteSyncService(stateStore, options = {}) {
             if (batch.commitments.length === 0) {
                 break;
             }
+            // Phase 1: Ingest commitments into tree + store
+            const decryptedNotes = [];
             for (const record of batch.commitments) {
                 const expectedIndex = trees.getLeafCount(chainId);
                 if (record.index !== expectedIndex) {
-                    throw new Error("indexed commitments out of order");
+                    throw new CoreError(`indexed commitments out of order: expected index ${expectedIndex}, got ${record.index} (cursor=${cursor})`);
                 }
-                const value = ByteUtils.hexToBigInt(record.commitment);
+                const value = Hex.toBigInt(record.commitment);
                 const { index } = trees.addLeaf(chainId, value);
                 if (index !== record.index) {
-                    throw new Error("local merkle tree desynchronized");
+                    throw new CoreError("local merkle tree desynchronized");
                 }
-                await stateStore.putLeaf({
-                    chainId,
-                    index: record.index,
-                    commitment: record.commitment,
+                const noteRecord = tryDecryptNoteRecord(chainId, record, account);
+                const ciphertext = buildCiphertext(record.ciphertext);
+                const ciphertextBytes = encodeCiphertext(ciphertext);
+                await stateStore.syncCommitment({
+                    leaf: {
+                        chainId,
+                        index: record.index,
+                        commitment: record.commitment,
+                        txHash: record.txHash,
+                        eventType: record.eventType,
+                        insertedAt: record.insertedAt,
+                    },
+                    ciphertext: {
+                        chainId,
+                        index: record.index,
+                        payload: ciphertextBytes,
+                    },
+                    root: { chainId, root: record.root },
+                    note: noteRecord ?? undefined,
                 });
-                await stateStore.putRoot({ chainId, root: record.root });
-                await tryStoreNote(chainId, record, account, shouldCheckNullifiers);
+                if (noteRecord) {
+                    decryptedNotes.push(noteRecord);
+                }
                 cursor = record.index + 1;
             }
-            if (batch.commitments.length < limit) {
-                break;
+            // Phase 2: Batch nullifier check for decrypted notes
+            if (decryptedNotes.length > 0) {
+                const notesToCheck = [];
+                for (const note of decryptedNotes) {
+                    const existing = await stateStore.getNote(chainId, note.index);
+                    if (existing?.spentAt !== undefined) {
+                        await stateStore.putNullifier({
+                            chainId,
+                            nullifier: note.nullifier,
+                            noteIndex: note.index,
+                        });
+                    }
+                    else {
+                        notesToCheck.push(note);
+                    }
+                }
+                if (notesToCheck.length > 0) {
+                    const spentNullifiers = await indexerClient.checkNullifiers({
+                        chainId,
+                        nullifiers: notesToCheck.map((n) => n.nullifier),
+                    });
+                    const spentMap = new Map(spentNullifiers.map((n) => [n.nullifier, n]));
+                    for (const note of notesToCheck) {
+                        const spent = spentMap.get(note.nullifier);
+                        if (spent) {
+                            const spentAtMs = spent.spentAt * 1000;
+                            await stateStore.putNullifier({
+                                chainId,
+                                nullifier: note.nullifier,
+                                noteIndex: note.index,
+                            });
+                            await stateStore.markNoteSpent(chainId, note.index, spentAtMs, spent.txHash);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    async function diagnoseChainState(chainId, localCount) {
+        // Tier 1: compare first commitment
+        const firstBatch = await indexerClient.fetchCommitmentBatch({
+            chainId,
+            start: 0,
+            limit: 1,
+        });
+        const localFirst = await stateStore.getLeaf(chainId, 0);
+        if (firstBatch.commitments.length === 0 || !localFirst) {
+            return { kind: "full-divergence" };
+        }
+        if (firstBatch.commitments[0].commitment !== localFirst.commitment) {
+            return { kind: "full-divergence" };
+        }
+        // Single-leaf shortcut: first matches and there's only one local leaf.
+        if (localCount === 1) {
+            return { kind: "consistent" };
+        }
+        // Compare last local commitment
+        const lastBatch = await indexerClient.fetchCommitmentBatch({
+            chainId,
+            start: localCount - 1,
+            limit: 1,
+        });
+        const localLast = await stateStore.getLeaf(chainId, localCount - 1);
+        if (lastBatch.commitments.length > 0 &&
+            localLast &&
+            lastBatch.commitments[0].commitment === localLast.commitment) {
+            return { kind: "consistent" };
+        }
+        // Tier 2: binary search for divergence point
+        const divergePoint = await findDivergencePoint(chainId, 1, localCount - 1);
+        return { kind: "partial-divergence", validPrefix: divergePoint };
+    }
+    async function findDivergencePoint(chainId, low, high) {
+        while (low < high) {
+            const mid = Math.floor((low + high) / 2);
+            const batch = await indexerClient.fetchCommitmentBatch({
+                chainId,
+                start: mid,
+                limit: 1,
+            });
+            const localLeaf = await stateStore.getLeaf(chainId, mid);
+            if (batch.commitments.length > 0 &&
+                localLeaf &&
+                batch.commitments[0].commitment === localLeaf.commitment) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
             }
         }
+        return low;
+    }
+    // Clears stale tail data and re-ingests from the divergence point.
+    async function partialResync(chainId, fromIndex, account) {
+        await Promise.all([
+            stateStore.clearChainDataFromIndex(chainId, fromIndex),
+            stateStore.clearNullifiersFromIndex(chainId, fromIndex),
+        ]);
+        trees.reset(chainId);
+        await rebuildTreeFromStore({
+            chainId,
+            trees,
+            loadLeaf: stateStore.getLeaf.bind(stateStore),
+        });
+        await ingestFrom(chainId, fromIndex, account);
     }
     // 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 Promise.all([
+            stateStore.clearLeaves(chainId),
+            stateStore.clearNotes(chainId),
+            stateStore.clearCiphertexts(chainId),
+            stateStore.clearNullifiers(chainId),
+        ]);
         await ingestFrom(chainId, 0, account);
     }
+    // Decode a stored ciphertext (3 x 32-byte values) into a Ciphertext object
+    function decodeCiphertext(payload) {
+        const data = [];
+        for (let i = 0; i < 3; i++) {
+            const start = i * FieldSize.SCALAR;
+            const end = start + FieldSize.SCALAR;
+            const slice = payload.slice(start, end);
+            data.push(Hex.toBigInt(Hex.fromBytes(slice)));
+        }
+        return { data: data };
+    }
+    // Re-scan stored ciphertexts for a new account, using batch nullifier check.
+    async function rescanCiphertextsForAccount(chainId, account, leafCount) {
+        const accountMpk = formatUint256(account.masterPublicKey);
+        const pendingNotes = [];
+        for (let index = 0; index < leafCount; index++) {
+            const existingNote = await stateStore.getNote(chainId, index);
+            if (existingNote && existingNote.mpk === accountMpk) {
+                continue;
+            }
+            const ciphertextBytes = await stateStore.getCiphertext(chainId, index);
+            if (!ciphertextBytes)
+                continue;
+            const leaf = await stateStore.getLeaf(chainId, index);
+            if (!leaf)
+                continue;
+            const ciphertext = decodeCiphertext(ciphertextBytes);
+            let note;
+            try {
+                note = decryptNote(ciphertext, account.masterPublicKey);
+            }
+            catch (err) {
+                if (err instanceof CoreError)
+                    continue;
+                throw err;
+            }
+            const npk = poseidon([account.masterPublicKey, note.random]);
+            const commitment = poseidon([npk, BigInt(note.token), note.amount]);
+            if (commitment !== parseHexToBigInt(leaf.commitment))
+                continue;
+            const nullifier = poseidon([account.nullifyingKey, BigInt(index)]);
+            const nullifierHex = formatUint256(nullifier);
+            const baseNoteParams = {
+                chainId,
+                index,
+                commitment: leaf.commitment,
+                token: note.token,
+                amount: note.amount,
+                npk,
+                mpk: account.masterPublicKey,
+                random: note.random,
+                nullifier: nullifierHex,
+                createdTxHash: leaf.txHash,
+                createdEventType: leaf.eventType,
+                createdAt: leaf.insertedAt != null ? leaf.insertedAt * 1000 : undefined,
+            };
+            pendingNotes.push({
+                note: createNoteRecord(baseNoteParams),
+                baseParams: baseNoteParams,
+            });
+        }
+        if (pendingNotes.length > 0) {
+            const spentNullifiers = await indexerClient.checkNullifiers({
+                chainId,
+                nullifiers: pendingNotes.map((p) => p.note.nullifier),
+            });
+            const spentMap = new Map(spentNullifiers.map((n) => [n.nullifier, n]));
+            for (const { note, baseParams } of pendingNotes) {
+                const spent = spentMap.get(note.nullifier);
+                if (spent) {
+                    await stateStore.putNullifier({
+                        chainId,
+                        nullifier: note.nullifier,
+                        noteIndex: note.index,
+                    });
+                    await stateStore.putNote(createNoteRecord({
+                        ...baseParams,
+                        spentAt: spent.spentAt * 1000,
+                        spentTxHash: spent.txHash,
+                    }));
+                }
+                else {
+                    await stateStore.putNote(note);
+                }
+            }
+        }
+    }
+    // Check existing unspent notes for nullification using batch check.
+    async function checkExistingNotesForNullification(chainId, account) {
+        const accountMpk = formatUint256(account.masterPublicKey);
+        const unspentNotes = await stateStore.listNotes({
+            chainId,
+            mpk: accountMpk,
+            includeSpent: false,
+        });
+        if (unspentNotes.length === 0)
+            return;
+        const spentNullifiers = await indexerClient.checkNullifiers({
+            chainId,
+            nullifiers: unspentNotes.map((n) => n.nullifier),
+        });
+        const spentMap = new Map(spentNullifiers.map((n) => [n.nullifier, n]));
+        for (const note of unspentNotes) {
+            const spent = spentMap.get(note.nullifier);
+            if (spent) {
+                await stateStore.putNullifier({
+                    chainId,
+                    nullifier: note.nullifier,
+                    noteIndex: note.index,
+                });
+                await stateStore.markNoteSpent(chainId, note.index, spent.spentAt * 1000, spent.txHash);
+            }
+        }
+    }
     /**
      * 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);
@@ -223,9 +391,8 @@ export function createNoteSyncService(stateStore, options = {}) {
             inFlight: false,
             lastSuccess: null,
         };
-        if (current.inFlight) {
+        if (current.inFlight)
             return;
-        }
         status.set(chainId, { ...current, inFlight: true, lastError: undefined });
         try {
             const start = opts.forceFullResync
@@ -238,19 +405,57 @@ export function createNoteSyncService(stateStore, options = {}) {
             if (opts.forceFullResync) {
                 await fullResync(chainId, account);
             }
+            else if (start > 0) {
+                try {
+                    const diagnosis = await diagnoseChainState(chainId, start);
+                    switch (diagnosis.kind) {
+                        case "consistent":
+                            try {
+                                await ingestFrom(chainId, start, account);
+                            }
+                            catch (err) {
+                                console.warn(`[note-sync] incremental ingest failed for chain ${chainId}, falling back to full resync:`, err);
+                                await fullResync(chainId, account);
+                            }
+                            break;
+                        case "partial-divergence":
+                            await partialResync(chainId, diagnosis.validPrefix, account);
+                            break;
+                        case "full-divergence":
+                            await fullResync(chainId, account);
+                            break;
+                    }
+                }
+                catch (err) {
+                    console.warn(`[note-sync] chain diagnosis failed for chain ${chainId}, falling back to full resync:`, err);
+                    await fullResync(chainId, account);
+                }
+            }
             else {
+                // start === 0, fresh first sync
                 try {
-                    await ingestFrom(chainId, start, account);
+                    await ingestFrom(chainId, 0, account);
                 }
                 catch (err) {
-                    // Fallback to full resync on ordering/root mismatch.
+                    console.warn(`[note-sync] initial ingest failed for chain ${chainId}, falling back to full resync:`, err);
                     await fullResync(chainId, account);
                 }
             }
-            status.set(chainId, {
-                inFlight: false,
-                lastSuccess: Date.now(),
-            });
+            // Rescan ciphertexts for multi-account support
+            const accountMpk = formatUint256(account.masterPublicKey);
+            const leafCount = trees.getLeafCount(chainId);
+            if (leafCount > 0 && !opts.forceFullResync) {
+                const accountNotes = await stateStore.listNotes({
+                    chainId,
+                    mpk: accountMpk,
+                });
+                if (accountNotes.length < leafCount) {
+                    await rescanCiphertextsForAccount(chainId, account, leafCount);
+                }
+            }
+            // Check if any existing unspent notes have been nullified
+            await checkExistingNotesForNullification(chainId, account);
+            status.set(chainId, { inFlight: false, lastSuccess: Date.now() });
         }
         catch (err) {
             status.set(chainId, {
@@ -269,50 +474,10 @@ export function createNoteSyncService(stateStore, options = {}) {
             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

@@ -1,20 +1,18 @@
-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>;
-};
+import type { JobKind, JobStatus } from "../state/index.js";
+import type { BaseStateStore, DepositSyncResult, TransactSyncResult } from "./types/index.js";
 type ReconcilerDeps = {
     stateStore: BaseStateStore;
-    depositClient: DepositClient;
-    transactService: TransactService;
+    depositClient: {
+        syncPendingDeposit: (relayId: string) => Promise<DepositSyncResult>;
+    };
+    transactService: {
+        syncPendingTransact: (relayId: string) => Promise<TransactSyncResult>;
+    };
 };
 export declare function createJobReconciler(deps: ReconcilerDeps): {
-    reconcileRelay: (relayId: string) => Promise<DepositSyncResult | TransactSyncResult>;
+    reconcileRelay: (relayId: string) => Promise<Error | DepositSyncResult | TransactSyncResult | null>;
     reconcileAll: (filter?: {
-        kind?: PendingJobKind;
+        kind?: JobKind;
         statuses?: JobStatus[];
     }) => Promise<unknown[]>;
 };