@ninsei-labs/sdk 0.52.0 → 0.54.0

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" } : {}),
+  };
 }