@ninsei-labs/sdk 0.43.3 → 0.44.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## 0.44.0 — 2026-10-19
+
+THE WITHDRAWAL AND THE NODE NOW ASK THE PACKAGE INSTEAD OF CARRYING THEIR OWN COPIES. Every rule below was
+implemented in the sweep page or in the node first, and each had a second reader or a second copy waiting to
+diverge. Nothing here is a breaking change: the entries are new names, apart from two type-level declarations that
+replace nothing.
+
+- `sweep.restore` restores the wallet from a height with one second pass when coins exist but none is spendable,
+  and `recovery.restoreHeight` answers the height with its source: the service wins when it knows one, the file is
+  the fallback, and "no height" is a named state rather than a refusal.
+- `sweep.wallet` builds the withdrawal wallet from the caller's monero-ts namespace. The network word becomes the
+  library's enum inside the package, and `xmr.networkFromNode` reads the three known answers while anything else
+  is null.
+- `sweep.destination` compares a typed address with the address the recovery file promised and with the file's
+  network, and `sweep.sign` now reports `fee` and `receive`: a withdrawal moves the whole remainder, so the fee
+  comes out of it.
+- `core.formatXmr` and `core.parseXmr` work in BigInt at twelve decimals. One atomic unit is `"0.000000000001"`,
+  never `"0"`, and more than twelve decimals is refused instead of rounded.
+- `xmr.decodeAddressKeys`, `xmr.scalarToLeHex`, `xmr.viewKeyMatchesAddress` and `xmr.unlockStateOf` read an arrival
+  without a wallet: the address and its public keys, the daemon's little-endian scalar, the key check, and the
+  `unlock_time` rule with its boundary named.
+- `xmr.judgeDaemonAddress` is one policy for a node address: https anywhere, http on loopback, and http to a remote
+  host only on stagenet and testnet. An unknown network is judged as mainnet.
+- `xmr.moneroFeeEstimate` asks a node for `get_fee_estimate`, and `xmr.feeForBytes` turns a per-KB price into a sum,
+  rounded up. `xmr.probeMoneroNode` answers a preflight with a height, a network and a named reason when it cannot.
+- `core.scaleOf` and `core.msFromOrderSeconds` keep seconds at the chain and in the signed terms, milliseconds
+  everywhere else, with one conversion at the boundary that refuses a value already in milliseconds.
+- `ERROR_META` and `ERROR_SIDES` sit beside `ERROR_CODES`: whether another attempt has a chance, and who can act.
+  A machine check keeps the two vocabularies exactly equal.
+
+Verified by the package battery: 22 checks green, and every new rule has its own guard with a breaking run.
+
 ## 0.43.3 — 2026-10-18
 
 THE SAME CONTENT AS 0.43.2, PUBLISHED UNDER A NEW NUMBER. The tag-triggered release for 0.43.2 stopped in

package/engine/core/deadlineScale.js

