@orbinum/sdk 1.3.0 → 1.4.0

package/dist/index.d.mts

@@ -240,8 +240,27 @@ declare function reserveSelfEphIndex(storage: NoteStorage): Promise<number>;
  * viewing public key. Registering the counterparty is a side effect worth
  * having: it makes the REVERSE direction cheap too, since their future payments
  * to this wallet become hash lookups instead of one trial ECDH per note.
+ *
+ * Returns `null` when this vault holds no history for that counterparty, and
+ * the caller must then use a random ephemeral. The reason is that "no history"
+ * has two causes this function cannot tell apart:
+ *
+ *   - a genuine first payment, where index 0 is correct;
+ *   - a counter that was LOST — a restored seed, a cleared IndexedDB, a wipe
+ *     and rescan — where index 0 was already published and re-deriving it
+ *     republishes that ephPk, linking the two notes in public.
+ *
+ * Unlike `selfEphCounter`, this one cannot be recovered: the index was
+ * published on a note encrypted toward someone else, so it never appears in
+ * this wallet's own scan, and asking a server whether a given ephPk exists
+ * would reveal which notes are ours. So the ambiguity is resolved the safe way
+ * — the caller degrades to random, costing the recipient one trial scan, and
+ * every later payment to the same counterparty takes the fast path again.
+ *
+ * The entry is still created: the NEXT payment has a counter, and registering
+ * the counterparty is what makes the reverse direction cheap.
  */
-declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number>;
+declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number | null>;
 
 /**
  * Turning a note into a stored record and back.
@@ -4495,7 +4514,13 @@ declare function resolveSelfEphCeiling(params: {
 /**
  * Discovery window size for the next scan, given the persisted counter: at least
  * the default, rounded up so every index the wallet may already have used (plus
- * the gap margin) falls inside the fast path.
+ * the gap margin) falls inside the fast path, and never past `MAX_EPH_WINDOW`.
+ *
+ * The counter is read from a config that survives restores and hand-editing, so
+ * a non-finite value is treated as "no history" rather than propagated: `NaN`
+ * would make the builder's `i < from + count` false immediately and return an
+ * EMPTY window, silently disabling the fast path, while `Infinity` would make
+ * that same loop never terminate.
  */
 declare function windowSizeForCounter(counter: number): number;
 
@@ -4515,9 +4540,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 +4577,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 +4592,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;

package/dist/index.d.ts

@@ -240,8 +240,27 @@ declare function reserveSelfEphIndex(storage: NoteStorage): Promise<number>;
  * viewing public key. Registering the counterparty is a side effect worth
  * having: it makes the REVERSE direction cheap too, since their future payments
  * to this wallet become hash lookups instead of one trial ECDH per note.
+ *
+ * Returns `null` when this vault holds no history for that counterparty, and
+ * the caller must then use a random ephemeral. The reason is that "no history"
+ * has two causes this function cannot tell apart:
+ *
+ *   - a genuine first payment, where index 0 is correct;
+ *   - a counter that was LOST — a restored seed, a cleared IndexedDB, a wipe
+ *     and rescan — where index 0 was already published and re-deriving it
+ *     republishes that ephPk, linking the two notes in public.
+ *
+ * Unlike `selfEphCounter`, this one cannot be recovered: the index was
+ * published on a note encrypted toward someone else, so it never appears in
+ * this wallet's own scan, and asking a server whether a given ephPk exists
+ * would reveal which notes are ours. So the ambiguity is resolved the safe way
+ * — the caller degrades to random, costing the recipient one trial scan, and
+ * every later payment to the same counterparty takes the fast path again.
+ *
+ * The entry is still created: the NEXT payment has a counter, and registering
+ * the counterparty is what makes the reverse direction cheap.
  */
-declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number>;
+declare function reservePairwiseIndex(storage: NoteStorage, ivkHex: string): Promise<number | null>;
 
 /**
  * Turning a note into a stored record and back.
@@ -4495,7 +4514,13 @@ declare function resolveSelfEphCeiling(params: {
 /**
  * Discovery window size for the next scan, given the persisted counter: at least
  * the default, rounded up so every index the wallet may already have used (plus
- * the gap margin) falls inside the fast path.
+ * the gap margin) falls inside the fast path, and never past `MAX_EPH_WINDOW`.
+ *
+ * The counter is read from a config that survives restores and hand-editing, so
+ * a non-finite value is treated as "no history" rather than propagated: `NaN`
+ * would make the builder's `i < from + count` false immediately and return an
+ * EMPTY window, silently disabling the fast path, while `Infinity` would make
+ * that same loop never terminate.
  */
 declare function windowSizeForCounter(counter: number): number;
 
@@ -4515,9 +4540,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 +4577,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 +4592,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;

package/dist/index.js

@@ -5414,13 +5414,29 @@ function mergeCounters(current, fallback) {
     ...parties !== void 0 ? { pairwiseCounterparties: parties } : {}
   };
 }
-var higher = (a, b) => a === void 0 ? b : b === void 0 ? a : Math.max(a, b);
+var counterOrNone = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var higher = (a, b) => {
+  const x = counterOrNone(a);
+  const y = counterOrNone(b);
+  return x === void 0 ? y : y === void 0 ? x : Math.max(x, y);
+};
+function usableEntry(entry) {
+  if (typeof entry !== "object" || entry === null) return void 0;
+  const { nextIndex, addedAt } = entry;
+  const index = counterOrNone(nextIndex);
+  if (index === void 0) return void 0;
+  return { nextIndex: index, addedAt: counterOrNone(addedAt) ?? Date.now() };
+}
 function mergePairwise(current, fallback) {
   if (!current && !fallback) return void 0;
-  const merged = {
-    ...fallback ?? {}
-  };
-  for (const [key, entry] of Object.entries(current ?? {})) {
+  const merged = {};
+  for (const [key, entry] of Object.entries(fallback ?? {})) {
+    const usable = usableEntry(entry);
+    if (usable) merged[key] = usable;
+  }
+  for (const [key, raw] of Object.entries(current ?? {})) {
+    const entry = usableEntry(raw);
+    if (!entry) continue;
     const prev = merged[key];
     merged[key] = prev ? {
       nextIndex: Math.max(prev.nextIndex, entry.nextIndex),
@@ -5431,33 +5447,42 @@ function mergePairwise(current, fallback) {
 }
 
 // src/wallet/vault/storage/ephemeralIndex.ts
+var MAX_EPH_INDEX = 4294967294;
+function usableCounter(value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) return null;
+  if (value < 0 || value > MAX_EPH_INDEX) return null;
+  return value;
+}
 async function reserveSelfEphIndex(storage) {
   const updated = await storage.updateConfig((config) => ({
     ...config,
-    selfEphCounter: (config.selfEphCounter ?? 0) + 1,
+    selfEphCounter: (usableCounter(config.selfEphCounter) ?? 0) + 1,
     updatedAt: Date.now()
   }));
   if (!updated) throw new Error("vault not initialized");
-  return (updated.selfEphCounter ?? 1) - 1;
+  return (usableCounter(updated.selfEphCounter) ?? 1) - 1;
 }
 async function reservePairwiseIndex(storage, ivkHex) {
   const key = ivkHex.toLowerCase();
   const updated = await storage.updateConfig((config) => {
-    const current = config.pairwiseCounterparties?.[key];
+    const stored = usableCounter(config.pairwiseCounterparties?.[key]?.nextIndex);
+    const addedAt = config.pairwiseCounterparties?.[key]?.addedAt;
     return {
       ...config,
       pairwiseCounterparties: {
         ...config.pairwiseCounterparties,
         [key]: {
-          nextIndex: (current?.nextIndex ?? 0) + 1,
-          addedAt: current?.addedAt ?? Date.now()
+          nextIndex: (stored ?? 0) + 1,
+          addedAt: typeof addedAt === "number" ? addedAt : Date.now()
         }
       },
       updatedAt: Date.now()
     };
   });
   if (!updated) throw new Error("vault not initialized");
-  return (updated.pairwiseCounterparties?.[key]?.nextIndex ?? 1) - 1;
+  const nextIndex = usableCounter(updated.pairwiseCounterparties?.[key]?.nextIndex);
+  if (nextIndex === null || nextIndex <= 1) return null;
+  return nextIndex - 1;
 }
 
 // src/wallet/vault/notes/record.ts
@@ -5880,6 +5905,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 = [];
@@ -5927,6 +5953,24 @@ async function processHints(ctx, hints, total) {
   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);
@@ -5939,27 +5983,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 { onBatchDone } = params;
+  const { source, sinceLeafIndex, signal } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -5977,14 +6030,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,
-    onBatchDone
+    onPage: params.onPage,
+    onBatchDone: params.onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -5995,33 +6048,7 @@ 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;
 }
 
@@ -6233,7 +6260,7 @@ function gapMargin(windowSize) {
 }
 function resolveSelfEphCeiling(params) {
   const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
-  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
+  const windowSize = params.windowSize !== void 0 && params.windowSize > 0 ? params.windowSize : SELF_EPH_WINDOW;
   if (scanMaxIndex === null) return null;
   if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
   const ownEphPks = /* @__PURE__ */ new Set();
@@ -6258,9 +6285,12 @@ function resolveSelfEphCeiling(params) {
   }
   return max;
 }
+var MAX_EPH_WINDOW = SELF_EPH_WINDOW * 64;
 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);
+  const used = Number.isFinite(counter) ? counter : 0;
+  const needed = used + gapMargin(SELF_EPH_WINDOW);
+  const rounded = Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW;
+  return Math.min(MAX_EPH_WINDOW, Math.max(SELF_EPH_WINDOW, rounded));
 }
 
 // src/wallet/scanner/phases/spentStatus.ts
