@ninsei-labs/sdk 0.39.0 → 0.39.2

package/src/config.mjs

@@ -218,12 +218,15 @@ export function buildConfig(options) {
     if (!known.includes(id)) fail("bad-input", { field: "routing.prefer", unknown: id, known });
   }
 
-  // MONERO NETWORKS THE CORE KNOWS. The engine's registry declares only the one the demo is configured for
-  // (XMR_NETWORKS: stagenet). But the SDK contract (index.d.ts, xmrNetwork) names THREE standard names -
-  // mainnet/stagenet/testnet - and that is not about the demo: the withdrawal page takes the network FROM THE
-  // NODE, and on a production network its network is mainnet, not a typo. So three standard ones are added to
-  // the declared ones; anything else is still a refusal with the known list.
-  const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet"];
+  // MONERO NETWORKS THE CORE KNOWS. The engine's registry declares only the ones the demo is configured for
+  // (XMR_NETWORKS). But the SDK contract (index.d.ts, xmrNetwork) names the STANDARD ones - mainnet/stagenet/
+  // testnet - and that is not about the demo: the withdrawal page takes the network FROM THE NODE, and on a
+  // production network its network is mainnet, not a typo.
+  // REGTEST JOINS THEM BY ITS OFFICIAL NAME. monerod in regtest mode reports its network as `fakechain`, and the
+  // withdrawal page builds the facade from the network the node hands it - so the CI contour (a regtest node)
+  // hands out `fakechain`. Without that name the core refuses its OWN recovery file and the withdrawal never
+  // starts. This is a KNOWN name, not a wildcard: anything else is still a refusal with the known list below.
+  const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet", "fakechain"];
   const xmrNetworks = [...new Set([...Object.values(engine.config.XMR_NETWORKS || {}), ...STANDARD_XMR_NETWORKS])];
   if (!xmrNetworks.includes(options.xmrNetwork)) {
     fail("bad-input", { field: "xmrNetwork", known: xmrNetworks });

package/src/engine.mjs

@@ -1,53 +1,53 @@
-// THE ENGINE SEAM, NOW SELF-CONTAINED.
-//
-// The engine modules the core depends on are mirrored under sdk/engine/ - byte-for-byte copies kept in
-// sync by tools/build-sdk-engine.mjs and guarded by tools/check-sdk-engine.mjs. This file is the ONLY
-// place that knows where the engine lives; no other SDK module does.
-//
-// WHY A VERIFIED MIRROR, NOT A MOVE. The very same modules are loaded by the demo page in the browser
-// (www/js), and the production web root is www/ alone - the sdk/ directory is not served there (see
-// tools/serve.mjs). Lifting the files out of www/js would 404 every engine import on the live site, and
-// dozens of repository checks read those sources by their www/js path. So the single source of truth
-// stays www/js and the SDK carries a copy: any drift reddens check-sdk-engine, so it cannot diverge
-// silently (the same rule build-sweep uses for the sweep/rfq copies).
-//
-// The mirror is generated - never edit sdk/engine/ by hand. Change www/js, then run:
-//   node tools/build-sdk-engine.mjs
-export * as config from "../engine/core/config.js";
-export * as guards from "../engine/core/preSignGuards.js";
-export * as restore from "../engine/recovery/restore.js";
-// STORES - THROUGH THIS SAME SEAM. Both modules take an adapter from outside (get/set/remove), and by default
-// use web storage if it is present: without an adapter they run in memory rather than fail on a missing DOM.
-export * as store from "../engine/core/store.js";
-export * as auth from "../engine/evm/auth.js";
-export * as swap from "../engine/core/swap.js";
-export * as recoveryFile from "../engine/recovery/recoveryFile.js";
-export * as halves from "../engine/atomic/halves.js";
-export * as orderContext from "../engine/atomic/orderContext.js";
-export * as order from "../engine/atomic/order.js";
-// HALF TRANSFER: the byte format and opening are the very same ones the page worker uses
-// (www/js/atomic/order-worker.js). The core keeps no copy of the format: the commitment is computed over those
-// exact bytes, and a second copy would silently drift from the calldata.
-export * as halfenc from "../engine/atomic/halfenc.js";
-// The engine's EVM layer: talking to the chain (order terms, sending, reading) - through this seam.
-export * as evm from "../engine/evm/index.js";
-// THE DEAL ENGINE NO LONGER LIVES IN www/js (#32, wave 3): the order flow moved into the package
-// (sdk/src/swap-flow.mjs) and is declared in sdk/index.d.ts. The page reaches it through the bridge, so the
-// mirror no longer carries core/swap-flow.js - what stays in the seam is the ORDER CLIENT (the half worker),
-// the ORDER QUOTE source and the shared CLAIM GAS LIMIT that the moved flow reads through this same seam.
-export * as orderClient from "../engine/atomic/order-client.js";
-export * as rfqSource from "../engine/core/rfqSource.js";
-export * as claimGas from "../engine/evm/claimGas.js";
-export * as escrow from "../engine/evm/escrow.js";
-export * as halvesSweep from "../engine/monero/halvesSweep.js";
-// MONERO ADDRESSES - THROUGH THE SAME MODULE THE DEMO USES. The format, the network prefixes and the address
-// check live in www/js/monero/address.js (checkAddress: base58 + keccak256 + network), and the page uses it
-// too. The wallet adapter needs exactly networkFromShape: its own address must belong to the network named by
-// the core, and that is checked by the same code, not by a private prefix table.
-export * as xmrAddress from "../engine/monero/address.js";
-// THE unlock_time RULE AND THE BLOCK READER - FROM THE SAME MIRROR, NOT A COPY. A second copy of "the output
-// is barred until a boundary" would be a second truth about money, so the rule lives under www/js
-// (monero/unlock.js) together with the Monero block parser (monero/scan.js), and the SDK reads them through
-// the engine mirror. check-sdk-engine reddens on any drift, so the two cannot diverge silently.
-export * as xmrUnlock from "../engine/monero/unlock.js";
-export * as xmrScan from "../engine/monero/scan.js";
+// THE ENGINE SEAM, NOW SELF-CONTAINED.
+//
+// The engine modules the core depends on are mirrored under sdk/engine/ - byte-for-byte copies kept in
+// sync by tools/build-sdk-engine.mjs and guarded by tools/check-sdk-engine.mjs. This file is the ONLY
+// place that knows where the engine lives; no other SDK module does.
+//
+// WHY A VERIFIED MIRROR, NOT A MOVE. The very same modules are loaded by the demo page in the browser
+// (www/js), and the production web root is www/ alone - the sdk/ directory is not served there (see
+// tools/serve.mjs). Lifting the files out of www/js would 404 every engine import on the live site, and
+// dozens of repository checks read those sources by their www/js path. So the single source of truth
+// stays www/js and the SDK carries a copy: any drift reddens check-sdk-engine, so it cannot diverge
+// silently (the same rule build-sweep uses for the sweep/rfq copies).
+//
+// The mirror is generated - never edit sdk/engine/ by hand. Change www/js, then run:
+//   node tools/build-sdk-engine.mjs
+export * as config from "../engine/core/config.js";
+export * as guards from "../engine/core/preSignGuards.js";
+export * as restore from "../engine/recovery/restore.js";
+// STORES - THROUGH THIS SAME SEAM. Both modules take an adapter from outside (get/set/remove), and by default
+// use web storage if it is present: without an adapter they run in memory rather than fail on a missing DOM.
+export * as store from "../engine/core/store.js";
+export * as auth from "../engine/evm/auth.js";
+export * as swap from "../engine/core/swap.js";
+export * as recoveryFile from "../engine/recovery/recoveryFile.js";
+export * as halves from "../engine/atomic/halves.js";
+export * as orderContext from "../engine/atomic/orderContext.js";
+export * as order from "../engine/atomic/order.js";
+// HALF TRANSFER: the byte format and opening are the very same ones the page worker uses
+// (www/js/atomic/order-worker.js). The core keeps no copy of the format: the commitment is computed over those
+// exact bytes, and a second copy would silently drift from the calldata.
+export * as halfenc from "../engine/atomic/halfenc.js";
+// The engine's EVM layer: talking to the chain (order terms, sending, reading) - through this seam.
+export * as evm from "../engine/evm/index.js";
+// THE DEAL ENGINE NO LONGER LIVES IN www/js (#32, wave 3): the order flow moved into the package
+// (sdk/src/swap-flow.mjs) and is declared in sdk/index.d.ts. The page reaches it through the bridge, so the
+// mirror no longer carries core/swap-flow.js - what stays in the seam is the ORDER CLIENT (the half worker),
+// the ORDER QUOTE source and the shared CLAIM GAS LIMIT that the moved flow reads through this same seam.
+export * as orderClient from "../engine/atomic/order-client.js";
+export * as rfqSource from "../engine/core/rfqSource.js";
+export * as claimGas from "../engine/evm/claimGas.js";
+export * as escrow from "../engine/evm/escrow.js";
+export * as halvesSweep from "../engine/monero/halvesSweep.js";
+// MONERO ADDRESSES - THROUGH THE SAME MODULE THE DEMO USES. The format, the network prefixes and the address
+// check live in www/js/monero/address.js (checkAddress: base58 + keccak256 + network), and the page uses it
+// too. The wallet adapter needs exactly networkFromShape: its own address must belong to the network named by
+// the core, and that is checked by the same code, not by a private prefix table.
+export * as xmrAddress from "../engine/monero/address.js";
+// THE unlock_time RULE AND THE BLOCK READER - FROM THE SAME MIRROR, NOT A COPY. A second copy of "the output
+// is barred until a boundary" would be a second truth about money, so the rule lives under www/js
+// (monero/unlock.js) together with the Monero block parser (monero/scan.js), and the SDK reads them through
+// the engine mirror. check-sdk-engine reddens on any drift, so the two cannot diverge silently.
+export * as xmrUnlock from "../engine/monero/unlock.js";
+export * as xmrScan from "../engine/monero/scan.js";

package/src/index.mjs

@@ -97,6 +97,14 @@ const normalizeOptions = (options) => {
   if (o.knownFactoryCodes !== undefined && o.knownFactoryCodes !== null && !Array.isArray(o.knownFactoryCodes)) {
     fail("bad-input", { field: "knownFactoryCodes" });
   }
+  // THE INTERFACE'S ESCROW-IMPLEMENTATION POLICY (issue #114): an array of code hashes of known implementations
+  // of the escrow - the code every order's clone delegatecalls. The client checks the pair (implementation,
+  // implementationCodeHash) the factory carries, exactly as the factory does at creation; this list pins WHICH
+  // builds the interface accepts. Same rule as knownFactoryCodes: a POLICY list, empty/absent means "no policy"
+  // (then the pair is still read and the code at the implementation's address must be non-empty).
+  if (o.knownImplementationCodes !== undefined && o.knownImplementationCodes !== null && !Array.isArray(o.knownImplementationCodes)) {
+    fail("bad-input", { field: "knownImplementationCodes" });
+  }
   // 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
@@ -137,6 +145,7 @@ const normalizeOptions = (options) => {
     evmCode: o.evmCode || null,
     allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
     knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
+    knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
     serverAuth: o.serverAuth || null,
     watch: o.watch || null,
     createRecord: o.createRecord || null,
@@ -186,7 +195,7 @@ export function createNinsei(options) {
     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 });
+    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes });
   // 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 });

