@orbinum/sdk 1.2.0 → 1.3.1

package/dist/index.d.mts

@@ -4503,9 +4503,9 @@ declare function windowSizeForCounter(counter: number): number;
  * Phase 1 — walk the hint feed and trial-decrypt every memo against the wallet's
  * keys.
  *
- * Pure collection: no vault writes and no spent-status resolution, both of which
- * are later phases. Nothing here persists, so the note list a user is looking at
- * stays stable for the whole scan.
+ * Pure collection: this phase itself writes nothing — persistence happens only
+ * through the injected `onPage`/`onBatchDone` callbacks, so the caller decides
+ * what (if anything) is checkpointed while the scan runs.
  *
  * Transport, in order of preference:
  *   1. Sealed chunks — the immutable bulk of the feed, digest-addressed and
@@ -4515,9 +4515,9 @@ declare function windowSizeForCounter(counter: number): number;
  *
  * The expensive part (one ECDH per memo) runs in the injected decrypt pool —
  * Web Workers when the host provides a factory, a yielded loop otherwise — while
- * the cheap bookkeeping (cursor, on-chain set, counters) stays here. The next
- * chunk/page is prefetched while the current one decrypts, overlapping network
- * and CPU.
+ * the cheap bookkeeping (cursor, on-chain set, counters) stays here. Both
+ * transports download through the same PREFETCH-deep sliding window
+ * (`runPrefetched`), overlapping network and CPU.
  */
 
 /**
@@ -4552,8 +4552,11 @@ interface ScanOutcome {
     onChainHexes: Set<string>;
     /** Highest leafIndex seen — the next incremental scan resumes after it. */
     maxLeafIndex: number | undefined;
+    /** Hints walked this call, across both transports. */
     scanned: number;
+    /** Notes recovered that the vault did not hold yet. */
     found: number;
+    /** Hints carrying no memo or ephemeral key — nothing to decrypt. */
     noMemo: number;
     /**
      * Hints whose memo did not open with this wallet's keys.
@@ -4564,6 +4567,7 @@ interface ScanOutcome {
      * recovers nothing while this equals the whole pool has a key problem.
      */
     decryptFailed: number;
+    /** Notes recovered that the vault already held. */
     alreadyPresent: number;
     /** Hints discarded by the view-tag fast filter (no AEAD decrypt attempted). */
     tagFiltered: number;
@@ -4600,6 +4604,15 @@ interface CollectScanEntriesParams {
         note: ZkNote;
         isNew: boolean;
     }>) => Promise<void>) | undefined;
+    /**
+     * Awaited after each fully processed chunk/page — AFTER `onPage`, so the
+     * batch's notes are already in the caller's hands — with the highest valid
+     * leaf seen so far. Fires for every batch, including ones with no owned
+     * notes: that is the common case, and the checkpoint must advance past
+     * other people's leaves too. Lets callers persist the scan cursor
+     * incrementally so an aborted scan resumes instead of restarting.
+     */
+    onBatchDone?: ((maxLeafIndex: number | undefined) => Promise<void>) | undefined;
     /**
      * Bounds `outcome.onChainHexes` to commitments the wallet actually holds.
      * Pass the pre-scan snapshot, since `existingHexes` grows during the scan.
@@ -4678,14 +4691,16 @@ declare function resolveSpentStatus(params: {
  * casing between runs cannot split one nullifier into two entries.
  */
 
-interface ResolveSpentSetParams {
+interface OpenSpentSetParams {
     source: NullifierSource;
     cache: NullifierCache;
-    /** The wallet's own nullifiers, lowercase hex. */
-    ownNullifiers: Set<string>;
     signal?: AbortSignal | undefined;
     onWarning?: ((message: string, cause?: unknown) => void) | undefined;
 }
+interface ResolveSpentSetParams extends OpenSpentSetParams {
+    /** The wallet's own nullifiers, lowercase hex. */
+    ownNullifiers: Set<string>;
+}
 /**
  * Returns ONLY the spent members of `ownNullifiers` as a Map hex → spend details
  * (block timestamp + spending tx hash, each null when the row carried none).

package/dist/index.d.ts

@@ -4503,9 +4503,9 @@ declare function windowSizeForCounter(counter: number): number;
  * Phase 1 — walk the hint feed and trial-decrypt every memo against the wallet's
  * keys.
  *
- * Pure collection: no vault writes and no spent-status resolution, both of which
- * are later phases. Nothing here persists, so the note list a user is looking at
- * stays stable for the whole scan.
+ * Pure collection: this phase itself writes nothing — persistence happens only
+ * through the injected `onPage`/`onBatchDone` callbacks, so the caller decides
+ * what (if anything) is checkpointed while the scan runs.
  *
  * Transport, in order of preference:
  *   1. Sealed chunks — the immutable bulk of the feed, digest-addressed and
@@ -4515,9 +4515,9 @@ declare function windowSizeForCounter(counter: number): number;
  *
  * The expensive part (one ECDH per memo) runs in the injected decrypt pool —
  * Web Workers when the host provides a factory, a yielded loop otherwise — while
- * the cheap bookkeeping (cursor, on-chain set, counters) stays here. The next
- * chunk/page is prefetched while the current one decrypts, overlapping network
- * and CPU.
+ * the cheap bookkeeping (cursor, on-chain set, counters) stays here. Both
+ * transports download through the same PREFETCH-deep sliding window
+ * (`runPrefetched`), overlapping network and CPU.
  */
 
 /**
@@ -4552,8 +4552,11 @@ interface ScanOutcome {
     onChainHexes: Set<string>;
     /** Highest leafIndex seen — the next incremental scan resumes after it. */
     maxLeafIndex: number | undefined;
+    /** Hints walked this call, across both transports. */
     scanned: number;
+    /** Notes recovered that the vault did not hold yet. */
     found: number;
+    /** Hints carrying no memo or ephemeral key — nothing to decrypt. */
     noMemo: number;
     /**
      * Hints whose memo did not open with this wallet's keys.
@@ -4564,6 +4567,7 @@ interface ScanOutcome {
      * recovers nothing while this equals the whole pool has a key problem.
      */
     decryptFailed: number;
+    /** Notes recovered that the vault already held. */
     alreadyPresent: number;
     /** Hints discarded by the view-tag fast filter (no AEAD decrypt attempted). */
     tagFiltered: number;
@@ -4600,6 +4604,15 @@ interface CollectScanEntriesParams {
         note: ZkNote;
         isNew: boolean;
     }>) => Promise<void>) | undefined;
