@ninsei-labs/sdk 0.43.1 → 0.44.0

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/order.d.ts

@@ -159,3 +159,15 @@ export declare function signQuoteDigest(request: {
  * verified at all. Null is a refusal for the caller to name, never consent.
  */
 export declare function recoverQuoteKey(request: { readonly crypto: QuoteCrypto; readonly quote: OrderQuote }): string | null;
+
+/**
+ * Names of the signed-set fields the quote does not carry, bound to the SDK's own primitives: the same answer as
+ * `quoteMissingFields`, offered so a verifier does not have to pass crypto it already trusts twice.
+ */
+export declare function orderQuoteMissingFields(quote: Partial<OrderQuote> | null | undefined): string[];
+
+/**
+ * The address that signed the quote, recovered with the SDK's own primitives, or null when the quote cannot be
+ * verified at all. Null is a refusal for the caller to name, never consent.
+ */
+export declare function recoverOrderQuoteKey(quote: OrderQuote): string | null;

package/src/public/order.mjs

@@ -20,3 +20,8 @@ export {
   recoverQuoteKey,
   signQuoteDigest,
 } from "../quoteEip712Spec.mjs";
+
+// THE BOUND VERIFICATION HELPERS. The spec above is handed crypto by the caller; these two bind it to the SDK's
+// own primitives, so a consumer verifies a maker's quote without assembling the binding itself. Verification
+// only: the provider's signing key never enters this package.
+export { orderQuoteMissingFields, recoverOrderQuoteKey } from "../quoteEip712.mjs";

package/src/public/provider.d.ts

@@ -0,0 +1,93 @@
+// DECLARATIONS FOR THE `./provider` ENTRY: the node-side helpers, Node only.
+//
+// These declarations name what `src/public/provider.mjs` re-exports: identity, signing and env files. Every
+// signature is copied from the modules the barrel re-exports (`src/provider/identity.mjs`, `sign.mjs`,
+// `envFile.mjs`), and a symbol the barrel does not re-export is not declared here.
+//
+// NOT FOR A BROWSER. These functions use `node:crypto`, `node:fs` and `node:path`; a page must import from the
+// browser entries instead.
+
+/** The shape of a provider code: `lp-` and eight lowercase hex digits, derived from the provider's address. */
+export declare const PROVIDER_CODE_RE: RegExp;
+
+/** The longest display name a provider may set. */
+export declare const DISPLAY_NAME_MAX: number;
+
+/** The provider code of an address: stable for the address, independent of any key. Throws on a malformed address. */
+export declare function providerCode(address: string): string;
+
+/** A display name the operator may keep or replace: a word and four hex digits. */
+export declare function randomDisplayName(): string;
+
+/** The canonical JSON a signature covers: keys sorted at every level, so two writers agree on the bytes. */
+export declare function canonical(payload: unknown): string;
+
+/** A signed package: the payload's fields plus the detached signature and the key identity that made it. */
+export interface SignedPayload {
+  readonly [field: string]: unknown;
+  readonly signature: string;
+  readonly keyId?: string;
+}
+
+/** Signs the canonical form of the payload with a PEM private key. */
+export declare function signPayload(payload: Record<string, unknown>, privateKeyPem: string, keyId?: string): SignedPayload;
+
+/** Verifies a signed package against a PEM public key. False means refused, never "probably fine". */
+export declare function verifyPayload(pkg: SignedPayload, publicKeyPem: string): boolean;
+
+/** The public key file that belongs to a private key file: `x.key` becomes `x.pub`. */
+export declare function publicKeyPath(keyFile: string): string;
+
+/** Creates a key pair on disk and writes the public half beside it. Refuses to overwrite unless `force`. */
+export declare function generateKeyFiles(options?: { readonly keyFile?: string; readonly force?: boolean }): {
+  readonly key?: string;
+  readonly file?: string;
+  readonly why?: string;
+};
+
+/** The raw seed bytes of a PEM private key, for consumers that must not keep the PEM. */
+export declare function privateKeySeedBytes(privateKeyPem: string): Uint8Array;
+
+/** Reads a PEM private key from a file. */
+export declare function loadPrivateKey(keyFile: string): string;
+
+/** The base64 SPKI form of a public key, from either a public or a private PEM. */
+export declare function publicKeyBase64From(publicKeyPem: string): string;
+
+/** The base64 public key that belongs to a private key. */
+export declare function signingPublicKeyBase64(privateKeyPem: string): string;
+
+/** The base64 public key held in a public key file, or a named reason when it is missing. */
+export declare function publicKeyFileBase64(pubFile: string): { readonly key: string | null; readonly why?: string };
+
+/** What the node reports about its own key: the key, its file, and whether the two halves agree. */
+export declare function nodePublicKeyReport(options?: {
+  readonly privateKeyPem?: string | null;
+  readonly keyFile?: string | null;
+  readonly pubFile?: string | null;
+}): { readonly key: string | null; readonly file?: string | null; readonly matches?: boolean | null; readonly why?: string };
+
+/** The settings files looked up, in order, when none is named. */
+export declare const ENV_CANDIDATES: readonly string[];
+
+/** The first settings file that exists under `cwd`, or null. */
+export declare function findEnvFile(cwd: string, candidates?: readonly string[]): string | null;
+
+/** A Windows path found in a settings file on a non-Windows system, or null when the file is usable. */
+export declare function foreignPathProblem(
+  file: string,
+  values: Record<string, string>,
+  platform?: string,
+): { readonly file: string; readonly key: string; readonly value: string } | null;
+
+/** The sentence that explains a foreign path to an operator. */
+export declare function foreignPathMessage(problem: { readonly file: string; readonly key: string; readonly value: string }): string;
+
+/** Reads a settings file into a plain object of its values. */
+export declare function readEnvFile(path: string): Record<string, string>;
+
+/** Substitutes `${STACK_DATA}` and `${ROOT}` in a setting value. */
+export declare function substituteEnvVars(value: unknown, paths: { readonly dataDir: string; readonly root: string }): string;
+
+/** Applies a settings file to a target object (the process environment by default) and returns the names set. */
+export declare function applyEnvFile(path: string, target?: Record<string, string | undefined>): string[];

package/src/public/provider.mjs

@@ -0,0 +1,39 @@
+// THE PROVIDER SIDE, NODE ONLY: identity, signing and env files for the machine that runs the node.
+//
+// Separate entry, like ./adapters, because these helpers reach the filesystem and node:crypto. A browser
+// consumer must never pull them in, and a Node consumer gets them with one import.
+//
+// WHY THEY LIVE HERE. The demo's backend verifies a maker's quote and builds an allow list from the provider's
+// key; the node signs tickets with the same key. One implementation in the package means the identity rule and
+// the key-path rule are not re-derived per consumer.
+
+export {
+  PROVIDER_CODE_RE,
+  DISPLAY_NAME_MAX,
+  providerCode,
+  randomDisplayName,
+} from "../provider/identity.mjs";
+
+export {
+  canonical,
+  signPayload,
+  verifyPayload,
+  publicKeyPath,
+  generateKeyFiles,
+  privateKeySeedBytes,
+  loadPrivateKey,
+  publicKeyBase64From,
+  signingPublicKeyBase64,
+  publicKeyFileBase64,
+  nodePublicKeyReport,
+} from "../provider/sign.mjs";
+
+export {
+  ENV_CANDIDATES,
+  findEnvFile,
+  foreignPathProblem,
+  foreignPathMessage,
+  readEnvFile,
+  substituteEnvVars,
+  applyEnvFile,
+} from "../provider/envFile.mjs";

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,
+      };
+    },
   };
 }

