@ninsei-labs/sdk 0.39.0

package/src/lock.mjs

@@ -0,0 +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;
+}

package/src/order.mjs

@@ -0,0 +1,212 @@
+// THE COUNTERPARTY'S SIDE AND THE JOINT ADDRESS.
+//
+// TWO CHECKS, BOTH MANDATORY BEFORE SIGNING - after it there is nothing to fix:
+//
+//   1) the DLEQ proof stands in the CONTEXT OF THIS order: the counterparty proved for our terms, not for others.
+//      The context is the same one the quote signature is bound to (see quotes.firm);
+//   2) the proven ed25519 point is THE VERY ONE that will go into the contract and from which the address is
+//      assembled. Without this check the counterparty could prove one thing and substitute another: on our side
+//      everything would look sound, and the discrepancy would surface when claiming the XMR, with nothing left to
+//      fix.
+//
+// Both are done by the engine (order.js: the verifying code is the same for us and for the counterparty). The
+// core has no cryptography of its own and should not: a copy would silently drift from the original.
+import { SdkError } from "./errors.mjs";
+import { primitives } from "./primitives.mjs";
+import * as engine from "./engine.mjs";
+
+const builder = () => engine.order.createOrderBuilder(primitives);
+
+/** The order context: the string the proof and the quote signature are both bound to. */
+export function contextOf(order) {
+  if (!order || typeof order !== "object") throw new SdkError("bad-input", { field: "order" });
+  try { return engine.orderContext.orderContextString(order); }
+  catch { throw new SdkError("bad-input", { field: "order" }); }
+}
+
+/**
+ * Check the counterparty's side in the order context. It passed - return the side itself; it did not - a refusal
+ * with a CODE (`quote-refused { step: "proof" }`). "Probably fine" does not exist here: the side is either proven
+ * or it is not.
+ */
+export function verifyCounterparty({ side, order, sealed = null, ownEncPriv = null }) {
+  if (!side || typeof side !== "object") throw new SdkError("bad-input", { field: "side" });
+  const context = contextOf(order);
+  let verdict = null;
+  try { verdict = builder().verifySide(side, context, sealed, ownEncPriv); }
+  catch { throw new SdkError("bad-input", { field: "side" }); }
+  if (!verdict || verdict.ok !== true) {
+    throw new SdkError("quote-refused", { step: "proof", why: verdict && verdict.reason ? "rejected" : "unknown" });
+  }
+  return side;
+}
+
+/**
+ * The shared Monero address: your own spend half and the other's POINT (the same for the view key). We take the
+ * same encoder the wallet uses: a second one would drift from the first where the error is visible only by
+ * sending XMR.
+ */
+export function jointAddress({ ownSpendHalf, ownViewHalf, otherSpendPoint, otherViewPoint, network }) {
+  const need = { ownSpendHalf, ownViewHalf, otherSpendPoint, otherViewPoint };
+  const missing = Object.keys(need).filter((k) => need[k] === undefined || need[k] === null || need[k] === "");
+  if (missing.length) throw new SdkError("bad-input", { field: "jointAddress", missing });
+  try {
+    return builder().jointAddress({ ownSpendHalf, ownViewHalf, otherSpendPoint, otherViewPoint, network });
+  } catch { throw new SdkError("bad-input", { field: "jointAddress" }); }
+}
+
+// --- THE ORDER STEP: FROM OUR SIDE TO THE JOINT ADDRESS -----------------------------------------
+//
+// WHY THIS IS A SINGLE CALL AND NOT THREE SEPARATE ONES. The order here IS the rule: your own side -> the
+// counterparty's side (accepted and verified in THIS SAME context) -> the joint address. The address is assembled
+// from YOUR half and the OTHER's point, so before the counterparty's side appears it simply does not exist - and
+// refusing here is cheaper than discovering the discrepancy when claiming the XMR, with nothing left to fix.
+//
+// THERE IS NOT A SINGLE FORMULA OF OUR OWN HERE. The halves, the points, the DLEQ proof, the encryption key and
+// the address are computed by the engine's builder (www/js/atomic/order.js) on the core's primitives. The core
+// names the order and translates the result into the record's fields - exactly the names the engine reads
+// (core/swap.js, halvesWalletOf).
+
+export const norm = (h) => "0x" + String(h).replace(/^0x/i, "").toLowerCase();
+// A HALF AT THE BOUNDARY IS A HEX STRING: a BigInt survives neither storage nor the recovery file
+// (www/js/recovery/recoveryFile.js, bigintSafe). One form at every boundary, otherwise JSON silently loses the key.
+export const halfHex = (v) => "0x" + BigInt(v).toString(16).padStart(64, "0");
+const isPoint = (h) => /^0x[0-9a-f]{64}$/.test(String(h));
+// THE PROVEN POINT AND THE POINT IN THE ORDER MUST BE WRITTEN IDENTICALLY. The engine compares them AS STRINGS
+// (order.js, verifySide), so the record's form is part of the check, not cosmetics: without bringing both to one
+// form, a correct proof would look like a discrepancy. The page does the same
+// (sdk/src/swap-flow.mjs: it normalises both proof.XB and the point). One normalisation for both sides.
+const sameFormAsPoint = (proof) => (proof && typeof proof === "object" && proof.XB ? { ...proof, XB: norm(proof.XB) } : proof);
+// A POINT AT THE BOUNDARY IS IN CANONICAL FORM (0x + lowercase). The engine's points arrive WITHOUT the 0x prefix
+// (that is how www/js/atomic/halves.js stores them), while the proof check compares points AS STRINGS. The
+// normalisation must be SYMMETRIC: the proven point of the proof is already normalised by sameFormAsPoint, so the
+// counterparty's declared point is normalised the same way - otherwise the same number written once with 0x and
+// once without would give a false quote-refused { step: "proof" } on a matching proof. The page does the same
+// (sdk/src/swap-flow.mjs, with0x). Not a string - then there is no point: we leave it as is, this is a refusal
+// "no point", not "point in another form".
+const pointForm = (v) => (typeof v === "string" && v ? norm(v) : v);
+
+/**
+ * Our side of the order. It is built by the engine's builder: two halves, their points, the DLEQ PROOF (it is
+ * bound to the order terms and so is not computed without the context) and the side's encryption key.
+ * The long proof computation lives here - one side, one computation.
+ */
+export function buildOwnSide(order, onBit) {
+  const context = contextOf(order);
+  const side = builder().newSide(context, false, onBit);
+  return { context, side, spendPoint: norm(side.pub.ed), viewPoint: norm(side.viewPub), encPub: norm(side.enc.pub) };
+}
+
+/**
+ * The counterparty's side: accept and verify. The check is ONE for both sides and is done by the engine
+ * (order.js, verifySide): the proof stands in the CONTEXT OF THIS order, the proven point matches the one that
+ * will go into the contract, and if a sealed package arrived it is opened with OUR encryption key and checked
+ * against its point. The sandbox stand-in is built here too and marked: it must not be passed off as a real
+ * provider.
+ */
+export function acceptCounterparty({ context, side = null, counterparty = null, standIn = false }) {
+  let accepted = null;
+  if (counterparty && typeof counterparty === "object") {
+    const pub = counterparty.pub && typeof counterparty.pub === "object" ? counterparty.pub : {};
+    // THE ORDER-QUOTE FIELD NAMES ARE THE ONES THE CORE ITSELF RETURNS (a defect found). The counterparty's side
+    // comes from `quotes.firm`, and there the point is called `edPointClaimer`, the view half - `viewHalfClaimer`
+    // (rfq/orderQuote.mjs). While only `edPub`/`viewPub` were accepted, the facade's own side was NOT accepted:
+    // start answered bad-input { field: "counterparty", missing: ["edPub"] } to its own answer. The engine knew
+    // this mapping (sdk/src/swap-flow.mjs: edPub: quote.edPointClaimer). We accept BOTH names.
+    accepted = {
+      proof: sameFormAsPoint(counterparty.proof),
+      edPub: pointForm(counterparty.edPub || counterparty.edPoint || counterparty.edPointClaimer || pub.ed || null),
+      viewPoint: pointForm(counterparty.viewPoint || counterparty.viewPub || null),
+      viewHalf: counterparty.viewHalf || counterparty.viewHalfClaimer || null,
+      // THE COUNTERPARTY'S SPEND HALF: HIS commitment (commitHalfClaimer) is computed from it where it did not
+      // arrive ready-made. Without the half the commitment cannot be obtained - and that is named null, not invented.
+      half: counterparty.half !== undefined ? counterparty.half : null,
+      commitHalfClaimer: counterparty.commitHalfClaimer || null,
+      sealed: counterparty.sealed || null,
+      providerId: counterparty.providerId || null,
+      standIn: false,
+    };
+  } else if (standIn === true) {
+    // THE STAND-IN IS COMPUTED IN THE SAME CONTEXT AS THE ORDER: the string gets nothing appended. The same path
+    // as the page (sdk/src/swap-flow.mjs: worker.buildSide) and the flow check - otherwise what would be checked is
+    // not what the page runs on.
+    const mock = builder().newSide(context, true);
+    accepted = { proof: sameFormAsPoint(mock.proof), edPub: norm(mock.pub.ed), viewPoint: norm(mock.viewPub),
+      viewHalf: mock.viewHalf, half: mock.half, commitHalfClaimer: null, sealed: null, providerId: null, standIn: true, mock };
+  } else {
+    throw new SdkError("bad-input", { field: "counterparty" });
+  }
+  const missing = [];
+  if (!accepted.proof) missing.push("proof");
+  if (!accepted.edPub) missing.push("edPub");
+  if (missing.length) throw new SdkError("bad-input", { field: "counterparty", missing });
+  // OPENING THE SEALED PACKAGE - BY THE SAME ENGINE CALL, and the key is OURS (the package is addressed to us).
+  // The envelope's composition is locked separately (www/js/atomic/halfenc.js, HALFENC_LOCK_REASON): in the live
+  // flow the half arrives from the chain via the commit/reveal mechanism, so a locked package honestly answers
+  // with a refusal rather than passing itself off as a working key handover.
+  const ownEncPriv = accepted.sealed && side && side.enc ? side.enc.priv : null;
+  let verdict = null;
+  try { verdict = builder().verifySide({ proof: accepted.proof, pub: { ed: accepted.edPub } }, context, accepted.sealed, ownEncPriv); }
+  catch { throw new SdkError("bad-input", { field: "counterparty" }); }
+  if (!verdict || verdict.ok !== true) {
+    throw new SdkError("quote-refused", { step: "proof", why: verdict && verdict.reason ? "rejected" : "unknown" });
+  }
+  return accepted;
+}
+
+/**
+ * THE ORDER STEP AS A WHOLE: your own side (or one already built by the record), the counterparty's side and the
+ * joint address. It hands out the fields the record and the recovery file are assembled from; NOT A SINGLE empty
+ * value: an address is not assembled without the other's point, and that is a refusal, not an empty string.
+ */
+export function orderStep({ order, side = null, counterparty = null, standIn = false, network = null }) {
+  const context = contextOf(order);
+  const own = side
+    ? { context, side, spendPoint: norm(side.pub && side.pub.ed), viewPoint: norm(side.viewPub),
+        encPub: norm(side.enc && side.enc.pub ? side.enc.pub : null) }
+    : buildOwnSide(order);
+  const lack = [];
+  if (own.side.half === undefined || own.side.half === null) lack.push("half");
+  if (own.side.viewHalf === undefined || own.side.viewHalf === null) lack.push("viewHalf");
+  if (!isPoint(own.spendPoint)) lack.push("spendPoint");
+  if (!isPoint(own.viewPoint)) lack.push("viewPoint");
+  if (lack.length) throw new SdkError("bad-input", { field: "side", missing: lack });
+
+  const other = acceptCounterparty({ context: own.context, side: own.side, counterparty, standIn });
+  const otherViewPoint = other.viewPoint || (other.viewHalf ? norm(builder().pointOf(other.viewHalf)) : null);
+  if (!otherViewPoint) throw new SdkError("bad-input", { field: "counterparty", missing: ["viewPoint"] });
+
+  let joint = null;
+  try {
+    joint = builder().jointAddress({
+      ownSpendHalf: own.side.half, ownViewHalf: own.side.viewHalf,
+      otherSpendPoint: other.edPub, otherViewPoint, network,
+    });
+  } catch { throw new SdkError("bad-input", { field: "network" }); }
+
+  return {
+    context: own.context,
+    own: { spendPoint: own.spendPoint, viewPoint: own.viewPoint, encPub: own.encPub, proof: own.side.proof },
+    side: own.side,
+    counterparty: other,
+    // READY-MADE RECORD AND FILE FIELDS: the names the engine reads (core/swap.js, halvesWalletOf) and the ones
+    // recovery file version 3 requires. A file without the other's view half will not be assembled - and that is
+    // named by the otherViewHalf field with the value null, not by an invented half.
+    wallet: {
+      spendHalf: halfHex(own.side.half), viewHalf: halfHex(own.side.viewHalf),
+      otherSpendPoint: other.edPub, otherViewPoint: norm(otherViewPoint),
+      otherViewHalf: other.viewHalf ? halfHex(other.viewHalf) : null,
+      address: joint.address, spendPub: norm(joint.spendPub), viewPub: norm(joint.viewPub),
+      otherCommitHalf: other.commitHalfClaimer || null,
+      // THE COMMITMENTS FOR THE HALVES - FROM THESE SAME SIDES, by the same call as the contract
+      // (keccak256(abi.encodePacked(bytes32 half))). One built side -> one commitment: there is no second half
+      // computation here. The other's half may not arrive (the order brings it) - then the counterparty's
+      // commitment is taken ready-made or stays null, not invented.
+      commitHalfLocker: norm(builder().halfCommitment(own.side.half)),
+      commitHalfClaimer: other.half !== undefined && other.half !== null
+        ? norm(builder().halfCommitment(other.half))
+        : (other.commitHalfClaimer || null),
+      network: network || null,
+    },
+  };
+}

