@ninsei-labs/sdk 0.48.0 → 0.49.0

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.49.0 — 2026-10-21
+
+A ONE-KEY RECOVERY CAN WITHDRAW WITHOUT A FULL SCAN, AND A CLAIM TIP IS CHECKED.
+
+- `findSwaps` accepts `xmrNodes` and `moneroNetwork`: it asks the node for `get_info` and
+  `get_block_header_by_height` itself, so a page needs only `evmBlockTime`; the `startHeight` rule stays in the SDK.
+- `sweep.restore({ window })` sets the wallet at the node tip, scans only the blocks from the swap's start to
+  `t1 + 10` through `scanTxs` (batches of 100), checks the wallet's key images at `/is_key_image_spent`, and does
+  not run `rescanBlockchain` after `scanTxs`. An empty window falls back to the full scan; `windowTxHashes` collects
+  the hashes from a node.
+- `quotes.firm` refuses a `claimTip` above twice the SDK's own `claimGasGiftWei` estimate, read from the new
+  `evmBlock` seam. Zero tips (the buy side) do not call it; an unmeasured base fee is named.
+- `claimTipVerdict` is exported for the same arithmetic outside the quote path.
+- No breaking changes: the old recovery-file path, the full restore and zero-tip quotes behave as before.
+
+## 0.48.1 — 2026-10-21
+
+A SWAP KEEPS ITS MONERO HEIGHT, AND A RECOVERED ORDER KNOWS WHERE TO SCAN.
+
+- `swaps.start` measures the start height from the configured Monero nodes before it hands over recovery data. A
+  node on another network, or no answer at all, is `xmr-no-nodes { step: "restore-height" }`; a swap without a
+  height is not funded.
+- The measured height is kept on the swap record and written into the recovery file. `openWatch` sends that
+  Monero height; the settlement-chain block is named `evmBirthBlock` and stays the bound for the EVM log search.
+- `findSwaps` derives a `startHeight` for every order it finds: the timestamp of the order's block, then the last
+  Monero header at or before it, minus 60 blocks. The readers are seams (`evmBlockTime`, `moneroTip`,
+  `moneroBlockTimestamp`); without them the order comes back with `startHeight: null` and a named reason.
+
 ## 0.48.0 — 2026-10-21
 
 A SWAP CAN START FROM THE ONE RECOVERY KEY.

package/index.d.ts

