@ninsei-labs/sdk 0.53.0 → 0.54.0

package/src/recovery-key.mjs

@@ -30,6 +30,13 @@ export const RECOVERY_KEY_WORDS = 12;
 // The allocator's ceiling. Discovery must use the same range: a search that stops earlier can miss an order
 // whose number was skipped by an abandoned start or by a swap on another chain.
 export const RECOVERY_INDEX_MAX = 100000;
+// A DISCOVERY SCAN IS BOUNDED BY DEFAULT. The allocator can reach 100,000, but deriving a secp256k1 point for
+// every number on a phone is not a page-open cost. One thousand indices keeps the common case inside a short
+// call and, more importantly, the result NAMES that it stopped: the caller can continue from `nextIndex`.
+export const RECOVERY_SCAN_DEFAULT = 1000;
+// The scan yields to the event loop between chunks. A page must be able to paint and answer a cancel click even
+// when a caller explicitly asks for a large range; a synchronous loop of 100,000 derivations froze the page.
+export const RECOVERY_SCAN_YIELD_EVERY = 64;
 export const RECOVERY_KEY_STORE = "ninsei.recovery.key.v1";
 export const RECOVERY_KEY_FILE_MAGIC = "NINSEI RECOVERY KEY";
 export const RECOVERY_KEY_DOMAIN = "ninsei-taker-v1";
@@ -650,7 +657,9 @@ async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBloc
  * positions) and merges the answers. Without one, every OrderCreated of the factory is read and matched locally.
  */
 export async function findSwaps({ mnemonic, chainId, factory, address = null, evmLogs,
-  fromBlock = null, deploymentBlock = null, toBlock = "latest", gap = 5, maxIndex = RECOVERY_INDEX_MAX,
+  fromBlock = null, deploymentBlock = null, toBlock = "latest", gap = 5,
+  fromIndex = 0, maxIndex = RECOVERY_SCAN_DEFAULT,
+  signal = null, onProgress = null,
   evmBlockTime = null, evmCode = null, moneroTip = null, moneroBlockTimestamp = null,
   xmrNodes = null, moneroNetwork = null, fetchImpl = globalThis.fetch } = {}) {
   if (typeof factory !== "string" || !ADDRESS_RE.test(factory)) throw bad("factory");
@@ -659,7 +668,10 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
   // numbers are ordinary when a start was abandoned or the key was used on another chain, and stopping there
   // hides a funded order whose log is already in `logs`.
   void gap;
-  const max = Math.min(numberField(maxIndex, "maxIndex") || RECOVERY_INDEX_MAX, RECOVERY_INDEX_MAX);
+  const startIndex = numberField(fromIndex, "fromIndex");
+  if (startIndex < 0 || startIndex >= RECOVERY_INDEX_MAX) throw bad("fromIndex");
+  const asked = numberField(maxIndex, "maxIndex");
+  const max = Math.min(asked, RECOVERY_INDEX_MAX - startIndex);
   // THE CHAIN SAYS WHERE ITS ORDERS CAN START. An explicit fromBlock wins; otherwise the caller can pass the
   // factory's deployment block (the SDK's chain registry exposes it as escrow.deploymentBlock). Zero remains the
   // last resort for a caller that knows the factory existed at genesis.
@@ -733,19 +745,45 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
       byCommit.get(claimer).push({ order, side: "claimer" });
     }
   }
-  const v1Needed = orders.some((order) => !v2Matched.has(orderKey(order)));
+  const v1Keys = orders.filter((order) => !v2Matched.has(orderKey(order))).map(orderKey);
+  const v1Needed = v1Keys.length > 0;
+  const remaining = new Set(v1Keys);
   let scanned = 0;