package/src/preflight.mjs

@@ -0,0 +1,137 @@
+// PRE-SIGNATURE CHECKS: the same engine guards, but the answer is codes, not texts.
+//
+// WHAT MATTERS HERE and why this is not a "wrapper": the unverified must be named as unverified. The engine guards
+// already distinguish "good" from "not measured" (`checked: false`, the `*-unchecked` kinds), so the SDK does not
+// discard such checks and does not pass them off as green: it calls the guard with what it has and passes the
+// verdict on.
+import * as engine from "./engine.mjs";
+import { checkCodeFor } from "./codes.mjs";
+
+// The engine's refusal reason is a phrase for a person; the SDK does not hand it out: the interface translates the code itself.
+const toCheck = (verdict) => {
+  const v = verdict && typeof verdict === "object" ? verdict : {};
+  const { reason, kind, ok, checked, blocks, ...params } = v;
+  return {
+    code: checkCodeFor(kind),
+    ok: ok === true,
+    checked: checked !== false,
+    blocks: blocks === true,
+    kind: typeof kind === "string" ? kind : "unknown",
+    params,
+  };
+};
+
+// IS THERE ANYTHING TO COMPARE AGAINST. An empty value means "there was no check", and a check with nothing to
+// apply to is not run at all: otherwise it locks the signature where there is NOTHING to check against by
+// construction.
+const hasComparison = (...values) => values.some((v) => v !== undefined && v !== null && v !== "");
+
+const call = (fn, input) => {
+  try {
+    return fn(input);
+  } catch (error) {
+    // A guard that could not compute is "not checked", not "passed".
+    return { ok: false, checked: false, blocks: false, kind: "unchecked", error: String(error && error.message ? error.message : error) };
+  }
+};
+
+export function createPreflight({ config, wallet, limits = {} }) {
+  return async function preflight(offer = {}, options = {}) {
+    const guards = engine.config.SIGNING_GUARDS || {};
+    const nowMs = Number.isFinite(options.nowMs) ? options.nowMs : Date.now();
+    const quote = offer && typeof offer === "object" ? offer : {};
+    const tokenIsNative = Boolean(options.tokenIsNative);
+    const chain = config.evmNetwork;
+
+    const checks = [
+      // 1. THE QUOTE IS ALIVE. The deadline is taken from the quote: an expired one must not be signed, even if its numbers are correct.
+      call(engine.guards.quoteFreshnessVerdict, {
+        at: Number.isFinite(quote.at) ? quote.at : null,
+        ttlMs: Number.isFinite(quote.ttlMs) ? quote.ttlMs : null,
+        expiresAt: Number.isFinite(quote.expiresAt) ? quote.expiresAt : null,
+        nowMs,
+      }),
+      // 2. DEADLINES FROM THE CHAIN: the mark window and the claim window must not overlap.
+      call(engine.guards.deadlineVerdict, {
+        nowSec: Math.floor(nowMs / 1000),
+        readyBy: Number.isFinite(quote.readyBy) ? quote.readyBy : null,
+        t1: Number.isFinite(quote.t1) ? quote.t1 : null,
+        minReadyLeadSec: guards.minReadyLeadSec ?? null,
+        minClaimWindowSec: guards.minClaimWindowSec ?? null,
+      }),
+      // 3. SIZE. The grid is declared by the provider node, so the sizes come with the quote, not from a file.
+      call(engine.guards.rangeVerdict, {
+        size: Number.isFinite(quote.amount) ? quote.amount : null,
+        unit: quote.token || null,
+        min: Number.isFinite(quote.min) ? quote.min : (limits.minAmount ?? null),
+        max: Number.isFinite(quote.max) ? quote.max : (limits.maxAmount ?? null),
+        step: Number.isFinite(quote.step) ? quote.step : (limits.stepAmount ?? null),
+        quoteUnit: quote.token || null,
+      }),
+      // 4. MONEY: is there enough to pay and does anything remain for gas.
+      call(engine.guards.payBalanceVerdict, {
+        payBalanceWei: options.payBalanceWei ?? null,
+        payAmountWei: options.payAmountWei ?? null,
+        symbol: tokenIsNative ? chain.nativeSymbol : (quote.token || null),
+        decimals: Number.isFinite(options.decimals) ? options.decimals : 18,
+      }),
+      call(engine.guards.gasReserveVerdict, {
+        nativeBalanceWei: options.nativeBalanceWei ?? null,
+        requiredNativeWei: options.requiredNativeWei ?? null,
+        gasReserveWei: options.gasReserveWei ?? null,
+        symbol: chain.nativeSymbol,
+        decimals: 18,
+      }),
+      // 5. TOKEN ALLOWANCE. Without the person's consent no allowance is granted - that is a separate code.
+      call(engine.guards.allowanceVerdict, {
+        tokenIsNative,
+        allowanceWei: options.allowanceWei ?? null,
+        amountWei: options.payAmountWei ?? null,
+        consent: options.allowanceConsent === true,
+        symbol: quote.token || null,
+        decimals: Number.isFinite(options.decimals) ? options.decimals : 18,
+      }),
+      // 6. THE WALLET NETWORK against the settlement network.
+      call(engine.guards.networkGateVerdict, {
+        walletChainId: wallet.status().chainId,
+        selectedChainId: chain.chainId,
+        settlementChainId: chain.chainId,
+        selectedChainName: chain.name,
+      }),
+      // 7. THE COUNTERPARTY and 8. THE ESCROW STATE, 9. THE POINTS, 10. THE ORDER-BOOK SLOTS. These are chain
+      // reads: while they are absent, the guards must say "not checked" rather than stay silent (stages 2 and 3).
+      call(engine.guards.counterpartyVerdict, {
+        standIn: options.standIn === true,
+        liveChain: options.liveChain === true,
+        network: config.evmNetwork.id,
+        chainId: chain.chainId,
+      }),
+      call(engine.guards.escrowStateVerdict, { status: options.escrowStatus ?? null, error: null, address: options.escrowAddress ?? null }),
+      // THE POINTS AND SLOTS ARE TURNED ON ONLY WHEN THERE IS SOMETHING TO COMPARE AGAINST. Both compare an order
+      // ALREADY LYING ON THE CHAIN, while at the swap-start step the order does not exist YET: it is created by
+      // the very signature the guards protect, so there is nothing to compare against BY CONSTRUCTION. While both
+      // stood in the list unconditionally, on empty data each answered "not checked" (blocks: true), and the swap
+      // start ran into its own guard without ever reaching the signature. The check APPEARS when its data is
+      // brought (the core does this on mark/claim/refund - assertOrderSlots), and then incompleteness still locks:
+      // this is removing a check with nothing to apply to, not weakening one that compares.
+      ...(hasComparison(options.point, options.commit)
+        ? [call(engine.guards.escrowPointsVerdict, {
+            role: options.pointsRole ?? null,
+            what: options.pointsWhat ?? null,
+            point: options.point ?? null,
+            onchainPoint: options.onchainPoint ?? null,
+            commit: options.commit ?? null,
+            onchainCommit: options.onchainCommit ?? null,
+            readError: options.pointsReadError ?? null,
+          })]
+        : []),
+      ...(hasComparison(options.slots)
+        ? [call(engine.guards.liveOrderSlotsVerdict, { slots: options.slots ?? null, expect: options.slotsExpect ?? null, readError: options.slotsReadError ?? null })]
+        : []),
+    ];
+
+    const mapped = checks.map(toCheck);
+    const blockedBy = [...new Set(mapped.filter((c) => c.blocks).map((c) => c.code))];
+    return { ok: blockedBy.length === 0, blockedBy, checks: mapped };
+  };
+}

