@ninsei-labs/sdk 0.52.0 → 0.54.0

package/src/recovery-key.mjs

@@ -27,9 +27,23 @@ const halves = createHalves({ ed25519, secp256k1, keccak256, randomBytes });
 /** A BIP39 mnemonic with 128 bits of entropy: twelve words. */
 export const RECOVERY_KEY_VERSION = 1;
 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";
+// THE SALT-BASED VERSION. A v1 number is the same at every factory and every device; a v2 binding names the fresh
+// order salt, the factory and the role, so two orders cannot share a taker half even when the words are restored
+// elsewhere. The salt is already public in `OrderCreated`; recovery reads it back instead of reserving a number.
+export const RECOVERY_KEY_DOMAIN_V2 = "ninsei-taker-v2";
 // The counterparty's view half is derived from the SAME ONE KEY, in a domain of its own. The taker sends this
 // number to the maker (the node), which uses it as its own view half; the taker keeps it, so the joint view key
 // can be rebuilt from the twelve words without any server.
@@ -40,6 +54,7 @@ export const RECOVERY_KEY_ITER = 600000;
 const ITER_MIN = 600000;
 const ITER_MAX = 6000000;
 
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 const te = new TextEncoder();
 const td = new TextDecoder();
 
@@ -121,8 +136,38 @@ export function recoveryBinding(chainId, index) {
  * package is a hex string, and a BigInt that reaches JSON.stringify fails the whole record.
  */
 export function takerHalves({ mnemonic, chainId, index }) {
-  const binding = recoveryBinding(chainId, index);
-  const seed = seedOf(mnemonic);
+  return takerHalvesFromSeed(seedOf(mnemonic), chainId, index);
+}
+
+// THE SAME KEY, A PUBLIC PER-ORDER SALT. The factory and role are in the binding, so the same words, chain and
+// salt at another factory produce another half. `role` is fixed for the taker's side; the maker's view half is
+// separated by its own domain. Salt is the `salt` word from `OrderCreated`, never a secret.
+export function recoveryBindingV2({ chainId, factory, role = "taker", salt } = {}) {
+  if (typeof factory !== "string" || !ADDRESS_RE.test(factory)) throw bad("factory");
+  if (typeof role !== "string" || !/^[a-z0-9-]{1,32}$/.test(role)) throw bad("role");
+  return `${RECOVERY_KEY_DOMAIN_V2}|${numberField(chainId, "chainId")}|${factory.toLowerCase()}|${role}|${recoverySaltOf(salt)}`;
+}
+
+export function takerHalvesV2({ mnemonic, chainId, factory, role = "taker", salt } = {}) {
+  const normalized = recoverySaltOf(salt);
+  const binding = recoveryBindingV2({ chainId, factory, role, salt: normalized });
+  return {
+    ...halvesFromBinding(seedOf(mnemonic), binding),
+    index: null,
+    derivation: "salt-v2",
+    factory: factory.toLowerCase(),
+    role,
+    salt: normalized,
+  };
+}
+
+// Discovery derives thousands of numbers from one mnemonic. The BIP39 seed is the expensive part (PBKDF2), so it
+// is computed once by the caller and passed here; the per-number work is only HMAC and a curve point.
+function takerHalvesFromSeed(seed, chainId, index) {
+  return { index: numberField(index, "index"), ...halvesFromBinding(seed, recoveryBinding(chainId, index)) };
+}
+
+function halvesFromBinding(seed, binding) {
   const spendHalf = halves.halfFromSeed(seed, binding, halves.HALF_DOMAIN);
   const viewHalf = halves.halfFromSeed(seed, binding, halves.VIEW_HALF_DOMAIN);
   // THE OTHER SIDE'S VIEW HALF. The same key, a third domain: the taker gives this number to the maker, so the
@@ -132,7 +177,6 @@ export function takerHalves({ mnemonic, chainId, index }) {
   const view = halves.publicHalves(viewHalf);
   const makerView = halves.publicHalves(makerViewHalf);
   return {
-    index: numberField(index, "index"),
     binding,
     spendHalf: hex32(spendHalf),
     viewHalf: hex32(viewHalf),
@@ -144,6 +188,41 @@ export function takerHalves({ mnemonic, chainId, index }) {
   };
 }
 
+// DISCOVERY NEEDS ONE COMMITMENT, NOT THREE POINTS. The view and maker-view halves are not compared during a
+// search, and their Edwards points are the expensive part of `takerHalves`; deriving only the spend scalar keeps
+// a full-range scan practical.
+function spendCommitmentFromSeed(seed, chainId, index) {
+  const spendHalf = halves.halfFromSeed(seed, recoveryBinding(chainId, index), halves.HALF_DOMAIN);
+  return halfCommitmentHex(spendHalf, secp256k1, keccak256).toLowerCase();
+}
+
+function spendCommitmentFromSeedV2(seed, { chainId, factory, role = "taker", salt }) {
+  const binding = recoveryBindingV2({ chainId, factory, role, salt });
+  const spendHalf = halves.halfFromSeed(seed, binding, halves.HALF_DOMAIN);
+  return halfCommitmentHex(spendHalf, secp256k1, keccak256).toLowerCase();
+}
+
+// The salt is the 32-byte word from the order, not a secret and not a tag. Lower-case it so the binding is stable
+// across an event decoder and a caller that hand-wrote the value.
+/** A fresh public salt for one v2 order. The client owns it; a maker must not hand the same value back twice. */
+export function newRecoverySalt() {
+  return "0x" + Array.from(randomBytes(32), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export function recoverySaltOf(value) {
+  if (typeof value === "bigint") return saltField("0x" + value.toString(16).padStart(64, "0"));
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+    return saltField("0x" + BigInt(value).toString(16).padStart(64, "0"));
+  }
+  return saltField(value);
+}
+
+function saltField(value) {
+  const salt = String(value == null ? "" : value).trim().toLowerCase();
+  if (!/^0x[0-9a-f]{64}$/.test(salt)) throw bad("salt");
+  return salt;
+}
+
 // ---------------------------------------------------------------------------------------------------
 // THE BACKUP FILE
 // ---------------------------------------------------------------------------------------------------
@@ -274,23 +353,31 @@ export async function openRecoveryKeyFile(contents, passphrase = "") {
 // RESERVATION
 // ---------------------------------------------------------------------------------------------------
 
+const storageFailure = (step) => new SdkError("storage-unavailable", { step });
 const readStore = (storage) => {
   if (!storage || typeof storage.get !== "function" || typeof storage.set !== "function" || typeof storage.remove !== "function") throw bad("storage");
-  const raw = storage.get(RECOVERY_KEY_STORE);
-  if (!raw) return null;
-  try {
-    const value = JSON.parse(raw);
-    if (!value || value.version !== RECOVERY_KEY_VERSION || typeof value.mnemonic !== "string") return null;
-    return value;
-  } catch {
-    return null;
-  }
+  let raw;
+  try { raw = storage.get(RECOVERY_KEY_STORE); } catch { throw storageFailure("read"); }
+  // NOTHING STORED IS NOT AN UNREADABLE STORE. `null`/absent means no key yet; a throwing read or a corrupt
+  // record must be named, because the next start would otherwise overwrite a key it could not read.
+  if (raw === undefined || raw === null || raw === "") return null;
+  let value;
+  try { value = JSON.parse(raw); } catch { throw storageFailure("parse"); }
+  if (!value || value.version !== RECOVERY_KEY_VERSION || typeof value.mnemonic !== "string") throw storageFailure("parse");
+  return value;
+};
+
+const writeStore = (storage, value) => {
+  let text;
+  try { text = JSON.stringify(value); } catch { throw storageFailure("serialize"); }
+  try { storage.set(RECOVERY_KEY_STORE, text); } catch { throw storageFailure("write"); }
 };
 
 /** Save the key next to the swap records. The words are the secret; the store is the caller's. */
 export function saveRecoveryKey(storage, key) {
   const checked = recoveryKeyOf(key && key.mnemonic, key && key.createdAt);
-  storage.set(RECOVERY_KEY_STORE, JSON.stringify({ ...checked, nextIndex: Number(key.nextIndex) || 0, reserved: key.reserved || {}, retired: key.retired || {} }));
+  writeStore(storage, { ...checked, nextIndex: Number(key.nextIndex) || 0,
+    reserved: key.reserved || {}, retired: key.retired || {}, backupConfirmed: key.backupConfirmed === true });
   return checked;
 }
 
@@ -316,13 +403,13 @@ export function reserveRecoveryIndex(storage, { chainId, swapId = null } = {}) {
   for (let i = 0; i < index; i += 1) {
     if (!Object.prototype.hasOwnProperty.call(reserved, i) && !Object.prototype.hasOwnProperty.call(retired, i)) {
       reserved[i] = { chainId: chain, swapId, at: new Date().toISOString() };
-      storage.set(RECOVERY_KEY_STORE, JSON.stringify({ ...key, reserved, retired }));
+      writeStore(storage, { ...key, reserved, retired });
       return i;
     }
   }
-  if (index >= 100000) throw failed("index-exhausted");
+  if (index >= RECOVERY_INDEX_MAX) throw failed("index-exhausted");
   reserved[index] = { chainId: chain, swapId, at: new Date().toISOString() };
-  storage.set(RECOVERY_KEY_STORE, JSON.stringify({ ...key, nextIndex: index + 1, reserved, retired }));
+  writeStore(storage, { ...key, nextIndex: index + 1, reserved, retired });
   return index;
 }
 
@@ -331,7 +418,7 @@ export function releaseRecoveryIndex(storage, index) {
   if (!key) throw failed("key-missing");
   const reserved = { ...(key.reserved || {}) };
   delete reserved[String(numberField(index, "index"))];
-  storage.set(RECOVERY_KEY_STORE, JSON.stringify({ ...key, reserved }));
+  writeStore(storage, { ...key, reserved });
 }
 
 /** Retire a number after its order exists on chain: it is never reused, so a later scan has no collision. */
@@ -343,15 +430,13 @@ export function commitRecoveryIndex(storage, index) {
   const n = numberField(index, "index");
   delete reserved[String(n)];
   retired[String(n)] = true;
-  storage.set(RECOVERY_KEY_STORE, JSON.stringify({ ...key, reserved, retired }));
+  writeStore(storage, { ...key, reserved, retired });
 }
 
 // ---------------------------------------------------------------------------------------------------
 // THE SEARCH
 // ---------------------------------------------------------------------------------------------------
 
-const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-
 function topicAddress(address) {
   if (typeof address !== "string" || !ADDRESS_RE.test(address)) throw bad("address");
   return pad32(address);
@@ -543,7 +628,13 @@ async function recoveredStartHeight(order, { evmBlockTime, moneroTip, moneroBloc
   // timestamp is already needed here for the Monero height, so it is returned with it.
   let timestamp = cache.get(order.blockNumber);
   if (timestamp === undefined) {
-    timestamp = typeof evmBlockTime === "function" ? secondsOf(await evmBlockTime(order.blockNumber)) : null;
+    // ONE UNREADABLE BLOCK TIME MUST NOT THROW AWAY THE ORDERS ALREADY MATCHED. The order is still a fact from
+    // its log; only the start height is unknown, and the reason says which read failed.
+    try {
+      timestamp = typeof evmBlockTime === "function" ? secondsOf(await evmBlockTime(order.blockNumber)) : null;
+    } catch {
+      return { startHeight: null, startHeightReason: "block-time-read", blockTime: null };
+    }
     if (timestamp === null) return { startHeight: null, startHeightReason: "no-block-time", blockTime: null };
     cache.set(order.blockNumber, timestamp);
   }
@@ -566,13 +657,21 @@ 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 = 1000,
+  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");
   const chain = numberField(chainId, "chainId");
-  const max = numberField(maxIndex, "maxIndex") || 1000;
-  const missesAllowed = numberField(gap, "gap") || 5;
+  // `gap` is retained in the signature for callers of the old API, but it is deliberately NOT used: five empty
+  // 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 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.
@@ -601,23 +700,90 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
     logs = await readLogs(evmLogs, { ...base, topics: [ORDER_CREATED_TOPICS] });
   }
   const orders = logs.map(decodeOrderLog).filter(Boolean);
+  for (const order of orders) order.factory = factory;
+  const orderKey = (order) => `${order.transactionHash || ""}:${order.logIndex ?? ""}`;
+  const seed = seedOf(mnemonic);
   const found = [];
-  let misses = 0;
-  let scanned = 0;
-  for (let index = 0; index < max && misses < missesAllowed; index += 1) {
-    scanned = index + 1;
-    const own = takerHalves({ mnemonic, chainId: chain, index });
-    const matches = orders.filter((order) =>
-      order.commitHalfLocker.toLowerCase() === own.spendCommitment.toLowerCase() ||
-      order.commitHalfClaimer.toLowerCase() === own.spendCommitment.toLowerCase()
-    );
-    if (matches.length === 0) {
-      misses += 1;
+  const foundKeys = new Set();
+  const v2Matched = new Set();
+
+  // A V2 ORDER IS FOUND FROM ITS OWN SALT. No index is reserved and no range is scanned: the binding names the
+  // factory, the role and the public `OrderCreated` salt, so the same words on another device or at another
+  // factory produce a different half. The v2 pass runs first; v1 orders are left for the index scan below.
+  for (const order of orders) {
+    let commitment;
+    try {
+      commitment = spendCommitmentFromSeedV2(seed, { chainId: chain, factory, role: "taker", salt: order.salt });
+    } catch {
       continue;
     }
-    misses = 0;
-    for (const order of matches) {
-      found.push({ ...order, index, side: order.commitHalfLocker.toLowerCase() === own.spendCommitment.toLowerCase() ? "locker" : "claimer" });
+    const locker = order.commitHalfLocker.toLowerCase();
+    const claimer = order.commitHalfClaimer.toLowerCase();
+    const side = commitment === locker ? "locker" : commitment === claimer ? "claimer" : null;
+    if (!side) continue;
+    const key = orderKey(order);
+    if (foundKeys.has(key)) continue;
+    foundKeys.add(key);
+    v2Matched.add(key);
+    found.push({ ...order, index: null, derivation: "salt-v2", side });
+  }
+
+  // MATCH V1 BY COMMITMENT, NOT BY A DENSE INDEX RANGE. The logs are already in hand; the only cost of a missing
+  // index is one derivation. Building the map first also keeps each order from being compared against every
+  // index.
+  const byCommit = new Map();
+  for (const order of orders) {
+    if (v2Matched.has(orderKey(order))) continue;
+    const locker = order.commitHalfLocker.toLowerCase();
+    const claimer = order.commitHalfClaimer.toLowerCase();
+    if (locker) {
+      if (!byCommit.has(locker)) byCommit.set(locker, []);
+      byCommit.get(locker).push({ order, side: "locker" });
+    }
+    if (claimer && claimer !== locker) {
+      if (!byCommit.has(claimer)) byCommit.set(claimer, []);
+      byCommit.get(claimer).push({ order, side: "claimer" });
+    }
+  }
+  const v1Keys = orders.filter((order) => !v2Matched.has(orderKey(order))).map(orderKey);
+  const v1Needed = v1Keys.length > 0;
+  const remaining = new Set(v1Keys);
+  let scanned = 0;
+  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
@@ -668,5 +834,17 @@ export async function findSwaps({ mnemonic, chainId, factory, address = null, ev
     order.xmrAmount = read.value;
     order.xmrAmountReason = read.reason;
   }
-  return { swaps: found, scanned };
+  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,
+    complete,
+    ...(complete ? {} : { incompleteReason: stoppedBy || "max-index", nextIndex }),
+  };
 }

package/src/recovery.mjs

@@ -23,9 +23,17 @@ export function createRecovery({ http = null, config = null } = {}) {
     async open(file, passphrase) {
       const contents = contentsOf(file);
       if (contents === null) throw new SdkError("bad-input", { field: "file" });
+      // THE ENVELOPE IS PARSED AT THE BOUNDARY: `restoreFromFile` takes the OBJECT, while the file arrives as text.
+      // A text passed through reached the parser as a string and every valid file failed as `stage: restore`.
+      let envelope;
+      try {
+        envelope = JSON.parse(contents);
+      } catch {
+        throw new SdkError("recovery-failed", { stage: "parse" });
+      }
       let restored;
       try {
-        restored = await engine.restore.restoreFromFile(contents, passphrase);
+        restored = await engine.restore.restoreFromFile(envelope, passphrase);
       } catch (error) {
         // Parsing, decryption and the address check live in the engine; a code goes out, not the engine's wording.
         throw new SdkError("recovery-failed", { stage: "restore" });

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