@ninsei-labs/sdk 0.50.0 → 0.51.1

package/src/recovery-key.mjs

@@ -385,6 +385,27 @@ function decodeOrderLog(log) {
   };
 }
 
+// THE CLONE CARRIES THE ORDER, INCLUDING THE XMR AMOUNT. OrderCreated does not repeat `xmrAmount`, and the clone
+// has no getter for it, but word 18 of the condition blob is in its code. Read it only from a clone of the exact
+// shape: a contract of another size is not this order and must not yield a guessed number.
+const CLONE_CODE_BYTES = 877;
+const XMR_AMOUNT_WORD = 18;
+const CLONE_PROXY_BYTES = 45;
+const XMR_AMOUNT_OFFSET = CLONE_PROXY_BYTES + XMR_AMOUNT_WORD * 32;
+
+function xmrAmountFromClone(code) {
+  if (typeof code !== "string" || !/^0x[0-9a-fA-F]+$/.test(code)) return { value: null, reason: "code" };
+  const bytes = (code.length - 2) / 2;
+  if (!Number.isInteger(bytes) || bytes !== CLONE_CODE_BYTES) return { value: null, reason: "not-clone" };
+  const word = code.slice(2 + XMR_AMOUNT_OFFSET * 2, 2 + (XMR_AMOUNT_OFFSET + 32) * 2);
+  if (word.length !== 64) return { value: null, reason: "not-clone" };
+  try {
+    return { value: BigInt("0x" + word).toString(), reason: null };
+  } catch {
+    return { value: null, reason: "code" };
+  }
+}
+
 async function readLogs(evmLogs, request) {
   if (typeof evmLogs !== "function") throw bad("evmLogs");
   let logs;
@@ -397,6 +418,25 @@ async function readLogs(evmLogs, request) {
   return logs;
 }
 
+/**
+ * Is this number already held by an order on chain?
+ *
+ * A browser store is per device. The same twelve words opened on a second device, or restored before any search, start
+ * at number 0 again; two swaps would then share the taker's halves, and a refund of one publishes a half the other's
+ * maker can use. The check is the factory's own `OrderCreated` log, matched by the spend commitment the number derives.
+ *
+ * The caller owns the log transport, as everywhere else in this module. An unreadable log request is a refusal, not
+ * "free": the number is not reserved on a guess.
+ */
+export async function recoveryIndexTaken({ mnemonic, chainId, index, factory, evmLogs, fromBlock = 0, toBlock = "latest" } = {}) {
+  if (typeof factory !== "string" || !ADDRESS_RE.test(factory)) throw bad("factory");
+  const own = takerHalves({ mnemonic, chainId, index });
+  const logs = await readLogs(evmLogs, { address: factory, topics: [ORDER_CREATED_TOPIC], fromBlock, toBlock });
+  return logs.map(decodeOrderLog).filter(Boolean).some((order) =>
+    order.commitHalfLocker.toLowerCase() === own.spendCommitment.toLowerCase() ||
+    order.commitHalfClaimer.toLowerCase() === own.spendCommitment.toLowerCase());
+}
+
 // THE MONERO HEIGHT A RECOVERED ORDER STARTED AT. With one key there is no per-swap file to carry it, so it is
 // derived from the settlement chain: the timestamp of the block that holds OrderCreated, then the last Monero
 // block at or before it. A Monero block's timestamp may run ahead of wall time, hence the safety margin.
@@ -406,8 +446,11 @@ async function readLogs(evmLogs, request) {
 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;
+  if (!Number.isFinite(n) || n < 0) return null;
   return n > 1e12 ? Math.floor(n / 1000) : Math.floor(n);
 }
 
@@ -437,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 {
@@ -460,34 +508,47 @@ async function moneroReadersFromNodes({ nodes = [], network = null, fetchImpl =
     return body.result;
   };
   return {
-    tip: async () => node.height,
-    headerTimestamp: async (height) => {
-      const result = await call("get_block_header_by_height", { height });
-      const ts = Number(result.block_header && result.block_header.timestamp);
-      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" };
+    return { startHeight: null, startHeightReason: "no-block-number", blockTime: null };
   }
-  if (typeof evmBlockTime !== "function" || typeof moneroTip !== "function" || typeof moneroBlockTimestamp !== "function") {
-    return { startHeight: null, startHeightReason: "no-height-readers" };
+  // 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: 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.
   let timestamp = cache.get(order.blockNumber);
   if (timestamp === undefined) {
-    timestamp = secondsOf(await evmBlockTime(order.blockNumber));
-    if (timestamp === null) return { startHeight: null, startHeightReason: "no-block-time" };
+    timestamp = typeof evmBlockTime === "function" ? secondsOf(await evmBlockTime(order.blockNumber)) : null;
+    if (timestamp === null) return { startHeight: null, startHeightReason: "no-block-time", blockTime: null };
     cache.set(order.blockNumber, timestamp);
   }
+  if (typeof moneroTip !== "function" || typeof moneroBlockTimestamp !== "function") {
+    return { startHeight: null, startHeightReason: readersReason || "no-height-readers", blockTime: timestamp };
+  }
   try {
     const height = await heightAtOrBefore(timestamp, { tip: moneroTip, headerTimestamp: moneroBlockTimestamp });
-    return { startHeight: Math.max(0, height - MONERO_HEIGHT_SAFETY_BLOCKS), startHeightReason: null };
+    return { startHeight: Math.max(0, height - MONERO_HEIGHT_SAFETY_BLOCKS), startHeightReason: null, blockTime: timestamp };
   } catch {
-    return { startHeight: null, startHeightReason: "monero-header" };
+    return { startHeight: null, startHeightReason: "monero-header", blockTime: timestamp };
   }
 }
 
@@ -499,14 +560,23 @@ async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBloc
  * positions) and merges the answers. Without one, every OrderCreated of the factory is read and matched locally.
  */
 export async function findSwaps({ mnemonic, chainId, factory, address = null, evmLogs,
-  fromBlock = 0, toBlock = "latest", gap = 5, maxIndex = 1000,
-  evmBlockTime = null, moneroTip = null, moneroBlockTimestamp = null,
+  fromBlock = null, deploymentBlock = null, toBlock = "latest", gap = 5, maxIndex = 1000,
+  evmBlockTime = null, evmCode = null, moneroTip = null, moneroBlockTimestamp = null,
   xmrNodes = null, moneroNetwork = null, fetchImpl = globalThis.fetch } = {}) {
   if (typeof factory !== "string" || !ADDRESS_RE.test(factory)) throw bad("factory");
   const chain = numberField(chainId, "chainId");
   const max = numberField(maxIndex, "maxIndex") || 1000;
   const missesAllowed = numberField(gap, "gap") || 5;
-  const base = { address: factory, fromBlock, toBlock };
+  // THE CHAIN SAYS WHERE ITS ORDERS CAN START. An explicit fromBlock wins; otherwise the caller can pass the
+  // factory's deployment block (the SDK's chain registry exposes it as escrow.deploymentBlock). Zero remains the
+  // last resort for a caller that knows the factory existed at genesis.
+  if (deploymentBlock !== null && deploymentBlock !== undefined && !Number.isSafeInteger(Number(deploymentBlock))) {
+    throw bad("deploymentBlock");
+  }
+  const startBlock = fromBlock === null || fromBlock === undefined
+    ? (deploymentBlock === null || deploymentBlock === undefined ? 0 : Number(deploymentBlock))
+    : fromBlock;
+  const base = { address: factory, fromBlock: startBlock, toBlock };
   let logs = [];
   if (address) {
     const padded = topicAddress(address);
@@ -549,12 +619,43 @@ 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
+  // record, not to OrderCreated or the clone. `payToken: null` plus a reason is the honest answer here; an invented
+  // "USDC" would be a claim the chain does not support.
+  for (const order of found) {
+    order.settlementToken = "native";
+    order.payToken = null;
+    order.payTokenReason = "not-on-chain";
+  }
+  for (const order of found) {
+    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.
   for (const order of found) {
-    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip: tip, moneroBlockTimestamp: header, cache }));
+    if (typeof evmCode !== "function") {
+      order.xmrAmount = null;
+      order.xmrAmountReason = "no-code-reader";
+      continue;
+    }
+    let code;
+    try {
+      code = await evmCode(order.escrow);
+    } catch {
+      order.xmrAmount = null;
+      order.xmrAmountReason = "code";
+      continue;
+    }
+    const read = xmrAmountFromClone(code);
+    order.xmrAmount = read.value;
+    order.xmrAmountReason = read.reason;
   }
   return { swaps: found, scanned };
 }

package/src/swaps.mjs

@@ -27,7 +27,7 @@ import { createActions } from "./actions.mjs";
 // THE ONE RECOVERY KEY (sdk#76): the taker's halves come from it, not from a fresh random pair per swap.
 import {
   commitRecoveryIndex, createRecoveryKeyFile, importRecoveryKey, loadRecoveryKey,
-  recoveryKeyFileName, reserveRecoveryIndex, saveRecoveryKey, takerHalves,
+  recoveryIndexTaken, recoveryKeyFileName, reserveRecoveryIndex, saveRecoveryKey, takerHalves,
 } from "./recovery-key.mjs";
 // THE XMR ARRIVAL CHECK ON TWO NODES (issue #85) - IN THE CORE, from the same mirrored rule and block parser.
 import * as xmrArrival from "./xmr-arrival.mjs";
@@ -804,10 +804,32 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         const key = saved || importRecoveryKey(supplied);
         if (!saved) saveRecoveryKey(storage, key);
         const chainId = request.order.chainId;
-        const index = request.recoveryIndex === undefined || request.recoveryIndex === null
-          ? reserveRecoveryIndex(storage, { chainId })
-          : Number(request.recoveryIndex);
+        const explicit = request.recoveryIndex !== undefined && request.recoveryIndex !== null;
+        let index = explicit ? Number(request.recoveryIndex) : reserveRecoveryIndex(storage, { chainId });
         if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "recoveryIndex" });
