@ninsei-labs/sdk 0.53.0 → 0.55.0

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

package/src/record.mjs

@@ -54,6 +54,16 @@ export function createRecord(input, { order = null, side: knownSide = null } = {
     // both the slot check against the chain and the address check read them.
     half: halfHex(side.half), viewHalf: halfHex(side.viewHalf),
     edPointLocker: norm(side.pub.ed), edViewPointLocker: norm(side.viewPub) };
+  // THE XMR AMOUNT THE PROVIDER SIGNED, IN ATOMIC UNITS. The record's `xmrAmount` is a display number rounded
+  // from the quote; the signed order carries the exact integer. The arrival check compares against the signed
+  // figure, so it must survive the record and the recovery file unchanged (never re-derived from the display
+  // number). A malformed value is a refusal before anything is saved.
+  if (input.expectedAtomic !== undefined && input.expectedAtomic !== null) {
+    let atomic;
+    try { atomic = BigInt(String(input.expectedAtomic)); } catch { throw new SdkError("bad-input", { field: "expectedAtomic" }); }
+    if (atomic <= 0n) throw new SdkError("bad-input", { field: "expectedAtomic" });
+    escrow.expectedAtomic = atomic.toString();
+  }
   // THE SIDE'S ENCRYPTION KEY - only the public one: the private one stays with the side and never enters the record.
   if (side.enc && side.enc.pub) escrow.encPub = norm(side.enc.pub);
   const record = { ...swap, escrow };

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,206 @@
+// 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,string[] capabilities,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"],
+  ["capabilities", "string[]"],
+  ["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 (!Array.isArray(features.capabilities) || features.capabilities.length === 0
+    || features.capabilities.length > 16
+    || new Set(features.capabilities).size !== features.capabilities.length
+    || features.capabilities.some((name) => typeof name !== "string" || name === ""
+      || name.length > 32 || !/^[ -~]+$/.test(name))) {
+    throw new SdkError("quote-refused", { step: "features", why: "capabilities" });
+  }
+  const firm = features.capabilities.includes("firm/1");
+  if (firm && (!/^[0-9a-f]{64}$/.test(hpkeKey) || /^0+$/.test(hpkeKey))) {
+    throw new SdkError("quote-refused", { step: "features", why: "hpke-key" });
+  }
+  if (firm && (!Array.isArray(features.firmWindows) || features.firmWindows.length === 0)) {
+    throw new SdkError("quote-refused", { step: "features", why: "windows" });
+  }
+  if (!firm && hpkeKey !== "0".repeat(64)) {
+    throw new SdkError("quote-refused", { step: "features", why: "hpke-key" });
+  }
+  if (!firm && 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;
+}