package/src/levelsWalkSpec.mjs

@@ -141,11 +141,22 @@ function walkCostForXmr(levels, xmrAtomic) {
   return costWei;
 }
 
+// THE SMALLEST TRADE (rule 3). It is the size of the FIRST level the maker SENT, and the node's own
+// deductions (outstanding quotes, a balance cut) never change it: they take depth off the TOP, and a trade
+// that was allowed when the set arrived must stay allowed after the top was eaten. If the minimum were read
+// off the EFFECTIVE set, eating the first level whole would RAISE it to the next, larger level, and eating it
+// in part would LOWER it below what the maker sent - both wrong. Callers pass the sent minimum as minAtomic;
+// absent, the set's own first level is the minimum (the historical behaviour and what the vectors pin).
+function minOf(levels, minAtomic) {
+  if (minAtomic === null || minAtomic === undefined) return toBigInt(levels[0].amount);
+  return toBigInt(minAtomic);
+}
+
 // 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" }) {
+export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation = "ask", minAtomic = null }) {
   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 };
@@ -157,7 +168,12 @@ export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation =
   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));
+  // THE SMALLEST TRADE, from the set AS THE MAKER SENT IT (rule 3): callers pass it in minAtomic and the
+  // node's deductions never change it. Absent, the set's own first level is used, as it always was.
+  const min = minOf(levels, minAtomic);
+  // Its cost ON THE EFFECTIVE SET: after deductions the smallest trade may reach into a later level, so the
+  // cost is walked, not read off one price.
+  const minCost = walkCostForXmr(levels, min);
   if (budget < minCost) return { ok: false, reason: "levels-below-minimum", role };
   const xmrAtomic = walkXmrForBudget(levels, budget);
   return { ok: true, role, xmrAtomic, assetWei: asset };