+        // A BROWSER STORE IS PER DEVICE. The same words opened elsewhere start at the same number, so the factory's own
+        // 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 })) {
+            if (explicit) throw new SdkError("bad-input", { field: "recoveryIndex", why: "on-chain" });
+            commitRecoveryIndex(storage, index);
+            index = reserveRecoveryIndex(storage, { chainId });
+            hops += 1;
+            if (!Number.isSafeInteger(index) || index < 0 || hops > 1000) throw new SdkError("bad-input", { field: "recoveryIndex", why: "exhausted" });
+          }
+        }
         const derived = takerHalves({ mnemonic: key.mnemonic, chainId, index });
         keySide = buildOwnSideFromHalves(request.order, { spendHalf: derived.spendHalf, viewHalf: derived.viewHalf }).side;
         recovery = { storage, key, index, newKey: !saved };

package/src/sweep-half.mjs

@@ -0,0 +1,14 @@
+// THE REVEALED HALF IS A 32-BYTE SCALAR, NOT AN ADDRESS.
+//
+// `revealedHalf()` returns one ABI word: 32 bytes of the ed25519 scalar the settlement published. The withdrawal path
+// used to read it as an address (`hex.slice(24)`), keeping only the last 20 bytes; `(s_a + s_b)·G` then never matched the
+// order's spend point and every real withdrawal was refused. The parser is separate from the chain read so a guard can
+// hand it the exact 32-byte word without a wallet or an RPC.
+const WORD_RE = /^[0-9a-f]{64}$/;
+
+export function revealedHalfWord(word) {
+  const raw = String(word === undefined || word === null ? "" : word).trim();
+  const hex = (raw.startsWith("0x") || raw.startsWith("0X") ? raw.slice(2) : raw).toLowerCase();
+  if (!WORD_RE.test(hex) || /^0+$/.test(hex)) return null;
+  return "0x" + hex;
+}