package/src/primitives.mjs

@@ -0,0 +1,47 @@
+// ATOMIC SWAP PRIMITIVES - FROM THE SAME npm PACKAGES AS THE PAGE BUNDLE.
+//
+// The bundle entry point (tools/atomic-browser-entry.mjs) hands the page exactly five names: ed25519, secp256k1,
+// keccak256, sha3_512, randomBytes. The order-side build modules (www/js/atomic/order.js) do NOT import them
+// themselves - they arrive as parameters. That is what lets the SDK expose the same primitives from the same
+// packages instead of dragging a hashed build artefact into the core: a package never has a "version with a
+// different cache".
+//
+// WHY EXACTLY THESE PACKAGES, AND NOT JUST ANY. keccak256 and sha3_512 are DIFFERENT functions, and they must
+// not be confused: the commitment for a half is computed with keccak256 (exactly as Solidity does it), while the
+// DLEQ proof uses SHA3-512 with wide reduction. Swapping one for the other looks like a typo and costs a whole
+// swap, so the difference is verified by a run on known values, not by eye.
+
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+// keccak_256 is taken from here, and NOT from the separate keccak256 package: that one accepts only a Buffer of
+// ITS OWN instance and refuses bytes from another module with "invalid type" (verified by a run). The popular
+// package of the family is already present for the curves and SHA3-512, and keccak_256 from it gives the same
+// thing - this is confirmed by the known value of the empty string in the check, which also shows it is not
+// sha3_256.
+import { keccak_256, sha3_512 } from "@noble/hashes/sha3.js";
+// The core speaks in CODES, not in phrases: a message here would become UI text by accident (check-sdk
+// forbids user-facing strings in sdk/src).
+import { fail } from "./errors.mjs";
+export { ed25519, secp256k1, sha3_512 };
+
+// The engine passes a Uint8Array, a Buffer and a string alike. We normalise on input so the caller need not think about it.
+export const keccak256 = (data) => {
+  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+  return keccak_256(bytes);
+};
+
+/** Bytes: the same representation as keccak256, so the caller need not tell the source apart. */
+export const keccak256Bytes = (data) => keccak256(data);
+
+// Random bytes. We take them from the environment (both the browser and Node provide crypto.getRandomValues),
+// not from a third-party library: the source of randomness is the last thing you want to shuffle around.
+export const randomBytes = (length) => {
+  const out = new Uint8Array(length);
+  const source = globalThis.crypto;
+  if (!source || typeof source.getRandomValues !== "function") fail("bad-input", { field: "random-bytes", why: "no-source" });
+  source.getRandomValues(out);
+  return out;
+};
+
+/** The five primitives as one set - exactly the shape createOrderBuilder expects. */
+export const primitives = { ed25519, secp256k1, keccak256, sha3_512, randomBytes };