+    /**
+     * Awaited after each fully processed chunk/page — AFTER `onPage`, so the
+     * batch's notes are already in the caller's hands — with the highest valid
+     * leaf seen so far. Fires for every batch, including ones with no owned
+     * notes: that is the common case, and the checkpoint must advance past
+     * other people's leaves too. Lets callers persist the scan cursor
+     * incrementally so an aborted scan resumes instead of restarting.
+     */
+    onBatchDone?: ((maxLeafIndex: number | undefined) => Promise<void>) | undefined;
     /**
      * Bounds `outcome.onChainHexes` to commitments the wallet actually holds.
      * Pass the pre-scan snapshot, since `existingHexes` grows during the scan.
@@ -4678,14 +4691,16 @@ declare function resolveSpentStatus(params: {
  * casing between runs cannot split one nullifier into two entries.
  */
 
-interface ResolveSpentSetParams {
+interface OpenSpentSetParams {
     source: NullifierSource;
     cache: NullifierCache;
-    /** The wallet's own nullifiers, lowercase hex. */
-    ownNullifiers: Set<string>;
     signal?: AbortSignal | undefined;
     onWarning?: ((message: string, cause?: unknown) => void) | undefined;
 }
+interface ResolveSpentSetParams extends OpenSpentSetParams {
+    /** The wallet's own nullifiers, lowercase hex. */
+    ownNullifiers: Set<string>;
+}
 /**
  * Returns ONLY the spent members of `ownNullifiers` as a Map hex → spend details
  * (block timestamp + spending tx hash, each null when the row carried none).

package/dist/index.js

@@ -5880,6 +5880,7 @@ var VaultStore = class {
 
 // src/wallet/scanner/phases/collect.ts
 var PAGE_SIZE = 2500;
+var PREFETCH = 3;
 async function processHints(ctx, hints, total) {
   const { outcome } = ctx;
   const toDecrypt = [];
@@ -5924,8 +5925,27 @@ async function processHints(ctx, hints, total) {
     pageEntries.push({ note, isNew });
   }
   if (pageEntries.length > 0) await ctx.onPage?.(pageEntries);
+  await ctx.onBatchDone?.(outcome.maxLeafIndex);
   ctx.onProgress?.({ scanned: outcome.scanned, total, found: outcome.found });
 }
+async function runPrefetched(count, fetchItem, signal, handle) {
+  const inFlight = /* @__PURE__ */ new Map();
+  const ensureFetching = (i) => {
+    if (i < count && !inFlight.has(i)) inFlight.set(i, fetchItem(i));
+  };
+  try {
+    for (let i = 0; i < count; i++) {
+      if (signal?.aborted) throw scanAbortError();
+      for (let n = i; n < i + PREFETCH; n++) ensureFetching(n);
+      const item = await inFlight.get(i);
+      inFlight.delete(i);
+      await handle(item);
+    }
+  } finally {
+    for (const pending of inFlight.values()) pending.catch(() => {
+    });
+  }
+}
 async function processSealedChunks(ctx, source, sinceLeafIndex) {
   if (!source.chunks) return null;
   const manifest = await source.chunks.manifest().catch(() => null);
@@ -5938,26 +5958,36 @@ async function processSealedChunks(ctx, source, sinceLeafIndex) {
   if (pending.length === 0) return null;
   const total = Math.max(manifest.total - startLeaf, 0);
   const fetchChunk = (i) => source.chunks.chunk(pending[i].idx, pending[i].digest);
-  let nextChunk = fetchChunk(0);
-  try {
-    for (let i = 0; i < pending.length; i++) {
-      if (ctx.signal?.aborted) throw scanAbortError();
-      const hints = await nextChunk;
-      nextChunk = i + 1 < pending.length ? fetchChunk(i + 1) : null;
-      await processHints(
+  await runPrefetched(
+    pending.length,
+    fetchChunk,
+    ctx.signal,
+    (hints) => (
+      // The first chunk may straddle the cursor — drop already-scanned leaves.
+      processHints(
         ctx,
         hints.filter((h) => (h.leafIndex ?? 0) >= startLeaf),
         total
-      );
-    }
-  } finally {
-    nextChunk?.catch(() => {
-    });
-  }
+      )
+    )
+  );
   return manifest.lastSealedLeaf + 1;
 }
+async function processPaginatedTail(ctx, source, sinceLeafIndex) {
+  const fetchPage = (page) => source.listHints({ page, limit: PAGE_SIZE, sinceLeafIndex });
+  const firstPage = await fetchPage(1);
+  const total = ctx.outcome.scanned + firstPage.pagination.total;
+  const effectiveLimit = firstPage.pagination.limit || PAGE_SIZE;
+  const totalPages = Math.max(Math.ceil(firstPage.pagination.total / effectiveLimit), 1);
+  await runPrefetched(
+    totalPages,
+    (i) => i === 0 ? Promise.resolve(firstPage) : fetchPage(i + 1),
+    ctx.signal,
+    (page) => processHints(ctx, page.data, total)
+  );
+}
 async function collectScanEntries(params) {
-  const { source, pool, keys, existingHexes, sinceLeafIndex, onProgress, signal, onPage } = params;
+  const { source, sinceLeafIndex, signal } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -5975,13 +6005,14 @@ async function collectScanEntries(params) {
   };
   const ctx = {
     outcome,
-    pool,
-    keys,
-    existingHexes,
-    vaultHexes: params.vaultHexes ?? existingHexes,
-    onProgress,
+    pool: params.pool,
+    keys: params.keys,
+    existingHexes: params.existingHexes,
+    vaultHexes: params.vaultHexes ?? params.existingHexes,
+    onProgress: params.onProgress,
     signal,
-    onPage
+    onPage: params.onPage,
+    onBatchDone: params.onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -5992,93 +6023,16 @@ async function collectScanEntries(params) {
     params.onWarning?.("sealed-chunk path failed; falling back to paginated hints", err);
     if (outcome.maxLeafIndex !== void 0) tailSince = outcome.maxLeafIndex + 1;
   }
-  const fetchPage = (page) => source.listHints({ page, limit: PAGE_SIZE, sinceLeafIndex: tailSince });
-  const firstPage = await fetchPage(1);
-  const total = outcome.scanned + firstPage.pagination.total;
-  const effectiveLimit = firstPage.pagination.limit || PAGE_SIZE;
-  const totalPages = Math.ceil(firstPage.pagination.total / effectiveLimit);
-  const PREFETCH = 3;
-  const inFlight = /* @__PURE__ */ new Map();
-  const ensureFetching = (page) => {
-    if (page >= 2 && page <= totalPages && !inFlight.has(page)) {
-      inFlight.set(page, fetchPage(page));
-    }
-  };
-  try {
-    for (let p = 2; p < 2 + PREFETCH; p++) ensureFetching(p);
-    await processHints(ctx, firstPage.data, total);
-    for (let page = 2; page <= totalPages; page++) {
-      if (signal?.aborted) throw scanAbortError();
-      ensureFetching(page);
-      const current = await inFlight.get(page);
-      inFlight.delete(page);
-      for (let p = page + 1; p <= page + PREFETCH; p++) ensureFetching(p);
-      await processHints(ctx, current.data, total);
-    }
-  } finally {
-    for (const pending of inFlight.values()) pending.catch(() => {
-    });
-  }
+  await processPaginatedTail(ctx, source, tailSince);
   return outcome;
 }
 
-// src/wallet/worker/kernel/types.ts
-var SELF_EPH_WINDOW = 1024;
-var PAIRWISE_EPH_WINDOW = 64;
-var EMPTY_BATCH_RESULT = {
-  notes: [],
-  tagFiltered: 0,
-  selfMatched: 0,
-  pairwiseMatched: 0,
-  maxSelfEphIndex: null
-};
-
-// src/wallet/scanner/selfEphGap.ts
-function noteEphPkHex(note) {
-  if (!Array.isArray(note.memo) || note.memo.length < 32) return null;
-  return toHex(note.memo.slice(-32)).toLowerCase();
-}
-function gapMargin(windowSize) {
-  return Math.max(1, Math.floor(windowSize / 16));
-}
-function resolveSelfEphCeiling(params) {
-  const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
-  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
-  if (scanMaxIndex === null) return null;
-  if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
-  const ownEphPks = /* @__PURE__ */ new Set();
-  for (const note of notes) {
-    const hex = noteEphPkHex(note);
-    if (hex) ownEphPks.add(hex);
-  }
-  const ivkPacked = deriveViewingPublicKey(viewingKey);
-  let max = scanMaxIndex;
-  let from = windowSize;
-  for (; ; ) {
-    const slice = selfEphWindow(spendingKey, ivkPacked, from, windowSize);
-    let matched = false;
-    for (const entry of slice) {
-      if (ownEphPks.has(entry.ephPkHex.toLowerCase())) {
-        matched = true;
-        if (entry.index > max) max = entry.index;
-      }
-    }
-    if (!matched) break;
-    from += windowSize;
-  }
-  return max;
-}
-function windowSizeForCounter(counter) {
-  const needed = counter + gapMargin(SELF_EPH_WINDOW);
-  return Math.max(SELF_EPH_WINDOW, Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW);
-}
-
 // src/wallet/scanner/phases/spentSet.ts
 function normalizeNullifierHex(hex) {
   return hex.toLowerCase();
 }
-async function resolveSpentSet(params) {
-  const { source, cache, ownNullifiers, signal } = params;
+async function openSpentSet(params) {
+  const { source, cache, signal } = params;
   const throwIfAborted = () => {
     if (signal?.aborted) throw scanAbortError();
   };
@@ -6087,20 +6041,29 @@ async function resolveSpentSet(params) {
   await syncNullifierCache(params, manifest, throwIfAborted);
   throwIfAborted();
   const tail = await getConsistentTail(params, throwIfAborted);
-  const stored = await cache.getSpentNullifiers([...ownNullifiers]);
   const tailMap = new Map(
     tail.data.map((h, i) => [
       normalizeNullifierHex(h),
       { spentAt: tail.timestampsMs?.[i] ?? null, txHash: tail.txHashes?.[i] ?? null }
     ])
   );
-  const spent = /* @__PURE__ */ new Map();
-  const unknown = { spentAt: null, txHash: null };
-  for (const h of ownNullifiers) {
-    if (stored.has(h)) spent.set(h, stored.get(h) ?? unknown);
-    else if (tailMap.has(h)) spent.set(h, tailMap.get(h) ?? unknown);
-  }
-  return spent;
+  return {
+    async query(ownNullifiers) {
+      if (ownNullifiers.size === 0) return /* @__PURE__ */ new Map();
+      const stored = await cache.getSpentNullifiers([...ownNullifiers]);
+      const spent = /* @__PURE__ */ new Map();
+      const unknown = { spentAt: null, txHash: null };
+      for (const h of ownNullifiers) {
+        if (stored.has(h)) spent.set(h, stored.get(h) ?? unknown);
+        else if (tailMap.has(h)) spent.set(h, tailMap.get(h) ?? unknown);
+      }
+      return spent;
+    }
+  };
+}
+async function resolveSpentSet(params) {
+  const handle = await openSpentSet(params);
+  return handle.query(params.ownNullifiers);
 }
 async function syncNullifierCache(params, manifest, throwIfAborted) {
   const { source, cache } = params;
@@ -6150,40 +6113,6 @@ async function getConsistentTail(params, throwIfAborted) {
   throw new Error("nullifier tail inconsistent with local chunks after retry");
 }
 
-// src/wallet/scanner/phases/spentStatus.ts
-function collectNullifiersToQuery(scanEntries, onChainHexes, vaultNotes) {
-  const syncedCommitments = new Set(scanEntries.map((e) => e.note.commitmentHex));
-  const nullifiers = /* @__PURE__ */ new Set();
-  for (const { note } of scanEntries) {
-    nullifiers.add(note.nullifierHex.toLowerCase());
-  }
-  for (const vaultNote of vaultNotes) {
-    if (syncedCommitments.has(vaultNote.commitmentHex)) continue;
-    if (!onChainHexes.has(vaultNote.commitmentHex)) continue;
-    if (vaultNote.nullifierHex) nullifiers.add(vaultNote.nullifierHex.toLowerCase());
-  }
-  return nullifiers;
-}
-async function resolveSpentStatus(params) {
-  if (params.nullifiers.size === 0) return /* @__PURE__ */ new Map();
-  try {
-    return await resolveSpentSet({
-      source: params.source,
-      cache: params.cache,
-      ownNullifiers: params.nullifiers,
-      signal: params.signal,
-      onWarning: params.onWarning
-    });
-  } catch (err) {
-    if (isAbortError(err)) throw err;
-    params.onWarning?.(
-      "could not resolve spent-nullifier status (feed unavailable or inconsistent); spent status left unverified this pass",
-      err
-    );
-    return /* @__PURE__ */ new Map();
-  }
-}
-
 // src/wallet/scanner/phases/persist.ts
 function purgeIsTrustworthy(hintsScanned, purgeableNotes) {
   if (purgeableNotes === 0) return true;
@@ -6242,6 +6171,134 @@ async function persistCursor(storage, maxLeafIndex, isIncremental) {
   });
 }
 
+// src/wallet/scanner/phases/checkpoint.ts
+function createScanCheckpoint(params) {
+  const { vault, storage, nullifiers, isIncremental, signal, onWarning } = params;
+  const throwIfAborted = () => {
+    if (signal?.aborted) throw scanAbortError();
+  };
+  let spentSetPromise = null;
+  const getSpentSet = () => spentSetPromise ??= openSpentSet({
+    source: nullifiers,
+    cache: storage,
+    signal,
+    onWarning
+  }).catch(() => null);
+  return {
+    async savePageNotes(entries) {
+      throwIfAborted();
+      const fresh = entries.filter((e) => e.isNew);
+      if (fresh.length === 0) return;
+      const own = new Set(fresh.map((e) => e.note.nullifierHex.toLowerCase()));
+      const spentSet = await getSpentSet();
+      const spent = spentSet ? await spentSet.query(own).catch(() => /* @__PURE__ */ new Map()) : /* @__PURE__ */ new Map();
+      throwIfAborted();
+      await vault.saveMany(
+        fresh.map(({ note }) => {
+          const spend = spent.get(note.nullifierHex.toLowerCase());
+          return {
+            note: spend ? stampSpentTxHash(note, spend.txHash) : note,
+            noteStatus: {
+              spent: spend !== void 0,
+              spentAt: spend?.spentAt ?? null
+            }
+          };
+        })
+      );
+    },
+    async advanceCursor(maxLeafIndex) {
+      if (maxLeafIndex === void 0) return;
+      throwIfAborted();
+      await persistCursor(storage, maxLeafIndex, isIncremental);
+    }
+  };
+}
+
+// src/wallet/worker/kernel/types.ts
+var SELF_EPH_WINDOW = 1024;
+var PAIRWISE_EPH_WINDOW = 64;
+var EMPTY_BATCH_RESULT = {
+  notes: [],
+  tagFiltered: 0,
+  selfMatched: 0,
+  pairwiseMatched: 0,
+  maxSelfEphIndex: null
+};
+
+// src/wallet/scanner/selfEphGap.ts
+function noteEphPkHex(note) {
+  if (!Array.isArray(note.memo) || note.memo.length < 32) return null;
+  return toHex(note.memo.slice(-32)).toLowerCase();
+}
+function gapMargin(windowSize) {
+  return Math.max(1, Math.floor(windowSize / 16));
+}
+function resolveSelfEphCeiling(params) {
+  const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
+  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
+  if (scanMaxIndex === null) return null;
+  if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
+  const ownEphPks = /* @__PURE__ */ new Set();
+  for (const note of notes) {
+    const hex = noteEphPkHex(note);
+    if (hex) ownEphPks.add(hex);
+  }
+  const ivkPacked = deriveViewingPublicKey(viewingKey);
+  let max = scanMaxIndex;
+  let from = windowSize;
+  for (; ; ) {
+    const slice = selfEphWindow(spendingKey, ivkPacked, from, windowSize);
+    let matched = false;
+    for (const entry of slice) {
+      if (ownEphPks.has(entry.ephPkHex.toLowerCase())) {
+        matched = true;
+        if (entry.index > max) max = entry.index;
+      }
+    }
+    if (!matched) break;
+    from += windowSize;
+  }
+  return max;
+}
+function windowSizeForCounter(counter) {
+  const needed = counter + gapMargin(SELF_EPH_WINDOW);
+  return Math.max(SELF_EPH_WINDOW, Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW);
+}
+
+// src/wallet/scanner/phases/spentStatus.ts
+function collectNullifiersToQuery(scanEntries, onChainHexes, vaultNotes) {
+  const syncedCommitments = new Set(scanEntries.map((e) => e.note.commitmentHex));
+  const nullifiers = /* @__PURE__ */ new Set();
+  for (const { note } of scanEntries) {
+    nullifiers.add(note.nullifierHex.toLowerCase());
+  }
+  for (const vaultNote of vaultNotes) {
+    if (syncedCommitments.has(vaultNote.commitmentHex)) continue;
+    if (!onChainHexes.has(vaultNote.commitmentHex)) continue;
+    if (vaultNote.nullifierHex) nullifiers.add(vaultNote.nullifierHex.toLowerCase());
+  }
+  return nullifiers;
+}
+async function resolveSpentStatus(params) {
+  if (params.nullifiers.size === 0) return /* @__PURE__ */ new Map();
+  try {
+    return await resolveSpentSet({
+      source: params.source,
+      cache: params.cache,
+      ownNullifiers: params.nullifiers,
+      signal: params.signal,
+      onWarning: params.onWarning
+    });
+  } catch (err) {
+    if (isAbortError(err)) throw err;
+    params.onWarning?.(
+      "could not resolve spent-nullifier status (feed unavailable or inconsistent); spent status left unverified this pass",
+      err
+    );
+    return /* @__PURE__ */ new Map();
+  }
+}
+
 // src/wallet/scanner/pipeline.ts
 async function runScan(params) {
   const { vault, storage, hints, nullifiers, pool, keys, sinceLeafIndex, signal, onWarning } = params;
@@ -6260,6 +6317,14 @@ async function runScan(params) {
       }
     }
   );
+  const checkpoint = createScanCheckpoint({
+    vault,
+    storage,
+    nullifiers,
+    isIncremental,
+    signal,
+    onWarning
+  });
   const scan = await collectScanEntries({
     source: hints,
     pool,
@@ -6280,7 +6345,9 @@ async function runScan(params) {
     // consumer probes it with a vault commitment, so keeping the whole pool
     // only bought heap.
     vaultHexes: preScanHexes,
-    onWarning
+    onWarning,
+    onPage: (entries) => checkpoint.savePageNotes(entries),
+    onBatchDone: (maxLeafIndex) => checkpoint.advanceCursor(maxLeafIndex)
   });
   const nullifiersToQuery = collectNullifiersToQuery(
     scan.scanEntries,

package/dist/index.mjs

@@ -4654,6 +4654,7 @@ var VaultStore = class {
 
 // src/wallet/scanner/phases/collect.ts
 var PAGE_SIZE = 2500;
+var PREFETCH = 3;
 async function processHints(ctx, hints, total) {
   const { outcome } = ctx;
   const toDecrypt = [];
@@ -4698,8 +4699,27 @@ async function processHints(ctx, hints, total) {
     pageEntries.push({ note, isNew });
   }
   if (pageEntries.length > 0) await ctx.onPage?.(pageEntries);
+  await ctx.onBatchDone?.(outcome.maxLeafIndex);
   ctx.onProgress?.({ scanned: outcome.scanned, total, found: outcome.found });
 }
+async function runPrefetched(count, fetchItem, signal, handle) {
+  const inFlight = /* @__PURE__ */ new Map();
+  const ensureFetching = (i) => {
+    if (i < count && !inFlight.has(i)) inFlight.set(i, fetchItem(i));
+  };
+  try {
+    for (let i = 0; i < count; i++) {
+      if (signal?.aborted) throw scanAbortError();
+      for (let n = i; n < i + PREFETCH; n++) ensureFetching(n);
+      const item = await inFlight.get(i);
+      inFlight.delete(i);
+      await handle(item);
+    }
+  } finally {
+    for (const pending of inFlight.values()) pending.catch(() => {
+    });
+  }
+}
 async function processSealedChunks(ctx, source, sinceLeafIndex) {
   if (!source.chunks) return null;
   const manifest = await source.chunks.manifest().catch(() => null);
@@ -4712,26 +4732,36 @@ async function processSealedChunks(ctx, source, sinceLeafIndex) {
   if (pending.length === 0) return null;
   const total = Math.max(manifest.total - startLeaf, 0);
   const fetchChunk = (i) => source.chunks.chunk(pending[i].idx, pending[i].digest);
-  let nextChunk = fetchChunk(0);
-  try {
-    for (let i = 0; i < pending.length; i++) {
-      if (ctx.signal?.aborted) throw scanAbortError();
-      const hints = await nextChunk;
-      nextChunk = i + 1 < pending.length ? fetchChunk(i + 1) : null;
-      await processHints(
+  await runPrefetched(
+    pending.length,
+    fetchChunk,
+    ctx.signal,
+    (hints) => (
+      // The first chunk may straddle the cursor — drop already-scanned leaves.
+      processHints(
         ctx,
         hints.filter((h) => (h.leafIndex ?? 0) >= startLeaf),
         total
-      );
-    }
-  } finally {
-    nextChunk?.catch(() => {
-    });
-  }
+      )
+    )
+  );
   return manifest.lastSealedLeaf + 1;
 }
+async function processPaginatedTail(ctx, source, sinceLeafIndex) {
+  const fetchPage = (page) => source.listHints({ page, limit: PAGE_SIZE, sinceLeafIndex });
+  const firstPage = await fetchPage(1);
+  const total = ctx.outcome.scanned + firstPage.pagination.total;
+  const effectiveLimit = firstPage.pagination.limit || PAGE_SIZE;
+  const totalPages = Math.max(Math.ceil(firstPage.pagination.total / effectiveLimit), 1);
+  await runPrefetched(
+    totalPages,
+    (i) => i === 0 ? Promise.resolve(firstPage) : fetchPage(i + 1),
+    ctx.signal,
+    (page) => processHints(ctx, page.data, total)
+  );
+}
 async function collectScanEntries(params) {
-  const { source, pool, keys, existingHexes, sinceLeafIndex, onProgress, signal, onPage } = params;
+  const { source, sinceLeafIndex, signal } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -4749,13 +4779,14 @@ async function collectScanEntries(params) {
   };
   const ctx = {
     outcome,
-    pool,
-    keys,
-    existingHexes,
-    vaultHexes: params.vaultHexes ?? existingHexes,
-    onProgress,
+    pool: params.pool,
+    keys: params.keys,
+    existingHexes: params.existingHexes,
+    vaultHexes: params.vaultHexes ?? params.existingHexes,
+    onProgress: params.onProgress,
     signal,
-    onPage
+    onPage: params.onPage,
+    onBatchDone: params.onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -4766,82 +4797,16 @@ async function collectScanEntries(params) {
     params.onWarning?.("sealed-chunk path failed; falling back to paginated hints", err);
     if (outcome.maxLeafIndex !== void 0) tailSince = outcome.maxLeafIndex + 1;
   }
-  const fetchPage = (page) => source.listHints({ page, limit: PAGE_SIZE, sinceLeafIndex: tailSince });
-  const firstPage = await fetchPage(1);
-  const total = outcome.scanned + firstPage.pagination.total;
-  const effectiveLimit = firstPage.pagination.limit || PAGE_SIZE;
-  const totalPages = Math.ceil(firstPage.pagination.total / effectiveLimit);
-  const PREFETCH = 3;
-  const inFlight = /* @__PURE__ */ new Map();
-  const ensureFetching = (page) => {
-    if (page >= 2 && page <= totalPages && !inFlight.has(page)) {
-      inFlight.set(page, fetchPage(page));
-    }
-  };
-  try {
-    for (let p = 2; p < 2 + PREFETCH; p++) ensureFetching(p);
-    await processHints(ctx, firstPage.data, total);
-    for (let page = 2; page <= totalPages; page++) {
-      if (signal?.aborted) throw scanAbortError();
-      ensureFetching(page);
-      const current = await inFlight.get(page);
-      inFlight.delete(page);
-      for (let p = page + 1; p <= page + PREFETCH; p++) ensureFetching(p);
-      await processHints(ctx, current.data, total);
-    }
-  } finally {
-    for (const pending of inFlight.values()) pending.catch(() => {
-    });
-  }
+  await processPaginatedTail(ctx, source, tailSince);
   return outcome;
 }
 
-// src/wallet/scanner/selfEphGap.ts
-function noteEphPkHex(note) {
-  if (!Array.isArray(note.memo) || note.memo.length < 32) return null;
-  return toHex(note.memo.slice(-32)).toLowerCase();
-}
-function gapMargin(windowSize) {
-  return Math.max(1, Math.floor(windowSize / 16));
-}
-function resolveSelfEphCeiling(params) {
-  const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
-  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
-  if (scanMaxIndex === null) return null;
-  if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
-  const ownEphPks = /* @__PURE__ */ new Set();
-  for (const note of notes) {
-    const hex = noteEphPkHex(note);
-    if (hex) ownEphPks.add(hex);
-  }
-  const ivkPacked = deriveViewingPublicKey(viewingKey);
-  let max = scanMaxIndex;
-  let from = windowSize;
-  for (; ; ) {
-    const slice = selfEphWindow(spendingKey, ivkPacked, from, windowSize);
-    let matched = false;
-    for (const entry of slice) {
-      if (ownEphPks.has(entry.ephPkHex.toLowerCase())) {
-        matched = true;
-        if (entry.index > max) max = entry.index;
-      }
-    }
-    if (!matched) break;
-    from += windowSize;
-  }
-  return max;
-}
-function windowSizeForCounter(counter) {
-  const needed = counter + gapMargin(SELF_EPH_WINDOW);
-  return Math.max(SELF_EPH_WINDOW, Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW);
-}
-
 // src/wallet/scanner/phases/spentSet.ts
 function normalizeNullifierHex(hex) {
   return hex.toLowerCase();
 }
-async function resolveSpentSet(params) {
-  const { source, cache, ownNullifiers, signal } = params;
+async function openSpentSet(params) {
+  const { source, cache, signal } = params;
   const throwIfAborted = () => {
     if (signal?.aborted) throw scanAbortError();
   };
@@ -4850,20 +4815,29 @@ async function resolveSpentSet(params) {
   await syncNullifierCache(params, manifest, throwIfAborted);
   throwIfAborted();
   const tail = await getConsistentTail(params, throwIfAborted);
-  const stored = await cache.getSpentNullifiers([...ownNullifiers]);
   const tailMap = new Map(
     tail.data.map((h, i) => [
       normalizeNullifierHex(h),
       { spentAt: tail.timestampsMs?.[i] ?? null, txHash: tail.txHashes?.[i] ?? null }
     ])
   );
-  const spent = /* @__PURE__ */ new Map();
-  const unknown = { spentAt: null, txHash: null };
-  for (const h of ownNullifiers) {
-    if (stored.has(h)) spent.set(h, stored.get(h) ?? unknown);
-    else if (tailMap.has(h)) spent.set(h, tailMap.get(h) ?? unknown);
-  }
-  return spent;
+  return {
+    async query(ownNullifiers) {
+      if (ownNullifiers.size === 0) return /* @__PURE__ */ new Map();
+      const stored = await cache.getSpentNullifiers([...ownNullifiers]);
+      const spent = /* @__PURE__ */ new Map();
+      const unknown = { spentAt: null, txHash: null };
+      for (const h of ownNullifiers) {
+        if (stored.has(h)) spent.set(h, stored.get(h) ?? unknown);
+        else if (tailMap.has(h)) spent.set(h, tailMap.get(h) ?? unknown);
+      }
+      return spent;
+    }
+  };
+}
+async function resolveSpentSet(params) {
+  const handle = await openSpentSet(params);
+  return handle.query(params.ownNullifiers);
 }
 async function syncNullifierCache(params, manifest, throwIfAborted) {
   const { source, cache } = params;
@@ -4913,40 +4887,6 @@ async function getConsistentTail(params, throwIfAborted) {
   throw new Error("nullifier tail inconsistent with local chunks after retry");
 }
 
-// src/wallet/scanner/phases/spentStatus.ts
-function collectNullifiersToQuery(scanEntries, onChainHexes, vaultNotes) {
-  const syncedCommitments = new Set(scanEntries.map((e) => e.note.commitmentHex));
-  const nullifiers = /* @__PURE__ */ new Set();
-  for (const { note } of scanEntries) {
-    nullifiers.add(note.nullifierHex.toLowerCase());
-  }
-  for (const vaultNote of vaultNotes) {
-    if (syncedCommitments.has(vaultNote.commitmentHex)) continue;
-    if (!onChainHexes.has(vaultNote.commitmentHex)) continue;
-    if (vaultNote.nullifierHex) nullifiers.add(vaultNote.nullifierHex.toLowerCase());
-  }
-  return nullifiers;
-}
-async function resolveSpentStatus(params) {
-  if (params.nullifiers.size === 0) return /* @__PURE__ */ new Map();
-  try {
-    return await resolveSpentSet({
-      source: params.source,
-      cache: params.cache,
-      ownNullifiers: params.nullifiers,
-      signal: params.signal,
-      onWarning: params.onWarning
-    });
-  } catch (err) {
-    if (isAbortError(err)) throw err;
-    params.onWarning?.(
-      "could not resolve spent-nullifier status (feed unavailable or inconsistent); spent status left unverified this pass",
-      err
-    );
-    return /* @__PURE__ */ new Map();
-  }
-}
-
 // src/wallet/scanner/phases/persist.ts
 function purgeIsTrustworthy(hintsScanned, purgeableNotes) {
   if (purgeableNotes === 0) return true;
@@ -5005,6 +4945,123 @@ async function persistCursor(storage, maxLeafIndex, isIncremental) {
   });
 }
 
+// src/wallet/scanner/phases/checkpoint.ts
+function createScanCheckpoint(params) {
+  const { vault, storage, nullifiers, isIncremental, signal, onWarning } = params;
+  const throwIfAborted = () => {
+    if (signal?.aborted) throw scanAbortError();
+  };
+  let spentSetPromise = null;
+  const getSpentSet = () => spentSetPromise ??= openSpentSet({
+    source: nullifiers,
+    cache: storage,
+    signal,
+    onWarning
+  }).catch(() => null);
+  return {
+    async savePageNotes(entries) {
+      throwIfAborted();
+      const fresh = entries.filter((e) => e.isNew);
+      if (fresh.length === 0) return;
+      const own = new Set(fresh.map((e) => e.note.nullifierHex.toLowerCase()));
+      const spentSet = await getSpentSet();
+      const spent = spentSet ? await spentSet.query(own).catch(() => /* @__PURE__ */ new Map()) : /* @__PURE__ */ new Map();
+      throwIfAborted();
+      await vault.saveMany(
+        fresh.map(({ note }) => {
+          const spend = spent.get(note.nullifierHex.toLowerCase());
+          return {
+            note: spend ? stampSpentTxHash(note, spend.txHash) : note,
+            noteStatus: {
+              spent: spend !== void 0,
+              spentAt: spend?.spentAt ?? null
+            }
+          };
+        })
+      );
+    },
+    async advanceCursor(maxLeafIndex) {
+      if (maxLeafIndex === void 0) return;
+      throwIfAborted();
+      await persistCursor(storage, maxLeafIndex, isIncremental);
+    }
+  };
+}
+
+// src/wallet/scanner/selfEphGap.ts
+function noteEphPkHex(note) {
+  if (!Array.isArray(note.memo) || note.memo.length < 32) return null;
+  return toHex(note.memo.slice(-32)).toLowerCase();
+}
+function gapMargin(windowSize) {
+  return Math.max(1, Math.floor(windowSize / 16));
+}
+function resolveSelfEphCeiling(params) {
+  const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
+  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
+  if (scanMaxIndex === null) return null;
+  if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
+  const ownEphPks = /* @__PURE__ */ new Set();
+  for (const note of notes) {
+    const hex = noteEphPkHex(note);
+    if (hex) ownEphPks.add(hex);
+  }
+  const ivkPacked = deriveViewingPublicKey(viewingKey);
+  let max = scanMaxIndex;
+  let from = windowSize;
+  for (; ; ) {
+    const slice = selfEphWindow(spendingKey, ivkPacked, from, windowSize);
+    let matched = false;
+    for (const entry of slice) {
+      if (ownEphPks.has(entry.ephPkHex.toLowerCase())) {
+        matched = true;
+        if (entry.index > max) max = entry.index;
+      }
+    }
+    if (!matched) break;
+    from += windowSize;
+  }
+  return max;
+}
+function windowSizeForCounter(counter) {
+  const needed = counter + gapMargin(SELF_EPH_WINDOW);
+  return Math.max(SELF_EPH_WINDOW, Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW);
+}
+
+// src/wallet/scanner/phases/spentStatus.ts
+function collectNullifiersToQuery(scanEntries, onChainHexes, vaultNotes) {
+  const syncedCommitments = new Set(scanEntries.map((e) => e.note.commitmentHex));
+  const nullifiers = /* @__PURE__ */ new Set();
+  for (const { note } of scanEntries) {
+    nullifiers.add(note.nullifierHex.toLowerCase());
+  }
+  for (const vaultNote of vaultNotes) {
+    if (syncedCommitments.has(vaultNote.commitmentHex)) continue;
+    if (!onChainHexes.has(vaultNote.commitmentHex)) continue;
+    if (vaultNote.nullifierHex) nullifiers.add(vaultNote.nullifierHex.toLowerCase());
+  }
+  return nullifiers;
+}
+async function resolveSpentStatus(params) {
+  if (params.nullifiers.size === 0) return /* @__PURE__ */ new Map();
+  try {
+    return await resolveSpentSet({
+      source: params.source,
+      cache: params.cache,
+      ownNullifiers: params.nullifiers,
+      signal: params.signal,
+      onWarning: params.onWarning
+    });
+  } catch (err) {
+    if (isAbortError(err)) throw err;
+    params.onWarning?.(
+      "could not resolve spent-nullifier status (feed unavailable or inconsistent); spent status left unverified this pass",
+      err
+    );
+    return /* @__PURE__ */ new Map();
+  }
+}
+
 // src/wallet/scanner/pipeline.ts
 async function runScan(params) {
   const { vault, storage, hints, nullifiers, pool, keys, sinceLeafIndex, signal, onWarning } = params;
@@ -5023,6 +5080,14 @@ async function runScan(params) {
       }
     }
   );
+  const checkpoint = createScanCheckpoint({
+    vault,
+    storage,
+    nullifiers,
+    isIncremental,
+    signal,
+    onWarning
+  });
   const scan = await collectScanEntries({
     source: hints,
     pool,
@@ -5043,7 +5108,9 @@ async function runScan(params) {
     // consumer probes it with a vault commitment, so keeping the whole pool
     // only bought heap.
     vaultHexes: preScanHexes,
-    onWarning
+    onWarning,
+    onPage: (entries) => checkpoint.savePageNotes(entries),
+    onBatchDone: (maxLeafIndex) => checkpoint.advanceCursor(maxLeafIndex)
   });
   const nullifiersToQuery = collectNullifiersToQuery(
     scan.scanEntries,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",