@ninsei-labs/sdk 0.51.0 → 0.51.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.51.1 — 2026-10-22
+
+A BUSY NODE NO LONGER ENDS A WITHDRAWAL, AND MISSING HEIGHT DATA HAS A NAME.
+
+- `windowTxHashes` retries a `429`, a timeout and a `5xx` with `Retry-After` or exponential backoff; only a read that
+  still fails reaches the fallback.
+- `restoreWallet` runs the full scan when the window cannot be read and reports `window.fallback: true`,
+  `fallbackWhy: "window-read"` and the node's status. A malformed window is still a caller error, not a fallback.
+- A null settlement block time is `no-block-time`, not timestamp 0. An unreachable Monero node
+  (`monero-nodes-unreachable`) and a reachable node on another network (`monero-network-mismatch`) no longer share
+  `no-height-readers`.
+- `recoveryIndexTaken` is exported from `@ninsei-labs/sdk/recovery`.
+- The on-chain recovery-number check starts at the registry's escrow deployment block, not block 0; an explicit
+  `fromBlock` still wins.
+
 ## 0.51.0 — 2026-10-22
 
 THE WITHDRAWAL AND THE ON-CHAIN SEARCH NOW CARRY EVERYTHING THE KEY CAN KNOW.

package/README.md

@@ -173,6 +173,16 @@ When a token is needed, the order can be joined with an off-chain quote record b
 would have to put the token into the signed quote and the clone (and therefore a new order format and factory); only
 then can `findSwaps` return it from the chain and set `payTokenReason` to something other than `not-on-chain`.
 
+The found order also carries the Monero start height and the reason it is absent. `no-block-time`,
+`monero-nodes-unreachable` and `monero-network-mismatch` are different answers: a missing settlement timestamp is not
+a dead node, and a node on another network is not an absent reader. A page that starts swaps without the SDK's start
+path can call `recoveryIndexTaken` from `./recovery` before using a number; it checks the factory's `OrderCreated`
+logs from the registry's deployment block.
+
+The withdrawal window retries a `429`, a timeout or a `5xx` before it gives up. If the window still cannot be read,
+`restoreWallet` falls back to the full scan and reports `window.fallback: true` with `fallbackWhy: "window-read"` and
+the node's status; a withdrawal is not refused because the node was busy.
+
 ## Extending to other networks (Tron, Solana and beyond)
 
 The package name is deliberately common: the shared part — the quote client, the Monero leg, the state machine,

package/index.d.ts

