@ninsei-labs/sdk 0.47.0 → 0.48.1

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 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.
+
+- `swaps.start` accepts `recoveryKey` (a BIP39 mnemonic or a key object). It derives the spend and view halves
+  for the reserved swap number instead of generating a random pair, and writes no per-swap recovery file.
+- A key created by the call is handed to `onRecoveryKey` once, before the funds are locked; a key already in the
+  store is not shown again. The number is reserved before the order and retired only after the escrow exists.
+- The old path is unchanged: without `recoveryKey`, `onRecoveryFile` still assembles and confirms a per-swap file.
+- `buildOwnSideFromHalves` builds the order side and its DLEQ proof from supplied halves; `createRecord` accepts
+  that side, so the recovery key remains the only taker secret.
+
 ## 0.47.0 — 2026-10-21
 
 ONE RECOVERY KEY, AND THE NODE'S VIEW HALF COMES FROM IT.

package/index.d.ts

@@ -717,7 +717,7 @@ export interface SwapsApi {
   /**
    * Start a swap. The SDK holds the step order, not the screen:
    *   1) guards (preflight); 2) the swap record (createSwap); 3) the order - it GENERATES the key halves;
-   *   4) the recovery file and the interface's confirmation that the file is saved; 5) locking the funds (signature);
+   *   4) the recovery file / one key and the interface's confirmation that it is saved; 5) locking the funds (signature);
    *   6) saving on the server; 7) opening the watch on the Monero address.
    * HALVES DO NOT EXIST BEFORE THE ORDER: the recovery file carries MY half of the spend key and the counterparty's
    * open points, and they are taken from the signed order (www/js/atomic/order-worker.js, createOrderBuilder; in the
@@ -1102,10 +1102,31 @@ export interface StartRequest {
    */
   readonly wallet?: WalletAdapter;
   /**
-   * Hand the recovery file to the interface and wait for the person's decision.
+   * Hand the OLD per-swap recovery file to the interface and wait for the person's decision.
    * `true` - the person confirmed the file is saved; `false` - the swap is not started.
+   * Not used when `recoveryKey` is present: that path has one key, saved once.
    */
-  onRecoveryFile(file: RecoveryFile): Promise<boolean>;
+  onRecoveryFile?(file: RecoveryFile): Promise<boolean>;
+  /**
+   * THE ONE RECOVERY KEY (sdk#76). A BIP39 mnemonic, or a key object from `@ninsei-labs/sdk/recovery`.
+   * When present, the swap's spend and view halves are derived from it instead of being generated, and no
+   * per-swap recovery file is written. The key is kept through the SDK's storage adapter.
+   */
+  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.
+   */
+  onRecoveryKey?(file: RecoveryFile): Promise<boolean>;
 }
 
 export interface RecoveryFile {

package/package.json

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

package/src/order.mjs

@@ -97,6 +97,29 @@ export function buildOwnSide(order, onBit) {
   return { context, side, spendPoint: norm(side.pub.ed), viewPoint: norm(side.viewPub), encPub: norm(side.enc.pub) };
 }
 
+/**
+ * OUR SIDE FROM HALVES WE ALREADY HAVE - the one recovery key case. A random side would be a second secret,
+ * which is exactly what one key removes. The proof is still bound to this order and built by the same engine
+ * builder; only the source of the two numbers changes.
+ */
+export function buildOwnSideFromHalves(order, { spendHalf, viewHalf } = {}) {
+  const context = contextOf(order);
+  const b = builder();
+  const scalar = (value, name) => {
+    const n = BigInt(value);
+    if (n <= 0n || n >= BigInt(b.halves.LIMIT)) throw new SdkError("bad-input", { field: name });
+    return n;
+  };
+  const half = scalar(spendHalf, "spendHalf");
+  const view = scalar(viewHalf, "viewHalf");
+  const pub = b.halves.publicHalves(half);
+  const viewPub = b.halves.publicHalves(view).ed;
+  const encPair = b.enc.recipientKeyPair();
+  const proof = b.dleq.prove(half, context);
+  const side = { half, pub, viewHalf: view, viewPub, enc: encPair, proof, standIn: false };
+  return { context, side, spendPoint: norm(pub.ed), viewPoint: norm(viewPub), encPub: norm(encPair.pub) };
+}
+
 /**
  * The counterparty's side: accept and verify. The check is ONE for both sides and is done by the engine
  * (order.js, verifySide): the proof stands in the CONTEXT OF THIS order, the proven point matches the one that

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,10 @@ 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>;
 }): Promise<{ swaps: FoundSwap[]; scanned: number }>;

package/src/record.mjs

@@ -14,7 +14,7 @@
 import { SdkError } from "./errors.mjs";
 import { primitives } from "./primitives.mjs";
 import * as engine from "./engine.mjs";
-import { buildOwnSide, halfHex, norm } from "./order.mjs";
+import { buildOwnSide, buildOwnSideFromHalves, halfHex, norm } from "./order.mjs";
 
 /**
  * Our side. Without order terms - only the halves and their points (a shape of the record; there is no proof and
@@ -23,7 +23,11 @@ import { buildOwnSide, halfHex, norm } from "./order.mjs";
  * THE HALF NAMES ARE THE ENGINE'S: the half is returned in the engine's form (BigInt), and it goes into the
  * record as a hex string, because a BigInt survives neither storage nor the recovery file's JSON.
  */
-export function ownSide(order = null) {
+export function ownSide(order = null, known = null) {
+  if (known && known.spendHalf && known.viewHalf) {
+    const built = buildOwnSideFromHalves(order, known);
+    return built.side;
+  }
   if (order !== null && order !== undefined) {
     const built = buildOwnSide(order);
     return built.side;
@@ -40,9 +44,9 @@ export function ownSide(order = null) {
  * edPointLocker, edViewPointLocker). The counterparty's half cannot and need not be put in: it will come from
  * the order.
  */
-export function createRecord(input, { order = null } = {}) {
+export function createRecord(input, { order = null, side: knownSide = null } = {}) {
   if (!input || typeof input !== "object") throw new SdkError("bad-input", { field: "input" });
-  const side = ownSide(order);
+  const side = knownSide || ownSide(order);
   let swap = null;
   try { swap = engine.swap.createSwap(input); } catch { throw new SdkError("bad-input", { field: "input" }); }
   const escrow = { ...(swap.escrow || {}),

package/src/recovery-key.mjs

@@ -396,6 +396,61 @@ 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;
+}
+
+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 +458,9 @@ 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 } = {}) {
   if (typeof factory !== "string" || !ADDRESS_RE.test(factory)) throw bad("factory");
   const chain = numberField(chainId, "chainId");
   const max = numberField(maxIndex, "maxIndex") || 1000;
@@ -446,5 +503,11 @@ 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();
+  for (const order of found) {
+    Object.assign(order, await recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBlockTimestamp, cache }));
+  }
   return { swaps: found, scanned };
 }

package/src/swaps.mjs

@@ -12,17 +12,23 @@ import * as engine from "./engine.mjs";
 import * as recordModule from "./record.mjs";
 // The order: our own side is built by the engine's builder, the counterparty's side is verified and accepted, and
 // the joint address is assembled from the halves. There are no formulas of our own in the core - see order.mjs.
-import { contextOf, orderStep } from "./order.mjs";
+import { buildOwnSideFromHalves, contextOf, orderStep } from "./order.mjs";
 // Locking the funds: sending goes through the already-finished step (`lock.send`), the wallet is an adapter from outside.
 import * as lock from "./lock.mjs";
 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.
 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,
+} 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";
 // THE MAKER'S DECLINE (issue #40): the escrow's `Declined` event and the node's `declined` + `compliance` status
@@ -301,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
@@ -337,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);
@@ -449,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 = {};
@@ -705,7 +745,9 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
     async start(request) {
       if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
       if (!request.quote || typeof request.quote !== "object") throw new SdkError("bad-input", { field: "quote" });
-      if (typeof request.onRecoveryFile !== "function") throw new SdkError("bad-input", { field: "onRecoveryFile" });
+      // THE OLD PATH IS UNCHANGED; THE NEW ONE ASKS FOR A KEY INSTEAD OF A PER-SWAP FILE.
+      const wantsKey = request.recoveryKey !== undefined && request.recoveryKey !== null;
+      if (!wantsKey && typeof request.onRecoveryFile !== "function") throw new SdkError("bad-input", { field: "onRecoveryFile" });
       if (!request.receiveTo || typeof request.receiveTo !== "string") throw new SdkError("bad-input", { field: "receiveTo" });
       // THE ORDER CONTEXT IS MANDATORY AND NOT INVENTED. It is assembled by the engine FROM THE VERY FIELDS the firm
       // quote's signature is bound to (orderContext.js, FIELDS), because the DLEQ proof proves a half FOR THESE TERMS.
@@ -734,8 +776,9 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       // record, and our side of the order is computed from the core's primitives.
       // THE RECORD IS CREATED TOGETHER WITH OUR SIDE: the order terms go into it, and the side is built by the engine's
       // builder (with the DLEQ proof and the encryption key), not by the core's own arithmetic.
+      let keySide = null;
       const makeRecord = typeof createRecord === "function" ? createRecord
-        : async (req) => recordModule.createRecord(recordInputOf(req), { order: req.order });
+        : async (req) => recordModule.createRecord(recordInputOf(req), { order: req.order, side: keySide });
       const passphrase = typeof request.passphrase === "string" ? request.passphrase : "";
       if (typeof passphrase !== "string") throw new SdkError("bad-input", { field: "passphrase" });
       if (passphrase.length > 0 && passphrase.length < MIN_PASSPHRASE) throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
@@ -744,6 +787,32 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       // values: the DLEQ proof would then be bound to nothing.
       const orderContext = contextOf(request.order);
 
+      // THE KEY RECORD, THE NUMBER AND THE SIDE. A key is made once and kept through the SDK's store; the
+      // number is reserved before the order is built, and it is retired only after the order exists on chain.
+      // No per-swap file is assembled on this path.
+      let recovery = null;
+      if (wantsKey) {
+        const storage = engine.store.storage();
+        const supplied = typeof request.recoveryKey === "string"
+          ? request.recoveryKey
+          : request.recoveryKey && typeof request.recoveryKey.mnemonic === "string" ? request.recoveryKey.mnemonic : null;
+        const saved = loadRecoveryKey(storage);
+        if (saved && supplied && saved.mnemonic !== supplied) {
+          throw new SdkError("bad-input", { field: "recoveryKey", why: "different-key" });
+        }
+        if (!saved && !supplied) throw new SdkError("bad-input", { field: "recoveryKey" });
+        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);
+        if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "recoveryIndex" });
+        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 };
+      }
+
       let made = null;
       try { made = await makeRecord(request); } catch (error) {
         // THE CODE MATTERS, NOT THE CLASS: an error with a code (including from another instance of the module) passes
@@ -785,26 +854,51 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         builtSide = step;
       }
 