@@ -0,0 +1,59 @@
+// SECONDS AT THE CHAIN, MILLISECONDS EVERYWHERE ELSE - AND ONE CONVERSION BETWEEN THEM.
+//
+// WHAT WENT WRONG WITHOUT THIS RULE (a live log, not a theory). One line carried deadlines in different scales:
+// ready_by = 1791828827 (seconds), t1 = 1791832427 (seconds), funded_at = 1791825228449 (milliseconds). The payout
+// path read ready_by as it was and subtracted a margin in MILLISECONDS: "1791828827 - 1800000" is a moment around
+// 1970, so the deadline looked long past at once and the check never asked the money-origin hook even once.
+//
+// THE RULE IS NOT "MILLISECONDS EVERYWHERE", because two values are outside our control and stay in seconds:
+//   * the escrow deadlines readyBy/t1 travel in the SIGNED order terms as 32-bit words;
+//   * EVM block time is whole seconds.
+// So: seconds at the chain and in the signed terms; milliseconds for everything a program keeps, compares with its own
+// clock or hands out over the wire.
+//
+// THE CONVERSION HAPPENS ONCE, at the boundary (`msFromOrderSeconds`), and it REFUSES a value that is already in
+// milliseconds - otherwise the thousand would be multiplied a second time, in silence.
+//
+// THE SCALE IS DISTINGUISHABLE BY MAGNITUDE: in 2026 seconds are about 1.79e9 and milliseconds about 1.79e12. A value
+// in the gap between the two thresholds has NO scale - guessing "probably seconds" is exactly how the defect passes.
+export const SECONDS_SCALE_MAX = 1e11;
+export const MS_SCALE_MIN = 1e12;
+export const DEADLINE_SCALE = Object.freeze({ seconds: "seconds", milliseconds: "milliseconds", unknown: "unknown" });
+
+/** THE SCALE OF A VALUE. Empty, zero, a non-number or a value between the thresholds: unknown. */
+export function scaleOf(value) {
+  const n = Number(value);
+  if (value === null || value === undefined || value === "" || !Number.isFinite(n) || n <= 0) return DEADLINE_SCALE.unknown;
+  if (n < SECONDS_SCALE_MAX) return DEADLINE_SCALE.seconds;
+  if (n >= MS_SCALE_MIN) return DEADLINE_SCALE.milliseconds;
+  return DEADLINE_SCALE.unknown;
+}
+
+export function isSecondsScale(value) { return scaleOf(value) === DEADLINE_SCALE.seconds; }
+export function isMsScale(value) { return scaleOf(value) === DEADLINE_SCALE.milliseconds; }
+
+/**
+ * THE ONLY CONVERSION FROM THE SIGNED ORDER'S SECONDS TO MILLISECONDS.
+ *
+ * An empty value gives null: "no deadline named" stays unnamed rather than becoming zero. A value already in
+ * milliseconds is REFUSED - this function is called at one boundary, and a second conversion is a silent thousand.
+ */
+export function msFromOrderSeconds(value, what = "the value") {
+  if (value === null || value === undefined || value === "") return null;
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) throw new Error(what + " is not a positive number: " + JSON.stringify(value));
+  const scale = scaleOf(n);
+  if (scale === DEADLINE_SCALE.milliseconds) {
+    throw new Error(what + " is already in milliseconds (" + n + "); the single conversion at the boundary would multiply the thousand a second time");
+  }
+  if (scale !== DEADLINE_SCALE.seconds) throw new Error(what + " is neither seconds nor milliseconds (" + n + ")");
+  return n * 1000;
+}
+
+/** A WRITE GUARD: a value of the wrong scale stops the write instead of being stored. Returns true when it passes. */
+export function assertMsScale(value, what = "the value") {
+  if (scaleOf(value) !== DEADLINE_SCALE.milliseconds) {
+    throw new Error(what + " is not in milliseconds: " + JSON.stringify(value) + " (scale " + scaleOf(value) + ")");
+  }
+  return true;
+}

package/engine/core/xmrAmount.js

@@ -0,0 +1,51 @@
+// XMR AMOUNTS AS TEXT: ATOMIC UNITS IN, A HUMAN NUMBER OUT (AND BACK).
+//
+// WHY NOT `Number`. One XMR is 10^12 atomic units (piconero). A JavaScript number is exact only up to 2^53, which
+// is about 9007 XMR in piconero: a balance or a quote above it would be rounded in silence. The sweep page kept its
+// own `ATOMIC_UNITS = 10^12n` and its own formatting; a second copy of this rule is exactly how a page shows
+// 0.000000000001 and a node reports 0.
+//
+// THE FORMAT IS PLAIN DECIMAL, NO GROUPING: a value to be copied, compared or put into a field. The interface may
+// group digits for reading, but the string this module returns must remain a number.
+//
+// DUST DOES NOT VANISH: 1 atomic unit formats as "0.000000000001", never as "0".
+const DECIMALS = 12;
+const SCALE = 10n ** BigInt(DECIMALS);
+
+/** Atomic units (bigint | number | string) -> a decimal string. Throws on a value that is not a whole number. */
+export function formatXmr(atomic, { trim = true } = {}) {
+  let value;
+  try {
+    value = BigInt(atomic);
+  } catch {
+    throw new RangeError("formatXmr: expected whole atomic units");
+  }
+  // A fractional input (0.5) silently truncated by BigInt() would be a wrong amount, not a formatting choice.
+  if (typeof atomic === "number" && !Number.isInteger(atomic)) throw new RangeError("formatXmr: expected whole atomic units");
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const whole = abs / SCALE;
+  const fraction = (abs % SCALE).toString().padStart(DECIMALS, "0");
+  let text = trim ? fraction.replace(/0+$/, "") : fraction;
+  const out = text ? `${whole}.${text}` : `${whole}`;
+  return negative ? `-${out}` : out;
+}
+
+/**
+ * A decimal amount typed by a person -> atomic units (bigint), or null when the text is not an amount.
+ *
+ * A comma without a dot is the decimal separator ("0,05"), as in the amount field. MORE THAN TWELVE DECIMALS IS
+ * NOT ROUNDED AND NOT TRUNCATED: null. Rounding someone's amount is a wrong payment that looks successful;
+ * refusing is a question the interface can ask again.
+ */
+export function parseXmr(text) {
+  const raw = String(text == null ? "" : text).trim().replace(/\s+/g, "");
+  if (!raw) return null;
+  if (raw.includes(".") && raw.includes(",")) return null;
+  const normalized = raw.replace(",", ".");
+  if (!/^\d+(\.\d*)?$/.test(normalized)) return null;
+  const [whole, fraction = ""] = normalized.split(".");
+  const digits = fraction.replace(/0+$/, "");
+  if (digits.length > DECIMALS) return null;
+  return BigInt(whole) * SCALE + BigInt((digits || "0").padEnd(DECIMALS, "0"));
+}