-  if (v1Needed) {
-    for (let index = 0; index < max; index += 1) {
-      scanned = index + 1;
+  let stoppedBy = null;
+  if (onProgress !== null && typeof onProgress !== "function") throw bad("onProgress");
+  if (v1Needed && signal && signal.aborted === true) stoppedBy = "aborted";
+  if (v1Needed && stoppedBy === null) {
+    for (let offset = 0; offset < max; offset += 1) {
+      const index = startIndex + offset;
+      scanned = offset + 1;
       const commitment = spendCommitmentFromSeed(seed, chain, index);
       const matches = byCommit.get(commitment) || [];
       for (const { order, side } of matches) {
         const key = orderKey(order);
         if (foundKeys.has(key)) continue;
         foundKeys.add(key);
+        remaining.delete(key);
         found.push({ ...order, index, derivation: "index-v1", side });
       }
+      // EVERY MATCHED ORDER ENDS ITS OWN SEARCH. A key with only its own orders in the logs does not pay for
+      // the rest of the bound once the last one is found. A shared factory keeps the unrelated logs, so the
+      // scan continues to the requested bound and reports that it stopped there.
+      const final = remaining.size === 0 || offset === max - 1;
+      if (final || scanned % RECOVERY_SCAN_YIELD_EVERY === 0) {
+        // Progress is advisory: a page callback that throws must not turn a completed scan into a failed one.
+        if (typeof onProgress === "function") {
+          try { onProgress({ scanned, index }); } catch { /* progress is not the result */ }
+        }
+      }
+      // A CALLER CAN CANCEL. The check is after the progress callback, so a worker that aborts from its
+      // progress handler stops at this chunk instead of finishing the requested range.
+      if (signal && signal.aborted === true) { stoppedBy = "aborted"; break; }
+      if (remaining.size === 0) break;
+      // A LARGE CALLER-SUPPLIED BOUND MUST NOT OWN THE MAIN THREAD. The scan yields between chunks so the page
+      // can paint, and a later call can continue from `nextIndex`.
+      if (scanned % RECOVERY_SCAN_YIELD_EVERY === 0) {
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
     }
   }
   // EACH FOUND ORDER CARRIES THE MONERO HEIGHT ITS WITHDRAWAL MAY START FROM. The rule lives here, not in a
@@ -796,15 +834,17 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
     order.xmrAmount = read.value;
     order.xmrAmountReason = read.reason;
   }
-  const complete = !v1Needed || max >= RECOVERY_INDEX_MAX;
+  const searchedUpTo = scanned ? startIndex + scanned - 1 : null;
+  const complete = !v1Needed || remaining.size === 0 || startIndex + scanned >= RECOVERY_INDEX_MAX;
+  const nextIndex = complete ? null : startIndex + scanned;
   return {
     swaps: found,
     scanned,
     // A CALLER MUST NOT READ "NO SWAPS" AS "THE WHOLE RANGE WAS SEARCHED". The allocator ceiling is the only
     // complete range; a smaller caller-supplied bound says where the search stopped. A result made only of v2
     // orders has no range to search and is complete by construction.
-    searchedUpTo: scanned ? scanned - 1 : null,
+    searchedUpTo,
     complete,
-    ...(complete ? {} : { incompleteReason: "max-index" }),
+    ...(complete ? {} : { incompleteReason: stoppedBy || "max-index", nextIndex }),
   };
 }

package/src/relayFeatures.mjs

@@ -0,0 +1,191 @@
+// THE PUBLIC FEATURES A RELAY MAKER SIGNS.
+//
+// A relay price answer carries a `node_features` string signed by the maker's quote key. The client must check
+// that signature before it uses the `hpkeKey`, the registry or the firm windows: an unsigned or substituted key
+// would receive view material for another maker. This module owns the EIP-712 type, the relay domain and the
+// verification; the request builder takes only the verified result.
+//
+// The public object has no contact fields. The relay forwards the exact string it received; this module hashes
+// the decoded values, not a reconstructed subset.
+import { SdkError } from "./errors.mjs";
+import { keccak256, secp256k1 } from "./primitives.mjs";
+
+export const RELAY_FEATURES_TYPE_NAME = "NodeFeatures";
+export const RELAY_DOMAIN_NAME = "Ninsei Relay";
+export const RELAY_DOMAIN_VERSION = "1";
+
+const DOMAIN_TYPE = "EIP712Domain(string name,string version)";
+export const FIRM_WINDOW_TYPE =
+  "FirmWindow(string market,string side,string xmrNetwork,uint32 readyMinSeconds,uint32 readyMaxSeconds,uint32 settlementMinSeconds,uint32 settlementMaxSeconds,uint32 quoteTtlSeconds)";
+export const NODE_FEATURES_TYPE =
+  "NodeFeatures(string relayId,address provider,address quoteKey,address registry,bytes32 hpkeKey,FirmWindow[] firmWindows,uint64 time,bytes32 nonce)" +
+  FIRM_WINDOW_TYPE;
+
+export const FIRM_WINDOW_FIELDS = [
+  ["market", "string"],
+  ["side", "string"],
+  ["xmrNetwork", "string"],
+  ["readyMinSeconds", "uint32"],
+  ["readyMaxSeconds", "uint32"],
+  ["settlementMinSeconds", "uint32"],
+  ["settlementMaxSeconds", "uint32"],
+  ["quoteTtlSeconds", "uint32"],
+];
+export const NODE_FEATURES_FIELDS = [
+  ["relayId", "string"],
+  ["provider", "address"],
+  ["quoteKey", "address"],
+  ["registry", "address"],
+  ["hpkeKey", "bytes32"],
+  ["firmWindows", "FirmWindow[]"],
+  ["time", "uint64"],
+  ["nonce", "bytes32"],
+];
+
+const utf8 = (value) => new TextEncoder().encode(String(value));
+const concat = (...arrays) => {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const array of arrays) { out.set(array, at); at += array.length; }
+  return out;
+};
+const hexBytes = (value, field, width) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!new RegExp("^[0-9a-fA-F]{" + width * 2 + "}$").test(text)) {
+    throw new SdkError("bad-input", { field });
+  }
+  const out = new Uint8Array(width);
+  for (let i = 0; i < width; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+const numberWord = (value, field, bits) => {
+  let n = null;
+  try { n = BigInt(String(value === undefined || value === null ? "" : value).trim()); } catch { n = null; }
+  if (n === null || n < 0n || n >= (1n << BigInt(bits))) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0 && n > 0n; i -= 1) { out[i] = Number(n & 0xffn); n >>= 8n; }
+  return out;
+};
+const addressWord = (value, field) => {
+  const text = String(value === undefined || value === null ? "" : value).trim();
+  if (!/^(0x)?[0-9a-fA-F]{40}$/.test(text)) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(32);
+  out.set(hexBytes(text, field, 20), 12);
+  return out;
+};
+const stringWord = (value) => keccak256(utf8(value === undefined || value === null ? "" : value));
+const arrayWord = (values, field, hashOf) => {
+  if (!Array.isArray(values)) throw new SdkError("bad-input", { field });
+  const parts = values.map((value) => hashOf(value));
+  return keccak256(concat(...parts));
+};
+
+function firmWindowHash(window) {
+  if (!window || typeof window !== "object") throw new SdkError("bad-input", { field: "firmWindows" });
+  const parts = [keccak256(utf8(FIRM_WINDOW_TYPE))];
+  for (const [field, type] of FIRM_WINDOW_FIELDS) {
+    parts.push(type === "string" ? stringWord(window[field]) : numberWord(window[field], "firmWindows." + field, 32));
+  }
+  return keccak256(concat(...parts));
+}
+
+export function nodeFeaturesStructHash(features) {
+  if (!features || typeof features !== "object") throw new SdkError("bad-input", { field: "features" });
+  const parts = [keccak256(utf8(NODE_FEATURES_TYPE))];
+  for (const [field, type] of NODE_FEATURES_FIELDS) {
+    if (type === "string") parts.push(stringWord(features[field]));
+    else if (type === "address") parts.push(addressWord(features[field], "features." + field));
+    else if (type === "bytes32") parts.push(hexBytes(features[field], "features." + field, 32));
+    else if (type === "uint64") parts.push(numberWord(features[field], "features." + field, 64));
+    else if (type === "string[]") parts.push(arrayWord(features[field], "features." + field, (value) => stringWord(value)));
+    else if (type === "FirmWindow[]") parts.push(arrayWord(features[field], "features." + field, firmWindowHash));
+    else throw new SdkError("bad-input", { field: "features." + field });
+  }
+  return keccak256(concat(...parts));
+}
+
+export function nodeFeaturesDomainSeparator() {
+  return keccak256(concat(
+    keccak256(utf8(DOMAIN_TYPE)),
+    keccak256(utf8(RELAY_DOMAIN_NAME)),
+    keccak256(utf8(RELAY_DOMAIN_VERSION)),
+  ));
+}
+
+export function nodeFeaturesDigest(features) {
+  return keccak256(concat(Uint8Array.from([0x19, 0x01]), nodeFeaturesDomainSeparator(), nodeFeaturesStructHash(features)));
+}
+
+const bytesToHex = (bytes) => {
+  let out = "0x";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+
+function recoverAddress(digest, signature) {
+  const sig = String(signature || "").replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]{130}$/.test(sig)) return null;
+  let v = parseInt(sig.slice(128, 130), 16);
+  if (v >= 27) v -= 27;
+  if (v !== 0 && v !== 1) return null;
+  try {
+    const publicKey = secp256k1.Signature.fromBytes(concat(
+      hexBytes(sig.slice(0, 64), "signature", 32),
+      hexBytes(sig.slice(64, 128), "signature", 32),
+    )).addRecoveryBit(v).recoverPublicKey(digest);
+    return bytesToHex(keccak256(publicKey.toBytes(false).slice(1)).slice(12));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verify the signed public features. `terms` optionally binds the features to one request: the provider, the
+ * registry, the market, the side and the Monero network must agree. A zero key, a short key, a missing or empty
+ * window list, or a signature from another key is a refusal.
+ */
+export function verifyNodeFeatures({ features, terms = null } = {}) {
+  if (!features || typeof features !== "object") throw new SdkError("bad-input", { field: "features" });
+  if (features.type !== "node_features" || Number(features.version) !== 1) {
+    throw new SdkError("quote-refused", { step: "features", why: "version" });
+  }
+  const digest = nodeFeaturesDigest(features);
+  const recovered = recoverAddress(digest, features.signature);
+  const quoteKey = String(features.quoteKey || "").toLowerCase();
+  if (recovered === null || recovered !== quoteKey) {
+    throw new SdkError("quote-refused", { step: "features", why: "signature" });
+  }
+  const hpkeKey = String(features.hpkeKey || "").replace(/^0x/, "").toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(hpkeKey) || /^0+$/.test(hpkeKey)) {
+    throw new SdkError("quote-refused", { step: "features", why: "hpke-key" });
+  }
+  if (!Array.isArray(features.firmWindows) || features.firmWindows.length === 0) {
+    throw new SdkError("quote-refused", { step: "features", why: "windows" });
+  }
+  if (terms) {
+    if (String(features.provider || "").toLowerCase() !== String(terms.maker || "").toLowerCase()
+      || String(features.registry || "").toLowerCase() !== String(terms.registry || "").toLowerCase()) {
+      throw new SdkError("quote-refused", { step: "features", why: "identity" });
+    }
+    const market = String(terms.market || "");
+    const side = String(terms.side || "");
+    const network = String(terms.xmrNetwork || "");
+    const window = features.firmWindows.find((entry) => entry
+      && entry.market === market && entry.side === side && entry.xmrNetwork === network);
+    if (!window) throw new SdkError("quote-refused", { step: "features", why: "window" });
+    return { featuresHash: bytesToHex(digest), hpkeKey: "0x" + hpkeKey, window };
+  }
+  return { featuresHash: bytesToHex(digest), hpkeKey: "0x" + hpkeKey, window: null };
+}
+
+// Absent fields are named, not zero-filled.
+export function nodeFeaturesMissingFields(features) {
+  if (!features || typeof features !== "object") return ["features"];
+  const missing = [];
+  for (const [field] of NODE_FEATURES_FIELDS) {
+    const value = features[field];
+    if (value === undefined || value === null || value === "") missing.push(field);
+  }
+  return missing;
+}

