@ninsei-labs/sdk 0.51.2 → 0.53.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,9 +13,10 @@ 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, 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 { 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.
@@ -27,7 +29,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 +101,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 +135,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 +382,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 +493,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 +544,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
@@ -745,10 +793,29 @@ 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" });
-      // 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 +844,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 +859,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 +870,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 +995,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 +1006,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 +1059,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 +1081,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 +1114,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 +1146,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 +1267,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 +1318,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,

package/src/sweep-fees.mjs

@@ -0,0 +1,32 @@
+// THE FEE OF A WITHDRAWAL IS THE SUM OF EVERY SIGNED TRANSACTION, not the first one.
+//
+// A sweep normally signs one transaction, but the wallet may split the inputs: every transaction pays its own fee
+// and the relay sends all of them. Showing only the first fee understates what leaves, and subtracting only it
+// overstates what the recipient receives.
+//
+// The answer is null when any signed transaction cannot report a fee: a partial total would be a claim the wallet
+// did not make.
+export function signedFeeTotal(signed) {
+  const list = Array.isArray(signed) ? signed : [signed];
+  if (!list.length) return null;
+  let total = 0n;
+  for (const tx of list) {
+    if (!tx || typeof tx.getFee !== "function") return null;
+    let value;
+    try {
+      value = tx.getFee();
+    } catch {
+      return null;
+    }
+    if (value === null || value === undefined) return null;
+    let amount;
+    try {
+      amount = BigInt(value);
+    } catch {
+      return null;
+    }
+    if (amount < 0n) return null;
+    total += amount;
+  }
+  return total.toString();
+}

package/src/sweep-restore.mjs

@@ -62,6 +62,23 @@ const heightOf = async (driver, name) => {
   }
 };
 