package/engine/monero/arrivalRead.js

@@ -0,0 +1,95 @@
+// READING AN XMR ARRIVAL WITHOUT A WALLET: WHAT THE ADDRESS IS, WHETHER A KEY MATCHES IT, AND WHETHER THE COIN IS
+// LOCKED.
+//
+// WHY THIS MODULE. A node that pays XMR holds only ONE half of the view key, so it cannot open a wallet on the
+// address it pays to - and it still has to answer three questions before it treats a transfer as money it can
+// spend. The sweep page needs the same answers when it verifies a recovery file. Both used to carry their own
+// copies: base58 decoding, the little-endian scalar form the daemon expects, the view-key comparison, and the
+// unlock_time rule. A second copy of the last one is the expensive kind - money at the address that cannot be
+// spent yet reads as an arrival.
+//
+// WHAT IS HERE: reading only. No signing, no sending, no network, no wallet.
+//
+// THE NETWORK TABLE IS DERIVED from the package's own prefix table rather than written out with numbers: a prefix
+// typed from memory (stagenet is not 18) already produced an address that no wallet would open.
+import { decodeMoneroBase58, PREFIX_BY_NETWORK } from "./address.js";
+
+const NETWORK_BY_PREFIX = Object.fromEntries(
+  Object.entries(PREFIX_BY_NETWORK).map(([network, kinds]) => [kinds.primary, network]),
+);
+
+const toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+
+/**
+ * AN ADDRESS -> ITS NETWORK AND ITS PUBLIC KEYS, or an error when the text is not an address.
+ * A primary address carries a 65-byte payload; an integrated one 73 (the extra 8 are the payment id, not returned).
+ */
+export function decodeAddressKeys(address) {
+  const raw = decodeMoneroBase58(String(address == null ? "" : address).trim());
+  if (!raw || raw.length < 69) throw new Error("not a Monero address: " + (raw ? raw.length + " bytes" : "not base58"));
+  const netByte = raw[0];
+  return {
+    network: NETWORK_BY_PREFIX[netByte] || null,
+    netByte,
+    spendPub: toHex(raw.slice(1, 33)),
+    viewPub: toHex(raw.slice(33, 65)),
+  };
+}
+
+/**
+ * THE SCALAR IN THE FORM THE DAEMON EXPECTS: little-endian hex, low byte first.
+ *
+ * A number written high byte first is a DIFFERENT key, and nothing refuses it: the wallet is created without an
+ * error and simply sees no arrival.
+ */
+export function scalarToLeHex(scalar, bytes = 32) {
+  const size = Number(bytes);
+  if (!Number.isInteger(size) || size <= 0) throw new Error("scalarToLeHex: bad width");
+  let value;
+  try { value = BigInt(scalar); } catch { throw new Error("scalarToLeHex: not an integer"); }
+  if (value < 0n || value >= 1n << BigInt(size * 8)) throw new Error("scalarToLeHex: value does not fit " + size + " bytes");
+  const out = new Uint8Array(size);
+  let rest = value;
+  for (let i = 0; i < size; i++) { out[i] = Number(rest & 0xffn); rest >>= 8n; }
+  return toHex(out);
+}
+
+/**
+ * IS THIS VIEW KEY THE ONE THE ADDRESS NAMES.
+ *
+ * `halves` is the object `createHalves` returns: the comparison must use the same point arithmetic as the address
+ * build, otherwise a key that opens the wallet looks wrong.
+ *
+ * Answers: true - the key matches; false - it belongs to another address; null - there is no public key to compare
+ * with (an address without a view key, which is not a case this code builds).
+ */
+export function viewKeyMatchesAddress(viewScalar, expectedViewPubHex, halves) {
+  const want = String(expectedViewPubHex || "").trim().toLowerCase().replace(/^0x/, "");
+  if (!want) return null;
+  if (!halves || typeof halves.publicHalves !== "function") throw new Error("viewKeyMatchesAddress: createHalves is required");
+  const got = String(halves.publicHalves(viewScalar).ed || "").toLowerCase().replace(/^0x/, "");
+  return got === want;
+}
+
+/** A boundary up to this value is a BLOCK HEIGHT; from it on, a unix TIME. Monero's own convention. */
+export const UNLOCK_TIME_BLOCK_MAX = 500_000_000;
+
+/**
+ * IS THE COIN SPENDABLE AT THIS MOMENT, AND IF NOT, WHAT IS THE BOUNDARY.
+ *
+ * `unlocked` / `locked_height` / `locked_time`, with the boundary named in `untilHeight` or `untilTime`. A height
+ * that is not known is NOT "unlocked": without a height the answer stays locked, because the caller has no fact
+ * that would open it. `nowSec` defaults to the wall clock, and is a parameter so a check can pin it.
+ */
+export function unlockStateOf(unlockTime, { height = null, nowSec = null } = {}) {
+  const u = Number(unlockTime) || 0;
+  if (u <= 0) return { code: "unlocked", locked: false, untilHeight: null, untilTime: null };
+  if (u >= UNLOCK_TIME_BLOCK_MAX) {
+    const now = nowSec === null || nowSec === undefined ? Math.floor(Date.now() / 1000) : Number(nowSec);
+    const open = Number.isFinite(now) && now >= u;
+    return { code: open ? "unlocked" : "locked_time", locked: !open, untilHeight: null, untilTime: u };
+  }
+  const h = height === null || height === undefined ? null : Number(height);
+  const open = h !== null && Number.isFinite(h) && h >= u;
+  return { code: open ? "unlocked" : "locked_height", locked: !open, untilHeight: u, untilTime: null };
+}

