@ninsei-labs/sdk 0.51.0 → 0.51.2

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 0.51.2 — 2026-10-22
+
+- The withdrawal window falls back to the full scan when `scanTxs` or the balance read fails, and reports
+  `window.fallbackWhy: "window-scan"`.
+- The SDK does not call a backend by default: the `/api/swaps` lookups, the `swept` report, the session calls and the
+  relative `apiBase` default are gone. A caller that needs a backend passes its base explicitly; a watch without
+  `verify` data is a named `no-backend` refusal.
+
+## 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

@@ -44,7 +44,7 @@ import { createNinsei } from "@ninsei-labs/sdk";
 const sdk = createNinsei({
   settlement: { chain: "arbitrum-sepolia" },  // from sdk.config.chains; vm is taken from the registry
   xmrNetwork: "stagenet",
-  apiBase: "/api",
+  // apiBase: "https://your-service",   // only when you bring a backend; there is no default
   assetsBase: "/sdk/",
   mode: "live",                     // or "sim"
 });
@@ -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/engine/core/chainSource.js

@@ -67,6 +67,7 @@ export function pollInterval() {
 // see the reason, not a blank page.
 async function api(path, { method = "GET", body, base, timeoutMs = API.timeoutMs, fetchImpl } = {}) {
   const target = base || apiBaseOverride || API.base;
+  if (!target) return { ok: false, status: 0, error: "no backend base configured" };
   const doFetch = fetchImpl || globalThis.fetch;
   if (typeof doFetch !== "function") return { ok: false, status: 0, error: "no fetch: backend unavailable" };
   const ctl = typeof AbortController === "function" ? new AbortController() : null;
@@ -142,66 +143,9 @@ export function sameSwapTarget(a, b) {
     a.chain === b.chain;
 }
 
-export async function openSession({ swapId, share, expectedAmountXmr, chain, restoreHeight }, opts = {}) {
-  const src = share || {};
-  const address = src.address || null;
-  const viewKey = src.viewKey || src.privateViewKey || null;
-  if (!address || !viewKey) {
-    return { ok: false, status: 0, error: "the watch-only share has no address/viewKey - nothing to send to the backend" };
-  }
-  // THE EXPECTED AMOUNT IS MANDATORY and must be a number. Before, a non-number meant no field, and the swap
-  // was created WITHOUT an amount: any arrival was accepted as enough, so an underpayment looked like a done
-  // deal. Now it is a refusal with an explanation.
-  const amountXmr = Number(expectedAmountXmr);
-  if (!Number.isFinite(amountXmr) || amountXmr <= 0) {
-    const where = (new Error("caller").stack || "").split("\n").slice(1, 4).map((x) => x.trim().split("/").pop()).join(" <- ");
-    console.warn("[chainSource] no expected amount, call from: " + where);
-    return { ok: false, status: 0, error: "the expected XMR amount is unknown (" + String(expectedAmountXmr) + "): without it no watch is created" };
-  }
-  const wanted = {
-    swapId: swapId || src.swapId || null,
-    network: src.network || xmrNetworkForSource(),
-    address,
-    viewKey,
-    expectedAmountXmr: amountXmr,
-    restoreHeight: Number.isFinite(Number(restoreHeight)) && Number(restoreHeight) > 0 ? Number(restoreHeight) : Number(src.restoreHeight) || undefined,
-    chain: chain || undefined,
-  };
-  // The body is rebuilt from the allowlist: what is not in the list never reaches the request.
-  const body = {};
-  for (const field of ALLOWED_SESSION_FIELDS) {
-    if (wanted[field] !== undefined && wanted[field] !== null) body[field] = wanted[field];
-  }
-  const res = await api("/swaps", { method: "POST", body, ...opts });
-  if (!res.ok) return res;
-  return { ok: true, status: res.status, created: res.json?.created !== false, session: normalizeSession(res.json) };
-}
-
-export async function fetchSession(swapId, opts = {}) {
-  const res = await api(`/swaps/${encodeURIComponent(swapId)}`, opts);
-  if (!res.ok) return res;
-  return { ok: true, status: res.status, session: normalizeSession(res.json) };
-}
-
-// Tell the backend the XMR was withdrawn (the hash of the real transfer). Needed because a watch-only wallet
-// cannot see outgoing transfers.
-export async function reportSwept(swapId, txid, opts = {}) {
-  const res = await api(`/swaps/${encodeURIComponent(swapId)}/swept`, { method: "POST", body: { txid }, ...opts });
-  return res.ok ? { ok: true, status: res.status, session: normalizeSession(res.json) } : res;
-}
-
-// Close the swap (cancel or refund on the backend): the watch stops.
-export async function closeSession(swapId, reason = "cancelled", opts = {}) {
-  const res = await api(`/swaps/${encodeURIComponent(swapId)}/closed`, { method: "POST", body: { reason }, ...opts });
-  return res.ok ? { ok: true, status: res.status, session: normalizeSession(res.json) } : res;
-}
-
-// Backend state: is it up and does it see the wallet. The screen needs this to show 'backend unavailable'
-// before the user sends money, not after.
-export async function health(opts = {}) {
-  const res = await api("/health", opts);
-  return res.ok ? { ok: true, ...res.json } : res;
-}
+// NO SESSION CALLS. The swap engine no longer creates a watch on a backend: the address and the view key are not
+// sent to the page's own host, and the SDK does not poll a session for the Monero leg. A caller that needs a
+// backend later passes its base explicitly, outside these rules.
 
 // ---------------------------------------------------------------------------
 // The Monero-leg snapshot for the state engine

package/engine/core/config.js

@@ -908,14 +908,17 @@ export const MONERO = {
 };
 
 // ---------------------------------------------------------------------------
-// The backend (app/): swap sessions and watching the Monero leg.
+// A backend is OPTIONAL (app/): the SDK does not point requests at the page's own origin.
 //
-// The API lives on the same domain at /api/ (Angie proxies to 127.0.0.1:8787), so CSP needs no edit - connect-src
-// 'self' covers it. Locally the same path is served with an --api flag - also without touching the policy.
+// A caller that needs one passes `apiBase` explicitly; without it the swap engine watches the chain and the maker,
+// not a service. The legacy session calls were removed for that reason.
 // ---------------------------------------------------------------------------
 export const API = {
-  base: "/api",
-  // The Monero-leg source: 'app' - the real backend over HTTP, 'mock' - the demo simulator with no network.
+  // NO BACKEND BY DEFAULT. A page that needs one passes the base explicitly; nothing in the SDK points requests at
+  // the page's own origin. The legacy session calls were removed for the same reason: a host could link the visitor
+  // to the escrow from a request the widget never needed.
+  base: null,
+  // The Monero-leg source: 'app' - a backend the caller explicitly configured, 'mock' - the demo simulator.
   xmrSource: "app",
   pollMs: 5_000, // how often the front end polls a swap session
   // HOW MANY PROVIDERS TO SHOW in the price block. A list of dozens of rows is unreadable, and a person cannot

package/engine/core/swap.js

@@ -29,7 +29,7 @@ import * as node from "../monero/node.js";
 // The Monero-leg source: in "app" mode confirmations and arrivals come from the backend,
 // in "mock" mode - from the demo simulator. Exactly what goes outward (only the address and view key)
 // is checked mechanically.
-import { XMR_STATUS, explorerXmrTx, fetchSession, isLiveSource, openSession, pollInterval, xmrView } from "./chainSource.js";
+import { XMR_STATUS, explorerXmrTx, isLiveSource, xmrView } from "./chainSource.js";
 import { watchOnlyShareFromWallet } from "../recovery/restore.js";
 
 export const STEP_LABELS = [
@@ -788,25 +788,6 @@ function emit() {
   }
 }
 
-// --- live mode: the swap session on the backend -----------------------------------------------
-//
-// The poll runs without waiting: the screen ticker must not wait for the network, else with an unavailable backend
-// the demo starts to lag. The result is put into the swap itself (xmrSession / xmrSessionError), and derive()
-// reads it as ordinary state - it stays a pure function.
-const liveInFlight = new Set();
-
-function applyLive(id, patch) {
-  const s = loadState();
-  if (!s.swaps[id]) return;
-  Object.assign(s.swaps[id], patch);
-  saveState(s);
-}
-
-// The time of the last ATTEMPT to reach the backend per swap. Attempts, not successes: rate limiting must work
-// even when the request fails.
-const liveLastTry = new Map();
-
-
 // THE DEAL KEY: THE PAGE AND THE APP NAME IT DIFFERENTLY. The page has its own id (lives in the browser), the
 // app its own (localtest-...): the id is set by the app when it creates the watch record. The page asked for the
 // XMR state by ITS OWN id, which the app does not know and answers with a refusal. From outside it looks like
@@ -830,188 +811,21 @@ export function dealSwapIds(swap) {
   return [...ids];
 }
 
-const serverIdByAddress = new Map();
-
-// WE LOOK FOR THE DEAL'S FACTS ACROSS ALL ITS RECORDS IN THE BROWSER. The page keeps TWO records per deal: one
-// created by the swap (Monero address, expected XMR amount), another by the escrow (halves, escrow address). A
-// screen opened on the escrow record did not know the expected amount, the session was not created at all and the
-// readiness button did not turn on - although the app was already reporting readiness. The records are tied by the SHARED Monero address: one per deal.
-function dealFactsFor(swap) {
-  const w0 = (() => { try { return halvesWalletOf(swap) || {}; } catch { return {}; } })();
-  let address = w0.address || (swap && swap.escrow && swap.escrow.moneroAddress) || (swap && swap.xmrSession && swap.xmrSession.address) || null;
-  let amountXmr = Number(swap && swap.xmrAmount) > 0 ? Number(swap.xmrAmount) : null;
-  let source = "own record";
-  if (address && amountXmr === null) {
-    for (const other of Object.values((loadState() || {}).swaps || {})) {
-      if (!other || other === swap) continue;
-      const w = (() => { try { return halvesWalletOf(other) || {}; } catch { return {}; } })();
-      if (!w.address || w.address !== address) continue;
-      if (Number(other.xmrAmount) > 0) { amountXmr = Number(other.xmrAmount); source = "another record of the same deal (" + String(other.id || "?") + ")"; break; }
-    }
-  }
-  if (!address) {
-    for (const other of Object.values((loadState() || {}).swaps || {})) {
-      const w = (() => { try { return halvesWalletOf(other) || {}; } catch { return {}; } })();
-      if (w.address && Number(other.xmrAmount) > 0) { address = w.address; amountXmr = amountXmr || Number(other.xmrAmount); source = "another record of the same deal"; break; }
-    }
-  }
-  return { address, amountXmr, source };
-}
-
-// WE TAKE THE DEAL ADDRESS FROM EVERYWHERE IT MAY LIE. A browser deal and the app's watch record are DIFFERENT
-// records about one deal (the page creates its own for the escrow, the app one for watching the address), so the
-// page's record does not always have the address: on the escrow record it lies in the halves, not in the
-// escrow.moneroAddress field. A live run therefore polled a dead id, got 404 and left the readiness button off.
-// Extracted separately so the same address is used by the server height lookup too.
-function dealMoneroAddress(swap) {
-  const fromHalves = (() => { try { return (halvesWalletOf(swap) || {}).address || null; } catch { return null; } })();
-  return (swap && swap.escrow && swap.escrow.moneroAddress)
-    || (swap && swap.xmrSession && swap.xmrSession.address)
-    || (swap && swap.swapWallet && swap.swapWallet.address)
-    || fromHalves
-    || null;
-}
-
 // THE SCAN HEIGHT THE APP KNOWS. Needed by OLD deals' files: their record has no birthHeight (the field appeared
 // later), while the app resolved and stored the height when registering the watch. The source is ours, so it does
 // not depend on someone else's Monero node. The server is silent - we return null and the caller keeps the
 // previous behaviour: the height comes from other sources or the file honestly warns of its absence.
-export async function serverRestoreHeightFor(swap, { attempts = 3, pauseMs = 1200 } = {}) {
-  const addr = dealMoneroAddress(swap);
-  if (!addr) return null;
-  // NOT ONE ATTEMPT. The app's watch row appears the same instant as the escrow, and the file may be issued a
-  // hair earlier: then the fallback source is silent and null goes into the file - and there is nowhere else to
-  // get the height, the file is already with the owner. A few short attempts close this gap instead of turning
-  // it into an empty field; the price is fractions of a second in the rare case when there is no row at all.
-  for (let i = 0; i < attempts; i++) {
-    try {
-      const r = await fetch("/api/swaps", { headers: { accept: "application/json" } });
-      if (r.ok) {
-        const j = await r.json();
-        const rows = Array.isArray(j) ? j : (j.swaps || []);
-        const row = rows.find((x) => String((x && x.address) || "") === String(addr));
-        const h = Number(row && row.restoreHeight);
-        if (Number.isFinite(h) && h > 0) return h;
-      }
-    } catch {
-      /* try again: the service may have been busy with the first request */
-    }
-    if (i < attempts - 1) await new Promise((r) => setTimeout(r, pauseMs));
-  }
+export async function serverRestoreHeightFor() {
+  // NO BACKEND LOOKUP. The app's watch record is not a source for the SDK any more: asking the page's own host by
+  // the deal's Monero address is exactly the request the owner removed. A caller that still has a backend passes the
+  // height itself; otherwise the recovery file says it is missing.
   return null;
 }
 
-async function resolveServerSwapId(swap) {
-  const addr = dealMoneroAddress(swap);
-  if (!addr) return null;
-  if (serverIdByAddress.has(addr)) return serverIdByAddress.get(addr);
-  try {
-    const r = await fetch("/api/swaps", { headers: { accept: "application/json" } });
-    if (!r.ok) return null;
-    const j = await r.json();
-    const rows = Array.isArray(j) ? j : (j.swaps || []);
-    const row = rows.find((x) => String((x && x.address) || "") === String(addr));
-    if (!row || !row.id) return null;
-    serverIdByAddress.set(addr, String(row.id));
-    return String(row.id);
-  } catch {
-    return null;   // the server is silent - we keep the previous behaviour, the screen does not wait for the network
-  }
-}
-
-function refreshLiveSession(id) {
-  if (liveInFlight.has(id)) return;
-  // No more than once per pollMs per swap, REGARDLESS of whether the session survived. The limit used to stand
-  // only in the "session exists" branch: if the request failed (429 from the proxy, 502 from a timeout), the
-  // session was not saved, the limit did not apply - and the tick repeated the request every 5 seconds for EACH
-  // swap. With eight accumulated swaps that produced a stream of 429s: the app fought itself.
-  const now = Date.now();
-  const lastTry = liveLastTry.get(id) || 0;
-  if (now - lastTry < pollInterval()) return;
-  liveLastTry.set(id, now);
-  liveInFlight.add(id);
-  (async () => {
-    try {
-      const fresh = loadState().swaps[id];
-      if (!fresh || fresh.settlement) return;
-      if (!fresh.xmrSession) {
-        // The swap wallet is created in the browser; only the address and view key go outward (see chainSource).
-        // THE EXPECTED AMOUNT IS MANDATORY. Without it we do not create a session at all: the wallet is the same
-        // as on the confirmation screen, so the address is already watched. Otherwise a second truth about one
-        // deal would appear at the same address, and a record without an amount would let an underpayment through.
-        // As soon as the amount appears, the next tick creates the session itself.
-        const facts = dealFactsFor(fresh);
-        const amountXmr = facts.amountXmr;
-        if (!Number.isFinite(amountXmr) || amountXmr <= 0) {
-          pushLog(fresh, simElapsed(fresh), "Backend session not opened yet: amount of XMR is unknown", String((fresh && fresh.xmrAmount) ?? "no"));
-          return;
-        }
-        if (facts.source !== "own record") {
-          pushLog(fresh, simElapsed(fresh), "Amount of XMR taken from the deal's other record", facts.source + ", " + String(amountXmr));
-        }
-        const share = watchOnlyShareFromWallet({ swapId: fresh.id, wallet: fresh.swapWallet });
-        const opened = await openSession({
-          swapId: fresh.id,
-          share,
-          expectedAmountXmr: amountXmr,
-          chain: fresh.network,
-        });
-        if (opened.ok) {
-          applyLive(id, { xmrSession: opened.session, xmrSessionError: null });
-          const s2 = loadState();
-          if (s2.swaps[id]) {
-            pushLog(s2.swaps[id], simElapsed(s2.swaps[id]), "Backend session opened (watch-only: address + view key)", opened.session.address || "");
-            saveState(s2);
-          }
-        } else {
-          applyLive(id, { xmrSessionError: opened.error });
-        }
-      } else if (Date.now() - (fresh.xmrSession.at || 0) >= pollInterval()) {
-        // WE ASK BY THE APP'S ID, not our own: see resolveServerSwapId. If the record was not found, we do NOT
-        // ask by our own id - the app will answer 404 and the screen will silently wait forever. Instead we
-        // create the watch afresh: the app itself ties it by address to the existing record and returns the same
-        // one, not a second truth about one deal.
-        const serverId = await resolveServerSwapId(fresh);
-        const polled = await fetchSession(serverId || id);
-        if (polled.ok) {
-          applyLive(id, { xmrSession: polled.session, xmrSessionError: null });
-        } else if (!serverId) {
-          const share = watchOnlyShareFromWallet({ swapId: fresh.id, wallet: fresh.swapWallet });
-          const again = await openSession({
-            swapId: fresh.id, share, expectedAmountXmr: Number(fresh.xmrAmount), chain: fresh.network,
-          });
-          if (again.ok) {
-            applyLive(id, { xmrSession: again.session, xmrSessionError: null });
-            const s3 = loadState();
-            if (s3.swaps[id]) { pushLog(s3.swaps[id], simElapsed(s3.swaps[id]), "Backend record re-linked by the Monero address", again.session.address || ""); saveState(s3); }
-          } else {
-            applyLive(id, { xmrSessionError: again.error });
-          }
-        } else {
-          applyLive(id, { xmrSessionError: polled.error });
-        }
-      }
-    } catch (e) {
-      applyLive(id, { xmrSessionError: "session did not open: " + e.message });
-    } finally {
-      liveInFlight.delete(id);
-    }
-  })();
-}
-
-// The deals currently open on screen. The core polls the backend ONLY for them.
-//
-// Why: the tick used to poll all unfinished deals indiscriminately. After a few presses of the sign button they
-// accumulated to eight, and the app itself flooded the proxy with requests - a 429 came back. And on the main
-// page there is nothing to watch at all: there is no deal yet.
-//
-// An empty set (the default) means "poll nothing". Screens that need watching report their set themselves: the
-// deal list - all unfinished, the deal screen - one.
-let liveFocusIds = new Set();
-
+// Kept for callers that used to name the deals on screen. There is no backend poll any more; the function only
+// returns how many ids were named, so an old caller does not break.
 export function setLiveFocus(ids) {
-  liveFocusIds = new Set(Array.isArray(ids) ? ids.map(String) : []);
-  return liveFocusIds.size;
+  return new Set(Array.isArray(ids) ? ids.map(String) : []).size;
 }
 
 export function tick() {
@@ -1024,7 +838,6 @@ export function tick() {
     // Live mode: a session on the backend. We create it on the first tick after the swap is created and then
     // poll no more often than API.pollMs. Not awaited: the screen must not wait for the network.
     // We poll only what is open on screen.
-    if (isLiveSource(swap.xmrSource) && liveFocusIds.has(String(swap.id))) refreshLiveSession(swap.id);
 
     const view = derive(swap);
 
@@ -1080,26 +893,7 @@ export function tick() {
       changed = true;
     }
 
-    // Live mode: the withdrawal is confirmed by the sweep page (a watch-only wallet cannot see outgoing
-    // transfers), so the final state is taken from the session status, and the hash is not invented.
-    if (isLiveSource(swap.xmrSource) && swap.xmrSession && swap.xmrSession.status === XMR_STATUS.SWEPT && !swap.settlement) {
-      const atSim = view.sim;
-      swap.settlement = {
-        kind: "success",
-        phase: TERMINAL.success.phase,
-        atSim,
-        txid: swap.xmrSession.sweepTxid || null,
-        by: "your sweep wallet",
-      };
-      pushLog(swap, atSim, "XMR swept by you (backend reported)", swap.settlement.txid || "");
-      const key = swap.id + ":success";
-      if (!notified.has(key)) {
-        notified.add(key);
-        notify("Swap " + swap.id + " complete: XMR is on your address", "ok");
-      }
-      changed = true;
-      continue;
-    }
+    // Live mode: the XMR arrives from the chain; the SDK does not confirm a sweep from a backend session.
 
     // happy path: after claim the user's wallet sweeps the XMR itself (litepaper §4.2)
     if (!isLiveSource(swap.xmrSource) && view.can.sweep && view.phase === "success") {

package/engine/sdk/bridge.js

@@ -122,7 +122,7 @@ function optionsFor(chain) {
   return {
     settlement: { chain: chain.id },
     xmrNetwork: MONERO.networkType,
-    apiBase: "/api",
+    // NO BACKEND BY DEFAULT: a page that needs one passes its base explicitly.
     assetsBase: "/",
     mode: modeOf(chain),
     // THE PAGE STORAGE BECOMES THE CORE STORAGE: deal records and the session live in one place.

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;
@@ -1300,14 +1303,8 @@ export interface SweepApi {
    * the person what will leave, BEFORE sending.
    */
   sign(request: SweepRunRequest): Promise<SweepSignResult>;
-  /** Send what `sign` signed, close the wallet and tell the service about the withdrawal. */
+  /** Send what `sign` signed, close the wallet and return the transaction hashes. */
   relay(request: SweepRelayRequest): Promise<SweepRunResult>;
-  /**
-   * TELL THE SERVICE ABOUT THE WITHDRAWAL. The mark does not affect the transfer - it is already on the network - so
-   * it can be repeated: the interface calls this even after `relay` if the report did not go through then. A
-   * connection refusal gives `reported: false`.
-   */
-  report(request: SweepReportRequest): Promise<SweepReportResult>;
   /** Perform the withdrawal as a whole (`sign` + `relay`). */
   run(request: SweepRunRequest): Promise<SweepRunResult>;
 }
@@ -1328,8 +1325,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 +1355,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;
@@ -1407,16 +1415,6 @@ export interface SweepWallet {
   driver(): unknown;
 }
 
-/** The withdrawal mark: the swap identifier and the transfer hash. */
-export interface SweepReportRequest {
-  readonly swapId: string;
-  readonly txid: string;
-}
-
-export interface SweepReportResult {
-  readonly reported: boolean;
-}
-
 export interface SweepFromOrderRequest {
   /** The 12 words of the recovery key. */
   readonly mnemonic: string;
@@ -1571,12 +1569,6 @@ export interface SweepRelayRequest {
 export interface SweepRunResult {
   readonly txids: readonly string[];
   readonly swept: string;
-  /**
-   * Whether the service was told about the withdrawal. THE REPORT DOES NOT AFFECT THE TRANSFER - it is already on
-   * the network - so a failed report does not make the withdrawal unsuccessful: it gives `reported: false`, so the
-   * interface offers to report again.
-   */
-  readonly reported: boolean;
 }
 
 // --- Recovery// --- Recovery ------------------------------------------------------------------------------

package/package.json

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

package/src/http.mjs

@@ -16,6 +16,7 @@ export function createHttp({ apiBase, fetchImpl = null, timeoutMs = 20_000 }) {
     // a GET, and the service would answer with a refusal to a request it did not understand. The defaults are
     // the previous ones (GET without a body).
     async json(path, { signal = null, method = "GET", headers = null, body = null } = {}) {
+      if (!apiBase) throw new SdkError("server-unavailable", { why: "no-api-base" });
       if (typeof impl !== "function") throw new SdkError("bad-input", { field: "fetch" });
       const ctrl = new AbortController();
       const timer = setTimeout(() => ctrl.abort(), timeoutMs);
@@ -47,6 +48,7 @@ export function createHttp({ apiBase, fetchImpl = null, timeoutMs = 20_000 }) {
      * refused" are different things, and the caller must see them.
      */
     async tryJson(path, { signal = null, method = "GET", headers = null, body = null } = {}) {
+      if (!apiBase) throw new SdkError("server-unavailable", { why: "no-api-base" });
       if (typeof impl !== "function") throw new SdkError("bad-input", { field: "fetch" });
       const ctrl = new AbortController();
       const timer = setTimeout(() => ctrl.abort(), timeoutMs);

package/src/index.mjs

@@ -142,7 +142,7 @@ const normalizeOptions = (options) => {
   return {
     settlement: { chain: settlement.chain, vm: settlement.vm },
     xmrNetwork: o.xmrNetwork,
-    apiBase: typeof o.apiBase === "string" && o.apiBase ? o.apiBase : "/api",
+    apiBase: typeof o.apiBase === "string" && o.apiBase ? o.apiBase : null,
     assetsBase: typeof o.assetsBase === "string" && o.assetsBase ? o.assetsBase : "/",
     mode,
     storage: o.storage || null,

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

@@ -46,8 +46,8 @@ import { declineOf, logReaderOf, blockBoundaryOf, DECLINED_TOPIC0, DECLINED_TERM
 //
 // WHAT CAN BE A KIND, EXHAUSTIVELY. The record's settlement belongs to the engine (engine/core/swap.js, the only
 // module that assigns swap.settlement), and `declined` is the one kind written by us (src/decline.mjs):
-//   `success`    - the swap completed and the XMR is on the depositor's address (sweepNow, the auto-sweep in the
-//                  ticker, and the backend-reported sweep on the live path);
+//   `success`    - the swap completed and the XMR is on the depositor's address (sweepNow and the auto-sweep in the
+//                  ticker; the SDK does not take it from a backend session);
 //   `refund_eth` - the ETH went back to the depositor. TWO WRITERS, ONE KIND: the person's own refund (refundEth)
 //                  and the watchtower inside the ticker both write `kind: "refund_eth"` with the phase
 //                  `refunded_eth`, so there is exactly ONE refund-shaped kind here and nothing is collapsed;
@@ -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 });
@@ -980,20 +989,21 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         }
       }
 
-      // 5. THE SERVER: RECORDING THE SWAP WITH US, THEN THE FACTORY WATCH RECORD FOR THE MONERO ADDRESS.
-      // THE ORDER IS EXACTLY THIS: first the swap becomes known to the service (by it, the service checks the escrow
-      // address against the CHAIN), and only then is the watch opened. The reverse order would leave a watch on a swap
-      // the service does not know.
-      // IF ANYTHING OF THIS FAILED - THE REFUSAL GOES OUT AS A CODE (server-unavailable / server-refused) with the step
-      // and the service's reason: the funds are already locked, and this must not be hidden in silence or in "success".
-      const server = await markOnServer(record.swap, escrowAddress, request.order);
-      const watch = await openWatch(record.swap, request.order);
+      // 5. A BACKEND IS OPTIONAL AND NEVER A DEFAULT. When the caller configured an API base, the swap is recorded
+      // there and the watch row is opened. Without one, the SDK returns the local state and the joint address: the
+      // caller watches the chain itself. The owner's rule: no request to the page's own origin.
+      let server = null;
+      let watch = null;
+      if (config && config.apiBase) {
+        server = await markOnServer(record.swap, escrowAddress, request.order);
+        watch = await openWatch(record.swap, request.order);
+      }
       // THE STATE IS NAMED, NOT PASSED OFF AS COMPLETION: the swap reached exactly "waiting for XMR at the joint address",
-      // and there is no arrival yet - `receivedXmr` is taken from the service's response, not implied by zero.
+      // and there is no arrival yet - `receivedXmr` is never implied by zero.
       return {
         id: record.swap.id || null,
         escrow: escrowAddress,
-        address: watch.address,
+        address: (watch && watch.address) || (record.swapWallet && record.swapWallet.address) || null,
         step: "xmr-incoming",
         server,
         watch,
@@ -1004,8 +1014,9 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
     /**
      * WAIT FOR THE XMR TO ARRIVE AT THE JOINT ADDRESS - the whole point of opening the watch.
      *
-     * The polling uses THE SAME request as the page's (GET /api/swaps/{id}), the rate and the timeout - from the
-     * configuration (config.limits.watchPollMs/watchTimeoutMs, the engine's defaults too) and are overridable here.
+     * The CLIENT checks the arrival from the Monero nodes (`verify`); there is no backend poll by default. The rate
+     * and the timeout come from the configuration (config.limits.watchPollMs/watchTimeoutMs) and are overridable here.
+     * A caller that explicitly configured `apiBase` may use the old watch-row flow instead.
      * IT ARRIVED - we return the FACT (the amount, the confirmations, the txid); WE DID NOT WAIT - a refusal with the
      * code `xmr-timeout`, separate from the others, so "the wait expired" is confused with neither a breakdown nor an
      * empty response. XMR ON THE ADDRESS BUT BARRED BY unlock_time is a THIRD answer with its own code `xmr-locked`
@@ -1047,6 +1058,11 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
           : (request.deadline && request.deadline.readyBy !== undefined ? Number(request.deadline.readyBy) : null);
         if (readyBy) xmrArrival.assertTimeForConfirmations({ readyBySec: readyBy, nowSec: Math.floor(Date.now() / 1000), minConfirmations, blockTimeSec: limitOf("xmrBlockTimeSec", 120) });
       }
+      const hasBackend = Boolean(config && config.apiBase);
+      // THE WATCH DOES NOT CALL A BACKEND BY DEFAULT. The client-side arrival check needs the joint address, the view
+      // secret and the spend public key; without them, and without an explicitly configured backend, there is nothing
+      // to wait on. That is a named refusal, not a request to the page's own origin.
+      if (!verifyRequest && !hasBackend) throw new SdkError("bad-input", { field: "verify", why: "no-backend" });
       const started = Date.now();
       // --- THE MAKER'S DECLINE: THE WAIT IS NOT STARTED AT ALL (issue #40). -------------------------------------
       // A decline leaves the escrow `refunded`, so nothing in the state says "do not wait any longer": without
@@ -1114,8 +1130,12 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       let last = null;
       for (;;) {
         await readDeclineLogs();
-        const body = await readWatch(id);
-        last = incomingOf(body);
+        // THE CLIENT-SIDE CHECK DOES NOT ASK THE SERVICE. Only a watch without `verify` and with an explicitly
+        // configured backend reads the watch row.
+        const body = verifyRequest ? {} : await readWatch(id);
+        last = verifyRequest
+          ? { address: request.address || escrowAddress, expectedXmr: request.expectedXmr ?? null, status: null }
+          : incomingOf(body);
         // THE DECLINE IS DECIDED BEFORE THE ARRIVAL IS LOOKED AT, and before the "foreign response" refusal below:
         // a declined swap's answer carries no `receivedXmr` at all, and refusing it as a bad response would name
         // the wrong thing (the state is known - it is a decline, not a broken answer).

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,24 +173,62 @@ 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));
-      try { await wallet.sync(); } catch { /* the balance below decides */ }
-      windowTotal = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
-      windowUnlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
-      windowReport.used = true;
+      try {
+        await step("setRestoreHeight", () => driver.setRestoreHeight(tipHeight));
+        await step("scanTxs", () => driver.scanTxs(hashes));
+        try { await wallet.sync(); } catch { /* the balance below decides */ }
+        windowTotal = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
+        windowUnlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
+        windowReport.used = true;
+      } catch (e) {
+        // A WINDOW THAT WAS READ BUT NOT APPLIED IS STILL A FAILED WINDOW. `scanTxs` and the balance read use the
+        // wallet's own transport; a node that misses one route (`/gettransactions`) or a wallet that refuses the
+        // scan must not end the withdrawal. The full scan below is the fallback, and the reason says which step.
+        if (e && e.code === "bad-input") throw e;
+        windowTotal = 0n;
+        windowUnlocked = 0n;
+        windowReport.fallback = true;
+        windowReport.fallbackWhy = "window-scan";
+        windowReport.error = {
+          code: e && e.code ? e.code : "wallet-rejected",
+          surface: e && e.params && e.params.surface ? e.params.surface : "scanTxs",
+          status: null,
+          height: null,
+          why: e && e.params && e.params.why ? e.params.why : null,
+        };
+      }
       // THE KEY IMAGES OF THE WALLET, CHECKED AT THE NODE. `scanTxs` finds an output; whether the chain already
-      // spent it is a separate fact, and the caller must not sign on a guess.
-      if (requestWindow.nodeUrl && typeof driver.getKeyImages === "function") {
+      // spent it is a separate fact, and the caller must not sign on a guess. A failed scan has no images to ask for.
+      if (windowReport.used && requestWindow.nodeUrl && typeof driver.getKeyImages === "function") {
         try {
           const exported = await driver.getKeyImages();
           const images = Array.isArray(exported) ? exported
@@ -175,13 +250,13 @@ export async function restoreWallet(request = {}) {
             } else windowReport.spent = null;
           } else { windowReport.spent = null; windowReport.spentWhy = "no-key-images"; }
         } catch { windowReport.spent = null; windowReport.spentWhy = "check-failed"; }
-      } else if (requestWindow.nodeUrl) {
+      } else if (windowReport.used && requestWindow.nodeUrl) {
         windowReport.spent = null;
         windowReport.spentWhy = "no-key-images";
       }
       // A WINDOW WITH COINS IS THE ANSWER. A window with none falls through to the full scan unless the caller
       // explicitly turned the fallback off.
-      if (windowTotal > 0n || windowUnlocked > 0n || requestWindow.fallback === false) {
+      if (windowReport.used && (windowTotal > 0n || windowUnlocked > 0n || requestWindow.fallback === false)) {
         return {
           total: windowTotal.toString(), unlocked: windowUnlocked.toString(), scanHeight, walletHeight: await heightOf(driver, "getHeight"),
           nodeHeight: await heightOf(driver, "getDaemonHeight"), passes: 1, lockedPass: false, window: windowReport,
@@ -194,7 +269,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/sweep.mjs

@@ -209,30 +209,15 @@ export function createSweep({ http, config, call = null }) {
       const spendable = !!wallet.spendHalf;
       if (!spendable) missing.push("spendable");
 
-      // THE RESTORE HEIGHT: first from the file, then from the app BY ADDRESS - exactly as the sweep page does it.
-      // An unavailable app is a lack of data, not a refusal: the plan is returned anyway, and `missing` shows what
-      // is lacking.
+      // THE RESTORE HEIGHT COMES FROM THE FILE OR THE CHAIN. The SDK does not ask a service by address: a static
+      // page and a widget must not tell their own host which deal they are recovering. A missing height is named in
+      // `missing`; the caller can pass one from `findSwaps` or the person can type it.
       let restoreHeight = Number(wallet.restoreHeight) || 0;
-      let row = null;
-      try {
-        // THE PATH BY NAME, not by a string: the override comes through the `routes` option.
-        const answer = await http.json(config.route("swaps"));
-        const rows = Array.isArray(answer) ? answer : ((answer && answer.swaps) || []);
-        row = rows.find((x) => String((x && x.address) || "") === String(address)) || null;
-      } catch { row = null; }
-      const fromApp = Number(row && row.restoreHeight) || 0;
-      if (fromApp > 0) restoreHeight = fromApp;
       if (!(restoreHeight > 0)) missing.push("restore-height");
 
-      // THE COUNTERPARTY'S REVEALED HALF - FROM THE CHAIN, VIA THE APP. Exactly as the sweep page does it: POST to
-      // the named path, body { network, address }, where address is the ESCROW ADDRESS (not the Monero address).
-      // The half is published by the settlement that moves the ETH: a claim or a refund. Before that no one has the
-      // spend key, so "not revealed yet" is not an error but a state, and that is exactly where it lands in `missing`.
       // THE COUNTERPARTY'S REVEALED HALF - FROM THE CHAIN WHEN THE CALLER HAS A CHAIN READ. The half is public:
-      // `claim` and `refund` store it in `revealedHalf()` and emit `HalfRevealed`. A recovery page served from a
-      // static host has no `/escrow/revealed-half` route, so asking the app was the only path and a static page
-      // could never withdraw. The app route stays as the fallback for a caller that has no chain read and did
-      // configure an API base.
+      // `claim` and `refund` store it in `revealedHalf()` and emit `HalfRevealed`. There is no service fallback: a
+      // caller without a chain read gets `missing: ["revealed-half"]`, not a request to its own origin.
       let revealed = false;
       let revealedValue = null;
       const escrowAddress = wallet.escrowAddress || (payload.escrow && payload.escrow.address) || null;
@@ -246,17 +231,6 @@ export function createSweep({ http, config, call = null }) {
           }
         } catch { revealed = false; }
       }
-      if (!revealed && escrowAddress && config && config.apiBase) {
-        try {
-          const half = await http.json(config.route("revealedHalf"), {
-            method: "POST",
-            headers: { "content-type": "application/json" },
-            body: JSON.stringify({ network: payload.network, address: escrowAddress }),
-          });
-          revealed = !!(half && half.ok && half.revealed && half.half);
-          if (revealed) revealedValue = String(half.half);
-        } catch { revealed = false; }
-      }
       if (!revealed) missing.push("revealed-half");
 
       return {
@@ -317,24 +291,6 @@ export function createSweep({ http, config, call = null }) {
     // SIGNING AND SENDING ARE DELIBERATELY SPLIT: between them the interface has time to show the person what will
     // leave, rather than telling them about it after sending. An empty remainder stops the withdrawal BEFORE
     // signing - otherwise the wallet would sign a transaction for zero and the refusal would look like success.
-    // TELLING THE SERVICE ABOUT THE WITHDRAWAL - SEPARATELY AND REPEATABLY. The mark does not affect the transfer
-    // (it is already on the network), so it can be repeated: the interface calls this even after `relay` if the
-    // report did not go through then.
-    async report(request) {
-      if (!request || typeof request.swapId !== "string" || !request.swapId) throw new SdkError("bad-input", { field: "swapId" });
-      if (typeof request.txid !== "string" || !request.txid) throw new SdkError("bad-input", { field: "txid" });
-      try {
-        const answer = await http.json(config.route("swept", { id: request.swapId }), {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ txid: request.txid }),
-        });
-        return { reported: !(answer && answer.ok === false) };
-      } catch {
-        // The service is unavailable - that is `reported: false`, not a withdrawal refusal: the money has already left.
-        return { reported: false };
-      }
-    },
 
     // SIGNING WITHOUT SENDING - AS A SEPARATE STEP. The core HOLDS the signed transaction until the person's
     // decision: otherwise the interface could not show what exactly will leave, and would tell about it only after
@@ -410,14 +366,9 @@ export function createSweep({ http, config, call = null }) {
       try {
         const txids = await wallet.relay(signed);
         const list = Array.isArray(txids) ? txids : [];
-        // MARKING THE WITHDRAWAL - AFTER SENDING AND NOT AFFECTING IT. The transfer is already on the network; the
-        // report merely tells the service that the XMR left. So a failed report does NOT make the withdrawal
-        // unsuccessful: it gives `reported: false`, so the interface offers to report again - by the same path as
-        // here (`report`).
-        const reported = plan.swapId && list.length
-          ? (await api.report({ swapId: plan.swapId, txid: list[0] })).reported
-          : false;
-        return { txids: list, swept: plan.address, reported };
+        // NO SERVICE REPORT. The transfer is on the Monero network; the SDK does not ask the page's own host to
+        // record it, so the host cannot link the visitor's IP to the escrow and the withdrawal.
+        return { txids: list, swept: plan.address };
       } finally {
         await wallet.close();
       }

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.2";