@ninsei-labs/sdk 0.52.0 → 0.54.0

package/src/swaps.mjs

@@ -5,6 +5,7 @@
 // order and halves -> server -> watching the Monero address. A lock without a recovery file is a lock with nothing
 // to open it with if the browser is lost, so the confirmation stands BEFORE anything that locks funds.
 import { SdkError } from "./errors.mjs";
+import { SDK_VERSION } from "./version.mjs";
 import * as engine from "./engine.mjs";
 // The name is NOT `record`: inside start there is a variable with that name, and referencing the module before it
 // ran into "Cannot access 'record' before initialization" - a refusal without a code, that is, a breakdown. A check
@@ -12,13 +13,15 @@ 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 { buildOwnSideFromHalves, contextOf, orderStep } from "./order.mjs";
+import { buildOwnSideFromHalves, contextOf, halfHex, norm, normalizeCounterpartyView, 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 * as flow from "./swap-flow.mjs";
+import { fundingReceiptVerdict } from "../engine/evm/funding.js";
 import { vmOfChain, legFor } from "./legs/index.mjs";
 // THE VIEW HALVES - from the core's primitives: the sum of two halves is the key the wallet sees incoming payments
 // with. There is no arithmetic of the core's own here either (see order.mjs) - we use the same halves builder.
-import { primitives } from "./primitives.mjs";
+import { keccak256, primitives, secp256k1 } from "./primitives.mjs";
 import { probeMoneroNode } from "./probes.mjs";
 // MARKING READY - A FINISHED STEP, NOT A SECOND IMPLEMENTATION OF IT: it requires the order expectations and checks
 // the slots against the chain BEFORE signing (actions.markReady). The watch must call exactly it, otherwise "we saw
@@ -27,7 +30,8 @@ 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,
-  recoveryIndexTaken, recoveryKeyFileName, reserveRecoveryIndex, saveRecoveryKey, takerHalves,
+  recoveryIndexTaken, recoveryKeyFileName, recoverySaltOf, reserveRecoveryIndex, saveRecoveryKey,
+  newRecoverySalt, takerHalves, takerHalvesV2,
 } 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";
@@ -98,7 +102,7 @@ const LOCKED_STATUS = "xmr_locked";
 // WHAT IS DELIBERATELY ABSENT HERE: a waiting policy of its own inside the step. How long to wait for the XMR to
 // arrive is the caller's decision, so the watch is exposed as a separate method (`swaps.watch`) with a timeout from
 // the configuration.
-const MARK_FIELDS = ["id", "network", "escrow", "quoteId", "providerId", "hashlock", "amount", "t0", "t1"];
+const MARK_FIELDS = ["id", "network", "escrow", "quoteId", "providerId", "hashlock", "amount", "t0", "t1", "sdkVersion"];
 // THE FIELDS OF THE FACTORY WATCH RECORD - the same whitelist as the page client's
 // (www/js/core/chainSource.js:33, ALLOWED_SESSION_FIELDS). The body is assembled FROM IT anew, so neither the spend
 // half nor the spend key can get into the request, even if someone adds them to the record "just in case".
@@ -132,6 +136,7 @@ export function markBodyOf(swap, escrow, order = null) {
     amount: first(e.amountWei, o.amount, swap.amountWei),
     t0: first(e.t0, o.t0),
     t1: first(e.t1, o.t1),
+    sdkVersion: SDK_VERSION,
   };
 }
 
@@ -378,6 +383,48 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
     const all = Object.values((state && state.swaps) || {}).filter((s) => s && s.id);
     return all.sort((a, b) => Number(b.createdAt || 0) - Number(a.createdAt || 0));
   };
