@ninsei-labs/sdk 0.43.1 → 0.44.0

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/provider/envFile.mjs

@@ -0,0 +1,106 @@
+// THE SERVICE SETTINGS FILE: WHERE IT LIES AND HOW IT IS READ.
+//
+// The module deliberately imports NOTHING from config.mjs: the entry point connects it BEFORE the config loads, so that
+// the values get into the environment in time. config.mjs reads process.env at module load time, and static
+// imports in ESM run before any code of the file - so 'read the file, then import the config' is
+// possible only through a dynamic import and only from a separate module.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// WHERE TO LOOK WHEN THE FLAG IS NOT GIVEN: the current directory (the command is run from the node tree), then rfq/ under it (the layout of the tree this node was cut from)
+// (the same run from the repository root), then .env - that is also a frequent name for a settings file. What was found
+// is printed: a silent read of 'some' file is exactly the case where people later look for why the settings are wrong.
+//
+// ORDER: THE LOCAL FILE OUTRANKS THE PRODUCTION ONE. The local contour puts its settings BESIDE the production ones
+// (rfq.env.local), and while the search went from the plain name to .local, the developer tool picked up the production
+// file: the wallet path /opt/ninsei/..., the production price feed and its age - and refused with 'nothing to price the order with' where
+// the settings were in place (the quote checks fell exactly on this, and `npm run payout` with them).
+// The reverse order can err in one direction only: on the server there is no .local file at all, and the production
+// one remains the only one. An explicit --env= still outranks everything.
+export const ENV_CANDIDATES = ["rfq.env.local", "rfq.env.local", "rfq.env", "rfq.env", ".env.local", ".env"];
+
+export function findEnvFile(cwd, candidates = ENV_CANDIDATES) {
+  for (const rel of candidates) {
+    const full = join(cwd, rel);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+
+// A PATH OF A FOREIGN MACHINE IN A SETTINGS FILE IS AN ERROR, NOT A SETTING.
+//
+// The trap was found in battle on 25.09.2026. The local files (*.env.local) travelled to the server with the directory upload
+// (the documented rsync commands had no --exclude '*.env.local'), the tool honestly took the local file -
+// it outranks the production one, see below - start directory and the result was:
+//
+//     /opt/ninsei/keys
+//
+// The check is one-sided DELIBERATELY: the reverse case - production paths /opt/... on a developer machine - is legitimate,
+// because the repository holds copies of the production files, and they must be readable. The function is pure: the platform comes
+// as a parameter, so its behaviour is checkable on any machine.
+export function foreignPathProblem(file, values, platform = process.platform) {
+  if (platform === "win32") return null;
+  for (const [key, value] of Object.entries(values || {})) {
+    const v = String(value).trim();
+    if (/^(?:[A-Za-z]:[\\/]|\\\\)/.test(v)) return { file, key, value: v };
+  }
+  return null;
+}
+
+export function foreignPathMessage(p) {
+  return "settings file " + p.file + " sets a Windows path in setting " + p.key + " (" + p.value
+    + "), and the system is not Windows. This is how a local file (*.env.local) copied from a developer "
+    + "machine looks: it must not be on the server, the service reads <service>/<service>.env. Delete the local "
+    + "file and repeat.";
+}
+
+// We read by the systemd rules: comments and broken lines are skipped, export is stripped, quotes are stripped,
+// spaces are trimmed.
+export function readEnvFile(path) {
+  const out = {};
+  for (const raw of readFileSync(path, "utf8").split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    const key = line.slice(0, eq).replace(/^export\s+/, "").trim();
+    let value = line.slice(eq + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key) out[key] = value;
+  }
+  // The file is read, but the values may be FROM A FOREIGN MACHINE - then it is a refusal, not a setting.
+  const foreign = foreignPathProblem(path, out);
+  if (foreign) throw new Error(foreignPathMessage(foreign));
+  return out;
+}
+
+// WE APPLY THE FILE TO THE ENVIRONMENT. The file is the SERVICE's configuration, so it outranks what happened to be
+// exported in the shell; explicit command flags are parsed later and outrank both. We return the key names
+// without values: printing setting values into the log is not allowed.
+// VARIABLE SUBSTITUTION LIVES HERE, NOT IN EVERY TOOL. In the local file the settings are written as
+// ${STACK_DATA}/rfq-wallet.json, and they are substituted by the launcher (the stack itself). A tool that does not do this
+// sees literally "${STACK_DATA}" - and the consequences are not only 'wallet not found': by the same literal path it
+// creates an EMPTY quote database and then reports 'the log is empty' on a live contour, that is, the refusal looks like
+// absence of data. Before, the substitution was copied into one tool; a copy is a sign that the place is shared.
+export function substituteEnvVars(value, { dataDir, root }) {
+  return String(value)
+    .replace(/\$\{STACK_DATA\}/g, dataDir)
+    .replace(/\$\{ROOT\}/g, root);
+}
+
+export function applyEnvFile(path, target = process.env) {
+  const values = readEnvFile(path);
+  const dataDir = target.STACK_DATA || join(tmpdir(), "ninsei-stack");
+  const root = target.ROOT || process.cwd();
+  const substituted = {};
+  for (const [k, v] of Object.entries(values)) substituted[k] = substituteEnvVars(v, { dataDir, root });
+  // THE SUBSTITUTION MAY BRING A FOREIGN PATH: ${STACK_DATA} expands to the directory of THE machine where it is run.
+  // We check after the substitution too - that is exactly how the production case with /opt/ninsei/ surfaced.
+  const foreign = foreignPathProblem(path, substituted);
+  if (foreign) throw new Error(foreignPathMessage(foreign));
+  for (const [k, v] of Object.entries(substituted)) target[k] = v;
+  return Object.keys(values);
+}

package/src/provider/identity.mjs

@@ -0,0 +1,43 @@
+// RFQ NODE IDENTITY: the code from the PROVIDER ADDRESS and a human-readable name.
+//
+// THIS IS THE NODE'S RESPONSIBILITY, NOT OUR BACKEND'S. The node derives its code from its address itself, picks the
+// name itself and only sends them in the packet. Our backend accepts and CHECKS the shape, but invents nothing:
+// if we assigned the code or the name, we would be defining the provider's identity instead of him.
+//
+// WHY FROM THE ADDRESS AND NOT FROM THE KEY. A provider's identity is his EVM address: a quote signature is made with an EIP-712
+// wallet key, and the CHAIN checks that the key belongs to the address (maker registry, providerOf). The Ed25519 key
+// stays with the node, but does something else: the Monero halves are derived from it and the market packets are signed with it. The code
+// must follow the one the chain confirms - the address. The former code was computed from the ed25519 key and
+// therefore changed with it, not with the identity (owner's decision: backward compatibility is not needed).
+import { createHash, randomBytes, randomInt } from "node:crypto";
+
+// Code shape. Strict: "lp-" and exactly 8 hex in lower case.
+export const PROVIDER_CODE_RE = /^lp-[0-9a-f]{8}$/;
+
+// A human-readable name shorter than this limit: long names break tables and logs.
+export const DISPLAY_NAME_MAX = 48;
+
+// PROVIDER CODE. Computed from the provider's EVM ADDRESS (lower case, with 0x), not from the ed25519 key.
+//
+// Why deterministic and from one address: the code must be THE SAME everywhere the maker is seen (decision 14),
+// and must not change when the node restarts. The address IS the identity, so the code survives a key change and does not
+// depend on which of the accepted keys signed the quote this time.
+export function providerCode(address) {
+  const a = String(address == null ? "" : address).trim().toLowerCase();
+  if (!/^0x[0-9a-f]{40}$/.test(a)) {
+    throw new Error("provider code is derived from an EVM address, got " + JSON.stringify(String(address).slice(0, 24)));
+  }
+  return "lp-" + createHash("sha256").update(a).digest("hex").slice(0, 8);
+}
+
+// A RANDOM NAME - for the case when no name is set in the config. The node must not stay nameless: in market
+// view a provider has to be called something for a human. The alphabet is Latin simply because this is a generated name;
+// a manually set one may be anything - identity is defined by the code, not by the name.
+const WORDS = ["north", "harbor", "lumen", "cedar", "atlas", "quartz", "verde", "nova", "orbit", "delta"];
+
+export function randomDisplayName() {
+  // randomInt, not a modulo of random bytes: 65536 % 10 leaves six words one draw more likely than the other
+  // four. The difference is invisible in a display name, but a biased draw has no reason to exist at all.
+  const word = WORDS[randomInt(WORDS.length)];
+  return word + "-" + randomBytes(2).toString("hex");
+}

package/src/provider/sign.mjs

@@ -0,0 +1,164 @@
+// Signing the quote packet of the RFQ node. Ed25519, canonical packet.
+//
+// WHY THIS FILE IS COPIED AND NOT TAKEN FROM OUR SIGNER APPLICATION. The node runs AT THE PROVIDER: he has no
+// signer application of ours, and must not. An application that pulls code from a neighbouring directory is not
+// standalone - and the node must start on its own.
+//
+// THE RISK OF THE THREE IMPLEMENTATIONS DIVERGING (the feeder, rfq, the interface backend) IS CLOSED NOT BY COMMON CODE, BUT BY A CHECK.
+// the check on our side signs the same packet with both senders and confirms it with our
+// backend, and also compares the signatures against each other. They cannot diverge unnoticed.
+//
+// Canonical form: all fields except signature, keys sorted, no spaces. The order of serialisation is part of
+// the contract: if it diverges, the signatures stop matching for everyone at once.
+
+import { generateKeyPairSync, sign as nodeSign, verify as nodeVerify, createPrivateKey, createPublicKey } from "node:crypto";
+import { readFileSync, writeFileSync, chmodSync, existsSync, statSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// The canonical form of the packet: the signature is excluded, the keys are sorted, there are no spaces.
+export function canonical(payload) {
+  const { signature, ...rest } = payload || {};
+  const sortKeys = (v) => {
+    if (Array.isArray(v)) return v.map(sortKeys);
+    if (v && typeof v === "object") {
+      return Object.keys(v).sort().reduce((acc, k) => {
+        acc[k] = sortKeys(v[k]);
+        return acc;
+      }, {});
+    }
+    return v;
+  };
+  return JSON.stringify(sortKeys(rest));
+}
+
+export function signPayload(payload, privateKeyPem, keyId) {
+  // IMPORTANT: the FINAL packet is signed, already including keyId. Otherwise the signature is computed over one set of
+  // bytes while the check is over another (the check sees keyId in the packet), and one's own signature does not match.
+  // Verified by a round-trip test: before this fix 'own packet' gave false.
+  const pkg = { ...payload, keyId };
+  const signature = nodeSign(null, Buffer.from(canonical(pkg), "utf8"), createPrivateKey(privateKeyPem)).toString("base64");
+  return { ...pkg, signature };
+}
+
+// The check is needed by the interface backend when it turns signature checking on. It is not called now,
+// but it lies next to the signing: signing and checking must be computed the same way, otherwise they diverge.
+export function verifyPayload(payload, publicKeyPem) {
+  const { signature, ...rest } = payload || {};
+  if (!signature) return false;
+  try {
+    return nodeVerify(null, Buffer.from(canonical(rest), "utf8"), createPublicKey(publicKeyPem), Buffer.from(signature, "base64"));
+  } catch {
+    return false;
+  }
+}
+
+// The public key path: beside the private one, by the same name without ".key" and with ".pub" at the end.
+//   <path>.key -> <path>.pub
+// That way the operator does not look for the file by eye and does not copy the key from the terminal output: both files appear together.
+export function publicKeyPath(keyFile) {
+  return String(keyFile).replace(/\.key$/i, "") + ".pub";
+}
+
+// Key pair generation: the private one goes to a file with permissions 0600, the public one - TO A FILE BESIDE it and to the output
+// (the public one is not a secret, it is handy both to print and to keep as a file; the private one NEVER gets into the log).
+//
+// Overwriting an existing key is possible ONLY explicitly (force). Otherwise - a refusal: to silently wipe someone else's key
+// means breaking the provider, and he learns about it by rejected quotes rather than by a message.
+export function generateKeyFiles({ keyFile, force = false } = {}) {
+  if (!keyFile) throw new Error("key file is not specified");
+  if (existsSync(keyFile) && !force) {
+    const e = new Error("key already exists: " + keyFile + " - it was NOT overwritten");
+    e.code = "KEY_EXISTS";
+    throw e;
+  }
+  // We create the keys directory ourselves: the keys lie apart from the code (keys/), and it may be absent on a fresh install.
+  try { mkdirSync(dirname(keyFile), { recursive: true }); } catch { /* it is already there - not a reason to fall */ }
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const priv = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  const pub = publicKey.export({ type: "spki", format: "pem" }).toString();
+  writeFileSync(keyFile, priv, { mode: 0o600 });
+  try { chmodSync(keyFile, 0o600); } catch { /* on some file systems there are no permissions - not a reason to fall */ }
+  const pubFile = publicKeyPath(keyFile);
+  writeFileSync(pubFile, pub, { mode: 0o644 });
+  return { keyFile, pubFile, publicKeyPem: pub };
+}
+
+// Reading a key with a permission check: if the file is available to anyone besides the owner - a refusal, not silent work.
+// THE RAW KEY BYTES - the material for deriving the halves for orders. For an ed25519 key this is exactly
+// 32 bytes of a uniform seed: HMAC and hashing over them give a result indistinguishable from random.
+//
+// AN IMPORTANT CONSEQUENCE ONE MUST KNOW: the derivation requires the RAW key in the process. So a node whose
+// signing key has moved into hardware (HSM, a hardware wallet) will not be able to issue an order quote - and this is
+// an honest limitation, not a breakdown: while the key is there, the node is both identified and serves such quotes.
+export function privateKeySeedBytes(privateKeyPem) {
+  const ko = createPrivateKey(privateKeyPem);
+  const jwk = ko.export({ format: "jwk" });
+  if (!jwk || !jwk.d) throw new Error("could not get raw bytes from the signing key (an ed25519 key is required)");
+  const bytes = Buffer.from(jwk.d, "base64url");
+  if (bytes.length < 16) throw new Error("signing key is shorter than 16 bytes: unusable for half derivation");
+  return new Uint8Array(bytes);
+}
+
+export function loadPrivateKey(keyFile) {
+  const st = statSync(keyFile);
+  // The permission check - only where permissions exist. On Windows there are no POSIX mode bits (the file is always seen
+  // as 666), and access is defined by ACLs, not by these bits: refusing on Windows would mean not letting the
+  // service start locally at all. This is not a weakening - on Linux the check works as it worked.
+  if (process.platform !== "win32" && (st.mode & 0o077) !== 0) {
+    throw new Error("key file is accessible to others: " + keyFile + " (mode 0600 is required)");
+  }
+  return readFileSync(keyFile, "utf8");
+}
+
+// THE NODE'S PUBLIC KEY: THE ONE IT SIGNS WITH, AND NOT THE CONTENT OF THE FILE BESIDE IT (partner request to the node).
+//
+// WHY FROM THE LOADED KEY AND NOT FROM THE .pub FILE. The signature is made by the key the node read at start
+// (loadPrivateKey), so ITS public key must go out: the file beside it could be left from a former
+// key, come from a backup or be substituted. A reader who took the key from the file would check the signature
+// with the wrong key and would take a live node for a foreign one.
+//
+// WHY THE FILE IS STILL READ. A divergence of the file and the working key is a STATE, and it is NAMED
+// (nodePublicKeyFileMatches: false), not hidden: other tools and a human read the file, and by it they
+// judge the node. The file is re-read on EVERY read, not remembered at start: a file substituted beside the
+// key must be visible at once, not at the next node start.
+export function publicKeyBase64From(publicKeyPem) {
+  return createPublicKey(publicKeyPem).export({ type: "spki", format: "der" }).toString("base64");
+}
+
+// The SIGNING public key from a private PEM - with the same SPKI DER export as in the .pub file.
+// createPublicKey accepts the PRIVATE PEM itself and derives the public key from it; a repeated call on a KeyObject
+// (createPublicKey(createPublicKey(pem))) refuses - "expected private", so there is NO nesting here.
+export function signingPublicKeyBase64(privateKeyPem) {
+  return publicKeyBase64From(privateKeyPem);
+}
+
+// The content of the .pub file in the same form (base64 of SPKI DER), or the reason why it is absent.
+export function publicKeyFileBase64(pubFile) {
+  if (!pubFile) return { key: null, why: "the path of the public key file is not known" };
+  if (!existsSync(pubFile)) return { key: null, why: "the public key file is missing: " + pubFile };
+  try { return { key: publicKeyBase64From(readFileSync(pubFile, "utf8")), why: null }; }
+  catch (e) { return { key: null, why: "the public key file could not be read: " + String((e && e.message) || e).slice(0, 140) }; }
+}
+
+// THE REPORT FOR THE nodePublicKey FIELD IN GET /v1/info. The shape is assembled by ONE place - here; the listener only
+// returns it (makerApi.mjs), and the node passes its key (index.mjs), so the rule does not multiply.
+// key - the public key the node SIGNS with; file - what lies in the file beside it; matches - whether they
+// match (true/false, and null means 'nothing to compare with'); why - the reasons of the fields left null.
+export function nodePublicKeyReport({ privateKeyPem = null, keyFile = null, pubFile = null } = {}) {
+  const pubPath = pubFile || (keyFile ? publicKeyPath(keyFile) : null);
+  const file = publicKeyFileBase64(pubPath);
+  const why = {};
+  if (file.why) why.nodePublicKeyFile = file.why;
+  if (!privateKeyPem) {
+    why.nodePublicKey = "the node has no signing key it could read" + (keyFile ? " (" + keyFile + ")" : "") + ", so the key it signs with is unknown";
+    return { key: null, file: file.key, matches: null, why };
+  }
+  let key = null;
+  try { key = signingPublicKeyBase64(privateKeyPem); }
+  catch (e) { why.nodePublicKey = "the signing key could not be read: " + String((e && e.message) || e).slice(0, 140); }
+  // A DIVERGENCE IS A NAMED STATE, NOT SILENCE: false is the name of the state, and both keys stand side by side,
+  // so that one can sort it out without third-party tools. The node works with ITS OWN key meanwhile - it is loaded and
+  // the packets are signed with it; the file does not replace the signature.
+  const matches = key === null || file.key === null ? null : key === file.key;
+  return { key, file: file.key, matches, why };
+}

package/src/public/core.d.ts

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