@@ -166,7 +182,7 @@ export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation =
 // 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" }) {
+export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation = "ask", minAtomic = null }) {
   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 };
@@ -175,7 +191,8 @@ export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation
   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 };
+  // THE SMALLEST TRADE AS THE MAKER SENT IT, never the effective set's first level (rule 3): see minOf.
+  if (want < minOf(levels, 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 };

package/src/lock.mjs

@@ -1,140 +1,140 @@
-// LOCKING THE FUNDS: TERMS FIRST, THEN SENDING.
-//
-// The first half of the step is here - assembling and CHECKING the order terms BEFORE anything goes on-chain. The
-// rules are not ours: the contract sets them, and the engine already checks them (`www/js/evm/escrow.js`,
-// `orderTerms`). The core will not hold a copy of the rules: a copy would drift from the contract right where the
-// error shows up only as a rejected transaction.
-//
-// WHAT IS HERE: both the assembly of the terms and the sending itself - it goes through the engine's EVM layer
-// (`fundOrder`), and the EVM wallet (the `send`/`receipt` role) comes from outside. What reads the chain is also a
-// seam: by default the engine's read, but the caller can substitute its own (as in actions.mjs).
-import { SdkError } from "./errors.mjs";
-import * as engine from "./engine.mjs";
-// THE DEAL FLOW IS A PACKAGE MODULE NOW (#32, wave 3): the registry address is read through it, exactly as
-// the actions read the order flow.
-import * as flow from "./swap-flow.mjs";
-
-// THE ORDER'S WORD-ADDRESSES ARE BROUGHT TO 0x HERE, AT THE BOUNDARY, NOT AT EVERY CALLER.
-//
-// The engine returns the points and commitments WITHOUT the 0x prefix (that is how www/js/atomic/halves.js stores
-// them), while the calldata encoder (www/js/evm/factory.js, word) REQUIRES the prefix and refuses "not a number
-// and not hex" on 64 digits without one. The page normalises them on its side (sdk/src/swap-flow.mjs, with0x)
-// for exactly this reason. The core must do the same ITSELF: otherwise every caller would repeat the
-// normalisation, and one forgetful one would break the signature with the encoder's raw error. The list is
-// exactly the fields encoded as bytes32 that do NOT enter the order context string (otherwise the normalisation
-// would drift from the proof, which is bound to the context): two half commitments and three ed25519 points.
-const HEX_POLICY_FIELDS = ["commitHalfLocker", "commitHalfClaimer", "edPointLocker", "edPointClaimer", "edViewPointLocker"];
-const with0x = (v) => (typeof v === "string" && v && !/^0x/i.test(v) ? "0x" + v : v);
-
-/**
- * The order terms in canonical form: points and commitments - with the 0x prefix. One form for the check and for
- * sending - otherwise one thing would be checked and another encoded.
- */
-export function canonicalTerms(request) {
-  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
-  const out = { ...request };
-  for (const key of HEX_POLICY_FIELDS) out[key] = with0x(out[key]);
-  return out;
-}
-
-/**
- * The order terms for the contract. They are assembled by the engine, and its refusal (the deadlines the wrong
- * way, readyBy in the past) is turned into a CODE: texts are the interface's business, the core speaks in codes.
- */
-export function terms(request) {
-  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
-  const need = ["locker", "claimer", "commitHalfLocker", "commitHalfClaimer", "edPointLocker", "edPointClaimer", "amount", "readyBy", "t1"];
-  const missing = need.filter((k) => request[k] === undefined || request[k] === null || request[k] === "");
-  if (missing.length) throw new SdkError("bad-input", { field: "terms", missing });
-  try {
-    return engine.escrow.orderTerms(canonicalTerms(request));
-  } catch (error) {
-    // We will not parse ANOTHER's text: we name what the contract's rules check, and only if the deadlines are
-    // actually violated. Otherwise - a general refusal on the terms.
-    const seconds = Math.floor(Date.now() / 1000);
-    if (Number(request.readyBy) <= seconds) throw new SdkError("bad-input", { field: "readyBy", why: "not-in-future" });
-    if (Number(request.t1) <= Number(request.readyBy)) throw new SdkError("bad-input", { field: "t1", why: "not-after-readyBy" });
-    throw new SdkError("bad-input", { field: "terms" });
-  }
-}
-
-// SANITISING THE REASON. The engine's messages carry no keys, but sanitising costs one line and covers the case
-// where the engine starts printing a value: 0x + 64 hex is a private key, and it never goes out.
-const sanitizeWhy = (value) =>
-  String(value === undefined || value === null ? "" : value).replace(/0x[0-9a-fA-F]{64}/g, "0x<redacted>").slice(0, 200);
-// A NETWORK REFUSAL IS CALLED A NETWORK ONE, rather than being fitted to a data error: transport and order
-// validation are different things, and the caller needs an answer to "retry or fix".
-const TRANSPORT_WHY = /fetch failed|network|ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket|timeout|HTTP \d|status \d|non-ok/i;
-const transportish = (why) => TRANSPORT_WHY.test(why);
-
-/**
- * SEND THE LOCK. The deadlines and the composition are checked BEFORE sending (see `terms`), the chain work is
- * done by the engine (`fundOrder`), and the wallet arrives as an adapter: signing is possible only in it, and the
- * core keeps no path into the chain of its own.
- *
- * TWO THINGS ARE DELIBERATELY NOT OURS: reading from the chain is taken from the engine, and the escrow address -
- * FROM THE RECEIPT, not from a prediction. A prediction could diverge from what was actually created, and it
- * would diverge silently.
- */
-export async function send(request, wallet, deps = {}) {
-  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
-  if (!wallet || typeof wallet.send !== "function" || typeof wallet.receipt !== "function") {
-    throw new SdkError("bad-input", { field: "wallet", missing: ["send", "receipt"] });
-  }
-  // THE TERMS ARE BROUGHT TO CANONICAL FORM BEFORE EVERYTHING, and go in one form both into the check and into
-  // sending.
-  // THE DEADLINES - HERE, BEFORE ANY SENDING, and on the form funding expects (`amountWei`, not `amount`: the
-  // order terms and the sending have different names for the same field, and they must not be confused).
-  const canonical = canonicalTerms(request);
-  terms({ ...canonical, amount: canonical.amountWei });
-  const evm = engine.evm;
-  // WHAT READS THE CHAIN IS ALSO A SEAM (as in actions.mjs): by default it is the engine's read, but the caller
-  // can substitute its own. Without this capability the lock step could not be checked beyond predicting the
-  // address - and then "the address from the receipt" would remain an argument on trust, not a verified property.
-  const reader = typeof deps.call === "function" ? deps.call : evm.readContract;
-  try {
-    return await evm.fundOrder({
-      ...canonical,
-      call: reader,
-      send: (tx) => wallet.send(tx),
-      // NORMALISING THE RECEIPT ARGUMENT'S SHAPE - HERE, AT THE CORE'S BOUNDARY, NOT AT EVERY CALLER.
-      //
-      // www/js/evm/funding.js calls the receipt with an OBJECT { hash } (waitReceipt), while the adapter contract
-      // declares receipt(txHash: string). A strict adapter (sdk/src/adapters/evm-wallet.mjs) answers bad-input to
-      // an object, the refusal is SWALLOWED by the receipt 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. We
-      // normalise the argument to a string here: funding.js is foreign code and must not be edited, and every
-      // adapter should not repeat the normalisation.
-      receipt: (arg) => wallet.receipt(typeof arg === "string" ? arg : (arg && typeof arg.hash === "string" ? arg.hash : arg)),
-    });
-  } catch (error) {
-    // AN ALREADY-NAMED REASON PASSES AS IS: the adapter's and the reader's codes (wrong-chain, server-unavailable,
-    // contract-reverted, bad-input) ARE the answer, and it must not be overridden.
-    if (error && typeof error.code === "string") throw error;
-    // THE REST USED TO HIDE BEHIND server-unavailable { step: "fund-order" }, and the real reason (the first live
-    // run: "locker and claimer cannot coincide") never reached the caller. Now the reason is NAMED as a string
-    // (briefly, without keys), and the code is chosen by it: transport - server-unavailable, order/data
-    // validation - bad-input.
-    const why = sanitizeWhy((error && error.message) || error);
-    throw new SdkError(transportish(why) ? "server-unavailable" : "bad-input", { step: "fund-order", why });
-  }
-}
-
-/**
- * The escrow factory address for a network: FROM THE NETWORK REGISTRY, by the same path as the rest of the core.
- * The registry is read through the deal-flow module (sdk/src/swap-flow.mjs, escrowFactoryAddress) - the core
- * keeps no SECOND table of addresses.
- *
- * PREVIOUSLY THE FUNCTION LOOKED IN THE WRONG MODULE (www/js/evm/escrow.js, which has no such function) and
- * ALWAYS returned null - that is, the seam stayed silent about the factory's absence, and the caller took the
- * address elsewhere. Now the absence of a factory for a network is a REFUSAL WITH A CODE naming the network, not
- * null.
- */
-export function factoryOf(chainSlug) {
-  let address = null;
-  try { address = flow.escrowFactoryAddress(chainSlug); } catch { address = null; }
-  if (typeof address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(address)) {
-    throw new SdkError("bad-input", { field: "factory", chain: typeof chainSlug === "string" ? chainSlug : null });
-  }
-  return address;
-}
+// LOCKING THE FUNDS: TERMS FIRST, THEN SENDING.
+//
+// The first half of the step is here - assembling and CHECKING the order terms BEFORE anything goes on-chain. The
+// rules are not ours: the contract sets them, and the engine already checks them (`www/js/evm/escrow.js`,
+// `orderTerms`). The core will not hold a copy of the rules: a copy would drift from the contract right where the
+// error shows up only as a rejected transaction.
+//
+// WHAT IS HERE: both the assembly of the terms and the sending itself - it goes through the engine's EVM layer
+// (`fundOrder`), and the EVM wallet (the `send`/`receipt` role) comes from outside. What reads the chain is also a
+// seam: by default the engine's read, but the caller can substitute its own (as in actions.mjs).
+import { SdkError } from "./errors.mjs";
+import * as engine from "./engine.mjs";
+// THE DEAL FLOW IS A PACKAGE MODULE NOW (#32, wave 3): the registry address is read through it, exactly as
+// the actions read the order flow.
+import * as flow from "./swap-flow.mjs";
+
+// THE ORDER'S WORD-ADDRESSES ARE BROUGHT TO 0x HERE, AT THE BOUNDARY, NOT AT EVERY CALLER.
+//
+// The engine returns the points and commitments WITHOUT the 0x prefix (that is how www/js/atomic/halves.js stores
+// them), while the calldata encoder (www/js/evm/factory.js, word) REQUIRES the prefix and refuses "not a number
+// and not hex" on 64 digits without one. The page normalises them on its side (sdk/src/swap-flow.mjs, with0x)
+// for exactly this reason. The core must do the same ITSELF: otherwise every caller would repeat the
+// normalisation, and one forgetful one would break the signature with the encoder's raw error. The list is
+// exactly the fields encoded as bytes32 that do NOT enter the order context string (otherwise the normalisation
+// would drift from the proof, which is bound to the context): two half commitments and three ed25519 points.
+const HEX_POLICY_FIELDS = ["commitHalfLocker", "commitHalfClaimer", "edPointLocker", "edPointClaimer", "edViewPointLocker"];
+const with0x = (v) => (typeof v === "string" && v && !/^0x/i.test(v) ? "0x" + v : v);
+
+/**
+ * The order terms in canonical form: points and commitments - with the 0x prefix. One form for the check and for
+ * sending - otherwise one thing would be checked and another encoded.
+ */
+export function canonicalTerms(request) {
+  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+  const out = { ...request };
+  for (const key of HEX_POLICY_FIELDS) out[key] = with0x(out[key]);
+  return out;
+}
+
+/**
+ * The order terms for the contract. They are assembled by the engine, and its refusal (the deadlines the wrong
+ * way, readyBy in the past) is turned into a CODE: texts are the interface's business, the core speaks in codes.
+ */
+export function terms(request) {
+  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+  const need = ["locker", "claimer", "commitHalfLocker", "commitHalfClaimer", "edPointLocker", "edPointClaimer", "amount", "readyBy", "t1"];
+  const missing = need.filter((k) => request[k] === undefined || request[k] === null || request[k] === "");
+  if (missing.length) throw new SdkError("bad-input", { field: "terms", missing });
+  try {
+    return engine.escrow.orderTerms(canonicalTerms(request));
+  } catch (error) {
+    // We will not parse ANOTHER's text: we name what the contract's rules check, and only if the deadlines are
+    // actually violated. Otherwise - a general refusal on the terms.
+    const seconds = Math.floor(Date.now() / 1000);
+    if (Number(request.readyBy) <= seconds) throw new SdkError("bad-input", { field: "readyBy", why: "not-in-future" });
+    if (Number(request.t1) <= Number(request.readyBy)) throw new SdkError("bad-input", { field: "t1", why: "not-after-readyBy" });
+    throw new SdkError("bad-input", { field: "terms" });
+  }
+}
+
+// SANITISING THE REASON. The engine's messages carry no keys, but sanitising costs one line and covers the case
+// where the engine starts printing a value: 0x + 64 hex is a private key, and it never goes out.
+const sanitizeWhy = (value) =>
+  String(value === undefined || value === null ? "" : value).replace(/0x[0-9a-fA-F]{64}/g, "0x<redacted>").slice(0, 200);
+// A NETWORK REFUSAL IS CALLED A NETWORK ONE, rather than being fitted to a data error: transport and order
+// validation are different things, and the caller needs an answer to "retry or fix".
+const TRANSPORT_WHY = /fetch failed|network|ECONN|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket|timeout|HTTP \d|status \d|non-ok/i;
+const transportish = (why) => TRANSPORT_WHY.test(why);
+
+/**
+ * SEND THE LOCK. The deadlines and the composition are checked BEFORE sending (see `terms`), the chain work is
+ * done by the engine (`fundOrder`), and the wallet arrives as an adapter: signing is possible only in it, and the
+ * core keeps no path into the chain of its own.
+ *
+ * TWO THINGS ARE DELIBERATELY NOT OURS: reading from the chain is taken from the engine, and the escrow address -
+ * FROM THE RECEIPT, not from a prediction. A prediction could diverge from what was actually created, and it
+ * would diverge silently.
+ */
+export async function send(request, wallet, deps = {}) {
+  if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+  if (!wallet || typeof wallet.send !== "function" || typeof wallet.receipt !== "function") {
+    throw new SdkError("bad-input", { field: "wallet", missing: ["send", "receipt"] });
+  }
+  // THE TERMS ARE BROUGHT TO CANONICAL FORM BEFORE EVERYTHING, and go in one form both into the check and into
+  // sending.
+  // THE DEADLINES - HERE, BEFORE ANY SENDING, and on the form funding expects (`amountWei`, not `amount`: the
+  // order terms and the sending have different names for the same field, and they must not be confused).
+  const canonical = canonicalTerms(request);
+  terms({ ...canonical, amount: canonical.amountWei });
+  const evm = engine.evm;
+  // WHAT READS THE CHAIN IS ALSO A SEAM (as in actions.mjs): by default it is the engine's read, but the caller
+  // can substitute its own. Without this capability the lock step could not be checked beyond predicting the
+  // address - and then "the address from the receipt" would remain an argument on trust, not a verified property.
+  const reader = typeof deps.call === "function" ? deps.call : evm.readContract;
+  try {
+    return await evm.fundOrder({
+      ...canonical,
+      call: reader,
+      send: (tx) => wallet.send(tx),
+      // NORMALISING THE RECEIPT ARGUMENT'S SHAPE - HERE, AT THE CORE'S BOUNDARY, NOT AT EVERY CALLER.
+      //
+      // www/js/evm/funding.js calls the receipt with an OBJECT { hash } (waitReceipt), while the adapter contract
+      // declares receipt(txHash: string). A strict adapter (sdk/src/adapters/evm-wallet.mjs) answers bad-input to
+      // an object, the refusal is SWALLOWED by the receipt 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. We
+      // normalise the argument to a string here: funding.js is foreign code and must not be edited, and every
+      // adapter should not repeat the normalisation.
+      receipt: (arg) => wallet.receipt(typeof arg === "string" ? arg : (arg && typeof arg.hash === "string" ? arg.hash : arg)),
+    });
+  } catch (error) {
+    // AN ALREADY-NAMED REASON PASSES AS IS: the adapter's and the reader's codes (wrong-chain, server-unavailable,
+    // contract-reverted, bad-input) ARE the answer, and it must not be overridden.
+    if (error && typeof error.code === "string") throw error;
+    // THE REST USED TO HIDE BEHIND server-unavailable { step: "fund-order" }, and the real reason (the first live
+    // run: "locker and claimer cannot coincide") never reached the caller. Now the reason is NAMED as a string
+    // (briefly, without keys), and the code is chosen by it: transport - server-unavailable, order/data
+    // validation - bad-input.
+    const why = sanitizeWhy((error && error.message) || error);
+    throw new SdkError(transportish(why) ? "server-unavailable" : "bad-input", { step: "fund-order", why });
+  }
+}
+
+/**
+ * The escrow factory address for a network: FROM THE NETWORK REGISTRY, by the same path as the rest of the core.
+ * The registry is read through the deal-flow module (sdk/src/swap-flow.mjs, escrowFactoryAddress) - the core
+ * keeps no SECOND table of addresses.
+ *
+ * PREVIOUSLY THE FUNCTION LOOKED IN THE WRONG MODULE (www/js/evm/escrow.js, which has no such function) and
+ * ALWAYS returned null - that is, the seam stayed silent about the factory's absence, and the caller took the
+ * address elsewhere. Now the absence of a factory for a network is a REFUSAL WITH A CODE naming the network, not
+ * null.
+ */
+export function factoryOf(chainSlug) {
+  let address = null;
+  try { address = flow.escrowFactoryAddress(chainSlug); } catch { address = null; }
+  if (typeof address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    throw new SdkError("bad-input", { field: "factory", chain: typeof chainSlug === "string" ? chainSlug : null });
+  }
+  return address;
+}