@ninsei-labs/sdk 0.53.0 → 0.54.0

package/CHANGELOG.md

@@ -1,4 +1,31 @@
-## Unreleased
+## 0.54.0 — 2026-10-29
+
+- `findSwaps` no longer walks the allocator's 100,000 v1 indices in one synchronous call. One call scans at most
+  `RECOVERY_SCAN_DEFAULT` (1000) indices, yields to the event loop between chunks, and returns `nextIndex` with
+  `complete: false` and `incompleteReason: "max-index"` when it stopped. A caller continues from `nextIndex`; a search
+  that matched every order in the logs is complete without scanning the rest. `maxIndex` is the number of indices for
+  this call.
+- `findSwaps` accepts an AbortSignal-like `signal` and an `onProgress` callback. An aborted scan returns
+  `incompleteReason: "aborted"` with the same `nextIndex`; progress is reported after every chunk and after the final
+  index. The SDK creates no worker: a caller can run the same call in one.
+- The relay firm client has its signed-features check and request builder: a `NodeFeatures` digest with the
+  `FirmWindow` array, signature recovery, request binding, a normalised client half, and one HPKE envelope per
+  request. Ask carries one view scalar; bid carries two. Wire revision 13 removed the `capabilities` array: the
+  features now always carry a nonzero HPKE key and at least one firm window.
+- The relay firm client's HTTP hop is `requestFirmQuote`: it posts the exact payload once, keeps a relay refusal
+  code (`compliance`, `no_liquidity`, `size`, `paused`, `unavailable`, `bad_request`, `price_changed`), maps a
+  transport failure to `server-unavailable`, and verifies the outer frame and the inner `OrderQuote` before
+  returning. It also checks the relay/forwarded/answer relay-id equality.
+- `quotes.firmRelay` is the recovery-key adapter: it derives the client half and both view points from one
+  key, fills the provider's role for ask or bid, verifies the node half's DLEQ proof and commitment, sends one
+  relay request, and checks the registry provider and factory against the answer before returning the signed
+  `orderQuote`, the one-time joint XMR address, a `counterparty` object ready for `swaps.start`, and the maker
+  view half. `FirmOffer` now matches the direct `firm` call (`providerId`, `order`, optional `viewHalfClaimer`).
+- `swaps.sellWatch` is the client-side sell wait: it reads the escrow itself and returns `ready`,
+  `claimed` or `refunded` (or `sell-timeout`), with no backend watcher and no signature.
+- `swaps.startSell` records a sell from a verified relay offer: the one-time address, escrow, our half and the
+  order expectations survive a reload; the same offer resumes the same record. `swaps.sellClaim` claims from
+  that record, from the claimer's own wallet.
 
 ## 0.53.0 — 2026-10-28
 

package/README.md

@@ -17,7 +17,8 @@ machine). The wallet arrives as an EIP-1193 provider, storage as an adapter, and
 | `recovery.open` — parsing the recovery file | works |
 | `sim` — sandbox scenarios and time | works (applying to a swap — stage 2) |
 | `quotes.watch` | works: live indicative quotes, its own client; a snapshot carries the display fields (sides, networks, `why`, signature, age, maturity), and the size can be NAMED (`size`) |