+  // A START THAT ENDED WITH A SENT TRANSACTION AND NO RECEIPT IS RESUMED, NOT RESENT. The transaction hash and the
+  // predicted escrow are kept on the record; a retry of the same quote reads that receipt instead of building a
+  // second side and sending a second deposit.
+  const pendingFundingOf = (quoteId) => {
+    const id = String(quoteId || "");
+    if (!id) return null;
+    return records().find((swap) => String(swap.orderQuoteId || "") === id &&
+      (swap.fundingPending === true || (swap.escrow && swap.escrow.fundingPending === true))) || null;
+  };
+  async function resumePendingFunding(record, request) {
+    const swap = record.swap || record;
+    const escrowRecord = swap.escrow && typeof swap.escrow === "object" ? swap.escrow : {};
+    const txHash = escrowRecord.fundTx || swap.fundTx || null;
+    if (!txHash) {
+      return { id: swap.id || null, escrow: escrowRecord.address || null,
+        address: (record.swapWallet && record.swapWallet.address) || null,
+        step: "funding-pending", txHash: null, reason: "no-transaction-hash", next: "receipt" };
+    }
+    const wallet = request.wallet;
+    let receipt = null;
+    if (wallet && typeof wallet.receipt === "function") {
+      try { receipt = await wallet.receipt(txHash); } catch { receipt = null; }
+    }
+    const order = request.order && typeof request.order === "object" ? request.order : {};
+    const verdict = fundingReceiptVerdict(receipt, {
+      factory: order.factory || (request.orderQuote && request.orderQuote.factory) || null,
+      expectedEscrow: escrowRecord.address || null,
+    });
+    if (verdict.status === "reverted") throw new SdkError("contract-reverted", { step: "funding" });
+    if (verdict.status === "funded") {
+      swap.escrow = { ...escrowRecord, address: verdict.escrow, fundingPending: false,
+        evmBirthBlock: Number(verdict.birthBlock) > 0 ? Number(verdict.birthBlock) : (escrowRecord.evmBirthBlock ?? null) };
+      delete swap.fundingPending;
+      try { engine.swap.saveSwap(swap); } catch { throw new SdkError("storage-unavailable", { step: "save-escrow" }); }
+      return { id: swap.id || null, escrow: verdict.escrow,
+        address: (record.swapWallet && record.swapWallet.address) || null,
+        step: "xmr-incoming", server: null, watch: null, next: "watch" };
+    }
+    return { id: swap.id || null, escrow: escrowRecord.address || null,
+      address: (record.swapWallet && record.swapWallet.address) || null,
+      step: "funding-pending", txHash, reason: verdict.reason || "no-receipt", next: "receipt" };
+  }
 
   // THE GUARDS' DATA: what the core knows itself (the network, the order amount, the token allowance) plus the balance
   // read by THE SAME wallet the lock will be signed with. Here too - a refusal WITH A CODE where there is no data at
@@ -447,6 +494,8 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
   async function markOnServer(swap, escrow, order) {
     if (!http || typeof http.tryJson !== "function") throw new SdkError("bad-input", { field: "http", step: "mark" });
     const mark = markBodyOf(swap, escrow, order);
+    // THE BROWSER SDK LINE IS PART OF THE BODY. The node's body routes read it before any work; a mark request
+    // without it is refused as sdk-version-absent even though the swap is already funded.
     const body = JSON.stringify(Object.fromEntries(MARK_FIELDS.map((field) => [field, mark[field]])));
     const headers = { "content-type": "application/json" };
     // THE PASS IS ASKED EVERY TIME, NOT CACHED: it is short-lived (an hour: app/server.mjs, AUTH_TOKEN_TTL_MS), and a
@@ -496,7 +545,7 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       restoreHeight,
       chain: swap.network || swap.chain || null,
     };
-    const body = {};
+    const body = { sdkVersion: SDK_VERSION };
     for (const field of ALLOWED_SESSION_FIELDS) if (wanted[field] !== undefined && wanted[field] !== null) body[field] = wanted[field];
     // THE VIEW KEY IS NOT NEEDED BY THE SERVICE FOR THE DECISION ANY MORE: since the arrival is checked by the
     // client (verifyArrival), the backend may keep a watch only for notifications, and even that it can do from
@@ -744,11 +793,37 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
 
     async start(request) {
       if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      // SELL IS NOT A BUY WITH ANOTHER LABEL. The lock step sends the settlement deposit from the caller; on a sell
+      // the caller is the claimer and the node is the locker, so this path would ask the wallet to sign the wrong
+      // transaction. Refuse before the recovery key, the wallet or any network read; the sell client has its own
+      // flow and must not be simulated by this one.
+      if (request.side === "sell") {
+        throw new SdkError("bad-input", { field: "side", why: "sell-not-supported", surface: "swaps.start" });
+      }
       if (!request.quote || typeof request.quote !== "object") throw new SdkError("bad-input", { field: "quote" });
-      // 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" });
+      // THE PER-SWAP FILE PATH IS GONE. One key covers every swap, and a per-swap file issued before funding cannot
+      // name the escrow (it does not exist yet), so `sweep.plan` could not read the revealed half from it.
+      if (request.recoveryKey === undefined || request.recoveryKey === null) {
+        throw new SdkError("bad-input", { field: "recoveryKey", why: "required" });
+      }
       if (!request.receiveTo || typeof request.receiveTo !== "string") throw new SdkError("bad-input", { field: "receiveTo" });
+      // RESUME BEFORE ANY NEW SIDE OR SEND. The previous start may have sent the deposit and lost the receipt;
+      // reusing its hash is the only way to learn the escrow without a second payment.
+      const quoteForResume = (request.orderQuote && request.orderQuote.id) || (request.quote && request.quote.id) || null;
+      const pendingRecord = pendingFundingOf(quoteForResume);
+      if (pendingRecord) return await resumePendingFunding(pendingRecord, request);
+      // A NEW START USES A PER-ORDER SALT, NOT A RECOVERY INDEX. A v1 index is the same at every factory and on
+      // every device, so two devices can derive one half. When the caller brings no `recoverySalt`, the order's own
+      // salt is the client salt; a missing salt is drawn here and written into the order before its context is built.
+      // An explicit `recoveryIndex` keeps the legacy path for restoring an old order; it is not a new-start default.
+      const explicitRecoveryIndex = request.recoveryIndex !== undefined && request.recoveryIndex !== null;
+      if ((request.recoverySalt === undefined || request.recoverySalt === null) && !explicitRecoveryIndex) {
+        if (!request.order || typeof request.order !== "object") throw new SdkError("bad-input", { field: "order" });
+        if (request.order.salt === undefined || request.order.salt === null || request.order.salt === "") {
+          request.order = { ...request.order, salt: newRecoverySalt() };
+        }
+        request.recoverySalt = request.order.salt;
+      }
       // 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.
       // Substituting an empty value here would mean issuing a key bound to nothing.
@@ -777,6 +852,7 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       // 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;
+      let derivedViewHalf = null;
       const makeRecord = typeof createRecord === "function" ? createRecord
         : async (req) => recordModule.createRecord(recordInputOf(req), { order: req.order, side: keySide });
       const passphrase = typeof request.passphrase === "string" ? request.passphrase : "";
@@ -791,7 +867,7 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       // 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
@@ -802,37 +878,79 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         }
         if (!saved && !supplied) throw new SdkError("bad-input", { field: "recoveryKey" });
         const key = saved || importRecoveryKey(supplied);
