@ninsei-labs/sdk 0.51.1 → 0.51.2

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.

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"
 });

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

@@ -1303,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>;
 }
@@ -1421,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;
@@ -1585,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.1",
+  "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/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;
@@ -989,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,
@@ -1013,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`
@@ -1056,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
@@ -1123,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

@@ -202,15 +202,33 @@ export async function restoreWallet(request = {}) {
     }
     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
@@ -232,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,

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.1";
+export const SDK_VERSION = "0.51.2";