package/src/relayFirmClient.mjs

@@ -0,0 +1,86 @@
+// ONE HTTP HOP TO A RELAY FIRM QUOTE.
+//
+// The three crypto layers are already separate: features, request and answer. This module joins them to the
+// wire: it builds the exact payload, sends it once, maps a refusal to a named code and verifies the answer
+// before returning anything a caller could fund. The payload string is never re-serialised.
+import { SdkError } from "./errors.mjs";
+import { createHttp } from "./http.mjs";
+import { buildFirmRequest } from "./relayRequest.mjs";
+import { verifyFirmAnswer } from "./relayQuote.mjs";
+
+const REFUSAL_CODES = new Set([
+  "compliance",
+  "no_liquidity",
+  "size",
+  "paused",
+  "unavailable",
+  "bad_request",
+  "price_changed",
+]);
+const sameRelay = (a, b) => String(a === undefined || a === null ? "" : a) === String(b === undefined || b === null ? "" : b);
+
+/**
+ * Request a firm quote from a relay.
+ *
+ * `relayUrl` is the relay origin (for example `https://relay.example`), `partner` is the optional partner
+ * label and every other option is passed to `buildFirmRequest`. A transport error is
+ * `server-unavailable`; a relay refusal keeps its code in `quote-refused`. A timeout is not retried here:
+ * the salt is part of the signed terms, so a retry needs the caller's decision and a fresh proof.
+ */
+export async function requestFirmQuote({
+  relayUrl,
+  partner = null,
+  fetchImpl = null,
+  timeoutMs = 20_000,
+  ...request
+} = {}) {
+  const base = String(relayUrl === undefined || relayUrl === null ? "" : relayUrl).trim().replace(/\/+$/, "");
+  if (!base) throw new SdkError("bad-input", { field: "relayUrl" });
+
+  const built = await buildFirmRequest(request);
+  const body = JSON.stringify({
+    version: 1,
+    payload: built.payload,
+    ...(partner ? { partner: String(partner) } : {}),
+  });
+
+  const http = createHttp({ apiBase: base, fetchImpl, timeoutMs });
+  const response = await http.tryJson("/v1/quote", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body,
+  });
+
+  if (!response.ok) {
+    const code = response.body && response.body.code ? String(response.body.code) : null;
+    if (code && REFUSAL_CODES.has(code)) {
+      throw new SdkError("quote-refused", { step: "relay", code, status: response.status });
+    }
+    throw new SdkError("server-unavailable", { step: "relay", status: response.status });
+  }
+
+  const answer = response.body && response.body.answer;
+  if (!response.body || Number(response.body.version) !== 1 || !answer) {
+    throw new SdkError("quote-refused", { step: "answer", why: "envelope" });
+  }
+  if (typeof response.body.relay !== "string" || !response.body.relay
+    || !response.body.forwarded || response.body.forwarded.relayId !== response.body.relay) {
+    throw new SdkError("quote-refused", { step: "answer", why: "relay" });
+  }
+  if (!sameRelay(answer.relayId, response.body.relay)) {
+    throw new SdkError("quote-refused", { step: "answer", why: "relay" });
+  }
+
+  const verified = verifyFirmAnswer({
+    answer,
+    features: request.features,
+    request: built,
+  });
+  return {
+    ...verified,
+    relay: response.body.relay ?? null,
+    offered: response.body.offered ?? null,
+    forwarded: response.body.forwarded ?? null,
+    answer,
+  };
+}

