@ninsei-labs/sdk 0.39.0

package/src/index.mjs

@@ -0,0 +1,256 @@
+// THE SDK ENTRY POINT. Assembles the facades and holds rules common to all: no DOM, no texts, no windows.
+import { buildConfig } from "./config.mjs";
+import { createHttp } from "./http.mjs";
+import { createQuotes } from "./quotes.mjs";
+import { createPreflight } from "./preflight.mjs";
+import { createRecovery } from "./recovery.mjs";
+import { createSim } from "./sim.mjs";
+import { createWallet } from "./wallet.mjs";
+import { legFor } from "./legs/index.mjs";
+import * as engine from "./engine.mjs";
+import { createSwaps } from "./swaps.mjs";
+// ORDER ACTIONS - ON THE FACADE: marking ready, claiming and refunding go through the same chain-read seam as
+// the lock. The page gets them from the facade, not by importing the module separately.
+import { createActions } from "./actions.mjs";
+import { contextOf, verifyCounterparty, jointAddress } from "./order.mjs";
+// THE DEAL ENGINE, NOW A PACKAGE MODULE (#32, wave 3): the order flow used to be an engine file the page pulled
+// out of www/js. It is declared here so the facade carries the order READS the page needs (state and deadlines)
+// on the same chain-read seam as the actions.
+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";
+
+// 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
+// (sdk/README.md, "Stages").
+const stageOf = {
+  "quotes.firm": 2,
+  "swaps.start": 2,
+  "swaps.list": 2,
+  "swaps.get": 2,
+};
+
+const notImplemented = (surface) => {
+  const error = new SdkError("not-implemented", { surface, stage: stageOf[surface] ?? null });
+  return async () => { throw error; };
+};
+
+const normalizeOptions = (options) => {
+  const o = options && typeof options === "object" ? options : {};
+  const settlement = o.settlement && typeof o.settlement === "object" ? o.settlement : null;
+  if (!settlement || typeof settlement.chain !== "string" || !settlement.chain) {
+    fail("bad-input", { field: "settlement.chain" });
+  }
+  if (settlement.vm !== undefined && (typeof settlement.vm !== "string" || !settlement.vm)) {
+    fail("bad-input", { field: "settlement.vm" });
+  }
+  if (typeof o.xmrNetwork !== "string" || !o.xmrNetwork) fail("bad-input", { field: "xmrNetwork" });
+  const mode = o.mode === undefined ? "live" : o.mode;
+  if (mode !== "live" && mode !== "sim") fail("bad-input", { field: "mode", known: ["live", "sim"] });
+  if (o.storage !== undefined) {
+    const s = o.storage;
+    if (!(s && typeof s.get === "function" && typeof s.set === "function" && typeof s.remove === "function")) {
+      fail("bad-input", { field: "storage" });
+    }
+  }
+  if (o.fetch !== undefined && typeof o.fetch !== "function") fail("bad-input", { field: "fetch" });
+  if (o.now !== undefined && typeof o.now !== "function") fail("bad-input", { field: "now" });
+  if (o.routing !== undefined) {
+    const r = o.routing;
+    if (!r || typeof r !== "object" || (r.prefer !== undefined && !Array.isArray(r.prefer))) fail("bad-input", { field: "routing" });
+  }
+  // PATHS AND ADDRESSES: the shape is checked here, the meaning - when the configuration is built (where the
+  // registry's defaults live). They must not be silently dropped: an override nobody knows about is worse than
+  // a refusal.
+  if (o.routes !== undefined && (!o.routes || typeof o.routes !== "object" || Array.isArray(o.routes))) {
+    fail("bad-input", { field: "routes" });
+  }
+  if (o.endpoints !== undefined && (!o.endpoints || typeof o.endpoints !== "object" || Array.isArray(o.endpoints))) {
+    fail("bad-input", { field: "endpoints" });
+  }
+  // THE WITNESS NODES FOR THE ARRIVAL CHECK: the list the interface or the user brings. A shape check only - the
+  // meaning (defaults, per-network) is worked out when the configuration is built. An array replaces the list for
+  // the chosen network, an object replaces per network, and `addNodes` appends (that is how a user adds their own).
+  if (o.nodes !== undefined && !Array.isArray(o.nodes) && (!o.nodes || typeof o.nodes !== "object")) {
+    fail("bad-input", { field: "nodes" });
+  }
+  if (o.addNodes !== undefined && !Array.isArray(o.addNodes)) fail("bad-input", { field: "addNodes" });
+  // THE CHAIN-READ SEAM. By default the core reads the chain through the page's wallet (the engine's
+  // readContract), and in Node there is no such wallet: a live run from Node was impossible because there was
+  // nothing to read predict/status/fee with. From outside you can bring your own reader - a READ, not a node
+  // substitution: the calls go to the network whose address the registry returned. The shape is the same as the
+  // lock seam: ({to, data}) -> hex.
+  if (o.evmCall !== undefined && typeof o.evmCall !== "function") fail("bad-input", { field: "evmCall" });
+  // THE CODE-READ SEAM (issue #103): ({address}) -> hex code, for the extcodehash check of the factory. Same
+  // rule as evmCall - a read brought from outside, not a substitution of the chain.
+  if (o.evmCode !== undefined && typeof o.evmCode !== "function") fail("bad-input", { field: "evmCode" });
+  // THE INTERFACE'S ALLOW-LIST (POLICY, NOT PROOF): an array of provider addresses (or providerIds) OR a
+  // predicate. It is NOT the check itself - that is `providerOf` on chain, taken from the quote - but the
+  // interface's own decision about whom it trades with. A wrong shape is a typo, not a silent no-op.
+  if (o.allowedProviders !== undefined && o.allowedProviders !== null) {
+    const a = o.allowedProviders;
+    if (!Array.isArray(a) && typeof a !== "function") fail("bad-input", { field: "allowedProviders" });
+  }
+  // THE INTERFACE'S FACTORY POLICY (issue #103): an array of code hashes (extcodehash) the interface accepts.
+  // Like allowedProviders - a POLICY list, not proof; empty/absent means "no policy".
+  if (o.knownFactoryCodes !== undefined && o.knownFactoryCodes !== null && !Array.isArray(o.knownFactoryCodes)) {
+    fail("bad-input", { field: "knownFactoryCodes" });
+  }
+  // A PASS TO OUR SERVICE - A SEAM FROM OUTSIDE, like the wallet: only a wallet can sign the sign-in message
+  // (www/js/evm/auth.js, signIn), and requiring it of the core would mean opening windows and signing messages
+  // inside the SDK. The core receives a ready pass and presents it. A missing pass is NOT an option error: the
+  // "server" step then answers with the app's refusal (401) under a named code.
+  if (o.serverAuth !== undefined && typeof o.serverAuth !== "function") fail("bad-input", { field: "serverAuth" });
+  // YOUR OWN SWAP RECORD - A CAPABILITY, NOT A REQUIREMENT. By default the core builds the record and the order
+  // side itself (record.mjs + order.mjs) and uses that side both for the record and for the lock terms. The
+  // function is for whoever wants to bring THEIR OWN side; it must be a function, otherwise it is a typo, not a
+  // setting.
+  if (o.createRecord !== undefined && typeof o.createRecord !== "function") fail("bad-input", { field: "createRecord" });
+  // WATCHING THE MONERO ADDRESS: the rate and the timeout. They are checked here by shape, and their meaning is
+  // worked out when the configuration is built (where the engine settings' defaults live).
+  if (o.watch !== undefined) {
+    const w = o.watch;
+    if (!w || typeof w !== "object" || Array.isArray(w)) fail("bad-input", { field: "watch" });
+    for (const name of ["pollMs", "timeoutMs"]) {
+      if (w[name] !== undefined && !(Number.isFinite(Number(w[name])) && Number(w[name]) > 0)) fail("bad-input", { field: "watch." + name });
+    }
+  }
+  return {
+    settlement: { chain: settlement.chain, vm: settlement.vm },
+    xmrNetwork: o.xmrNetwork,
+    apiBase: typeof o.apiBase === "string" && o.apiBase ? o.apiBase : "/api",
+    assetsBase: typeof o.assetsBase === "string" && o.assetsBase ? o.assetsBase : "/",
+    mode,
+    storage: o.storage || null,
+    fetch: o.fetch || null,
+    now: o.now || null,
+    routing: o.routing || null,
+    // PATHS AND ADDRESSES PASS ON AS THEY ARE: their meaning is worked out when the configuration is built,
+    // where the registry's defaults live. They must not be dropped here - an override nobody knows about is
+    // worse than a refusal.
+    routes: o.routes || null,
+    endpoints: o.endpoints || null,
+    nodes: o.nodes === undefined ? null : o.nodes,
+    addNodes: o.addNodes === undefined ? null : o.addNodes,
+    evmCall: o.evmCall || null,
+    evmCode: o.evmCode || null,
+    allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
+    knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
+    serverAuth: o.serverAuth || null,
+    watch: o.watch || null,
+    createRecord: o.createRecord || null,
+  };
+};
+
+export function createNinsei(options) {
+  const o = normalizeOptions(options);
+  const config = buildConfig({
+    settlement: o.settlement,
+    xmrNetwork: o.xmrNetwork,
+    apiBase: o.apiBase,
+    assetsBase: o.assetsBase,
+    mode: o.mode,
+    routing: o.routing,
+    routes: o.routes,
+  endpoints: o.endpoints,
+  watch: o.watch,
+  nodes: o.nodes,
+  addNodes: o.addNodes,
+});
+  const leg = legFor(config.settlement.vm);
+  const wallet = createWallet({ settlement: config.settlement.chain, leg });
+  // THE GUARDS READ THE NETWORK UNDER THE NAME evmNetwork, WHILE THE CONFIGURATION BUILDER RETURNS IT AS
+  // settlement.chain (preflight.mjs: both chain.nativeSymbol and config.evmNetwork.id). The names diverged, and
+  // ANY guard call failed with a TypeError - without a code, that is, not as a refusal but as a breakdown. A
+  // live swap start was therefore impossible in principle: preflight is called as the first step of start. We
+  // hand the guards a record of the same network under the name they expect; from outside it is the same config
+  // as before.
+  const preflight = createPreflight({ config: { ...config, evmNetwork: config.settlement.chain }, wallet, limits: config.limits });
+  const sim = o.mode === "sim" ? createSim() : null;
+  // THE STORAGE THE INTERFACE BROUGHT BECOMES THE CORE'S STORAGE: unfinished swaps and the agent session live
+  // where the interface decided (browser storage, memory, a server). Without the option the core takes its
+  // default: web storage if it is present in the environment, otherwise memory.
+  if (o.storage) {
+    engine.store.setStorage(o.storage);
+    engine.auth.setSessionStore(o.storage);
+  }
+  const http = createHttp({ apiBase: config.apiBase, fetchImpl: o.fetch, timeoutMs: config.limits.httpTimeoutMs });
+  // THE CHAIN READ AND THE ALLOW-LIST GO INTO THE QUOTE CHECK: without the read the signature certifies itself,
+  // so the same evmCall seam the lock and the actions use is handed to the quotes too.
+  const providerAllowed = (() => {
+    const a = o.allowedProviders;
+    if (a === null || a === undefined) return null;
+    if (typeof a === "function") return (provider) => a(provider) === true;
+    const set = new Set(a.map((v) => String(v).toLowerCase()));
+    return (provider) => set.has(String(provider).toLowerCase());
+  })();
+  const quotes = createQuotes({ config, http, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
+    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes });
+  // THE SAME CHAIN-READ SEAM AS THE LOCK AND THE CORE: checking the slots and signing must go one way, otherwise
+  // part of the check goes past the wallet and part does not.
+  const actions = createActions({ call: o.evmCall });
+  // THE SAME CHAIN-READ SEAM FOR THE ORDER READS: state and deadlines must be read by the wallet that will sign,
+  // not by a second provider. Without a caller reader the module keeps its engine default.
+  const orderDeps = typeof o.evmCall === "function" ? { call: o.evmCall } : {};
+
+  return Object.freeze({
+    config,
+    wallet,
+    preflight,
+    recovery: createRecovery(),
+
+    // THE ORDER: checking the counterparty's side and the joint address. Both checks - BEFORE signing: after it
+    // there is nothing to fix.
+    // ORDER ACTIONS ON THE ESCROW: marking ready, claiming, refunding. Expectations (expect) are mandatory -
+    // without them there is nothing to check against, and the signature does not go out.
+    actions,
+    order: {
+      context: (terms) => contextOf(terms),
+      verifyCounterparty: (request) => verifyCounterparty(request),
+      jointAddress: (request) => jointAddress(request),
+      // ORDER STATE FROM THE CHAIN (escrow slot 3): which of the four states the order is in. Read, not guessed
+      // from logs - the very call the engine used to make from www/js/core/swap-flow.js.
+      status: (escrow) => orderFlow.orderStatus(escrow, orderDeps),
+      // THE ORDER DEADLINES (t1, readyBy, termsHash) from the chain: the screen needs them to say whether the
+      // person is in the dead zone.
+      deadlines: (escrow) => orderFlow.orderDeadlines(escrow, orderDeps),
+    },
+    sim,
+    quotes: {
+      // LIVE INDICATIVE QUOTES. The subscription delivers data on every poll tick and is removed by the function
+      // watch returned; the last listener to leave stops the polling.
+      watch: (request, onSnapshot) => quotes.watch(request, onSnapshot),
+      snapshot: () => quotes.snapshot(),
+      // A firm quote is stage 2: it is signed with a key and lives in the order protocol, not in a market snapshot.
+      // A FIRM QUOTE: accepted only with a confirmed provider signature.
+      firm: (request) => quotes.firm(request),
+    },
+    // READING STATE WORKS, STARTING IS NAMED HONESTLY: list/get raise swaps from storage after a page reload;
+    // start holds the step order and runs into the step that creates the record (stage 2).
+    // THE MODE AND THE MONERO NETWORK GO INTO THE SWAP START: in the sandbox the counterparty's side is built by
+    // a stand-in, on a live chain - only from the quote (a stand-in there would mean money against a
+    // non-existent side), and the network is needed to build the shared Monero address.
+    // THE CHAIN READER GOES INTO THE SWAP START: it will check the escrow address, the order state and the fee
+    // before signing.
+    // THE PATHS, THE POLL TIMINGS AND THE PASS GO INTO THE START: without the configuration the "server" step
+    // would not know where to knock, and without the pass there is nothing to present to the service (and that
+    // is a refusal with a CODE, not an invented path).
+    swaps: createSwaps({ preflight, http, mode: o.mode, xmrNetwork: o.xmrNetwork, call: o.evmCall,
+      config, auth: o.serverAuth, watch: o.watch,
+      // THE RECORD IS BUILT HERE ITSELF, and one brought from outside is only the caller's preference.
+      createRecord: o.createRecord }),
+    // XMR WITHDRAWAL: parsing the file and requesting data work; the withdrawal itself is named (the Monero
+    // wallet as an adapter).
+    sweep: createSweep({ http, config }),
+  });
+}
+
+export { SdkError, ERROR_CODES, STEP_CODES, CHECK_CODES };
+
+// THE LEVEL WALK IS ON THE PACKAGE SURFACE. A maker publishes a level set (chunks of volume with their own prices)
+// and both the node and the client compute a firm price by WALKING it - the client must reach the SAME price before
+// signing. `levelsWalkSpec.mjs` is the ONE implementation, a byte-identical twin of the node's copy, and it is
+// exported so a consumer can run the same walk: the set in, the answer out. Answers are values with a `reason`
+// token on refusal, never exceptions.
+export { checkLevels, xmrForAsset, assetForXmr, toBigInt, XMR_ATOMIC_PER_ONE } from "./levelsWalkSpec.mjs";

