@ninsei-labs/sdk 0.52.0 → 0.54.0

package/src/quotes.mjs

@@ -16,13 +16,18 @@
 //   3) a quote older than its own ttlMs is not shown, and a row that contradicts itself (the named sides disagree
 //      with the pair's name) is not read at all.
 import { fail } from "./errors.mjs";
+import { SDK_VERSION } from "./version.mjs";
 import * as engine from "./engine.mjs";
 import { orderQuoteMissingFields, recoverOrderQuoteKey } from "./quoteEip712.mjs";
 import { claimGasGiftWei } from "../engine/evm/claimGas.js";
+import { parseXmr } from "../engine/core/xmrAmount.js";
+import { takerHalves, takerHalvesV2, recoverySaltOf } from "./recovery-key.mjs";
+import { acceptCounterparty, buildOwnSideFromHalves, jointAddress } from "./order.mjs";
+import { requestFirmQuote } from "./relayFirmClient.mjs";
 // THE CHAIN READ NEEDED TO ASK THE REGISTRY WHO OWNS THE KEY. The selector is COMPUTED from the signature, not
 // remembered: a single wrong hex digit would call another function and return a zero address - and a zero
 // address is exactly the answer "nobody owns this key", which the caller would take as the truth.
-import { keccak256 } from "./primitives.mjs";
+import { keccak256, secp256k1 } from "./primitives.mjs";
 
 const utf8 = (value) => new TextEncoder().encode(String(value));
 const bytesToHexQ = (bytes) => { let out = "0x"; for (const b of bytes) out += b.toString(16).padStart(2, "0"); return out; };
@@ -40,6 +45,8 @@ const hexToBytesQ = (hex) => {
   return out;
 };
 const ZERO_ADDRESS = "0x" + "00".repeat(20);