-        if (!saved) saveRecoveryKey(storage, key);
+        // THE KEY IS SAVED, BUT NOT YET BACKED UP. `backupConfirmed` is its own fact: a key in storage is not a
+        // key the person has saved. Saving it here is needed for index reservations; funding waits for the flag.
+        if (!saved) saveRecoveryKey(storage, { ...key, backupConfirmed: false });
         const chainId = request.order.chainId;
         const explicit = request.recoveryIndex !== undefined && request.recoveryIndex !== null;
-        let index = explicit ? Number(request.recoveryIndex) : reserveRecoveryIndex(storage, { chainId });
-        if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "recoveryIndex" });
-        // A BROWSER STORE IS PER DEVICE. The same words opened elsewhere start at the same number, so the factory's own
-        // log is asked before the number is used; a taken number is retired locally and the next one is reserved.
-        // Without a log seam the previous behaviour is kept - the caller cannot be asked to invent a chain read.
-        if (typeof chainLogs === "function" && request.order.factory) {
-          // THE CHAIN'S BIRTH HEIGHT IS THE DEFAULT START, NOT ZERO. The factory's own log cannot hold an order
-          // before it existed; asking from zero is tens of log queries per number on a public RPC. An explicit
-          // `fromBlock` still wins, including the literal zero.
-          const chain = config && Array.isArray(config.chains)
-            ? config.chains.find((entry) => Number(entry.chainId) === Number(chainId)) : null;
-          const deploymentBlock = chain && chain.escrow ? chain.escrow.deploymentBlock : null;
-          const fromBlock = request.fromBlock !== undefined
-            ? request.fromBlock
-            : (Number.isSafeInteger(deploymentBlock) ? deploymentBlock : 0);
-          let hops = 0;
-          while (await recoveryIndexTaken({ mnemonic: key.mnemonic, chainId, index, factory: request.order.factory,
-            evmLogs: chainLogs, fromBlock })) {
-            if (explicit) throw new SdkError("bad-input", { field: "recoveryIndex", why: "on-chain" });
-            commitRecoveryIndex(storage, index);
-            index = reserveRecoveryIndex(storage, { chainId });
-            hops += 1;
-            if (!Number.isSafeInteger(index) || index < 0 || hops > 1000) throw new SdkError("bad-input", { field: "recoveryIndex", why: "exhausted" });
+        const saltRequested = request.recoverySalt !== undefined && request.recoverySalt !== null;
+        let derived;
+        if (saltRequested) {
+          // THE CLIENT OWNS THE SALT. A maker that chose it could hand the same salt to the same client twice, so
+          // the caller composes the signed quote with this value and passes it here. The order's own salt must be
+          // the same bytes; a mismatch means the quote is not the one being started.
+          if (explicit) throw new SdkError("bad-input", { field: "recoverySalt", why: "with-recovery-index" });
+          if (typeof request.order.factory !== "string" || !request.order.factory) {
+            throw new SdkError("bad-input", { field: "order.factory" });
+          }
+          let salt;
+          try { salt = recoverySaltOf(request.recoverySalt); } catch { throw new SdkError("bad-input", { field: "recoverySalt" }); }
+          let orderSalt;
+          try { orderSalt = recoverySaltOf(request.order.salt); } catch { throw new SdkError("bad-input", { field: "recoverySalt", why: "order-salt" }); }
+          if (salt !== orderSalt) throw new SdkError("bad-input", { field: "recoverySalt", why: "order-salt" });
+          derived = takerHalvesV2({ mnemonic: key.mnemonic, chainId, factory: request.order.factory, salt });
+          recovery = { storage, key, salt, derivation: "salt-v2", newKey: !saved || saved.backupConfirmed !== true };
+        } else {
+          let index = explicit ? Number(request.recoveryIndex) : reserveRecoveryIndex(storage, { chainId });
+          if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "recoveryIndex" });
+          // A BROWSER STORE IS PER DEVICE. The same words opened elsewhere start at the same number, so the factory's own
+          // log is asked before the number is used; a taken number is retired locally and the next one is reserved.
+          // Without a log seam the previous behaviour is kept - the caller cannot be asked to invent a chain read.
+          if (typeof chainLogs === "function" && request.order.factory) {
+            // THE CHAIN'S BIRTH HEIGHT IS THE DEFAULT START, NOT ZERO. The factory's own log cannot hold an order
+            // before it existed; asking from zero is tens of log queries per number on a public RPC. An explicit
+            // `fromBlock` still wins, including the literal zero.
+            const chain = config && Array.isArray(config.chains)
+              ? config.chains.find((entry) => Number(entry.chainId) === Number(chainId)) : null;
+            const deploymentBlock = chain && chain.escrow ? chain.escrow.deploymentBlock : null;
+            const fromBlock = request.fromBlock !== undefined
+              ? request.fromBlock
+              : (Number.isSafeInteger(deploymentBlock) ? deploymentBlock : 0);
+            let hops = 0;
+            while (await recoveryIndexTaken({ mnemonic: key.mnemonic, chainId, index, factory: request.order.factory,
+              evmLogs: chainLogs, fromBlock })) {
+              if (explicit) throw new SdkError("bad-input", { field: "recoveryIndex", why: "on-chain" });
+              commitRecoveryIndex(storage, index);
+              index = reserveRecoveryIndex(storage, { chainId });
+              hops += 1;
+              if (!Number.isSafeInteger(index) || index < 0 || hops > 1000) throw new SdkError("bad-input", { field: "recoveryIndex", why: "exhausted" });
+            }
           }
+          derived = takerHalves({ mnemonic: key.mnemonic, chainId, index });
+          recovery = { storage, key, index, derivation: "index-v1", newKey: !saved || saved.backupConfirmed !== true };
         }