package/src/legs/evm.mjs

@@ -0,0 +1,118 @@
+// THE EVM LEG DRIVER. Everything the SDK knows about an EVM network as a settlement side.
+//
+// This is not the full leg yet: the escrow reads and writes (fund/markReady/claim/refund, the order state) will
+// land here in stage 2. Already here: what the network is called for the wallet, how to tell that the wallet is on
+// the right network, how balances are read, and the ROUTE-PROVIDER REGISTRY (our declared routes today, an
+// external aggregator when it arrives).
+export const vm = "evm";
+
+/** What this network is called for the wallet: for EVM - a numeric chainId. */
+export const walletChainId = (chain) => Number(chain.chainId);
+
+/** Does the wallet's network match the settlement network. The comparison is VM-specific, so it lives in the driver. */
+export const sameChain = (walletChainIdValue, chain) => {
+  const want = walletChainId(chain);
+  const got = Number(walletChainIdValue);
+  return Number.isFinite(got) && Number.isFinite(want) && got === want;
+};
+
+// THE balanceOf(address) SELECTOR - 0x70a08231. It is not taken from memory: the same value is declared in the
+// project (rfq/evm.mjs, "verified against the project's code") and used by the engine (www/js/evm/session.js). The
+// match is checked by tools/check-sdk.mjs - it reads the engine's registry and fails if they diverge.
+export const BALANCE_OF_SELECTOR = "0x70a08231";
+
+const toMinimal = (hex) => {
+  try {
+    return BigInt(hex).toString(10);
+  } catch {
+    return null;
+  }
+};
+const addrWord = (address) => String(address).replace(/^0x/, "").toLowerCase().padStart(64, "0");
+
+/**
+ * BALANCES: the native coin - eth_getBalance, a token - balanceOf via eth_call. decimals are taken from the
+ * registry (they held the BSC trap), not from the chain's answer: the answer carries only the number in minimal
+ * units.
+ * Not read - null, not zero: zero would look like an empty wallet.
+ */
+export async function balances({ driver, address, tokens }) {
+  const out = [];
+  for (const token of tokens) {
+    let amount = null;
+    try {
+      if (token.address === null) {
+        amount = toMinimal(await driver.request({ method: "eth_getBalance", params: [address, "latest"] }));
+      } else {
+        const data = BALANCE_OF_SELECTOR + addrWord(address);
+        amount = toMinimal(await driver.request({ method: "eth_call", params: [{ to: token.address, data }, "latest"] }));
+      }
+    } catch {
+      amount = null;
+    }
+    out.push({ token: token.id, symbol: token.symbol, decimals: token.decimals, amount });
+  }
+  return out;
+}
+
+// THE ROUTE-PROVIDER REGISTRY (DEX/aggregator). Their role is one: turn what the person gives into what the escrow
+// is funded with, and name the expected output. They DIFFER in the method: your own declared routes (DEX_ROUTES
+// data in the engine's registry) or an external aggregator (1inch and the like).
+//
+// WHAT THIS GIVES: an aggregator becomes a CHOICE, not a rewrite - a new file and a line in this registry. The
+// pre-signature guards are shared by all providers: the price is not market, the amount is covered, the token
+// allowance - otherwise an external route would become a hole in those very guards.
+//
+// THE SHAPE OF THE SWAP IS DECLARED, NOT ASSUMED. A provider says which way its swap settles, because the deal
+// path differs by it. Uniswap and SushiSwap are router AMMs - the router runs INSIDE the user's transaction, so
+// the swap and the escrow funding are ONE transaction (shape "sync"). CoWSwap is an intent auction - the person
+// signs an intent, and the settlement arrives LATER as a separate transaction sent by someone else (shape
+// "async"). Hard-coding "one transaction" into the deal path would fit only the first and force a rewrite for the
+// second, so the shape lives HERE and the path ASKS for it (see requireSyncProvider) instead of assuming it.
+//
+// AN ASYNCHRONOUS PROVIDER MUST DECLARE WHAT ENDS ITS EXECUTION - not a stub field, but something that can really
+// be checked: `settled(request)`, a check that reads the outcome (for an intent auction - the settlement of the
+// signed order) and answers whether the swap has ended and with what. A provider that cannot say this is
+// incomplete, and the check refuses it by NAME rather than treating it as synchronous.
+//
+// REQUIREMENT FOR A PROVIDER: id, kind, shape ("sync" | "async"), plan(...) -> { ok, expectedOutWei | code,
+// route?, calldata?, to? } and, for shape "async", settled(...). Execution (assembling and sending the
+// transaction) is stage 3; for now only our provider is declared, and its plan honestly answers with a code.
+export const SYNC = "sync";
+export const ASYNC = "async";
+
+const ROUTE_PROVIDERS = {
+  declared: {
+    id: "declared",
+    kind: "declared",
+    // OUR ROUTES ARE A ROUTER: the swap runs inside the user's own transaction and funds the escrow in it - hence
+    // "sync", and hence no completion step: there is no later action to wait for.
+    shape: SYNC,
+    async plan() {
+      return { ok: false, code: "not-implemented", stage: 3 };
+    },
+  },
+};
+
+/** Who can execute a route at all. The list is needed by the "no such provider" error. */
+export const routeProviders = () => Object.keys(ROUTE_PROVIDERS).sort();
+export const routeProviderFor = (id) => ROUTE_PROVIDERS[id] || null;
+
+/**
+ * THE GATE OF A PATH THAT ASSUMES "SWAP AND FUNDING IN ONE TRANSACTION". Such a path (stage 3: the router leg that
+ * funds the escrow with the very transaction that swaps) needs a provider whose swap happens in the user's OWN
+ * transaction. An asynchronous provider settles in a LATER, separate action, and silently treating it as
+ * synchronous would fund an escrow with nothing behind it - so it is refused BY NAME, with a `reason` token (the
+ * same shape of refusal the level book uses), not assumed to be synchronous.
+ *
+ * Returns { ok: true, provider } or { ok: false, reason, ... } - a refusal as a VALUE, not an exception: the
+ * caller keeps its own wording for the token.
+ */
+export const requireSyncProvider = (id) => {
+  const provider = routeProviderFor(id);
+  if (!provider) return { ok: false, reason: "provider-unknown", provider: typeof id === "string" ? id : null, known: routeProviders() };
+  if (provider.shape !== SYNC) {
+    return { ok: false, reason: "provider-not-synchronous", provider: provider.id, shape: provider.shape === undefined ? null : provider.shape };
+  }
+  return { ok: true, provider };
+};

