@ninsei-labs/sdk 0.52.0 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -38,13 +38,30 @@
     "check:destination": "node tools/check-destination.mjs",
     "check:codes-meta": "node tools/check-codes-meta.mjs",
     "check:arrival-read": "node tools/check-arrival-read.mjs",
+    "check:sale-auth": "node tools/check-sale-auth.mjs",
+    "check:backup-confirmation": "node tools/check-backup-confirmation.mjs",
+    "check:key-view": "node tools/check-key-view.mjs",
+    "check:arrival-consensus": "node tools/check-arrival-consensus.mjs",
+    "check:arrival-real": "node tools/check-arrival-real.mjs",
+    "check:order-proof": "node tools/check-order-proof.mjs",
     "check:daemon-address": "node tools/check-daemon-address.mjs",
     "check:ci-scripts": "node tools/check-ci-scripts.mjs",
     "check:factory-selectors": "node tools/check-factory-selectors.mjs",
     "check:fee-estimate": "node tools/check-fee-estimate.mjs",
     "check:deadline-scale": "node tools/check-deadline-scale.mjs",
     "check:node-probe": "node tools/check-node-probe.mjs",
-    "check:recovery-key": "node tools/check.mjs --only=recovery-key"
+    "check:recovery-key": "node tools/check.mjs --only=recovery-key",
+    "check:recovery-open": "node tools/check-recovery-open.mjs",
+    "check:contract-vectors": "node tools/check-contract-vectors.mjs",
+    "check:live-contract": "node tools/check-live-contract.mjs",
+    "check:anvil-fork": "node tools/check-anvil-fork.mjs",
+    "check:dex": "node tools/check.mjs --only=cow,cow-refusal,kyber,kyber-refusal,uniswapx,uniswapx-refusal,uniswap-relay,uniswap-relay-refusal",
+    "check:anvil-uniswap": "node tools/check-anvil-uniswap.mjs",
+    "check:atomic-flow": "node tools/check-atomic-flow.mjs",
+    "check:packed-consumer": "node tools/check-packed-consumer.mjs",
+    "check:quote-binding": "node tools/check-quote-binding.mjs",
+    "check:types-consumer": "node node_modules/typescript/bin/tsc -p tools/ts-consumer/tsconfig.json",
+    "check:monero-live": "node tools/check-monero-live.mjs"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -126,5 +143,8 @@
     "@scure/bip39": "2.4.0",
     "keccak256": "^1.0.6"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "7.0.2"
+  }
 }

package/src/adapters/monero-wallet.mjs

@@ -25,16 +25,25 @@
 // with a code and params. Neither `null` nor a zero in place of the answer: an empty address and a zero balance
 // look like real data, and that is exactly why they are not returned.
 import { SdkError } from "../errors.mjs";
+import { signedFeeTotal } from "../sweep-fees.mjs";
 import { config as engineConfig, xmrAddress } from "../engine.mjs";
 
 const XMR_VM = "monero";
 // The wallet session label - the same as the withdrawal page's. This is not a secret and not an address, but a session name.
 const DEFAULT_PASSWORD = "ninsei-wallet-session";
 