package/src/sweep-restore.mjs

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

@@ -10,6 +10,9 @@ import * as engine from "./engine.mjs";
 import { restoreWallet } from "./sweep-restore.mjs";
 import { moneroWalletAdapter } from "./adapters/monero-wallet.mjs";
 import { checkDestination } from "./destination.mjs";
+import { revealedHalfWord } from "./sweep-half.mjs";
+import { takerHalves } from "./recovery-key.mjs";
+import { jointAddress } from "./order.mjs";
 
 // The same boundary as when the file was issued: a passphrase shorter than twelve characters will not open the file.
 const MIN_PASSPHRASE = 12;
@@ -19,6 +22,71 @@ const REVEALED_HALF_SELECTOR = "0x3f267bb6";
 
 const contentsOf = (file) => (typeof file === "string" ? file : file && typeof file.contents === "string" ? file.contents : null);
 
+const bare = (value) => String(value == null ? "" : value).replace(/^0x/i, "").toLowerCase();
+
+// A FOUND ORDER AND THE KEY, WITHOUT A FILE. The recovery page used to write the order into the SDK's own payload
+// (buildPayload) in memory; that rule belongs here, next to the withdrawal it feeds. The page keeps the order and
+// the key; this function decides which side is the person, checks the chain's points against the key, builds the
+// joint address and returns the same payload a recovery file would carry.
+const payloadFromOrder = async (request) => {
+  const order = request && request.order;
+  if (!order || typeof order !== "object") throw new SdkError("bad-input", { field: "order" });
+  if (typeof request.mnemonic !== "string" || !request.mnemonic.trim()) throw new SdkError("bad-input", { field: "mnemonic" });
+  const chainId = Number(request.chainId);
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new SdkError("bad-input", { field: "chainId" });
+  const index = Number(order.index);
+  if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "order.index" });
+  const network = typeof request.network === "string" ? request.network.trim() : "";
+  const moneroNetwork = typeof request.moneroNetwork === "string" ? request.moneroNetwork.trim() : "";
+  if (!network) throw new SdkError("bad-input", { field: "network" });
+  if (!moneroNetwork) throw new SdkError("bad-input", { field: "moneroNetwork" });
+  const passphrase = typeof request.passphrase === "string" ? request.passphrase : "";
+  if (passphrase && passphrase.length < MIN_PASSPHRASE) {
+    throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
+  }
+
+  const side = order.side === "locker" ? "buy" : order.side === "claimer" ? "sell" : null;
+  if (!side) throw new SdkError("bad-input", { field: "order.side" });
+  const halves = takerHalves({ mnemonic: request.mnemonic, chainId, index });
+  const buy = side === "buy";
+  if (bare(buy ? order.edPointLocker : order.edPointClaimer) !== bare(halves.spendPoint)) {
+    throw new SdkError("bad-input", { field: "order", why: "spend-point" });
+  }
+  if (bare(order.edViewPointLocker) !== bare(buy ? halves.viewPoint : halves.makerViewPoint)) {
+    throw new SdkError("bad-input", { field: "order", why: buy ? "own-view-point" : "maker-view-point" });
+  }
+
+  const otherSpendPoint = "0x" + bare(buy ? order.edPointClaimer : order.edPointLocker);
+  const otherViewPoint = "0x" + bare(halves.makerViewPoint);
+  const joint = jointAddress({
+    ownSpendHalf: halves.spendHalf, ownViewHalf: halves.viewHalf,
+    otherSpendPoint, otherViewPoint, network: moneroNetwork,
+  });
+  const escrow = { address: order.escrow, readyBy: order.readyBy, t1: order.t1 };
+  const payload = engine.recoveryFile.buildPayload({
+    swap: {
+      id: order.escrow, side, network, moneroNetwork,
+      createdAt: order.blockTime ? Number(order.blockTime) * 1000 : null,
+      payToken: null, payAmount: null, xmrAmount: null, rate: null, maker: null, quoteSignature: null,
+      escrow, timeline: null,
+    },
+    swapWallet: {
+      source: "halves", network: moneroNetwork, address: joint.address,
+      spendHalf: halves.spendHalf, viewHalf: halves.viewHalf,
+      otherSpendPoint, otherViewPoint, otherViewHalf: halves.makerViewHalf,
+      escrowAddress: order.escrow,
+    },
+    escrow,
+    receiveAddress: null,
+    restoreHeight: Number(order.startHeight) > 0 ? Number(order.startHeight) : null,
+  });
+  return {
+    payload,
+    contents: await engine.recoveryFile.createRecoveryFile(payload, passphrase),
+    address: joint.address,
+  };
+};
+
 // A LOW-LEVEL WALLET ERROR IS STILL A REFUSAL, AND EVERY REFUSAL CARRIES A CODE.
 //
 // The library brings its own exceptions with no code at all - monero-ts answers "failed to get hashes" while
