@ninsei-labs/sdk 0.53.0 → 0.55.0

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

package/src/relayRequest.mjs

@@ -0,0 +1,188 @@
+// ONE FIRM REQUEST: THE TERMS, THE CLIENT HALF AND THE ENCRYPTED VIEW MATERIAL.
+//
+// The relay signs the payload as the exact UTF-8 string it forwards, so this module serialises it once. Every
+// field that the node or the relay checks is taken from the caller's terms or from the signed features; nothing
+// is filled in from a second source.
+//
+// The builder does not create the client half: the caller has already built one order side and proved it in
+// this context. It normalises the proof's spellings and refuses a half whose point is not the one in its proof.
+import { SdkError } from "./errors.mjs";
+import { ed25519, keccak256 } from "./primitives.mjs";
+import { verifyNodeFeatures } from "./relayFeatures.mjs";
+import { relayViewInfo, sealViewEnvelope } from "./relayView.mjs";
+import { firmTermsDigest, firmTermsMissingFields } from "./relayTerms.mjs";
+
+const hexToBytes = (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 hex = (bytes) => {
+  let out = "0x";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+const normHex = (value, width, field) => hex(hexToBytes(value, field, width));
+const scalar = (value, field) => {
+  let n = null;
+  try { n = BigInt(value); } catch { n = null; }
+  if (n === null || n <= 0n || n >= ed25519.Point.Fn.ORDER) throw new SdkError("bad-input", { field });
+  return n;
+};
+const scalarBytes = (value, field) => {
+  let n = scalar(value, 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 pointOf = (value, field) => hex(ed25519.Point.BASE.multiply(scalar(value, field)).toBytes());
+const assertPoint = (value, field) => {
+  const bytes = hexToBytes(value, field, 32);
+  try { ed25519.Point.fromHex(hex(bytes).slice(2)); } catch { throw new SdkError("bad-input", { field }); }
+  return hex(bytes);
+};
+
+const PROOF_FIELDS = ["XA", "XB", "proofs"];
+function normaliseProof(proof) {
+  if (!proof || typeof proof !== "object") throw new SdkError("bad-input", { field: "clientHalf.proof" });
+  for (const field of PROOF_FIELDS) {
+    if (proof[field] === undefined || proof[field] === null || proof[field] === "") {
+      throw new SdkError("bad-input", { field: "clientHalf.proof." + field });
+    }
+  }
+  if (!Array.isArray(proof.proofs) || proof.proofs.length !== 253) {
+    throw new SdkError("bad-input", { field: "clientHalf.proof.proofs" });
+  }
+  const xa = normHex(proof.XA, 33, "clientHalf.proof.XA");
+  const xb = normHex(proof.XB, 32, "clientHalf.proof.XB");
+  const proofs = proof.proofs.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || !entry.sig) {
+      throw new SdkError("bad-input", { field: "clientHalf.proof.proofs." + index });
+    }
+    const sig = {};
+    for (const field of ["eA", "eB", "a0", "a1", "b0", "b1"]) {
+      sig[field] = normHex(entry.sig[field], 32, "clientHalf.proof.proofs." + index + ".sig." + field);
+    }
+    return {
+      cA: normHex(entry.cA, 33, "clientHalf.proof.proofs." + index + ".cA"),
+      cB: normHex(entry.cB, 32, "clientHalf.proof.proofs." + index + ".cB"),
+      sig,
+    };
+  });
+  return { XA: xa, XB: xb, proofs };
+}
+
+/**
+ * Build the exact request payload.
+ *
+ * `features` is the signed public object the relay forwarded; `terms` is the client's request terms (its
+ * `featuresHash` may be omitted and is filled from the verified features). `clientHalf` is
+ * `{commitHalf, edPoint, proof}`; `nodeViewScalar` and `clientViewScalar` are the two view halves the client
+ * chose. On ask only the node scalar is sent; on bid both.
+ */
+export async function buildFirmRequest({
+  features, terms, clientHalf, edViewPointClient, edViewPointNode,
+  nodeViewScalar, clientViewScalar = null, side = null,
+} = {}) {
+  const verdict = verifyNodeFeatures({ features, terms });
+  const requestSide = String(side || terms?.side || "");
+  if (requestSide !== "ask" && requestSide !== "bid") throw new SdkError("bad-input", { field: "side" });
+  if (terms?.side !== undefined && terms.side !== requestSide) throw new SdkError("bad-input", { field: "terms.side" });
+  if (!terms || typeof terms !== "object" || !terms.order || typeof terms.order !== "object") {
+    throw new SdkError("bad-input", { field: "terms" });
+  }
+  if (terms.featuresHash !== undefined && terms.featuresHash !== null && terms.featuresHash !== ""
+    && String(terms.featuresHash).toLowerCase() !== verdict.featuresHash) {
+    throw new SdkError("quote-refused", { step: "features", why: "hash" });
+  }
+  const order = terms.order;
+  const orderFields = ["chainId", "factory", "locker", "claimer", "amount", "readyBy", "t1", "salt"];
+  for (const field of orderFields) {
+    if (order[field] === undefined || order[field] === null || order[field] === "") {
+      throw new SdkError("bad-input", { field: "terms.order." + field });
+    }
+  }
+  if (String(order.chainId) !== String(terms.market || "").split(":")[0]) {
+    throw new SdkError("bad-input", { field: "terms.market" });
+  }
+  const half = clientHalf || {};
+  const commitHalf = normHex(half.commitHalf, 32, "clientHalf.commitHalf");
+  const point = normHex(half.edPoint, 32, "clientHalf.edPoint");
+  const proof = normaliseProof(half.proof);
+  if (proof.XB !== point) throw new SdkError("bad-input", { field: "clientHalf.edPoint" });
+  const maker = normHex(terms.maker, 20, "terms.maker");
+  const locker = normHex(order.locker, 20, "terms.order.locker");
+  const claimer = normHex(order.claimer, 20, "terms.order.claimer");
+  if (locker === claimer) throw new SdkError("bad-input", { field: "terms.order.roles" });
+  if (requestSide === "ask") {
+    if (claimer !== maker) throw new SdkError("bad-input", { field: "terms.order.claimer" });
+    if (String(terms.claimTip) !== "0") throw new SdkError("bad-input", { field: "terms.claimTip" });
+  } else if (locker !== maker) {
+    throw new SdkError("bad-input", { field: "terms.order.locker" });
+  }
+  const clientViewPoint = assertPoint(edViewPointClient, "edViewPointClient");
+  const nodeViewPoint = assertPoint(edViewPointNode, "edViewPointNode");
+  const nodeScalar = scalarBytes(nodeViewScalar, "nodeViewScalar");
+  if (pointOf(nodeViewScalar, "nodeViewScalar").toLowerCase() !== nodeViewPoint.toLowerCase()) {
+    throw new SdkError("bad-input", { field: "edViewPointNode" });
+  }
+  let clientScalar = null;
+  if (requestSide === "bid") {
+    clientScalar = scalarBytes(clientViewScalar, "clientViewScalar");
+    if (pointOf(clientViewScalar, "clientViewScalar").toLowerCase() !== clientViewPoint.toLowerCase()) {
+      throw new SdkError("bad-input", { field: "edViewPointClient" });
+    }
+  }
+  const requestTerms = {
+    market: String(terms.market),
+    side: requestSide,
+    maker: normHex(terms.maker, 20, "terms.maker"),
+    registry: normHex(terms.registry, 20, "terms.registry"),
+    featuresHash: verdict.featuresHash,
+    xmrNetwork: String(terms.xmrNetwork),
+    order: {
+      chainId: String(order.chainId),
+      factory: normHex(order.factory, 20, "terms.order.factory"),
+      locker: normHex(order.locker, 20, "terms.order.locker"),
+      claimer: normHex(order.claimer, 20, "terms.order.claimer"),
+      amount: String(order.amount),
+      readyBy: Number(order.readyBy),
+      t1: Number(order.t1),
+      salt: normHex(order.salt, 32, "terms.order.salt"),
+    },
+    xmrAmount: String(terms.xmrAmount),
+    claimTip: String(terms.claimTip),
+  };
+  const missing = firmTermsMissingFields(requestTerms);
+  if (missing.length) throw new SdkError("bad-input", { field: "terms", missing });
+  const termsDigest = hex(firmTermsDigest({ crypto: { keccak256 }, terms: requestTerms }));
+  const info = relayViewInfo({
+    termsDigest,
+    commitHalf,
+    edPoint: point,
+    edViewPointClient: clientViewPoint,
+    edViewPointNode: nodeViewPoint,
+  });
+  const plaintext = new Uint8Array(requestSide === "ask" ? 32 : 64);
+  plaintext.set(nodeScalar, 0);
+  if (requestSide === "bid") plaintext.set(clientScalar, 32);
+  const viewEnvelope = await sealViewEnvelope({ hpkeKey: verdict.hpkeKey, info, plaintext });
+  const payload = JSON.stringify({
+    terms: requestTerms,
+    clientHalf: { commitHalf, edPoint: point, proof },
+    edViewPointClient: clientViewPoint,
+    edViewPointNode: nodeViewPoint,
+    viewEnvelope,
+  });
+  return {
+    payload,
+    terms: requestTerms,
+    viewEnvelope,
+    edViewPointClient: clientViewPoint,
+    edViewPointNode: nodeViewPoint,
+  };
+}

package/src/relayTerms.mjs

@@ -0,0 +1,145 @@
+// THE EIP-712 TERMS A RELAY FIRM REQUEST SIGNS.
+//
+// The relay forwards the client's exact payload as a string and signs its UTF-8 bytes. The same terms are
+// also the HPKE context: `relayViewInfo` takes this digest, so a ciphertext is bound to the amounts, roles,
+// deadlines and salt in the request rather than to a separately supplied label.
+//
+// The domain is the relay domain, not the factory domain: `{name: "Ninsei Relay", version: "1"}` has no
+// chainId and no verifyingContract. The inner `OrderQuote` keeps its own factory domain; the two signatures
+// are deliberately separate.
+//
+// The type strings and field order are wire format. A rearrangement produces another digest, and the node
+// refuses the request before it decrypts anything.
+import { SdkError } from "./errors.mjs";
+
+export const FIRM_DOMAIN_NAME = "Ninsei Relay";
+export const FIRM_DOMAIN_VERSION = "1";
+const DOMAIN_TYPE_PARTS = ["EIP712Domain(", "string name,", "string version)"];
+export const FIRM_DOMAIN_TYPE = DOMAIN_TYPE_PARTS.join("");
+
+export const FIRM_ORDER_FIELDS = [
+  ["chainId", "uint256"],
+  ["factory", "address"],
+  ["locker", "address"],
+  ["claimer", "address"],
+  ["amount", "uint256"],
+  ["readyBy", "uint64"],
+  ["t1", "uint64"],
+  ["salt", "bytes32"],
+];
+export const FIRM_ORDER_TYPE = "FirmOrder(" + FIRM_ORDER_FIELDS.map(([name, type]) => type + " " + name).join(",") + ")";
+
+export const FIRM_TERMS_FIELDS = [
+  ["market", "string"],
+  ["side", "string"],
+  ["maker", "address"],
+  ["registry", "address"],
+  ["featuresHash", "bytes32"],
+  ["xmrNetwork", "string"],
+  ["order", "FirmOrder"],
+  ["xmrAmount", "uint256"],
+  ["claimTip", "uint256"],
+];
+// EIP-712 appends every referenced struct type to the primary type, sorted by name. `FirmOrder` is the only
+// one, so the type hash covers both strings.
+export const FIRM_TERMS_TYPE = "FirmTerms(" + FIRM_TERMS_FIELDS.map(([name, type]) => type + " " + name).join(",") + ")" + FIRM_ORDER_TYPE;
+
+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 hexToBytes = (value, field) => {
+  const text = String(value === undefined || value === null ? "" : value).replace(/^0x/, "");
+  if (!/^[0-9a-fA-F]*$/.test(text) || text.length % 2) throw new SdkError("bad-input", { field });
+  const out = new Uint8Array(text.length / 2);
+  for (let i = 0; i < out.length; i += 1) out[i] = parseInt(text.slice(i * 2, i * 2 + 2), 16);
+  return out;
+};
+const number = (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 address = (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(hexToBytes(text.replace(/^0x/, ""), field), 12);
+  return out;
+};
+const bytes32 = (value, field) => {
+  const bytes = hexToBytes(value, field);
+  if (bytes.length !== 32) throw new SdkError("bad-input", { field });
+  return bytes;
+};
+
+const encodeField = (crypto, type, value, field) => {
+  if (type === "string") return crypto.keccak256(utf8(value === undefined || value === null ? "" : value));
+  if (type === "address") return address(value, field);
+  if (type === "bytes32") return bytes32(value, field);
+  if (type === "uint64") return number(value, field, 64);
+  if (type === "uint256") return number(value, field, 256);
+  throw new SdkError("bad-input", { field });
+};
+
+const structHash = (crypto, typeString, fields, value, prefix) => {
+  const parts = [crypto.keccak256(utf8(typeString))];
+  for (const [field, type] of fields) {
+    if (type === "FirmOrder") {
+      const order = value && value.order;
+      if (!order || typeof order !== "object") throw new SdkError("bad-input", { field: prefix + ".order" });
+      parts.push(firmOrderHash(crypto, order));
+    } else {
+      parts.push(encodeField(crypto, type, value ? value[field] : undefined, prefix + "." + field));
+    }
+  }
+  return crypto.keccak256(concat(...parts));
+};
+
+export function firmOrderHash(crypto, order) {
+  return structHash(crypto, FIRM_ORDER_TYPE, FIRM_ORDER_FIELDS, order, "terms.order");
+}
+
+export function firmTermsDomainSeparator(crypto) {
+  return crypto.keccak256(concat(
+    crypto.keccak256(utf8(FIRM_DOMAIN_TYPE)),
+    crypto.keccak256(utf8(FIRM_DOMAIN_NAME)),
+    crypto.keccak256(utf8(FIRM_DOMAIN_VERSION)),
+  ));
+}
+
+export function firmTermsStructHash({ crypto, terms } = {}) {
+  if (!crypto || typeof crypto.keccak256 !== "function") throw new SdkError("bad-input", { field: "crypto" });
+  return structHash(crypto, FIRM_TERMS_TYPE, FIRM_TERMS_FIELDS, terms, "terms");
+}
+
+export function firmTermsDigest({ crypto, terms } = {}) {
+  if (!crypto || typeof crypto.keccak256 !== "function") throw new SdkError("bad-input", { field: "crypto" });
+  return crypto.keccak256(concat(Uint8Array.from([0x19, 0x01]), firmTermsDomainSeparator(crypto), firmTermsStructHash({ crypto, terms })));
+}
+
+// Absent fields are named, not treated as zero. The relay client builds a request only from a complete set.
+export function firmTermsMissingFields(terms) {
+  const missing = [];
+  if (!terms || typeof terms !== "object") return ["terms"];
+  for (const [name] of FIRM_TERMS_FIELDS) {
+    if (name === "order") {
+      if (!terms.order || typeof terms.order !== "object") missing.push("order");
+      else for (const [field] of FIRM_ORDER_FIELDS) {
+        const value = terms.order[field];
+        if (value === undefined || value === null || value === "") missing.push("order." + field);
+      }
+    } else {
+      const value = terms[name];
+      if (value === undefined || value === null || value === "") missing.push(name);
+    }
+  }
+  return missing;
+}