@ninsei-labs/sdk 0.43.3 → 0.44.0

package/src/destination.mjs

@@ -0,0 +1,46 @@
+// WHERE THE WITHDRAWAL GOES, AND WHETHER THAT IS WHO THE FILE PROMISED.
+//
+// The recovery file names the recipient the swap was made for. The page compared the address the person typed with
+// the file's and showed a warning - a rule about the file, implemented in the interface that happens to read it.
+// The comparison is not presentation: sending XMR to another address is a different payment.
+//
+// THE SHAPE IS CHECKED AGAINST THE FILE'S NETWORK. A stagenet file and a mainnet address is not "close enough": the
+// transfer would go to another chain. The checksum is checked when the library is available; when it is not, the
+// answer says so (`verified: false`) instead of pretending.
+//
+// A FILE WITHOUT A PROMISED ADDRESS IS NOT A FAILURE: `matches` is null, and the caller decides what to say.
+import { checkAddress } from "../engine/monero/address.js";
+
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+
+/** The address the file promised, if it named one. */
+export function promisedAddress(payload) {
+  const receive = payload && payload.receive;
+  const named = receive && typeof receive.address === "string" ? receive.address.trim() : "";
+  return named || null;
+}
+
+/**
+ * Compare a destination with the file's promise.
+ *
+ * `ok` answers "is this a usable address on the file's network"; `matches` answers "is it the promised one" and is
+ * null when the file named none. `reason` is the library's own phrase when the shape is wrong.
+ */
+export async function checkDestination(payload, dest) {
+  const address = text(dest);
+  const promised = promisedAddress(payload);
+  const network = (payload && payload.moneroWallet && payload.moneroWallet.network) || null;
+  if (!address) {
+    return { ok: false, dest: address, promised, matches: promised === null ? null : false, network, verified: false, reason: "no address" };
+  }
+  const shape = await checkAddress(address, network ? { expectNetwork: network } : {});
+  return {
+    ok: shape.ok === true,
+    dest: address,
+    promised,
+    matches: promised === null ? null : address === promised,
+    network,
+    verified: shape.verified === true,
+    reason: shape.reason || null,
+  };
+}

package/src/feeEstimate.mjs

