@ninsei-labs/sdk 0.52.0 → 0.54.0

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: {

package/src/version.mjs

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

package/src/xmr-arrival.mjs

@@ -7,11 +7,12 @@
 // decision moves into the client, which reads the chain itself with its own view key.
 //
 // TWO NODES OF DIFFERENT OPERATORS. A single node is a single truth that can lie. So `ready` opens only when at
-// least two nodes belonging to DIFFERENT operators see the transaction IN THE SAME BLOCK (the block hash matches)
-// with the required number of confirmations. A failed or lagging node does not count and blocks nothing; a synced
-// node that does not have the transaction in that block, or has a different block hash there, is a DISAGREEMENT -
-// the button stays closed and the screen says the nodes do not agree. When only one operator has confirmed, the
-// core names that state (`one-node`) instead of waiting silently.
+// least two nodes belonging to DIFFERENT operators see THE WHOLE OBSERVATION THE SAME WAY: the same transaction in
+// the same block, with the same output keys, the same decoded amounts (each backed by its Pedersen commitment) and
+// the same unlock state. A failed or lagging node does not count and blocks nothing; a synced node that does not
+// have the transaction, reports another block, or reports another amount is a DISAGREEMENT - the button stays closed
+// and the screen says the nodes do not agree. When only one operator has confirmed, the core names that state
+// (`one-node`) instead of waiting silently.
 //
 // WHERE THE RULE LIVES. "Locked by unlock_time is not an arrival" is ONE rule (issue #84). It is not copied here:
 // it lives under www/js/monero/unlock.js, is mirrored byte-for-byte into the engine (sdk/engine/monero/unlock.js,
@@ -108,8 +109,9 @@ async function getBlockTxs(node, hashes, fetchImpl, timeoutMs) {
   });
 }
 