package/src/legs/index.mjs

@@ -0,0 +1,50 @@
+// SETTLEMENT-LEG DRIVERS BY VIRTUAL MACHINE (VM).
+//
+// Why the seam was introduced right away, though one leg is implemented. Every VM has its own settlement side: for
+// EVM it is a contract with an ABI and eth_* calls, for Tron its own contracts and its own resource model, for
+// Solana a program and accounts. What they share is only the ROLE: deposit, mark ready, claim, refund, read
+// state. So a "vm -> driver" map lives here, and the leg knows about this role, not about EVM: adding Tron or
+// Solana means putting another file next to it and registering it HERE, touching neither the quotes, nor the
+// Monero leg, nor the state machine.
+//
+// What must not be in a driver: no user strings, no DOM. A driver is chain reads and writes plus knowing what the
+// network is measured in for this VM.
+import * as evm from "./evm.mjs";
+
+export const LEGS = { evm };
+
+/** VMs for which a driver already exists. The list is needed by the check and by the "this network is not supported yet" error. */
+export const implementedVms = () => Object.keys(LEGS).sort();
+
+/** The leg driver or null. The caller must decide what to do with null: EVM must not be silently substituted. */
+export const legFor = (vm) => LEGS[vm] || null;
+
+// --- NETWORK -> VIRTUAL MACHINE -> DRIVER ------------------------------------------------------------
+// The SDK keeps no network table: the source of truth is the engine's registry (www/js/core/config.js). A copy
+// here would silently drift from it, and the swap would go to the wrong network.
+import * as engine from "../engine.mjs";
+import { fail } from "../errors.mjs";
+
+/** A registry network by id, or null. */
+export const chainOf = (chainId) => (engine.config.CHAINS || []).find((c) => c && c.id === chainId) || null;
+
+/**
+ * The network's virtual machine. An unknown network is null: "evm" must not be substituted by default, otherwise a
+ * network without a driver would travel the EVM path and refuse somewhere deep inside foreign code.
+ */
+export const vmOfChain = (chainId) => {
+  const chain = chainOf(chainId);
+  return chain && chain.vm ? chain.vm : null;
+};
+
+/**
+ * The leg driver for a network. A network without a driver is a NAMED refusal: you can see which vm is not
+ * supported and which are. This is exactly the rule "no network is silently assumed to be EVM".
+ */
+export const legForChain = (chainId) => {
+  const vm = vmOfChain(chainId);
+  if (!vm) fail("bad-input", { field: "chain", chain: typeof chainId === "string" ? chainId : null });
+  const driver = legFor(vm);
+  if (!driver) fail("not-implemented", { surface: "legs", vm, implemented: implementedVms() });
+  return driver;
+};