@@ -0,0 +1,80 @@
+// WHAT A TRANSACTION WILL COST, ASKED FROM THE NODE THAT WILL CARRY IT.
+//
+// THE FEE = THE PRICE OF A BYTE × THE SIZE OF THE TRANSACTION. The price belongs to the network, not to the wallet:
+// on Monero it moves with the median block load, so it is not set but ASKED - `get_fee_estimate` returns a price per
+// kilobyte for several priorities. The size is known only after the transaction is assembled (rings, inputs, outputs),
+// so this module answers the PRICE, and `feeForBytes` is the only arithmetic that turns it into a sum.
+//
+// The page used to learn the fee only after signing; a person deciding whether to withdraw should see it before.
+//
+// THE DAEMON ANSWERS IN snake_case AND THE LIBRARY RENAMES IT - both forms are accepted. A field the node did not send
+// is null, never zero: zero is a legal price and would read as a free transaction.
+const DEFAULT_TIMEOUT_MS = 8000;
+
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+
+/** A per-KB price -> the fee for a transaction of `bytes`, rounded UP: one unit short is still short. */
+export function feeForBytes(feePerKB, bytes) {
+  let perKB;
+  let size;
+  try { perKB = BigInt(feePerKB); size = BigInt(bytes); } catch { throw new RangeError("feeForBytes: whole numbers only"); }
+  if (perKB < 0n || size < 0n) throw new RangeError("feeForBytes: negative input");
+  return ((perKB * size + 1023n) / 1024n).toString();
+}
+
+const atomicField = (source, ...names) => {
+  for (const name of names) {
+    const value = source[name];
+    if (value === undefined || value === null || value === "") continue;
+    try { return BigInt(value).toString(); } catch { continue; }
+  }
+  return null;
+};
+
+/**
+ * ASK A NODE WHAT A TRANSACTION WILL COST.
+ *
+ * The answer is a price per kilobyte (and the median, and the daemon's own priority list). The exact sum needs the
+ * assembled transaction; `feeForBytes` is the arithmetic that gets there. Never throws - a refusal names the problem.
+ */
+export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  // TRAILING SLASHES WITHOUT A REGEX: a pattern anchored on a run of slashes is flagged as a slow expression on
+  // hostile input, and this value can be typed by a person.
+  let base = text(url);
+  while (base.endsWith("/")) base = base.slice(0, -1);
+  if (!base) return { ok: false, why: "no-url" };
+  if (typeof fetchImpl !== "function") return { ok: false, why: "no-fetch" };
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), Math.max(1, Number(timeoutMs) || DEFAULT_TIMEOUT_MS)) : null;
+  let response;
+  try {
+    response = await fetchImpl(base + "/json_rpc", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: "0", method: "get_fee_estimate" }),
+      signal: controller ? controller.signal : undefined,
+    });
+  } catch (error) {
+    const aborted = error && (error.name === "AbortError" || error.code === "ABORT_ERR");
+    return { ok: false, why: aborted ? "timeout" : "unreachable" };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  if (!response || !response.ok) return { ok: false, why: "http", status: response ? response.status : null };
+  let body = null;
+  try { body = await response.json(); } catch { return { ok: false, why: "not-json" }; }
+  if (!body || body.error) return { ok: false, why: "rpc", rpc: body && body.error ? body.error.code ?? null : null };
+  const result = body.result || {};
+  const feePerKB = atomicField(result, "fee_per_kb", "feePerKB");
+  const medianFeePerKB = atomicField(result, "median_fee_per_kb", "medianFeePerKB");
+  const list = result.fees ?? result.feesPerKB ?? null;
+  let perPriority = null;
+  if (Array.isArray(list)) {
+    perPriority = [];
+    for (const value of list) {
+      try { perPriority.push(BigInt(value).toString()); } catch { perPriority = null; break; }
+    }
+  }
+  if (feePerKB === null && medianFeePerKB === null && !perPriority) return { ok: false, why: "no-estimate" };
+  return { ok: true, url: base, feePerKB, medianFeePerKB, perPriority };
+}

package/src/index.mjs

@@ -19,7 +19,7 @@ import { contextOf, verifyCounterparty, jointAddress } from "./order.mjs";
 import * as orderFlow from "./swap-flow.mjs";
 import { createSweep } from "./sweep.mjs";
 import { SdkError, fail } from "./errors.mjs";
-import { ERROR_CODES, STEP_CODES, CHECK_CODES } from "./codes.mjs";
+import { ERROR_CODES, ERROR_META, ERROR_SIDES, STEP_CODES, CHECK_CODES } from "./codes.mjs";
 
 // A surface declared by the contract but answering with a code: that is more honest than returning an empty
 // value that looks like data. The stage number is named so the interface understands what to expect
@@ -232,7 +232,7 @@ export function createNinsei(options) {
     config,
     wallet,
     preflight,
-    recovery: createRecovery(),
+    recovery: createRecovery({ http, config }),
 
     // THE ORDER: checking the counterparty's side and the joint address. Both checks - BEFORE signing: after it
     // there is nothing to fix.
@@ -288,7 +288,7 @@ export function createNinsei(options) {
   });
 }
 
-export { SdkError, ERROR_CODES, STEP_CODES, CHECK_CODES };
+export { SdkError, ERROR_CODES, ERROR_META, ERROR_SIDES, STEP_CODES, CHECK_CODES };
 export { SDK_VERSION } from "./version.mjs";
 
 // THE LEVEL WALK IS ON THE PACKAGE SURFACE. A maker publishes a level set (chunks of volume with their own prices)

package/src/probes.mjs