+const sameText = (a, b) => String(a === undefined || a === null ? "" : a).toLowerCase()
+  === String(b === undefined || b === null ? "" : b).toLowerCase();
 const addressFromWord = (raw) => {
   const h = String(raw == null ? "" : raw).replace(/^0x/, "");
   return h.length >= 40 ? "0x" + h.slice(-40).toLowerCase() : null;
@@ -398,7 +405,12 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
     // plus the priority part of the gas price. A buy quote has no tip; a sale is the only route where one exists.
     async sale(request) {
       if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
-      const payload = request.request && typeof request.request === "object" ? request : { request };
+      // THE NODE GATES THE THREE BROWSER BODY ROUTES ON THE CLIENT'S SDK LINE. The value is the package's own
+      // baked-in version, not a caller field: a caller cannot claim a line it was not built from.
+      // THE ENVELOPE IS THE REQUEST. The node accepts both `{ request: {...} }` and a bare body; every check below
+      // must read the same object the node priced, not the outer envelope that carries only `sdkVersion`.
+      const saleRequest = request.request && typeof request.request === "object" ? request.request : request;
+      const payload = { ...(request.request && typeof request.request === "object" ? request : { request }), sdkVersion: SDK_VERSION };
       let res = null;
       try {
         res = await http.tryJson(config.route("orderSell"), {
@@ -412,6 +424,162 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       const ticket = res.body;
       const quote = (ticket.handoff && ticket.handoff.quote) || ticket.quote || null;
       if (!quote || typeof quote !== "object") fail("quote-field-unbound", { step: "order-sell", field: "quote" });
+      // THE SALE TICKET IS A SIGNED QUOTE, AND IT GETS THE SAME GATES AS `firm`: every field of the signed set,
+      // its expiry, the EIP-712 signature and the named key, the registry's provider mapping, the interface's
+      // allow-list, and the factory/implementation policy. The one difference is the binding below: a sale has no
+      // caller-supplied order terms, so its context is checked against `ticket.order` when the node returns it.
+      // A MISSING FIELD OF THE SIGNED SET IS NOT "PROBABLY ZERO": the digest cannot be built, so the quote is
+      // not verifiable and is refused (its own code, so the interface can say which field is unbound).
+      const missingFields = orderQuoteMissingFields(quote);
+      if (missingFields.length) fail("quote-field-unbound", { step: "signature", missing: missingFields });
+      // THE QUOTE'S OWN EXPIRY, checked against the clock the core already has. It is bound in the signature too,
+      // but a stale quote is refused by its own code rather than looking like a signature failure.
+      const validUntil = Number(quote.validUntil);
+      // THE SCALE IS SECONDS: the same as the order's deadlines and block.timestamp. The core's clock is in
+      // milliseconds (Date.now), so exactly ONE boundary is converted - "now", not the quote value itself: one
+      // unit for the value, one conversion at the input.
+      const nowSec = Math.floor(now() / 1000);
+      if (Number.isFinite(validUntil) && validUntil > 0 && validUntil <= nowSec) {
+        fail("quote-expired", { step: "signature", validUntil });
+      }
+      // RECOVER, THEN MATCH THE NAMED KEY. A signature that does not recover is one refusal; a valid signature
+      // that recovers to a DIFFERENT address is another (the quote names a key that did not sign it).
+      const recoveredKey = recoverOrderQuoteKey(quote);
+      if (recoveredKey === null) fail("quote-signature-invalid", { step: "signature" });
+      const declaredKey = String(quote.quoteKey).toLowerCase();
+      if (recoveredKey !== declaredKey) fail("quote-key-mismatch", { step: "signature", got: recoveredKey, want: declaredKey });
+      // WHO OWNS THE KEY - ASKED OF THE REGISTRY NAMED BY THE QUOTE. Both fields are part of the signed set, so
+      // they cannot be swapped after signing; this is what turns "a key signed it" into "this provider's key
+      // signed it". No chain-read seam - refuse rather than take the signature on trust.
+      const registry = String(quote.registry || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(registry) || registry === ZERO_ADDRESS) {
+        fail("quote-field-unbound", { step: "registry", field: "registry" });
+      }
+      const declaredProvider = String(quote.provider || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(declaredProvider) || declaredProvider === ZERO_ADDRESS) {
+        fail("quote-field-unbound", { step: "registry", field: "provider" });
+      }
+      if (typeof evmCall !== "function") fail("quote-registry-unchecked", { step: "registry", why: "no-chain-read" });
+      let mappedProvider = null;
+      try {
+        mappedProvider = addressFromWord(await evmCall({ to: registry, data: providerOfData(declaredKey) }));
+      } catch {
+        fail("quote-registry-unchecked", { step: "registry", why: "read-failed", registry });
+      }
+      if (mappedProvider === null || mappedProvider === ZERO_ADDRESS) {
+        fail("quote-key-unknown", { step: "registry", registry, quoteKey: declaredKey });
+      }
+      if (mappedProvider !== declaredProvider) {
+        fail("quote-provider-mismatch", { step: "registry", got: mappedProvider, want: declaredProvider });
+      }
+      // THE INTERFACE'S OWN ADMISSION LIST - POLICY, NOT PROOF. The chain says whose key it is; whether this
+      // interface trades with that provider at all is the interface's decision, and it rides as a hook.
+      if (typeof providerAllowed === "function" && providerAllowed(declaredProvider) !== true) {
+        fail("quote-provider-not-allowed", { step: "policy", provider: declaredProvider });
+      }
+      // THE FACTORY: NAMED BY THE PROVIDER'S RECORD, CHECKED BY ITS CODE (#103). The factory will verify the
+      // quote in EVM (it is the EIP-712 verifyingContract), so it must be the one the record names AND its
+      // code must be a build this interface knows. The record lookup always runs; the code check runs when a
+      // policy list was supplied (nothing to pin against otherwise).
+      const declaredFactory = String(quote.factory || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(declaredFactory) || declaredFactory === ZERO_ADDRESS) {
+        fail("quote-field-unbound", { step: "factory", field: "factory" });
+      }
+      let recordedFactory = null;
+      try {
+        recordedFactory = addressFromWord(await evmCall({ to: registry, data: factoryOfData(declaredProvider) }));
+      } catch {
+        fail("quote-factory-unchecked", { step: "factory", why: "read-failed", registry });
+      }
+      if (recordedFactory === null || recordedFactory === ZERO_ADDRESS) {
+        fail("quote-factory-unknown", { step: "factory", registry, provider: declaredProvider });
+      }
+      if (recordedFactory !== declaredFactory) {
+        fail("quote-factory-mismatch", { step: "factory", got: declaredFactory, want: recordedFactory });
+      }
+      if (factoryPolicy) {
+        if (typeof evmCode !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-code-read" });
+        let codeHex = null;
+        try { codeHex = await evmCode(declaredFactory); } catch { fail("quote-factory-unchecked", { step: "factory", why: "code-read-failed", factory: declaredFactory }); }
+        const codeBytes = hexToBytesQ(codeHex);
+        // EXTCODEHASH SEMANTICS: keccak256 of the runtime code. An address with no code (empty/0x) hashes to
+        // the keccak of empty, which is not on any build list - refused like any unknown build.
+        const codeHash = bytesToHexQ(keccak256(codeBytes || new Uint8Array(0)));
+        if (!factoryPolicy.includes(codeHash)) {
+          fail("quote-factory-code-unknown", { step: "factory", factory: declaredFactory, codeHash });
+        }
+      }
+      // THE IMPLEMENTATION THE CLONES WILL EXECUTE (#114). A pinned factory CODE is not enough on its own: the
+      // implementation ADDRESS lives in the factory's STORAGE, so the client re-reads the pair the factory itself
+      // checks (implementation() / implementationCodeHash()) and the CODE at that address, then applies the same
+      // verdict (verifyFactoryImplementationOnChain). A delegatecall to an address WITHOUT code SUCCEEDS, so a
+      // clone without an implementation would take the ETH and its markReady/claim/refund would appear to go
+      // through while doing nothing - that is exactly the case this refuses. The live code is re-hashed here, so
+      // the verdict does not trust the factory's own answer alone.
+      if (implementationPolicy) {
+        if (typeof evmCall !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-chain-read" });
+        if (typeof evmCode !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-code-read" });
+        const verdict = await engine.evm.verifyFactoryImplementationOnChain({
+          factory: declaredFactory,
+          read: evmCall,
+          code: (address) => evmCode(address),
+          policy: implementationPolicy,
+          hashCode: (codeHex) => bytesToHexQ(keccak256(hexToBytesQ(codeHex) || new Uint8Array(0))),
+        });
+        if (!verdict.ok) {
+          const unknown = verdict.why === "implementation-code-unknown" ||
+            verdict.why === "implementation-code-mismatch" || verdict.why === "implementation-has-no-code";
+          fail(unknown ? "quote-factory-code-unknown" : "quote-factory-unchecked",
+            { step: "factory", why: verdict.why, factory: declaredFactory, implementation: verdict.implementation || null });
+        }
+      }
+      // THE PERSON SELLING IS THE CLAIMER. The interface's denylist is applied to that address, not to a
+      // caller-chosen value: a ticket that names a denied claimer must not reach the funding step.
+      const saleClaimer = String((saleRequest && saleRequest.claimer) || quote.claimer || "").toLowerCase();
+      if (saleClaimer && denylist && denylist.has(saleClaimer)) fail("address-denied", { step: "order-sell" });
+      if (saleRequest && saleRequest.claimer && quote.claimer && String(saleRequest.claimer).toLowerCase() !== String(quote.claimer).toLowerCase()) {
+        fail("quote-refused", { step: "order-sell", why: "claimer-not-bound" });
+      }
+      // THE XMR THE CALLER ASKED FOR IS THE XMR THE QUOTE SIGNED. A ticket is paid against the signed `xmrAmount`;
+      // accepting a different requested amount shows one figure and settles another.
+      const requestedXmr = saleRequest && (saleRequest.xmr !== undefined ? saleRequest.xmr
+        : (saleRequest.xmrAmount !== undefined ? saleRequest.xmrAmount : null));
+      if (requestedXmr !== null && requestedXmr !== undefined) {
+        let wanted = null;
+        try { wanted = BigInt(String(requestedXmr)); } catch { wanted = null; }
+        // A whole-XMR request (the public `xmr` field) is converted with the package's own parser; digits are
+        // already atomic. A value that cannot be read is a refusal, not a skipped check.
+        if (wanted === null || wanted < 10n ** 12n) {
+          try { wanted = parseXmr(String(requestedXmr)); } catch { wanted = null; }
+        }
+        let signedAtomic = null;
+        try { signedAtomic = quote.xmrAmount === undefined || quote.xmrAmount === null || quote.xmrAmount === ""
+          ? null : BigInt(String(quote.xmrAmount)); } catch { signedAtomic = null; }
+        if (signedAtomic === null || wanted === null || wanted !== signedAtomic) {
+          fail("quote-refused", { step: "order-sell", why: "xmr-amount" });
+        }
+      }
+      // THE CONTEXT WHEN THE TICKET CARRIES ITS ORDER. The signed quote binds the order terms; when the node
+      // returns the order it priced, recompute the context with our own engine and refuse a mismatch.
+      if (ticket.order && typeof ticket.order === "object") {
+        // THE RETURNED ORDER MUST BE THE SIGNED ONE FIELD BY FIELD. `quote.context` is a derived label, not a
+        // signed field; comparing only it lets a node return another amount with a matching relabelled context.
+        const sameValue = (a, b) => String(a === undefined || a === null ? "" : a).replace(/^0x/i, "").toLowerCase()
+          === String(b === undefined || b === null ? "" : b).replace(/^0x/i, "").toLowerCase();
+        for (const name of ["locker", "claimer", "amount", "readyBy", "t1", "salt"]) {
+          if (!sameValue(ticket.order[name], quote[name])) {
+            fail("quote-refused", { step: "order-sell", why: "other-terms", field: name });
+          }
+        }
+        // The context remains a useful cross-check when both sides carry it.
+        if (quote.context) {
+          let expectedSaleContext = null;
+          try { expectedSaleContext = engine.orderContext.orderContextString(ticket.order); } catch { expectedSaleContext = null; }
+          if (expectedSaleContext !== null && String(quote.context) !== expectedSaleContext) {
+            fail("quote-refused", { step: "order-sell", why: "other-terms", field: "context" });
+          }
+        }
+      }
       // THE TICKET'S TIP MUST BE THE SIGNED ONE. The node returns both the ticket's `claimTip` object and the quote it
       // signed; a difference means the figure shown to the person is not the figure the escrow will pay.
       const shown = ticket.claimTip && ticket.claimTip.wei !== undefined && ticket.claimTip.wei !== null
@@ -467,7 +635,7 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ providerId: request.providerId, order: request.order,
-            ...(viewHalfClaimer === null ? {} : { viewHalfClaimer }) }),
+            ...(viewHalfClaimer === null ? {} : { viewHalfClaimer }), sdkVersion: SDK_VERSION }),
         });
       } catch (error) {
         if (error && error.code === "bad-input") throw error;
@@ -650,5 +818,244 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       }
       return quote;
     },