-        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 };
+        // THE MAKER'S VIEW HALF IS DERIVED FROM THE KEY, NOT CHOSEN BY THE NODE. Without this binding a
+        // signed quote could carry another view half; the funded address would differ from the one the twelve
+        // words rebuild, and `sweep.fromOrder` would refuse after the funds were locked.
+        derivedViewHalf = { half: derived.makerViewHalf, point: derived.makerViewPoint };
+      }
+
+      // THE KEY PATH BINDS THE VIEW HALF BEFORE THE ORDER IS BUILT. The quote must echo the half derived from
+      // the same words and number; a missing or different half is refused, never silently replaced.
+      if (derivedViewHalf) {
+        const cp = request.counterparty && typeof request.counterparty === "object" ? request.counterparty : null;
+        // ONE NORMALISATION FOR THE GUARD AND THE BUILDER. Conflicting aliases are a refusal here, not a choice
+        // between two values; the point is derived from the half when the quote names only the half.
+        const view = normalizeCounterpartyView(cp);
+        if (view.half === null) throw new SdkError("quote-field-unbound", { step: "viewHalfClaimer", field: "viewHalfClaimer" });
+        let sameHalf = false;
+        try { sameHalf = BigInt(view.half) === BigInt(derivedViewHalf.half); } catch { sameHalf = false; }
+        if (!sameHalf) throw new SdkError("quote-refused", { step: "viewHalfClaimer", why: "not-the-derived-half" });
+        if (view.point !== null &&
+            String(view.point).replace(/^0x/, "").toLowerCase() !== String(derivedViewHalf.point).replace(/^0x/, "").toLowerCase()) {
+          throw new SdkError("quote-refused", { step: "viewHalfClaimer", why: "point-mismatch" });
+        }
       }
 
       let made = null;
@@ -885,32 +1003,10 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       record.swap.escrow = { ...(record.swap.escrow || {}), moneroRestoreHeight: measuredHeight };
       try { engine.swap.saveSwap(record.swap); } catch { throw new SdkError("storage-unavailable", { step: "save-restore-height" }); }
 