package/src/levelsWalkSpec.mjs

@@ -0,0 +1,183 @@
+// THE MAKER'S LEVEL SET: THE REFERENCE WALK OVER IT (issue #110, part B).
+//
+// WHY. The maker sends the node a LEVEL SET - chunks of volume with their own prices - and the node computes a
+// firm price by WALKING it. The client (SDK) needs the same walk to show the same price before signing. This is
+// the SINGLE implementation of the walk and of the level-set rules; the file exists as BYTE-IDENTICAL copies in
+// two places, and tools/check-levels-walk.mjs verifies that:
+//     node: rfq/lib/levelsWalkSpec.mjs        SDK: sdk/src/levelsWalkSpec.mjs
+// Two copies, not an import: the node runs on the provider's machine and sees neither www/ nor sdk/, and the SDK
+// package does not see rfq/ - each starts on its own (the same argument as rfq/lib/quoteEip712Spec.mjs). A
+// divergence would mean the node and the client name a DIFFERENT price for the same set.
+//
+// NUMBERS ARE INTEGERS ONLY, BigInt ONLY (rule 10). XMR is in atomic units (1 XMR = 1e12). A price is in the
+// asset's atomic units PER 1 WHOLE XMR (for a wei asset that is wei per 1 XMR). No Number for money.
+//
+// THE RULES OF THE SET (part B of the ticket):
+//   1. a level is the NEXT chunk of volume, not a running total;
+//   2. the best price comes FIRST, then only worse (for ask the best is the lowest, for bid the highest; checked
+//      by the same rule on the reversed set, the orientation argument); a violation is a NAMED refusal, not silence;
+//   3. the first level sets the minimum deal size (there is no separate min);
+//   4. an EMPTY set = the side is off, and that is NOT an error;
+//   5. the walk goes BOTH ways: "I give asset - how much XMR" and "I give XMR - how much asset";
+//   6. rounding to atomic units is in the maker's favour;
+//   7. one orientation: volume in XMR, price in the asset per 1 XMR;
+//   8. a fixed swap fee (fee in wei, separate for each side): the buyer pays the walk PLUS the fee, the seller
+//      receives the walk MINUS the fee. It is NOT spread over the volume: otherwise the average price would fall
+//      as the deal grew and the levels would break rule 2;
+//   9. an order deeper than the side is a NAMED refusal; there is no partial fill.
+//
+// ROLES. role="buy"  - the taker BUYS XMR and PAYS the asset (the fee is ADDED to the asset).
+//       role="sell" - the taker SELLS XMR and RECEIVES the asset (the fee is SUBTRACTED from the asset).
+//
+// REFUSALS COME BACK AS A reason TOKEN, NOT AS AN EXCEPTION: the caller must have a named refusal it can show
+// in words, not a crash without a cause.
+
+export const XMR_ATOMIC_PER_ONE = 1000000000000n;
+
+// Parse an integer value into BigInt. Fractional / NaN / garbage -> null (the caller names the refusal, it does not guess).
+export function toBigInt(value) {
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number") {
+    return Number.isInteger(value) && Number.isSafeInteger(value) ? BigInt(value) : null;
+  }
+  if (typeof value === "string") {
+    const s = value.trim();
+    if (/^[0-9]+$/.test(s)) return BigInt(s);
+    if (/^0x[0-9a-fA-F]+$/.test(s)) return BigInt(s);
+  }
+  return null;
+}
+
+// CHECK THE SET. Returns a NAMED verdict (it does not throw):
+//   { ok: true, enabled: false }                              - empty set: the side is off (rule 4);
+//   { ok: true, enabled: true, count, minAtomic, totalAtomic } - the set is valid;
+//   { ok: false, reason, index }                              - the set breaks a rule.
+export function checkLevels(levels, orientation = "ask") {
+  if (!Array.isArray(levels)) return { ok: false, reason: "levels-not-array" };
+  if (levels.length === 0) {
+    return { ok: true, enabled: false, count: 0, minAtomic: 0n, totalAtomic: 0n };
+  }
+  if (orientation !== "ask" && orientation !== "bid") return { ok: false, reason: "levels-bad-orientation" };
+  // ORIENTATION. Rule 2 ("the best price first, then only worse") reads DIFFERENTLY per side: for ask the best is
+  // the LOWEST, for bid the HIGHEST. So for bid the REVERSED set is checked - by the same device already used in
+  // the listener (levelOrderRefusal), not by a second rule beside it. The walk itself still runs over the ORIGINAL
+  // order: only the RULE is reversed, not the list (the best price must stay first for the walk).
+  const order = orientation === "bid" ? levels.slice().reverse() : levels;
+  let totalAtomic = 0n;
+  let prevPrice = null;
+  for (let index = 0; index < order.length; index += 1) {
+    const level = order[index];
+    if (!level || typeof level !== "object") return { ok: false, reason: "levels-bad-level", index };
+    const amount = toBigInt(level.amount);
+    const price = toBigInt(level.price);
+    if (amount === null || price === null) return { ok: false, reason: "levels-not-integer", index };
+    if (amount <= 0n || price <= 0n) return { ok: false, reason: "levels-not-positive", index };
+    // Equal prices are allowed (two chunks at one price are one level cut in two); a worse price is a NAMED
+    // refusal, and the index is translated back to the ORIGINAL numbering so the maker finds the guilty level.
+    if (prevPrice !== null && price < prevPrice) {
+      return { ok: false, reason: "levels-not-best-first", index: orientation === "bid" ? levels.length - 1 - index : index };
+    }
+    prevPrice = price;
+    totalAtomic += amount;
+  }
+  return { ok: true, enabled: true, count: levels.length, minAtomic: toBigInt(levels[0].amount), totalAtomic };
+}
+
+// THE COST OF A CHUNK OF VOLUME IN WEI, ROUNDED UP (rule 6, in the maker's favour).
+function levelCostWei(amountAtomic, priceWeiPerXmr) {
+  const num = amountAtomic * priceWeiPerXmr;
+  return (num + XMR_ATOMIC_PER_ONE - 1n) / XMR_ATOMIC_PER_ONE;
+}
+
+// HOW MANY XMR ATOMS A BUDGET GIVES WITHIN ONE LEVEL, ROUNDED DOWN (rule 6).
+function levelXmrForBudget(budgetWei, priceWeiPerXmr) {
+  return (budgetWei * XMR_ATOMIC_PER_ONE) / priceWeiPerXmr;
+}
+
+// THE FULL COST OF A SIDE (the sum of its levels' costs) and its volume - computed once.
+function sideSummary(levels) {
+  let totalAtomic = 0n;
+  let fullCostWei = 0n;
+  for (const level of levels) {
+    const amount = toBigInt(level.amount);
+    const price = toBigInt(level.price);
+    totalAtomic += amount;
+    fullCostWei += levelCostWei(amount, price);
+  }
+  return { totalAtomic, fullCostWei };
+}
+
+// THE WALK WITHOUT THE FEE: a budget is given - how much XMR it yields (rounding down within a level, rule 6).
+function walkXmrForBudget(levels, budgetWei) {
+  let remaining = budgetWei;
+  let xmrAtomic = 0n;
+  for (const level of levels) {
+    const amount = toBigInt(level.amount);
+    const price = toBigInt(level.price);
+    const full = levelCostWei(amount, price);
+    if (remaining >= full) {
+      xmrAtomic += amount;
+      remaining -= full;
+      continue;
+    }
+    xmrAtomic += levelXmrForBudget(remaining, price);
+    break;
+  }
+  return xmrAtomic;
+}
+
+// THE WALK WITHOUT THE FEE: an XMR volume is given - what it costs (each chunk's cost rounded up, rule 6).
+function walkCostForXmr(levels, xmrAtomic) {
+  let left = xmrAtomic;
+  let costWei = 0n;
+  for (const level of levels) {
+    if (left <= 0n) break;
+    const amount = toBigInt(level.amount);
+    const price = toBigInt(level.price);
+    const take = left < amount ? left : amount;
+    costWei += levelCostWei(take, price);
+    left -= take;
+  }
+  return costWei;
+}
+
+// DIRECTION 1: "I give/take ASSET - how much XMR".
+//   buy:  assetWei - the asset the taker PAYS; the walk budget = assetWei - fee;
+//   sell: assetWei - the asset the taker RECEIVES; the walk budget = assetWei + fee (the set must yield that
+//         much so that AFTER the fee is taken out exactly assetWei is left in hand).
+export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation = "ask" }) {
+  const verdict = checkLevels(levels, orientation);
+  if (!verdict.ok) return { ok: false, reason: verdict.reason, role, index: verdict.index };
+  if (!verdict.enabled) return { ok: false, reason: "side-off", role };
+  if (role !== "buy" && role !== "sell") return { ok: false, reason: "levels-bad-role", role };
+  const asset = toBigInt(assetWei);
+  const fee = toBigInt(feeWei === undefined || feeWei === null ? 0n : feeWei);
+  if (asset === null || fee === null || fee < 0n) return { ok: false, reason: "levels-not-integer", role };
+  const budget = role === "buy" ? asset - fee : asset + fee;
+  if (budget <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
+  const { fullCostWei } = sideSummary(levels);
+  if (budget > fullCostWei) return { ok: false, reason: "levels-exceed-side", role };
+  const minCost = levelCostWei(toBigInt(levels[0].amount), toBigInt(levels[0].price));
+  if (budget < minCost) return { ok: false, reason: "levels-below-minimum", role };
+  const xmrAtomic = walkXmrForBudget(levels, budget);
+  return { ok: true, role, xmrAtomic, assetWei: asset };
+}
+
+// DIRECTION 2: "I give/want XMR - how much ASSET".
+//   buy:  xmrAtomic - how much XMR the taker WANTS; the asset to pay = the walk + fee;
+//   sell: xmrAtomic - how much XMR the taker GIVES;  the asset to receive = the walk - fee.
+export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation = "ask" }) {
+  const verdict = checkLevels(levels, orientation);
+  if (!verdict.ok) return { ok: false, reason: verdict.reason, role, index: verdict.index };
+  if (!verdict.enabled) return { ok: false, reason: "side-off", role };
+  if (role !== "buy" && role !== "sell") return { ok: false, reason: "levels-bad-role", role };
+  const want = toBigInt(xmrAtomic);
+  const fee = toBigInt(feeWei === undefined || feeWei === null ? 0n : feeWei);
+  if (want === null || fee === null || fee < 0n) return { ok: false, reason: "levels-not-integer", role };
+  if (want > verdict.totalAtomic) return { ok: false, reason: "levels-exceed-side", role };
+  if (want < verdict.minAtomic) return { ok: false, reason: "levels-below-minimum", role };
+  const walkWei = walkCostForXmr(levels, want);
+  const assetWei = role === "buy" ? walkWei + fee : walkWei - fee;
+  if (assetWei <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
+  return { ok: true, role, xmrAtomic: want, assetWei };
+}