-| `quotes.firm` | answers `not-implemented` (stage 2: signing with a key and the order protocol) |
+| `quotes.firm` | works: a signed, binding quote with a TTL; a refusal is a named code |
+| `quotes.firmRelay` | works: a firm quote through a relay, built from one recovery key; the node half is DLEQ-checked |
 | `swaps.list` / `swaps.get` | read state from storage (and after a page reload) |
 | `swaps.start` | holds the order: guards → recovery file and the person's confirmation → order → locking funds → **recording with us and watching the Monero address**; returns the named state `step: "xmr-incoming"` |
 | `swaps.watch` | waits for XMR to arrive at the joint address with the same request as the page (`GET /swaps/{id}`): arrived — returns the fact (amount, confirmations, txid); did not wait — a refusal with the code `xmr-timeout`; already on the address but barred by `unlock_time` — a refusal with the code `xmr-locked` (the boundary is in `params.until`), and NO ready mark; the maker DECLINED the order — returns `SwapDeclinedWatch` (`declined: true`, `terminal: "declined"`, the node's own `code`), with every action off; with expectations and a wallet, places the ready mark after the arrival |
@@ -173,7 +174,7 @@ signature, the age (`ageMs`) and the maturity level (`finality`) — display fie
 The price does not depend on volume: the volume is needed by the provider to say whether it takes such a size. So
 the size is computed from the person's amount and is snapped to the node's grid **down**, and a size outside the
 range is not aligned: it is the provider's refusal, and it arrives as a code. Indicative quotes commit to nothing;
-`quotes.firm` commits (stage 2).
+`quotes.firm` and `quotes.firmRelay` commit, and the relay path carries the maker's signed terms and its view half.
 
 ## Found orders and the paying token
 
@@ -182,8 +183,12 @@ public `salt` in its own `OrderCreated`: the binding is `ninsei-taker-v2|<chain>
 words on another device or at another factory produce a different half and no number is reserved. The result says
 `derivation: "salt-v2"` and leaves `index` null. Existing v1 orders stay on `ninsei-taker-v1|<chain>|<index>` and are
 still found by the index path; a v2 result needs no range scan. For a v1 fallback, discovery does **not** stop after a
-run of empty numbers: the allocator's whole range is searched by default, a smaller caller-supplied `maxIndex` returns
-`complete: false` with `searchedUpTo`, and `gap` is ignored. Each found order reports:
+run of empty numbers. One call scans at most `RECOVERY_SCAN_DEFAULT` (1000) indices; that keeps a shared factory from
+freezing the page. The result names where it stopped: `complete: false`, `searchedUpTo`, `incompleteReason: "max-index"`
+and `nextIndex`. A caller that needs more passes `nextIndex` back as `fromIndex`; the scan yields between chunks so the
+page stays responsive. `maxIndex` is the number of indices for this call, and `gap` is ignored. `onProgress` receives
+`{ scanned, index }` after each chunk and after the final index; `signal` stops between chunks and returns
+`incompleteReason: "aborted"` with the same resumable shape.
 
 - `amount` — the escrow's **native** amount in wei;
 - `settlementToken: "native"` — what the escrow receives;

package/index.d.ts

@@ -454,6 +454,11 @@ export interface QuotesApi {
   snapshot(): QuoteSnapshot | null;
   /** A binding quote with a TTL. A refusal comes as a code, not text. */
   firm(offer: FirmOffer): Promise<Quote>;
+  /**
+   * A firm quote through a relay, built from one recovery key. The relay answer is verified against the
+   * requested terms and the on-chain registry/factory binding before it is returned.
+   */
+  firmRelay(request: FirmRelayOffer): Promise<FirmRelayAnswer>;
   /**
    * A reverse-mode ticket: the maker sells XMR. The request is the node's `request` object; the answer carries the
    * signed order quote and its claim tip, which is checked against the gas price before it is returned.
@@ -660,11 +665,60 @@ export interface QuoteReference {
 }
 
 export interface FirmOffer {
-  readonly direction: "buy" | "sell";
-  readonly token: string;
-  readonly amount: number;
-  readonly receiveTo: string;
-  readonly providerId?: string;
+  /** Who gives the quote. Without it there is no one to ask. */
+  readonly providerId: string;
+  /** The order terms the signature is bound to. */
+  readonly order: Readonly<Record<string, unknown>>;
+  /** The taker's maker view half when the order was built from a recovery key. */
+  readonly viewHalfClaimer?: string;
+}
+
+export interface FirmRelayOffer {
+  /** Relay origin, without the `/v1/quote` path. */
+  readonly relayUrl: string;
+  /** The signed public features the relay forwarded; they are verified before anything is sent. */
+  readonly features: Readonly<Record<string, unknown>>;
+  readonly order: Readonly<Record<string, unknown>>;
+  readonly side: "ask" | "bid";
+  /** The twelve-word recovery key or an object carrying it. */
+  readonly recoveryKey: string | { readonly mnemonic: string };
+  /** A fresh salt the client owns; it must equal `order.salt`. Defaults to `order.salt`. */
+  readonly recoverySalt?: string;
+  /** The v1 index; it is mutually exclusive with `recoverySalt`. */
+  readonly recoveryIndex?: number;
+  /** The market's chain and asset, for example `421614:ETH`. Derived when exactly one window matches. */
+  readonly market?: string;
+  readonly xmrNetwork?: string;
+  readonly xmrAmount: string | number;
+  readonly claimTip?: string | number;
+  readonly partner?: string;
+  readonly fetchImpl?: typeof fetch;
+  readonly timeoutMs?: number;
+}
+
+export interface FirmRelayAnswer {
+  readonly quote: Readonly<Record<string, unknown>>;
+  readonly orderQuote: Readonly<Record<string, unknown>>;
+  /** The exact order terms the quote is bound to. */
+  readonly order: Readonly<Record<string, unknown>>;
+  readonly nodeHalf: Readonly<Record<string, unknown>>;
+  /** Ready to pass as `swaps.start({ counterparty })`: proof, claimer commitment and maker view half. */
+  readonly counterparty: Readonly<Record<string, unknown>>;
+  readonly edViewPointLocker: string;
+  readonly edViewPointClaimer: string;
+  readonly context: string;
+  readonly viewHalfClaimer: string;
+  readonly viewHalfPoint: string;
+  /** The one-time Monero address assembled from the recovery key and the answer's points. */
+  readonly jointAddress: string;
+  /** The escrow address predicted from the signed quote and the depositor's half. */
+  readonly escrow: string;
+  readonly recovery: { readonly kind: "salt-v2"; readonly salt: string }
+    | { readonly kind: "index-v1"; readonly index: number };
+  readonly relay: string | null;
+  readonly offered: number | null;
+  readonly forwarded: Readonly<Record<string, unknown>> | null;
+  readonly answer: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -758,6 +812,13 @@ export interface SwapsApi {
    * the swap with if the browser is lost.
    */
   start(request: StartRequest): Promise<SwapStart>;
+  /**
+   * START A SELL from a verified relay offer. It records the one-time address, the escrow, our half and the
+   * order expectations; it sends nothing. The same offer retried yields the same record (`resumed: true`).
+   */
+  startSell(request: SellStartRequest): Promise<SellStart>;
+  /** CLAIM THE ETH on a sell from the record: the half and the expectations are the ones stored by `startSell`. */
+  sellClaim(request: SellClaimRequest, wallet: WalletAdapter): Promise<unknown>;
   /**
    * WAIT FOR THE XMR TO ARRIVE at the order's joint address. The polling uses the same request as the page's
    * (GET /swaps/{id}), the rate and the timeout - from `config.limits` and overridable here.
@@ -774,6 +835,12 @@ export interface SwapsApi {
    * signed, and the decline is written into the record, so every later read of the swap reports the same state.
    */
   watch(request: SwapWatchRequest): Promise<SwapWatch | SwapDeclinedWatch>;
+  /**
+   * WAIT FOR THE NODE'S SIDE ON A SELL. The escrow is the one predicted by `quotes.firmRelay`; the client sends
+   * XMR to the joint address, and this reads the escrow itself until the locker marks it ready, claims it or
+   * refunds it. No backend watcher is involved. A wait that expires is `sell-timeout`.
+   */
+  sellWatch(request: SellWatchRequest): Promise<SellWatchResult>;
   /**
    * THE XMR ARRIVAL CHECK WITHOUT THE WATCH LOOP (issue #85). The client reads the chain itself with its own view
    * key and `ready` opens only when at least two nodes of DIFFERENT operators see the transaction IN THE SAME BLOCK
@@ -1021,6 +1088,53 @@ export interface SwapStart {
   readonly next: "watch";
 }
 
+export interface SellStartRequest {
+  /** The verified `quotes.firmRelay` answer for the bid side. */
+  readonly offer: FirmRelayAnswer;
+  /** The twelve-word key; required only when no key is stored yet. */
+  readonly recoveryKey?: string | { readonly mnemonic: string };
+}
+
+export interface SellStart {
+  readonly id: string;
+  readonly side: "sell";
+  readonly escrow: string;
+  /** The one-time Monero address the client sends XMR to. */
+  readonly address: string;
+  readonly xmrAmount: string;
+  readonly claimTip: string | null;
+  readonly orderQuote: Readonly<Record<string, unknown>> | null;
+  readonly resumed: boolean;
+  readonly next: "send-xmr";
+}
+
+export interface SellClaimRequest {
+  readonly id: string;
+  readonly escrow?: string;
+  readonly halfClaimer?: string;
+  readonly expect?: Readonly<Record<string, unknown>>;
+  readonly onStep?: (step: unknown) => void;
+}
+
+export interface SellWatchRequest {
+  /** The escrow predicted by the relay adapter. */
+  readonly escrow: string;
+  readonly timeoutMs?: number;
+  readonly pollMs?: number;
+}
+
+export interface SellWatchResult {
+  readonly escrow: string;
+  readonly state: "ready" | "claimed" | "refunded";
+  readonly funded: boolean;
+  readonly claimed: boolean;
+  readonly refunded: boolean;
+  /** `null` for a terminal claim/refund: the ready mark is not part of that answer. */
+  readonly ready: boolean | null;
+  readonly balanceWei: string;
+  readonly waitedMs: number;
+}
+
 export interface SwapWatchRequest {
   /** The watch record's identifier at the service (from SwapStart.watch.id). */
   readonly id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -41,6 +41,15 @@
     "check:sale-auth": "node tools/check-sale-auth.mjs",
     "check:backup-confirmation": "node tools/check-backup-confirmation.mjs",
     "check:key-view": "node tools/check-key-view.mjs",
+    "check:relay-view": "node tools/check-relay-view.mjs",
+    "check:relay-terms": "node tools/check-relay-terms.mjs",
+    "check:relay-features": "node tools/check-relay-features.mjs",
+    "check:relay-request": "node tools/check-relay-request.mjs",
+    "check:relay-answer": "node tools/check-relay-answer.mjs",
+    "check:relay-http": "node tools/check-relay-http.mjs",
+    "check:relay-adapter": "node tools/check-relay-adapter.mjs",
+    "check:sell-watch": "node tools/check-sell-watch.mjs",
+    "check:sell-start": "node tools/check-sell-start.mjs",
     "check:arrival-consensus": "node tools/check-arrival-consensus.mjs",
     "check:arrival-real": "node tools/check-arrival-real.mjs",
     "check:order-proof": "node tools/check-order-proof.mjs",
@@ -138,6 +147,9 @@
     "url": "https://github.com/Ninsei-Labs/sdk/issues"
   },
   "dependencies": {
+    "@hpke/chacha20poly1305": "1.8.0",
+    "@hpke/core": "1.9.0",
+    "@hpke/dhkem-x25519": "1.8.0",
     "@noble/curves": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@scure/bip39": "2.4.0",

package/src/index.mjs

@@ -270,6 +270,8 @@ export function createNinsei(options) {
       // A firm quote is stage 2: it is signed with a key and lives in the order protocol, not in a market snapshot.
       // A FIRM QUOTE: accepted only with a confirmed provider signature.
       firm: (request) => quotes.firm(request),
+      // THE RELAY PATH: one recovery key in, signed orderQuote and its maker view half out.
+      firmRelay: (request) => quotes.firmRelay(request),
       // A REVERSE TICKET: the node signs it; its claim tip is checked here before the caller sees it.
       sale: (request) => quotes.sale(request),
     },

package/src/public/recovery.d.ts

@@ -269,6 +269,8 @@ export declare function recoveryFileName(swapId?: string | null): string;
 export declare const RECOVERY_KEY_VERSION: number;
 /** Twelve words, by the BIP39 rules. */
 export declare const RECOVERY_KEY_WORDS: number;
+/** The default number of v1 indices one `findSwaps` call scans. */
+export declare const RECOVERY_SCAN_DEFAULT: number;
 /** The store key a browser adapter keeps the key under. */
 export declare const RECOVERY_KEY_STORE: string;
 /** The first line of a plain backup file. */
@@ -431,8 +433,15 @@ export declare function findSwaps(request: {
   toBlock?: number | string;
   /** Deprecated and ignored: discovery no longer stops after a run of empty numbers. */
   gap?: number;
-  /** The last index to try. Defaults to the allocator's ceiling; a smaller value returns `complete: false`. */
+  /** The first index to try. Defaults to 0; a continuation passes the previous `nextIndex`. */
+  fromIndex?: number;
+  /** How many indices this call may try. Defaults to `RECOVERY_SCAN_DEFAULT` (1000), not the allocator ceiling. */
   maxIndex?: number;
+  /** Stop the scan between chunks. An aborted scan returns `complete: false`, `incompleteReason: "aborted"` and
+   * the `nextIndex` to resume from. */
+  signal?: { readonly aborted: boolean } | null;
+  /** Called after every chunk and after the last index, with the count and the index just scanned. */
+  onProgress?: ((value: { readonly scanned: number; readonly index: number }) => void) | null;
   /** Reads the settlement block timestamp, in seconds: (blockNumber) -> seconds. */
   evmBlockTime?: (blockNumber: number) => Promise<number>;
   /** Reads contract code: (address) -> 0x-hex. Used to read the XMR amount from an order clone. */
@@ -453,8 +462,10 @@ export declare function findSwaps(request: {
   scanned: number;
   /** The last index tried, or null when no index was scanned. */
   searchedUpTo: number | null;
-  /** True only when the whole allocator range was searched. */
+  /** True when every order in the logs was matched, or when the allocator range was searched to its end. */
   complete: boolean;
-  /** `max-index` when a smaller caller-supplied bound stopped the search. */
+  /** `max-index` or `aborted` when a bound or the caller stopped the search before every order was matched. */
   incompleteReason?: string;
+  /** The next index to pass as `fromIndex`; absent when the search is complete. */
+  nextIndex?: number;
 }>;

package/src/public/recovery.mjs

@@ -33,6 +33,7 @@ export {
   RECOVERY_KEY_VERSION,
   MAKER_VIEW_HALF_DOMAIN,
   RECOVERY_KEY_WORDS,
+  RECOVERY_SCAN_DEFAULT,
   commitRecoveryIndex,
   createRecoveryKey,
   createRecoveryKeyFile,

package/src/quotes.mjs

@@ -21,10 +21,13 @@ 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; };
@@ -42,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;
@@ -813,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,
+      };
+    },
   };
 }