+// AN INCOMPLETE SCAN IS A NAMED OUTCOME, NOT A ZERO BALANCE. The wallet library's sync is best-effort: a node
+// that refuses block downloads leaves a wallet at height 0, and a caller that only reads `unlocked` shows "no
+// XMR". The heights and the sync error decide the verdict here, so the page does not have to guess.
+const scanCompleteness = async (driver, { syncError = null, rescanError = null } = {}) => {
+  const walletHeight = await heightOf(driver, "getHeight");
+  const nodeHeight = await heightOf(driver, "getDaemonHeight");
+  let reason = null;
+  // A FAILED RESCAN IS NOT A COMPLETE SCAN even when the heights happen to be equal: the wallet was already at the
+  // tip, the rescan was the only operation that would have walked the restored range, and its failure leaves the
+  // old range unscanned. It outranks the sync error because it names why the sync was a no-op.
+  if (rescanError) reason = "rescan-failed";
+  else if (syncError) reason = "sync-failed";
+  else if (walletHeight === null || nodeHeight === null) reason = "no-heights";
+  else if (walletHeight < nodeHeight) reason = "behind-node";
+  return { scanComplete: reason === null, ...(reason === null ? {} : { scanIncompleteReason: reason }), walletHeight, nodeHeight };
+};
+
 // THE BLOCK WINDOW AROUND THE LOCK. A full rescan of mainnet takes hours; the lock can only be in the blocks from
 // the order's start to just after its t1. The caller may pass the hashes, or a node URL and the SDK asks for them.
 export async function windowTxHashes({ nodeUrl, fromHeight, toHeight, fetchImpl = globalThis.fetch, sleep = defaultSleep, attempts = 3 } = {}) {
@@ -202,10 +219,11 @@ export async function restoreWallet(request = {}) {
     }
     windowReport.txs = hashes.length;
     if (hashes.length && typeof driver.scanTxs === "function") {
+      let windowSyncError = null;
       try {
         await step("setRestoreHeight", () => driver.setRestoreHeight(tipHeight));
         await step("scanTxs", () => driver.scanTxs(hashes));
-        try { await wallet.sync(); } catch { /* the balance below decides */ }
+        try { await wallet.sync(); } catch (error) { windowSyncError = error; }
         windowTotal = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
         windowUnlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
         windowReport.used = true;
@@ -257,9 +275,10 @@ export async function restoreWallet(request = {}) {
       // A WINDOW WITH COINS IS THE ANSWER. A window with none falls through to the full scan unless the caller
       // explicitly turned the fallback off.
       if (windowReport.used && (windowTotal > 0n || windowUnlocked > 0n || requestWindow.fallback === false)) {
+        const completeness = await scanCompleteness(driver, { syncError: windowSyncError });
         return {
-          total: windowTotal.toString(), unlocked: windowUnlocked.toString(), scanHeight, walletHeight: await heightOf(driver, "getHeight"),
-          nodeHeight: await heightOf(driver, "getDaemonHeight"), passes: 1, lockedPass: false, window: windowReport,
+          total: windowTotal.toString(), unlocked: windowUnlocked.toString(), scanHeight,
+          ...completeness, passes: 1, lockedPass: false, window: windowReport,
         };
       }
     } else if (hashes.length) {
@@ -280,12 +299,14 @@ export async function restoreWallet(request = {}) {
   // A RESCAN IS BEST-EFFORT, LIKE THE SYNC BELOW. A wallet built from keys already carries the height it was opened
   // with, and a library that cannot rescan a chain (monero-ts against a regtest node answers "failed to get hashes")
   // would otherwise stop a withdrawal the sync can still serve. The balance below is the verdict, not the rescan.
-  try { await step("rescanBlockchain", () => driver.rescanBlockchain()); } catch { /* the balance decides */ }
+  let rescanError = null;
+  try { await step("rescanBlockchain", () => driver.rescanBlockchain()); } catch (error) { rescanError = error; }
 
   // A FAILED SYNC IS BEST-EFFORT, exactly as in the signing step: what blocks a withdrawal is the spendable
   // remainder, and it is read below. The library throws low-level while scanning a chain it cannot read; that must
-  // not pre-empt the verdict.
-  try { await wallet.sync(); } catch { /* the remainder decides */ }
+  // not pre-empt the verdict. The error is remembered and named in `scanIncompleteReason`.
+  let syncError = null;
+  try { await wallet.sync(); } catch (error) { syncError = error; }
 
   let total = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
   let unlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
@@ -298,18 +319,18 @@ export async function restoreWallet(request = {}) {
   if (rescanWhenLocked && total > 0n && unlocked === 0n && typeof driver.rescanSpent === "function" && passes < PASSES) {
     lockedPass = true;
     await step("rescanSpent", () => driver.rescanSpent());
-    try { await wallet.sync(); } catch { /* as above */ }
+    try { await wallet.sync(); } catch (error) { syncError = error; }
     total = asAmount(await step("getBalance", () => driver.getBalance()), "balance");
     unlocked = asAmount(await step("unlockedBalance", () => wallet.unlockedBalance()), "unlockedBalance");
     passes += 1;
   }
 
+  const completeness = await scanCompleteness(driver, { syncError, rescanError });
   return {
     total: total.toString(),
     unlocked: unlocked.toString(),
     scanHeight,
-    walletHeight: await heightOf(driver, "getHeight"),
-    nodeHeight: await heightOf(driver, "getDaemonHeight"),
+    ...completeness,
     passes,
     // Whether the second pass RAN - not whether it helped. A reader must be able to tell "nothing was locked" from
     // "it was locked and stayed locked".

package/src/sweep.mjs

@@ -11,8 +11,20 @@ import { restoreWallet } from "./sweep-restore.mjs";
 import { moneroWalletAdapter } from "./adapters/monero-wallet.mjs";
 import { checkDestination } from "./destination.mjs";
 import { revealedHalfWord } from "./sweep-half.mjs";
-import { takerHalves } from "./recovery-key.mjs";
+import { takerHalves, takerHalvesV2 } from "./recovery-key.mjs";
 import { jointAddress } from "./order.mjs";
+import { formatXmr } from "../engine/core/xmrAmount.js";
+
+// THE XMR AMOUNT IS PART OF THE RECOVERY FILE. A found order carries the amount the provider signed, in atomic
+// units; the file keeps it in whole XMR, the unit every other payload user reads. An order without the amount
+// stays null rather than silently falling back to the ETH side or to zero.
+const xmrAmountOf = (value) => {
+  if (value === null || value === undefined || value === "") return null;
+  const text = String(value);
+  if (/^\d+$/.test(text)) return formatXmr(BigInt(text));
+  const numeric = Number(text);
+  return Number.isFinite(numeric) && numeric > 0 ? text : null;
+};
 
 // The same boundary as when the file was issued: a passphrase shorter than twelve characters will not open the file.
 const MIN_PASSPHRASE = 12;
@@ -34,8 +46,6 @@ const payloadFromOrder = async (request) => {
   if (typeof request.mnemonic !== "string" || !request.mnemonic.trim()) throw new SdkError("bad-input", { field: "mnemonic" });
   const chainId = Number(request.chainId);
   if (!Number.isSafeInteger(chainId) || chainId <= 0) throw new SdkError("bad-input", { field: "chainId" });
-  const index = Number(order.index);
-  if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "order.index" });
   const network = typeof request.network === "string" ? request.network.trim() : "";
   const moneroNetwork = typeof request.moneroNetwork === "string" ? request.moneroNetwork.trim() : "";
   if (!network) throw new SdkError("bad-input", { field: "network" });
@@ -47,7 +57,20 @@ const payloadFromOrder = async (request) => {
 
   const side = order.side === "locker" ? "buy" : order.side === "claimer" ? "sell" : null;
   if (!side) throw new SdkError("bad-input", { field: "order.side" });
-  const halves = takerHalves({ mnemonic: request.mnemonic, chainId, index });
+  // TWO DERIVATIONS, BOTH LIVE. A v1 order has an index; a v2 order has the public salt from OrderCreated and
+  // the factory in its binding. The page may hand either shape back; reading `index` from a v2 order would invent
+  // a number and rebuild the wrong address.
+  let halves;
+  if (order.derivation === "salt-v2") {
+    if (typeof order.factory !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(order.factory)) {
+      throw new SdkError("bad-input", { field: "order.factory" });
+    }
+    halves = takerHalvesV2({ mnemonic: request.mnemonic, chainId, factory: order.factory, salt: order.salt });
+  } else {
+    const index = Number(order.index);
+    if (!Number.isSafeInteger(index) || index < 0) throw new SdkError("bad-input", { field: "order.index" });
+    halves = takerHalves({ mnemonic: request.mnemonic, chainId, index });
+  }
   const buy = side === "buy";
   if (bare(buy ? order.edPointLocker : order.edPointClaimer) !== bare(halves.spendPoint)) {
     throw new SdkError("bad-input", { field: "order", why: "spend-point" });
@@ -67,7 +90,7 @@ const payloadFromOrder = async (request) => {
     swap: {
       id: order.escrow, side, network, moneroNetwork,
       createdAt: order.blockTime ? Number(order.blockTime) * 1000 : null,
-      payToken: null, payAmount: null, xmrAmount: null, rate: null, maker: null, quoteSignature: null,
+      payToken: null, payAmount: null, xmrAmount: xmrAmountOf(order.xmrAmount), rate: null, maker: null, quoteSignature: null,
       escrow, timeline: null,
     },
     swapWallet: {