package/src/sweep-restore.mjs

@@ -0,0 +1,130 @@
+// RESTORING THE WITHDRAWAL WALLET: THE PASS BEFORE ANYTHING IS SIGNED.
+//
+// WHY THIS IS IN THE PACKAGE. The sweep page used to run this itself: set the restore height ten blocks below
+// the one the file names, rescan, sync, read the balance, and - if the balance was non-zero while nothing was
+// spendable - rescan the spent status and sync again. The second pass was not a guess: coins are locked for ten
+// blocks after they arrive, and the spent status of outputs restored from a key is not known until the wallet
+// asks the chain. Both are facts about wallet2, not about a page, and a node or a CLI needs the same pass.
+//
+// WHAT IS NOT HERE: creating the wallet, opening it and closing it. The wallet arrives as the same withdrawal
+// adapter the signing step takes (`sync`, `unlockedBalance`, `driver`); who built it and where the WASM and the
+// worker live is the caller's business.
+//
+// REFUSALS CARRY CODES. A missing method, a missing height and a library error all come out as `SdkError`; a
+// low-level exception never escapes with `code: null`, because the interface has no phrase for it and a check
+// cannot assert it.
+import { SdkError } from "./errors.mjs";
+
+// THE SECOND PASS IS BOUNDED: a wallet that reports a balance but no spendable coins twice is not helped by a
+// third pass, and repeating it would only make an empty answer slower to arrive.
+const PASSES = 2;
+// HOW FAR BELOW THE NAMED HEIGHT THE SCAN STARTS. A gap in an arrival block is worth more than the ten blocks it
+// costs: scanning from the exact height has already missed an arrival one block earlier.
+const SCAN_BACK = 10;
+
+const asAmount = (value, field) => {
+  try {
+    return BigInt(value);
+  } catch {
+    throw new SdkError("bad-input", { field });
+  }
+};
+
+const driverOf = (wallet) => {
+  if (!wallet || typeof wallet.driver !== "function") throw new SdkError("bad-input", { field: "wallet.driver" });
+  const driver = wallet.driver();
+  if (!driver || typeof driver !== "object") throw new SdkError("bad-input", { field: "wallet.driver" });
+  const missing = ["setRestoreHeight", "getBalance"].filter((name) => typeof driver[name] !== "function");
+  if (missing.length) throw new SdkError("bad-input", { field: "wallet.driver", missing });
+  return driver;
+};
+
+// A WALLET STEP THAT FAILS IS A REFUSAL WITH A CODE, never raw library text. The surface is named so a reader can
+// tell which call went wrong.
+const step = async (surface, fn) => {
+  try {
+    return await fn();
+  } catch (error) {
+    if (error instanceof SdkError) throw error;
+    throw new SdkError("wallet-rejected", { surface, why: String((error && error.message) || error) });
+  }
+};
+
+const heightOf = async (driver, name) => {
+  if (typeof driver[name] !== "function") return null;
+  try {
+    const value = await driver[name]();
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+  } catch {
+    // A missing height is not a refusal: the balance is the answer this pass exists for.
+    return null;
+  }
+};
+
+/**
+ * Restore the wallet from a height and report what it holds.
+ *
+ * @param {object} request
+ * @param {object} request.wallet   the withdrawal adapter: `sync`, `unlockedBalance`, `driver`
+ * @param {number} request.fromHeight the height the file names; the scan starts a little below it
+ * @param {number} [request.scanBack] how far below, default 10
+ * @param {boolean} [request.rescanWhenLocked] run the second pass, default true
+ * @returns {Promise<{total: string, unlocked: string, scanHeight: number, walletHeight: number|null,
+ *   nodeHeight: number|null, passes: number, lockedPass: boolean}>}
+ */
+export async function restoreWallet(request = {}) {
+  const wallet = request.wallet;
+  if (!wallet || typeof wallet !== "object") throw new SdkError("bad-input", { field: "wallet" });
+  const missing = ["sync", "unlockedBalance"].filter((name) => typeof wallet[name] !== "function");
+  if (missing.length) throw new SdkError("bad-input", { field: "wallet", missing });
+
+  const fromHeight = Number(request.fromHeight);
+  if (!Number.isFinite(fromHeight) || fromHeight <= 0) throw new SdkError("bad-input", { field: "restoreHeight" });
+
+  const scanBack = Number.isFinite(Number(request.scanBack)) && Number(request.scanBack) >= 0
+    ? Math.floor(Number(request.scanBack))
+    : SCAN_BACK;
+  const scanHeight = Math.max(0, Math.floor(fromHeight) - scanBack);
+  const driver = driverOf(wallet);
+
+  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.
+  if (typeof driver.rescanBlockchain !== "function") throw new SdkError("bad-input", { field: "wallet.driver.rescanBlockchain" });
+  await step("rescanBlockchain", () => driver.rescanBlockchain());
+
+  // A FAILED SYNC IS BEST-EFFORT, exactly as in the signing step: what blocks a withdrawal is the spendable
+  // remainder, and it is read below. The library throws low-level while scanning a chain it cannot read; that must
+  // not pre-empt the verdict.
+  try { await wallet.sync(); } catch { /* the remainder decides */ }
+
+  let total = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
+  let unlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
+  let passes = 1;
+  let lockedPass = false;
+
+  // THE SECOND PASS: coins exist but none is spendable. The spent status is re-checked and the wallet is synced
+  // again; the arrival may have been locked by time rather than lost.
+  const rescanWhenLocked = request.rescanWhenLocked !== false;
+  if (rescanWhenLocked && total > 0n && unlocked === 0n && typeof driver.rescanSpent === "function" && passes < PASSES) {
+    lockedPass = true;
+    await step("rescanSpent", () => driver.rescanSpent());
+    try { await wallet.sync(); } catch { /* as above */ }
+    total = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
+    unlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
+    passes += 1;
+  }
+
+  return {
+    total: total.toString(),
+    unlocked: unlocked.toString(),
+    scanHeight,
+    walletHeight: await heightOf(driver, "getHeight"),
+    nodeHeight: await heightOf(driver, "getDaemonHeight"),
+    passes,
+    // 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,
+  };
+}