@ninsei-labs/sdk 0.48.0 → 0.48.1

package/CHANGELOG.md

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

@@ -1115,6 +1115,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.

package/package.json

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

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/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

@@ -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/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.48.1";