-/** Monero network names declared by the core's registry. The adapter keeps no table of its own. */
+// THE STANDARD NAMES ARE PART OF THE PROTOCOL, NOT OF A DEPLOYMENT. XMR_NETWORKS names what the demo is configured
+// for (stagenet in CI, fakechain in regtest); a mainnet or testnet wallet is still a valid Monero wallet and the
+// withdrawal page takes the network from its own node. Refuse only a name that is not a Monero network at all.
+const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet", "fakechain"];
+
+/** Monero network names declared by the core's registry plus the standard names. */
 const knownNetworks = () => {
   const declared = engineConfig.XMR_NETWORKS || {};
-  return [...new Set(Object.values(declared).filter((v) => typeof v === "string" && v))].sort();
+  return [...new Set([
+    ...Object.values(declared).filter((v) => typeof v === "string" && v),
+    ...STANDARD_XMR_NETWORKS,
+  ])].sort();
 };
 
 /**
@@ -183,11 +192,9 @@ export function moneroWalletAdapter({
     },
 
     // Optional, like every withdrawal adapter: a library that reports no fee answers null rather than a zero.
+    // A split sweep pays a fee on EVERY signed transaction; the total is what leaves the remainder.
     async fee(signed) {
-      const tx = Array.isArray(signed) ? signed[0] : signed;
-      if (!tx || typeof tx.getFee !== "function") return null;
-      const value = tx.getFee();
-      return value === null || value === undefined ? null : String(value);
+      return signedFeeTotal(signed);
     },
 
     // THE MONERO WALLET HAS NO EVENTS (monero-ts has no on/removeListener): a subscriber receives a notification

package/src/adapters/monero.mjs

@@ -8,6 +8,7 @@
 // sending is a separate call. That way the interface has a point where it can show the person what exactly will
 // leave, BEFORE sending rather than after.
 import { SdkError } from "../errors.mjs";
+import { signedFeeTotal } from "../sweep-fees.mjs";
 
 export function moneroWallet({ createWallet, networkType, serverUri, password = "ninsei-sweep-session", fields = {} }) {
   const build = typeof createWallet === "function" ? createWallet : null;
@@ -41,15 +42,12 @@ export function moneroWallet({ createWallet, networkType, serverUri, password =
       return await wallet.sweepUnlocked({ address, relay });
     },
     // THE FEE OF WHAT WAS SIGNED, when the library reports one. `sweepUnlocked` answers with the signed
-    // transactions; monero-ts puts the fee on each transaction. Optional by contract - the core treats a missing
-    // method as "unknown", so this adapter says what it can and nothing more.
+    // transactions; monero-ts puts the fee on each transaction and a split sweep pays every one of them. Optional
+    // by contract - the core treats a missing method as "unknown", so this adapter says what it can and nothing
+    // more; one unreadable fee makes the total unknown, not partial.
     async fee(signed) {
       need();
-      const list = Array.isArray(signed) ? signed : [signed];
-      const tx = list[0];
-      if (!tx || typeof tx.getFee !== "function") return null;
-      const value = tx.getFee();
-      return value === null || value === undefined ? null : String(value);
+      return signedFeeTotal(signed);
     },
 
     async relay(signed) {

package/src/codes.mjs

@@ -92,6 +92,9 @@ export const ERROR_CODES = [
   // through - server-unavailable, while the service answered and did not accept - server-refused (with the
   // status and its own reason). The advice to the interface differs: "retry" versus "investigate".
   "server-refused",
+  // THE TRANSACTION WAS SENT BUT THE RECEIPT DOES NOT PROVE AN ESCROW: no receipt yet, no expected OrderCreated,
+  // or a receipt from another factory. The tx hash is the handle for a retry read; nothing was saved as funded.
+  "funding-pending",
   // A TIMEOUT WAITING FOR XMR TO ARRIVE - a separate code. "We did not wait long enough" is a state of the
   // money, not a breakdown and not an empty response: mixing it with other refusals, the interface could not
   // tell "not arrived yet" from "broken".
@@ -167,6 +170,7 @@ export const ERROR_META = Object.freeze({
   "storage-unavailable": { retryable: true, side: "service" },
   "server-unavailable": { retryable: true, side: "service" },
   "server-refused": { retryable: false, side: "service" },
+  "funding-pending": { retryable: true, side: "chain" },
   "xmr-timeout": { retryable: true, side: "chain" },
   "xmr-locked": { retryable: true, side: "chain" },
   "xmr-nodes-disagree": { retryable: true, side: "chain" },

package/src/config.mjs

@@ -8,7 +8,7 @@
 import * as engine from "./engine.mjs";
 import { CHECK_CODES, ERROR_CODES, STEP_CODES } from "./codes.mjs";
 import { fail } from "./errors.mjs";
-import { implementedVms, legFor } from "./legs/index.mjs";
+import { implementedVms, legFor, profileOfChain } from "./legs/index.mjs";
 import { routeProviders } from "./legs/evm.mjs";
 
 // TOKENS ARE TAKEN BY AN ENGINE FUNCTION, NOT FROM A NETWORK FIELD: `tokensOf` returns the native coin first,
@@ -41,7 +41,10 @@ const tokensOfNetwork = (chainId) => {
 const chainConfig = (chain) => ({
   id: chain.id,
   name: chain.name,
-  vm: chain.vm || "evm",
+  vm: chain.vm || null,
+  // WHAT THIS SETTLEMENT SIDE LOOKS LIKE: address format, contract/program/UTXO and ref kind. It is metadata and
+  // does not claim a driver exists; `implementedVms` and `legFor` decide that. Finality belongs to a chain.
+  settlementProfile: profileOfChain(chain.id),
   chainId: chain.chainId,
   nativeSymbol: chain.native && chain.native.symbol ? chain.native.symbol : null,
   tokens: tokensOfNetwork(chain.chainId).map((t) => ({
@@ -108,7 +111,7 @@ export const DEFAULT_XMR_NODES = Object.freeze({
     { url: "https://mainnet.xmr.kernal.eu:18089", operator: "kernal.eu" },
   ],
   stagenet: [
-    { url: "https://xmr.arrakisswap.trade", operator: "ninseiswap" },
+    { url: "https://xmr-stagenet.ninsei.finance", operator: "Ninsei" },
     { url: "https://stagenet.xmr.kernal.eu:38089", operator: "kernal.eu" },
   ],
 });

package/src/decline.mjs

@@ -41,7 +41,12 @@ const hexOf = (bytes) => {
   return out;
 };
 
-/** keccak256("Declined(address)") - the first (and only) topic of a decline's log. */
+/**
+ * keccak256("Declined(address)") - topic0 of a decline's log. The escrow indexes `claimer`, so a log emitted by the
+ * current contracts also carries it in topic1; the event signature (and therefore topic0) does not change. Logs from
+ * escrows deployed before the indexing carry the claimer in data instead, which is why this module matches only
+ * topic0 and does not assume a claimer position.
+ */
 export const DECLINED_TOPIC0 = hexOf(keccak256(DECLINE_EVENT_SIGNATURE()));
 
 // THE NODE'S OWN TWO FIELDS for a declined swap: `{ status: "declined", code: "compliance" }`. The code is the