-      // 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;
+      // 2a. THE KEY IS CONFIRMED ONCE. 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 file = null;
-      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" }); }
-
-        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 (recovery.newKey) {
         if (typeof request.onRecoveryKey !== "function") throw new SdkError("bad-input", { field: "onRecoveryKey" });
         try {
           file = {
@@ -918,15 +1014,23 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
             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);
+        const confirmed = await request.onRecoveryKey(file);
         if (confirmed !== true) throw new SdkError("recovery-declined", { key: recovery.key.fingerprint });
+        // ONLY THE PERSON'S TRUE ANSWER MAKES THE KEY "BACKED UP". The record already exists for reservations;
+        // this flag is what a later start reads. A failed write is a refusal before any funds move.
+        try {
+          const stored = loadRecoveryKey(recovery.storage) || {};
+          saveRecoveryKey(recovery.storage, { ...recovery.key, nextIndex: stored.nextIndex,
+            reserved: stored.reserved, retired: stored.retired, backupConfirmed: true });
+          recovery.key = { ...recovery.key, backupConfirmed: true };
+        } catch { throw new SdkError("storage-unavailable", { step: "save-recovery-key" }); }
       }
 
       // 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,
       // not a substitution of something by default: a lock without a signature would either not happen or go out with
-      // the wrong key. The recovery file has by now been assembled and confirmed by the person - a lock without a file
-      // is not done.
+      // the wrong key. The recovery key has by now been shown and confirmed by the person - a lock without a saved
+      // key is not done.
       const wallet = request.wallet;
       if (!wallet || typeof wallet.send !== "function" || typeof wallet.receipt !== "function") {
         throw new SdkError("bad-input", { field: "wallet", missing: ["send", "receipt"], surface: "swaps.start", step: "lock" });
@@ -963,6 +1067,21 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       const lockRequest = { ...request.order, ...derived, amountWei: request.order.amount };
       // THE SIGNED QUOTE: the fee, the registry address and the provider live in IT, not in the factory
       // (decision #76). The caller brings it (the interface got it from the maker); without it the lock is not signed.
+      // THE QUOTE MUST NAME THE SAME COUNTERPARTY HALF THAT WAS VERIFIED. `orderStep` verifies
+      // `request.counterparty`, while funding encodes `request.orderQuote`; a caller that brings both can otherwise
+      // prove one point and fund another. The same comparison is repeated in funding.js, at the money boundary.
+      if (request.orderQuote && (builtSide || request.counterparty)) {
+        const norm = (v) => String(v === null || v === undefined ? "" : v).replace(/^0x/i, "").toLowerCase();
+        const verifiedCommit = builtSide ? builtSide.wallet.commitHalfClaimer
+          : (request.counterparty.commitHalfClaimer || null);
+        const verifiedPoint = builtSide ? builtSide.wallet.otherSpendPoint
+          : (request.counterparty.edPointClaimer || request.counterparty.edPub || null);
+        if (!verifiedCommit || !verifiedPoint ||
+            norm(request.orderQuote.commitHalfClaimer) !== norm(verifiedCommit) ||
+            norm(request.orderQuote.edPointClaimer) !== norm(verifiedPoint)) {
+          throw new SdkError("quote-refused", { step: "quote-binding", why: "counterparty-half" });
+        }
+      }
       lockRequest.quote = request.orderQuote || null;
       let funded = null;
       try { funded = await lock.send(lockRequest, wallet, { call: reader }); }
@@ -970,6 +1089,25 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         if (error && typeof error.code === "string") throw error;
         throw new SdkError("server-unavailable", { step: "lock" });
       }
+      // A SENT TRANSACTION IS NOT A FUNDED ESCROW. Without a status-1 receipt and the expected OrderCreated, the
+      // address is unknown and calling the step xmr-incoming would make the person wait for XMR at a guess. Keep
+      // the swap pending: the transaction hash is the handle for a later receipt read.
+      if (funded && funded.pending) {
+        // THE TRANSACTION IS SENT; ONLY THE RECEIPT IS LATE. Keep the hash and the predicted escrow on the record
+        // so this start and a later retry can read the receipt instead of building a second deposit.
+        const pendingTx = funded.createHash || null;
+        const predicted = funded.predictedEscrow || null;
+        const escrowRecord = record.swap.escrow && typeof record.swap.escrow === "object" ? record.swap.escrow : {};
+        record.swap.fundingPending = true;
+        record.swap.escrow = { ...escrowRecord, address: predicted || escrowRecord.address || null,
+          fundTx: pendingTx || escrowRecord.fundTx || null, fundingPending: true,
+          fundingReason: funded.pendingReason || "no-receipt" };
+        try { engine.swap.saveSwap(record.swap); } catch { throw new SdkError("storage-unavailable", { step: "save-pending" }); }
+        return { id: record.swap.id || null, escrow: record.swap.escrow.address || null,
+          address: (record.swapWallet && record.swapWallet.address) || null,
+          step: "funding-pending", txHash: pendingTx,
+          reason: funded.pendingReason || "no-receipt", predictedEscrow: predicted, next: "receipt" };
+      }
       // THE ESCROW ADDRESS IS TAKEN FROM THE RECEIPT (lock.send does this), not from a prediction. It is also written
       // into the swap: otherwise the progress screen and the explorer link would show an address that is not on the
       // chain (the page does this on its side: www/js/ui/views/confirm.js:463).
@@ -984,7 +1122,7 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         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) {
+        if (recovery && recovery.index !== undefined) {
           try { commitRecoveryIndex(recovery.storage, recovery.index); } catch { /* the reservation stays; the key still works */ }
         }
       }
@@ -1016,7 +1154,8 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
      *
      * The CLIENT checks the arrival from the Monero nodes (`verify`); there is no backend poll by default. The rate
      * and the timeout come from the configuration (config.limits.watchPollMs/watchTimeoutMs) and are overridable here.