@@ -6518,11 +6548,13 @@ async function buildZkNote(params, deps) {
   } else if (params.viewingPublicKey && storage && keys.viewingSecretKey) {
     try {
       const index = await reservePairwiseIndex(storage, toHex(params.viewingPublicKey));
-      const pairSecret = derivePairwiseSharedSecret(
-        keys.viewingSecretKey,
-        params.viewingPublicKey
-      );
-      ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      if (index !== null) {
+        const pairSecret = derivePairwiseSharedSecret(
+          keys.viewingSecretKey,
+          params.viewingPublicKey
+        );
+        ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      }
     } catch {
     }
   }

package/dist/index.mjs

@@ -4188,13 +4188,29 @@ function mergeCounters(current, fallback) {
     ...parties !== void 0 ? { pairwiseCounterparties: parties } : {}
   };
 }
-var higher = (a, b) => a === void 0 ? b : b === void 0 ? a : Math.max(a, b);
+var counterOrNone = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+var higher = (a, b) => {
+  const x = counterOrNone(a);
+  const y = counterOrNone(b);
+  return x === void 0 ? y : y === void 0 ? x : Math.max(x, y);
+};
+function usableEntry(entry) {
+  if (typeof entry !== "object" || entry === null) return void 0;
+  const { nextIndex, addedAt } = entry;
+  const index = counterOrNone(nextIndex);
+  if (index === void 0) return void 0;
+  return { nextIndex: index, addedAt: counterOrNone(addedAt) ?? Date.now() };
+}
 function mergePairwise(current, fallback) {
   if (!current && !fallback) return void 0;
-  const merged = {
-    ...fallback ?? {}
-  };
-  for (const [key, entry] of Object.entries(current ?? {})) {
+  const merged = {};
+  for (const [key, entry] of Object.entries(fallback ?? {})) {
+    const usable = usableEntry(entry);
+    if (usable) merged[key] = usable;
+  }
+  for (const [key, raw] of Object.entries(current ?? {})) {
+    const entry = usableEntry(raw);
+    if (!entry) continue;
     const prev = merged[key];
     merged[key] = prev ? {
       nextIndex: Math.max(prev.nextIndex, entry.nextIndex),
@@ -4205,33 +4221,42 @@ function mergePairwise(current, fallback) {
 }
 
 // src/wallet/vault/storage/ephemeralIndex.ts
+var MAX_EPH_INDEX = 4294967294;
+function usableCounter(value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) return null;
+  if (value < 0 || value > MAX_EPH_INDEX) return null;
+  return value;
+}
 async function reserveSelfEphIndex(storage) {
   const updated = await storage.updateConfig((config) => ({
     ...config,
-    selfEphCounter: (config.selfEphCounter ?? 0) + 1,
+    selfEphCounter: (usableCounter(config.selfEphCounter) ?? 0) + 1,
     updatedAt: Date.now()
   }));
   if (!updated) throw new Error("vault not initialized");
-  return (updated.selfEphCounter ?? 1) - 1;
+  return (usableCounter(updated.selfEphCounter) ?? 1) - 1;
 }
 async function reservePairwiseIndex(storage, ivkHex) {
   const key = ivkHex.toLowerCase();
   const updated = await storage.updateConfig((config) => {
-    const current = config.pairwiseCounterparties?.[key];
+    const stored = usableCounter(config.pairwiseCounterparties?.[key]?.nextIndex);
+    const addedAt = config.pairwiseCounterparties?.[key]?.addedAt;
     return {
       ...config,
       pairwiseCounterparties: {
         ...config.pairwiseCounterparties,
         [key]: {
-          nextIndex: (current?.nextIndex ?? 0) + 1,
-          addedAt: current?.addedAt ?? Date.now()
+          nextIndex: (stored ?? 0) + 1,
+          addedAt: typeof addedAt === "number" ? addedAt : Date.now()
         }
       },
       updatedAt: Date.now()
     };
   });
   if (!updated) throw new Error("vault not initialized");
-  return (updated.pairwiseCounterparties?.[key]?.nextIndex ?? 1) - 1;
+  const nextIndex = usableCounter(updated.pairwiseCounterparties?.[key]?.nextIndex);
+  if (nextIndex === null || nextIndex <= 1) return null;
+  return nextIndex - 1;
 }
 
 // src/wallet/vault/notes/record.ts
@@ -4654,6 +4679,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 = [];
@@ -4701,6 +4727,24 @@ async function processHints(ctx, hints, total) {
   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);
@@ -4713,27 +4757,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 { onBatchDone } = params;
+  const { source, sinceLeafIndex, signal } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -4751,14 +4804,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,
-    onBatchDone
+    onPage: params.onPage,
+    onBatchDone: params.onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -4769,33 +4822,7 @@ 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;
 }
 
@@ -4996,7 +5023,7 @@ function gapMargin(windowSize) {
 }
 function resolveSelfEphCeiling(params) {
   const { notes, spendingKey, viewingKey, scanMaxIndex } = params;
-  const windowSize = params.windowSize ?? SELF_EPH_WINDOW;
+  const windowSize = params.windowSize !== void 0 && params.windowSize > 0 ? params.windowSize : SELF_EPH_WINDOW;
   if (scanMaxIndex === null) return null;
   if (scanMaxIndex < windowSize - gapMargin(windowSize)) return scanMaxIndex;
   const ownEphPks = /* @__PURE__ */ new Set();
@@ -5021,9 +5048,12 @@ function resolveSelfEphCeiling(params) {
   }
   return max;
 }
+var MAX_EPH_WINDOW = SELF_EPH_WINDOW * 64;
 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);
+  const used = Number.isFinite(counter) ? counter : 0;
+  const needed = used + gapMargin(SELF_EPH_WINDOW);
+  const rounded = Math.ceil(needed / SELF_EPH_WINDOW) * SELF_EPH_WINDOW;
+  return Math.min(MAX_EPH_WINDOW, Math.max(SELF_EPH_WINDOW, rounded));
 }
 
 // src/wallet/scanner/phases/spentStatus.ts
@@ -5281,11 +5311,13 @@ async function buildZkNote(params, deps) {
   } else if (params.viewingPublicKey && storage && keys.viewingSecretKey) {
     try {
       const index = await reservePairwiseIndex(storage, toHex(params.viewingPublicKey));
-      const pairSecret = derivePairwiseSharedSecret(
-        keys.viewingSecretKey,
-        params.viewingPublicKey
-      );
-      ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      if (index !== null) {
+        const pairSecret = derivePairwiseSharedSecret(
+          keys.viewingSecretKey,
+          params.viewingPublicKey
+        );
+        ephSkOverride = derivePairwiseEphSk(pairSecret, index);
+      }
     } catch {
     }
   }

package/package.json

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