@ninsei-labs/sdk 0.39.0

package/src/adapters/node-test-evm-wallet.mjs

@@ -0,0 +1,345 @@
+// A TEST EVM WALLET FOR NODE: KEY FROM THE ENVIRONMENT, REFUSAL ON A PRODUCTION NETWORK.
+//
+// WHY A SEPARATE ADAPTER. The SDK had only the browser wallet (evm-wallet.mjs): it receives the page's ready-made
+// EIP-1193 provider and signs via eth_sendTransaction - that is, the person's wallet does the signing. From Node
+// there is nothing to sign with, and a live run on a local chain was impossible: the SDK refused at the very first
+// step that needed a signature. This file closes exactly that hole - and only it.
+//
+// THIS IS A TOOL OF THE TEST CONTOUR, NOT A USER WALLET. The name shows it (node-test-*), and from that come two
+// rules that are not up for discussion here:
+//
+//   1) THE KEY COMES ONLY FROM THE ENVIRONMENT OR FROM A FILE, the path to which also lives in the environment.
+//      This module does NOT read command-line arguments AT ALL: a key in argv is visible in the shell history and
+//      in the process list, that is, it leaks before anything is signed. The key's value is never printed: only the
+//      address, transaction hashes and amounts go out.
+//
+//   2) ON A PRODUCTION NETWORK THE ADAPTER DOES NOT SIGN. The rule is not its own: it is already declared by the
+//      engine (sdk/src/swap-flow.mjs: production = chain.escrow.mode === "live" && !chain.testnet) and the page
+//      itself uses the same marker. A private "production network" marker would silently drift from the engine, and
+//      then the test key would sign real money. So the rule is taken from the network registry, not written here.
+//
+// DEPENDENCIES. The signature is assembled the same way as the provider node's (rfq/evmSend.mjs): @noble/curves
+// (secp256k1) and keccak256 - they are in the repository's devDependencies and already used in the project. There
+// is neither DOM nor node:fs at the top level here: the adapters directory is the only place where the environment
+// is allowed, but a static node:fs import would break the package's browser build, so the file is read via a
+// dynamic import and only inside the key-loading function.
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import keccakPkg from "keccak256";
+import { SdkError } from "../errors.mjs";
+import { config as engineConfig } from "../engine.mjs";
+
+const keccak256 = (bytes) => new Uint8Array(keccakPkg(Buffer.from(bytes)));
+
+// THE ENVIRONMENT VARIABLE NAMES - HERE, IN ONE PLACE: the run and the adapter must look at the same name,
+// otherwise the key "is there" but the adapter does not see it.
+export const KEY_ENV = "ARRAKIS_TEST_EVM_KEY";
+export const KEY_FILE_ENV = "ARRAKIS_TEST_EVM_KEY_FILE";
+export const RPC_ENV = "ARRAKIS_TEST_EVM_RPC";
+export const CHAIN_ENV = "ARRAKIS_TEST_EVM_CHAIN";
+export const CLAIMER_ENV = "ARRAKIS_TEST_EVM_CLAIMER";
+
+// AN EXPLICIT WHITELIST OF TEST NETWORKS - HERE, NOT IN THE ENGINE, and WHY. The engine's "production network" rule
+// (sdk/src/swap-flow.mjs: escrow.mode === "live" && !testnet) today does not trigger ON ANY recorded network: for
+// the registry's production networks the escrow is marked "simulated", that is, by the letter of the rule they are
+// not production. So the test key would also sign on mainnet - the engine would not notice, and the engine's rule
+// must not be changed (it is shared by the page and all legs). So the "signing is ALLOWED here" marker is set
+// separately and EXPLICITLY: only what is listed, and nothing more. First - the local anvil by chainId 31337.
+export const TEST_CHAIN_IDS = Object.freeze([31337]);
+
+const envOf = (name) => {
+  const box = typeof process !== "undefined" && process ? process.env : null;
+  const value = box ? box[name] : undefined;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+};
+export const envValue = envOf;
+
+// --- ENCODINGS -----------------------------------------------------------------------------------------
+const hexToBytes = (hex) => {
+  const h = String(hex || "").replace(/^0x/, "");
+  if (h.length === 0) return new Uint8Array(0);
+  if (h.length % 2) throw new SdkError("bad-input", { field: "hex", why: "odd" });
+  if (!/^[0-9a-fA-F]+$/.test(h)) throw new SdkError("bad-input", { field: "hex", why: "not-hex" });
+  return Uint8Array.from(Buffer.from(h, "hex"));
+};
+const bytesToHex = (bytes) => "0x" + Buffer.from(bytes).toString("hex");
+// Integers in RLP are encoded MINIMALLY, and zero is the empty string. A non-canonical encoding (an extra leading
+// zero) makes the node reject the WHOLE transaction, even though the signature is valid.
+const numToBytes = (value) => {
+  const v = BigInt(value);
+  if (v < 0n) throw new SdkError("bad-input", { field: "value", why: "negative" });
+  if (v === 0n) return new Uint8Array(0);
+  let hex = v.toString(16);
+  if (hex.length % 2) hex = "0" + hex;
+  return hexToBytes(hex);
+};
+const intFromBytes = (bytes) => numToBytes(BigInt(bytesToHex(bytes)));
+const encodeLength = (len, offset) => {
+  if (len < 56) return Uint8Array.from([offset + len]);
+  const lenBytes = numToBytes(len);
+  return Uint8Array.from([offset + 55 + lenBytes.length, ...lenBytes]);
+};
+const rlpItem = (item) => {
+  if (item instanceof Uint8Array) {
+    if (item.length === 1 && item[0] < 0x80) return item;
+    return Uint8Array.from([...encodeLength(item.length, 0x80), ...item]);
+  }
+  if (Array.isArray(item)) {
+    const body = item.flatMap((x) => [...rlpItem(x)]);
+    return Uint8Array.from([...encodeLength(body.length, 0xc0), ...body]);
+  }
+  throw new SdkError("bad-input", { field: "rlp" });
+};
+
+/** The account address for a private key: the last 20 bytes of the keccak256 of the UNcompressed point. */
+export function addressOfPrivateKey(privateKeyHex) {
+  const pub = secp256k1.getPublicKey(hexToBytes(privateKeyHex), false);
+  return "0x" + Buffer.from(keccak256(pub.slice(1))).toString("hex").slice(-40);
+}
+
+/**
+ * SIGNING A LEGACY TRANSACTION (type 0, EIP-155). Legacy specifically, not 1559: it has no dependency on fee
+ * history, and a local chain accepts it everywhere. Three things that are easy to get silently wrong (all three
+ * were already caught in rfq/evmSend.mjs by checking against the Foundry reference, and all three are repeated
+ * here deliberately):
+ *   prehash: false - Ethereum signs the ALREADY computed keccak hash; the library by default hashes the passed
+ *     data once more, and the signature becomes valid in form and completely foreign;
+ *   recovery is the FIRST byte of the 65-byte signature (not the last);
+ *   r and s go into RLP with minimal encoding, not full 32 bytes.
+ */
+export function signLegacyTx({ privateKey, nonce, gasPrice, gasLimit, to, data = "0x", value = 0, chainId }) {
+  const signing = rlpItem([
+    numToBytes(nonce), numToBytes(gasPrice), numToBytes(gasLimit), hexToBytes(to),
+    numToBytes(value), hexToBytes(data), numToBytes(chainId), new Uint8Array(0), new Uint8Array(0),
+  ]);
+  const digest = keccak256(signing);
+  const sig = secp256k1.sign(digest, hexToBytes(privateKey), { format: "recovered", prehash: false });
+  if (sig.length !== 65) throw new SdkError("bad-input", { field: "signature", got: sig.length });
+  const recovery = Number(sig[0]);
+  if (recovery !== 0 && recovery !== 1) throw new SdkError("bad-input", { field: "signature", why: "recovery" });
+  const r = intFromBytes(sig.slice(1, 33));
+  const s = intFromBytes(sig.slice(33, 65));
+  const v = BigInt(recovery) + 35n + BigInt(chainId) * 2n;
+  const raw = rlpItem([
+    numToBytes(nonce), numToBytes(gasPrice), numToBytes(gasLimit), hexToBytes(to),
+    numToBytes(value), hexToBytes(data), numToBytes(v), r, s,
+  ]);
+  return { raw: bytesToHex(raw), hash: bytesToHex(keccak256(raw)) };
+}
+
+// --- LOADING THE KEY ------------------------------------------------------------------------------------
+/**
+ * The key from the environment or from a file. THE LOADER LIVES NEXT TO THE ADAPTER ON PURPOSE: it is the only
+ * entry point for the key, and if the caller could pass the key as an argument, the rule "never from argv" would
+ * rest on an honest word.
+ * Returns { privateKey, address, from } - from names the source ("env" or "file"), the key itself goes out only in
+ * this field and is never printed anywhere.
+ */
+export async function testPrivateKeyFromEnv() {
+  let raw = envOf(KEY_ENV);
+  let from = "env";
+  if (!raw) {
+    const file = envOf(KEY_FILE_ENV);
+    if (!file) throw new SdkError("bad-input", { field: "privateKey", missing: [KEY_ENV, KEY_FILE_ENV] });
+    // DYNAMIC IMPORT: a static node:fs would end up in the package's browser build, though it is needed only here.
+    const fs = await import("node:fs");
+    raw = String(fs.readFileSync(file, "utf8")).trim().split(/\r?\n/)[0].trim();
+    from = "file";
+  }
+  const hex = raw.replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]{64}$/.test(hex)) throw new SdkError("bad-input", { field: "privateKey", why: "shape" });
+  return { privateKey: "0x" + hex.toLowerCase(), address: addressOfPrivateKey(hex), from };
+}
+
+// --- A READ PROVIDER ------------------------------------------------------------------------------------
+/**
+ * An EIP-1193-compatible provider over HTTP JSON-RPC. Needed where the SDK reads the chain with the leg driver
+ * (leg.balances -> eth_getBalance/eth_call) and as the reader for the lock step. THERE IS DELIBERATELY NO SIGNING
+ * HERE: eth_sendTransaction answers with a refusal, because this adapter must sign with its own key, not the node -
+ * otherwise the key would end up with the node, and the rule "key only from the environment" would stop meaning
+ * anything.
+ */
+export function evmRpcProvider(url) {
+  if (typeof url !== "string" || !/^https?:\/\//.test(url)) throw new SdkError("bad-input", { field: "rpcUrl" });
+  const call = async (method, params = []) => {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+    if (!res.ok) throw new SdkError("server-unavailable", { rpc: method, status: res.status });
+    const body = await res.json();
+    if (body && body.error) throw new SdkError("server-unavailable", { rpc: method, why: String(body.error.message || "").slice(0, 80) });
+    return body ? body.result : null;
+  };
+  const provider = {
+    url,
+    request({ method, params = [] }) {
+      if (method === "eth_sendTransaction") {
+        throw new SdkError("not-implemented", { surface: "provider.eth_sendTransaction" });
+      }
+      if (method === "eth_requestAccounts") return Promise.resolve([]);
+      return call(method, params);
+    },
+  };
+  return provider;
+}
+
+/**
+ * CONTRACT READ FOR THE LOCK SEAM: { to, data } -> hex. Exactly the shape the engine expects (www/js/evm/
+ * session.js, readContract), so it is dropped into the SDK WITHOUT an adapter. This is a CHAIN READ, not a node
+ * substitution: the calls go to the real node at the rpcUrl address.
+ */
+export function evmRpcReader({ url }) {
+  const provider = evmRpcProvider(url);
+  return ({ to, data } = {}) => {
+    if (!to || !data) throw new SdkError("bad-input", { field: "eth_call" });
+    return provider.request({ method: "eth_call", params: [{ to, data }, "latest"] });
+  };
+}
+
+// --- THE PRODUCTION-NETWORK MARKER ----------------------------------------------------------------------
+/**
+ * A PRODUCTION NETWORK - BY THE ENGINE'S RULE, NOT ITS OWN. The marker is taken from www/js/core/config.js (the
+ * testnet field) and sdk/src/swap-flow.mjs (escrow.mode === "live"): on a production network there is a live
+ * escrow and NO testnet marker. An unknown network is also considered production: there is nothing to prove it is a
+ * test one, and an error in that direction costs a test key signing over real money.
+ */
+export function isProductionChain(chainId) {
+  const chain = typeof engineConfig.chainByChainId === "function" ? engineConfig.chainByChainId(Number(chainId)) : null;
+  if (!chain) return { production: true, reason: "unknown-chain", chain: null };
+  const escrow = chain.escrow && typeof chain.escrow === "object" ? chain.escrow : null;
+  const production = Boolean(escrow && escrow.mode === "live" && !chain.testnet);
+  return { production, reason: production ? "production" : "testnet", chain };
+}
+
+// --- THE ADAPTER ----------------------------------------------------------------------------------------
+/**
+ * A test EVM wallet: the same interface as the page's wallet (vm, connect, disconnect, address, chainId, subscribe,
+ * driver + send/receipt), but the signature is its own and the chain is read directly.
+ *
+ * IT ACCEPTS ONLY AN ALREADY-LOADED KEY: the loader is testPrivateKeyFromEnv above, and there is no other entry.
+ * rpcUrl and chainId come from outside, but as VALUES (not the key), and the adapter keeps no factory address at
+ * all: the addresses come from the SDK/engine's network registry, and a second source of truth about addresses must
+ * not be introduced.
+ */
+export function nodeTestEvmWallet({ privateKey, rpcUrl, chainId = null, id = "node-test" } = {}) {
+  const hex = String(privateKey || "").replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]{64}$/.test(hex)) throw new SdkError("bad-input", { field: "privateKey" });
+  const key = "0x" + hex.toLowerCase();
+  const owner = addressOfPrivateKey(key);
+  const provider = evmRpcProvider(rpcUrl);
+  let connected = false;
+
+  const remoteChainId = async () => Number(BigInt(await provider.request({ method: "eth_chainId" })));
+
+  // REFUSAL ON A PRODUCTION NETWORK - ONE POINT THROUGH WHICH EVERY SIGNATURE PASSES. The check stands here, not in
+  // connect(), deliberately: connect may happen once and early, while the node's network may change later (or turn
+  // out to be the wrong one at the moment of signing). We ask the network OF THE NODE right before signing.
+  const assertTestContour = async () => {
+    const remote = await remoteChainId();
+    // A NETWORK OUTSIDE THE WHITELIST IS A REFUSAL NAMING THE NETWORK, BEFORE ANY SIGNATURE. This is the FIRST line
+    // of defense and it does not depend on how the network is marked in the registry (the production marker is the
+    // second line below, and today it may not trigger).
+    if (!TEST_CHAIN_IDS.includes(Number(remote))) {
+      throw new SdkError("wrong-chain", {
+        why: "test-contour-network-not-allowed", chainId: remote, allowed: [...TEST_CHAIN_IDS],
+      });
+    }
+    // THE SECOND LINE - THE ENGINE'S PRODUCTION-NETWORK RULE (not rewritten here, taken from the registry). It stays
+    // for the case where a network from the list is later marked production: then the signature still stops.
+    const view = isProductionChain(remote);
+    if (view.production) {
+      throw new SdkError("wrong-chain", {
+        why: "test-contour-refuses-live-network", chainId: remote, reason: view.reason,
+        escrowMode: view.chain && view.chain.escrow ? view.chain.escrow.mode : null,
+        testnet: view.chain ? Boolean(view.chain.testnet) : null,
+      });
+    }
+    if (chainId !== null && Number(chainId) !== remote) {
+      throw new SdkError("wrong-chain", { got: remote, want: Number(chainId) });
+    }
+    return remote;
+  };
+
+  return {
+    vm: "evm",
+    id,
+    // The address going out is what is anyway visible in every transaction. The key is not handed out by any method.
+    async connect(options = {}) {
+      const want = options && options.chainId !== undefined && options.chainId !== null ? Number(options.chainId) : chainId;
+      const remote = await remoteChainId();
+      if (want !== null && want !== undefined && Number(want) !== remote) {
+        throw new SdkError("wrong-chain", { got: remote, want: Number(want) });
+      }
+      connected = true;
+    },
+    async disconnect() {
+      connected = false;
+    },
+    address() {
+      return owner;
+    },
+    async chainId() {
+      return remoteChainId();
+    },
+    // NO SUBSCRIPTION: a local run has no "wallet changed network" event, while a poll timer would keep the process
+    // alive after the last transaction. We return an unsubscribe function, as the adapter interface requires.
+    subscribe() {
+      return () => {};
+    },
+    driver() {
+      return provider;
+    },
+    /**
+     * SENDING: sign with its own key and eth_sendRawTransaction. The nonce is taken by pending, the gas price - from
+     * the node, the gas limit - from the caller (the lock passes its own; if it did not, we estimate with a margin).
+     * None of these numbers is invented: a guessed gas limit costs a signature, and a guessed nonce costs a lost
+     * transaction.
+     */
+    async send({ to, data = "0x", value = 0n, gas = null }) {
+      if (!connected) throw new SdkError("wallet-not-connected");
+      if (typeof to !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(to)) throw new SdkError("bad-input", { field: "send.to" });
+      const remote = await assertTestContour();
+      const valueWei = BigInt(value === undefined || value === null ? 0 : value);
+      const nonce = Number(BigInt(await provider.request({ method: "eth_getTransactionCount", params: [owner, "pending"] })));
+      const gasPrice = BigInt(await provider.request({ method: "eth_gasPrice" }));
+      let gasLimit = gas === null || gas === undefined ? null : BigInt(gas);
+      if (gasLimit === null) {
+        const est = BigInt(await provider.request({
+          method: "eth_estimateGas",
+          params: [{ from: owner, to, value: "0x" + valueWei.toString(16), data }],
+        }));
+        gasLimit = (est * 12n) / 10n;
+      }
+      const signed = signLegacyTx({
+        privateKey: key, nonce, gasPrice, gasLimit, to, data,
+        value: valueWei, chainId: remote,
+      });
+      const hash = await provider.request({ method: "eth_sendRawTransaction", params: [signed.raw] });
+      if (typeof hash !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(hash)) {
+        throw new SdkError("server-unavailable", { step: "send-raw" });
+      }
+      // THE HASH IS CHECKED AGAINST THE LOCALLY COMPUTED ONE. A discrepancy means the node accepted a transaction
+      // different from the one we signed - and that must be found out here, not from missing money.
+      if (hash.toLowerCase() !== signed.hash.toLowerCase()) {
+        throw new SdkError("contract-reverted", { step: "hash-mismatch", node: hash, local: signed.hash });
+      }
+      return hash;
+    },
+    /**
+     * THE RECEIPT: asked once and returned as is (null - not in a block yet). THE ARGUMENT SHAPE IS ACCEPTED BOTH
+     * WAYS: a hash string and an object { hash }. This is not "just in case": the adapter contract declares
+     * receipt(txHash: string), while the lock path in the SDK calls the receipt as receipt({ hash }) - the engine's
+     * waitReceipt passes an object (www/js/evm/funding.js), and lock.mjs passes it into the adapter without
+     * normalisation. A strict adapter answers bad-input to this, the refusal is swallowed by the wait, and the
+     * escrow address is silently replaced with the PREDICTED one - that is, the "address from the receipt" check
+     * stops working without saying so.
+     */
+    async receipt(txHash) {
+      const hash = typeof txHash === "string" ? txHash : (txHash && typeof txHash.hash === "string" ? txHash.hash : null);
+      if (!hash) throw new SdkError("bad-input", { field: "receipt.txHash" });
+      const r = await provider.request({ method: "eth_getTransactionReceipt", params: [hash] });
+      return r || null;
+    },
+  };
+}

