@orbinum/sdk 1.3.0 → 1.3.1

package/dist/index.d.mts

@@ -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;

package/dist/index.d.ts

@@ -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;

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 = [];
@@ -5927,6 +5928,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 +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 { onBatchDone } = params;
+  const { source, sinceLeafIndex, signal } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -5977,14 +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,
-    onBatchDone
+    onPage: params.onPage,
+    onBatchDone: params.onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -5995,33 +6023,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;
 }
 

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 = [];
@@ -4701,6 +4702,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 +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 { onBatchDone } = params;
+  const { source, sinceLeafIndex, signal } = params;
   if (signal?.aborted) throw scanAbortError();
   const outcome = {
     scanEntries: [],
@@ -4751,14 +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,
-    onBatchDone
+    onPage: params.onPage,
+    onBatchDone: params.onBatchDone
   };
   let tailSince = sinceLeafIndex;
   try {
@@ -4769,33 +4797,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;
 }
 

package/package.json

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