-      // 2a. THE RECOVERY FILE IS ASSEMBLED AND CHECKED BEFORE THE PERSON. A file that will not open is worse than no
-      // file: the person will rely on it. So we check on our side, before the screen.
-      let payload = null;
-      try {
-        payload = engine.recoveryFile.buildPayload({
-          swap: record.swap, swapWallet: record.swapWallet, escrow: record.escrow,
-          receiveAddress: record.receiveTo || request.receiveTo, restoreHeight: record.restoreHeight ?? null,
-        });
-        engine.recoveryFile.validatePayload(payload);
-      } catch { throw new SdkError("recovery-failed", { step: "build-payload" }); }
+      // 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.
+      let payload = null;
       let file = null;
-      try {
-        file = { name: engine.recoveryFile.recoveryFileName(payload.swapId), contents: await engine.recoveryFile.createRecoveryFile(payload, passphrase) };
-      } catch { throw new SdkError("recovery-failed", { step: "encrypt" }); }
+      let confirmed = true;
+      if (!recovery) {
+        // THE RECOVERY FILE IS ASSEMBLED AND CHECKED BEFORE THE PERSON. A file that will not open is worse than no
+        // file: the person will rely on it. So we check on our side, before the screen.
+        try {
+          payload = engine.recoveryFile.buildPayload({
+            swap: record.swap, swapWallet: record.swapWallet, escrow: record.escrow,
+            receiveAddress: record.receiveTo || request.receiveTo, restoreHeight: record.restoreHeight ?? null,
+          });
+          engine.recoveryFile.validatePayload(payload);
+        } catch { throw new SdkError("recovery-failed", { step: "build-payload" }); }
 
-      // 3. THE PERSON'S CONFIRMATION - THE GATE. No action that locks funds goes earlier: otherwise the lock would end
-      // up without a key if the browser is lost. "Did not answer" is a refusal, not consent.
-      const confirmed = await request.onRecoveryFile(file);
-      if (confirmed !== true) throw new SdkError("recovery-declined", { swapId: payload.swapId });
+        try {
+          file = { name: engine.recoveryFile.recoveryFileName(payload.swapId), contents: await engine.recoveryFile.createRecoveryFile(payload, passphrase) };
+        } catch { throw new SdkError("recovery-failed", { step: "encrypt" }); }
+
+        // 3. THE PERSON'S CONFIRMATION - THE GATE. No action that locks funds goes earlier: otherwise the lock would end
+        // up without a key if the browser is lost. "Did not answer" is a refusal, not consent.
+        confirmed = await request.onRecoveryFile(file);
+        if (confirmed !== true) throw new SdkError("recovery-declined", { swapId: payload.swapId });
+      } else if (recovery.newKey) {
+        if (typeof request.onRecoveryKey !== "function") throw new SdkError("bad-input", { field: "onRecoveryKey" });
+        try {
+          file = {
+            name: recoveryKeyFileName(recovery.key),
+            contents: await createRecoveryKeyFile({ mnemonic: recovery.key.mnemonic, createdAt: recovery.key.createdAt, passphrase }),
+          };
+        } catch { throw new SdkError("recovery-failed", { step: "encrypt-key" }); }
+        confirmed = await request.onRecoveryKey(file);
+        if (confirmed !== true) throw new SdkError("recovery-declined", { key: recovery.key.fingerprint });
+      }
 
       // 4. LOCKING THE FUNDS. The wallet comes FROM OUTSIDE (an adapter with `send`/`receipt`): signing is possible only
       // in it, and the core keeps no path into the chain of its own. The absence of a wallet is a REFUSAL WITH A CODE,
@@ -861,9 +955,16 @@ 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.
+        if (recovery) {
+          try { commitRecoveryIndex(recovery.storage, recovery.index); } catch { /* the reservation stays; the key still works */ }
+        }
       }
 
       // 5. THE SERVER: RECORDING THE SWAP WITH US, THEN THE FACTORY WATCH RECORD FOR THE MONERO ADDRESS.
@@ -954,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/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.47.0";
+export const SDK_VERSION = "0.48.1";