@@ -0,0 +1,73 @@
+// IS THE NODE A WITHDRAWAL CAN USE, AND WHAT DOES IT SAY ABOUT ITSELF.
+//
+// The sweep page ran its own preflight: a request to get_info, a check for the height, a guess about the network.
+// Every interface that withdraws needs the same answer, and a preflight that disagrees with the wallet builder is a
+// page that says "ready" and then fails to open a wallet.
+//
+// ONE REQUEST, ONE ANSWER. `get_info` is what the node can be asked without a wallet: height, nettype, sync state and
+// version. The answer names WHY it is not usable instead of a bare false - "unreachable" and "this node reports an
+// unknown network" are different problems for the person.
+//
+// A TIMEOUT IS A REFUSAL, NOT A HANG: the request is abandoned after `timeoutMs` (8 seconds by default).
+import { networkFromNode } from "../engine/monero/nodeNetwork.js";
+
+const DEFAULT_TIMEOUT_MS = 8000;
+
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+
+/**
+ * Ask a Monero node for `get_info`.
+ *
+ * `fetchImpl` is injected (the browser's `fetch` by default) so a Node consumer and a test can pass their own.
+ * The answer never throws: `{ ok: false, why }` names the problem.
+ */
+export async function probeMoneroNode({ url, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  // TRAILING SLASHES WITHOUT A REGEX: a pattern anchored on a run of slashes is flagged as a slow expression on
+  // input a person can type, and this address is exactly that.
+  let base = text(url);
+  while (base.endsWith("/")) base = base.slice(0, -1);
+  if (!base) return { ok: false, why: "no-url" };
+  if (typeof fetchImpl !== "function") return { ok: false, why: "no-fetch" };
+  const started = Date.now();
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), Math.max(1, Number(timeoutMs) || DEFAULT_TIMEOUT_MS)) : null;
+  let response;
+  try {
+    response = await fetchImpl(base + "/json_rpc", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: "0", method: "get_info" }),
+      signal: controller ? controller.signal : undefined,
+    });
+  } catch (error) {
+    const aborted = error && (error.name === "AbortError" || error.code === "ABORT_ERR");
+    return { ok: false, why: aborted ? "timeout" : "unreachable", ms: Date.now() - started };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  if (!response || !response.ok) {
+    return { ok: false, why: "http", status: response ? response.status : null, ms: Date.now() - started };
+  }
+  let body = null;
+  try { body = await response.json(); } catch { return { ok: false, why: "not-json", ms: Date.now() - started }; }
+  if (!body || body.error) {
+    return { ok: false, why: "rpc", rpc: body && body.error ? body.error.code ?? null : null, ms: Date.now() - started };
+  }
+  const info = body.result || {};
+  const height = Number(info.height);
+  if (!Number.isInteger(height) || height < 0) return { ok: false, why: "no-height", ms: Date.now() - started };
+  // THE NETWORK THE NODE NAMES must be one the wallet builder accepts; an unknown word is not "probably stagenet".
+  const network = networkFromNode(info);
+  if (!network) return { ok: false, why: "nettype", nettype: info.nettype ?? null, ms: Date.now() - started };
+  return {
+    ok: true,
+    url: base,
+    height,
+    network,
+    nettype: info.nettype ?? null,
+    synchronized: info.synchronized === true,
+    version: info.version ?? null,
+    status: info.status ?? null,
+    ms: Date.now() - started,
+  };
+}

package/src/public/core.d.ts

@@ -11,3 +11,40 @@
  * ("1,234.5" is 1234.5), so what the field shows and what the rest of the code computes cannot diverge.
  */
 export declare function parseAmount(raw: string | number | null | undefined): number | null;