@@ -108,6 +108,13 @@ export interface NinseiOptions {
    * the order's escrow and the topic is the package's own.
    */
   evmLogs?: EvmLogReader;
+  /**
+   * READING A SETTLEMENT BLOCK FROM OUTSIDE (`(tag) => block`): the claim-tip check needs the chain's current
+   * `baseFeePerGas`. A missing seam is `quote-tip-unchecked` when a quote carries a non-zero tip; zero tips (the
+   * buy side) never call it.
+   */
+  evmBlock?: (tag?: string) => Promise<{ readonly baseFeePerGas?: string | number | bigint | null;
+    readonly baseFeeWei?: string | number | bigint | null }>;
   /**
    * THE INTERFACE'S OWN ADMISSION LIST - policy, not proof. The chain (maker registry, providerOf, taken from the
    * quote) proves whose key signed; this says whom THIS interface trades with at all. An array of provider
@@ -1115,6 +1122,13 @@ 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 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;
+  /** Monero nodes for that one measurement; absent - the configured nodes for the swap's network. */
+  xmrNodes?: readonly (string | { readonly url: string })[];
+  /** The fetch used for the height measurement (tests); absent - the global fetch. */
+  fetchImpl?: typeof fetch;
   /**
    * Hand the key backup to the interface, ONCE, when this call created the key. `true` - the person saved it;
    * `false` - the swap is not started. A key already in the store is not shown again.
@@ -1289,6 +1303,20 @@ export interface SweepRestoreRequest {
   readonly scanBack?: number;
   /** Run the second pass when coins exist but none is spendable. Default true. */
   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`.
+   */
+  readonly window?: {
+    readonly nodeUrl?: string;
+    readonly txHashes?: readonly string[];
+    readonly toHeight: number;
+    readonly tipHeight: number;
+    readonly fallback?: boolean;
+  };
+  /** The fetch used for `get_block`; absent - the global fetch. */
+  readonly fetchImpl?: typeof fetch;
 }
 
 /** What `restore` found. Amounts are atomic units as strings; heights are numbers when the driver can read them. */
@@ -1303,6 +1331,18 @@ export interface SweepRestoreResult {
   readonly passes: number;
   /** Whether the second pass RAN - not whether it helped. */
   readonly lockedPass: boolean;
+  /** Present when a window was requested: whether it was used, and why it was skipped. */
+  readonly window?: {
+    readonly used: boolean;
+    readonly skipped: string | null;
+    readonly fromHeight: number;
+    readonly toHeight: number;
+    readonly blocks: number;
+    readonly txs: number;
+    readonly spent?: number | null;
+    readonly keyImages?: number;
+    readonly spentWhy?: string;
+  } | null;
 }
 
 /** What `wallet` needs: the library namespace and the facts the wallet is built from. */

package/package.json

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

package/src/index.mjs

@@ -91,6 +91,9 @@ const normalizeOptions = (options) => {
   // same provider the chain read uses. Same rule as evmCall: a READ of the escrow's own event, not a node
   // substitution.
   if (o.evmLogs !== undefined && typeof o.evmLogs !== "function") fail("bad-input", { field: "evmLogs" });
+  // THE BLOCK-READ SEAM: the claim tip is checked against the chain's current base fee, and that is a block read,
+  // not an `eth_call`. Same rule as evmCall - brought from outside, refused when it is not a function.
+  if (o.evmBlock !== undefined && typeof o.evmBlock !== "function") fail("bad-input", { field: "evmBlock" });
   // THE INTERFACE'S ALLOW-LIST (POLICY, NOT PROOF): an array of provider addresses (or providerIds) OR a
   // predicate. It is NOT the check itself - that is `providerOf` on chain, taken from the quote - but the
   // interface's own decision about whom it trades with. A wrong shape is a typo, not a silent no-op.
@@ -156,6 +159,7 @@ const normalizeOptions = (options) => {
     evmCall: o.evmCall || null,
     evmCode: o.evmCode || null,
     evmLogs: o.evmLogs || null,
+    evmBlock: o.evmBlock || null,
     allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
     knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
     knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
@@ -215,7 +219,8 @@ export function createNinsei(options) {
     ? new Set(o.denylist.map((a) => String(a).toLowerCase()))
     : null;
   const quotes = createQuotes({ config, http, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
-    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes,
+    evmCode: o.evmCode || null, evmBlock: o.evmBlock || null,
+    providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes,
     denylist });
   // THE SAME CHAIN-READ SEAM AS THE LOCK AND THE CORE: checking the slots and signing must go one way, otherwise
   // part of the check goes past the wallet and part does not.

package/src/public/recovery.d.ts

@@ -327,6 +327,10 @@ export interface FoundSwap {
   readonly logIndex: number | null;
   readonly index: number;
   readonly side: "locker" | "claimer";
+  /** 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;
 }
 
 /** A storage adapter: the same shape the SDK store takes. */
@@ -375,4 +379,17 @@ export declare function findSwaps(request: {
   toBlock?: number | string;
   gap?: number;
   maxIndex?: number;
+  /** Reads the settlement block timestamp, in seconds: (blockNumber) -> seconds. */
+  evmBlockTime?: (blockNumber: number) => Promise<number>;
+  /** The Monero tip at the time of the search: () -> height. */
+  moneroTip?: () => Promise<number>;
+  /** A Monero block header timestamp, in seconds: (height) -> seconds. */
+  moneroBlockTimestamp?: (height: number) => Promise<number>;
+  /** Convenience: the node URLs the caller already probed. When the two Monero readers above are absent, the SDK
+   * asks these for `get_info` and `get_block_header_by_height` itself. */
+  xmrNodes?: readonly (string | { readonly url: string })[];
+  /** The Monero network those nodes must name (mainnet, stagenet, testnet). */
+  moneroNetwork?: string | null;
+  /** The fetch used for those node requests; absent - the global fetch. */
+  fetchImpl?: typeof fetch;
 }): Promise<{ swaps: FoundSwap[]; scanned: number }>;

package/src/quotes.mjs

@@ -18,6 +18,7 @@
 import { fail } from "./errors.mjs";
 import * as engine from "./engine.mjs";
 import { orderQuoteMissingFields, recoverOrderQuoteKey } from "./quoteEip712.mjs";
+import { claimGasGiftWei } from "../engine/evm/claimGas.js";
 // THE CHAIN READ NEEDED TO ASK THE REGISTRY WHO OWNS THE KEY. The selector is COMPUTED from the signature, not
 // remembered: a single wrong hex digit would call another function and return a zero address - and a zero
 // address is exactly the answer "nobody owns this key", which the caller would take as the truth.
@@ -208,7 +209,32 @@ const compactOffer = (o) => ({
 // the price of the failed row to tell the person WHY there is no offer (and not just "none").
 const compactRefusal = (r) => ({ ...compactOffer(r), code: r.code, why: r.why });
 
-export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null }) {
+/**
+ * A CLAIM TIP IS SIZED BY THE CLAIM, NOT BY THE MAKER'S MOOD. The node's own estimate uses the chain's current
+ * base fee and the same formula; a quote may carry up to twice that estimate (gas moves between the sizing and
+ * the check). Zero is the buy side and is always allowed. An unmeasured base fee is a refusal, not a free pass.
+ */
+export function claimTipVerdict({ claimTipWei = 0, baseFeeWei = null, priorityFeeWei = 0, factor = 2 } = {}) {
+  let tip = 0n;
+  try { tip = BigInt(claimTipWei === undefined || claimTipWei === null || claimTipWei === "" ? 0 : claimTipWei); }
+  catch { return { ok: false, code: "quote-tip-unreadable" }; }
+  if (tip < 0n) return { ok: false, code: "quote-tip-unreadable" };
+  if (tip === 0n) return { ok: true, tipWei: "0", ceilingWei: null, estimateWei: null };
+  if (baseFeeWei === null || baseFeeWei === undefined || baseFeeWei === "") {
+    return { ok: false, code: "quote-tip-unchecked", tipWei: tip.toString() };
+  }
+  const estimate = claimGasGiftWei({ baseFeeWei, priorityFeeWei });
+  if (estimate === null) return { ok: false, code: "quote-tip-unchecked", tipWei: tip.toString() };
+  const f = BigInt(factor);
+  const ceiling = estimate * f;
+  if (tip > ceiling) {
+    return { ok: false, code: "quote-tip-too-large", tipWei: tip.toString(), estimateWei: estimate.toString(), ceilingWei: ceiling.toString() };
+  }
+  return { ok: true, tipWei: tip.toString(), estimateWei: estimate.toString(), ceilingWei: ceiling.toString() };
+}
+
+export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, evmBlock = null,
+  providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null }) {
   // THE INTERFACE'S FACTORY POLICY (#103): the code hashes of factories it is willing to trade through
   // (extcodehash semantics = keccak256 of the runtime code). An EMPTY list is "no policy" (like
   // allowedProviders); a NON-EMPTY one refuses any factory whose code is not on it. Lower-cased once.
@@ -507,6 +533,24 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       if (String(quoted) !== expectedContext) {
         fail("quote-refused", { step: "context", why: quoted ? "other-terms" : "not-reported" });
       }
+      // THE CLAIM TIP: the seller pays it out of the payout, so a quote that asks for more than the claim can
+      // cost is refused before it is signed. The chain's base fee is read through the caller's block seam; a
+      // missing seam or an unreadable base fee is a named refusal, never a silently accepted tip.
+      const tipCheck = (() => {
+        try { return claimTipVerdict({ claimTipWei: quote.claimTip }); }
+        catch { return { ok: true, tipWei: "0" }; }
+      })();
+      if (!tipCheck.ok && tipCheck.code === "quote-tip-unreadable") {
+        fail("quote-field-unbound", { step: "claimTip", field: "claimTip" });
+      }
+      if (tipCheck.tipWei !== "0") {
+        if (typeof evmBlock !== "function") fail("quote-tip-unchecked", { step: "claimTip", why: "no-block-read" });
+        let block = null;
+        try { block = await evmBlock("latest"); } catch { fail("quote-tip-unchecked", { step: "claimTip", why: "block-read-failed" }); }
+        const baseFeeWei = block && (block.baseFeePerGas !== undefined ? block.baseFeePerGas : block.baseFeeWei);
+        const verdict = claimTipVerdict({ claimTipWei: quote.claimTip, baseFeeWei });
+        if (!verdict.ok) fail(verdict.code, { step: "claimTip", ...verdict });
+      }
       return quote;
     },
   };

package/src/recovery-key.mjs

@@ -19,6 +19,7 @@ import { createHalves } from "../engine/atomic/halves.js";
 import { halfCommitmentHex } from "../engine/atomic/orderHalfCommit.js";
 import { ORDER_CREATED_TOPIC } from "../engine/evm/factory.js";
 import { SdkError } from "./errors.mjs";
+import { probeMoneroNode } from "./probes.mjs";
 import { ed25519, keccak256, randomBytes, secp256k1 } from "./primitives.mjs";
 
 const halves = createHalves({ ed25519, secp256k1, keccak256, randomBytes });
@@ -396,6 +397,100 @@ async function readLogs(evmLogs, request) {
   return logs;
 }
 
+// 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.
+//
+// The two readers are seams, like evmLogs: the SDK owns the rule, the caller owns the transport. Without them the
+// order is still returned, with startHeight null and a named reason, instead of a guessed height.
+const MONERO_HEIGHT_SAFETY_BLOCKS = 60;
+
+function secondsOf(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return n > 1e12 ? Math.floor(n / 1000) : Math.floor(n);
+}
+
+async function heightAtOrBefore(timestamp, { tip, headerTimestamp }) {
+  const top = Number(await tip());
+  if (!Number.isSafeInteger(top) || top < 0) throw new Error("monero-tip");
+  const at = async (height) => secondsOf(await headerTimestamp(height));
+  const topTime = await at(top);
+  if (topTime !== null && topTime <= timestamp) return top;
+  let low = 0;
+  let high = top;
+  const zeroTime = await at(0);
+  if (zeroTime !== null && zeroTime > timestamp) return 0;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const ts = await at(mid);
+    if (ts === null) throw new Error("monero-header");
+    if (ts <= timestamp) low = mid;
+    else high = mid - 1;
+  }
+  return low;
+}
+
+// THE READERS A CALLER SHOULD NOT HAVE TO BUILD. A page already holds the node URLs it probed; these wrap
+// `get_info` and `get_block_header_by_height` over one of them. The SDK still owns the binary search; only the
+// transport is borrowed.
+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;
+  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;
+  const call = async (method, params) => {
+    let response;
+    try {
+      response = await fetchImpl(node.url + "/json_rpc", {
+        method: "POST", headers: { "content-type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", id: method, method, params }),
+        signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
+      });
+    } catch { throw new Error("monero-unreachable"); }
+    if (!response || response.ok !== true) throw new Error("monero-http");
+    let body = null;
+    try { body = await response.json(); } catch { throw new Error("monero-json"); }
+    if (!body || body.error || !body.result) throw new Error("monero-rpc");
+    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;
+    },
+  };
+}
+
+async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBlockTimestamp, cache }) {
+  if (order.blockNumber === null || order.blockNumber === undefined) {
+    return { startHeight: null, startHeightReason: "no-block-number" };
+  }
+  if (typeof evmBlockTime !== "function" || typeof moneroTip !== "function" || typeof moneroBlockTimestamp !== "function") {
+    return { startHeight: null, startHeightReason: "no-height-readers" };
+  }
+  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" };
+    cache.set(order.blockNumber, timestamp);
+  }
+  try {
+    const height = await heightAtOrBefore(timestamp, { tip: moneroTip, headerTimestamp: moneroBlockTimestamp });
+    return { startHeight: Math.max(0, height - MONERO_HEIGHT_SAFETY_BLOCKS), startHeightReason: null };
+  } catch {
+    return { startHeight: null, startHeightReason: "monero-header" };
+  }
+}
+
 /**
  * Find orders made with this key.
  *
@@ -403,7 +498,10 @@ async function readLogs(evmLogs, request) {
  * search asks for it as the locker and as the claimer (two queries; the RPC topic filter cannot say OR across two
  * 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 } = {}) {
+export async function findSwaps({ mnemonic, chainId, factory, address = null, evmLogs,
+  fromBlock = 0, toBlock = "latest", gap = 5, maxIndex = 1000,
+  evmBlockTime = 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;
@@ -446,5 +544,17 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
       found.push({ ...order, index, side: order.commitHalfLocker.toLowerCase() === own.spendCommitment.toLowerCase() ? "locker" : "claimer" });
     }
   }
+  // EACH FOUND ORDER CARRIES THE MONERO HEIGHT ITS WITHDRAWAL MAY START FROM. The rule lives here, not in a
+  // page: a widget and the recovery page must not derive two different answers from one chain.
+  const cache = new Map();
+  let tip = moneroTip;
+  let header = moneroBlockTimestamp;
+  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; }
+  }
+  for (const order of found) {
+    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip: tip, moneroBlockTimestamp: header, cache }));
+  }
   return { swaps: found, scanned };
 }

package/src/swaps.mjs

@@ -19,6 +19,7 @@ import { vmOfChain, legFor } from "./legs/index.mjs";
 // THE VIEW HALVES - from the core's primitives: the sum of two halves is the key the wallet sees incoming payments
 // with. There is no arithmetic of the core's own here either (see order.mjs) - we use the same halves builder.
 import { primitives } from "./primitives.mjs";
+import { probeMoneroNode } from "./probes.mjs";
 // MARKING READY - A FINISHED STEP, NOT A SECOND IMPLEMENTATION OF IT: it requires the order expectations and checks
 // the slots against the chain BEFORE signing (actions.markReady). The watch must call exactly it, otherwise "we saw
 // the XMR" and "we allowed the settlement to be taken" would diverge.
@@ -306,6 +307,24 @@ const recordInputOf = (request) => {
 // createRecord is the start step that requires a Monero wallet IN THE BROWSER (creating the wallet and the order of
 // the halves). It arrives from outside, so the whole path after it (building the file, encryption, the person's
 // confirmation) is written and checked already now, rather than appearing together with the browser part.
+/**
+ * The Monero height a swap starts at, measured from the configured nodes. Exported for the guard, not as a
+ * package entry: the start is the only production caller. A node that answers on another network is not a height
+ * for this deal, and a missing answer is a named refusal, never a scan from zero.
+ */
+export async function startHeightFromNodes({ nodes = [], network = null, fetchImpl = globalThis.fetch } = {}) {
+  const urls = (Array.isArray(nodes) ? nodes : [])
+    .map((entry) => typeof entry === "string" ? entry : entry && entry.url).filter(Boolean);
+  const answers = await Promise.all(urls.map(async (url) => {
+    try { return await probeMoneroNode({ url, fetchImpl }); }
+    catch { return { ok: false, why: "unreachable" }; }
+  }));
+  const good = answers.find((answer) => answer.ok === true && (!network || answer.network === network));
+  if (good) return good.height;
+  const why = answers.find((answer) => answer.ok === true) ? "network" : (answers[0] && answers[0].why) || "no-node";
+  throw new SdkError("xmr-no-nodes", { step: "restore-height", network: network || null, why });
+}
+
 export function createSwaps({ preflight, http, createRecord, mode = null, xmrNetwork = null, call = null,
   // THE PATHS AND LIMITS ARE BROUGHT BY THE CONFIGURATION: the "server" step's paths are named by names (config.route),
   // and the timeout and rate of the watch polling - in config.limits. Without the configuration the step answers with a
@@ -342,6 +361,18 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
     const value = config && config.limits ? config.limits[name] : null;
     return Number.isFinite(Number(value)) && Number(value) > 0 ? Number(value) : fallback;
   };
+
+  // THE MONERO HEIGHT A SWAP STARTS AT. It is measured before the recovery data is handed over: a file without
+  // it scans Monero from block zero, and a watch opened at an EVM block sees nothing. The node must name the same
+  // network as the swap; a different network is not a height for this deal.
+  async function measuredStartHeight(request, moneroNetwork) {
+    const explicit = Number(request.restoreHeight);
+    if (Number.isSafeInteger(explicit) && explicit > 0) return explicit;
+    const listed = Array.isArray(request.xmrNodes) ? request.xmrNodes
+      : (config && typeof config.nodesFor === "function" ? config.nodesFor(moneroNetwork) : []);
+    return startHeightFromNodes({ nodes: listed, network: moneroNetwork,
+      fetchImpl: request.fetchImpl || (typeof fetch === "function" ? fetch : null) });
+  }
   const records = () => {
     const state = engine.store.loadState();
     const all = Object.values((state && state.swaps) || {}).filter((s) => s && s.id);
@@ -454,11 +485,15 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
     if (!(expectedXmr > 0)) throw new SdkError("bad-input", { field: "expectedAmountXmr" });
     const network = swap.moneroNetwork || xmrNetwork || null;
     if (!network) throw new SdkError("bad-input", { field: "moneroNetwork" });
+    const restoreHeight = Number(swap.restoreHeight) > 0 ? Number(swap.restoreHeight)
+      : (Number(e.moneroRestoreHeight) > 0 ? Number(e.moneroRestoreHeight) : null);
+    if (!(restoreHeight > 0)) throw new SdkError("bad-input", { field: "restoreHeight", step: "watch" });
     const wanted = {
       swapId: swap.id || null, network, address, viewKey: jointViewKey(swap), expectedAmountXmr: expectedXmr,
-      // THE RESTORE HEIGHT - FROM THE SWAP RECORD (the order puts it there), not invented: a scan from zero would take
-      // tens of hours, and the arrivals would not be visible in a reasonable time.
-      restoreHeight: Number(e.birthHeight) > 0 ? Number(e.birthHeight) : null,
+      // THE RESTORE HEIGHT - THE MONERO HEIGHT, NEVER THE EVM BLOCK. It is measured before the file is handed
+      // over and kept on the record; `birthHeight`/`evmBirthBlock` is a settlement-chain block for log search and
+      // is far above any Monero tip, so using it here opened the watch nowhere near the money.
+      restoreHeight,
       chain: swap.network || swap.chain || null,
     };
     const body = {};
@@ -819,6 +854,15 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         builtSide = step;
       }
 
+      // THE HEIGHT IS MEASURED BEFORE THE FILE OR THE WATCH: the node is asked once, while the swap is still in
+      // front of us. A swap without it is not funded - a recovery file that scans from zero is a file that looks
+      // usable and is not.
+      const measuredHeight = await measuredStartHeight(request, record.swap.moneroNetwork || xmrNetwork || null);
+      record.swap.restoreHeight = measuredHeight;
+      record.restoreHeight = measuredHeight;
+      record.swap.escrow = { ...(record.swap.escrow || {}), moneroRestoreHeight: measuredHeight };
+      try { engine.swap.saveSwap(record.swap); } catch { throw new SdkError("storage-unavailable", { step: "save-restore-height" }); }
+
       // 2a. THE KEY IS CONFIRMED ONCE; THE OLD PATH STILL ASSEMBLES A PER-SWAP FILE. On the key path there is
       // no file per swap: the same twelve words cover every swap, and a person who already saved them is not
       // asked again. A new key is shown before the money moves - no saved key, no funding.
@@ -911,8 +955,10 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       if (escrowAddress) {
         const escrowRecord = record.swap.escrow && typeof record.swap.escrow === "object" ? record.swap.escrow : {};
         record.swap.escrow = { ...escrowRecord, address: escrowAddress,
-          // THE FUNDING HEIGHT - FROM THE RECEIPT: the XMR watch and the recovery file take it from here.
-          birthHeight: Number(funded.birthBlock) > 0 ? Number(funded.birthBlock) : (escrowRecord.birthHeight ?? null) };
+          // THE SETTLEMENT-CHAIN HEIGHT, NAMED AS SUCH. It is for the OrderCreated/Declined log search; the XMR
+          // watch and the recovery file take the Monero height measured above. The old name `birthHeight` stays
+          // readable on records written before this split.
+          evmBirthBlock: Number(funded.birthBlock) > 0 ? Number(funded.birthBlock) : (escrowRecord.evmBirthBlock ?? escrowRecord.birthHeight ?? null) };
         try { engine.swap.saveSwap(record.swap); } catch { throw new SdkError("storage-unavailable", { step: "save-escrow" }); }
         // THE NUMBER IS SPENT ONLY NOW, WHEN THE ORDER EXISTS ON CHAIN. A failed or abandoned start keeps the
         // reservation, so a retry uses the same number and the later search has no gap.
@@ -1009,7 +1055,8 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       const escrowAddress = request.escrow || (record && record.escrow && record.escrow.address) || null;
       // FROM THE ESCROW'S BIRTH HEIGHT when the record knows it: the event cannot be older than the funding, and
       // walking the whole chain every tick is a cost with no answer behind it.
-      const fromBlock = blockBoundaryOf(record && record.escrow ? record.escrow.birthHeight : null);
+      const fromBlock = blockBoundaryOf(record && record.escrow
+        ? (record.escrow.evmBirthBlock ?? record.escrow.birthHeight) : null);
       const chainDecline = { checked: false, error: null, logs: undefined };
       const readDeclineLogs = async () => {
         chainDecline.checked = false; chainDecline.error = null; chainDecline.logs = undefined;

package/src/sweep-restore.mjs

@@ -62,6 +62,45 @@ 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 } = {}) {
+  let base = typeof nodeUrl === "string" ? nodeUrl.trim() : "";
+  while (base.endsWith("/")) base = base.slice(0, -1);
+  const from = Number(fromHeight);
+  const to = Number(toHeight);
+  if (!base) throw new SdkError("bad-input", { field: "window.nodeUrl" });
+  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 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 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" });
+    const result = body.result;
+    let list = Array.isArray(result.tx_hashes) ? result.tx_hashes : null;
+    if (!list && typeof result.json === "string") {
+      try {
+        const json = JSON.parse(result.json);
+        list = Array.isArray(json.tx_hashes) ? json.tx_hashes : null;
+      } catch { list = null; }
+    }
+    if (!list) throw new SdkError("wallet-rejected", { surface: "window-blocks", height, why: "no-tx-hashes" });
+    hashes.push(...list.map(String));
+  }
+  return hashes;
+}
+
 /**
  * Restore the wallet from a height and report what it holds.
  *
@@ -88,6 +127,71 @@ export async function restoreWallet(request = {}) {
   const scanHeight = Math.max(0, Math.floor(fromHeight) - scanBack);
   const driver = driverOf(wallet);
 
+  // THE WINDOW PATH: set the wallet at the node tip, scan the lock's blocks, and only fall back to a full scan
+  // when that window holds nothing. An empty window is "not found", not "no funds".
+  const requestWindow = request.window && typeof request.window === "object" ? request.window : null;
+  let windowReport = null;
+  let windowTotal = 0n;
+  let windowUnlocked = 0n;
+  if (requestWindow) {
+    const tipHeight = Number(requestWindow.tipHeight);
+    if (!Number.isSafeInteger(tipHeight) || tipHeight <= 0) throw new SdkError("bad-input", { field: "window.tipHeight" });
+    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,
+      });
+    }
+    windowReport = { used: false, skipped: null, fromHeight, toHeight: Number(requestWindow.toHeight),
+      blocks: Math.max(0, Number(requestWindow.toHeight) - fromHeight + 1), 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;
+      // 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") {
+        try {
+          const exported = await driver.getKeyImages();
+          const images = Array.isArray(exported) ? exported
+            : (exported && typeof exported.getKeyImages === "function" ? exported.getKeyImages() : []);
+          const hexes = images.map((image) => typeof image === "string" ? image
+            : (image && typeof image.getHex === "function" ? image.getHex() : image && image.hex)).filter(Boolean);
+          if (hexes.length) {
+            let base = String(requestWindow.nodeUrl);
+            while (base.endsWith("/")) base = base.slice(0, -1);
+            const response = await (request.fetchImpl || globalThis.fetch)(base + "/is_key_image_spent", {
+              method: "POST", headers: { "content-type": "application/json" },
+              body: JSON.stringify({ key_images: hexes }),
+              signal: typeof AbortSignal !== "undefined" && AbortSignal.timeout ? AbortSignal.timeout(8000) : undefined,
+            });
+            const body = response && response.ok === true ? await response.json() : null;
+            if (body && Array.isArray(body.spent_status)) {
+              windowReport.spent = body.spent_status.filter((value) => value === true || value === 1).length;
+              windowReport.keyImages = hexes.length;
+            } 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) {
+        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) {
+        return {
+          total: windowTotal.toString(), unlocked: windowUnlocked.toString(), scanHeight, walletHeight: await heightOf(driver, "getHeight"),
+          nodeHeight: await heightOf(driver, "getDaemonHeight"), passes: 1, lockedPass: false, window: windowReport,
+        };
+      }
+    } else if (hashes.length) {
+      windowReport.skipped = "no-scan-txs";
+    }
+  }
+
   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.
@@ -129,5 +233,6 @@ export async function restoreWallet(request = {}) {
     // Whether the second pass RAN - not whether it helped. A reader must be able to tell "nothing was locked" from
     // "it was locked and stayed locked".
     lockedPass,
+    window: windowReport,
   };
 }

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