@ninsei-labs/sdk 0.43.3 → 0.44.1

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.

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,46 @@
  * ("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;
+
+/**
+ * The same field text reduced to something a decimal parser can read: thousands separators removed, a lone comma
+ * read as the decimal separator, anything after a second separator dropped. Empty when the text carries no digit.
+ */
+export declare function normalizeAmountInput(raw: string | number | null | undefined): string;
+
+/**
+ * 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

@@ -3,4 +3,20 @@
 // One function today. It is a separate entry because it belongs to neither the XMR side nor the EVM side, and a
 // consumer forced to import it from either would learn a false lesson about where it lives.
 
-export { parseAmount } from "../../engine/core/format.js";
+export { normalizeAmountInput, 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/networks.d.ts

@@ -0,0 +1,50 @@
+// DECLARATIONS FOR THE `./networks` ENTRY.
+//
+// src/public/networks.mjs only NAMES what engine/core/config.js already exports. The declarations cover the fields
+// a consumer of the registry reads; the engine's objects carry more (explorers, price feeds, gas hints) and a
+// consumer is free to read them, but nothing here invents a field the engine does not have.
+
+/** A token the network accepts. `address` is a 20-byte hex string; `decimals` is what its own contract reports. */
+export interface ChainToken {
+  symbol: string;
+  address: string;
+  decimals: number;
+  hidden?: boolean;
+}
+
+/** The DEX deployment on a network, when there is one. */
+export interface ChainUniswap {
+  factory?: string;
+  quoter?: string;
+  /** WETH: the wrapped form of the native coin, used when a route needs an ERC-20. */
+  wrapped?: { address: string; decimals: number };
+  [field: string]: unknown;
+}
+
+export interface Chain {
+  id: string;
+  name: string;
+  vm: string;
+  chainId: number;
+  caip2?: string;
+  testnet?: boolean;
+  native: { symbol: string; decimals: number };
+  rpcUrl?: string;
+  tokens?: ChainToken[];
+  uniswap?: ChainUniswap;
+  [field: string]: unknown;
+}
+
+/** One entry per async route provider (CoWSwap, UniswapX, ...): what it settles and the networks it serves. */
+export interface AsyncRouteProvider {
+  venue?: string;
+  shape?: string;
+  settles?: string;
+  networks?: Record<string, unknown>;
+  [field: string]: unknown;
+}
+
+export declare const CHAINS: readonly Chain[];
+export declare const DEX_CHAINS: readonly string[];
+export declare const DEFAULT_CHAIN: string;
+export declare const ASYNC_ROUTE_PROVIDERS: Readonly<Record<string, AsyncRouteProvider>>;

package/src/public/networks.mjs

@@ -0,0 +1,9 @@
+// THE NETWORK REGISTRY, FOR A CONSUMER THAT IS NOT THE BROWSER.
+//
+// The registry is one structure: each network names its chain id, its native coin, the tokens it accepts and,
+// where it exists, the DEX deployment. A backend that validates a chain id and a token against it must read the
+// same data the page reads, or the two drift apart silently.
+//
+// Names only: the engine owns the values. Nothing here is re-implemented.
+
+export { ASYNC_ROUTE_PROVIDERS, CHAINS, DEFAULT_CHAIN, DEX_CHAINS } from "../../engine/core/config.js";

package/src/public/xmr.d.ts

@@ -316,3 +316,180 @@ 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>;
+
+/** The watch key form that matches the address's view public key, or null when none does. */
+export declare function viewKeyFormForAddress(viewSecret: string, expectedViewPubHex: string): string | null;
+
+/** A boundary height derived from a later unlock_time, or null when the time names no height. */
+export declare function laterBoundary(...args: unknown[]): unknown;
+
+/** One transaction that carries an output for a watched address. */
+export interface ScannedMatch {
+  [field: string]: unknown;
+}
+
+/** Walk a block range and return the transactions that pay a watched address. */
+export declare function scanRange(options: {
+  daemonUrl: string;
+  fromHeight: number;
+  toHeight: number;
+  watched: unknown;
+  log?: (event: unknown) => void;
+  concurrency?: number;
+  nowSec?: number | null;
+}): Promise<ScannedMatch[]>;

package/src/public/xmr.mjs

@@ -20,6 +20,9 @@ export {
   prefixFor,
 } from "../../engine/monero/address.js";
 
+// THE BLOCK WALK A WATCHER RUNS: the same scanner the page uses, without a wallet.
+export { laterBoundary, scanRange, viewKeyFormForAddress } from "../../engine/monero/scan.js";
+
 export { createHalves } from "../../engine/atomic/halves.js";
 export { createDleq2 } from "../../engine/atomic/dleq2.js";
 
@@ -27,3 +30,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";