@ninsei-labs/sdk 0.52.0 → 0.53.0

package/src/public/xmr.d.ts

@@ -407,17 +407,18 @@ export declare function judgeDaemonAddress(
   options?: { network?: string; allowPlainLoopback?: boolean },
 ): DaemonAddressJudgement;
 
-/** A per-KB price -> the fee for a transaction of `bytes`, rounded UP. Throws on a non-integer or a negative input. */
-export declare function feeForBytes(feePerKB: bigint | number | string, bytes: bigint | number | string): string;
+/** A per-byte price -> the fee for a transaction of `bytes`/weight. Exact integer multiplication. */
+export declare function feeForBytes(feePerByte: bigint | number | string, bytes: bigint | number | string): string;
 
 export interface FeeEstimateOk {
   readonly ok: true;
   readonly url: string;
-  /** The price per kilobyte for the next block, in atomic units, or null when the daemon did not send it. */
-  readonly feePerKB: string | null;
-  readonly medianFeePerKB: string | null;
-  /** The daemon's own priority list, in its order, or null. */
+  /** The price per byte for the next block, in atomic units, or null when the daemon did not send it. */
+  readonly feePerByte: string | null;
+  /** The daemon's own priority list, per byte and in its order, or null. */
   readonly perPriority: readonly string[] | null;
+  /** The unit the final fee is rounded to, or null when the daemon did not send it. */
+  readonly quantizationMask: string | null;
 }
 
 export interface FeeEstimateRefusal {
@@ -430,7 +431,7 @@ export interface FeeEstimateRefusal {
 
 /**
  * ASK A NODE WHAT A TRANSACTION WILL COST (`get_fee_estimate`). The exact sum needs the assembled transaction, so
- * this is a price per kilobyte; `feeForBytes` is the only arithmetic that turns it into a fee. Never throws.
+ * this is a price per byte; `feeForBytes` is the only arithmetic that turns it into a fee. Never throws.
  */
 export declare function moneroFeeEstimate(options: {
   url: string;
@@ -483,6 +484,19 @@ export interface ScannedMatch {
   [field: string]: unknown;
 }
 
+/** A range scan's answer: the per-address totals and whether every block was read. */
+export interface ScanRangeResult {
+  readonly fromHeight: number;
+  readonly toHeight: number;
+  readonly results: ScannedMatch[];
+  /** False when at least one block or its transactions could not be read. */
+  readonly complete: boolean;
+  /** The heights that failed; empty when `complete` is true. */
+  readonly missingHeights: number[];
+  /** `blocks-unreadable` when `complete` is false. */
+  readonly incompleteReason?: "blocks-unreadable";
+}
+
 /** Walk a block range and return the transactions that pay a watched address. */
 export declare function scanRange(options: {
   daemonUrl: string;
@@ -492,4 +506,8 @@ export declare function scanRange(options: {
   log?: (event: unknown) => void;
   concurrency?: number;
   nowSec?: number | null;
-}): Promise<ScannedMatch[]>;
+  /** The chain tip used to judge a height lock; defaults to `toHeight`. Inclusion height still drives confirmations. */
+  tipHeight?: number | null;
+  /** The fetch used for the daemon requests; absent - the global fetch. */
+  fetchImpl?: typeof fetch;
+}): Promise<ScanRangeResult>;

package/src/quotes.mjs

@@ -16,9 +16,11 @@
 //   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 { SDK_VERSION } from "./version.mjs";
 import * as engine from "./engine.mjs";
 import { orderQuoteMissingFields, recoverOrderQuoteKey } from "./quoteEip712.mjs";
 import { claimGasGiftWei } from "../engine/evm/claimGas.js";
+import { parseXmr } from "../engine/core/xmrAmount.js";
 // 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.
@@ -398,7 +400,12 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
     // plus the priority part of the gas price. A buy quote has no tip; a sale is the only route where one exists.
     async sale(request) {
       if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
-      const payload = request.request && typeof request.request === "object" ? request : { request };
+      // THE NODE GATES THE THREE BROWSER BODY ROUTES ON THE CLIENT'S SDK LINE. The value is the package's own
+      // baked-in version, not a caller field: a caller cannot claim a line it was not built from.
+      // THE ENVELOPE IS THE REQUEST. The node accepts both `{ request: {...} }` and a bare body; every check below
+      // must read the same object the node priced, not the outer envelope that carries only `sdkVersion`.
+      const saleRequest = request.request && typeof request.request === "object" ? request.request : request;
+      const payload = { ...(request.request && typeof request.request === "object" ? request : { request }), sdkVersion: SDK_VERSION };
       let res = null;
       try {
         res = await http.tryJson(config.route("orderSell"), {
@@ -412,6 +419,162 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       const ticket = res.body;
       const quote = (ticket.handoff && ticket.handoff.quote) || ticket.quote || null;
       if (!quote || typeof quote !== "object") fail("quote-field-unbound", { step: "order-sell", field: "quote" });
+      // THE SALE TICKET IS A SIGNED QUOTE, AND IT GETS THE SAME GATES AS `firm`: every field of the signed set,
+      // its expiry, the EIP-712 signature and the named key, the registry's provider mapping, the interface's
+      // allow-list, and the factory/implementation policy. The one difference is the binding below: a sale has no
+      // caller-supplied order terms, so its context is checked against `ticket.order` when the node returns it.
+      // 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 });
+        }
+      }
+      // THE IMPLEMENTATION THE CLONES WILL EXECUTE (#114). A pinned factory CODE is not enough on its own: the
+      // implementation ADDRESS lives in the factory's STORAGE, so the client re-reads the pair the factory itself
+      // checks (implementation() / implementationCodeHash()) and the CODE at that address, then applies the same
+      // verdict (verifyFactoryImplementationOnChain). A delegatecall to an address WITHOUT code SUCCEEDS, so a
+      // clone without an implementation would take the ETH and its markReady/claim/refund would appear to go
+      // through while doing nothing - that is exactly the case this refuses. The live code is re-hashed here, so
+      // the verdict does not trust the factory's own answer alone.
+      if (implementationPolicy) {
+        if (typeof evmCall !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-chain-read" });
+        if (typeof evmCode !== "function") fail("quote-factory-unchecked", { step: "factory", why: "no-code-read" });
+        const verdict = await engine.evm.verifyFactoryImplementationOnChain({
+          factory: declaredFactory,
+          read: evmCall,
+          code: (address) => evmCode(address),
+          policy: implementationPolicy,
+          hashCode: (codeHex) => bytesToHexQ(keccak256(hexToBytesQ(codeHex) || new Uint8Array(0))),
+        });
+        if (!verdict.ok) {
+          const unknown = verdict.why === "implementation-code-unknown" ||
+            verdict.why === "implementation-code-mismatch" || verdict.why === "implementation-has-no-code";
+          fail(unknown ? "quote-factory-code-unknown" : "quote-factory-unchecked",
+            { step: "factory", why: verdict.why, factory: declaredFactory, implementation: verdict.implementation || null });
+        }
+      }
+      // THE PERSON SELLING IS THE CLAIMER. The interface's denylist is applied to that address, not to a
+      // caller-chosen value: a ticket that names a denied claimer must not reach the funding step.
+      const saleClaimer = String((saleRequest && saleRequest.claimer) || quote.claimer || "").toLowerCase();
+      if (saleClaimer && denylist && denylist.has(saleClaimer)) fail("address-denied", { step: "order-sell" });
+      if (saleRequest && saleRequest.claimer && quote.claimer && String(saleRequest.claimer).toLowerCase() !== String(quote.claimer).toLowerCase()) {
+        fail("quote-refused", { step: "order-sell", why: "claimer-not-bound" });
+      }
+      // THE XMR THE CALLER ASKED FOR IS THE XMR THE QUOTE SIGNED. A ticket is paid against the signed `xmrAmount`;
+      // accepting a different requested amount shows one figure and settles another.
+      const requestedXmr = saleRequest && (saleRequest.xmr !== undefined ? saleRequest.xmr
+        : (saleRequest.xmrAmount !== undefined ? saleRequest.xmrAmount : null));
+      if (requestedXmr !== null && requestedXmr !== undefined) {
+        let wanted = null;
+        try { wanted = BigInt(String(requestedXmr)); } catch { wanted = null; }
+        // A whole-XMR request (the public `xmr` field) is converted with the package's own parser; digits are
+        // already atomic. A value that cannot be read is a refusal, not a skipped check.
+        if (wanted === null || wanted < 10n ** 12n) {
+          try { wanted = parseXmr(String(requestedXmr)); } catch { wanted = null; }
+        }
+        let signedAtomic = null;
+        try { signedAtomic = quote.xmrAmount === undefined || quote.xmrAmount === null || quote.xmrAmount === ""
+          ? null : BigInt(String(quote.xmrAmount)); } catch { signedAtomic = null; }
+        if (signedAtomic === null || wanted === null || wanted !== signedAtomic) {
+          fail("quote-refused", { step: "order-sell", why: "xmr-amount" });
+        }
+      }
+      // THE CONTEXT WHEN THE TICKET CARRIES ITS ORDER. The signed quote binds the order terms; when the node
+      // returns the order it priced, recompute the context with our own engine and refuse a mismatch.
+      if (ticket.order && typeof ticket.order === "object") {
+        // THE RETURNED ORDER MUST BE THE SIGNED ONE FIELD BY FIELD. `quote.context` is a derived label, not a
+        // signed field; comparing only it lets a node return another amount with a matching relabelled context.
+        const sameValue = (a, b) => String(a === undefined || a === null ? "" : a).replace(/^0x/i, "").toLowerCase()
+          === String(b === undefined || b === null ? "" : b).replace(/^0x/i, "").toLowerCase();
+        for (const name of ["locker", "claimer", "amount", "readyBy", "t1", "salt"]) {
+          if (!sameValue(ticket.order[name], quote[name])) {
+            fail("quote-refused", { step: "order-sell", why: "other-terms", field: name });
+          }
+        }
+        // The context remains a useful cross-check when both sides carry it.
+        if (quote.context) {
+          let expectedSaleContext = null;
+          try { expectedSaleContext = engine.orderContext.orderContextString(ticket.order); } catch { expectedSaleContext = null; }
+          if (expectedSaleContext !== null && String(quote.context) !== expectedSaleContext) {
+            fail("quote-refused", { step: "order-sell", why: "other-terms", field: "context" });
+          }
+        }
+      }
       // THE TICKET'S TIP MUST BE THE SIGNED ONE. The node returns both the ticket's `claimTip` object and the quote it
       // signed; a difference means the figure shown to the person is not the figure the escrow will pay.
       const shown = ticket.claimTip && ticket.claimTip.wei !== undefined && ticket.claimTip.wei !== null
@@ -467,7 +630,7 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ providerId: request.providerId, order: request.order,
-            ...(viewHalfClaimer === null ? {} : { viewHalfClaimer }) }),
+            ...(viewHalfClaimer === null ? {} : { viewHalfClaimer }), sdkVersion: SDK_VERSION }),
         });
       } catch (error) {
         if (error && error.code === "bad-input") throw error;

package/src/recovery-key.mjs

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

package/src/recovery.mjs

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

package/src/swap-flow.mjs

@@ -193,7 +193,8 @@ export async function runAtomicOrder({
       // string, and that turned the check into a ritual: the stand-in's proof was bound to a different string,
       // that is, to nothing. Now exactly the path a real provider would take is checked.
       const mock = await worker.buildSide(orderContext);
-      counter = { proof: mock.proof, edPub: mock.pub.ed, mock, viewHalf: mock.viewHalf, viewPoint: mock.viewPub };
+      counter = { proof: mock.proof, edPub: mock.pub.ed, mock, viewHalf: mock.viewHalf, viewPoint: mock.viewPub,
+        commitHalfClaimer: (await worker.halfCommitment(mock.half)).commitment };
     }
     // THE COUNTERPARTY CHECK REMAINS ONE AND IT IS THE MAIN ONE: the DLEQ proof in the context of this order.
     // It confirms that both public points stand for ONE scalar - that is, that the half declared for the Monero
@@ -203,7 +204,7 @@ export async function runAtomicOrder({
     // receive: without that check a correct proof would guarantee nothing about the chain.
     say("verify", "dleq");
     const verdict = await worker.verifyCounterparty(orderContext, {
-      proof: counter.proof, edPub: counter.edPub,
+      proof: counter.proof, edPub: counter.edPub, commitHalfClaimer: counter.commitHalfClaimer,
     }, null);
     if (!verdict.ok) throw new SdkError("quote-refused", { step: "proof", why: "rejected" });