package/src/relayQuote.mjs

@@ -0,0 +1,209 @@
+// THE SIGNED ANSWER A RELAY RETURNS.
+//
+// The relay's outer `quote` frame is signed by the maker's quote key in the relay domain. Its `payload` is a
+// JSON string with the factory, the signed `OrderQuote`, the node half and both view points. This module checks
+// both signatures and binds the answer to the request terms before the caller can fund anything.
+import { SdkError } from "./errors.mjs";
+import { keccak256, secp256k1 } from "./primitives.mjs";
+import { recoverOrderQuoteKey } from "./quoteEip712.mjs";
+import * as engine from "./engine.mjs";
+
+export const RELAY_QUOTE_TYPE =
+  "Quote(string relayId,address provider,bytes32 session,bytes32 requestId,uint64 counter,bytes32 requestHash,string payload,uint64 time)";
+
+const DOMAIN_TYPE = "EIP712Domain(string name,string version)";
+const DOMAIN_NAME = "Ninsei Relay";
+const DOMAIN_VERSION = "1";
+
+const utf8 = (value) => new TextEncoder().encode(String(value));
+const concat = (...arrays) => {
+  const total = arrays.reduce((n, a) => n + a.length, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const array of arrays) { out.set(array, at); at += array.length; }
+  return out;
+};
+const hexBytes = (value, field, width) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!new RegExp("^[0-9a-fA-F]{" + width * 2 + "}$").test(text)) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(width);
+  for (let i = 0; i < width; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+const wordAddress = (value, field) => {
+  const out = new Uint8Array(32);
+  out.set(hexBytes(value, field, 20), 12);
+  return out;
+};
+const wordBytes32 = (value, field) => hexBytes(value, field, 32);
+const wordUint = (value, field) => {
+  let n = null;
+  try { n = BigInt(value); } catch { n = null; }
+  if (n === null || n < 0n) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0 && n > 0n; i -= 1) { out[i] = Number(n & 0xffn); n >>= 8n; }
+  return out;
+};
+const wordString = (value) => keccak256(utf8(value === undefined || value === null ? "" : value));
+
+export function relayQuoteStructHash(answer) {
+  if (!answer || typeof answer !== "object") throw new SdkError("bad-input", { field: "answer" });
+  return keccak256(concat(
+    keccak256(utf8(RELAY_QUOTE_TYPE)),
+    wordString(answer.relayId),
+    wordAddress(answer.provider, "answer.provider"),
+    wordBytes32(answer.session, "answer.session"),
+    wordBytes32(answer.requestId, "answer.requestId"),
+    wordUint(answer.counter, "answer.counter"),
+    wordBytes32(answer.requestHash, "answer.requestHash"),
+    wordString(answer.payload),
+    wordUint(answer.time, "answer.time"),
+  ));
+}
+
+export function relayQuoteDomainSeparator() {
+  return keccak256(concat(
+    keccak256(utf8(DOMAIN_TYPE)),
+    keccak256(utf8(DOMAIN_NAME)),
+    keccak256(utf8(DOMAIN_VERSION)),
+  ));
+}
+
+export function relayQuoteDigest(answer) {
+  return keccak256(concat(Uint8Array.from([0x19, 0x01]), relayQuoteDomainSeparator(), relayQuoteStructHash(answer)));
+}
+
+const hex = (bytes) => {
+  let out = "0x";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+function recoverAddress(digest, signature) {
+  const sig = String(signature || "").replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]{130}$/.test(sig)) return null;
+  let v = parseInt(sig.slice(128, 130), 16);
+  if (v >= 27) v -= 27;
+  if (v !== 0 && v !== 1) return null;
+  try {
+    const publicKey = secp256k1.Signature.fromBytes(concat(
+      hexBytes(sig.slice(0, 64), "signature", 32),
+      hexBytes(sig.slice(64, 128), "signature", 32),
+    )).addRecoveryBit(v).recoverPublicKey(digest);
+    return hex(keccak256(publicKey.toBytes(false).slice(1)).slice(12));
+  } catch {
+    return null;
+  }
+}
+
+// The outer frame: signed by the quote key in the relay domain.
+export function verifyRelayQuoteFrame(answer, quoteKey) {
+  if (!answer || typeof answer !== "object" || answer.type !== "quote" || Number(answer.version) !== 1) {
+    throw new SdkError("quote-refused", { step: "answer", why: "frame" });
+  }
+  const recovered = recoverAddress(relayQuoteDigest(answer), answer.signature);
+  if (recovered === null || recovered !== String(quoteKey || "").toLowerCase()) {
+    throw new SdkError("quote-refused", { step: "answer", why: "signature" });
+  }
+  return answer;
+}
+
+const ZERO = "0x" + "00".repeat(20);
+const lower = (value) => String(value === undefined || value === null ? "" : value).toLowerCase();
+const same = (a, b) => lower(a) === lower(b);
+
+function checkOrderQuote(quote, terms, nowSec) {
+  const order = terms.order;
+  if (!quote || typeof quote !== "object") throw new SdkError("quote-refused", { step: "answer", why: "quote" });
+  const pairs = [
+    ["chainId", String(order.chainId)],
+    ["factory", order.factory],
+    ["locker", order.locker],
+    ["claimer", order.claimer],
+    ["amount", String(order.amount)],
+    ["readyBy", String(order.readyBy)],
+    ["t1", String(order.t1)],
+    ["salt", order.salt],
+    ["xmrAmount", String(terms.xmrAmount)],
+    ["claimTip", String(terms.claimTip)],
+    ["provider", terms.maker],
+    ["registry", terms.registry],
+  ];
+  for (const [field, want] of pairs) {
+    if (!same(quote[field], want)) throw new SdkError("quote-refused", { step: "answer", why: "field", field });
+  }
+  if (same(quote.feeRecipient, ZERO)) {
+    throw new SdkError("quote-refused", { step: "answer", why: "fee-recipient" });
+  }
+  const bps = Number(quote.feeBps);
+  let fee = null;
+  let amount = null;
+  try { fee = BigInt(String(quote.fee)); amount = BigInt(String(order.amount)); }
+  catch { throw new SdkError("quote-refused", { step: "answer", why: "fee" }); }
+  if (!Number.isSafeInteger(bps) || bps < 0 || bps > 200) {
+    throw new SdkError("quote-refused", { step: "answer", why: "fee" });
+  }
+  if (fee !== (amount * BigInt(bps)) / 10000n) throw new SdkError("quote-refused", { step: "answer", why: "fee" });
+  const validUntil = Number(quote.validUntil);
+  if (!Number.isSafeInteger(validUntil) || validUntil <= nowSec) {
+    throw new SdkError("quote-expired", { step: "answer", validUntil: quote.validUntil });
+  }
+}
+
+/**
+ * Verify an answer against the request terms and the verified features. `request` is the result of
+ * `buildFirmRequest`: it carries the normalised terms and both view points.
+ */
+export function verifyFirmAnswer({ answer, features, request, now = null } = {}) {
+  if (!request || !request.terms) throw new SdkError("bad-input", { field: "request" });
+  verifyRelayQuoteFrame(answer, features && features.quoteKey);
+  if (!answer.relayId || !same(answer.relayId, features && features.relayId)) {
+    throw new SdkError("quote-refused", { step: "answer", why: "relay" });
+  }
+  let payload = null;
+  try { payload = JSON.parse(answer.payload); } catch { throw new SdkError("quote-refused", { step: "answer", why: "payload" }); }
+  if (!payload || typeof payload !== "object" || !payload.quote) {
+    throw new SdkError("quote-refused", { step: "answer", why: "payload" });
+  }
+  if (payload.contextVersion !== "ninsei-order-v3" || Number(payload.quoteVersion) !== 9) {
+    throw new SdkError("quote-refused", { step: "answer", why: "version" });
+  }
+  if (!same(payload.factory, request.terms.order.factory)) {
+    throw new SdkError("quote-refused", { step: "answer", why: "factory" });
+  }
+  if (!same(answer.provider, request.terms.maker)) {
+    throw new SdkError("quote-refused", { step: "answer", why: "provider" });
+  }
+  const quote = { ...payload.quote, factory: request.terms.order.factory };
+  if (!quote.quoteSignature) quote.quoteSignature = payload.quoteSignature;
+  let context = null;
+  try { context = engine.orderContext.orderContextString(request.terms.order); } catch { context = null; }
+  if (!context || payload.context !== context) throw new SdkError("quote-refused", { step: "context", why: "other-terms" });
+  const recovered = recoverOrderQuoteKey({ ...quote, signature: payload.quoteSignature });
+  if (recovered === null) throw new SdkError("quote-refused", { step: "signature", why: "invalid" });
+  if (!same(recovered, quote.quoteKey)) throw new SdkError("quote-refused", { step: "signature", why: "key" });
+  const nowSec = Math.floor((now === null ? Date.now() : now) / 1000);
+  checkOrderQuote(quote, request.terms, nowSec);
+  const side = request.terms.side;
+  const lockerPoint = side === "ask" ? request.edViewPointClient : request.edViewPointNode;
+  const claimerPoint = side === "ask" ? request.edViewPointNode : request.edViewPointClient;
+  if (!same(payload.edViewPointLocker, lockerPoint) || !same(payload.edViewPointClaimer, claimerPoint)) {
+    throw new SdkError("quote-refused", { step: "answer", why: "view-points" });
+  }
+  const nodeHalf = payload.nodeHalf;
+  if (!nodeHalf || typeof nodeHalf !== "object" || !nodeHalf.proof) {
+    throw new SdkError("quote-refused", { step: "answer", why: "node-half" });
+  }
+  if (side === "ask") {
+    if (!same(nodeHalf.commitHalf, quote.commitHalfClaimer) || !same(nodeHalf.edPoint, quote.edPointClaimer)) {
+      throw new SdkError("quote-refused", { step: "answer", why: "node-half" });
+    }
+  }
+  return {
+    quote,
+    orderQuote: { ...quote, factory: payload.factory, signature: payload.quoteSignature },
+    nodeHalf,
+    edViewPointLocker: payload.edViewPointLocker,
+    edViewPointClaimer: payload.edViewPointClaimer,
+    context,
+  };
+}