@ninsei-labs/sdk 0.39.0

package/src/quotes.mjs

@@ -0,0 +1,465 @@
+// LIVE INDICATIVE QUOTES: the SDK's own quote client.
+//
+// WHY OUR OWN AND NOT THE ENGINE'S. The package must work without `www/js`: the consumer does not have it. The
+// rules for reading the quote book are a specification (docs 41 and 54), not foreign code, so they are embodied
+// here anew and pinned by a run on fixtures next to the engine implementation. For now the demo screen computes
+// with its own copy: it is a test bench, and it is not scary for it to diverge from the SDK - the bench exists
+// precisely to notice that.
+//
+// WHAT MUST NOT BE LOST HERE (all three rules cost the project mistakes):
+//   1) a row has TWO rates: rateQuote - as written in the pair, rate - how much non-XMR per 1 XMR. This is not
+//      duplication but different orientations; zero means "no direction", and it is NEVER divided and never
+//      becomes a price;
+//   2) the size is requested in the units of the pair's ASSET (the first element): for a buy that is XMR, for a
+//      sell - the token; a size outside the provider's grid is not accepted, so the size is snapped to the grid
+//      DOWN, not to the nearest;
+//   3) a quote older than its own ttlMs is not shown, and a row that contradicts itself (the named sides disagree
+//      with the pair's name) is not read at all.
+import { fail } from "./errors.mjs";
+import * as engine from "./engine.mjs";
+import { orderQuoteMissingFields, recoverOrderQuoteKey } from "./quoteEip712.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";
+
+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; };
+const providerOfSelector = () => bytesToHexQ(keccak256(utf8("providerOf(address)")).slice(0, 4));
+const providerOfData = (key) => providerOfSelector() + "0".repeat(24) + String(key).toLowerCase().replace(/^0x/, "");
+// THE FACTORY IS READ FROM THE RECORD, NOT FROM SETTINGS: `factoryOf(provider)` answers the factory the
+// provider named in its record (#103). Selected by a COMPUTED selector, like providerOf.
+const factoryOfSelector = () => bytesToHexQ(keccak256(utf8("factoryOf(address)")).slice(0, 4));
+const factoryOfData = (provider) => factoryOfSelector() + "0".repeat(24) + String(provider).toLowerCase().replace(/^0x/, "");
+const hexToBytesQ = (hex) => {
+  const h = String(hex == null ? "" : hex).replace(/^0x/, "");
+  if (h.length % 2) return null;
+  const out = new Uint8Array(h.length / 2);
+  for (let i = 0; i < out.length; i++) { const b = parseInt(h.slice(i * 2, i * 2 + 2), 16); if (Number.isNaN(b)) return null; out[i] = b; }
+  return out;
+};
+const ZERO_ADDRESS = "0x" + "00".repeat(20);
+const addressFromWord = (raw) => {
+  const h = String(raw == null ? "" : raw).replace(/^0x/, "");
+  return h.length >= 40 ? "0x" + h.slice(-40).toLowerCase() : null;
+};
+
+const num = (v) => (v === undefined || v === null || v === "" ? null : (Number.isFinite(Number(v)) ? Number(v) : null));
+const pairAsset = (pair) => String(pair || "").split("/")[0].toUpperCase();
+const pairCurrency = (pair) => String(pair || "").split("/")[1] ? String(pair).split("/")[1].toUpperCase() : "";
+
+/** The pair the user sees: buying XMR - looking at XMR/<token>, selling - at the reverse. */
+export const pairFacingUser = (direction, token) =>
+  (direction === "sell" ? String(token).toUpperCase() + "/XMR" : "XMR/" + String(token).toUpperCase());
+
+/** Reading one quote row. The shape comes from the specification; networks are NOT filled in. */
+export function readQuote(pair, raw, owner = {}, data = {}) {
+  const q = raw && typeof raw === "object" ? raw : {};
+  const text = String(pair || q.pair || "").trim().toUpperCase();
+  if (!text.includes("/")) return null;
+  const statedAsset = q.asset ? String(q.asset).toUpperCase() : null;
+  const statedCurrency = q.currency ? String(q.currency).toUpperCase() : null;
+  const asset = pairAsset(text);
+  const currency = pairCurrency(text);
+  const givenRateQuote = num(q.rateQuote);
+  const givenRate = num(q.rate);
+  const rateQuote = givenRateQuote !== null ? givenRateQuote : givenRate;
+  let rate = null;
+  if (givenRateQuote !== null) rate = givenRate;
+  else if (rateQuote !== null) rate = currency === "XMR" ? (rateQuote > 0 ? 1 / rateQuote : null) : rateQuote;
+  const contradicts = (statedAsset && statedAsset !== asset) || (statedCurrency && statedCurrency !== currency);
+  const at = num(q.at);
+  return {
+    providerId: String(owner.providerId || q.providerId || "").trim(),
+    displayName: owner.displayName || q.displayName || null,
+    // THE PROVIDER'S MATURITY LEVEL RIDES WITH THE OFFER: a person chooses not only by price but also by how long
+    // to wait. No field - no value either, not an invented default.
+    finality: owner.finality || q.finality || null,
+    pair: text,
+    asset: statedAsset || asset,
+    currency: statedCurrency || currency,
+    assetNetwork: q.assetNetwork ? String(q.assetNetwork) : null,
+    currencyNetwork: q.currencyNetwork ? String(q.currencyNetwork) : null,
+    rateQuote,
+    rate,
+    min: num(q.min),
+    max: num(q.max),
+    step: num(q.step),
+    ttlMs: num(q.ttlMs) && num(q.ttlMs) > 0 ? num(q.ttlMs) : null,
+    at,
+    why: q.why ? String(q.why) : null,
+    disabled: q.disabled === true || (givenRate !== null && !(givenRate > 0)),
+    // NETWORKS NOT NAMED / FILLED IN BY THE RECEIVER - this is a FACT ABOUT THE QUOTE, and it is visible apart
+    // from "named and matched": the screen must say "nothing to check against" rather than attribute our network
+    // to the quote.
+    networksUnnamed: q.networksUnnamed === true,
+    networksDerived: q.networksDerived === true,
+    seq: num(q.seq) !== null ? num(q.seq) : (num(owner.seq) !== null ? num(owner.seq) : num(data.seq)),
+    signature: q.signature || owner.signature || null,
+    keyId: q.keyId || null,
+    networkStated: Boolean(q.assetNetwork || q.currencyNetwork),
+    contradicts,
+    ageMs: at === null ? null : Math.max(0, Date.now() - at),
+  };
+}
+
+/**
+ * Parsing the book in one place. The envelope is accepted in three forms (a map by pairs, a list of rows, a list
+ * of providers) and is brought to a single list: the screen must not know which form the answer came in.
+ * Refusals are named separately from offers: "no direction" and "the quote is stale" are not emptiness.
+ */
+export function readBook(data, now = Date.now()) {
+  const quotes = data && data.quotes;
+  const rows = [];
+  const add = (pair, raw, owner) => { const row = readQuote(pair, raw, owner, data || {}); if (row) rows.push(row); };
+  if (Array.isArray(quotes)) {
+    for (const row of quotes) {
+      if (!row || typeof row !== "object") continue;
+      const nested = row.quotes && !Array.isArray(row.quotes) && typeof row.quotes === "object" ? row.quotes : null;
+      if (nested) for (const [pair, q] of Object.entries(nested)) add(pair, q, row);
+      else add(row.pair, row, row);
+    }
+  } else if (quotes && typeof quotes === "object") {
+    for (const [pair, q] of Object.entries(quotes)) add(pair, q, q && typeof q === "object" ? q : {});
+  }
+  // ONE QUOTE PER PAIR PER PROVIDER: if several arrived, we keep the fresh one rather than choosing arbitrarily
+  // (these are two different offers under one name).
+  const byKey = new Map();
+  for (const row of rows) {
+    const key = (row.providerId || "?") + "|" + row.pair;
+    const prev = byKey.get(key);
+    if (!prev || Number(row.at) > Number(prev.at)) byKey.set(key, row);
+  }
+  const offers = [];
+  const refused = [];
+  for (const row of byKey.values()) {
+    if (row.contradicts) { refused.push({ ...row, code: "malformed" }); continue; }
+    if (row.rateQuote === null && row.rate === null) { refused.push({ ...row, code: "malformed" }); continue; }
+    if (row.disabled || !(row.rate > 0)) { refused.push({ ...row, code: "disabled" }); continue; }
+    if (row.ttlMs && row.ageMs !== null && row.ageMs > row.ttlMs) { refused.push({ ...row, code: "stale" }); continue; }
+    offers.push(row);
+  }
+  const best = offers.slice().sort((a, b) => b.rate - a.rate)[0] || null;
+  return { offers, refused, best, at: now };
+}
+
+/**
+ * The size is snapped to the provider's grid DOWN. A size refusal is not aligned: a size outside the range is a
+ * provider's refusal and must reach the interface as a code, not turn into permission.
+ */
+export function snapToGrid(size, { min = null, max = null, step = null } = {}) {
+  const s = Number(size);
+  if (!Number.isFinite(s) || s <= 0) return { size: null, asked: size, snapped: false, code: "bad-size" };
+  const st = Number(step);
+  const lo = Number.isFinite(Number(min)) && min !== null && min !== "" ? Number(min) : 0;
+  const hi = Number.isFinite(Number(max)) && max !== null && max !== "" ? Number(max) : null;
+  if (s < lo) return { size: s, asked: s, snapped: false, code: "below-min" };
+  if (hi !== null && s > hi) return { size: s, asked: s, snapped: false, code: "above-max" };
+  if (!Number.isFinite(st) || st <= 0) return { size: s, asked: s, snapped: false, code: null };
+  const steps = Math.floor((s - lo) / st + 1e-9);
+  let snapped = Number((lo + steps * st).toFixed(12));
+  if (snapped < lo) snapped = lo;
+  return { size: snapped, asked: s, snapped: Math.abs(snapped - s) > 1e-12, code: null };
+}
+
+/**
+ * What the user will receive and what they pay for it, by the best offer and its rate.
+ * buy: they pay with the token and receive XMR, so the size (the ASSET of the pair XMR/<token>) is XMR.
+ * sell: they give XMR and receive the token, the ASSET of the pair <token>/XMR is the token itself.
+ */
+export function derivedFor(offer, direction, amount, now = Date.now()) {
+  const rate = offer && Number.isFinite(Number(offer.rate)) && Number(offer.rate) > 0 ? Number(offer.rate) : null;
+  const size = direction === "sell" ? (rate !== null && amount > 0 ? amount * rate : null)
+                                    : (rate !== null && amount > 0 ? amount / rate : null);
+  if (size === null) return { rate, size: null, unit: null, code: "no-offer", xmr: null };
+  const settled = snapToGrid(size, offer || {});
+  return {
+    rate,
+    size: settled.size,
+    unit: direction === "sell" ? String(offer.currency || "").toUpperCase() || null : "XMR",
+    snapped: settled.snapped,
+    code: settled.code,
+    // HOW MUCH XMR FOR THE REQUESTED SIZE. For a buy this is the size, for a sell - the amount the person gives.
+    xmr: direction === "sell" ? amount : (Number.isFinite(Number(settled.size)) ? Number(settled.size) : null),
+  };
+}
+
+// THE ROW FIELDS THAT GO OUT. This is a translation of the SHAPE, not a recomputation: the values are taken from
+// the read row and are not changed. The fields are listed explicitly (and not `...row`) so that internal parsing
+// markers do not leak out. Selection and priority are done by readBook above: a row gets here only if it has
+// already been recognised as an offer.
+const compactOffer = (o) => ({
+  providerId: o.providerId, displayName: o.displayName, pair: o.pair, rate: o.rate, rateQuote: o.rateQuote,
+  min: o.min, max: o.max, step: o.step, ttlMs: o.ttlMs, at: o.at, seq: o.seq,
+  // THE MATURITY LEVEL IS PART OF THE CHOICE: one provider gives a better price but only on finalized, another is
+  // pricier but faster. No field - null, not an invented default.
+  finality: o.finality || null,
+  // THE PAIR'S SIDES AND BOTH NETWORKS: the network is part of the market's identity, and the display must
+  // distinguish arbitrum from arbitrum-sepolia. `networks` is kept as the assembled view of the same values.
+  asset: o.asset, currency: o.currency,
+  assetNetwork: o.assetNetwork, currencyNetwork: o.currencyNetwork, networkStated: o.networkStated,
+  networksDerived: o.networksDerived === true, networksUnnamed: o.networksUnnamed === true,
+  // THE REASON (in the provider's words), THE PACKAGE'S SIGNATURE AND KEY, THE AGE BY ITS OWN MARK.
+  why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
+  networks: { asset: o.assetNetwork, currency: o.currencyNetwork, stated: o.networkStated },
+});
+
+// A REFUSAL IS THE SAME ROW PLUS A REASON CODE. The fields are not trimmed: the interface needs the range and
+// the price of the failed row to tell the person WHY there is no offer (and not just "none").
+const compactRefusal = (r) => ({ ...compactOffer(r), code: r.code, why: r.why });
+
+export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, providerAllowed = null, knownFactoryCodes = null }) {
+  // THE INTERFACE'S FACTORY POLICY (#103): the code hashes of factories it is willing to trade through
+  // (extcodehash semantics = keccak256 of the runtime code). An EMPTY list is "no policy" (like
+  // allowedProviders); a NON-EMPTY one refuses any factory whose code is not on it. Lower-cased once.
+  const factoryPolicy = Array.isArray(knownFactoryCodes) && knownFactoryCodes.length
+    ? knownFactoryCodes.map((h) => String(h).toLowerCase()).filter(Boolean)
+    : null;
+  const listeners = new Set();
+  let timer = null;
+  let size = 1;              // the request size in units of the pair's ASSET; we start from one, as the engine does
+  let state = null;
+  let request = { direction: "buy", token: null, amount: null };
+  let inFlight = false;
+
+  const emit = () => { for (const handler of listeners) handler(state); };
+
+  const tick = async () => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      // THE REQUEST SIZE. Usually it is derived from the person's amount (amount) and refined on the next tick.
+      // But the caller can name it HIMSELF (size) - then it is taken AS IS rather than derived anew: it is the
+      // same size the interface has already aligned to the provider's grid. There is no second size rule here.
+      const explicit = Number.isFinite(Number(request.size)) && Number(request.size) > 0;
+      const asked = explicit ? Number(request.size) : size;
+      const data = await http.json("/rate?amount=" + encodeURIComponent(asked) + "&side=" + encodeURIComponent(request.direction));
+      const book = readBook(data, now());
+      const offer = book.best;
+      const amount = Number.isFinite(Number(request.amount)) ? Number(request.amount) : null;
+      // The size derived from the person's amount becomes the size of the NEXT request: the price does not depend
+      // on volume, and the volume is needed by the provider to say whether it takes such a size. With a named size
+      // there is nothing to derive - it stays what it was asked as.
+      const derived = offer && amount !== null && !explicit ? derivedFor(offer, request.direction, amount, now()) : null;
+      if (derived && derived.size !== null) size = derived.size;
+      // THE UNIT with a named size: a buy is measured in XMR (the ASSET of the pair XMR/<token>), a sell - in the token.
+      const unitFromOffer = offer ? (String(offer.currency || "").toUpperCase() || null) : null;
+      const settled = explicit ? (offer ? snapToGrid(asked, offer) : null) : null;
+      state = {
+        direction: request.direction,
+        token: request.token,
+        amount,
+        size: explicit ? asked : size,
+        unit: explicit ? (request.direction === "sell" ? unitFromOffer : "XMR") : (derived ? derived.unit : null),
+        rate: explicit ? (offer ? Number(offer.rate) : null) : (derived ? derived.rate : null),
+        xmr: derived ? derived.xmr : null,
+        at: now(),
+        providerId: offer ? offer.providerId : null,
+        sizeOk: explicit ? Boolean(settled && settled.code === null) : Boolean(derived && derived.code === null),
+        sizeCode: explicit ? (settled ? settled.code : "no-offer") : (derived ? derived.code : "no-offer"),
+        seq: book.offers.length ? (book.offers.find((o) => o.seq !== null) || {}).seq ?? null : null,
+        // THE BEST, AS THE SERVICE NAMED IT (for the requested volume and side). The core does NOT recompute it:
+        // these are response data the interface needs to confirm its own "best" mark by pair and provider.
+        best: data && data.best && typeof data.best === "object"
+          ? { providerId: String(data.best.providerId || ""), pair: String(data.best.pair || "") } : null,
+        offers: book.offers.map(compactOffer),
+        refused: book.refused.map(compactRefusal),
+        references: Array.isArray(data && data.references) ? data.references.map((r) => ({ source: r.source, value: num(r.value), at: num(r.at) })) : [],
+        ok: book.offers.length > 0,
+      };
+      emit();
+    } catch (error) {
+      // A REFUSAL IS NOT REPLACED BY PAST NUMBERS: showing a stale price as live is worse than saying the connection
+      // is gone. The data is kept, but ok is cleared, and the interface sees it.
+      state = { ...(state || { direction: request.direction, token: request.token, amount: null, size, unit: null, rate: null, xmr: null,
+        at: now(), providerId: null, sizeOk: false, sizeCode: null, seq: null, best: null, offers: [], refused: [], references: [] }),
+        at: now(), ok: false, error: { code: error && error.code === "server-unavailable" ? "quote-unavailable" : "unknown" } };
+      emit();
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  const restart = () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    if (listeners.size > 0) {
+      void tick();
+      timer = setInterval(() => { void tick(); }, config.limits.quotePollMs);
+    }
+  };
+
+  return {
+    watch(next, onSnapshot) {
+      if (typeof onSnapshot !== "function") fail("bad-input", { field: "onSnapshot" });
+      const direction = next && next.direction === "sell" ? "sell" : "buy";
+      const token = next && typeof next.token === "string" && next.token ? next.token.toLowerCase() : config.settlement.chain.nativeSymbol.toLowerCase();
+      request = {
+        direction,
+        token,
+        amount: next && next.amount !== undefined ? next.amount : null,
+        // A NAMED SIZE (in units of `unit`): an interface that has already aligned the volume to the provider's
+        // grid hands it here, and the core asks for EXACTLY it rather than deriving it from the amount anew.
+        size: next && Number.isFinite(Number(next.size)) && Number(next.size) > 0 ? Number(next.size) : null,
+      };
+      size = 1;
+      state = null;
+      listeners.add(onSnapshot);
+      restart();
+      return () => {
+        listeners.delete(onSnapshot);
+        if (listeners.size === 0) {
+          if (timer) clearInterval(timer);
+          timer = null;
+        }
+      };
+    },
+    // WHAT THE SDK KNOWS RIGHT NOW: a snapshot without waiting. Needed by an interface that subscribed later than
+    // the first poll happened.
+    snapshot: () => state,
+    // A FIRM QUOTE FOR AN ORDER. It carries a commitment under keys, so THE PROVIDER'S SIGNATURE IS CONFIRMED
+    // HERE, BY RECOVERING THE ADDRESS FROM THE EIP-712 SIGNATURE - not taken on trust from a flag the backend
+    // reports. A quote that cannot be verified is not "probably fine": a missing field, a missing signature or
+    // an unusable domain is REFUSED, never accepted (the rule the old flag carried is kept). The digest is
+    // built from the quote's own fields, so nothing signed can be swapped afterwards; the named quoteKey is
+    // matched against the recovered address. THEN THE CHAIN IS ASKED WHO OWNS THE KEY (providerOf): the
+    // signature alone certifies itself, because a key can sign anything and call itself any provider. The
+    // registry is read from the quote/order conditions - never from SDK settings: any registry can be deployed
+    // by anyone, and the order carries which one it is (the field is signed and bound into the terms). Finally
+    // the interface's allow-list, when it supplied one, is applied as policy (who is admitted at all).
+    //
+    // The path and the body are the same as the engine's (`requestOrderQuote` in www/js/core/rfqSource.js): POST to
+    // the named path, body { providerId, order }. The path is named by name, so it is overridable by options.
+    async firm(request) {
+      if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
+      if (typeof request.providerId !== "string" || !request.providerId) fail("bad-input", { field: "providerId" });
+      if (!request.order || typeof request.order !== "object") fail("bad-input", { field: "order" });
+      let body = null;
+      try {
+        body = await http.json(config.route("orderQuote"), {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ providerId: request.providerId, order: request.order }),
+        });
+      } catch (error) {
+        if (error && error.code === "bad-input") throw error;
+        fail("server-unavailable", { step: "order-quote" });
+      }
+      if (!body || body.ok !== true || !body.quote) fail("quote-refused", { step: "order-quote" });
+      const quote = body.quote;
+      // A MISSING FIELD OF THE SIGNED SET IS NOT "PROBABLY ZERO": the digest cannot be built, so the quote is
+      // not verifiable and is refused (its own code, so the interface can say which field is unbound).
+      const missingFields = orderQuoteMissingFields(quote);
+      if (missingFields.length) fail("quote-field-unbound", { step: "signature", missing: missingFields });
+      // THE QUOTE'S OWN EXPIRY, checked against the clock the core already has. It is bound in the signature too,
+      // but a stale quote is refused by its own code rather than looking like a signature failure.
+      const validUntil = Number(quote.validUntil);
+      // THE SCALE IS SECONDS: the same as the order's deadlines and block.timestamp. The core's clock is in
+      // milliseconds (Date.now), so exactly ONE boundary is converted - "now", not the quote value itself: one
+      // unit for the value, one conversion at the input.
+      const nowSec = Math.floor(now() / 1000);
+      if (Number.isFinite(validUntil) && validUntil > 0 && validUntil <= nowSec) {
+        fail("quote-expired", { step: "signature", validUntil });
+      }
+      // RECOVER, THEN MATCH THE NAMED KEY. A signature that does not recover is one refusal; a valid signature
+      // that recovers to a DIFFERENT address is another (the quote names a key that did not sign it).
+      const recoveredKey = recoverOrderQuoteKey(quote);
+      if (recoveredKey === null) fail("quote-signature-invalid", { step: "signature" });
+      const declaredKey = String(quote.quoteKey).toLowerCase();
+      if (recoveredKey !== declaredKey) fail("quote-key-mismatch", { step: "signature", got: recoveredKey, want: declaredKey });
+      // WHO OWNS THE KEY - ASKED OF THE REGISTRY NAMED BY THE QUOTE. Both fields are part of the signed set, so
+      // they cannot be swapped after signing; this is what turns "a key signed it" into "this provider's key
+      // signed it". No chain-read seam - refuse rather than take the signature on trust.
+      const registry = String(quote.registry || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(registry) || registry === ZERO_ADDRESS) {
+        fail("quote-field-unbound", { step: "registry", field: "registry" });
+      }
+      const declaredProvider = String(quote.provider || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(declaredProvider) || declaredProvider === ZERO_ADDRESS) {
+        fail("quote-field-unbound", { step: "registry", field: "provider" });
+      }
+      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(declaredKey) }));
+      } 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: declaredKey });
+      }
+      if (mappedProvider !== declaredProvider) {
+        fail("quote-provider-mismatch", { step: "registry", got: mappedProvider, want: declaredProvider });
+      }
+      // THE INTERFACE'S OWN ADMISSION LIST - POLICY, NOT PROOF. The chain says whose key it is; whether this
+      // interface trades with that provider at all is the interface's decision, and it rides as a hook.
+      if (typeof providerAllowed === "function" && providerAllowed(declaredProvider) !== true) {
+        fail("quote-provider-not-allowed", { step: "policy", provider: declaredProvider });
+      }
+      // THE FACTORY: NAMED BY THE PROVIDER'S RECORD, CHECKED BY ITS CODE (#103). The factory will verify the
+      // quote in EVM (it is the EIP-712 verifyingContract), so it must be the one the record names AND its
+      // code must be a build this interface knows. The record lookup always runs; the code check runs when a
+      // policy list was supplied (nothing to pin against otherwise).
+      const declaredFactory = String(quote.factory || "").toLowerCase();
+      if (!/^0x[0-9a-f]{40}$/.test(declaredFactory) || declaredFactory === ZERO_ADDRESS) {
+        fail("quote-field-unbound", { step: "factory", field: "factory" });
+      }
+      let recordedFactory = null;
+      try {
+        recordedFactory = addressFromWord(await evmCall({ to: registry, data: factoryOfData(declaredProvider) }));
+      } 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: declaredProvider });
+      }
+      if (recordedFactory !== declaredFactory) {
+        fail("quote-factory-mismatch", { step: "factory", got: declaredFactory, 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(declaredFactory); } catch { fail("quote-factory-unchecked", { step: "factory", why: "code-read-failed", factory: declaredFactory }); }
+        const codeBytes = hexToBytesQ(codeHex);
+        // EXTCODEHASH SEMANTICS: keccak256 of the runtime code. An address with no code (empty/0x) hashes to
+        // the keccak of empty, which is not on any build list - refused like any unknown build.
+        const codeHash = bytesToHexQ(keccak256(codeBytes || new Uint8Array(0)));
+        if (!factoryPolicy.includes(codeHash)) {
+          fail("quote-factory-code-unknown", { step: "factory", factory: declaredFactory, codeHash });
+        }
+      }
+      // BINDING THE QUOTE TO OUR TERMS. The signature confirms the provider signed THIS quote, but not that it is
+      // about our swap: we are responsible for the binding. The context string is computed by OUR engine module
+      // (format arrakis-order-v3; the field order is part of the protocol and must not be rearranged). There is
+      // deliberately no copy of the format here: a copy would silently drift from the protocol.
+      //
+      // THE ORDER OF THE GATES: signature first, then binding. So a refusal names the nearest reason, not the first
+      // one at hand.
+      // THE PROVIDER MAY NAME THE CLAIMER HIMSELF, AND THAT IS ALSO AN ASSEMBLED CONTEXT (a defect found). The
+      // provider may be the claimer: then it substitutes ITS OWN address into the order terms and signs the context
+      // with it already in place. Requiring the context from the caller in that case is impossible - they do not
+      // know the provider's address, and then the quote cannot be obtained at all (the live contour answered this
+      // with bad-input {field:"order"} BEFORE any network). So if the sent terms had no claimer, the context is
+      // computed from the terms WITH HIS value from the quote - exactly as the engine does it
+      // (sdk/src/swap-flow.mjs: `{ ...orderBase, claimer: claimerResolved }`). No OPTIONAL checks appeared here:
+      // a mismatched string is still a refusal (quote-refused { step: "context" }).
+      let expectedContext = null;
+      try { expectedContext = engine.orderContext.orderContextString(request.order); }
+      catch { expectedContext = null; }
+      if (expectedContext === null) {
+        const providerClaimer = quote && quote.claimer;
+        if (providerClaimer) {
+          try { expectedContext = engine.orderContext.orderContextString({ ...request.order, claimer: providerClaimer }); }
+          catch { fail("bad-input", { field: "order" }); }
+        } else {
+          fail("bad-input", { field: "order" });
+        }
+      }
+      const quoted = quote.context || "";
+      if (String(quoted) !== expectedContext) {
+        fail("quote-refused", { step: "context", why: quoted ? "other-terms" : "not-reported" });
+      }
+      return quote;
+    },
+  };
+}