+
+    /**
+     * A firm quote through the relay, starting from the one recovery key.
+     *
+     * The caller gives the signed features, the order terms and the recovery key; this method derives the
+     * client half and both view points, sends one relay request and verifies the relay answer plus the
+     * on-chain registry/factory binding. It returns the signed `orderQuote` and a `quote` carrying the maker's
+     * view half, so `swaps.start` does not have to map relay fields by hand.
+     */
+    async firmRelay(request) {
+      if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
+      const features = request.features;
+      const order = request.order && typeof request.order === "object" ? { ...request.order } : null;
+      if (!features || typeof features !== "object") fail("bad-input", { field: "features" });
+      if (!order) fail("bad-input", { field: "order" });
+      const side = String(request.side || "");
+      if (side !== "ask" && side !== "bid") fail("bad-input", { field: "side" });
+      const maker = String(features.provider || "").toLowerCase();
+      const registry = String(features.registry || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(maker) || maker === ZERO_ADDRESS) fail("bad-input", { field: "features.provider" });
+      if (!/^0x[0-9a-f]{40}$/.test(registry) || registry === ZERO_ADDRESS) fail("bad-input", { field: "features.registry" });
+      if (denylist && typeof order.locker === "string" && denylist.has(order.locker.toLowerCase())) {
+        fail("address-denied", { step: "order-quote" });
+      }
+      // THE PROVIDER'S ROLE IS PART OF THE SIDE. A caller that names another claimer/locker is not asking
+      // for this side; a caller that omits it gets the only value the wire allows.
+      if (side === "ask") {
+        if (order.claimer && !sameText(order.claimer, maker)) fail("bad-input", { field: "order.claimer" });
+        order.claimer = maker;
+      } else {
+        if (order.locker && !sameText(order.locker, maker)) fail("bad-input", { field: "order.locker" });
+        order.locker = maker;
+      }
+      const chainId = Number(order.chainId);
+      if (!Number.isSafeInteger(chainId) || chainId <= 0) fail("bad-input", { field: "order.chainId" });
+      const windows = Array.isArray(features.firmWindows)
+        ? features.firmWindows.filter((entry) => entry && entry.side === side)
+        : [];
+      const markets = [...new Set(windows.map((entry) => entry.market).filter((value) => typeof value === "string" && value))];
+      const market = request.market !== undefined ? String(request.market) : (markets.length === 1 ? markets[0] : null);
+      if (!market) fail("bad-input", { field: "market" });
+      const window = windows.find((entry) => entry.market === market) || null;
+      if (!window) fail("quote-refused", { step: "features", why: "window" });
+      const xmrNetwork = request.xmrNetwork !== undefined ? String(request.xmrNetwork) : window.xmrNetwork;
+      if (!xmrNetwork) fail("bad-input", { field: "xmrNetwork" });
+      if (request.xmrAmount === undefined || request.xmrAmount === null || request.xmrAmount === "") {
+        fail("bad-input", { field: "xmrAmount" });
+      }
+      const claimTip = request.claimTip === undefined || request.claimTip === null ? "0" : String(request.claimTip);
+      const mnemonic = typeof request.recoveryKey === "string"
+        ? request.recoveryKey
+        : request.recoveryKey && typeof request.recoveryKey.mnemonic === "string" ? request.recoveryKey.mnemonic : null;
+      if (!mnemonic) fail("bad-input", { field: "recoveryKey" });
+      const saltRequested = request.recoverySalt !== undefined && request.recoverySalt !== null;
+      const indexRequested = request.recoveryIndex !== undefined && request.recoveryIndex !== null;
+      if (saltRequested && indexRequested) fail("bad-input", { field: "recoverySalt", why: "with-recovery-index" });
+      let derived = null;
+      let derivation = null;
+      if (indexRequested) {
+        const index = Number(request.recoveryIndex);
+        if (!Number.isSafeInteger(index) || index < 0) fail("bad-input", { field: "recoveryIndex" });
+        derived = takerHalves({ mnemonic, chainId, index });
+        derivation = { kind: "index-v1", index };
+      } else {
+        if (!order.factory || !/^0x[0-9a-f]{40}$/i.test(String(order.factory))) fail("bad-input", { field: "order.factory" });
+        let salt = null;
+        try { salt = recoverySaltOf(saltRequested ? request.recoverySalt : order.salt); }
+        catch { fail("bad-input", { field: "recoverySalt" }); }
+        if (saltRequested) {
+          let orderSalt = null;
+          try { orderSalt = recoverySaltOf(order.salt); } catch { fail("bad-input", { field: "recoverySalt", why: "order-salt" }); }
+          if (salt !== orderSalt) fail("bad-input", { field: "recoverySalt", why: "order-salt" });
+        }
+        derived = takerHalvesV2({ mnemonic, chainId, factory: order.factory, salt });
+        derivation = { kind: "salt-v2", salt };
+      }
+      const own = buildOwnSideFromHalves(order, { spendHalf: derived.spendHalf, viewHalf: derived.viewHalf });
+      const xa = secp256k1.Point.fromHex(own.side.proof.XA);
+      const clientHalf = {
+        commitHalf: bytesToHexQ(keccak256(xa.toBytes(false).slice(1))),
+        edPoint: own.side.pub.ed,
+        proof: own.side.proof,
+      };
+      const result = await requestFirmQuote({
+        relayUrl: request.relayUrl,
+        partner: request.partner,
+        fetchImpl: request.fetchImpl,
+        timeoutMs: request.timeoutMs,
+        features,
+        terms: {
+          market,
+          side,
+          maker,
+          registry,
+          xmrNetwork,
+          order,
+          xmrAmount: String(request.xmrAmount),
+          claimTip,
+        },
+        clientHalf,
+        edViewPointClient: own.side.viewPub,
+        edViewPointNode: derived.makerViewPoint,
+        nodeViewScalar: derived.makerViewHalf,
+        clientViewScalar: side === "bid" ? derived.viewHalf : null,
+        side,
+      });
+      const quote = result.quote;
+      // THE NODE HALF IS NOT A DECORATION. The answer's proof must stand in THIS order's context and the proven
+      // point must be the one the quote commits to. For ask that is the claimer's commitment; for bid the node
+      // half is the locker's and carries its own commitment. This is the same engine check the swap path uses.
+      const nodeHalf = result.nodeHalf;
+      acceptCounterparty({
+        context: own.context,
+        side: own.side,
+        counterparty: side === "ask"
+          ? {
+              proof: nodeHalf.proof,
+              edPub: quote.edPointClaimer,
+              commitHalfClaimer: quote.commitHalfClaimer,
+              viewPoint: result.edViewPointClaimer,
+              viewHalf: derived.makerViewHalf,
+            }
+          : {
+              proof: nodeHalf.proof,
+              edPub: nodeHalf.edPoint,
+              commitHalfClaimer: nodeHalf.commitHalf,
+              viewPoint: result.edViewPointLocker,
+              viewHalf: derived.makerViewHalf,
+            },
+      });
+      // THE ONE-TIME XMR ADDRESS IS DERIVED, NOT TAKEN FROM THE RELAY. Both sides must assemble it from the same
+      // points: our spend/view halves from the recovery key, the node's spend point and view point from the answer.
+      // For ask we are the locker and the node is the claimer; for bid the roles are swapped.
+      const nodeSpendPoint = side === "ask" ? quote.edPointClaimer : nodeHalf.edPoint;
+      const nodeViewPoint = side === "ask" ? result.edViewPointClaimer : result.edViewPointLocker;
+      const oneTimeAddress = jointAddress({
+        ownSpendHalf: derived.spendHalf,
+        ownViewHalf: derived.viewHalf,
+        otherSpendPoint: nodeSpendPoint,
+        otherViewPoint: nodeViewPoint,
+        network: xmrNetwork,
+      });
+      // THE ESCROW ADDRESS IS A READ, NOT A GUESS. predict() is a free call and uses the same signed quote the
+      // factory will receive; the locker fields are the side that deposits ETH. A read failure is a named refusal,
+      // because a client that cannot name the escrow cannot watch it.
+      const lockerHalf = side === "ask"
+        ? { commitHalfLocker: clientHalf.commitHalf, edPointLocker: own.side.pub.ed, edViewPointLocker: own.side.viewPub }
+        : { commitHalfLocker: nodeHalf.commitHalf, edPointLocker: nodeHalf.edPoint, edViewPointLocker: result.edViewPointLocker };
+      let escrow = null;
+      try {
+        const predicted = await evmCall({
+          to: quote.factory,
+          data: engine.evm.encodePredict({ ...result.orderQuote, ...lockerHalf, signature: result.orderQuote.signature }),
+        });
+        escrow = engine.evm.decodeAddress(predicted);
+      } catch {
+        fail("quote-escrow-unchecked", { step: "factory", why: "predict-failed", factory: quote.factory });
+      }
+      if (providerAllowed && providerAllowed(maker) !== true) {
+        fail("quote-provider-not-allowed", { step: "policy", provider: maker });
+      }
+      if (typeof evmCall !== "function") fail("quote-registry-unchecked", { step: "registry", why: "no-chain-read" });
+      let mappedProvider = null;
+      try {
+        mappedProvider = addressFromWord(await evmCall({ to: registry, data: providerOfData(quote.quoteKey) }));
+      } catch { fail("quote-registry-unchecked", { step: "registry", why: "read-failed", registry }); }
+      if (mappedProvider === null || mappedProvider === ZERO_ADDRESS) fail("quote-key-unknown", { step: "registry", registry, quoteKey: quote.quoteKey });
+      if (!sameText(mappedProvider, quote.provider)) {
+        fail("quote-provider-mismatch", { step: "registry", got: mappedProvider, want: quote.provider });
+      }
+      let recordedFactory = null;
+      try {
+        recordedFactory = addressFromWord(await evmCall({ to: registry, data: factoryOfData(quote.provider) }));
+      } catch { fail("quote-factory-unchecked", { step: "factory", why: "read-failed", registry }); }
+      if (recordedFactory === null || recordedFactory === ZERO_ADDRESS) {
+        fail("quote-factory-unknown", { step: "factory", registry, provider: quote.provider });
+      }
+      if (!sameText(recordedFactory, quote.factory)) {
+        fail("quote-factory-mismatch", { step: "factory", got: quote.factory, want: recordedFactory });
+      }
+      if (factoryPolicy) {
+        if (typeof evmCode !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-code-read" });
+        let codeHex = null;
+        try { codeHex = await evmCode(quote.factory); } catch { fail("quote-factory-unchecked", { step: "factory", why: "code-read-failed", factory: quote.factory }); }
+        const codeHash = bytesToHexQ(keccak256(hexToBytesQ(codeHex) || new Uint8Array(0)));
+        if (!factoryPolicy.includes(codeHash)) fail("quote-factory-code-unknown", { step: "factory", factory: quote.factory, codeHash });
+      }
+      if (implementationPolicy) {
+        if (typeof evmCall !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-chain-read" });
+        if (typeof evmCode !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-code-read" });
+        const verdict = await engine.evm.verifyFactoryImplementationOnChain({
+          factory: quote.factory,
+          read: evmCall,
+          code: (address) => evmCode(address),
+          policy: implementationPolicy,
+          hashCode: (codeHex) => bytesToHexQ(keccak256(hexToBytesQ(codeHex) || new Uint8Array(0))),
+        });
+        if (!verdict.ok) {
+          const unknown = verdict.why === "implementation-code-unknown" ||
+            verdict.why === "implementation-code-mismatch" || verdict.why === "implementation-has-no-code";
+          fail(unknown ? "quote-factory-code-unknown" : "quote-factory-unchecked",
+            { step: "factory", why: verdict.why, factory: quote.factory, implementation: verdict.implementation || null });
+        }
+      }
+      const tipCheck = (() => {
+        try { return claimTipVerdict({ claimTipWei: quote.claimTip }); }
+        catch { return { ok: true, tipWei: "0" }; }
+      })();
+      if (!tipCheck.ok && tipCheck.code === "quote-tip-unreadable") {
+        fail("quote-field-unbound", { step: "claimTip", field: "claimTip" });
+      }
+      if (tipCheck.tipWei !== "0") {
+        if (typeof evmBlock !== "function") fail("quote-tip-unchecked", { step: "claimTip", why: "no-block-read" });
+        let block = null;
+        try { block = await evmBlock("latest"); } catch { fail("quote-tip-unchecked", { step: "claimTip", why: "block-read-failed" }); }
+        const baseFeeWei = block && (block.baseFeePerGas !== undefined ? block.baseFeePerGas : block.baseFeeWei);
+        const verdict = claimTipVerdict({ claimTipWei: quote.claimTip, baseFeeWei });
+        if (!verdict.ok) fail(verdict.code, { step: "claimTip", ...verdict });
+      }
+      return {
+        ...result,
+        quote: { ...quote, viewHalfClaimer: derived.makerViewHalf },
+        order,
+        // THE SHAPE `swaps.start` TAKES: the proof and the claimer commitment travel with the view half, so a
+        // caller can pass this object as `counterparty` without rebuilding the relay fields.
+        counterparty: {
+          proof: nodeHalf.proof,
+          edPointClaimer: side === "ask" ? quote.edPointClaimer : nodeHalf.edPoint,
+          commitHalfClaimer: side === "ask" ? quote.commitHalfClaimer : nodeHalf.commitHalf,
+          viewHalfClaimer: derived.makerViewHalf,
+          viewPoint: side === "ask" ? result.edViewPointClaimer : result.edViewPointLocker,
+        },
+        viewHalfClaimer: derived.makerViewHalf,
+        viewHalfPoint: derived.makerViewPoint,
+        jointAddress: oneTimeAddress.address,
+        escrow,
+        recovery: derivation,
+      };
+    },
   };
 }