-// The amount of our own outputs in a matched transaction (a swap can be paid in several outputs).
-const sumOutputs = (hit) => hit.outputs.reduce((n, o) => n + (o.amountAtomic || 0n), 0n);
+// The amount of our own outputs in a matched transaction (a swap can be paid in several outputs). An output whose
+// amount did not match its Pedersen commitment is NOT money: it contributes zero, and the caller names it.
+const sumOutputs = (hit) => hit.outputs.reduce((n, o) => n + (o.amountVerified ? (o.amountAtomic || 0n) : 0n), 0n);
 
 /**
  * FIND THE TRANSACTION, IF IT IS THERE. Blocks are walked from the swap's birth height upwards and the whole block
@@ -128,7 +130,10 @@ async function locate(node, { txid, address, viewSecret, spendPub, fromHeight, t
     for (const tx of txs) {
       if (txid && tx.tx_hash !== txid) continue;
       const hit = engine.xmrScan.matchTransaction(tx, [{ address, viewSecret, spendPub }], { height: h, nowSec });
-      if (hit.length && sumOutputs(hit[0]) > 0n) return { txid: tx.tx_hash, height: h };
+      // LOCATE FINDS AN OUTPUT, NOT AN AMOUNT. The amount can be forged or unbacked; the verification step below
+      // refuses it. Requiring a positive verified sum here made two nodes that agreed on a forged amount look like
+      // "no transaction at all".
+      if (hit.length) return { txid: tx.tx_hash, height: h };
     }
   }
   return null;
@@ -207,22 +212,51 @@ export async function verifyArrival(request) {
     try { body = (await getBlockTxs(node, block.txHashes, fetchImpl, timeoutMs)).find((t) => t.tx_hash === located.txid) || null; }
     catch { record.state = "down"; seen.push(record); continue; }
     if (!body) { record.state = "no-tx"; seen.push(record); continue; }
-    const hit = engine.xmrScan.matchTransaction(body, [watched], { height: located.height, nowSec });
+    // THE LOCK IS JUDGED AT THE WITNESS'S TIP, NOT AT THE BLOCK THAT MINED THE TRANSFER. `located.height` stays for
+    // confirmations; a height lock that has matured is no longer `xmr-locked`.
+    const hit = engine.xmrScan.matchTransaction(body, [watched], {
+      height: located.height,
+      tipHeight: Math.max(0, info.height - 1),
+      nowSec,
+    });
     if (!hit.length) { record.state = "no-output"; seen.push(record); continue; }
     record.state = "ok";
     record.amountAtomic = sumOutputs(hit[0]);
+    record.amountVerified = hit[0].outputs.every((o) => o.amountVerified === true);
+    record.outputs = hit[0].outputs.map((o) => ({
+      index: o.index,
+      key: String(o.key || "").replace(/^0x/, "").toLowerCase(),
+      amountAtomic: o.amountVerified ? String(o.amountAtomic ?? null) : null,
+      amountVerified: o.amountVerified === true,
+    }));
     record.unlock = hit[0].unlock;
     // Confirmations of a block: top - height + 1, and top = info.height - 1 (see above), so this is height - located.
     record.confirmations = Number.isFinite(Number(body.confirmations)) ? Number(body.confirmations) : (info.height - located.height);
+    // A NODE THAT CHANGED THE AMOUNT IS A DISAGREEMENT, NOT A WITNESS. The commitment check above is what
+    // makes this observable: without it an altered ecdhInfo.amount would still look like a valid output.
+    if (!record.amountVerified) { record.state = "amount-unverified"; seen.push(record); continue; }
+    // THE WHOLE OBSERVATION, NOT A BLOCK HASH. Two nodes must agree on the transaction id, the block, every
+    // output key and amount, and the unlock state. A block hash alone let one node change the amount and still
+    // form its own group; that is exactly the finding this closes.
+    record.observation = {
+      txid: located.txid,
+      blockHash: String(block.hash || "").replace(/^0x/, "").toLowerCase(),
+      outputs: record.outputs,
+      unlock: record.unlock ? {
+        locked: record.unlock.locked === true,
+        untilHeight: record.unlock.untilHeight ?? null,
+        untilTime: record.unlock.untilTime ?? null,
+      } : null,
+    };
     seen.push(record);
   }
 
-  // A DISAGREEMENT CLOSES THE BUTTON - it is named, and the nodes and hashes travel in the params.
-  const disagreeing = seen.filter((r) => r.state === "no-tx" || r.state === "no-output");
+  // A DISAGREEMENT CLOSES THE BUTTON - it is named, and the nodes and observations travel in the params.
+  const disagreeing = seen.filter((r) => r.state === "no-tx" || r.state === "no-output" || r.state === "amount-unverified");
   if (disagreeing.length) {
     throw new SdkError("xmr-nodes-disagree", {
       txid: located.txid, height: located.height,
-      nodes: disagreeing.map((r) => ({ url: r.url, operator: r.operator, blockHash: r.blockHash || null, why: r.state })),
+      nodes: disagreeing.map((r) => ({ url: r.url, operator: r.operator, blockHash: r.blockHash || null, why: r.state, outputs: r.outputs || null })),
       agreed: seen.filter((r) => r.state === "ok").map((r) => ({ url: r.url, operator: r.operator, blockHash: r.blockHash })),
     });
   }
@@ -230,43 +264,53 @@ export async function verifyArrival(request) {
   const okay = seen.filter((r) => r.state === "ok");
   if (!okay.length) return { seen: false, state: "pending", txid: located.txid, height: located.height, checked: seen };
 
+  // THE OBSERVATIONS MUST BE IDENTICAL. Grouping by the whole observation (not just the block hash) means a
+  // node that reports a different amount, output key or unlock state does not count as agreeing with anyone.
+  const byObservation = new Map();
+  for (const r of okay) {
+    const key = JSON.stringify(r.observation);
+    if (!byObservation.has(key)) byObservation.set(key, { observation: r.observation, operators: new Set(), nodes: [] });
+    const g = byObservation.get(key);
+    g.operators.add(r.operator);
+    g.nodes.push(r);
+  }
+  if (byObservation.size > 1) {
+    throw new SdkError("xmr-nodes-disagree", {
+      txid: located.txid, height: located.height,
+      nodes: okay.map((r) => ({ url: r.url, operator: r.operator, blockHash: r.blockHash || null, outputs: r.outputs, why: "observation" })),
+      agreed: [],
+    });
+  }
+  const best = [...byObservation.values()][0];
+  // A node that is further along is not a liar: the minimum is the figure every witness can support. What
+  // matters is that the transaction itself is identical; confirmations only decide when the button opens.
+  const confirmations = Math.min(...best.nodes.map((r) => r.confirmations));
+  const amountAtomic = best.nodes[0].amountAtomic;
+  const agreedBy = best.nodes.map((r) => ({ url: r.url, operator: r.operator, blockHash: r.blockHash, confirmations: r.confirmations }));
+
   // LOCKED IS NOT AN ARRIVAL, and the rule for that is the shared one (issue #84), mirrored from www/js.
-  const locked = okay.find((r) => r.unlock && r.unlock.locked);
+  const locked = best.nodes.find((r) => r.unlock && r.unlock.locked);
   if (locked) {
     const until = locked.unlock;
     throw new SdkError("xmr-locked", { txid: located.txid, height: located.height, address: request.address,
       untilHeight: until.untilHeight ?? null, untilTime: until.untilTime ?? null });
   }
 
-  // THE AMOUNT IS NOT LESS THAN EXPECTED. A shortfall is named rather than shown as a completed swap.
-  const amountAtomic = okay.reduce((best, r) => (r.amountAtomic > best ? r.amountAtomic : best), 0n);
+  // THE AMOUNT IS NOT LESS THAN EXPECTED. A shortfall is named rather than shown as a completed swap. The figure
+  // comes from the agreed observation, never from the largest answer of one node: that maximum was the defect.
   if (amountAtomic < expectedAtomic) {
     throw new SdkError("xmr-underpaid", { txid: located.txid, height: located.height, got: amountAtomic.toString(), want: expectedAtomic.toString() });
   }
 
-  // AGREEMENT: the same block hash, held by at least two DIFFERENT operators, with the required confirmations.
-  const byHash = new Map();
-  for (const r of okay) {
-    const key = r.blockHash;
-    if (!byHash.has(key)) byHash.set(key, { blockHash: key, operators: new Set(), nodes: [] });
-    const g = byHash.get(key);
-    g.operators.add(r.operator);
-    g.nodes.push(r);
-  }
-  let best = null;
-  for (const g of byHash.values()) if (!best || g.operators.size > best.operators.size) best = g;
-  const confirmations = Math.min(...best.nodes.map((r) => r.confirmations));
-  const agreedBy = best.nodes.map((r) => ({ url: r.url, operator: r.operator, blockHash: r.blockHash, confirmations: r.confirmations }));
-
   if (best.operators.size < 2) {
-    return { seen: false, state: "one-node", txid: located.txid, height: located.height, blockHash: best.blockHash,
+    return { seen: false, state: "one-node", txid: located.txid, height: located.height, blockHash: best.observation.blockHash,
       amountAtomic: amountAtomic.toString(), confirmations, operators: [...best.operators], agreedBy, checked: seen };
   }
   if (confirmations < minConfirmations) {
-    return { seen: false, state: "pending", why: "confirmations", txid: located.txid, height: located.height, blockHash: best.blockHash,
+    return { seen: false, state: "pending", why: "confirmations", txid: located.txid, height: located.height, blockHash: best.observation.blockHash,
       amountAtomic: amountAtomic.toString(), confirmations, needConfirmations: minConfirmations, agreedBy, checked: seen };
   }
-  return { seen: true, state: "arrived", txid: located.txid, height: located.height, blockHash: best.blockHash,
+  return { seen: true, state: "arrived", txid: located.txid, height: located.height, blockHash: best.observation.blockHash,
     amountAtomic: amountAtomic.toString(), confirmations, needConfirmations: minConfirmations,
     operators: [...best.operators], agreedBy, checked: seen };
 }