+
+/**
+ * ATOMIC UNITS -> A DECIMAL STRING. One XMR is 10^12 atomic units; the conversion uses BigInt, so a value above
+ * 2^53 (about 9007 XMR in piconero) is not rounded. Dust does not vanish: 1 unit is "0.000000000001". `trim`
+ * drops trailing zeros in the fraction; the result is always a plain decimal, never grouped.
+ *
+ * Throws a RangeError when the input is not a whole number of atomic units.
+ */
+export declare function formatXmr(atomic: bigint | number | string, options?: { readonly trim?: boolean }): string;
+
+/**
+ * A DECIMAL AMOUNT TYPED BY A PERSON -> ATOMIC UNITS, or null when the text is not an amount. A comma without a
+ * dot is the decimal separator ("0,05"). More than twelve decimals is null: rounding an amount is a wrong payment
+ * that looks successful.
+ */
+export declare function parseXmr(text: string | number | null | undefined): bigint | null;
+
+/** A value below this is in seconds. Separated from the millisecond threshold on purpose: the gap has no scale. */
+export declare const SECONDS_SCALE_MAX: number;
+/** A value from this on is in milliseconds. */
+export declare const MS_SCALE_MIN: number;
+export declare const DEADLINE_SCALE: Readonly<{ seconds: "seconds"; milliseconds: "milliseconds"; unknown: "unknown" }>;
+export type DeadlineScale = "seconds" | "milliseconds" | "unknown";
+
+/** THE SCALE OF A VALUE. Empty, zero, a non-number, or a value between the thresholds: unknown - never a guess. */
+export declare function scaleOf(value: unknown): DeadlineScale;
+export declare function isSecondsScale(value: unknown): boolean;
+export declare function isMsScale(value: unknown): boolean;
+
+/**
+ * THE ONLY CONVERSION from the signed order's seconds to milliseconds. Empty gives null; a value already in
+ * milliseconds is refused (a second conversion would multiply the thousand in silence).
+ */
+export declare function msFromOrderSeconds(value: unknown, what?: string): number | null;
+
+/** A write guard: throws unless the value is in milliseconds. Returns true when it passes. */
+export declare function assertMsScale(value: unknown, what?: string): true;

package/src/public/core.mjs

@@ -4,3 +4,19 @@
 // consumer forced to import it from either would learn a false lesson about where it lives.
 
 export { parseAmount } from "../../engine/core/format.js";
+
+// XMR AMOUNTS IN ATOMIC UNITS: 12 decimals, bigint, no rounding. `formatXmr` for display and for a field,
+// `parseXmr` for what a person typed.
+export { formatXmr, parseXmr } from "../../engine/core/xmrAmount.js";
+
+// SECONDS AT THE CHAIN, MILLISECONDS EVERYWHERE ELSE: the scale of a deadline, and the one conversion at the boundary.
+export {
+  DEADLINE_SCALE,
+  SECONDS_SCALE_MAX,
+  MS_SCALE_MIN,
+  scaleOf,
+  isSecondsScale,
+  isMsScale,
+  msFromOrderSeconds,
+  assertMsScale,
+} from "../../engine/core/deadlineScale.js";

package/src/public/xmr.d.ts

@@ -316,3 +316,158 @@ export declare function sellWindowSec(request?: {
   readonly soft?: number;
   readonly hard?: number;
 }): number;