@@ -1140,6 +1140,9 @@ export interface StartRequest {
   recoveryKey?: string | { readonly mnemonic: string };
   /** The swap number, when the caller already reserved one. Absent - the SDK reserves the next free number. */
   recoveryIndex?: number;
+  /** The first block for the on-chain number check. Absent - the chain registry's escrow deployment block, and
+   * zero only when the registry has no height. */
+  fromBlock?: string | number;
   /** The Monero height the swap starts at. Absent - the SDK asks the configured nodes (`get_info`) and refuses
    * the start if none answers on the swap's network. */
   restoreHeight?: number;
@@ -1328,8 +1331,9 @@ export interface SweepRestoreRequest {
   readonly rescanWhenLocked?: boolean;
   /**
    * THE BLOCK WINDOW AROUND THE LOCK. When present, the wallet is set at the node tip and only these blocks are
-   * scanned. An empty window falls back to the full scan unless `fallback` is false. `txHashes` may be supplied by
-   * the caller; otherwise the SDK reads `get_block` from `nodeUrl`.
+   * scanned. An empty window falls back to the full scan unless `fallback` is false. A window read that fails
+   * (429, timeout, 5xx) is retried; if it still fails, the full scan runs and `fallbackWhy` names the read.
+   * `txHashes` may be supplied by the caller; otherwise the SDK reads `get_block` from `nodeUrl`.
    */
   readonly window?: {
     readonly nodeUrl?: string;
@@ -1357,8 +1361,18 @@ export interface SweepRestoreResult {
   /** Present when a window was requested: whether it was used, and why it was skipped. */
   readonly window?: {
     readonly used: boolean;
-    /** Whether the full scan ran because the window found nothing (or could not scan). */
+    /** Whether the full scan ran because the window found nothing, could not scan, or could not be read. */
     readonly fallback: boolean;
+    /** Why the fallback ran: `empty-window`, `window-read`, or a named skip. */
+    readonly fallbackWhy?: string;
+    /** The node's answer when the window read failed; absent when the window was read. */
+    readonly error?: {
+      readonly code: string;
+      readonly surface: string;
+      readonly status: number | null;
+      readonly height: number | null;
+      readonly why: string | null;
+    };
     readonly skipped: string | null;
     readonly fromHeight: number;
     readonly toHeight: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.51.0",
+  "version": "0.51.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/public/recovery.d.ts

@@ -342,7 +342,7 @@ export interface FoundSwap {
   /** The Monero height a withdrawal may start from, derived from the order's block time. Null when the caller did
    * not pass the readers; `startHeightReason` then names why. */
   readonly startHeight: number | null;
-  readonly startHeightReason: "no-block-number" | "no-height-readers" | "no-block-time" | "monero-header" | null;
+  readonly startHeightReason: "no-block-number" | "no-height-readers" | "monero-nodes-unreachable" | "monero-network-mismatch" | "no-block-time" | "monero-header" | null;
 }
 
 /** A storage adapter: the same shape the SDK store takes. */
@@ -376,6 +376,17 @@ export declare function saveRecoveryKey(storage: RecoveryKeyStorage, key: Recove
 export declare function loadRecoveryKey(storage: RecoveryKeyStorage): (RecoveryKey & { nextIndex: number; reserved: Record<string, unknown>; retired: Record<string, unknown> }) | null;
 /** Reserves a swap number; the caller releases it if the request is abandoned. */
 export declare function reserveRecoveryIndex(storage: RecoveryKeyStorage, request: { chainId: number; swapId?: string | null }): number;
+/** True when an order already holds this number's commitment on chain. A page that starts swaps without the SDK's
+ * start path calls this before using a number; an unreadable log is a refusal, not "free". */
+export declare function recoveryIndexTaken(request: {
+  mnemonic: string;
+  chainId: number;
+  index: number;
+  factory: string;
+  evmLogs: (request: { address: string; topics: (string | null)[]; fromBlock: number | string; toBlock: number | string }) => Promise<unknown[]>;
+  fromBlock?: number | string;
+  toBlock?: number | string;
+}): Promise<boolean>;
 /** Releases a number that never reached the chain. */
 export declare function releaseRecoveryIndex(storage: RecoveryKeyStorage, index: number): void;
 /** Retires a number after its order exists on chain. */

package/src/public/recovery.mjs

@@ -41,6 +41,7 @@ export {
   loadRecoveryKey,
   openRecoveryKeyFile,
   recoveryBinding,
+  recoveryIndexTaken,
   recoveryKeyFileName,
   recoveryKeyText,
   releaseRecoveryIndex,

package/src/recovery-key.mjs

@@ -446,6 +446,9 @@ export async function recoveryIndexTaken({ mnemonic, chainId, index, factory, ev
 const MONERO_HEIGHT_SAFETY_BLOCKS = 60;
 
 function secondsOf(value) {
+  // A MISSING BLOCK TIME IS NOT 1970. `Number(null)` is 0, so a reader that answered null used to place an order
+  // at the epoch and derive a Monero height from it. Null means "not read": the caller names no-block-time.
+  if (value === null || value === undefined) return null;
   const n = Number(value);
   if (!Number.isFinite(n) || n < 0) return null;
   return n > 1e12 ? Math.floor(n / 1000) : Math.floor(n);
@@ -477,13 +480,18 @@ async function heightAtOrBefore(timestamp, { tip, headerTimestamp }) {
 async function moneroReadersFromNodes({ nodes = [], network = null, fetchImpl = globalThis.fetch } = {}) {
   const urls = (Array.isArray(nodes) ? nodes : [])
     .map((entry) => typeof entry === "string" ? entry : entry && entry.url).filter(Boolean);
-  if (!urls.length) return null;
+  if (!urls.length) return { readers: null, reason: "no-height-readers" };
   const answers = await Promise.all(urls.map(async (url) => {
     try { return { ...(await probeMoneroNode({ url, fetchImpl })), url }; }
     catch { return { ok: false, why: "unreachable", url }; }
   }));
   const node = answers.find((answer) => answer.ok === true && (!network || answer.network === network));
-  if (!node) return null;
+  if (!node) {
+    // TWO DIFFERENT FAILURES, TWO DIFFERENT REASONS. A node that answered but runs another network is not the
+    // same as no node answering at all; a page must be able to tell the person which one to fix.
+    const answered = answers.some((answer) => answer.ok === true);
+    return { readers: null, reason: answered ? "monero-network-mismatch" : "monero-nodes-unreachable" };
+  }
   const call = async (method, params) => {
     let response;
     try {
@@ -500,27 +508,30 @@ async function moneroReadersFromNodes({ nodes = [], network = null, fetchImpl =
     return body.result;
   };
   return {
-    // `get_info.height` is the block COUNT, one past the top block. Asking a real node for a header at that height
-    // answers "greater than current top block"; the tip reader must name the top block itself.
-    tip: async () => Math.max(0, Number(node.height) - 1),
-    headerTimestamp: async (height) => {
-      const result = await call("get_block_header_by_height", { height });
-      const ts = Number(result.block_header && result.block_header.timestamp);
-      // GENESIS HAS TIMESTAMP 0. The binary search reads height 0 to prove the requested moment is before it; a
-      // `<= 0` refusal turned a legitimate genesis answer into "monero-header" and every old order lost its height.
-      if (!Number.isFinite(ts) || ts < 0) throw new Error("monero-header");
-      return ts;
+    reason: null,
+    readers: {
+      // `get_info.height` is the block COUNT, one past the top block. Asking a real node for a header at that height
+      // answers "greater than current top block"; the tip reader must name the top block itself.
+      tip: async () => Math.max(0, Number(node.height) - 1),
+      headerTimestamp: async (height) => {
+        const result = await call("get_block_header_by_height", { height });
+        const ts = Number(result.block_header && result.block_header.timestamp);
+        // GENESIS HAS TIMESTAMP 0. The binary search reads height 0 to prove the requested moment is before it; a
+        // `<= 0` refusal turned a legitimate genesis answer into "monero-header" and every old order lost its height.
+        if (!Number.isFinite(ts) || ts < 0) throw new Error("monero-header");
+        return ts;
+      },
     },
   };
 }
 
-async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBlockTimestamp, cache }) {
+async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBlockTimestamp, cache, readersReason = "no-height-readers" }) {
   if (order.blockNumber === null || order.blockNumber === undefined) {
     return { startHeight: null, startHeightReason: "no-block-number", blockTime: null };
   }
   // NOTHING TO READ WITH: no settlement block time and no Monero readers. That is a missing seam, not a missing date.
   if (typeof evmBlockTime !== "function" && typeof moneroTip !== "function" && typeof moneroBlockTimestamp !== "function") {
-    return { startHeight: null, startHeightReason: "no-height-readers", blockTime: null };
+    return { startHeight: null, startHeightReason: readersReason || "no-height-readers", blockTime: null };
   }
   // THE BLOCK TIME IS PART OF THE FOUND ORDER. The page used to read the block again just to show a date; the
   // timestamp is already needed here for the Monero height, so it is returned with it.
@@ -531,7 +542,7 @@ async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBloc
     cache.set(order.blockNumber, timestamp);
   }
   if (typeof moneroTip !== "function" || typeof moneroBlockTimestamp !== "function") {
-    return { startHeight: null, startHeightReason: "no-height-readers", blockTime: timestamp };
+    return { startHeight: null, startHeightReason: readersReason || "no-height-readers", blockTime: timestamp };
   }
   try {
     const height = await heightAtOrBefore(timestamp, { tip: moneroTip, headerTimestamp: moneroBlockTimestamp });
@@ -608,9 +619,11 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
   const cache = new Map();
   let tip = moneroTip;
   let header = moneroBlockTimestamp;
+  let readersReason = "no-height-readers";
   if ((typeof tip !== "function" || typeof header !== "function") && Array.isArray(xmrNodes) && xmrNodes.length) {
-    const readers = await moneroReadersFromNodes({ nodes: xmrNodes, network: moneroNetwork, fetchImpl });
-    if (readers) { tip = tip || readers.tip; header = header || readers.headerTimestamp; }
+    const probed = await moneroReadersFromNodes({ nodes: xmrNodes, network: moneroNetwork, fetchImpl });
+    if (probed.readers) { tip = tip || probed.readers.tip; header = header || probed.readers.headerTimestamp; }
+    else readersReason = probed.reason || "no-height-readers";
   }
   // THE ORDER IS NATIVE, AND THE PAYING TOKEN IS NOT ON THE CHAIN. The escrow receives the settlement network's
   // native coin (`amount` is wei); which token the person swapped into it (USDC, USDT, ...) belongs to the DEX/quote
@@ -622,7 +635,7 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
     order.payTokenReason = "not-on-chain";
   }
   for (const order of found) {
-    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip: tip, moneroBlockTimestamp: header, cache }));
+    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip: tip, moneroBlockTimestamp: header, cache, readersReason }));
   }
   // THE XMR AMOUNT IS IN THE CLONE, NOT IN THE LOG. A caller without a code reader gets null and a named reason;
   // an unreadable or differently-shaped contract does the same. This is data, not a withdrawal verdict.

package/src/swaps.mjs

@@ -811,9 +811,18 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         // log is asked before the number is used; a taken number is retired locally and the next one is reserved.
         // Without a log seam the previous behaviour is kept - the caller cannot be asked to invent a chain read.
         if (typeof chainLogs === "function" && request.order.factory) {
+          // THE CHAIN'S BIRTH HEIGHT IS THE DEFAULT START, NOT ZERO. The factory's own log cannot hold an order
+          // before it existed; asking from zero is tens of log queries per number on a public RPC. An explicit
+          // `fromBlock` still wins, including the literal zero.
+          const chain = config && Array.isArray(config.chains)
+            ? config.chains.find((entry) => Number(entry.chainId) === Number(chainId)) : null;
+          const deploymentBlock = chain && chain.escrow ? chain.escrow.deploymentBlock : null;
+          const fromBlock = request.fromBlock !== undefined
+            ? request.fromBlock
+            : (Number.isSafeInteger(deploymentBlock) ? deploymentBlock : 0);
           let hops = 0;
           while (await recoveryIndexTaken({ mnemonic: key.mnemonic, chainId, index, factory: request.order.factory,
-            evmLogs: chainLogs, fromBlock: request.fromBlock === undefined ? 0 : request.fromBlock })) {
+            evmLogs: chainLogs, fromBlock })) {
             if (explicit) throw new SdkError("bad-input", { field: "recoveryIndex", why: "on-chain" });
             commitRecoveryIndex(storage, index);
             index = reserveRecoveryIndex(storage, { chainId });

package/src/sweep-restore.mjs

@@ -64,7 +64,7 @@ const heightOf = async (driver, name) => {
 
 // THE BLOCK WINDOW AROUND THE LOCK. A full rescan of mainnet takes hours; the lock can only be in the blocks from
 // the order's start to just after its t1. The caller may pass the hashes, or a node URL and the SDK asks for them.
-export async function windowTxHashes({ nodeUrl, fromHeight, toHeight, fetchImpl = globalThis.fetch } = {}) {
+export async function windowTxHashes({ nodeUrl, fromHeight, toHeight, fetchImpl = globalThis.fetch, sleep = defaultSleep, attempts = 3 } = {}) {
   let base = typeof nodeUrl === "string" ? nodeUrl.trim() : "";
   while (base.endsWith("/")) base = base.slice(0, -1);
   const from = Number(fromHeight);
@@ -73,17 +73,39 @@ export async function windowTxHashes({ nodeUrl, fromHeight, toHeight, fetchImpl
   if (!Number.isSafeInteger(from) || from < 0) throw new SdkError("bad-input", { field: "window.fromHeight" });
   if (!Number.isSafeInteger(to) || to < from) throw new SdkError("bad-input", { field: "window.toHeight" });
   if (typeof fetchImpl !== "function") throw new SdkError("bad-input", { field: "fetchImpl" });
+  const tries = Math.max(1, Math.min(5, Number(attempts) || 3));
   const hashes = [];
   for (let height = from; height <= to; height += 1) {
-    let response;
-    try {
-      response = await fetchImpl(base + "/json_rpc", {
-        method: "POST", headers: { "content-type": "application/json" },
-        body: JSON.stringify({ jsonrpc: "2.0", id: "block", method: "get_block", params: { height } }),
-        signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
-      });
-    } catch { throw new SdkError("wallet-rejected", { surface: "window-blocks", height }); }
-    if (!response || response.ok !== true) throw new SdkError("wallet-rejected", { surface: "window-blocks", height, status: response ? response.status : null });
+    let response = null;
+    let last = null;
+    for (let attempt = 1; attempt <= tries; attempt += 1) {
+      try {
+        response = await fetchImpl(base + "/json_rpc", {
+          method: "POST", headers: { "content-type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", id: "block", method: "get_block", params: { height } }),
+          signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
+        });
+      } catch {
+        // A TIMEOUT OR A BROKEN CONNECTION IS RETRIED, NOT THE END OF THE WINDOW. The node is rate-limited by the
+        // same bursts the page sends; a withdrawal that stops on the first 429 or timeout is a refund waiting to
+        // happen (the page's measured failure: 93 of 150 parallel reads answered 429).
+        response = null;
+        last = new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "transport" });
+        if (attempt < tries) { await sleep(backoffMs(attempt)); continue; }
+        throw last;
+      }
+      if (response && response.ok === true) { last = null; break; }
+      const status = response ? response.status : null;
+      last = new SdkError("wallet-rejected", { surface: "window-blocks", height, status });
+      // ONLY A RATE LIMIT AND A SERVER FAULT ARE WORTH ANOTHER READ. A 404 or a bad request will answer the same
+      // way every time, and retrying it only makes the fallback slower.
+      if ((status === 429 || (status !== null && status >= 500)) && attempt < tries) {
+        await sleep(retryAfterMs(response) ?? backoffMs(attempt));
+        continue;
+      }
+      throw last;
+    }
+    if (!response || response.ok !== true) throw last || new SdkError("wallet-rejected", { surface: "window-blocks", height });
     let body = null;
     try { body = await response.json(); } catch { throw new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "not-json" }); }
     if (!body || body.error || !body.result) throw new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "rpc" });
@@ -101,6 +123,21 @@ export async function windowTxHashes({ nodeUrl, fromHeight, toHeight, fetchImpl
   return hashes;
 }
 
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const backoffMs = (attempt) => Math.min(4000, 250 * (2 ** Math.max(0, attempt - 1)));
+function retryAfterMs(response) {
+  try {
+    const value = response && response.headers && typeof response.headers.get === "function"
+      ? response.headers.get("retry-after") : null;
+    if (value === null || value === undefined || value === "") return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.min(5000, Math.floor(seconds * 1000));
+    const date = Date.parse(String(value));
+    if (Number.isFinite(date)) return Math.min(5000, Math.max(0, date - Date.now()));
+  } catch { /* a bad header is not a reason to stop */ }
+  return null;
+}
+
 /**
  * Restore the wallet from a height and report what it holds.
  *
@@ -136,14 +173,34 @@ export async function restoreWallet(request = {}) {
   if (requestWindow) {
     const tipHeight = Number(requestWindow.tipHeight);
     if (!Number.isSafeInteger(tipHeight) || tipHeight <= 0) throw new SdkError("bad-input", { field: "window.tipHeight" });
+    windowReport = { used: false, skipped: null, fallback: false, fromHeight, toHeight: Number(requestWindow.toHeight),
+      blocks: Math.max(0, Number(requestWindow.toHeight) - fromHeight + 1), txs: 0 };
     let hashes = Array.isArray(requestWindow.txHashes) ? requestWindow.txHashes.map(String) : null;
     if (hashes === null) {
-      hashes = await windowTxHashes({
-        nodeUrl: requestWindow.nodeUrl, fromHeight, toHeight: requestWindow.toHeight, fetchImpl: request.fetchImpl,
-      });
+      try {
+        hashes = await windowTxHashes({
+          nodeUrl: requestWindow.nodeUrl, fromHeight, toHeight: requestWindow.toHeight, fetchImpl: request.fetchImpl,
+        });
+      } catch (e) {
+        // A MALFORMED WINDOW IS NOT A BUSY NODE. A bad height or a missing URL is the caller's error and is
+        // rethrown; only a read the node refused reaches the fallback.
+        if (e && e.code === "bad-input") throw e;
+        // THE WINDOW READ FAILED: FALL BACK TO THE FULL SCAN, NOT TO A REFUSAL. A 429 from a busy node, a timeout
+        // or a 5xx is a fact about the node, not about the coins; the scan below can still find them. The reason is
+        // carried on the report so the caller does not present this as a normal empty window.
+        windowReport.fallback = true;
+        windowReport.fallbackWhy = "window-read";
+        windowReport.error = {
+          code: e && e.code ? e.code : "wallet-rejected",
+          surface: e && e.params && e.params.surface ? e.params.surface : "window-blocks",
+          status: e && e.params && e.params.status !== undefined ? e.params.status : null,
+          height: e && e.params && e.params.height !== undefined ? e.params.height : null,
+          why: e && e.params && e.params.why ? e.params.why : null,
+        };
+        hashes = [];
+      }
     }
-    windowReport = { used: false, skipped: null, fallback: false, fromHeight, toHeight: Number(requestWindow.toHeight),
-      blocks: Math.max(0, Number(requestWindow.toHeight) - fromHeight + 1), txs: hashes.length };
+    windowReport.txs = hashes.length;
     if (hashes.length && typeof driver.scanTxs === "function") {
       await step("setRestoreHeight", () => driver.setRestoreHeight(tipHeight));
       await step("scanTxs", () => driver.scanTxs(hashes));
@@ -194,7 +251,10 @@ export async function restoreWallet(request = {}) {
 
   // THE WINDOW DID NOT ANSWER: the full scan below is the fallback. Say so on the report, so the caller does not
   // have to infer it from `used: false` and a balance.
-  if (windowReport) windowReport.fallback = true;
+  if (windowReport) {
+    windowReport.fallback = true;
+    if (!windowReport.fallbackWhy) windowReport.fallbackWhy = "empty-window";
+  }
   await step("setRestoreHeight", () => driver.setRestoreHeight(scanHeight));
   // A RESCAN IS REQUIRED, NOT OPTIONAL: without it the height only applies to a wallet that has not scanned yet,
   // and a wallet restored from a key has. A driver that cannot rescan is the caller's mistake, named here.

package/src/version.mjs

@@ -6,4 +6,4 @@
 // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
 // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
 
-export const SDK_VERSION = "0.51.0";
+export const SDK_VERSION = "0.51.1";