@ninsei-labs/sdk 0.51.2 → 0.53.0

package/engine/evm/factory.js

@@ -22,11 +22,18 @@ export const FACTORY_METHODS = {
   createOrderAndFund: "0x3a504547",
 };
 
-// The OrderCreated event topic. It grew the registry address, the provider and the signing key:
-//   cast keccak "OrderCreated(address,address,address,bytes32,bytes32,bytes32,bytes32,bytes32,uint256,uint64,uint64,bytes32,address,address,address)"
+// The OrderCreated event topic. It grew the registry address, the provider and the signing key, and now carries
+// `xmrAmount` in bulk (#32):
+//   cast keccak "OrderCreated(address,address,address,bytes32,bytes32,bytes32,bytes32,bytes32,uint256,uint256,uint64,uint64,bytes32,address,address,address)"
 // The topic lives in TWO places and both must match; a check pins them.
 export const ORDER_CREATED_TOPIC =
+  "0x09add13cca47b227c377447295bfaa00ef3169bfed0f5513d06f8be04af78aad";
+
+// THE PREVIOUS EVENT, KEPT FOR ORDERS ALREADY ON CHAIN. It has no `xmrAmount`, so those orders still fall back to
+// reading word 18 of the clone's code. A new order uses the topic above.
+export const ORDER_CREATED_TOPIC_V1 =
   "0xa22cdabaed3cce4f51dde71626a108ffe9c7bc4216fd14d5e719f892e2fd8ab0";
+export const ORDER_CREATED_TOPICS = Object.freeze([ORDER_CREATED_TOPIC, ORDER_CREATED_TOPIC_V1]);
 
 // QUOTE FIELDS IN CONTRACT ORDER. The order is part of the ABI: a swap gives another call. One list for both
 // functions, so they cannot diverge.

package/engine/evm/funding.js

@@ -125,18 +125,45 @@ export const GAS_CREATE_ORDER_AND_FUND = 700_000n;
 
 // The ACTUAL escrow address from the receipt. Returns null when the event is absent (the transaction is not in a
 // block, or the factory is another) - then the caller must say so aloud rather than substitute a guess.