package/src/quoteEip712.mjs

@@ -0,0 +1,35 @@
+// EIP-712 ORDER-QUOTE SIGNATURE - THE SDK SIDE (VERIFICATION ONLY).
+//
+// The SDK verifies, it does not sign: the maker's wallet key never reaches the customer's machine. The spec
+// (types, domain, digest, recovery) lives in quoteEip712Spec.mjs, byte-identical to the node's copy and pinned
+// by tools/check-quote-eip712.mjs. Here it is only bound to the SDK's own crypto primitives.
+//
+// The rule the old flag carried is kept: a quote that cannot be verified is REFUSED. A missing field, a
+// missing signature or an unusable domain is not "probably fine" - the caller names it with a code.
+import { keccak256, secp256k1 } from "./primitives.mjs";
+import {
+  recoverQuoteKey as recover,
+  quoteDigest as digest,
+  quoteMissingFields,
+  ORDER_QUOTE_FIELDS as FIELDS,
+  ORDER_QUOTE_TYPE as TYPE,
+  EIP712_DOMAIN_TYPE,
+  ORDER_QUOTE_DOMAIN_NAME,
+  ORDER_QUOTE_DOMAIN_VERSION,
+  ORDER_QUOTE_VERSION,
+} from "./quoteEip712Spec.mjs";
+
+const crypto = { keccak256, secp256k1 };
+
+export const ORDER_QUOTE_FIELDS = FIELDS;
+export const ORDER_QUOTE_TYPE = TYPE;
+export { EIP712_DOMAIN_TYPE, ORDER_QUOTE_DOMAIN_NAME, ORDER_QUOTE_DOMAIN_VERSION, ORDER_QUOTE_VERSION };
+
+/** Names of the signed-set fields the quote does not carry. Not empty - the quote is not verifiable. */
+export const orderQuoteMissingFields = (quote) => quoteMissingFields(quote);
+
+/** The digest the provider signed, from the quote's own declared fields. */
+export const orderQuoteDigest = (quote) => digest({ crypto, quote });
+
+/** The address that signed the quote, or null when it cannot be recovered. */
+export const recoverOrderQuoteKey = (quote) => recover({ crypto, quote });