@ninsei-labs/sdk 0.46.2 → 0.48.0

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.48.0 — 2026-10-21
+
+A SWAP CAN START FROM THE ONE RECOVERY KEY.
+
+- `swaps.start` accepts `recoveryKey` (a BIP39 mnemonic or a key object). It derives the spend and view halves
+  for the reserved swap number instead of generating a random pair, and writes no per-swap recovery file.
+- A key created by the call is handed to `onRecoveryKey` once, before the funds are locked; a key already in the
+  store is not shown again. The number is reserved before the order and retired only after the escrow exists.
+- The old path is unchanged: without `recoveryKey`, `onRecoveryFile` still assembles and confirms a per-swap file.
+- `buildOwnSideFromHalves` builds the order side and its DLEQ proof from supplied halves; `createRecord` accepts
+  that side, so the recovery key remains the only taker secret.
+
+## 0.47.0 — 2026-10-21
+
+ONE RECOVERY KEY, AND THE NODE'S VIEW HALF COMES FROM IT.
+
+- `@ninsei-labs/sdk/recovery` exposes a BIP39 12-word taker key: creation, import, fingerprint, the
+  `ninsei-recovery-key-DO-NOT-DELETE-...` backup file (plain or AES-GCM/PBKDF2), and a storage adapter for the key.
+- `takerHalves({ mnemonic, chainId, index })` derives the taker spend/view halves with
+  `ninsei-taker-v1|<chainId>|<index>`, and the counterparty view half with `ninsei-maker-view-v1`. The taker sends
+  the latter to the node (`viewHalfClaimer` on a direct quote, `viewHalfLocker` on a reverse ticket); the node
+  accepts it and keeps the joint view key.
+- `findSwaps({ mnemonic, chainId, factory, address?, evmLogs, ... })` reads `OrderCreated`, filters by the indexed
+  locker/claimer when an address is given, matches `commitHalfLocker`/`commitHalfClaimer` locally, and stops after
+  five numbers in a row with no order.
+- Numbers are reserved in the store: released numbers are reused, numbers seen on chain are retired.
+- The current per-swap recovery file and `swaps.start` are unchanged. The switch is a separate change.
+
 ## 0.46.2 — 2026-10-21
 
 THE TESTNET CONFIG NAMES THE CLAIMTIP DEPLOYMENT.

package/index.d.ts