+
+/**
+ * WHAT NETWORK A NODE SAYS IT IS ON, from its `get_info` answer. The wallet must be built from this value: a
+ * mainnet wallet against a stagenet node looks like a broken withdrawal. An answer that is none of `mainnet`,
+ * `stagenet`, `testnet` comes back as null - a default would build a wallet for a chain the node may not serve.
+ */
+export declare function networkFromNode(info: unknown): "mainnet" | "stagenet" | "testnet" | null;
+
+/** An address read as its network and its public keys. An integrated address's payment id is not returned. */
+export interface AddressKeys {
+  readonly network: "mainnet" | "stagenet" | "testnet" | null;
+  /** The first payload byte, kept for callers that meet a prefix the table does not know. */
+  readonly netByte: number;
+  readonly spendPub: string;
+  readonly viewPub: string;
+}
+
+/** AN ADDRESS -> ITS NETWORK AND PUBLIC KEYS. Throws when the text is not a Monero address. */
+export declare function decodeAddressKeys(address: string): AddressKeys;
+
+/** A SCALAR AS LITTLE-ENDIAN HEX, low byte first - the form the daemon expects. */
+export declare function scalarToLeHex(scalar: bigint | number | string, bytes?: number): string;
+
+/**
+ * WHETHER A VIEW KEY IS THE ONE THE ADDRESS NAMES: true / false, or null when there is no public key to compare.
+ * `halves` is what `createHalves` returns, so the comparison uses the same arithmetic as the address build.
+ */
+export declare function viewKeyMatchesAddress(
+  viewScalar: bigint | number | string,
+  expectedViewPubHex: string,
+  halves: { publicHalves(scalar: bigint | number | string): { ed: string } },
+): boolean | null;
+
+/** A boundary up to this value is a block height; from it on, a unix time. */
+export declare const UNLOCK_TIME_BLOCK_MAX: number;
+
+export interface UnlockState {
+  readonly code: "unlocked" | "locked_height" | "locked_time";
+  readonly locked: boolean;
+  readonly untilHeight: number | null;
+  readonly untilTime: number | null;
+}
+
+/**
+ * WHETHER A COIN IS SPENDABLE. A height that is unknown does not open the coin: without the height there is no
+ * fact that would. `nowSec` defaults to the wall clock.
+ */
+export declare function unlockStateOf(
+  unlockTime: number | bigint | string,
+  options?: { height?: number | null; nowSec?: number | null },
+): UnlockState;
+
+/** The names that count as loopback: 127.0.0.1, ::1, localhost - not all of 127.0.0.0/8. */
+export declare const LOOPBACK_HOSTS: ReadonlySet<string>;
+export declare function isLoopbackHost(host: string): boolean;
+
+/** An address read as scheme and host, or null when the text is not a URL. */
+export declare function hostOfUrl(url: string): { scheme: string; host: string } | null;
+
+export type DaemonCode = "daemon-not-https" | "daemon-address-unreadable" | "daemon-scheme-unknown";
+export declare const DAEMON_CODES: Readonly<{ notHttps: DaemonCode; unreadable: DaemonCode; schemeUnknown: DaemonCode }>;
+export declare const DAEMON_PLAIN_HTTP_NETWORKS: readonly string[];
+export declare const DAEMON_NETWORK_MAINNET: string;
+
+/** A setting in one shape: 0/false/no/off switches it off; anything else, a typo included, leaves it on. */
+export declare function plainLoopbackAllowed(raw: unknown): boolean;
+
+export interface DaemonAddressJudgement {
+  readonly ok: boolean;
+  /** False for an empty value: nothing to judge, not a refusal. */
+  readonly configured: boolean;
+  readonly scheme: string | null;
+  readonly host: string | null;
+  readonly loopback: boolean;
+  readonly plainLoopbackAllowed: boolean;
+  /** True when a remote plain-http daemon was accepted because the network is stagenet or testnet. */
+  readonly plainHttpAccepted: boolean;
+  readonly network: string;
+  readonly code: DaemonCode | null;
+  readonly reason: string | null;
+}
+
+/**
+ * MAY THIS DAEMON ADDRESS BE USED. https anywhere; http on loopback; http to a remote host only on stagenet and
+ * testnet. An unknown network is judged as mainnet.
+ */
+export declare function judgeDaemonAddress(
+  raw: string | null | undefined,
+  options?: { network?: string; allowPlainLoopback?: boolean },
+): DaemonAddressJudgement;
+
+/** A per-KB price -> the fee for a transaction of `bytes`, rounded UP. Throws on a non-integer or a negative input. */
+export declare function feeForBytes(feePerKB: bigint | number | string, bytes: bigint | number | string): string;
+
+export interface FeeEstimateOk {
+  readonly ok: true;
+  readonly url: string;
+  /** The price per kilobyte for the next block, in atomic units, or null when the daemon did not send it. */
+  readonly feePerKB: string | null;
+  readonly medianFeePerKB: string | null;
+  /** The daemon's own priority list, in its order, or null. */
+  readonly perPriority: readonly string[] | null;
+}
+
+export interface FeeEstimateRefusal {
+  readonly ok: false;
+  /** no-url | no-fetch | timeout | unreachable | http | not-json | rpc | no-estimate */
+  readonly why: string;
+  readonly status?: number | null;
+  readonly rpc?: number | null;
+}
+
+/**
+ * ASK A NODE WHAT A TRANSACTION WILL COST (`get_fee_estimate`). The exact sum needs the assembled transaction, so
+ * this is a price per kilobyte; `feeForBytes` is the only arithmetic that turns it into a fee. Never throws.
+ */
+export declare function moneroFeeEstimate(options: {
+  url: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}): Promise<FeeEstimateOk | FeeEstimateRefusal>;
+
+/** The answer to a preflight: usable, or the named reason it is not. */
+export interface NodeProbeOk {
+  readonly ok: true;
+  readonly url: string;
+  readonly height: number;
+  readonly network: "mainnet" | "stagenet" | "testnet";
+  readonly nettype: string | null;
+  readonly synchronized: boolean;
+  readonly version: string | null;
+  readonly status: string | null;
+  readonly ms: number;
+}
+
+export interface NodeProbeRefusal {
+  readonly ok: false;
+  /** no-url | no-fetch | timeout | unreachable | http | not-json | rpc | no-height | nettype */
+  readonly why: string;
+  readonly status?: number | null;
+  readonly nettype?: string | null;
+  readonly rpc?: number | null;
+  readonly ms?: number;
+}
+
+/**
+ * ASK A NODE FOR `get_info`: the height, the network it names, whether it is synchronized. Never throws - the
+ * answer names the problem (`unreachable`, `timeout`, `nettype`, ...). `fetchImpl` is injected so a Node consumer
+ * or a test can pass its own; `timeoutMs` abandons the request (8 seconds by default).
+ */
+export declare function probeMoneroNode(options: {
+  url: string;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}): Promise<NodeProbeOk | NodeProbeRefusal>;