package/engine/monero/daemonAddress.js

@@ -0,0 +1,82 @@
+// WHERE A MONERO NODE MAY LIVE: ONE POLICY FOR EVERY CLIENT.
+//
+// WHY. An open `http://` connection to a machine across the network shows anyone on the path what is asked and what
+// is answered: addresses, amounts, transfer ids. A node refuses that on mainnet, and the sweep page - which lets an
+// operator type their own node address - accepts it today. Two answers to one question is how one of them ends up
+// allowing exactly what the other forbids.
+//
+// THE RULE. `https` anywhere; `http` on loopback (where the kernel, not the network, answers for the wire); `http`
+// to a remote host only on stagenet and testnet, where the public nodes known to us serve http only. Everything
+// else is refused with a code, and an unknown network is judged as mainnet: a network we cannot name cannot be
+// judged safe.
+//
+// LOOPBACK IS THREE NAMES, NOT ALL OF 127.0.0.0/8. That is how the node already counted, and widening the concept
+// under the cover of a fix would change behaviour nobody measured.
+export const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
+
+export function isLoopbackHost(host) {
+  return LOOPBACK_HOSTS.has(String(host || "").toLowerCase());
+}
+
+/** ADDRESS -> { scheme, host }, or null when the text is not a URL. A port and a path are allowed and ignored. */
+export function hostOfUrl(url) {
+  try {
+    const u = new URL(String(url));
+    const scheme = String(u.protocol || "").replace(":", "").toLowerCase();
+    const host = String(u.hostname || "").replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+    return { scheme, host };
+  } catch { return null; }
+}
+
+export const DAEMON_CODES = Object.freeze({
+  notHttps: "daemon-not-https",
+  unreadable: "daemon-address-unreadable",
+  schemeUnknown: "daemon-scheme-unknown",
+});
+
+/** The networks where a remote plain-http daemon is accepted. Every other name, including an unknown one, is not. */
+export const DAEMON_PLAIN_HTTP_NETWORKS = Object.freeze(["stagenet", "testnet"]);
+export const DAEMON_NETWORK_MAINNET = "mainnet";
+
+/**
+ * A SETTING READ IN ONE SHAPE: switching off is a named 0/false/no/off; anything else, a typo included, leaves the
+ * exception ON, because the safe default here is "loopback allowed, outside not".
+ */
+export function plainLoopbackAllowed(raw) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return true;
+  return !/^(0|false|no|off)$/i.test(String(raw).trim());
+}
+
+/**
+ * THE DECISION FOR ONE ADDRESS.
+ *
+ * `ok` - may this address be used. `configured: false` for an empty value (nothing to judge, not a refusal).
+ * `code` names a refusal; `reason` is a short technical phrase for the caller's log, not interface text.
+ */
+export function judgeDaemonAddress(raw, { network = DAEMON_NETWORK_MAINNET, allowPlainLoopback = true } = {}) {
+  const value = String(raw == null ? "" : raw).trim();
+  const allowed = allowPlainLoopback === undefined || allowPlainLoopback === null ? true : Boolean(allowPlainLoopback);
+  const net = String(network == null ? "" : network).trim().toLowerCase() || DAEMON_NETWORK_MAINNET;
+  const base = { configured: Boolean(value), scheme: null, host: null, loopback: false, plainLoopbackAllowed: allowed, plainHttpAccepted: false, network: net };
+  if (!value) return { ...base, ok: true, code: null, reason: null };
+  const target = hostOfUrl(value);
+  if (!target) return { ...base, ok: false, code: DAEMON_CODES.unreadable, reason: "not a URL" };
+  // "node.example:18081" parses as a URL whose scheme is "node.example" and whose host is empty - a missing
+  // scheme, not a foreign one. A daemon address without a host is unreadable either way.
+  if (!target.host) return { ...base, ok: false, scheme: target.scheme || null, code: DAEMON_CODES.unreadable, reason: "no host in the address" };
+  const loopback = isLoopbackHost(target.host);
+  if (target.scheme !== "http" && target.scheme !== "https") {
+    return { ...base, scheme: target.scheme, host: target.host, loopback, ok: false, code: DAEMON_CODES.schemeUnknown, reason: "scheme " + JSON.stringify(target.scheme) + " is neither http nor https" };
+  }
+  const seen = { ...base, scheme: target.scheme, host: target.host, loopback };
+  if (target.scheme === "https") return { ...seen, ok: true, code: null, reason: null };
+  if (loopback) {
+    return allowed
+      ? { ...seen, ok: true, code: null, reason: null }
+      : { ...seen, ok: false, code: DAEMON_CODES.notHttps, reason: "plain http on loopback, and the loopback exception is switched off" };
+  }
+  if (DAEMON_PLAIN_HTTP_NETWORKS.includes(net)) {
+    return { ...seen, ok: true, plainHttpAccepted: true, code: null, reason: null };
+  }
+  return { ...seen, ok: false, code: DAEMON_CODES.notHttps, reason: "plain http to a remote host on " + net };
+}