@@ -717,7 +717,7 @@ export interface SwapsApi {
   /**
    * Start a swap. The SDK holds the step order, not the screen:
    *   1) guards (preflight); 2) the swap record (createSwap); 3) the order - it GENERATES the key halves;
-   *   4) the recovery file and the interface's confirmation that the file is saved; 5) locking the funds (signature);
+   *   4) the recovery file / one key and the interface's confirmation that it is saved; 5) locking the funds (signature);
    *   6) saving on the server; 7) opening the watch on the Monero address.
    * HALVES DO NOT EXIST BEFORE THE ORDER: the recovery file carries MY half of the spend key and the counterparty's
    * open points, and they are taken from the signed order (www/js/atomic/order-worker.js, createOrderBuilder; in the
@@ -1102,10 +1102,24 @@ export interface StartRequest {
    */
   readonly wallet?: WalletAdapter;
   /**
-   * Hand the recovery file to the interface and wait for the person's decision.
+   * Hand the OLD per-swap recovery file to the interface and wait for the person's decision.
    * `true` - the person confirmed the file is saved; `false` - the swap is not started.
+   * Not used when `recoveryKey` is present: that path has one key, saved once.
    */
-  onRecoveryFile(file: RecoveryFile): Promise<boolean>;
+  onRecoveryFile?(file: RecoveryFile): Promise<boolean>;
+  /**
+   * THE ONE RECOVERY KEY (sdk#76). A BIP39 mnemonic, or a key object from `@ninsei-labs/sdk/recovery`.
+   * When present, the swap's spend and view halves are derived from it instead of being generated, and no
+   * per-swap recovery file is written. The key is kept through the SDK's storage adapter.
+   */
+  recoveryKey?: string | { readonly mnemonic: string };
+  /** The swap number, when the caller already reserved one. Absent - the SDK reserves the next free number. */
+  recoveryIndex?: number;
+  /**
+   * Hand the key backup to the interface, ONCE, when this call created the key. `true` - the person saved it;
+   * `false` - the swap is not started. A key already in the store is not shown again.
+   */
+  onRecoveryKey?(file: RecoveryFile): Promise<boolean>;
 }
 
 export interface RecoveryFile {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.46.2",
+  "version": "0.48.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -42,7 +42,8 @@
     "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:node-probe": "node tools/check-node-probe.mjs",
+    "check:recovery-key": "node tools/check.mjs --only=recovery-key"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -120,6 +121,7 @@
   "dependencies": {
     "@noble/curves": "^2.4.0",
     "@noble/hashes": "^2.4.0",
+    "@scure/bip39": "2.4.0",
     "keccak256": "^1.0.6"
   },
   "sideEffects": false

package/src/order.mjs

@@ -97,6 +97,29 @@ export function buildOwnSide(order, onBit) {
   return { context, side, spendPoint: norm(side.pub.ed), viewPoint: norm(side.viewPub), encPub: norm(side.enc.pub) };
 }
 
+/**
+ * OUR SIDE FROM HALVES WE ALREADY HAVE - the one recovery key case. A random side would be a second secret,
+ * which is exactly what one key removes. The proof is still bound to this order and built by the same engine
+ * builder; only the source of the two numbers changes.
+ */
+export function buildOwnSideFromHalves(order, { spendHalf, viewHalf } = {}) {
+  const context = contextOf(order);
+  const b = builder();
+  const scalar = (value, name) => {
+    const n = BigInt(value);
+    if (n <= 0n || n >= BigInt(b.halves.LIMIT)) throw new SdkError("bad-input", { field: name });
+    return n;
+  };
+  const half = scalar(spendHalf, "spendHalf");
+  const view = scalar(viewHalf, "viewHalf");
+  const pub = b.halves.publicHalves(half);
+  const viewPub = b.halves.publicHalves(view).ed;
+  const encPair = b.enc.recipientKeyPair();
+  const proof = b.dleq.prove(half, context);
+  const side = { half, pub, viewHalf: view, viewPub, enc: encPair, proof, standIn: false };
+  return { context, side, spendPoint: norm(pub.ed), viewPoint: norm(viewPub), encPub: norm(encPair.pub) };
+}
+
 /**
  * The counterparty's side: accept and verify. The check is ONE for both sides and is done by the engine
  * (order.js, verifySide): the proof stands in the CONTEXT OF THIS order, the proven point matches the one that

package/src/public/recovery.d.ts

@@ -259,3 +259,120 @@ export declare function createRecoveryFile(payload: RecoveryPayload, passphrase:
  * yet. Stable, so a repeated download shows up as a second copy of one name rather than a new random file.
  */
 export declare function recoveryFileName(swapId?: string | null): string;
+
+
+// ---------------------------------------------------------------------------------------------------
+// ONE RECOVERY KEY PER BROWSER (sdk#79)
+// ---------------------------------------------------------------------------------------------------
+
+/** The version of the stored/backup key record. */
+export declare const RECOVERY_KEY_VERSION: number;
+/** Twelve words, by the BIP39 rules. */
+export declare const RECOVERY_KEY_WORDS: number;
+/** The store key a browser adapter keeps the key under. */
+export declare const RECOVERY_KEY_STORE: string;
+/** The first line of a plain backup file. */
+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 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. */
+export declare const RECOVERY_KEY_ENVELOPE_VERSION: number;
+/** The encrypted backup algorithm identifier. */
+export declare const RECOVERY_KEY_ALG: string;
+/** The PBKDF2 iteration count written into an encrypted backup. */
+export declare const RECOVERY_KEY_ITER: number;
+
+/** A key as it is kept: the words are the secret, the fingerprint is its short public name. */
+export interface RecoveryKey {
+  readonly version: number;
+  readonly mnemonic: string;
+  readonly fingerprint: string;
+  readonly createdAt: string;
+}
+
+/** A derived swap number: the halves cross JSON as hex scalars. */
+export interface TakerHalves {
+  readonly index: number;
+  readonly binding: string;
+  readonly spendHalf: string;
+  readonly viewHalf: string;
+  readonly spendPoint: string;
+  readonly viewPoint: string;
+  readonly makerViewHalf: string;
+  readonly makerViewPoint: string;
+  readonly spendCommitment: string;
+}
+
+/** One order found by the key's commitments. */
+export interface FoundSwap {
+  readonly escrow: string;
+  readonly locker: string;
+  readonly claimer: string;
+  readonly commitHalfLocker: string;
+  readonly commitHalfClaimer: string;
+  readonly edPointLocker: string;
+  readonly edPointClaimer: string;
+  readonly edViewPointLocker: string;
+  readonly amount: string;
+  readonly readyBy: number;
+  readonly t1: number;
+  readonly salt: string;
+  readonly registry: string;
+  readonly provider: string;
+  readonly quoteKey: string;
+  readonly transactionHash: string | null;
+  readonly blockNumber: number | null;
+  readonly logIndex: number | null;
+  readonly index: number;
+  readonly side: "locker" | "claimer";
+}
+
+/** A storage adapter: the same shape the SDK store takes. */
+export interface RecoveryKeyStorage {
+  get(key: string): string | null;
+  set(key: string, value: string): unknown;
+  remove(key: string): unknown;
+}
+
+/** Makes a new 12-word key. The caller saves it; nothing is stored here. */
+export declare function createRecoveryKey(options?: { createdAt?: string | Date }): RecoveryKey;
+/** Imports and validates words. */
+export declare function importRecoveryKey(mnemonic: string, options?: { createdAt?: string | Date }): RecoveryKey;
+/** The short public fingerprint (four hex characters) of the words. */
+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;
+/** Derives the taker spend and view halves for one swap number. */
+export declare function takerHalves(request: { mnemonic: string; chainId: number; index: number }): TakerHalves;
+/** 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. */
+export declare function recoveryKeyText(request: { mnemonic: string; createdAt?: string | Date }): string;
+/** A backup file, optionally encrypted with a passphrase of at least 12 characters. */
+export declare function createRecoveryKeyFile(request: { mnemonic: string; createdAt?: string | Date; passphrase?: string }): Promise<string>;
+/** 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;
+/** 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;
+/** 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;
+/** Releases a number that never reached the chain. */
+export declare function releaseRecoveryIndex(storage: RecoveryKeyStorage, index: number): void;
+/** Retires a number after its order exists on chain. */
+export declare function commitRecoveryIndex(storage: RecoveryKeyStorage, index: number): void;
+/** Finds orders whose commitment was made from the key's halves. */
+export declare function findSwaps(request: {
+  mnemonic: string;
+  chainId: number;
+  factory: string;
+  address?: string | null;
+  evmLogs: (request: { address: string; topics: (string | null)[]; fromBlock: number | string; toBlock: number | string }) => Promise<unknown[]>;
+  fromBlock?: number | string;
+  toBlock?: number | string;
+  gap?: number;
+  maxIndex?: number;
+}): Promise<{ swaps: FoundSwap[]; scanned: number }>;

package/src/public/recovery.mjs

@@ -20,3 +20,31 @@ export {
   scanStartHeight,
   validatePayload,
 } from "../../engine/recovery/recoveryFile.js";
+
+// ONE RECOVERY KEY FOR EVERY SWAP (sdk#79): the taker's key, its derivation, its file and the on-chain search.
+export {
+  RECOVERY_KEY_ALG,
+  RECOVERY_KEY_DOMAIN,
+  RECOVERY_KEY_ENVELOPE_VERSION,
+  RECOVERY_KEY_FILE_MAGIC,
+  RECOVERY_KEY_ITER,
+  RECOVERY_KEY_STORE,
+  RECOVERY_KEY_VERSION,
+  MAKER_VIEW_HALF_DOMAIN,
+  RECOVERY_KEY_WORDS,
+  commitRecoveryIndex,
+  createRecoveryKey,
+  createRecoveryKeyFile,
+  findSwaps,
+  fingerprintOf,
+  importRecoveryKey,
+  loadRecoveryKey,
+  openRecoveryKeyFile,
+  recoveryBinding,
+  recoveryKeyFileName,
+  recoveryKeyText,
+  releaseRecoveryIndex,
+  reserveRecoveryIndex,
+  saveRecoveryKey,
+  takerHalves,
+} from "../recovery-key.mjs";

package/src/record.mjs

@@ -14,7 +14,7 @@
 import { SdkError } from "./errors.mjs";
 import { primitives } from "./primitives.mjs";
 import * as engine from "./engine.mjs";
-import { buildOwnSide, halfHex, norm } from "./order.mjs";
+import { buildOwnSide, buildOwnSideFromHalves, 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
@@ -23,7 +23,11 @@ import { buildOwnSide, halfHex, norm } from "./order.mjs";
  * 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) {
+export function ownSide(order = null, known = null) {
+  if (known && known.spendHalf && known.viewHalf) {
+    const built = buildOwnSideFromHalves(order, known);
+    return built.side;
+  }
   if (order !== null && order !== undefined) {
     const built = buildOwnSide(order);
     return built.side;
@@ -40,9 +44,9 @@ export function ownSide(order = null) {
  * 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 } = {}) {
+export function createRecord(input, { order = null, side: knownSide = null } = {}) {
   if (!input || typeof input !== "object") throw new SdkError("bad-input", { field: "input" });
-  const side = ownSide(order);
+  const side = knownSide || ownSide(order);
   let swap = null;
   try { swap = engine.swap.createSwap(input); } catch { throw new SdkError("bad-input", { field: "input" }); }
   const escrow = { ...(swap.escrow || {}),

package/src/recovery-key.mjs

@@ -0,0 +1,450 @@
+// ONE RECOVERY KEY FOR EVERY SWAP: THE TAKER'S KEY, ITS HALVES, ITS FILE, AND THE SEARCH.
+//
+// The taker used to make a random secret per swap and ask a person to save a file before funding. One BIP39 key,
+// made once and saved once, removes that step. The seeds of this module are the ONLY source of the taker's
+// halves: the spend and view halves for swap number i come from halfFromSeed with a binding that is known at
+// recovery time. The factory is deliberately not part of the binding: numbers then run across a redeployment,
+// and the search reads every factory the caller names.
+//
+// THE KEY NEVER LEAVES THE CLIENT. The search sends an address and the OrderCreated topic to a log reader; it
+// never sends the words, the seed, a half or a commitment. A service that answered "which of these are mine"
+// would learn that the orders belong to one person.
+//
+// THIS MODULE DOES NOT SWITCH swaps.start. It is the foundation: the current per-swap flow keeps working until
+// the node accepts the taker's maker view half and the page is rebuilt around the key.
+
+import { generateMnemonic, mnemonicToSeedSync, validateMnemonic } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { createHalves } from "../engine/atomic/halves.js";
+import { halfCommitmentHex } from "../engine/atomic/orderHalfCommit.js";
+import { ORDER_CREATED_TOPIC } from "../engine/evm/factory.js";
+import { SdkError } from "./errors.mjs";
+import { ed25519, keccak256, randomBytes, secp256k1 } from "./primitives.mjs";
+
+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;
+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 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.
+export const MAKER_VIEW_HALF_DOMAIN = "ninsei-maker-view-v1";
+export const RECOVERY_KEY_ENVELOPE_VERSION = 1;
+export const RECOVERY_KEY_ALG = "AES-GCM-256/PBKDF2-SHA256";
+export const RECOVERY_KEY_ITER = 600000;
+const ITER_MIN = 600000;
+const ITER_MAX = 6000000;
+
+const te = new TextEncoder();
+const td = new TextDecoder();
+
+const hex32 = (value) => "0x" + BigInt(value).toString(16).padStart(64, "0");
+const pad32 = (value) => "0x" + String(value).toLowerCase().replace(/^0x/, "").padStart(64, "0");
+const b64 = (bytes) => {
+  let text = "";
+  for (const byte of bytes) text += String.fromCharCode(byte);
+  return btoa(text);
+};
+const unb64 = (text) => Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+
+const bad = (field) => new SdkError("bad-input", { field });
+const failed = (stage) => new SdkError("recovery-failed", { stage });
+
+function normalizeWords(value) {
+  if (typeof value !== "string") throw bad("mnemonic");
+  const mnemonic = value.trim().toLowerCase().replace(/\s+/g, " ");
+  if (!mnemonic || mnemonic.split(" ").length !== RECOVERY_KEY_WORDS) throw bad("mnemonic");
+  if (!validateMnemonic(mnemonic, wordlist)) throw bad("mnemonic");
+  return mnemonic;
+}
+
+function createdAtOf(value) {
+  const date = value instanceof Date ? value : value ? new Date(value) : new Date();
+  if (Number.isNaN(date.getTime())) throw bad("createdAt");
+  return date.toISOString();
+}
+
+/** A new 12-word key. The caller stores it; this function keeps nothing. */
+export function createRecoveryKey({ createdAt } = {}) {
+  const mnemonic = generateMnemonic(wordlist, 128);
+  return recoveryKeyOf(mnemonic, createdAt);
+}
+
+/** A key imported from words. Validation happens here, once. */
+export function importRecoveryKey(mnemonic, { createdAt } = {}) {
+  return recoveryKeyOf(mnemonic, createdAt);
+}
+
+function recoveryKeyOf(mnemonic, createdAt) {
+  const words = normalizeWords(mnemonic);
+  return {
+    version: RECOVERY_KEY_VERSION,
+    mnemonic: words,
+    fingerprint: fingerprintOf(words),
+    createdAt: createdAtOf(createdAt),
+  };
+}
+
+/** The first four hex characters of the key's hash: a name a person can compare, not a secret. */
+export function fingerprintOf(mnemonic) {
+  const words = typeof mnemonic === "string" ? mnemonic.trim().toLowerCase().replace(/\s+/g, " ") : "";
+  if (!words) throw bad("mnemonic");
+  return Array.from(keccak256(te.encode(words)), (b) => b.toString(16).padStart(2, "0")).join("").slice(0, 4);
+}
+
+function seedOf(mnemonic) {
+  // BIP39 defines the seed; no wallet password is used here. A wallet password is a DIFFERENT feature and would
+  // silently produce different halves.
+  return mnemonicToSeedSync(normalizeWords(mnemonic));
+}
+
+function numberField(value, field) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw bad(field);
+  return n;
+}
+
+/** The binding a swap number is derived from. The chain id keeps testnet and mainnet keys apart. */
+export function recoveryBinding(chainId, index) {
+  return `${RECOVERY_KEY_DOMAIN}|${numberField(chainId, "chainId")}|${numberField(index, "index")}`;
+}
+
+/**
+ * The taker's two halves for swap number `index`.
+ *
+ * The halves are returned as 0x-prefixed scalars (64 hex digits), not BigInt: every crossing of JSON in this
+ * 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);
+  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
+  // maker's view half no longer comes from a seed the taker cannot reproduce.
+  const makerViewHalf = halves.halfFromSeed(seed, binding, MAKER_VIEW_HALF_DOMAIN);
+  const spend = halves.publicHalves(spendHalf);
+  const view = halves.publicHalves(viewHalf);
+  const makerView = halves.publicHalves(makerViewHalf);
+  return {
+    index: numberField(index, "index"),
+    binding,
+    spendHalf: hex32(spendHalf),
+    viewHalf: hex32(viewHalf),
+    spendPoint: spend.ed,
+    viewPoint: view.ed,
+    makerViewHalf: hex32(makerViewHalf),
+    makerViewPoint: makerView.ed,
+    spendCommitment: halfCommitmentHex(spendHalf, secp256k1, keccak256),
+  };
+}
+
+// ---------------------------------------------------------------------------------------------------
+// THE BACKUP FILE
+// ---------------------------------------------------------------------------------------------------
+
+const stampOf = (createdAt) => createdAtOf(createdAt).slice(0, 10);
+
+/** The stable name a person can search for. `DO-NOT-DELETE` is part of the name on purpose. */
+export function recoveryKeyFileName({ mnemonic, fingerprint, createdAt } = {}) {
+  const fp = fingerprint || fingerprintOf(mnemonic);
+  return `ninsei-recovery-key-DO-NOT-DELETE-${stampOf(createdAt)}-${fp}.txt`;
+}
+
+function headerOf({ fingerprint, createdAt }) {
+  return [
+    RECOVERY_KEY_FILE_MAGIC,
+    "This file restores every swap made with this key.",
+    "Restore at https://recovery.ninsei.finance",
+    "Never share it with anyone, not even Ninsei.",
+    "This is not a wallet seed. Do not import it into a wallet.",
+    `Key ${fingerprint}, created ${stampOf(createdAt)}`,
+  ].join("\n");
+}
+
+/** The plain file: a readable header above the words. */
+export function recoveryKeyText({ mnemonic, createdAt } = {}) {
+  const key = recoveryKeyOf(mnemonic, createdAt);
+  return `${headerOf(key)}\n\n${key.mnemonic}\n`;
+}
+
+async function deriveKey(passphrase, salt, iter) {
+  if (!globalThis.crypto || !globalThis.crypto.subtle) throw failed("crypto-unavailable");
+  const material = await crypto.subtle.importKey("raw", te.encode(passphrase), "PBKDF2", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: iter, hash: "SHA-256" },
+    material,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+
+const aadOf = (header) => JSON.stringify({
+  kind: "ninsei-recovery-key",
+  v: header.v,
+  alg: header.alg,
+  iter: header.iter,
+  salt: header.salt,
+  iv: header.iv,
+  meta: header.meta,
+});
+
+/**
+ * The backup file, optionally protected by a password. An empty password is a choice, not an omission: the
+ * file then says so in plain text, as the unencrypted recovery envelope does.
+ */
+export async function createRecoveryKeyFile({ mnemonic, createdAt, passphrase = "" } = {}) {
+  const key = recoveryKeyOf(mnemonic, createdAt);
+  if (typeof passphrase !== "string") throw bad("passphrase");
+  if (passphrase === "") return recoveryKeyText(key);
+  if (passphrase.length < 12) throw bad("passphrase");
+  if (!globalThis.crypto || !globalThis.crypto.subtle) throw failed("crypto-unavailable");
+
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const header = {
+    v: RECOVERY_KEY_ENVELOPE_VERSION,
+    alg: RECOVERY_KEY_ALG,
+    iter: RECOVERY_KEY_ITER,
+    salt: b64(salt),
+    iv: b64(iv),
+    meta: { fingerprint: key.fingerprint, createdAt: key.createdAt },
+  };
+  const aes = await deriveKey(passphrase, salt, RECOVERY_KEY_ITER);
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, tagLength: 128, additionalData: te.encode(aadOf(header)) },
+    aes,
+    te.encode(JSON.stringify({ mnemonic: key.mnemonic }))
+  );
+  return JSON.stringify({ ...header, ciphertext: b64(new Uint8Array(ciphertext)) }, null, 2);
+}
+
+/** Read a plain or an encrypted key file. The returned key is always validated. */
+export async function openRecoveryKeyFile(contents, passphrase = "") {
+  if (typeof contents !== "string" || !contents.trim()) throw bad("file");
+  if (typeof passphrase !== "string") throw bad("passphrase");
+  const text = contents.trim();
+
+  if (!text.startsWith("{")) {
+    // THE PLAIN FILE. The header is checked by its first line, not by a loose search: a random text file must
+    // not be mistaken for a key.
+    const lines = text.split(/\r?\n/);
+    if (lines[0].trim() !== RECOVERY_KEY_FILE_MAGIC) throw failed("parse");
+    const words = lines.slice(1).map((line) => line.trim()).find((line) => line && validateMnemonic(line.toLowerCase(), wordlist));
+    if (!words) throw failed("parse");
+    return recoveryKeyOf(words);
+  }
+
+  let envelope;
+  try {
+    envelope = JSON.parse(text);
+  } catch {
+    throw failed("parse");
+  }
+  if (!envelope || envelope.v !== RECOVERY_KEY_ENVELOPE_VERSION || envelope.alg !== RECOVERY_KEY_ALG) throw failed("parse");
+  for (const field of ["salt", "iv", "ciphertext"]) if (typeof envelope[field] !== "string" || !envelope[field]) throw failed("parse");
+  const iter = Number(envelope.iter);
+  if (!Number.isInteger(iter) || iter < ITER_MIN || iter > ITER_MAX) throw failed("parse");
+  if (passphrase.length < 12) throw failed("passphrase");
+
+  let payload;
+  try {
+    const aes = await deriveKey(passphrase, unb64(envelope.salt), iter);
+    const plain = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: unb64(envelope.iv), tagLength: 128, additionalData: te.encode(aadOf(envelope)) },
+      aes,
+      unb64(envelope.ciphertext)
+    );
+    payload = JSON.parse(td.decode(plain));
+  } catch {
+    throw failed("decrypt");
+  }
+  const key = recoveryKeyOf(payload && payload.mnemonic);
+  if (envelope.meta && envelope.meta.fingerprint && envelope.meta.fingerprint !== key.fingerprint) throw failed("fingerprint");
+  return key;
+}
+
+// ---------------------------------------------------------------------------------------------------
+// RESERVATION
+// ---------------------------------------------------------------------------------------------------
+
+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;
+  }
+};
+
+/** 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 || {} }));
+  return checked;
+}
+
+export function loadRecoveryKey(storage) {
+  const value = readStore(storage);
+  if (!value) return null;
+  return { ...value, fingerprint: value.fingerprint || fingerprintOf(value.mnemonic) };
+}
+
+/**
+ * Reserve a number for a request. A reservation is not a spent number: if the request is abandoned, the caller
+ * releases it and the same number is used again. The chain check belongs to the caller: a number is retired only
+ * when an order with its commitment exists.
+ */
+export function reserveRecoveryIndex(storage, { chainId, swapId = null } = {}) {
+  const key = loadRecoveryKey(storage);
+  if (!key) throw failed("key-missing");
+  const chain = String(numberField(chainId, "chainId"));
+  const reserved = { ...(key.reserved || {}) };
+  const retired = { ...(key.retired || {}) };
+  const index = Number(key.nextIndex) || 0;
+  // Holes left by RELEASED numbers are reused; a retired number was seen on chain and is never reused.
+  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 }));
+      return i;
+    }
+  }
+  if (index >= 100000) 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 }));
+  return index;
+}
+
+export function releaseRecoveryIndex(storage, index) {
+  const key = loadRecoveryKey(storage);
+  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 }));
+}
+
+/** Retire a number after its order exists on chain: it is never reused, so a later scan has no collision. */
+export function commitRecoveryIndex(storage, index) {
+  const key = loadRecoveryKey(storage);
+  if (!key) throw failed("key-missing");
+  const reserved = { ...(key.reserved || {}) };
+  const retired = { ...(key.retired || {}) };
+  const n = numberField(index, "index");
+  delete reserved[String(n)];
+  retired[String(n)] = true;
+  storage.set(RECOVERY_KEY_STORE, JSON.stringify({ ...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);
+}
+
+function decodeOrderLog(log) {
+  const topics = Array.isArray(log && log.topics) ? log.topics : [];
+  if (topics.length < 4 || String(topics[0]).toLowerCase() !== ORDER_CREATED_TOPIC) return null;
+  const data = String(log.data || "").replace(/^0x/, "");
+  if (data.length < 64 * 2) return null;
+  const word = (i) => "0x" + data.slice(i * 64, (i + 1) * 64).toLowerCase();
+  return {
+    escrow: "0x" + String(topics[1]).slice(26).toLowerCase(),
+    locker: "0x" + String(topics[2]).slice(26).toLowerCase(),
+    claimer: "0x" + String(topics[3]).slice(26).toLowerCase(),
+    commitHalfLocker: word(0),
+    commitHalfClaimer: word(1),
+    edPointLocker: word(2),
+    edPointClaimer: word(3),
+    edViewPointLocker: word(4),
+    amount: BigInt(word(5)).toString(),
+    readyBy: Number(BigInt(word(6))),
+    t1: Number(BigInt(word(7))),
+    salt: word(8),
+    registry: "0x" + data.slice(9 * 64 + 24, 10 * 64),
+    provider: "0x" + data.slice(10 * 64 + 24, 11 * 64),
+    quoteKey: "0x" + data.slice(11 * 64 + 24, 12 * 64),
+    transactionHash: log.transactionHash || null,
+    blockNumber: log.blockNumber != null ? Number(log.blockNumber) : null,
+    logIndex: log.logIndex != null ? Number(log.logIndex) : null,
+  };
+}
+
+async function readLogs(evmLogs, request) {
+  if (typeof evmLogs !== "function") throw bad("evmLogs");
+  let logs;
+  try {
+    logs = await evmLogs(request);
+  } catch {
+    throw failed("logs");
+  }
+  if (!Array.isArray(logs)) throw failed("logs");
+  return logs;
+}
+
+/**
+ * Find orders made with this key.
+ *
+ * `evmLogs` is the caller's read seam: ({ address, topics, fromBlock, toBlock }) -> logs. With an address, the
+ * search asks for it as the locker and as the claimer (two queries; the RPC topic filter cannot say OR across two
+ * 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 = 0, toBlock = "latest", gap = 5, maxIndex = 1000 } = {}) {
+  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;
+  const base = { address: factory, fromBlock, toBlock };
+  let logs = [];
+  if (address) {
+    const padded = topicAddress(address);
+    const [asLocker, asClaimer] = await Promise.all([
+      readLogs(evmLogs, { ...base, topics: [ORDER_CREATED_TOPIC, null, padded, null] }),
+      readLogs(evmLogs, { ...base, topics: [ORDER_CREATED_TOPIC, null, null, padded] }),
+    ]);
+    const seen = new Set();
+    for (const log of asLocker.concat(asClaimer)) {
+      const id = `${log.transactionHash || ""}:${log.logIndex ?? ""}`;
+      if (seen.has(id)) continue;
+      seen.add(id);
+      logs.push(log);
+    }
+  } else {
+    logs = await readLogs(evmLogs, { ...base, topics: [ORDER_CREATED_TOPIC] });
+  }
+  const orders = logs.map(decodeOrderLog).filter(Boolean);
+  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;
+      continue;
+    }
+    misses = 0;
+    for (const order of matches) {
+      found.push({ ...order, index, side: order.commitHalfLocker.toLowerCase() === own.spendCommitment.toLowerCase() ? "locker" : "claimer" });
+    }
+  }
+  return { swaps: found, scanned };
+}

package/src/swaps.mjs

@@ -12,7 +12,7 @@ import * as engine from "./engine.mjs";
 import * as recordModule from "./record.mjs";
 // The order: our own side is built by the engine's builder, the counterparty's side is verified and accepted, and
 // the joint address is assembled from the halves. There are no formulas of our own in the core - see order.mjs.
-import { contextOf, orderStep } from "./order.mjs";
+import { buildOwnSideFromHalves, contextOf, orderStep } from "./order.mjs";
 // Locking the funds: sending goes through the already-finished step (`lock.send`), the wallet is an adapter from outside.
 import * as lock from "./lock.mjs";
 import { vmOfChain, legFor } from "./legs/index.mjs";
@@ -23,6 +23,11 @@ import { primitives } from "./primitives.mjs";
 // the slots against the chain BEFORE signing (actions.markReady). The watch must call exactly it, otherwise "we saw
 // the XMR" and "we allowed the settlement to be taken" would diverge.
 import { createActions } from "./actions.mjs";
+// THE ONE RECOVERY KEY (sdk#76): the taker's halves come from it, not from a fresh random pair per swap.
+import {
+  commitRecoveryIndex, createRecoveryKeyFile, importRecoveryKey, loadRecoveryKey,
+  recoveryKeyFileName, reserveRecoveryIndex, saveRecoveryKey, takerHalves,
+} from "./recovery-key.mjs";
 // THE XMR ARRIVAL CHECK ON TWO NODES (issue #85) - IN THE CORE, from the same mirrored rule and block parser.
 import * as xmrArrival from "./xmr-arrival.mjs";
 // THE MAKER'S DECLINE (issue #40): the escrow's `Declined` event and the node's `declined` + `compliance` status
@@ -705,7 +710,9 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
     async start(request) {
       if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
       if (!request.quote || typeof request.quote !== "object") throw new SdkError("bad-input", { field: "quote" });
-      if (typeof request.onRecoveryFile !== "function") throw new SdkError("bad-input", { field: "onRecoveryFile" });
+      // THE OLD PATH IS UNCHANGED; THE NEW ONE ASKS FOR A KEY INSTEAD OF A PER-SWAP FILE.
+      const wantsKey = request.recoveryKey !== undefined && request.recoveryKey !== null;
+      if (!wantsKey && typeof request.onRecoveryFile !== "function") throw new SdkError("bad-input", { field: "onRecoveryFile" });
       if (!request.receiveTo || typeof request.receiveTo !== "string") throw new SdkError("bad-input", { field: "receiveTo" });
       // THE ORDER CONTEXT IS MANDATORY AND NOT INVENTED. It is assembled by the engine FROM THE VERY FIELDS the firm
       // quote's signature is bound to (orderContext.js, FIELDS), because the DLEQ proof proves a half FOR THESE TERMS.
@@ -734,8 +741,9 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       // record, and our side of the order is computed from the core's primitives.
       // THE RECORD IS CREATED TOGETHER WITH OUR SIDE: the order terms go into it, and the side is built by the engine's
       // builder (with the DLEQ proof and the encryption key), not by the core's own arithmetic.
+      let keySide = null;
       const makeRecord = typeof createRecord === "function" ? createRecord
-        : async (req) => recordModule.createRecord(recordInputOf(req), { order: req.order });
+        : async (req) => recordModule.createRecord(recordInputOf(req), { order: req.order, side: keySide });
       const passphrase = typeof request.passphrase === "string" ? request.passphrase : "";
       if (typeof passphrase !== "string") throw new SdkError("bad-input", { field: "passphrase" });
       if (passphrase.length > 0 && passphrase.length < MIN_PASSPHRASE) throw new SdkError("bad-input", { field: "passphrase", min: MIN_PASSPHRASE });
@@ -744,6 +752,32 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       // values: the DLEQ proof would then be bound to nothing.
       const orderContext = contextOf(request.order);
 
+      // THE KEY RECORD, THE NUMBER AND THE SIDE. A key is made once and kept through the SDK's store; the
+      // number is reserved before the order is built, and it is retired only after the order exists on chain.
+      // No per-swap file is assembled on this path.
+      let recovery = null;
+      if (wantsKey) {
+        const storage = engine.store.storage();
+        const supplied = typeof request.recoveryKey === "string"
+          ? request.recoveryKey
+          : request.recoveryKey && typeof request.recoveryKey.mnemonic === "string" ? request.recoveryKey.mnemonic : null;
+        const saved = loadRecoveryKey(storage);
+        if (saved && supplied && saved.mnemonic !== supplied) {
+          throw new SdkError("bad-input", { field: "recoveryKey", why: "different-key" });
+        }
+        if (!saved && !supplied) throw new SdkError("bad-input", { field: "recoveryKey" });
+        const key = saved || importRecoveryKey(supplied);
+        if (!saved) saveRecoveryKey(storage, key);
+        const chainId = request.order.chainId;
+        const index = request.recoveryIndex === undefined || request.recoveryIndex === null
+          ? reserveRecoveryIndex(storage, { chainId })
+          : Number(request.recoveryIndex);
+        if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "recoveryIndex" });
+        const derived = takerHalves({ mnemonic: key.mnemonic, chainId, index });
+        keySide = buildOwnSideFromHalves(request.order, { spendHalf: derived.spendHalf, viewHalf: derived.viewHalf }).side;
+        recovery = { storage, key, index, newKey: !saved };
+      }
+
       let made = null;
       try { made = await makeRecord(request); } catch (error) {
         // THE CODE MATTERS, NOT THE CLASS: an error with a code (including from another instance of the module) passes
@@ -785,26 +819,42 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         builtSide = step;
       }
 
-      // 2a. THE RECOVERY FILE IS ASSEMBLED AND CHECKED BEFORE THE PERSON. A file that will not open is worse than no
-      // file: the person will rely on it. So we check on our side, before the screen.
+      // 2a. THE KEY IS CONFIRMED ONCE; THE OLD PATH STILL ASSEMBLES A PER-SWAP FILE. On the key path there is
+      // no file per swap: the same twelve words cover every swap, and a person who already saved them is not
+      // asked again. A new key is shown before the money moves - no saved key, no funding.
       let payload = null;
-      try {
-        payload = engine.recoveryFile.buildPayload({
-          swap: record.swap, swapWallet: record.swapWallet, escrow: record.escrow,
-          receiveAddress: record.receiveTo || request.receiveTo, restoreHeight: record.restoreHeight ?? null,
-        });
-        engine.recoveryFile.validatePayload(payload);
-      } catch { throw new SdkError("recovery-failed", { step: "build-payload" }); }
-
       let file = null;
-      try {
-        file = { name: engine.recoveryFile.recoveryFileName(payload.swapId), contents: await engine.recoveryFile.createRecoveryFile(payload, passphrase) };
-      } catch { throw new SdkError("recovery-failed", { step: "encrypt" }); }
+      let confirmed = true;
+      if (!recovery) {
+        // THE RECOVERY FILE IS ASSEMBLED AND CHECKED BEFORE THE PERSON. A file that will not open is worse than no
+        // file: the person will rely on it. So we check on our side, before the screen.
+        try {
+          payload = engine.recoveryFile.buildPayload({
+            swap: record.swap, swapWallet: record.swapWallet, escrow: record.escrow,
+            receiveAddress: record.receiveTo || request.receiveTo, restoreHeight: record.restoreHeight ?? null,
+          });
+          engine.recoveryFile.validatePayload(payload);
+        } catch { throw new SdkError("recovery-failed", { step: "build-payload" }); }
 
-      // 3. THE PERSON'S CONFIRMATION - THE GATE. No action that locks funds goes earlier: otherwise the lock would end
-      // up without a key if the browser is lost. "Did not answer" is a refusal, not consent.
-      const confirmed = await request.onRecoveryFile(file);
-      if (confirmed !== true) throw new SdkError("recovery-declined", { swapId: payload.swapId });
+        try {
+          file = { name: engine.recoveryFile.recoveryFileName(payload.swapId), contents: await engine.recoveryFile.createRecoveryFile(payload, passphrase) };
+        } catch { throw new SdkError("recovery-failed", { step: "encrypt" }); }
+
+        // 3. THE PERSON'S CONFIRMATION - THE GATE. No action that locks funds goes earlier: otherwise the lock would end
+        // up without a key if the browser is lost. "Did not answer" is a refusal, not consent.
+        confirmed = await request.onRecoveryFile(file);
+        if (confirmed !== true) throw new SdkError("recovery-declined", { swapId: payload.swapId });
+      } else if (recovery.newKey) {
+        if (typeof request.onRecoveryKey !== "function") throw new SdkError("bad-input", { field: "onRecoveryKey" });
+        try {
+          file = {
+            name: recoveryKeyFileName(recovery.key),
+            contents: await createRecoveryKeyFile({ mnemonic: recovery.key.mnemonic, createdAt: recovery.key.createdAt, passphrase }),
+          };
+        } catch { throw new SdkError("recovery-failed", { step: "encrypt-key" }); }
+        confirmed = await request.onRecoveryKey(file);
+        if (confirmed !== true) throw new SdkError("recovery-declined", { key: recovery.key.fingerprint });
+      }
 
       // 4. LOCKING THE FUNDS. The wallet comes FROM OUTSIDE (an adapter with `send`/`receipt`): signing is possible only
       // in it, and the core keeps no path into the chain of its own. The absence of a wallet is a REFUSAL WITH A CODE,
@@ -864,6 +914,11 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
           // THE FUNDING HEIGHT - FROM THE RECEIPT: the XMR watch and the recovery file take it from here.
           birthHeight: Number(funded.birthBlock) > 0 ? Number(funded.birthBlock) : (escrowRecord.birthHeight ?? null) };
         try { engine.swap.saveSwap(record.swap); } catch { throw new SdkError("storage-unavailable", { step: "save-escrow" }); }
+        // THE NUMBER IS SPENT ONLY NOW, WHEN THE ORDER EXISTS ON CHAIN. A failed or abandoned start keeps the
+        // reservation, so a retry uses the same number and the later search has no gap.
+        if (recovery) {
+          try { commitRecoveryIndex(recovery.storage, recovery.index); } catch { /* the reservation stays; the key still works */ }
+        }
       }
 
       // 5. THE SERVER: RECORDING THE SWAP WITH US, THEN THE FACTORY WATCH RECORD FOR THE MONERO ADDRESS.

package/src/version.mjs

@@ -6,4 +6,4 @@
 // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
 // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
 
-export const SDK_VERSION = "0.46.2";
+export const SDK_VERSION = "0.48.0";