-     * A caller that explicitly configured `apiBase` may use the old watch-row flow instead.
+     * A caller that explicitly configured `apiBase` may still read the old watch row, but that row is only an
+     * observation: it never declares readiness or a decline.
      * IT ARRIVED - we return the FACT (the amount, the confirmations, the txid); WE DID NOT WAIT - a refusal with the
      * code `xmr-timeout`, separate from the others, so "the wait expired" is confused with neither a breakdown nor an
      * empty response. XMR ON THE ADDRESS BUT BARRED BY unlock_time is a THIRD answer with its own code `xmr-locked`
@@ -1136,10 +1275,9 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         last = verifyRequest
           ? { address: request.address || escrowAddress, expectedXmr: request.expectedXmr ?? null, status: null }
           : incomingOf(body);
-        // THE DECLINE IS DECIDED BEFORE THE ARRIVAL IS LOOKED AT, and before the "foreign response" refusal below:
-        // a declined swap's answer carries no `receivedXmr` at all, and refusing it as a bad response would name
-        // the wrong thing (the state is known - it is a decline, not a broken answer).
-        const declineNow = declineOf({ logs: chainDecline.logs, status: body, escrow: escrowAddress, at: Date.now() });
+        // THE DECLINE IS THE ESCROW'S EVENT, NOT THE SERVICE'S WORD. The legacy backend's `declined` status used
+        // to become a settlement and end the wait; it no longer does. A service answer is at most a notification.
+        const declineNow = declineOf({ logs: chainDecline.logs, escrow: escrowAddress, at: Date.now() });
         if (declineNow.declined) {
           settleDecline(record, declineNow.at);
           return declineResult({ source: declineNow.source, at: declineNow.at, waitedMs: Date.now() - started,
@@ -1188,18 +1326,13 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
           return verified;
         }
         if (last.seen) {
-          const result = { seen: true, id, address: last.address, status: last.status,
+          // THE SERVICE MAY OBSERVE MONEY, BUT IT DOES NOT DECLARE AN ARRIVAL. Readiness hands a foreign address
+          // the settlement, and only the client's own two-node check may do that. The observation is returned with
+          // `seen: false` and the next step named; no mark is ever signed from this body.
+          return { seen: false, observed: { id: last.id, address: last.address, status: last.status,
             expectedXmr: last.expectedXmr, receivedXmr: last.receivedXmr, confirmations: last.confirmations,
-            txids: last.txids, at: Date.now() };
-          if (wantExpect && wantWallet) {
-            result.marked = await actions.markReady(
-              { escrow: request.escrow || last.address, expect: request.expect, onStep: request.onStep }, request.wallet);
-          } else {
-            // WITHOUT EXPECTATIONS AND A WALLET, THE WATCH HONESTLY NAMES THE NEXT STEP, rather than pretending the mark
-            // has already been placed.
-            result.next = "mark-ready";
-          }
-          return result;
+            txids: last.txids }, id, address: last.address, expectedXmr: last.expectedXmr,
+            next: "verify", source: "service" };
         }
         if (Date.now() - started >= timeoutMs) {
           throw new SdkError("xmr-timeout", { id, address: last.address, expectedXmr: last.expectedXmr,
@@ -1209,5 +1342,194 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         await new Promise((resolve) => setTimeout(resolve, pollMs));
       }
     },
+
+    /**
+     * START A SELL FROM A VERIFIED RELAY OFFER. The offer is the result of `quotes.firmRelay` for the bid side;
+     * the record keeps the one-time address, the escrow, our half and the order expectations, so a reload can
+     * continue with `get` + `sellWatch` + `sellClaim`. This method sends nothing.
+     */
+    async startSell(request) {
+      if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      const offer = request.offer && typeof request.offer === "object" ? request.offer : null;
+      if (!offer) throw new SdkError("bad-input", { field: "offer" });
+      const order = offer.order && typeof offer.order === "object" ? offer.order : null;
+      const quote = offer.quote && typeof offer.quote === "object" ? offer.quote : null;
+      if (!order || !quote) throw new SdkError("bad-input", { field: "offer", missing: ["order", "quote"] });
+      if (typeof offer.jointAddress !== "string" || !offer.jointAddress) throw new SdkError("bad-input", { field: "offer.jointAddress" });
+      if (typeof offer.escrow !== "string" || !offer.escrow) throw new SdkError("bad-input", { field: "offer.escrow" });
+      // THE RECORD'S ROLE IS THE BID ROLE. The node is the locker and the person is the claimer; a quote whose
+      // addresses or factory disagree with the order is not the offer this record describes.
+      const sameValue = (a, b) => String(a || "").replace(/^0x/, "").toLowerCase() === String(b || "").replace(/^0x/, "").toLowerCase();
+      if (!sameValue(quote.locker, order.locker) || !sameValue(quote.claimer, order.claimer)
+        || !sameValue(quote.provider, order.locker)
+        || !sameValue(quote.factory, order.factory) || Number(quote.chainId) !== Number(order.chainId)) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "terms" });
+      }
+      // THE RECORD IS FOUND BEFORE A SECOND ONE IS MADE. The same offer retried after a reload yields the same
+      // one-time address and escrow; a second record would be a second promise about one deal.
+      const quoteId = quote.id || quote.nonce || null;
+      const existing = records().find((swap) => swap.side === "sell" &&
+        ((swap.escrow && String(swap.escrow.address || "").toLowerCase() === String(offer.escrow).toLowerCase()) ||
+          (quoteId !== null && String(swap.orderQuoteId || "") === String(quoteId))));
+      if (existing) {
+        // A RETRY IS THE SAME OFFER, NOT A NEW ONE THAT HAPPENS TO NAME THE SAME ESCROW. The stored fields are
+        // the commitment the first call verified; a changed point or commitment is refused before it is resumed.
+        const stored = existing.quote && typeof existing.quote === "object" ? existing.quote : {};
+        const same = (a, b) => String(a || "").replace(/^0x/, "").toLowerCase() === String(b || "").replace(/^0x/, "").toLowerCase();
+        if (!same(stored.commitHalfClaimer, quote.commitHalfClaimer)
+          || !same(stored.edPointClaimer, quote.edPointClaimer)
+          || !same(existing.escrow && existing.escrow.moneroAddress, offer.jointAddress)) {
+          throw new SdkError("quote-refused", { step: "sell-record", why: "offer-changed" });
+        }
+        return { id: existing.id, side: "sell", escrow: (existing.escrow && existing.escrow.address) || offer.escrow,
+          address: (existing.escrow && existing.escrow.moneroAddress) || offer.jointAddress,
+          xmrAmount: (existing.escrow && existing.escrow.xmrAmount) || quote.xmrAmount,
+          claimTip: existing.claimTip || quote.claimTip, orderQuote: existing.orderQuote || offer.orderQuote,
+          resumed: true, next: "send-xmr" };
+      }
+      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, backupConfirmed: false });
+      const chainId = Number(order.chainId);
+      if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new SdkError("bad-input", { field: "order.chainId" });
+      if (!order.factory || order.salt === undefined || order.salt === null) throw new SdkError("bad-input", { field: "order" });
+      let derived = null;
+      if (offer.recovery && offer.recovery.kind === "index-v1") {
+        const index = Number(offer.recovery.index);
+        if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "offer.recovery" });
+        derived = takerHalves({ mnemonic: key.mnemonic, chainId, index });
+      } else {
+        let salt = null;
+        try { salt = recoverySaltOf(offer.recovery && offer.recovery.salt ? offer.recovery.salt : order.salt); }
+        catch { throw new SdkError("bad-input", { field: "offer.recovery" }); }
+        derived = takerHalvesV2({ mnemonic: key.mnemonic, chainId, factory: order.factory, salt });
+      }
+      const own = buildOwnSideFromHalves(order, { spendHalf: derived.spendHalf, viewHalf: derived.viewHalf });
+      // THE OFFER MUST NAME THE HALF THIS KEY ACTUALLY PRODUCES. The relay already checked the proof; the record
+      // needs the same point and commitment, otherwise a later claim would reveal a half the escrow rejects.
+      const ownCommit = (() => {
+        try {
+          const point = secp256k1.Point.fromHex(own.side.proof.XA);
+          return "0x" + Array.from(keccak256(point.toBytes(false).slice(1)), (b) => b.toString(16).padStart(2, "0")).join("");
+        } catch { return null; }
+      })();
+      const low160 = (v) => String(v || "").replace(/^0x/, "").toLowerCase().slice(-40);
+      if (!ownCommit || low160(ownCommit) !== low160(quote.commitHalfClaimer)) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "commitment" });
+      }
+      if (String(own.spendPoint).toLowerCase() !== String(quote.edPointClaimer || "").toLowerCase()) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "spend-point" });
+      }
+      if (offer.edViewPointClaimer && String(own.viewPoint).toLowerCase() !== String(offer.edViewPointClaimer).toLowerCase()) {
+        throw new SdkError("quote-refused", { step: "sell-record", why: "view-point" });
+      }
+      const made = recordModule.createRecord({
+        side: "sell", network: String(order.chainId),
+        payToken: order.asset || quote.asset || undefined,
+        payAmount: quote.amount, xmrAmount: Number(quote.xmrAmount) / 1e12,
+        orderQuoteId: quoteId || undefined,
+        receiveAddress: order.claimer,
+        makerId: quote.provider || null,
+      }, { order, side: own.side });
+      const swap = made.swap;
+      swap.side = "sell";
+      swap.order = order;
+      swap.orderQuote = offer.orderQuote || null;
+      swap.quote = quote;
+      swap.claimTip = quote.claimTip || null;
+      swap.expect = {
+        chainId, factory: order.factory, locker: order.locker, claimer: order.claimer, amount: String(order.amount),
+        readyBy: order.readyBy, t1: order.t1, salt: order.salt,
+        commitHalfLocker: (offer.nodeHalf && offer.nodeHalf.commitHalf) || null,
+        edPointLocker: (offer.nodeHalf && offer.nodeHalf.edPoint) || null,
+        edViewPointLocker: offer.edViewPointLocker || null,
+        commitHalfClaimer: quote.commitHalfClaimer || null,
+        edPointClaimer: quote.edPointClaimer || null,
+      };
+      swap.escrow = { ...(swap.escrow || {}),
+        address: offer.escrow, moneroAddress: offer.jointAddress,
+        half: halfHex(own.side.half), viewHalf: halfHex(own.side.viewHalf),
+        edPointClaimer: own.spendPoint, edViewPointClaimer: norm(own.side.viewPub),
+        commitHalfClaimer: quote.commitHalfClaimer,
+        edPointLocker: (offer.nodeHalf && offer.nodeHalf.edPoint) || null,
+        edViewPointLocker: offer.edViewPointLocker || null,
+        commitHalfLocker: (offer.nodeHalf && offer.nodeHalf.commitHalf) || null,
+        orderContext: offer.context || null, xmrAmount: quote.xmrAmount || null,
+      };
+      try { engine.swap.saveSwap(swap); } catch { throw new SdkError("storage-unavailable", { step: "save-swap" }); }
+      return { id: swap.id, side: "sell", escrow: offer.escrow, address: offer.jointAddress,
+        xmrAmount: quote.xmrAmount, claimTip: quote.claimTip || null, orderQuote: offer.orderQuote || null,
+        resumed: false, next: "send-xmr" };
+    },
+
+    /**
+     * CLAIM THE ETH ON A SELL. The half and the expectations are in the record made by `startSell`; the sender
+     * must be the claimer's own wallet.
+     */
+    async sellClaim(request, wallet) {
+      if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      const id = String(request.id || "").trim();
+      if (!id) throw new SdkError("bad-input", { field: "id" });
+      let swap = null;
+      try { swap = engine.swap.getSwap(id); } catch { swap = null; }
+      if (!swap || swap.side !== "sell") throw new SdkError("bad-input", { field: "id", why: "sell-not-found" });
+      const escrow = request.escrow || (swap.escrow && swap.escrow.address) || null;
+      const halfClaimer = request.halfClaimer || (swap.escrow && swap.escrow.half) || null;
+      if (!escrow || !halfClaimer) throw new SdkError("bad-input", { field: "escrow", missing: ["escrow", "halfClaimer"] });
+      const expect = request.expect || swap.expect || null;
+      if (!expect) throw new SdkError("bad-input", { field: "expect", why: "not-in-record" });
+      return actions.claim({ escrow, halfClaimer, claimer: swap.order && swap.order.claimer,
+        expect, onStep: request.onStep }, wallet);
+    },
+
+    /**
+     * WAIT FOR THE NODE'S SIDE ON A SELL. The client sends XMR to the one-time joint address; the node (the
+     * locker) must mark the order ready before the claimer can take the ETH. This reads the escrow itself - no
+     * backend watcher - and returns as soon as the chain says ready, claimed or refunded.
+     */
+    async sellWatch(request) {
+      if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
+      const escrow = String(request.escrow || "").trim();
+      if (!escrow) throw new SdkError("bad-input", { field: "escrow" });
+      const timeoutMs = Number.isFinite(Number(request.timeoutMs)) && Number(request.timeoutMs) > 0
+        ? Number(request.timeoutMs) : limitOf("watchTimeoutMs", 1_200_000);
+      const pollMs = Number.isFinite(Number(request.pollMs)) && Number(request.pollMs) > 0
+        ? Number(request.pollMs) : limitOf("watchPollMs", 6_000);
+      const started = Date.now();
+      let lastStatus = null;
+      let lastError = null;
+      for (;;) {
+        try { lastStatus = await flow.orderStatus(escrow, { call: reader }); }
+        catch (error) { lastError = (error && error.code) || "status-unread"; lastStatus = null; }
+        if (lastStatus && (lastStatus.isClaimed || lastStatus.isRefunded)) {
+          return { escrow, state: lastStatus.isClaimed ? "claimed" : "refunded",
+            funded: lastStatus.isFunded, claimed: lastStatus.isClaimed, refunded: lastStatus.isRefunded,
+            ready: null, balanceWei: String(lastStatus.balance), waitedMs: Date.now() - started };
+        }
+        if (lastStatus && lastStatus.isFunded) {
+          let ready = null;
+          try {
+            const raw = await reader({ to: escrow, data: engine.evm.encodeRead("ready") });
+            const hex = String(raw || "").replace(/^0x/, "");
+            ready = hex.length > 0 && BigInt("0x" + hex) !== 0n;
+          } catch (error) { lastError = (error && error.code) || "ready-unread"; }
+          if (ready === true) {
+            return { escrow, state: "ready", funded: true, claimed: false, refunded: false,
+              ready: true, balanceWei: String(lastStatus.balance), waitedMs: Date.now() - started };
+          }
+        }
+        if (Date.now() - started >= timeoutMs) {
+          throw new SdkError("sell-timeout", { escrow, waitedMs: Date.now() - started, timeoutMs,
+            status: lastStatus, error: lastError });
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+      }
+    },
   };
 }