package/src/record.mjs

@@ -0,0 +1,65 @@
+// THE SWAP RECORD: CREATION AND OUR SIDE OF THE ORDER.
+//
+// What is here and what is not - and why exactly so.
+//
+// PRESENT: the swap record (the engine's `createSwap` - a pure state record) and OUR side of the order. When the
+// order terms are given, the side is built by the ENGINE'S BUILDER (www/js/atomic/order.js): two halves, their
+// public points, the DLEQ PROOF and the side's encryption key. The core does not invent its own halves: the
+// proof is bound to the order terms (how much, to whom, the deadlines, the salt, the factory, the chain), so
+// without them there is nothing to bind it to - and the record refuses with a code naming the field.
+//
+// ABSENT: the counterparty's side. Its half and point come from the order (or a sandbox stand-in is built), and
+// that is exactly why the record returns nextStep: "order" and missing: ["counterparty-half"]: a recovery file
+// cannot be assembled without the other half.
+import { SdkError } from "./errors.mjs";
+import { primitives } from "./primitives.mjs";
+import * as engine from "./engine.mjs";
+import { buildOwnSide, halfHex, norm } from "./order.mjs";
+
+/**
+ * Our side. Without order terms - only the halves and their points (a shape of the record; there is no proof and
+ * there cannot be: there is nothing to prove). With terms - the whole side is built by the engine's builder.
+ *
+ * THE HALF NAMES ARE THE ENGINE'S: the half is returned in the engine's form (BigInt), and it goes into the
+ * record as a hex string, because a BigInt survives neither storage nor the recovery file's JSON.
+ */
+export function ownSide(order = null) {
+  if (order !== null && order !== undefined) {
+    const built = buildOwnSide(order);
+    return built.side;
+  }
+  const halves = engine.halves.createHalves(primitives);
+  const half = halves.newHalf();
+  const viewHalf = halves.newHalf();
+  return { half, viewHalf, pub: halves.publicHalves(half), viewPub: halves.publicHalves(viewHalf).ed };
+}
+
+/**
+ * Create the swap record and put OUR side into it.
+ * The record's field names are the ones the engine reads them by (`halvesWalletOf`: half, viewHalf,
+ * edPointLocker, edViewPointLocker). The counterparty's half cannot and need not be put in: it will come from
+ * the order.
+ */
+export function createRecord(input, { order = null } = {}) {
+  if (!input || typeof input !== "object") throw new SdkError("bad-input", { field: "input" });
+  const side = ownSide(order);
+  let swap = null;
+  try { swap = engine.swap.createSwap(input); } catch { throw new SdkError("bad-input", { field: "input" }); }
+  const escrow = { ...(swap.escrow || {}),
+    // THE HALVES ARE A HEX STRING (a BigInt does not survive JSON), the points are in canonical form: that is how
+    // 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 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 };
+  // THE ORDER-QUOTE ID (a defect found). The engine's createSwap builds the record BY A LIST OF FIELDS, and the
+  // `orderQuoteId` field is not in it: the value brought by the request was silently lost. And our service uses
+  // it to tie the created escrow to the provider node's record - without it the node will not take the ETH (the
+  // mark body carried quoteId: null). The screen used to set this field itself
+  // (www/js/ui/views/confirm.js: swap.orderQuoteId = flow.quoteId).
+  const quoteId = input && input.orderQuoteId;
+  if (quoteId !== undefined && quoteId !== null && quoteId !== "") record.orderQuoteId = quoteId;
+  try { engine.swap.saveSwap(record); } catch { throw new SdkError("storage-unavailable", { step: "save-swap" }); }
+  return { swap: record, side, missing: ["counterparty-half"], nextStep: "order" };
+}

package/src/recovery.mjs

@@ -0,0 +1,40 @@
+// RECOVERY FROM FILE: parsing and integrity checks are done by the engine, the response shape by the SDK
+// contract.
+//
+// The file arrives from the interface as a string or as `{ contents }`: the SDK knows neither about
+// <input type=file> nor about buffers - that is the interface's business.
+import * as engine from "./engine.mjs";
+import { SdkError } from "./errors.mjs";
+
+const contentsOf = (file) => {
+  if (typeof file === "string") return file;
+  if (file && typeof file.contents === "string") return file.contents;
+  return null;
+};
+
+export function createRecovery() {
+  return {
+    async open(file, passphrase) {
+      const contents = contentsOf(file);
+      if (contents === null) throw new SdkError("bad-input", { field: "file" });
+      let restored;
+      try {
+        restored = await engine.restore.restoreFromFile(contents, 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" });
+      }
+      const payload = restored.payload || {};
+      const wallet = restored.wallet || {};
+      const halves = Number(payload.version) >= 3;
+      return {
+        address: typeof wallet.address === "string" ? wallet.address : null,
+        // THERE IS NO SPEND KEY FROM THE HALVES, AND THERE CANNOT BE: in the halves scheme the second half
+        // arrives from the chain once the counterparty takes the ETH. Observing - yes; disposing of funds -
+        // only after the half is revealed.
+        spendable: !halves,
+        swapId: typeof payload.swapId === "string" ? payload.swapId : null,
+      };
+    },
+  };
+}

package/src/sim.mjs

@@ -0,0 +1,37 @@
+// SANDBOX: failure scenarios and time. Added on requirement 8 of issue #32 - the interface lays out failure
+// screens without waiting for a live testnet.
+//
+// What is deliberately absent, and why: scenarios are applied by the ENGINE (`www/js/mock`, the scenario fields
+// on the swap), not by the SDK - the SDK merely names the scenarios and holds the interface's choice. Applying
+// one to a swap will arrive together with `swaps.start` (stage 2), because a scenario is a property of the swap,
+// not a global setting.
+import * as engine from "./engine.mjs";
+import { fail } from "./errors.mjs";
+
+export const SCENARIOS = Object.keys(engine.config.SCENARIO_LABELS || {});
+
+export function createSim() {
+  let scenario = SCENARIOS[0] || null;
+  let speedValue = 1;
+  let advancedMs = 0;
+  return {
+    scenarios: () => SCENARIOS.slice(),
+    apply(next) {
+      if (!SCENARIOS.includes(next)) fail("bad-input", { field: "scenario", known: SCENARIOS });
+      scenario = next;
+    },
+    speed(multiplier) {
+      const value = Number(multiplier);
+      if (!Number.isFinite(value) || value <= 0) fail("bad-input", { field: "speed" });
+      speedValue = value;
+    },
+    advance(ms) {
+      const value = Number(ms);
+      if (!Number.isFinite(value)) fail("bad-input", { field: "ms" });
+      advancedMs += value;
+    },
+    // The sandbox's internal state: needed by the interface's debug panel and by `swaps.start` (stage 2). Named
+    // `debug`, not `state`: this is not the swap state, and neither the interface nor a check should confuse them.
+    debug: () => ({ scenario, speed: speedValue, advancedMs }),
+  };
+}