package/src/codes.mjs

@@ -0,0 +1,188 @@
+// CODE TABLES. The single place where the codes are named: they are read by the SDK, by the check and by the README.
+//
+// Why codes and not texts: wording, translations and tone are the interface's business. The core must name a
+// state so that it can be translated and coloured without parsing a string (issue #32, requirement 2).
+
+export const STEP_CODES = [
+  "awaiting_funding",
+  "funded",
+  "maker_locking",
+  "xmr_locked",
+  "ready",
+  "claimed",
+  "swept",
+];
+
+export const TERMINAL_CODES = ["success", "refunded_eth", "xmr_returned", "closed"];
+
+export const CHECK_CODES = [
+  "balance",
+  "gas",
+  "allowance",
+  "consent",
+  "network",
+  "settlement-network",
+  "stale",
+  "deadline",
+  "range",
+  "size",
+  "escrow-state",
+  "escrow-points",
+  "counterparty",
+  "slots",
+  "unchecked",
+  "unknown",
+];
+
+export const ERROR_CODES = [
+  "not-implemented",
+  "bad-input",
+  "wallet-not-connected",
+  "wallet-rejected",
+  "wrong-chain",
+  "quote-unavailable",
+  "quote-refused",
+  "quote-stale",
+  // THE ORDER-QUOTE SIGNATURE (EIP-712, quote format v7). Four different refusals, because the interface owes the
+  // person a different piece of advice for each:
+  //   quote-signature-invalid - the signature does not recover to any address: it is malformed or made for other bytes;
+  //   quote-key-mismatch      - the signature is valid but belongs to a key other than the one the quote names;
+  //   quote-field-unbound     - a field the signature must cover is absent, so nothing can be verified;
+  //   quote-expired           - the quote's own validUntil has passed.
+  "quote-signature-invalid",
+  "quote-key-mismatch",
+  "quote-field-unbound",
+  "quote-expired",
+  // WHO OWNS THE KEY - ASKED OF THE CHAIN (maker registry, providerOf). The signature alone proves only that
+  // SOME key signed; these four name what the registry (and the interface's policy) said:
+  //   quote-registry-unchecked  - there was no way to ask the chain, so the claim stays unproven;
+  //   quote-key-unknown         - the registry has no provider for this key (nobody owns it);
+  //   quote-provider-mismatch   - the registry maps the key to a DIFFERENT provider than the quote names;
+  //   quote-provider-not-allowed - the chain confirms the provider, but this interface does not admit it (policy).
+  "quote-registry-unchecked",
+  "quote-key-unknown",
+  "quote-provider-mismatch",
+  "quote-provider-not-allowed",
+  // THE FACTORY THAT WILL VERIFY THE QUOTE AND WHERE ITS FEE GOES (issue #103). The factory is taken from
+  // the provider's REGISTRY RECORD and its CODE is checked against the interface's known builds (extcodehash):
+  //   quote-factory-unchecked    - no way to read the factory / its code, so the claim stays unproven;
+  //   quote-factory-unknown      - the record names no factory (zero);
+  //   quote-factory-mismatch     - the signed quote names a DIFFERENT factory than the record;
+  //   quote-factory-code-unknown - the factory's code is not a build this interface knows.
+  "quote-factory-unchecked",
+  "quote-factory-unknown",
+  "quote-factory-mismatch",
+  "quote-factory-code-unknown",
+  "recovery-declined",
+  "recovery-failed",
+  "storage-unavailable",
+  "server-unavailable",
+  // A REFUSAL BY OUR SERVICE, AND IT DELIBERATELY DIFFERS FROM A CONNECTION FAILURE: the connection never got
+  // through - server-unavailable, while the service answered and did not accept - server-refused (with the
+  // status and its own reason). The advice to the interface differs: "retry" versus "investigate".
+  "server-refused",
+  // A TIMEOUT WAITING FOR XMR TO ARRIVE - a separate code. "We did not wait long enough" is a state of the
+  // money, not a breakdown and not an empty response: mixing it with other refusals, the interface could not
+  // tell "not arrived yet" from "broken".
+  "xmr-timeout",
+  // XMR IS ON THE ADDRESS BUT BARRED BY THE TRANSACTION'S unlock_time (issue #84). Distinct from `xmr-timeout`:
+  // that one means "nothing arrived within the wait", this one means "money is there and CANNOT be spent until a
+  // height or a date". Marking ready under it would hand the escrow to the maker for funds he cannot be paid from -
+  // so the core refuses with its own code, and the `until` boundary travels in params.
+  "xmr-locked",
+  // THE XMR ARRIVAL CHECK ON TWO NODES (issue #85). The decision "the XMR arrived" is made by the client, and a
+  // single node is a single truth that can lie. Each code names a different reason the button must stay closed:
+  //   xmr-nodes-disagree - a synced node has no such transaction in that block or a different block hash there;
+  //   xmr-no-nodes       - every node in the list is unreachable, so nothing can be confirmed;
+  //   xmr-underpaid      - the arrived amount is less than the expected one;
+  //   xmr-too-late       - less time remains before the ready deadline than the required confirmations take.
+  "xmr-nodes-disagree",
+  "xmr-no-nodes",
+  "xmr-underpaid",
+  "xmr-too-late",
+  "contract-reverted",
+  "insufficient-funds",
+  // CLAIM GAS FOR THE XMR SELLER (issue #78). The seller comes from Monero and has no coin on the EVM side to pay
+  // for the claim, so the maker may send it - but only when asked for, and only after the core has CONFIRMED the
+  // gas actually arrived. The three codes name the three states the interface must not blur together:
+  //   gas-refused-by-maker - the maker declines to pay the claim gas, and the refusal is shown BEFORE the deal;
+  //   gas-not-arrived      - the gas was ordered but the recipient's balance did not grow;
+  //   gas-too-little       - gas arrived, but below what a claim costs (an unmeasured requirement counts here too).
+  "gas-refused-by-maker",
+  "gas-not-arrived",
+  "gas-too-little",
+  "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.
+export const KIND_TO_CHECK = {
+  // size and range
+  "in-range": "range",
+  "above-max": "range",
+  "below-min": "range",
+  "range-unstated": "range",
+  "size-unstated": "size",
+  "amount-unstated": "size",
+  "unit-mismatch": "range",
+  // money
+  "balance-enough": "balance",
+  "balance-short": "balance",
+  "balance-unchecked": "balance",
+  "gas-enough": "gas",
+  "gas-short": "gas",
+  "reserve-unstated": "gas",
+  "native-unchecked": "gas",
+  // token allowance
+  "not-needed": "allowance",
+  "allowed": "allowance",
+  "allowance-short": "allowance",
+  "allowance-unchecked": "allowance",
+  "consent-missing": "consent",
+  // network
+  "network-match": "network",
+  "network-unknown": "network",
+  "wallet-unknown": "network",
+  "wallet-network": "network",
+  "settlement-network": "settlement-network",
+  // counterparty: a stand-in chain or a stand-in counterparty in the sandbox
+  "real-provider": "counterparty",
+  "stand-in-provider": "counterparty",
+  "standin-on-production": "counterparty",
+  // quote freshness
+  "fresh": "stale",
+  "stale": "stale",
+  "no-ttl": "stale",
+  "untimed": "stale",
+  "expired": "stale",
+  // deadlines
+  "deadlines-ok": "deadline",
+  "deadlines-unstated": "deadline",
+  "ready-by-in-past": "deadline",
+  "t1-not-after-ready-by": "deadline",
+  "ready-window-too-short": "deadline",
+  "claim-window-too-short": "deadline",
+  // A DEADLINE TOO FAR AHEAD (issue #88 - a concurrent edit in this tree): the order's t1 is a year away, and the
+  // ETH cannot be returned until then. It shares the `deadline` code with the other two extremes.
+  "deadline-too-far": "deadline",
+  // escrow state
+  "new": "escrow-state",
+  "already-funded": "escrow-state",
+  "already-claimed": "escrow-state",
+  "already-refunded": "escrow-state",
+  "state-unchecked": "escrow-state",
+  "off-step": "escrow-state",
+  // points and halves
+  "points-match": "escrow-points",
+  "point-mismatch": "escrow-points",
+  "commit-mismatch": "escrow-points",
+  "points-unchecked": "escrow-points",
+  // order book slots
+  "slots-match": "slots",
+  "slots-unchecked": "slots",
+  // misc
+  "unchecked": "unchecked",
+};
+
+export const checkCodeFor = (kind) => KIND_TO_CHECK[kind] || "unknown";