@@ -68,6 +136,13 @@ export function createSweep({ http, config, call = null }) {
   const NETWORK_ENUM = { mainnet: "MAINNET", stagenet: "STAGENET", testnet: "TESTNET" };
 
   const api = {
+    // BUILD THE WITHDRAWAL MATERIAL FROM A FOUND ORDER AND THE KEY. No recovery file, no temporary payload in the
+    // page: the returned `contents` is the same file `plan`/`keys` already accept, and `payload` is for callers
+    // that want the fields directly.
+    async fromOrder(request = {}) {
+      return await payloadFromOrder(request);
+    },
+
     // BUILD THE WITHDRAWAL WALLET from the library namespace the caller has. The page used to pass a `createWallet`
     // callback that mapped the enum itself; that mapping is here now, so a caller passes `moneroTs` and the keys.
     wallet(request = {}) {
@@ -164,10 +239,10 @@ export function createSweep({ http, config, call = null }) {
       if (escrowAddress && typeof call === "function") {
         try {
           const word = String((await call({ to: escrowAddress, data: REVEALED_HALF_SELECTOR })) || "");
-          const hex = word.startsWith("0x") ? word.slice(2) : word;
-          if (/^[0-9a-fA-F]{64}$/.test(hex) && !/^0+$/.test(hex)) {
+          const half = revealedHalfWord(word);
+          if (half !== null) {
             revealed = true;
-            revealedValue = "0x" + hex.slice(24);
+            revealedValue = half;
           }
         } catch { revealed = false; }
       }
@@ -276,8 +351,13 @@ export function createSweep({ http, config, call = null }) {
     async sign(request) {
       const plan = await api.plan(request);
       if (!request || typeof request.to !== "string" || !request.to) throw new SdkError("bad-input", { field: "to" });
-      if (typeof request.connectWallet !== "function") throw new SdkError("bad-input", { field: "connectWallet" });
-      const wallet = await request.connectWallet(plan);
+      // ONE ADAPTER FOR RESTORE AND SIGN. A caller that already holds the opened and synced wallet passes it as
+      // `wallet`; a caller that wants the SDK to build one passes `connectWallet`.
+      const wallet = request.wallet !== undefined && request.wallet !== null
+        ? request.wallet
+        : (typeof request.connectWallet === "function"
+          ? await request.connectWallet(plan)
+          : (() => { throw new SdkError("bad-input", { field: "connectWallet" }); })());
       const role = ["open", "sync", "unlockedBalance", "sweepUnlocked", "relay", "close"];
       const missing = role.filter((name) => !wallet || typeof wallet[name] !== "function");
       if (missing.length) throw new SdkError("bad-input", { field: "wallet", missing });

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