package/engine/monero/nodeNetwork.js

@@ -0,0 +1,15 @@
+// THE NETWORK A NODE SAYS IT IS ON.
+//
+// A node answers `get_info` with `nettype` ("mainnet", "stagenet", "testnet"). A wallet MUST be built from that
+// answer: a mainnet wallet against a stagenet node looks like a broken sweep, not like a wrong address. The
+// mapping used to be a private function of the sweep page, which made "what a node may say" knowledge of one
+// interface.
+//
+// AN UNKNOWN ANSWER IS NULL, NOT A GUESS. Defaulting to a network would build a wallet for a chain the node may not
+// serve; the caller can then say which answer it got and stop.
+const KNOWN = new Set(["mainnet", "stagenet", "testnet"]);
+
+export function networkFromNode(info) {
+  const type = String((info && info.nettype) || "").trim().toLowerCase();
+  return KNOWN.has(type) ? type : null;
+}

package/index.d.ts

@@ -1230,8 +1230,27 @@ export type TerminalCode = "success" | "refunded_eth" | "closed" | "declined";
  * WASM - while the core stays DOM-free.
  */
 export interface SweepApi {
+  /**
+   * BUILD THE WITHDRAWAL WALLET from the caller's monero-ts namespace. The page used to pass a `createWallet`
+   * callback that translated the network name into the library's enum; that translation is the package's now, so a
+   * caller passes the namespace, the network, the node and the keys.
+   */
+  wallet(request: SweepWalletRequest): SweepWallet;
+
+   * COMPARE A DESTINATION WITH THE FILE'S PROMISE. `ok` is "usable address on the file's network", `matches` is
+   * "the promised one" and is null when the file named nobody. Sending XMR elsewhere is a different payment, so the
+   * comparison is not presentation.
+   */
+  destination(request: SweepDestinationRequest): Promise<SweepDestination>;
   /** What is known about the withdrawal from the recovery file: the address, the restore height, what we can dispose of. */
   plan(request: SweepPlanRequest): Promise<SweepPlan>;
+  /**
+   * RESTORE THE WALLET FROM A HEIGHT AND REPORT WHAT IT HOLDS. Sets the restore height a little below the one given,
+   * rescans, syncs and reads the total and the spendable balance. Coins that exist but are locked get ONE more pass
+   * with a spent-status re-check - the page used to decide that itself, and the rule belongs to wallet2, not to an
+   * interface. A failed sync is not the verdict: the remainder is.
+   */
+  restore(request: SweepRestoreRequest): Promise<SweepRestoreResult>;
   /**
    * Assemble the spend and view keys from the revealed half - with the mandatory check `(s_a + s_b)*G` against the
    * order's public key. It did not match - a refusal, not "let us try to send".
@@ -1256,6 +1275,68 @@ export interface SweepApi {
   run(request: SweepRunRequest): Promise<SweepRunResult>;
 }
 
+/** What `restore` needs: the withdrawal adapter and the height named by the file. */
+export interface SweepRestoreRequest {
+  /** The withdrawal adapter: `sync`, `unlockedBalance`, `driver`. The wallet is built by the caller. */
+  readonly wallet: {
+    sync(): Promise<void>;
+    unlockedBalance(): Promise<bigint | number | string>;
+    driver(): unknown;
+  };
+  /** The height from the recovery file. The scan starts `scanBack` blocks below it. */
+  readonly fromHeight: number;
+  /** How far below the named height the scan starts. Default 10. */
+  readonly scanBack?: number;
+  /** Run the second pass when coins exist but none is spendable. Default true. */
+  readonly rescanWhenLocked?: boolean;
+}
+
+/** What `restore` found. Amounts are atomic units as strings; heights are numbers when the driver can read them. */
+export interface SweepRestoreResult {
+  readonly total: string;
+  readonly unlocked: string;
+  /** The height the scan actually started from. */
+  readonly scanHeight: number;
+  readonly walletHeight: number | null;
+  readonly nodeHeight: number | null;
+  /** How many sync passes ran: 1, or 2 when the locked pass ran. */
+  readonly passes: number;
+  /** Whether the second pass RAN - not whether it helped. */
+  readonly lockedPass: boolean;
+}
+
+/** What `wallet` needs: the library namespace and the facts the wallet is built from. */
+export interface SweepWalletRequest {
+  /** The monero-ts namespace (the browser bundle's default export, or the module in Node). */
+  readonly moneroTs: {
+    readonly MoneroNetworkType?: Record<string, unknown>;
+    readonly createWalletFull: (config: Record<string, unknown>) => Promise<unknown>;
+  };
+  /** `mainnet`, `stagenet` or `testnet` - what a node says. */
+  readonly network: string;
+  /** The node (in production - a proxy). */
+  readonly serverUri: string;
+  readonly password?: string;
+  /** `{ seed }` or `{ privateSpendKey, privateViewKey, primaryAddress }`. */
+  readonly keys?: Record<string, unknown>;
+  readonly restoreHeight?: number;
+  /** When set, the derived address must match, or the wallet refuses to open. */
+  readonly expectedAddress?: string | null;
+}
+
+/** The wallet `sweep.wallet` returns: the SDK wallet adapter with the Monero surface on top. */
+export interface SweepWallet {
+  readonly vm: "monero";
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  address(): string;
+  chainId(): string;
+  unlockedBalance(): Promise<bigint | number | string>;
+  sync(): Promise<void>;
+  close(): Promise<void>;
+  driver(): unknown;
+}
+
 /** The withdrawal mark: the swap identifier and the transfer hash. */
 export interface SweepReportRequest {
   readonly swapId: string;
@@ -1331,11 +1412,42 @@ export interface MoneroWalletAdapter {
 }
 
 /** What signing returned: the open session's token and what lies under it. */
+/** What `destination` needs: the file, its passphrase, and the address the person typed. */
+export interface SweepDestinationRequest {
+  readonly file: { readonly contents: string };
+  readonly passphrase: string;
+  /** The address the person typed. Empty is refused (`bad-input`, field `dest`). */
+  readonly dest: string;
+}
+
+export interface SweepDestination {
+  /** True when the address is usable on the file's network. */
+  readonly ok: boolean;
+  readonly dest: string;
+  /** The recipient the file promised, or null when it named none. */
+  readonly promised: string | null;
+  /** True/false against the promise; null when the file named nobody. */
+  readonly matches: boolean | null;
+  /** The file's Monero network (stagenet, mainnet, testnet), or null. */
+  readonly network: string | null;
+  /** True when the checksum was actually checked; false when the library was not available. */
+  readonly verified: boolean;
+  /** The library's phrase when the shape or the network is wrong. */
+  readonly reason: string | null;
+}
+
 export interface SweepSignResult {
   /** The open session's token for `relay`. It contains no keys - they are owned by the library wallet. */
   readonly token: string;
   /** The free remainder at the moment of signing, in atomic units (string). */
   readonly amount: string;
+  /**
+   * THE FEE OF THE SIGNED TRANSFER, in atomic units, or null when the wallet could not report one. A withdrawal
+   * moves the whole remainder, so the fee comes out of it - `receive` is what the recipient gets.
+   */
+  readonly fee: string | null;
+  /** The remainder minus the fee. Null when the fee is unknown, or when a reported fee claims more than the remainder. */
+  readonly receive: string | null;
   /** Where the transfer was signed to. */
   readonly to: string;
   /** The address the XMR leaves from (the swap's joint address). */
@@ -1451,6 +1563,29 @@ export interface ActionsRequest {
 export interface RecoveryApi {
   /** Parse the recovery file. Without the right passphrase - a refusal with a code, not an exception. */
   open(file: { readonly contents: string } | string, passphrase?: string): Promise<RecoveredWallet>;
+  /**
+   * WHICH HEIGHT TO SCAN FROM, AND WHERE IT CAME FROM. The service's height wins when it knows one (it watches
+   * the address), the file's is the fallback, and no height is a named state - the person can type one.
+   */
+  restoreHeight(request: RestoreHeightRequest): Promise<RestoreHeightResult>;
+}
+
+export interface RestoreHeightRequest {
+  readonly file: { readonly contents: string } | string;
+  readonly passphrase: string;
+}
+
+export interface RestoreHeightResult {
+  readonly address: string | null;
+  /** 0 when no source knows a height. */
+  readonly height: number;
+  readonly source: "app" | "file" | "none";
+  readonly fileHeight: number;
+  readonly appHeight: number;
+  /** Whether the service was asked at all (it is absent in a package without a service). */
+  readonly appAsked: boolean;
+  /** When `source` is "none": "unreachable" | "no-row" | "no-height". Null when a height was found. */
+  readonly appProblem: string | null;
 }
 
 export interface RecoveredWallet {
@@ -1569,6 +1704,20 @@ export declare const CHECK_CODES: readonly CheckCode[];
 /** The error codes the SDK refuses with (`error.code`, `SdkError.code`): the same list as the `ErrorCode` type. */
 export declare const ERROR_CODES: readonly ErrorCode[];
 
+/** WHO CAN ACT on a refusal, and whether another attempt has a chance. */
+export type ErrorSide = "caller" | "wallet" | "chain" | "provider" | "service" | "unknown";
+
+export interface ErrorMeta {
+  /** Whether another attempt has a chance. Not permission to retry a payment. */
+  readonly retryable: boolean;
+  readonly side: ErrorSide;
+}
+
+/** What each refusal means: the interface's advice, kept beside the vocabulary and checked by machine. */
+export declare const ERROR_META: Readonly<Record<ErrorCode, ErrorMeta>>;
+
+export declare const ERROR_SIDES: readonly ErrorSide[];
+
 export declare function createNinsei(options: NinseiOptions): Ninsei;
 
 // --- The maker's level set: the level walk the node and the client agree on ------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.43.3",
+  "version": "0.44.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -28,7 +28,20 @@
     "check:terminal": "node tools/check.mjs --only=terminal",
     "check:terminal-teeth": "node tools/check-terminal-teeth.mjs",
     "check:sweep": "node tools/sweep-refusal.test.mjs",
-    "sync:version": "node tools/sync-version.mjs"
+    "sync:version": "node tools/sync-version.mjs",
+    "check:restore": "node tools/check-restore.mjs",
+    "check:restore-height": "node tools/check-restore-height.mjs",
+    "check:wallet-factory": "node tools/check-wallet-factory.mjs",
+    "check:xmr-amount": "node tools/check-xmr-amount.mjs",
+    "check:sign-preview": "node tools/check-sign-preview.mjs",
+    "check:destination": "node tools/check-destination.mjs",
+    "check:codes-meta": "node tools/check-codes-meta.mjs",
+    "check:arrival-read": "node tools/check-arrival-read.mjs",
+    "check:daemon-address": "node tools/check-daemon-address.mjs",
+    "check:ci-scripts": "node tools/check-ci-scripts.mjs",
+    "check:fee-estimate": "node tools/check-fee-estimate.mjs",
+    "check:deadline-scale": "node tools/check-deadline-scale.mjs",
+    "check:node-probe": "node tools/check-node-probe.mjs"
   },
   "types": "./index.d.ts",
   "exports": {

package/src/adapters/monero.mjs

@@ -40,6 +40,18 @@ export function moneroWallet({ createWallet, networkType, serverUri, password =
       need();
       return await wallet.sweepUnlocked({ address, relay });
     },
+    // THE FEE OF WHAT WAS SIGNED, when the library reports one. `sweepUnlocked` answers with the signed
+    // transactions; monero-ts puts the fee on each transaction. Optional by contract - the core treats a missing
+    // method as "unknown", so this adapter says what it can and nothing more.
+    async fee(signed) {
+      need();
+      const list = Array.isArray(signed) ? signed : [signed];
+      const tx = list[0];
+      if (!tx || typeof tx.getFee !== "function") return null;
+      const value = tx.getFee();
+      return value === null || value === undefined ? null : String(value);
+    },
+
     async relay(signed) {
       need();
       return await wallet.relayTxs(signed);

package/src/codes.mjs

@@ -125,6 +125,62 @@ export const ERROR_CODES = [
   "unknown",
 ];
 
+// WHAT EACH CODE MEANS FOR THE INTERFACE: may it offer "try again", and whose problem is it. The page kept two
+// hand-written lists (retryable, and "which of these are ours") next to a code dictionary; a code added to the
+// vocabulary and forgotten there showed the person the wrong advice. Here the table is beside the vocabulary, and a
+// machine checks that they name exactly the same codes.
+//
+// `retryable` answers "would another attempt have a chance"; it is not "was it transient" and it is not permission
+// to retry a payment. `side` names who can act:
+//   caller   - the person or the caller fixes an input;
+//   wallet   - the wallet's state or the person's decision in it;
+//   chain    - the chain, a node or a transaction;
+//   provider - a maker or a quote;
+//   service  - our own service;
+//   unknown  - the code is `unknown`, and pretending otherwise would be a guess.
+export const ERROR_SIDES = ["caller", "wallet", "chain", "provider", "service", "unknown"];
+
+export const ERROR_META = Object.freeze({
+  "not-implemented": { retryable: false, side: "caller" },
+  "bad-input": { retryable: false, side: "caller" },
+  "wallet-not-connected": { retryable: false, side: "wallet" },
+  "wallet-rejected": { retryable: false, side: "wallet" },
+  "wrong-chain": { retryable: false, side: "wallet" },
+  "quote-unavailable": { retryable: true, side: "provider" },
+  "quote-refused": { retryable: false, side: "provider" },
+  "address-denied": { retryable: false, side: "caller" },
+  "quote-stale": { retryable: true, side: "provider" },
+  "quote-signature-invalid": { retryable: false, side: "provider" },
+  "quote-key-mismatch": { retryable: false, side: "provider" },
+  "quote-field-unbound": { retryable: false, side: "provider" },
+  "quote-expired": { retryable: true, side: "provider" },
+  "quote-registry-unchecked": { retryable: true, side: "chain" },
+  "quote-key-unknown": { retryable: false, side: "chain" },
+  "quote-provider-mismatch": { retryable: false, side: "chain" },
+  "quote-provider-not-allowed": { retryable: false, side: "caller" },
+  "quote-factory-unchecked": { retryable: true, side: "chain" },
+  "quote-factory-unknown": { retryable: false, side: "chain" },
+  "quote-factory-mismatch": { retryable: false, side: "chain" },
+  "quote-factory-code-unknown": { retryable: false, side: "chain" },
+  "recovery-declined": { retryable: false, side: "wallet" },
+  "recovery-failed": { retryable: false, side: "wallet" },
+  "storage-unavailable": { retryable: true, side: "service" },
+  "server-unavailable": { retryable: true, side: "service" },
+  "server-refused": { retryable: false, side: "service" },
+  "xmr-timeout": { retryable: true, side: "chain" },
+  "xmr-locked": { retryable: true, side: "chain" },
+  "xmr-nodes-disagree": { retryable: true, side: "chain" },
+  "xmr-no-nodes": { retryable: true, side: "chain" },
+  "xmr-underpaid": { retryable: false, side: "chain" },
+  "xmr-too-late": { retryable: false, side: "chain" },
+  "contract-reverted": { retryable: false, side: "chain" },
+  "insufficient-funds": { retryable: false, side: "wallet" },
+  "gas-refused-by-maker": { retryable: false, side: "provider" },
+  "gas-not-arrived": { retryable: true, side: "chain" },
+  "gas-too-little": { retryable: false, side: "provider" },
+  "unknown": { retryable: false, side: "unknown" },
+});
+
 // GUARD KIND -> CHECK CODE. Kinds come from the engine (www/js/core/preSignGuards.js), codes are our public
 // vocabulary. The table is checked by machine: every kind the engine can return must be here, otherwise the
 // interface gets a code that is not in the contract.