package/src/public/xmr.mjs

@@ -27,3 +27,37 @@ export { createDleq2 } from "../../engine/atomic/dleq2.js";
 export { scalarFromMoneroHex, spendKeysFromRevealedHalf } from "../../engine/monero/halvesSweep.js";
 
 export { SELL_WINDOW, sellWindowSec } from "../../engine/core/sellWindow.js";
+
+// WHAT NETWORK A NODE SAYS IT IS ON: the wallet must be built from that answer, and an unknown answer is null -
+// a default here would build a wallet for a chain the node may not serve.
+export { networkFromNode } from "../../engine/monero/nodeNetwork.js";
+
+// READING AN ARRIVAL WITHOUT A WALLET: the address and its public keys, the little-endian scalar form the daemon
+// expects, whether a view key matches the address, and whether the coin is still locked by unlock_time.
+export {
+  decodeAddressKeys,
+  scalarToLeHex,
+  viewKeyMatchesAddress,
+  unlockStateOf,
+  UNLOCK_TIME_BLOCK_MAX,
+} from "../../engine/monero/arrivalRead.js";
+
+// WHERE A MONERO NODE MAY LIVE: https anywhere, http on loopback, http to a remote host only on stagenet/testnet -
+// one policy for the node and for the page that lets an operator type an address.
+export {
+  DAEMON_CODES,
+  DAEMON_NETWORK_MAINNET,
+  DAEMON_PLAIN_HTTP_NETWORKS,
+  LOOPBACK_HOSTS,
+  hostOfUrl,
+  isLoopbackHost,
+  judgeDaemonAddress,
+  plainLoopbackAllowed,
+} from "../../engine/monero/daemonAddress.js";
+
+// WHAT A TRANSACTION WILL COST: the daemon's price per kilobyte, by priority, and the arithmetic that turns it into
+// a fee. The page learned the fee only after signing.
+export { moneroFeeEstimate, feeForBytes } from "../feeEstimate.mjs";
+
+// IS THE NODE USABLE, AND WHAT DOES IT SAY ABOUT ITSELF: one get_info request, an answer that names why not.
+export { probeMoneroNode } from "../probes.mjs";

package/src/recovery.mjs

@@ -3,6 +3,12 @@
 //
 // The file arrives from the interface as a string or as `{ contents }`: the SDK knows neither about
 // <input type=file> nor about buffers - that is the interface's business.