-export function escrowFromReceipt(receipt) {
+export function escrowFromReceipt(receipt, { factory = null, expectedEscrow = null } = {}) {
   if (!receipt || !Array.isArray(receipt.logs)) return null;
+  const wantFactory = factory ? String(factory).toLowerCase() : null;
+  const wantEscrow = expectedEscrow ? String(expectedEscrow).toLowerCase() : null;
   for (const log of receipt.logs) {
+    // THE EVENT MUST COME FROM THE FACTORY THAT WAS CALLED. Another contract can emit the same topic; accepting
+    // it would let a receipt from a different order name the escrow that gets saved and used for the withdrawal.
+    if (wantFactory && String(log && log.address || "").toLowerCase() !== wantFactory) continue;
     const topics = log.topics || [];
     if (String(topics[0]).toLowerCase() !== ORDER_CREATED_TOPIC) continue;
     if (topics.length < 2) continue;
     const addr = "0x" + String(topics[1]).slice(26).toLowerCase();
-    if (/^0x[0-9a-f]{40}$/.test(addr) && !/^0x0{40}$/.test(addr)) return addr;
+    if (!/^0x[0-9a-f]{40}$/.test(addr) || /^0x0{40}$/.test(addr)) continue;
+    // THE PREDICTED ADDRESS IS THE EXPECTED ONE. A different escrow in the same factory is not this order; the
+    // caller must not save it as funded.
+    if (wantEscrow && addr !== wantEscrow) continue;
+    return addr;
   }
   return null;
 }
 
+// A RECEIPT IS A VERDICT, NOT A PRESENCE CHECK. `status: 0` is a reverted transaction; a receipt with no
+// OrderCreated from the expected factory is not a funded escrow; a missing receipt is pending. Only status 1 plus
+// the expected event is funded, and the caller saves the escrow only on that answer.
+export function fundingReceiptVerdict(receipt, { factory = null, expectedEscrow = null } = {}) {
+  if (!receipt || typeof receipt !== "object") return { status: "pending", reason: "no-receipt" };
+  if (receipt.status === undefined || receipt.status === null || receipt.status === "") {
+    return { status: "pending", reason: "no-status" };
+  }
+  const status = Number(receipt.status);
+  if (!Number.isFinite(status)) return { status: "pending", reason: "bad-status" };
+  if (status === 0) return { status: "reverted", reason: "status-0" };
+  if (status !== 1) return { status: "pending", reason: "bad-status" };
+  const escrow = escrowFromReceipt(receipt, { factory, expectedEscrow });
+  if (!escrow) return { status: "pending", reason: "no-order-created" };
+  const blockNumber = Number(receipt.blockNumber);
+  return { status: "funded", escrow, birthBlock: Number.isFinite(blockNumber) ? blockNumber : null };
+}
+
 // Wait for a receipt: right after signing there is none, which is normal. Waiting forever is not allowed - we say so honestly.
 async function waitReceipt(receiptReader, hash, { tries = 12, delayMs = 1500 } = {}) {
   for (let i = 0; i < tries; i += 1) {
@@ -184,8 +211,13 @@ export async function fundOrder({ factory, locker, claimer, commitHalfLocker, co
   // THE DEPOSITOR'S FIELDS GO AS SEPARATE FACTORY ARGUMENTS (they are not in the signed set).
   const quoteEnc = { ...quote, commitHalfLocker: terms.commitHalfLocker, edPointLocker: terms.edPointLocker, edViewPointLocker: terms.edViewPointLocker };
   // QUOTE AND TERMS ARE ABOUT ONE THING: a divergence moves the escrow address and signs the wrong order.
-  for (const name of ["locker", "claimer", "amount", "readyBy", "t1", "salt"]) {
-    if (String(quote[name]).toLowerCase() !== String(terms[name]).toLowerCase()) {
+  // THE COUNTERPARTY'S SPEND HALF IS PART OF THAT ONE THING. The proof is checked against the counterparty side,
+  // while the factory encodes the signed quote; without comparing these two fields a quote that commits to one
+  // point can be funded beside a proof for another, and the claim reveals a half that does not open the address.
+  const sameValue = (a, b) => String(a === undefined || a === null ? "" : a).replace(/^0x/i, "").toLowerCase()
+    === String(b === undefined || b === null ? "" : b).replace(/^0x/i, "").toLowerCase();
+  for (const name of ["locker", "claimer", "amount", "readyBy", "t1", "salt", "commitHalfClaimer", "edPointClaimer"]) {
+    if (!sameValue(quote[name], terms[name])) {
       throw new Error("the quote and the order terms diverge on field " + name);
     }
   }
@@ -260,20 +292,29 @@ export async function fundOrder({ factory, locker, claimer, commitHalfLocker, co
   // independent of the Monero node. Declared outside the branch on purpose: a variable declared inside a block is
   // not visible outside, and it must always be returned.
   let birthBlock = null;
+  let verdict = { status: "pending", reason: "no-receipt-reader" };
   if (typeof receipt === "function") {
     const rc = await waitReceipt(receipt, createHash);
-    actualEscrow = escrowFromReceipt(rc);
-    if (rc && Number.isFinite(Number(rc.blockNumber))) birthBlock = Number(rc.blockNumber);
-    if (!rc) {
-      onStep?.("no receipt yet - using the predicted address");
-    } else if (!actualEscrow) {
-      onStep?.("no OrderCreated in the receipt - using the predicted address");
-    } else if (actualEscrow !== String(escrow).toLowerCase()) {
-      console.warn("[escrow] receipt address " + actualEscrow + " != predicted " + escrow + " - using the receipt one");
-      onStep?.("receipt address differs from predicted - using the receipt one");
+    verdict = fundingReceiptVerdict(rc, { factory, expectedEscrow: escrow });
+    if (verdict.status === "reverted") {
+      const error = new Error("the funding transaction reverted");
+      error.code = "contract-reverted";
+      error.receiptStatus = 0;
+      throw error;
+    }
+    if (verdict.status === "funded") {
+      actualEscrow = verdict.escrow;
+      birthBlock = verdict.birthBlock;
+      if (actualEscrow !== String(escrow).toLowerCase()) {
+        console.warn("[escrow] receipt address " + actualEscrow + " != predicted " + escrow + " - using the receipt one");
+        onStep?.("receipt address differs from predicted - using the receipt one");
+      }
+    } else if (!rc) {
+      onStep?.("no receipt yet - funding is pending, not funded");
+    } else {
+      onStep?.("receipt has no matching OrderCreated - funding is pending, not funded");
     }
   }
-  const escrowToUse = actualEscrow || escrow;
 
   // 3) THE SECOND TRANSACTION IS GONE: the money left together with order creation. The name lockHash is kept on
   // purpose - callers look at it, and renaming would touch them with no benefit. THERE IS AND WILL BE NO TOP-UP:
@@ -282,10 +323,16 @@ export async function fundOrder({ factory, locker, claimer, commitHalfLocker, co
   // created without money.
   const lockHash = createHash;
 
-  // escrow is the ACTUAL address (from the receipt, if there was one); predictedEscrow is kept so a divergence is
-  // visible outside, not only in the log.
+  // ONLY A STATUS-1 RECEIPT WITH THE EXPECTED ORDER CREATED IS FUNDED. A missing receipt, a receipt without the
+  // event, or an event from another factory keeps `escrow` null and is returned as pending; the caller must not
+  // save it, retire a recovery number for it, or call it xmr-incoming.
   // THE FEE GOES OUTWARD: it went into the transaction and the deal record must keep it - otherwise the record
   // cannot tell how much the person deposited, and it would diverge from what the chain shows.
-  return { feeWei: fee.feeWei, feeTotalWei: totalValueWei, feeBps: fee.bps, feeWasLegacyFactory: Boolean(fee.legacy),
-           escrow: escrowToUse, predictedEscrow: escrow, escrowMismatch: Boolean(actualEscrow && actualEscrow !== String(escrow).toLowerCase()), salt, birthBlock, terms, createHash, lockHash };
+  const common = { feeWei: fee.feeWei, feeTotalWei: totalValueWei, feeBps: fee.bps, feeWasLegacyFactory: Boolean(fee.legacy),
+    predictedEscrow: escrow, salt, terms, createHash, lockHash };
+  if (verdict.status !== "funded") {
+    return { ...common, escrow: null, birthBlock: null, funded: false, pending: true, pendingReason: verdict.reason };
+  }
+  return { ...common, escrow: actualEscrow, escrowMismatch: actualEscrow !== String(escrow).toLowerCase(),
+    birthBlock, funded: true, pending: false };
 }

package/engine/monero/arrivalRead.js

@@ -71,25 +71,6 @@ export function viewKeyMatchesAddress(viewScalar, expectedViewPubHex, halves) {
   return got === want;
 }
 
-/** A boundary up to this value is a BLOCK HEIGHT; from it on, a unix TIME. Monero's own convention. */
-export const UNLOCK_TIME_BLOCK_MAX = 500_000_000;
-
-/**
- * IS THE COIN SPENDABLE AT THIS MOMENT, AND IF NOT, WHAT IS THE BOUNDARY.
- *
- * `unlocked` / `locked_height` / `locked_time`, with the boundary named in `untilHeight` or `untilTime`. A height
- * that is not known is NOT "unlocked": without a height the answer stays locked, because the caller has no fact
- * that would open it. `nowSec` defaults to the wall clock, and is a parameter so a check can pin it.
- */
-export function unlockStateOf(unlockTime, { height = null, nowSec = null } = {}) {
-  const u = Number(unlockTime) || 0;
-  if (u <= 0) return { code: "unlocked", locked: false, untilHeight: null, untilTime: null };
-  if (u >= UNLOCK_TIME_BLOCK_MAX) {
-    const now = nowSec === null || nowSec === undefined ? Math.floor(Date.now() / 1000) : Number(nowSec);
-    const open = Number.isFinite(now) && now >= u;
-    return { code: open ? "unlocked" : "locked_time", locked: !open, untilHeight: null, untilTime: u };
-  }
-  const h = height === null || height === undefined ? null : Number(height);
-  const open = h !== null && Number.isFinite(h) && h >= u;
-  return { code: open ? "unlocked" : "locked_height", locked: !open, untilHeight: u, untilTime: null };
-}
+// THE UNLOCK RULE HAS ONE HOME: ./unlock.js. This module re-exports it for the public xmr entry instead of keeping
+// a second copy; a second copy is a second truth about whether money can be spent.
+export { UNLOCK_TIME_BLOCK_MAX, unlockStateOf } from "./unlock.js";

package/engine/monero/halvesSweep.js

@@ -15,7 +15,11 @@ export function spendKeysFromRevealedHalf({
   for (const [name, v] of Object.entries({ ownSpendHalf, ownViewHalf, otherSpendPoint, otherViewHalf, revealedHalf })) {
     if (v === undefined || v === null || v === "") throw new Error("not set: " + name);
   }
-  const sum = halves.combineHalves(BigInt(ownSpendHalf), BigInt(revealedHalf));
+  // THE CONTRACT ACCEPTS THE REAL HALF PLUS THE SECP256K1 ORDER. `claim` and `refund` do not reject `h + n` (the
+  // escrow only hashes the word), but adding n is not the same point on edwards25519. Reduce the public word by the
+  // secp order first: the small real half is unchanged, and the alias lands on the same scalar.
+  const revealed = BigInt(revealedHalf) % halves.SECP_ORDER;
+  const sum = halves.combineHalves(BigInt(ownSpendHalf), revealed);
   const sumPub = halves.publicHalves(sum).ed;
   // The expected spend key is built FROM OWN HALF AND THE COUNTERPARTY POINT (what was in the order).
   // The half from the file arrives as a string, so it must be converted - forgetting this crashed the XMR

package/engine/monero/scan.js

@@ -33,6 +33,25 @@ export function keccak(bytes) { return keccak_256(bytes); }
 // corrupt the scalar, the derivation and the sum - an "invisible arrival".
 export const ED_ORDER = ed25519.Point.CURVE().n;
 
+// THE SECOND PEDERSEN GENERATOR, FROM THE MONERO SOURCE. `rct::H` is a fixed point whose discrete logarithm to
+// the base point is unknown: C = mask*G + amount*H. The bytes are the compressed point from
+// monero/src/ringct/rctTypes.h (`static const key H`), not a value recomputed from a remembered string.
+// It is the same point the DLEQ module calls Galt - one constant, two uses, no second derivation.
+export const PEDERSEN_H = "8b655970153799af2aeadc9ff1add0ea6c7251d54154cfa92c173a0dd39c1f94";
+const PEDERSEN_H_POINT = ed25519.Point.fromHex(PEDERSEN_H);
+
+function scalarPoint(point, scalar) {
+  const mod = ((BigInt(scalar) % ED_ORDER) + ED_ORDER) % ED_ORDER;
+  return mod === 0n ? ed25519.Point.ZERO : point.multiply(mod);
+}
+
+/** The Pedersen commitment C = mask*G + amount*H, compressed. Used to check a decoded amount against `outPk`. */
+export function amountMaskCommitment(amount, mask) {
+  const value = BigInt(amount);
+  if (value < 0n) throw new Error("the amount must not be negative");
+  return scalarPoint(ed25519.Point.BASE, mask).add(scalarPoint(PEDERSEN_H_POINT, value)).toHex();
+}
+
 export function hexToBytes(hex) {
   const t = String(hex).trim().replace(/^0x/, "");
   if (t.length % 2) throw new Error("odd hex length");
@@ -138,32 +157,52 @@ export function txPublicKeyFromExtra(extra) {
   return null;
 }
 
-// Amount decryption. version: 2 = current scheme (xor of the first 8 bytes), 1 = old (scalar subtraction).
+// Amount and mask decryption. THE ENCODING IS CHOSEN BY THE RingCT TYPE, not by a boolean:
+//   types 0-3 (old): every ecdhInfo entry carries a 32-byte amount and a 32-byte mask;
+//   types 4-6 (Bulletproof2, CLSAG, BulletproofPlus): the entry carries only the 8-byte amount, and the
+//   receiver DERIVES the mask as Hs("commitment_mask" || sharedSec). A transaction from a current node has no
+//   `ecdhInfo.mask` at all.
 //
 // THE SECRET IS THE DERIVATION SCALAR, NOT THE DERIVATION. Easy to get wrong: both are 32 bytes, but what goes
 // into genAmountEncodingFactor is the scalar (derivation_to_scalar), written LEAST-SIGNIFICANT first. With the
 // derivation the result looks plausible and is WRONG (checked on live numbers).
-export function decodeAmount(ecdhAmountHex, scalarLE, rctVersion) {
-  const enc = hexToBytes(ecdhAmountHex);
-  if (Number(rctVersion) >= 2) {
-    // Multiplier: keccak("amount" || scalar_LE), 38 bytes - order checked against the source.
-    const label = new TextEncoder().encode("amount");
-    const buf = new Uint8Array(label.length + scalarLE.length);
-    buf.set(label, 0); buf.set(scalarLE, label.length);
+//
+// THE TWO OLD FACTORS ARE DIFFERENT: amount -= Hs(Hs(sharedSec)), mask -= Hs(sharedSec). Using the amount's
+// double hash for the mask (the first version) makes every old-encoding commitment fail.
+function compactEncoding(rctType) { return Number(rctType) >= 4; }
+function oldFactor(scalarLE, label) {
+  const base = hashToScalar(scalarLE);
+  if (label === "mask") return base;
+  return hashToScalar(hexToBytes(base.toString(16).padStart(64, "0")));
+}
+function decodeField(ecdhHex, scalarLE, rctType, label) {
+  if (compactEncoding(rctType)) {
+    if (label === "mask") return hashToScalar(new TextEncoder().encode("commitment_mask"), scalarLE);
+    const enc = hexToBytes(ecdhHex);
+    const prefix = new TextEncoder().encode(label);
+    const buf = new Uint8Array(prefix.length + scalarLE.length);
+    buf.set(prefix, 0); buf.set(scalarLE, prefix.length);
     const factor = keccak(buf);
     const out = enc.slice();
-    for (let i = 0; i < 8; i++) out[i] ^= factor[i];             // xor of the FIRST 8 bytes only
-    // And again LEAST-SIGNIFICANT first: Monero amounts are little-endian too.
+    for (let i = 0; i < out.length && i < factor.length; i++) out[i] ^= factor[i];
     return scalarFromBytesLE(out);
   }
-  const s2 = hashToScalar(hexToBytes(hashToScalar(hexToBytes(bytesToHex(rctVersion === 1 ? scalarLE : scalarLE))).toString(16).padStart(64, "0")));
-  const amt = BigInt("0x" + bytesToHex(enc)) % ED_ORDER;
-  return (amt - s2 + ED_ORDER) % ED_ORDER;
+  const enc = hexToBytes(ecdhHex);
+  const value = BigInt("0x" + bytesToHex(enc)) % ED_ORDER;
+  return (value - oldFactor(scalarLE, label) + ED_ORDER) % ED_ORDER;
+}
+
+export function decodeAmount(ecdhAmountHex, scalarLE, rctType) {
+  return decodeField(ecdhAmountHex, scalarLE, rctType, "amount");
+}
+
+export function decodeMask(ecdhMaskHex, scalarLE, rctType) {
+  return decodeField(ecdhMaskHex, scalarLE, rctType, "mask");
 }
 
 // MAIN: parse a transaction and return OUR outputs (their indices, keys and amounts).
-// txView - { txPublicKey, vout: [{key, index}], ecdhAmounts: [...], rctVersion }
-export function findOurOutputs({ txPublicKey, viewSecretHex, spendPubHex, outputs, ecdhAmounts = [], rctVersion = 2 }) {
+// txView - { txPublicKey, vout: [{key, index}], ecdhAmounts: [...], ecdhMasks: [...], outPk: [...], rctVersion }
+export function findOurOutputs({ txPublicKey, viewSecretHex, spendPubHex, outputs, ecdhAmounts = [], ecdhMasks = [], outPk = [], rctVersion = 2 }) {
   if (!txPublicKey) throw new Error("the transaction has no public key (extra tag 0x01) - nothing to parse");
   // The key form is tried EXPLICITLY; the winner's name goes up so the log shows what was used. If none matched,
   // the first meaningful form is returned, not nothing.
@@ -178,7 +217,20 @@ export function findOurOutputs({ txPublicKey, viewSecretHex, spendPubHex, output
       if (derived.toLowerCase() === String(o.key).toLowerCase()) {
         // The amount decryption uses THIS output's SCALAR, least-significant first.
         const amount = ecdhAmounts[o.index] ? decodeAmount(ecdhAmounts[o.index], scalarToBytesLE(scalar), rctVersion) : null;
-        found.push({ index: o.index, key: o.key, amountAtomic: amount });
+        // THE COMMITMENT CHECK: outPk[i] = mask*G + amount*H. A node can flip a bit of the encrypted amount
+        // without any key; the commitment is the only figure it cannot forge. A missing or mismatching
+        // commitment is named on the output instead of being accepted as an arrival.
+        // COMPACT TYPES HAVE NO mask FIELD: it is derived from the same scalar. Old types carry it.
+        const mask = compactEncoding(rctVersion)
+          ? decodeMask(null, scalarToBytesLE(scalar), rctVersion)
+          : (ecdhMasks[o.index] ? decodeMask(ecdhMasks[o.index], scalarToBytesLE(scalar), rctVersion) : null);
+        let amountVerified = false;
+        if (amount !== null && mask !== null && outPk[o.index]) {
+          try {
+            amountVerified = amountMaskCommitment(amount, mask).toLowerCase() === String(outPk[o.index]).replace(/^0x/, "").toLowerCase();
+          } catch { amountVerified = false; }
+        }
+        found.push({ index: o.index, key: o.key, amountAtomic: amount, maskAtomic: mask, amountVerified });
       }
     }
     if (found.length) return { derivation: bytesToHex(derivation), outputs: found, viewKeyForm: form };
@@ -200,31 +252,69 @@ export function findOurOutputs({ txPublicKey, viewSecretHex, spendPubHex, output
 // ============================================================================================
 
 
-export async function fetchBlock(daemonUrl, height) {
-  const res = await fetch(`${String(daemonUrl).replace(/\/+$/, "")}/json_rpc`, {
+// A trailing-slash trim without a backtracking regular expression: the daemon URL is caller input, and CodeQL
+// flags `/+$` on a long run of slashes as a possible denial of service.
+const baseUrl = (value) => {
+  let out = String(value);
+  while (out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+};
+
+export async function fetchBlock(daemonUrl, height, fetchImpl = globalThis.fetch) {
+  const res = await fetchImpl(`${baseUrl(daemonUrl)}/json_rpc`, {
     method: "POST", headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ jsonrpc: "2.0", id: "block", method: "get_block", params: { height } }),
   });
   const j = await res.json();
+  // A BUSY ANSWER IS NOT AN EMPTY BLOCK. The daemon answers BUSY while it is still indexing; a reader that treats
+  // the missing `json` as "no transactions" reports a complete range with a smaller balance.
+  if (j && String(j.status || "").toUpperCase() === "BUSY") throw new Error(`block ${height}: daemon is BUSY`);
   if (!j.result) throw new Error(`block ${height} not received: ${j.error ? j.error.message : "empty answer"}`);
+  if (String(j.result.status || "").toUpperCase() === "BUSY") throw new Error(`block ${height}: daemon is BUSY`);
+  // THE BLOCK MUST CARRY ITS DECODED BODY. `json` is what scanRange walks; without it the block is unreadable, not
+  // empty. A result with only a blob or a header is refused by the same rule.
+  if (j.result.json === undefined || j.result.json === null || j.result.json === "") {
+    throw new Error(`block ${height}: no decoded body`);
+  }
   return j.result;
 }
 
 // Transactions by hash list. We hit the PATH /get_transactions, not /json_rpc: over JSON-RPC this method
 // silently returns empty, which looks like "no transactions".
-export async function fetchTransactions(daemonUrl, hashes) {
+export async function fetchTransactions(daemonUrl, hashes, fetchImpl = globalThis.fetch) {
   if (!hashes.length) return [];
-  const res = await fetch(`${String(daemonUrl).replace(/\/+$/, "")}/get_transactions`, {
+  const res = await fetchImpl(`${baseUrl(daemonUrl)}/get_transactions`, {
     method: "POST", headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ txs_hashes: hashes, decode_as_json: true }),
   });
   const j = await res.json();
-  const wrappers = j.txs || [];
+  // A BUSY ANSWER IS NOT AN EMPTY BLOCK. The daemon says BUSY while it is still indexing; returning [] would turn
+  // money that is there into a complete scan with a zero balance.
+  if (j && String(j.status || "").toUpperCase() === "BUSY") throw new Error("transactions-busy");
+  const wrappers = Array.isArray(j && j.txs) ? j.txs : [];
+  const encoded = Array.isArray(j && j.txs_as_json) ? j.txs_as_json : [];
+  // EVERY HASH WE ASKED FOR MUST COME BACK. A partial answer is a missing block, not a quiet "no transactions".
+  const requested = [...new Set(hashes.map((h) => String(h).replace(/^0x/, "").toLowerCase()))];
+  const byHash = new Map();
+  for (const wrapper of wrappers) {
+    const hash = String((wrapper && wrapper.tx_hash) || "").replace(/^0x/, "").toLowerCase();
+    if (!hash) continue;
+    if (byHash.has(hash)) throw new Error("transactions-duplicate: " + hash);
+    byHash.set(hash, wrapper);
+  }
+  const missing = requested.filter((h) => !byHash.has(h));
+  if (missing.length) throw new Error("transactions-missing: " + missing.length);
+  // EXACTLY THE REQUESTED SET. An extra transaction is not money this range asked for, and it may belong to another
+  // block; counting it silently inflates the sum. A decoded body is required for every wrapper, one for one.
+  if (byHash.size !== requested.length) throw new Error("transactions-extra: " + (byHash.size - requested.length));
+  if (encoded.length !== wrappers.length) throw new Error("transactions-undecoded");
   // HASH AND HEIGHT LIVE IN THE WRAPPER, not in the parsed body: as_json omits them. Without this stitching a
   // "found transfer" would have neither hash nor height - useless to the caller, yet everything would look successful.
-  return (j.txs_as_json || []).map((s, i) => {
+  const indexOf = new Map(wrappers.map((w, i) => [String((w && w.tx_hash) || "").replace(/^0x/, "").toLowerCase(), i]));
+  return requested.map((hash) => {
+    const w = byHash.get(hash) || {};
+    const s = encoded[indexOf.get(hash)];
     const body = typeof s === "string" ? JSON.parse(s) : s;
-    const w = wrappers[i] || {};
     body.tx_hash = w.tx_hash || body.tx_hash || null;
     body.block_height = w.block_height ?? null;
     body.confirmations = w.confirmations ?? null;
@@ -235,22 +325,29 @@ export async function fetchTransactions(daemonUrl, hashes) {
 
 // Parsing one transaction against the watched addresses. watched: [{ address, viewSecret, spendPub }] - viewSecret
 // is taken as a number, LE-hex or BE-hex. The result carries viewKeyForm: the form name that matched.
-export function matchTransaction(tx, watched, { height = null, nowSec = null } = {}) {
+export function matchTransaction(tx, watched, { height = null, tipHeight = null, nowSec = null } = {}) {
   const out = [];
   const txPublicKey = txPublicKeyFromExtra(tx.extra);
   if (!txPublicKey) return out;                       // no key in extra - nothing to look at
   // WHETHER THE OUTPUT IS LOCKED IS DECIDED HERE, ONCE PER TRANSACTION: all its outputs carry one unlock_time.
   // A normal transaction (unlock_time = 0) goes as before; the height comes from the block holding the transfer.
   const blockHeight = height === null || height === undefined ? (tx.block_height ?? null) : height;
-  const unlock = unlockStateOf(tx.unlock_time, { height: blockHeight, nowSec });
+  // THE INCLUSION HEIGHT IS FOR CONFIRMATIONS, THE TIP FOR THE LOCK. A height lock at 101 is open once the chain
+  // has reached 101, not once the transaction was mined at 100; using the inclusion height kept a matured lock
+  // reporting `xmr-locked` forever.
+  const unlockHeight = tipHeight === null || tipHeight === undefined ? blockHeight : Number(tipHeight);
+  const unlock = unlockStateOf(tx.unlock_time, { height: unlockHeight, nowSec });
   const keyOf = (o) => ((o.target || {}).tagged_key || o.target || {}).key;
   const outputs = (tx.vout || []).map((o, i) => ({ index: i, key: keyOf(o) }));
-  const ecdhAmounts = ((tx.rct_signatures || {}).ecdhInfo || []).map((e) => e.amount);
+  const ecdh = ((tx.rct_signatures || {}).ecdhInfo || []);
+  const ecdhAmounts = ecdh.map((e) => e.amount);
+  const ecdhMasks = ecdh.map((e) => e.mask);
+  const outPk = ((tx.rct_signatures || {}).outPk || []);
   const rctVersion = (tx.rct_signatures || {}).type || 2;
   for (const w of watched) {
     const r = findOurOutputs({
       txPublicKey, viewSecretHex: w.viewSecret, spendPubHex: w.spendPub,
-      outputs, ecdhAmounts, rctVersion: Number(rctVersion) >= 2 ? 2 : 1,
+      outputs, ecdhAmounts, ecdhMasks, outPk, rctVersion: Number(rctVersion) || 1,
     });
     if (r.outputs.length) out.push({ address: w.address, index: w.index ?? null, outputs: r.outputs, derivation: r.derivation, viewKeyForm: r.viewKeyForm, unlockTime: Number(tx.unlock_time) || 0, unlock });
   }
@@ -259,13 +356,14 @@ export function matchTransaction(tx, watched, { height = null, nowSec = null } =
 
 // Range scan. Returns per address the sum (receivedAtomic - only the UNLOCKED), hashes, the locked sum
 // (lockedAtomic) with its boundary (lockedUntil) and the best (highest) height of a found output.
-export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log = () => {}, concurrency = 4, nowSec = null }) {
+export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log = () => {}, concurrency = 4, nowSec = null, tipHeight = null, fetchImpl = globalThis.fetch }) {
   const from = Number(fromHeight), to = Number(toHeight);
   if (!(from >= 0) || !(to >= from)) throw new Error("bad height range: " + fromHeight + ".." + toHeight);
   const acc = new Map();
   for (const w of watched) acc.set(w.address, { address: w.address, receivedAtomic: 0n, lockedAtomic: 0n, lockedUntil: null, lockedTxids: [], txids: [], bestHeight: null, outputs: 0, viewKeyForm: null });
   const heights = [];
   for (let h = from; h <= to; h++) heights.push(h);
+  const missingHeights = [];
 
   // Bounded parallelism: the node is a shared resource and blocks are independent.
   let cursor = 0;
@@ -273,19 +371,21 @@ export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log
     while (cursor < heights.length) {
       const h = heights[cursor++];
       try {
-        const block = await fetchBlock(daemonUrl, h);
+        const block = await fetchBlock(daemonUrl, h, fetchImpl);
         const hashes = block.json ? (typeof block.json === "string" ? JSON.parse(block.json) : block.json).tx_hashes || [] : [];
         if (!hashes.length) continue;
-        const txs = await fetchTransactions(daemonUrl, hashes);
+        const txs = await fetchTransactions(daemonUrl, hashes, fetchImpl);
         for (const tx of txs) {
-          for (const hit of matchTransaction(tx, watched, { height: h, nowSec })) {
+          for (const hit of matchTransaction(tx, watched, { height: h, tipHeight: tipHeight === null || tipHeight === undefined ? to : tipHeight, nowSec })) {
             const a = acc.get(hit.address);
             if (!a) continue;
             if (hit.viewKeyForm) a.viewKeyForm = hit.viewKeyForm;   // what matched - this goes to the log
             const lockedHere = !!(hit.unlock && hit.unlock.locked);
             const hash = String(tx.tx_hash || "").replace(/^0x/, "");
             for (const o of hit.outputs) {
-              const amount = o.amountAtomic || 0n;
+              // AN UNVERIFIED AMOUNT IS NOT MONEY. A node can alter ecdhInfo.amount; until the Pedersen
+              // commitment confirms it, the figure is not added to any sum.
+              const amount = o.amountVerified ? (o.amountAtomic || 0n) : 0n;
               // A LOCKED OUTPUT IS NOT AN ARRIVAL. Its transfer shows in txids (money is on the address) but the
               // sum does NOT go into receivedAtomic: else 'ready' would allow claiming ETH against locked XMR.
               if (lockedHere) {
@@ -302,11 +402,22 @@ export async function scanRange({ daemonUrl, fromHeight, toHeight, watched, log
           }
         }
       } catch (e) {
+        // A BLOCK THAT COULD NOT BE READ IS NOT A BLOCK WITH NO MONEY. Keep its height so the caller can say the
+        // range is partial instead of treating a smaller sum as complete.
+        missingHeights.push(h);
         log({ event: "indexer_block_error", height: h, error: String(e.message).slice(0, 160) });
       }
     }
   };
   await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, heights.length)) }, worker));
-  return { fromHeight: from, toHeight: to, results: Array.from(acc.values()) };
+  const missing = [...new Set(missingHeights)].sort((a, b) => a - b);
+  return {
+    fromHeight: from,
+    toHeight: to,
+    results: Array.from(acc.values()),
+    complete: missing.length === 0,
+    missingHeights: missing,
+    ...(missing.length ? { incompleteReason: "blocks-unreadable" } : {}),
+  };
 }
 

package/index.d.ts

@@ -9,7 +9,7 @@
 //   2) not a single DOM access: `document`, `window`, `localStorage` do not occur in the SDK. Storage and the wallet
 //      come from outside: as an adapter and an EIP-1193 provider;
 //   3) the SDK opens no windows: the interface shows the wallet modal, the SDK accepts a ready provider;
-//   4) funds are not locked until the interface has confirmed the recovery file is saved (onRecoveryFile);
+//   4) funds are not locked until the interface has confirmed the one recovery key is saved (onRecoveryKey);
 //   5) the guards cannot be bypassed: preflight is part of the same path, not a separate button.
 //
 // Naming language: the values are data. `step` and `code` are stable strings from the tables below; they are
@@ -288,7 +288,15 @@ export interface SdkConfig {
 export interface ChainConfig {
   readonly id: string;
   /** The network's virtual machine: "evm" today; "tron" and "solana" - when their leg drivers appear. */
-  readonly vm: string;
+  readonly vm: string | null;
+  /** What this settlement side looks like. Metadata only: it does not claim that a driver exists. */
+  readonly settlementProfile?: {
+    readonly vm: string;
+    readonly addressFormat: string;
+    readonly settlementKind: "contract" | "program" | "utxo-script" | string;
+    readonly refKind: "address" | "pda" | "script" | string;
+    readonly txRef: "hash" | "signature" | "txid" | string;
+  } | null;
   readonly chainId: number;
   readonly name: string;
   readonly nativeSymbol: string;
@@ -742,14 +750,12 @@ export interface SwapsApi {
   /**
    * Start a swap. The SDK holds the step order, not the screen:
    *   1) guards (preflight); 2) the swap record (createSwap); 3) the order - it GENERATES the key halves;
-   *   4) the recovery file / one key and the interface's confirmation that it is saved; 5) locking the funds (signature);
+   *   4) the one recovery key and the interface's confirmation that it is saved; 5) locking the funds (signature);
    *   6) saving on the server; 7) opening the watch on the Monero address.
-   * HALVES DO NOT EXIST BEFORE THE ORDER: the recovery file carries MY half of the spend key and the counterparty's
-   * open points, and they are taken from the signed order (www/js/atomic/order-worker.js, createOrderBuilder; in the
-   * engine they are fetched by halvesWalletOf). So the file is assembled AFTER the order, but BEFORE locking the
-   * funds.
-   * FUNDS ARE NOT LOCKED UNTIL onRecoveryFile ALLOWS IT: the order is like this not for convenience, but because a
-   * lock without a recovery file is a lock with nothing to open it with if the browser is lost.
+   * HALVES DO NOT EXIST BEFORE THE ORDER: the key's halves and the counterparty's open points are taken from the
+   * signed order. The key is shown BEFORE locking the funds.
+   * FUNDS ARE NOT LOCKED UNTIL onRecoveryKey ALLOWS IT: a lock without a saved key is a lock with nothing to open
+   * the swap with if the browser is lost.
    */
   start(request: StartRequest): Promise<SwapStart>;
   /**
@@ -1123,23 +1129,20 @@ export interface StartRequest {
   /**
    * The EVM wallet for LOCKING THE FUNDS: an adapter with `send` and `receipt` (the same role as WalletAdapter).
    * It comes from outside and is NOT substituted by default: without it the lock step answers with a code
-   * (`bad-input`), rather than going in blind. The recovery file has by now been confirmed by the person.
+   * (`bad-input`), rather than going in blind. The recovery key has by now been confirmed by the person.
    */
   readonly wallet?: WalletAdapter;
-  /**
-   * Hand the OLD per-swap recovery file to the interface and wait for the person's decision.
-   * `true` - the person confirmed the file is saved; `false` - the swap is not started.
-   * Not used when `recoveryKey` is present: that path has one key, saved once.
-   */
-  onRecoveryFile?(file: RecoveryFile): Promise<boolean>;
   /**
    * THE ONE RECOVERY KEY (sdk#76). A BIP39 mnemonic, or a key object from `@ninsei-labs/sdk/recovery`.
-   * When present, the swap's spend and view halves are derived from it instead of being generated, and no
-   * per-swap recovery file is written. The key is kept through the SDK's storage adapter.
+   * The swap's spend and view halves are derived from it; the per-swap recovery file path is gone, and the key is
+   * kept through the SDK's storage adapter.
    */
   recoveryKey?: string | { readonly mnemonic: string };
   /** The swap number, when the caller already reserved one. Absent - the SDK reserves the next free number. */
   recoveryIndex?: number;
+  /** The per-order salt the caller put into the signed quote. When present, the key uses the v2 salt binding and
+   * no index is reserved; it must equal `order.salt`. */
+  recoverySalt?: string | number | bigint;
   /** The first block for the on-chain number check. Absent - the chain registry's escrow deployment block, and
    * zero only when the registry has no height. */
   fromBlock?: string | number;
@@ -1272,6 +1275,7 @@ export interface SweepApi {
    */
   wallet(request: SweepWalletRequest): SweepWallet;
 
+  /**
    * COMPARE A DESTINATION WITH THE FILE'S PROMISE. `ok` is "usable address on the file's network", `matches` is
    * "the promised one" and is null when the file named nobody. Sending XMR elsewhere is a different payment, so the
    * comparison is not presentation.
@@ -1344,6 +1348,10 @@ export interface SweepRestoreRequest {
 export interface SweepRestoreResult {
   readonly total: string;
   readonly unlocked: string;
+  /** False when the wallet did not reach the node's height after its sync; a zero balance is then not evidence. */
+  readonly scanComplete: boolean;
+  /** `sync-failed`, `behind-node` or `no-heights` when `scanComplete` is false. */
+  readonly scanIncompleteReason?: string;
   /** The height the scan actually started from. */
   readonly scanHeight: number;
   readonly walletHeight: number | null;
@@ -1431,7 +1439,10 @@ export interface SweepFromOrderRequest {
     readonly edPointLocker: string;
     readonly edPointClaimer: string;
     readonly edViewPointLocker: string;
-    readonly index: number;
+    readonly index?: number | null;
+    readonly derivation?: "index-v1" | "salt-v2";
+    readonly factory?: string;
+    readonly salt?: string;
     readonly side: "locker" | "claimer";
     readonly startHeight?: number | null;
     readonly blockTime?: number | null;
@@ -1549,8 +1560,9 @@ export interface SweepSignResult {
   /** The free remainder at the moment of signing, in atomic units (string). */
   readonly amount: string;
   /**
-   * THE FEE OF THE SIGNED TRANSFER, in atomic units, or null when the wallet could not report one. A withdrawal
-   * moves the whole remainder, so the fee comes out of it - `receive` is what the recipient gets.
+   * THE FEE OF THE SIGNED TRANSFER, in atomic units, summed over every signed transaction, or null when any of
+   * them could not report one. A withdrawal moves the whole remainder, so the fee comes out of it - `receive` is
+   * what the recipient gets.
    */
   readonly fee: string | null;
   /** The remainder minus the fee. Null when the fee is unknown, or when a reported fee claims more than the remainder. */
@@ -1763,6 +1775,8 @@ export type ErrorCode =
   | "server-unavailable"
   /** The service answered and did not accept: the connection got through, the request did not (status and reason in params). */
   | "server-refused"
+  /** The funding transaction was sent, but no status-1 receipt with the expected OrderCreated proves the escrow. */
+  | "funding-pending"
   /** The wait for the XMR to arrive expired: a separate code, because this is a state of the money, not a breakdown. */
   | "xmr-timeout"
   /**