package/src/feeEstimate.mjs

@@ -13,13 +13,16 @@ const DEFAULT_TIMEOUT_MS = 8000;
 
 const text = (value) => (typeof value === "string" ? value.trim() : "");
 
-/** A per-KB price -> the fee for a transaction of `bytes`, rounded UP: one unit short is still short. */
-export function feeForBytes(feePerKB, bytes) {
-  let perKB;
+/**
+ * A PER-BYTE price -> the fee for a transaction of `bytes`/weight. Monero's `get_fee_estimate` returns `fee` and
+ * `fees` in atomic units per byte; dividing by 1024 made every estimate 1024 times too low.
+ */
+export function feeForBytes(feePerByte, bytes) {
+  let perByte;
   let size;
-  try { perKB = BigInt(feePerKB); size = BigInt(bytes); } catch { throw new RangeError("feeForBytes: whole numbers only"); }
-  if (perKB < 0n || size < 0n) throw new RangeError("feeForBytes: negative input");
-  return ((perKB * size + 1023n) / 1024n).toString();
+  try { perByte = BigInt(feePerByte); size = BigInt(bytes); } catch { throw new RangeError("feeForBytes: whole numbers only"); }
+  if (perByte < 0n || size < 0n) throw new RangeError("feeForBytes: negative input");
+  return (perByte * size).toString();
 }
 
 const atomicField = (source, ...names) => {
@@ -34,8 +37,9 @@ const atomicField = (source, ...names) => {
 /**
  * ASK A NODE WHAT A TRANSACTION WILL COST.
  *
- * The answer is a price per kilobyte (and the median, and the daemon's own priority list). The exact sum needs the
- * assembled transaction; `feeForBytes` is the arithmetic that gets there. Never throws - a refusal names the problem.
+ * The answer is a price per byte (and the daemon's own priority list, and its quantization mask). The exact sum
+ * needs the assembled transaction; `feeForBytes` is the arithmetic that gets there. Never throws - a refusal names
+ * the problem.
  */
 export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   // TRAILING SLASHES WITHOUT A REGEX: a pattern anchored on a run of slashes is flagged as a slow expression on
@@ -65,9 +69,12 @@ export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, tim
   try { body = await response.json(); } catch { return { ok: false, why: "not-json" }; }
   if (!body || body.error) return { ok: false, why: "rpc", rpc: body && body.error ? body.error.code ?? null : null };
   const result = body.result || {};
-  const feePerKB = atomicField(result, "fee_per_kb", "feePerKB");
-  const medianFeePerKB = atomicField(result, "median_fee_per_kb", "medianFeePerKB");
-  const list = result.fees ?? result.feesPerKB ?? null;
+  // THE DAEMON'S OWN UNITS. `fee` and each entry of `fees` are atomic units PER BYTE; `quantization_mask` is the
+  // unit the final fee is rounded to. `fee_per_kb` was never sent, so the old read found nothing on a real node and
+  // the old fallback then divided per-byte values by 1024.
+  const feePerByte = atomicField(result, "fee", "feePerByte");
+  const quantizationMask = atomicField(result, "quantization_mask", "quantizationMask");
+  const list = result.fees ?? result.feesPerByte ?? null;
   let perPriority = null;
   if (Array.isArray(list)) {
     perPriority = [];
@@ -75,6 +82,6 @@ export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, tim
       try { perPriority.push(BigInt(value).toString()); } catch { perPriority = null; break; }
     }
   }
-  if (feePerKB === null && medianFeePerKB === null && !perPriority) return { ok: false, why: "no-estimate" };
-  return { ok: true, url: base, feePerKB, medianFeePerKB, perPriority };
+  if (feePerByte === null && !perPriority) return { ok: false, why: "no-estimate" };
+  return { ok: true, url: base, feePerByte, perPriority, quantizationMask };
 }

package/src/index.mjs

@@ -198,10 +198,11 @@ export function createNinsei(options) {
   // THE STORAGE THE INTERFACE BROUGHT BECOMES THE CORE'S STORAGE: unfinished swaps and the agent session live
   // where the interface decided (browser storage, memory, a server). Without the option the core takes its
   // default: web storage if it is present in the environment, otherwise memory.
-  if (o.storage) {
-    engine.store.setStorage(o.storage);
-    engine.auth.setSessionStore(o.storage);
-  }
+  // ONE CLIENT, ONE STORE. A second client with another adapter used to replace the module-wide store, so the
+  // first client listed the second's swaps and could delete them. Even a client that brought no adapter binds the
+  // current one, so a later explicit store cannot take it over.
+  engine.store.bindStorage(o.storage || engine.store.storage());
+  if (o.storage) engine.auth.setSessionStore(o.storage);
   const http = createHttp({ apiBase: config.apiBase, fetchImpl: o.fetch, timeoutMs: config.limits.httpTimeoutMs });
   // THE CHAIN READ AND THE ALLOW-LIST GO INTO THE QUOTE CHECK: without the read the signature certifies itself,
   // so the same evmCall seam the lock and the actions use is handed to the quotes too.

package/src/legs/index.mjs

@@ -10,6 +10,8 @@
 // What must not be in a driver: no user strings, no DOM. A driver is chain reads and writes plus knowing what the
 // network is measured in for this VM.
 import * as evm from "./evm.mjs";
+export { profileOf, VM_PROFILES } from "./profiles.mjs";
+import { profileOf } from "./profiles.mjs";
 
 export const LEGS = { evm };
 
@@ -37,6 +39,12 @@ export const vmOfChain = (chainId) => {
   return chain && chain.vm ? chain.vm : null;
 };
 
+/** The VM profile for a network, or null when the network or the profile is unknown. */
+export const profileOfChain = (chainId) => {
+  const vm = vmOfChain(chainId);
+  return vm ? profileOf(vm) : null;
+};
+
 /**
  * The leg driver for a network. A network without a driver is a NAMED refusal: you can see which vm is not
  * supported and which are. This is exactly the rule "no network is silently assumed to be EVM".

package/src/legs/profiles.mjs

@@ -0,0 +1,51 @@
+// WHAT A SETTLEMENT SIDE LOOKS LIKE, WITHOUT ASSERTING THAT A DRIVER EXISTS.
+//
+// The profile is metadata, not an implementation. It tells the SDK and the interface which address and transaction
+// shapes a VM uses, and whether settlement is a contract, a program or a UTXO script. The driver registry
+// (./index.mjs) stays the source of truth for what is RUNNABLE today.
+//
+// Bitcoin is listed because the planned order is Tron, Solana, then Bitcoin; a UTXO settlement side is a
+// script/HTLC, not an account with an escrow contract. A profile is not a promise that the chain is selectable:
+// `escrow: null` and the driver registry decide that. Finality is not here: it is a chain policy, not a VM shape,
+// and a generic "12 confirmations" is wrong for an L2. Add it to the chain that first needs it.
+export const VM_PROFILES = Object.freeze({
+  // EVM: 20-byte hex addresses, a contract escrow, a transaction hash.
+  evm: Object.freeze({
+    vm: "evm",
+    addressFormat: "hex-20",
+    settlementKind: "contract",
+    refKind: "address",
+    txRef: "hash",
+  }),
+  // TVM: base58check addresses on the wire (with a 0x41 hex form internally), a contract escrow and energy/bandwidth
+  // instead of gas.
+  tron: Object.freeze({
+    vm: "tron",
+    addressFormat: "base58check",
+    settlementKind: "contract",
+    refKind: "address",
+    txRef: "hash",
+  }),
+  // SVM: base58 addresses, a program with PDA accounts, a transaction signature.
+  solana: Object.freeze({
+    vm: "solana",
+    addressFormat: "base58",
+    settlementKind: "program",
+    refKind: "pda",
+    txRef: "signature",
+  }),
+  // UTXO: no account and no escrow contract. Settlement is an HTLC/adaptor-script output, addressed by a script
+  // or an address, and identified by a txid. A future Bitcoin-family chain uses the same shape with its own
+  // network parameters. Taproot outputs (the likely shape of an adaptor-signature leg) are bech32m (BIP350), so
+  // that format is named here next to the legacy bech32 (v0) and base58check forms.
+  bitcoin: Object.freeze({
+    vm: "bitcoin",
+    addressFormat: "base58check-or-bech32-or-bech32m",
+    settlementKind: "utxo-script",
+    refKind: "script",
+    txRef: "txid",
+  }),
+});
+
+/** The profile for a VM, or null. An unknown VM is never silently treated as EVM. */
+export const profileOf = (vm) => VM_PROFILES[vm] || null;

package/src/lock.mjs

@@ -99,12 +99,10 @@ export async function send(request, wallet, deps = {}) {
       send: (tx) => wallet.send(tx),
       // NORMALISING THE RECEIPT ARGUMENT'S SHAPE - HERE, AT THE CORE'S BOUNDARY, NOT AT EVERY CALLER.
       //
-      // www/js/evm/funding.js calls the receipt with an OBJECT { hash } (waitReceipt), while the adapter contract
-      // declares receipt(txHash: string). A strict adapter (sdk/src/adapters/evm-wallet.mjs) answers bad-input to
-      // an object, the refusal is SWALLOWED by the receipt wait, and the escrow address is silently replaced with
-      // the PREDICTED one - that is, the "address from the receipt" check stops working without saying so. We
-      // normalise the argument to a string here: funding.js is foreign code and must not be edited, and every
-      // adapter should not repeat the normalisation.
+      // funding.js calls the receipt with an OBJECT { hash } (waitReceipt), while the adapter contract declares
+      // receipt(txHash: string). A strict adapter (sdk/src/adapters/evm-wallet.mjs) answers bad-input to an object,
+      // the refusal is SWALLOWED by the receipt wait, and the address would silently fall back. We normalise the
+      // argument to a string at this boundary so every adapter sees one shape.
       receipt: (arg) => wallet.receipt(typeof arg === "string" ? arg : (arg && typeof arg.hash === "string" ? arg.hash : arg)),
     });
   } catch (error) {

package/src/order.mjs

@@ -1,15 +1,18 @@
 // THE COUNTERPARTY'S SIDE AND THE JOINT ADDRESS.
 //
-// TWO CHECKS, BOTH MANDATORY BEFORE SIGNING - after it there is nothing to fix:
+// THREE CHECKS, ALL MANDATORY BEFORE SIGNING - after it there is nothing to fix:
 //
 //   1) the DLEQ proof stands in the CONTEXT OF THIS order: the counterparty proved for our terms, not for others.
 //      The context is the same one the quote signature is bound to (see quotes.firm);
 //   2) the proven ed25519 point is THE VERY ONE that will go into the contract and from which the address is
 //      assembled. Without this check the counterparty could prove one thing and substitute another: on our side
 //      everything would look sound, and the discrepancy would surface when claiming the XMR, with nothing left to
-//      fix.
+//      fix;
+//   3) the proven secp256k1 point matches `commitHalfClaimer`, the commitment the contract compares on claim and
+//      refund. A proof without this comparison binds the wrong half and the escrow rejects it after the other side
+//      has paid.
 //
-// Both are done by the engine (order.js: the verifying code is the same for us and for the counterparty). The
+// All three are done by the engine (order.js: the verifying code is the same for us and for the counterparty). The
 // core has no cryptography of its own and should not: a copy would silently drift from the original.
 import { SdkError } from "./errors.mjs";
 import { primitives } from "./primitives.mjs";
@@ -86,6 +89,43 @@ const sameFormAsPoint = (proof) => (proof && typeof proof === "object" && proof.
 // "no point", not "point in another form".
 const pointForm = (v) => (typeof v === "string" && v ? norm(v) : v);
 
+// THE COUNTERPARTY'S VIEW MATERIAL HAS TWO SPELLINGS, AND THEY MUST AGREE. A quote carries `viewHalfClaimer`
+// (and sometimes `viewHalf`), a point as `viewPoint` or `viewPub`. The guard and the builder used to prefer
+// different names: the guard took the half first and ignored the point, the builder took the point first. A
+// counterparty could then supply a half and a different point, the address was built from one and the recovery
+// words from the other. Normalise once, refuse conflicting aliases, and derive the point from the half when only
+// the half is present.
+export function normalizeCounterpartyView(counterparty) {
+  const cp = counterparty && typeof counterparty === "object" ? counterparty : {};
+  const halves = [cp.viewHalf, cp.viewHalfClaimer].filter((v) => v !== undefined && v !== null && v !== "");
+  let half = null;
+  if (halves.length) {
+    try { half = BigInt(String(halves[0])); } catch { throw new SdkError("bad-input", { field: "counterparty", why: "view-half" }); }
+    for (const other of halves.slice(1)) {
+      let n = null;
+      try { n = BigInt(String(other)); } catch { n = null; }
+      if (n === null || n !== half) throw new SdkError("bad-input", { field: "counterparty", why: "conflicting-view-half" });
+    }
+  }
+  const points = [cp.viewPoint, cp.viewPub].filter((v) => v !== undefined && v !== null && v !== "");
+  let point = null;
+  if (points.length) {
+    point = pointForm(points[0]);
+    if (!isPoint(point)) throw new SdkError("bad-input", { field: "counterparty", why: "view-point" });
+    for (const other of points.slice(1)) {
+      if (pointForm(other) !== point) throw new SdkError("bad-input", { field: "counterparty", why: "conflicting-view-point" });
+    }
+  }
+  if (half !== null) {
+    let derived = null;
+    try { derived = pointForm(builder().pointOf(half)); } catch { derived = null; }
+    if (!derived) throw new SdkError("bad-input", { field: "counterparty", why: "view-half" });
+    if (point !== null && point !== derived) throw new SdkError("bad-input", { field: "counterparty", why: "view-half-point-mismatch" });
+    point = derived;
+  }
+  return { half: half === null ? null : halves[0], point };
+}
+
 /**
  * Our side of the order. It is built by the engine's builder: two halves, their points, the DLEQ PROOF (it is
  * bound to the order terms and so is not computed without the context) and the side's encryption key.
@@ -136,11 +176,12 @@ export function acceptCounterparty({ context, side = null, counterparty = null,
     // (rfq/orderQuote.mjs). While only `edPub`/`viewPub` were accepted, the facade's own side was NOT accepted:
     // start answered bad-input { field: "counterparty", missing: ["edPub"] } to its own answer. The engine knew
     // this mapping (sdk/src/swap-flow.mjs: edPub: quote.edPointClaimer). We accept BOTH names.
+    const view = normalizeCounterpartyView(counterparty);
     accepted = {
       proof: sameFormAsPoint(counterparty.proof),
       edPub: pointForm(counterparty.edPub || counterparty.edPoint || counterparty.edPointClaimer || pub.ed || null),
-      viewPoint: pointForm(counterparty.viewPoint || counterparty.viewPub || null),
-      viewHalf: counterparty.viewHalf || counterparty.viewHalfClaimer || null,
+      viewPoint: view.point,
+      viewHalf: view.half,
       // THE COUNTERPARTY'S SPEND HALF: HIS commitment (commitHalfClaimer) is computed from it where it did not
       // arrive ready-made. Without the half the commitment cannot be obtained - and that is named null, not invented.
       half: counterparty.half !== undefined ? counterparty.half : null,
@@ -155,13 +196,18 @@ export function acceptCounterparty({ context, side = null, counterparty = null,
     // not what the page runs on.
     const mock = builder().newSide(context, true);
     accepted = { proof: sameFormAsPoint(mock.proof), edPub: norm(mock.pub.ed), viewPoint: norm(mock.viewPub),
-      viewHalf: mock.viewHalf, half: mock.half, commitHalfClaimer: null, sealed: null, providerId: null, standIn: true, mock };
+      viewHalf: mock.viewHalf, half: mock.half,
+      // THE STAND-IN DOES CARRY A COMMITMENT: it is derived from the half it just built, by the same formula
+      // the contract uses. The proof check below is therefore the real one, not a path that skips it.
+      commitHalfClaimer: norm(builder().halfCommitment(mock.half)), sealed: null, providerId: null, standIn: true, mock };
   } else {
     throw new SdkError("bad-input", { field: "counterparty" });
   }
   const missing = [];
   if (!accepted.proof) missing.push("proof");
   if (!accepted.edPub) missing.push("edPub");
+  // THE COMMITMENT IS NOT OPTIONAL. Without it the proof says nothing about the half the contract will compare.
+  if (!accepted.commitHalfClaimer) missing.push("commitHalfClaimer");
   if (missing.length) throw new SdkError("bad-input", { field: "counterparty", missing });
   // OPENING THE SEALED PACKAGE - BY THE SAME ENGINE CALL, and the key is OURS (the package is addressed to us).
   // The envelope's composition is locked separately (www/js/atomic/halfenc.js, HALFENC_LOCK_REASON): in the live
@@ -169,7 +215,7 @@ export function acceptCounterparty({ context, side = null, counterparty = null,
   // with a refusal rather than passing itself off as a working key handover.
   const ownEncPriv = accepted.sealed && side && side.enc ? side.enc.priv : null;
   let verdict = null;
-  try { verdict = builder().verifySide({ proof: accepted.proof, pub: { ed: accepted.edPub } }, context, accepted.sealed, ownEncPriv); }
+  try { verdict = builder().verifySide({ proof: accepted.proof, pub: { ed: accepted.edPub }, commitHalfClaimer: accepted.commitHalfClaimer }, context, accepted.sealed, ownEncPriv); }
   catch { throw new SdkError("bad-input", { field: "counterparty" }); }
   if (!verdict || verdict.ok !== true) {
     throw new SdkError("quote-refused", { step: "proof", why: verdict && verdict.reason ? "rejected" : "unknown" });

package/src/public/networks.d.ts

@@ -21,10 +21,23 @@ export interface ChainUniswap {
   [field: string]: unknown;
 }
 
+/** What a settlement side looks like: address format, account/UTXO settlement and reference shape. Metadata, not a
+ * claim that a driver exists. */
+export interface SettlementProfile {
+  vm: string;
+  addressFormat: string;
+  settlementKind: "contract" | "program" | "utxo-script" | string;
+  refKind: "address" | "pda" | "script" | string;
+  txRef: "hash" | "signature" | "txid" | string;
+}
+
 export interface Chain {
   id: string;
   name: string;
-  vm: string;
+  /** A registry chain names its VM; the type allows null so an unknown network is never read as EVM. */
+  vm: string | null;
+  /** Present when the VM has a profile; unknown VMs are null, never silently EVM. */
+  settlementProfile?: SettlementProfile | null;
   chainId: number;
   caip2?: string;
   testnet?: boolean;

package/src/public/recovery.d.ts

@@ -275,6 +275,8 @@ export declare const RECOVERY_KEY_STORE: string;
 export declare const RECOVERY_KEY_FILE_MAGIC: string;
 /** The domain half derivation binds to; the chain id and swap number join it. */
 export declare const RECOVERY_KEY_DOMAIN: string;
+/** The salt-based derivation domain; the chain, factory, role and order salt join it. */
+export declare const RECOVERY_KEY_DOMAIN_V2: string;
 /** The domain of the counterparty's view half, derived from the same one key. */
 export declare const MAKER_VIEW_HALF_DOMAIN: string;
 /** The encrypted backup envelope version. */
@@ -290,6 +292,8 @@ export interface RecoveryKey {
   readonly mnemonic: string;
   readonly fingerprint: string;
   readonly createdAt: string;
+  /** True only after the person confirmed that the key is saved; a key in storage is not proof of that. */
+  readonly backupConfirmed?: boolean;
 }
 
 /** A derived swap number: the halves cross JSON as hex scalars. */
@@ -305,6 +309,15 @@ export interface TakerHalves {
   readonly spendCommitment: string;
 }
 
+/** A salt-based derivation: no number is reserved, and the public order salt is the input. */
+export interface TakerHalvesV2 extends Omit<TakerHalves, "index"> {
+  readonly index: null;
+  readonly derivation: "salt-v2";
+  readonly factory: string;
+  readonly role: string;
+  readonly salt: string;
+}
+
 /** One order found by the key's commitments. */
 export interface FoundSwap {
   readonly escrow: string;
@@ -338,12 +351,17 @@ export interface FoundSwap {
    * the expected clone. */
   readonly xmrAmount: string | null;
   readonly xmrAmountReason: "event" | "no-code-reader" | "code" | "not-clone" | null;
-  readonly index: number;
+  /** The v1 swap number; null for a salt-based v2 order. */
+  readonly index: number | null;
+  /** Which derivation found this order. v1 orders keep recovering through the index path. */
+  readonly derivation: "index-v1" | "salt-v2";
+  /** The factory the order was read from; the v2 binding needs it. */
+  readonly factory: string;
   readonly side: "locker" | "claimer";
   /** The Monero height a withdrawal may start from, derived from the order's block time. Null when the caller did
    * not pass the readers; `startHeightReason` then names why. */
   readonly startHeight: number | null;
-  readonly startHeightReason: "no-block-number" | "no-height-readers" | "monero-nodes-unreachable" | "monero-network-mismatch" | "no-block-time" | "monero-header" | null;
+  readonly startHeightReason: "no-block-number" | "no-height-readers" | "monero-nodes-unreachable" | "monero-network-mismatch" | "no-block-time" | "block-time-read" | "monero-header" | null;
 }
 
 /** A storage adapter: the same shape the SDK store takes. */
@@ -361,8 +379,16 @@ export declare function importRecoveryKey(mnemonic: string, options?: { createdA
 export declare function fingerprintOf(mnemonic: string): string;
 /** The binding for a chain and swap number: `ninsei-taker-v1|<chainId>|<index>`. */
 export declare function recoveryBinding(chainId: number, index: number): string;
+/** The salt-based binding: `ninsei-taker-v2|<chainId>|<factory>|<role>|<salt>`. */
+export declare function recoveryBindingV2(request: { chainId: number; factory: string; role?: string; salt: string }): string;
+/** Normalises a 32-byte salt from an event word, a hex string, a bigint or a safe integer. */
+export declare function recoverySaltOf(value: string | number | bigint): string;
+/** A fresh 32-byte public salt for one salt-based order. */
+export declare function newRecoverySalt(): string;
 /** Derives the taker spend and view halves for one swap number. */
 export declare function takerHalves(request: { mnemonic: string; chainId: number; index: number }): TakerHalves;
+/** Derives the taker halves from a public per-order salt; no index is reserved. */
+export declare function takerHalvesV2(request: { mnemonic: string; chainId: number; factory: string; role?: string; salt: string }): TakerHalvesV2;
 /** The stable backup name, with `DO-NOT-DELETE` in it on purpose. */
 export declare function recoveryKeyFileName(request: { mnemonic?: string; fingerprint?: string; createdAt?: string | Date }): string;
 /** A plain backup file: readable header above the words. */
@@ -372,9 +398,9 @@ export declare function createRecoveryKeyFile(request: { mnemonic: string; creat
 /** Reads a plain or encrypted backup file and validates the words. */
 export declare function openRecoveryKeyFile(contents: string, passphrase?: string): Promise<RecoveryKey>;
 /** Saves the key through a storage adapter. */
-export declare function saveRecoveryKey(storage: RecoveryKeyStorage, key: RecoveryKey & { nextIndex?: number; reserved?: Record<string, unknown>; retired?: Record<string, unknown> }): RecoveryKey;
+export declare function saveRecoveryKey(storage: RecoveryKeyStorage, key: RecoveryKey & { nextIndex?: number; reserved?: Record<string, unknown>; retired?: Record<string, unknown>; backupConfirmed?: boolean }): RecoveryKey;
 /** Reads the key from a storage adapter, or null. */
-export declare function loadRecoveryKey(storage: RecoveryKeyStorage): (RecoveryKey & { nextIndex: number; reserved: Record<string, unknown>; retired: Record<string, unknown> }) | null;
+export declare function loadRecoveryKey(storage: RecoveryKeyStorage): (RecoveryKey & { nextIndex: number; reserved: Record<string, unknown>; retired: Record<string, unknown>; backupConfirmed?: boolean }) | null;
 /** Reserves a swap number; the caller releases it if the request is abandoned. */
 export declare function reserveRecoveryIndex(storage: RecoveryKeyStorage, request: { chainId: number; swapId?: string | null }): number;
 /** True when an order already holds this number's commitment on chain. A page that starts swaps without the SDK's
@@ -403,7 +429,9 @@ export declare function findSwaps(request: {
   /** The factory's deployment block from the chain registry; used when `fromBlock` is omitted. */
   deploymentBlock?: number | null;
   toBlock?: number | string;
+  /** Deprecated and ignored: discovery no longer stops after a run of empty numbers. */
   gap?: number;
+  /** The last index to try. Defaults to the allocator's ceiling; a smaller value returns `complete: false`. */
   maxIndex?: number;
   /** Reads the settlement block timestamp, in seconds: (blockNumber) -> seconds. */
   evmBlockTime?: (blockNumber: number) => Promise<number>;
@@ -420,4 +448,13 @@ export declare function findSwaps(request: {
   moneroNetwork?: string | null;
   /** The fetch used for those node requests; absent - the global fetch. */
   fetchImpl?: typeof fetch;
-}): Promise<{ swaps: FoundSwap[]; scanned: number }>;
+}): Promise<{
+  swaps: FoundSwap[];
+  scanned: number;
+  /** The last index tried, or null when no index was scanned. */
+  searchedUpTo: number | null;
+  /** True only when the whole allocator range was searched. */
+  complete: boolean;
+  /** `max-index` when a smaller caller-supplied bound stopped the search. */
+  incompleteReason?: string;
+}>;

package/src/public/recovery.mjs

@@ -25,6 +25,7 @@ export {
 export {
   RECOVERY_KEY_ALG,
   RECOVERY_KEY_DOMAIN,
+  RECOVERY_KEY_DOMAIN_V2,
   RECOVERY_KEY_ENVELOPE_VERSION,
   RECOVERY_KEY_FILE_MAGIC,
   RECOVERY_KEY_ITER,
@@ -39,13 +40,17 @@ export {
   fingerprintOf,
   importRecoveryKey,
   loadRecoveryKey,
+  newRecoverySalt,
   openRecoveryKeyFile,
   recoveryBinding,
+  recoveryBindingV2,
   recoveryIndexTaken,
+  recoverySaltOf,
   recoveryKeyFileName,
   recoveryKeyText,
   releaseRecoveryIndex,
   reserveRecoveryIndex,
   saveRecoveryKey,
   takerHalves,
+  takerHalvesV2,
 } from "../recovery-key.mjs";