@orbinum/sdk 1.2.0 → 1.3.0

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
@@ -4600,6 +4600,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 +4687,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
@@ -4600,6 +4600,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 +4687,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

@@ -5924,6 +5924,7 @@ 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 processSealedChunks(ctx, source, sinceLeafIndex) {
@@ -5958,6 +5959,7 @@ async function processSealedChunks(ctx, source, sinceLeafIndex) {
 }
 async function collectScanEntries(params) {
   const { source, pool, keys, existingHexes, sinceLeafIndex, onProgress, signal, onPage } = params;
+  const { onBatchDone } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -5981,7 +5983,8 @@ async function collectScanEntries(params) {
     vaultHexes: params.vaultHexes ?? existingHexes,
     onProgress,
     signal,
-    onPage
+    onPage,
+    onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -6022,63 +6025,12 @@ async function collectScanEntries(params) {
   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 +6039,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 +6111,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 +6169,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 +6315,14 @@ async function runScan(params) {
       }
     }
   );
+  const checkpoint = createScanCheckpoint({
+    vault,
+    storage,
+    nullifiers,
+    isIncremental,
+    signal,
+    onWarning
+  });
   const scan = await collectScanEntries({
     source: hints,
     pool,
@@ -6280,7 +6343,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

@@ -4698,6 +4698,7 @@ 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 processSealedChunks(ctx, source, sinceLeafIndex) {
@@ -4732,6 +4733,7 @@ async function processSealedChunks(ctx, source, sinceLeafIndex) {
 }
 async function collectScanEntries(params) {
   const { source, pool, keys, existingHexes, sinceLeafIndex, onProgress, signal, onPage } = params;
+  const { onBatchDone } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -4755,7 +4757,8 @@ async function collectScanEntries(params) {
     vaultHexes: params.vaultHexes ?? existingHexes,
     onProgress,
     signal,
-    onPage
+    onPage,
+    onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -4796,52 +4799,12 @@ async function collectScanEntries(params) {
   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 +4813,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 +4885,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 +4943,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 +5078,14 @@ async function runScan(params) {
       }
     }
   );
+  const checkpoint = createScanCheckpoint({
+    vault,
+    storage,
+    nullifiers,
+    isIncremental,
+    signal,
+    onWarning
+  });
   const scan = await collectScanEntries({
     source: hints,
     pool,
@@ -5043,7 +5106,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.0",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",