+//
+// THE RESTORE HEIGHT IS A RULE, NOT A LOOKUP THE PAGE PERFORMS. Two sources exist: the height written into the
+// file when it was issued, and the height the service learned when it registered the wallet (it watches the
+// address, so its row is often more precise). The order between them is the package's: the service's height wins
+// when it is known, the file's is the fallback, and NO height is a named state - not a refusal, because the
+// person can still type one.
 import * as engine from "./engine.mjs";
 import { SdkError } from "./errors.mjs";
 
@@ -12,7 +18,7 @@ const contentsOf = (file) => {
   return null;
 };
 
-export function createRecovery() {
+export function createRecovery({ http = null, config = null } = {}) {
   return {
     async open(file, passphrase) {
       const contents = contentsOf(file);
@@ -36,5 +42,70 @@ export function createRecovery() {
         swapId: typeof payload.swapId === "string" ? payload.swapId : null,
       };
     },
+
+    // WHICH HEIGHT TO SCAN FROM, AND WHERE IT CAME FROM. The page used to run this lookup itself: it read the
+    // file, then asked the service by address. Two readers of one rule is how a page and a package drift, so the
+    // lookup lives here and the answer names its source.
+    //
+    // A SERVICE THAT DOES NOT ANSWER IS NOT A REFUSAL. The file's height is still a height; with neither, the
+    // answer is `source: "none"` and the interface asks the person. The problem is a token, never a message.
+    async restoreHeight(request = {}) {
+      const contents = contentsOf(request.file);
+      if (contents === null) throw new SdkError("bad-input", { field: "file" });
+      if (typeof request.passphrase !== "string" || !request.passphrase) {
+        throw new SdkError("bad-input", { field: "passphrase" });
+      }
+      // THE ENVELOPE IS PARSED HERE: `restoreFromFile` takes the OBJECT, while the file arrives as text. Doing it
+      // in one place keeps "not JSON" a named stage instead of a library message.
+      let envelope;
+      try {
+        envelope = JSON.parse(contents);
+      } catch {
+        throw new SdkError("recovery-failed", { stage: "parse" });
+      }
+      // ONLY THE PAYLOAD IS NEEDED, NOT A RESTORED WALLET: the height and the address live in the decrypted
+      // payload, while restoring a wallet would rebuild keys from the halves - work this answer does not use, and
+      // work that needs the browser's crypto vendor.
+      let payload;
+      try {
+        payload = await engine.recoveryFile.decryptFile(envelope, request.passphrase);
+        engine.recoveryFile.validatePayload(payload);
+      } catch {
+        throw new SdkError("recovery-failed", { stage: "restore" });
+      }
+      const wallet = payload.moneroWallet || {};
+      const address = typeof wallet.address === "string" && wallet.address ? wallet.address : null;
+      const fileHeight = Number(wallet.restoreHeight) || 0;
+
+      let appHeight = 0;
+      let appAsked = false;
+      let appProblem = null;
+      if (http && config && address) {
+        appAsked = true;
+        try {
+          const answer = await http.json(config.route("swaps"));
+          const rows = Array.isArray(answer) ? answer : ((answer && answer.swaps) || []);
+          const row = rows.find((x) => String((x && x.address) || "") === String(address)) || null;
+          appHeight = Number(row && row.restoreHeight) || 0;
+          if (!row) appProblem = "no-row";
+        } catch {
+          appProblem = "unreachable";
+        }
+      }
+
+      const height = appHeight > 0 ? appHeight : fileHeight;
+      const source = appHeight > 0 ? "app" : (fileHeight > 0 ? "file" : "none");
+      return {
+        address,
+        height,
+        source,
+        fileHeight,
+        appHeight,
+        appAsked,
+        // Why there is no height, when there is none: a token the interface turns into words. Null when a height
+        // was found, so a reader cannot mistake "found" for "asked and failed".
+        appProblem: source === "none" ? (appProblem || "no-height") : null,
+      };
+    },
   };
 }