@ninsei-labs/sdk 0.58.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/sweep.mjs CHANGED
@@ -175,7 +175,7 @@ const feeOf = async (wallet, signed) => {
175
175
  return /^\d+$/.test(text) ? text : null;
176
176
  };
177
177
 
178
- export function createSweep({ call = null }) {
178
+ export function createSweep({ call = null, fetchImpl = null } = {}) {
179
179
  // THE NAME IS NEEDED BY THE OBJECT ITSELF: `run` calls `api.plan(...)` - the step order is held by the plan and
180
180
  // the withdrawal living in one object, not in two copies. During a manual merge of branches the object was left
181
181
  // unnamed, and the withdrawal failed with "api is not defined": not a refusal, but a breakdown. `node --check`
@@ -336,7 +336,14 @@ export function createSweep({ call = null }) {
336
336
  // spendable - re-check the spent status once. The wallet is the same withdrawal adapter `sign` takes; the page
337
337
  // no longer decides when a second pass is needed.
338
338
  async restore(request) {
339
- return await restoreWallet(request || {});
339
+ const merged = { ...(request || {}) };
340
+ if (merged.fetchImpl !== undefined && merged.fetchImpl !== null && typeof merged.fetchImpl !== "function") {
341
+ throw new SdkError("bad-input", { field: "fetchImpl" });
342
+ }
343
+ // THE INSTANCE TRANSPORT REACHES THE WINDOW AND KEY-IMAGE READS TOO. A per-call `fetchImpl` still wins;
344
+ // without this fallback a Tor/proxy caller's restore would silently use the page's global fetch.
345
+ if (typeof merged.fetchImpl !== "function" && typeof fetchImpl === "function") merged.fetchImpl = fetchImpl;
346
+ return await restoreWallet(merged);
340
347
  },
341
348
 
342
349
  // THE WITHDRAWAL ITSELF. The wallet arrives as an adapter (the WASM and the worker live with whoever builds the
package/src/version.mjs CHANGED
@@ -6,4 +6,4 @@
6
6
  // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
7
7
  // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
8
8
 
9
- export const SDK_VERSION = "0.58.0";
9
+ export const SDK_VERSION = "0.60.0";
@@ -0,0 +1,84 @@
1
+ // THE WITNESS-V1 SLICE ANSWER. The parser lives apart from the arrival check so the wire format can be tested
2
+ // against a real witness service without importing the wallet engine.
3
+ import { SdkError } from "./errors.mjs";
4
+
5
+ export const WITNESS_SLICE_BLOCKS = 20;
6
+
7
+ export function witnessSliceIndex(height) {
8
+ const value = Number(height);
9
+ if (!Number.isSafeInteger(value) || value < 0) throw new SdkError("bad-input", { field: "height" });
10
+ return Math.floor(value / WITNESS_SLICE_BLOCKS);
11
+ }
12
+
13
+ export function witnessSliceStart(index) {
14
+ const value = Number(index);
15
+ if (!Number.isSafeInteger(value) || value < 0) throw new SdkError("bad-input", { field: "slice" });
16
+ return value * WITNESS_SLICE_BLOCKS;
17
+ }
18
+
19
+ export function witnessSliceEnd(index) {
20
+ return witnessSliceStart(index) + WITNESS_SLICE_BLOCKS - 1;
21
+ }
22
+
23
+ const witnessHash = (value) => {
24
+ const text = String(value || "").replace(/^0x/, "").toLowerCase();
25
+ return /^[0-9a-f]{64}$/.test(text) ? text : null;
26
+ };
27
+
28
+ /**
29
+ * A full slice below the tip has `grid` blocks. The tip slice ends at the top block, sets `complete: false`, and
30
+ * names that block in `tip`. A partial answer is accepted when its last block is at or above the top the caller
31
+ * read: a newer tip is a block that arrived during the walk, while a tip below it shows a witness that is behind.
32
+ */
33
+ export function parseWitnessSliceBody(body, { network, index, tipHeight = null }) {
34
+ if (!body || typeof body !== "object") throw new SdkError("xmr-no-nodes", { why: "bad-witness-slice" });
35
+ if (Number(body.version) !== 1) throw new SdkError("xmr-no-nodes", { why: "bad-witness-version" });
36
+ if (String(body.network) !== String(network)) throw new SdkError("xmr-no-nodes", { why: "witness-network" });
37
+ if (Number(body.grid) !== WITNESS_SLICE_BLOCKS) throw new SdkError("xmr-no-nodes", { why: "witness-grid" });
38
+ if (Number(body.slice) !== index) throw new SdkError("xmr-no-nodes", { why: "witness-slice" });
39
+ const start = witnessSliceStart(index);
40
+ const sliceEnd = witnessSliceEnd(index);
41
+ const to = Number(body.to);
42
+ if (Number(body.from) !== start || !Number.isSafeInteger(to) || to < start || to > sliceEnd) {
43
+ throw new SdkError("xmr-no-nodes", { why: "witness-bounds" });
44
+ }
45
+ if (typeof body.complete !== "boolean" || body.complete !== (to === sliceEnd)) {
46
+ throw new SdkError("xmr-no-nodes", { why: "witness-complete" });
47
+ }
48
+ const count = to - start + 1;
49
+ if (!Array.isArray(body.blocks) || body.blocks.length !== count) {
50
+ throw new SdkError("xmr-no-nodes", { why: "witness-block-count" });
51
+ }
52
+ const blocks = body.blocks.map((block, i) => {
53
+ if (!block || Number(block.height) !== start + i) {
54
+ throw new SdkError("xmr-no-nodes", { why: "witness-height" });
55
+ }
56
+ const hash = witnessHash(block.hash);
57
+ if (!hash) throw new SdkError("xmr-no-nodes", { why: "witness-hash" });
58
+ if (!Array.isArray(block.txids)) throw new SdkError("xmr-no-nodes", { why: "witness-txids" });
59
+ const txids = block.txids.map((txid) => {
60
+ const value = witnessHash(txid);
61
+ if (!value) throw new SdkError("xmr-no-nodes", { why: "witness-txid" });
62
+ return value;
63
+ });
64
+ return { height: Number(block.height), hash, txids };
65
+ });
66
+ let tip = null;
67
+ if (body.complete) {
68
+ if (body.tip !== null && body.tip !== undefined) throw new SdkError("xmr-no-nodes", { why: "witness-tip" });
69
+ } else {
70
+ const value = body.tip;
71
+ if (!value || typeof value !== "object" || Number(value.height) !== to || !witnessHash(value.hash)
72
+ || String(value.hash).toLowerCase() !== blocks[count - 1].hash) {
73
+ throw new SdkError("xmr-no-nodes", { why: "witness-tip" });
74
+ }
75
+ // A TIP AT OR ABOVE THE TOP IS A BLOCK THAT ARRIVED DURING THE WALK. A tip below it is a witness that is
76
+ // behind the chain the caller already read, and that cannot be evidence of absence.
77
+ if (tipHeight !== null && Number(value.height) < Number(tipHeight)) {
78
+ throw new SdkError("xmr-no-nodes", { why: "witness-tip-height" });
79
+ }
80
+ tip = { height: Number(value.height), hash: witnessHash(value.hash) };
81
+ }
82
+ return { version: 1, network: String(network), grid: WITNESS_SLICE_BLOCKS, slice: index,
83
+ from: start, to, complete: body.complete, blocks, tip };
84
+ }
@@ -28,6 +28,9 @@
28
28
  // client scans blocks from the swap's birth height (a few dozen blocks).
29
29
  import { SdkError } from "./errors.mjs";
30
30
  import * as engine from "./engine.mjs";
31
+ import {
32
+ WITNESS_SLICE_BLOCKS, parseWitnessSliceBody, witnessSliceEnd, witnessSliceIndex, witnessSliceStart,
33
+ } from "./witness-slice.mjs";
31
34
 
32
35
  const isStr = (v) => typeof v === "string" && v.length > 0;
33
36
  const intOf = (v) => { const n = Number(v); return Number.isFinite(n) ? Math.trunc(n) : null; };
@@ -118,7 +121,9 @@ async function getInfo(node, fetchImpl, timeoutMs) {
118
121
  if (r.busy === true || r.busy_syncing === true || (typeof r.status === "string" && r.status && r.status !== "OK")) {
119
122
  throw new SdkError("xmr-no-nodes", { node: node.url, why: "busy" });
120
123
  }
121
- return { height: Number(r.height), synced: r.synchronized !== false, nettype: r.nettype || null };
124
+ // A MISSING `synchronized` FIELD IS NOT A SYNCHRONIZED NODE. Only an explicit true lets an empty walk count as
125
+ // evidence of absence.
126
+ return { height: Number(r.height), synced: r.synchronized === true, nettype: r.nettype || null };
122
127
  }
123
128
 
124
129
  // THE WHOLE BLOCK: its hash and ALL of its transaction hashes. This is the only form a public node is asked in.
@@ -230,27 +235,18 @@ export async function verifyArrival(request) {
230
235
  const nowSec = Number.isFinite(Number(request.nowSec)) ? Number(request.nowSec) : Math.floor(Date.now() / 1000);
231
236
  const timeoutMs = Number.isFinite(Number(request.timeoutMs)) && Number(request.timeoutMs) > 0 ? Number(request.timeoutMs) : 20000;
232
237
  const txidHint = txidOf(request.txid);
233
- // THE KEY MUST BELONG TO THE ADDRESS, NOT MERELY BE PASSED BESIDE IT. The scanner used to try both byte orders
234
- // of the view secret and accept the first match; a maker could pay to the address built from the other reading and
235
- // still get `arrived` while the person's wallet saw nothing. Decode the address, keep the matching view form, and
236
- // require its spend key to be the same key.
237
- let addressKeys;
238
- try { addressKeys = engine.xmrArrivalRead.decodeAddressKeys(request.address); }
239
- catch { throw new SdkError("bad-input", { field: "address", why: "not-a-monero-address" }); }
240
- // THE WATCHED ADDRESS IS A PRIMARY ADDRESS. A subaddress has a different payload layout and its view/spend points
241
- // are not the ones the joint-address builder produces; refusing it by name is clearer than a spurious spend-pub
242
- // mismatch. SDK-generated addresses are always primary.
243
- if (!addressKeys.network) throw new SdkError("bad-input", { field: "address", why: "subaddress-not-supported" });
244
- const spendPub = String(request.spendPub).replace(/^0x/, "").toLowerCase();
245
- if (!addressKeys.spendPub || spendPub !== String(addressKeys.spendPub).toLowerCase()) {
246
- throw new SdkError("xmr-address-mismatch", { field: "spendPub", address: request.address });
247
- }
248
- const viewForm = engine.xmrScan.viewKeyFormForAddress(request.viewSecret, addressKeys.viewPub);
249
- if (!viewForm) {
250
- throw new SdkError("xmr-address-mismatch", { field: "viewSecret", address: request.address });
251
- }
252
- const viewSecret = engine.xmrScan.viewSecretCandidates(request.viewSecret).find(([form]) => form === viewForm)?.[1] ?? request.viewSecret;
253
- const watched = { address: request.address, viewSecret, spendPub: addressKeys.spendPub };
238
+ // THE KEY MUST BELONG TO THE ADDRESS, AND THE RULE LIVES IN THE ENGINE. Both facade paths call the same binding;
239
+ // a public `scanRange` cannot accept the other byte-order reading while the facade refuses it.
240
+ const bound = engine.xmrScan.watchedAddressVerdict({
241
+ address: request.address, viewSecret: request.viewSecret, spendPub: request.spendPub,
242
+ });
243
+ if (!bound.ok) {
244
+ if (bound.code === "bad-input") throw new SdkError("bad-input", { field: bound.field || "address", why: bound.why });
245
+ throw new SdkError(bound.code, { field: bound.field || "address", address: request.address });
246
+ }
247
+ const viewSecret = bound.viewSecret;
248
+ const spendPub = bound.spendPub;
249
+ const watched = { address: request.address, viewSecret, spendPub };
254
250
 
255
251
  // 1. THE TIP, and with it the first proof that ANY node answers. All nodes down is a named refusal, not silence.
256
252
  const live = [];
@@ -271,12 +267,14 @@ export async function verifyArrival(request) {
271
267
  // 2. LOCATE: from the birth height, by whole blocks. The first reachable node does the walk.
272
268
  let located = null;
273
269
  const completedOperators = new Set();
270
+ const staleWitnesses = [];
274
271
  for (const { node, info } of live) {
275
272
  // A WITNESS THAT IS NOT SYNCHRONIZED HAS NOT SEEN THE RANGE. Counting its empty walk as absence would let two
276
273
  // nodes that restarted behind the payout height refund a paid swap; the same rule already guards the positive
277
- // branch below.
274
+ // branch below. The stale entry is reported only when it is evidence about absence; an arrived verdict has a
275
+ // synced witness and must not carry a stale one as a failure.
278
276
  if (!info.synced) {
279
- failed.push({ url: node.url, operator: node.operator, code: "stale", why: "not-synchronized" });
277
+ staleWitnesses.push({ url: node.url, operator: node.operator, code: "stale", why: "not-synchronized" });
280
278
  continue;
281
279
  }
282
280
  try {
@@ -289,6 +287,7 @@ export async function verifyArrival(request) {
289
287
  if (located) break;
290
288
  }
291
289
  if (!located) {
290
+ failed.push(...staleWitnesses);
292
291
  // ABSENCE IS A CLAIM ABOUT MONEY, SO IT NEEDS TWO OPERATORS. One node can withhold a transaction and make
293
292
  // this walk look empty; a refund signed on that answer would take the depositor's ETH from a maker who paid.
294
293
  // Only when no node finished the walk is every node unreachable.
@@ -301,7 +300,7 @@ export async function verifyArrival(request) {
301
300
  }
302
301
  throw new SdkError("xmr-no-nodes", { tried: nodes.map((n) => n.url), nodes: failed });
303
302
  }
304
- return { seen: false, state: "pending", absent: completedOperators.size >= 2, txid: txidHint, tip, completedOperators: [...completedOperators], checked: live.map((l) => ({ url: l.node.url, operator: l.node.operator, height: l.info.height })), failed };
303
+ return { seen: false, state: "pending", absent: completedOperators.size >= 2, txid: txidHint, tip, completedOperators: [...completedOperators], checked: live.map((l) => ({ url: l.node.url, operator: l.node.operator, height: l.info.height, synchronized: l.info.synced })), failed };
305
304
  }
306
305
 
307
306
  // 3. VERIFY ON EVERY NODE: the SAME block hash, the SAME transaction inside it, the confirmations and the money.
@@ -438,64 +437,13 @@ export async function verifyArrival(request) {
438
437
  // `verifyArrival`: the production decision still uses the exact walk until an independent operator serves
439
438
  // witness-v1. `verifyArrivalShadow` runs both and compares them without changing ready, refund or any swap state.
440
439
 
441
- export const WITNESS_SLICE_BLOCKS = 20;
442
-
443
- export function witnessSliceIndex(height) {
444
- const value = Number(height);
445
- if (!Number.isSafeInteger(value) || value < 0) throw new SdkError("bad-input", { field: "height" });
446
- return Math.floor(value / WITNESS_SLICE_BLOCKS);
447
- }
448
-
449
- export function witnessSliceStart(index) {
450
- const value = Number(index);
451
- if (!Number.isSafeInteger(value) || value < 0) throw new SdkError("bad-input", { field: "slice" });
452
- return value * WITNESS_SLICE_BLOCKS;
453
- }
454
-
455
- export function witnessSliceEnd(index) {
456
- return witnessSliceStart(index) + WITNESS_SLICE_BLOCKS - 1;
457
- }
458
-
459
- const witnessHash = (value) => {
460
- const text = String(value || "").replace(/^0x/, "").toLowerCase();
461
- return /^[0-9a-f]{64}$/.test(text) ? text : null;
462
- };
463
-
464
- function assertWitnessSliceBody(body, { network, index }) {
465
- if (!body || typeof body !== "object") throw new SdkError("xmr-no-nodes", { why: "bad-witness-slice" });
466
- if (Number(body.version) !== 1) throw new SdkError("xmr-no-nodes", { why: "bad-witness-version" });
467
- if (String(body.network) !== String(network)) throw new SdkError("xmr-no-nodes", { why: "witness-network" });
468
- if (Number(body.grid) !== WITNESS_SLICE_BLOCKS) throw new SdkError("xmr-no-nodes", { why: "witness-grid" });
469
- if (Number(body.slice) !== index) throw new SdkError("xmr-no-nodes", { why: "witness-slice" });
470
- if (Number(body.from) !== witnessSliceStart(index) || Number(body.to) !== witnessSliceEnd(index)) {
471
- throw new SdkError("xmr-no-nodes", { why: "witness-bounds" });
472
- }
473
- if (!Array.isArray(body.blocks) || body.blocks.length !== WITNESS_SLICE_BLOCKS) {
474
- throw new SdkError("xmr-no-nodes", { why: "witness-block-count" });
475
- }
476
- const blocks = body.blocks.map((block, i) => {
477
- if (!block || Number(block.height) !== witnessSliceStart(index) + i) {
478
- throw new SdkError("xmr-no-nodes", { why: "witness-height" });
479
- }
480
- const hash = witnessHash(block.hash);
481
- if (!hash) throw new SdkError("xmr-no-nodes", { why: "witness-hash" });
482
- if (!Array.isArray(block.txids)) throw new SdkError("xmr-no-nodes", { why: "witness-txids" });
483
- const txids = block.txids.map((txid) => {
484
- const value = witnessHash(txid);
485
- if (!value) throw new SdkError("xmr-no-nodes", { why: "witness-txid" });
486
- return value;
487
- });
488
- return { height: Number(block.height), hash, txids };
489
- });
490
- return { version: 1, network: String(network), grid: WITNESS_SLICE_BLOCKS, slice: index,
491
- from: body.from, to: body.to, blocks };
492
- }
440
+ export { WITNESS_SLICE_BLOCKS, witnessSliceEnd, witnessSliceIndex, witnessSliceStart, parseWitnessSliceBody };
493
441
 
494
- async function readWitnessSlice(node, index, { network, fetchImpl, timeoutMs }) {
442
+ async function readWitnessSlice(node, index, { network, fetchImpl, timeoutMs, tipHeight = null }) {
495
443
  if (node.protocol !== "witness-v1") throw new SdkError("xmr-no-nodes", { node: node.url, why: "no-slice-witness" });
496
444
  const body = await call(node, "/v1/witness/slice",
497
445
  { version: 1, network, grid: WITNESS_SLICE_BLOCKS, slice: index }, fetchImpl, timeoutMs);
498
- return assertWitnessSliceBody(body, { network, index });
446
+ return parseWitnessSliceBody(body, { network, index, tipHeight });
499
447
  }
500
448
 
501
449
  // ALL THE TRANSACTIONS OF A SLICE, IN ONE REQUEST. The request names the whole slice's txids, not the one
@@ -508,16 +456,65 @@ async function readSliceTransactions(node, slice, { fetchImpl, timeoutMs }) {
508
456
  return new Map(txs.map((tx) => [String(tx.tx_hash || "").toLowerCase(), tx]));
509
457
  }
510
458
 
459
+ // THE TOP THE WALK MUST REACH. A witness may be behind the exact nodes, and a walk that stops at the witness's
460
+ // own top must not count as a completed walk: the blocks above it were never read by any source that claimed
461
+ // absence. The exact `verifyArrival` reports its tip on the absence path and the checked heights on the arrived
462
+ // path; both are the highest top the exact sources actually read.
463
+ function exactTopOf(exact) {
464
+ if (!exact || typeof exact !== "object") return null;
465
+ // THE HEIGHTS THAT BELONG TO A SYNCED EXACT NODE. A stale node can report a height far above the chain it has
466
+ // actually read; using its number as the target would keep every honest witness below it. Prefer the checked
467
+ // heights when they exist, and fall back to the tip only for an answer that carries no checked entries.
468
+ const heights = Array.isArray(exact.checked)
469
+ ? exact.checked
470
+ .filter((entry) => entry && entry.synchronized !== false && entry.state !== "stale" && entry.state !== "down")
471
+ .map((entry) => intOf(entry.height))
472
+ .filter((height) => height !== null && height > 0)
473
+ : [];
474
+ if (Array.isArray(exact.checked) && exact.checked.length) {
475
+ return heights.length ? Math.max(0, Math.max(...heights) - 1) : null;
476
+ }
477
+ const tip = intOf(exact.tip);
478
+ if (tip !== null && tip > 0) return Math.max(0, tip - 1);
479
+ return null;
480
+ }
481
+
511
482
  // FIND A PAYMENT THROUGH SLICES. The exact `fromHeight` is local: the witness sees only slice indexes.
512
- async function locateInSlices(node, { expectedAtomic, address, viewSecret, spendPub, fromHeight, toHeight, nowSec, network, fetchImpl, timeoutMs }) {
483
+ async function locateInSlices(node, { expectedAtomic, address, viewSecret, spendPub, fromHeight, toHeight, targetTop = toHeight, nowSec, network, fetchImpl, timeoutMs }) {
484
+ const target = intOf(targetTop);
485
+ if (target === null) throw new SdkError("bad-input", { field: "targetTop" });
486
+ // A WITNESS BEHIND THE FIRST BLOCK HAS NOT READ THE RANGE. The slice walk below would otherwise mark its last
487
+ // slice complete and let a lagging witness vouch for a payment it never saw.
488
+ if (target < fromHeight || toHeight < fromHeight) return { located: null, completed: false };
513
489
  const first = witnessSliceIndex(fromHeight);
514
- const last = witnessSliceIndex(toHeight);
490
+ const last = witnessSliceIndex(Math.min(toHeight, target));
515
491
  let best = null;
516
- let completed = true;
492
+ let completed = false;
493
+ let servedTop = null;
494
+ let failure = null;
517
495
  for (let index = first; index <= last; index++) {
518
- const slice = await readWitnessSlice(node, index, { network, fetchImpl, timeoutMs });
519
- const txs = await readSliceTransactions(node, slice, { fetchImpl, timeoutMs });
496
+ let slice;
497
+ let txs;
498
+ try {
499
+ // The witness reads its tip at slice time, so a block can arrive between the tip read and this request. The
500
+ // parser accepts a newer tip and rejects one below the top the walk started from.
501
+ slice = await readWitnessSlice(node, index, { network, fetchImpl, timeoutMs, tipHeight: toHeight });
502
+ txs = await readSliceTransactions(node, slice, { fetchImpl, timeoutMs });
503
+ } catch (error) {
504
+ // A CANDIDATE FOUND BEFORE THE FAILURE IS STILL A CANDIDATE. The slice walk is evidence, and a later
505
+ // refused slice does not erase the transaction already read from an earlier one. The caller records the
506
+ // failure beside the located candidate; an absence still requires the whole walk.
507
+ failure = error;
508
+ break;
509
+ }
510
+ // THE HIGHEST BLOCK THE WITNESS ACTUALLY SERVED. A newer tip can arrive inside the last slice; the caller
511
+ // uses this to raise the common target, so a walk that stopped at 115 cannot complete a target of 116.
512
+ servedTop = servedTop === null ? slice.to : Math.max(servedTop, slice.to);
520
513
  for (const block of slice.blocks) {
514
+ // THE SLICE IS A FIXED WINDOW; THE SWAP STARTS AT `fromHeight`. Blocks before the birth height may contain
515
+ // an earlier transfer to the same address, and counting them would make the slice walk disagree with the
516
+ // exact walk that starts at the birth height.
517
+ if (block.height < fromHeight) continue;
521
518
  for (const txid of block.txids) {
522
519
  const tx = txs.get(txid);
523
520
  if (!tx) continue;
@@ -529,19 +526,21 @@ async function locateInSlices(node, { expectedAtomic, address, viewSecret, spend
529
526
  const amountVerified = hit[0].outputs.every((o) => o.amountVerified === true);
530
527
  const locked = hit[0].unlock && hit[0].unlock.locked === true;
531
528
  const score = (amountAtomic >= expectedAtomic ? 4 : 0) + (amountVerified ? 2 : 0) + (locked ? 0 : 1);
532
- const candidate = { txid, height: block.height, blockHash: block.hash, amountAtomic, score };
529
+ const candidate = { txid, height: block.height, blockHash: block.hash, amountAtomic, locked, score };
533
530
  if (!best || score > best.score || (score === best.score && amountAtomic > best.amountAtomic)) best = candidate;
534
531
  }
535
532
  }
536
533
  // THE WHOLE SLICE WAS READ. A perfect candidate lets the walk stop after this slice, not after a block:
537
- // the last witness request is still a fixed slice, never the payout height. `completed` means the full
538
- // requested slice range was walked, so it stays false on an early stop.
534
+ // the last witness request is still a fixed slice, never the payout height. Completion is judged by the
535
+ // LAST BLOCK the witness actually served, not by the slice index: a witness can stop inside the same
536
+ // 20-block window as the target and still be behind it.
539
537
  if (best && best.score === 7) {
540
- completed = index === last;
538
+ completed = slice.to >= target;
541
539
  break;
542
540
  }
541
+ if (index === last) completed = slice.to >= target;
543
542
  }
544
- return { located: best, completed };
543
+ return { located: best, completed, servedTop, failure };
545
544
  }
546
545
 
547
546
  /**
@@ -562,11 +561,20 @@ export async function verifyArrivalShadow(request) {
562
561
  if (!witnessNodes.some((node) => node.protocol === "witness-v1")) {
563
562
  throw new SdkError("bad-input", { field: "witnessNodes", why: "no-witness-v1" });
564
563
  }
565
- let addressKeys;
566
- try { addressKeys = engine.xmrArrivalRead.decodeAddressKeys(request.address); }
567
- catch { throw new SdkError("bad-input", { field: "address", why: "not-a-monero-address" }); }
568
- if (!addressKeys.network) throw new SdkError("bad-input", { field: "address", why: "subaddress-not-supported" });
569
- const network = request.network || addressKeys.network;
564
+ // THE SAME ENGINE BINDING AS `verifyArrival`. The shadow path does not carry a second copy of the view/spend rule.
565
+ if (!isStr(request.address)) throw new SdkError("bad-input", { field: "address" });
566
+ if (!isStr(request.spendPub)) throw new SdkError("bad-input", { field: "spendPub" });
567
+ if (request.viewSecret === undefined || request.viewSecret === null) throw new SdkError("bad-input", { field: "viewSecret" });
568
+ const bound = engine.xmrScan.watchedAddressVerdict({
569
+ address: request.address, viewSecret: request.viewSecret, spendPub: request.spendPub,
570
+ });
571
+ if (!bound.ok) {
572
+ if (bound.code === "bad-input") throw new SdkError("bad-input", { field: bound.field || "address", why: bound.why });
573
+ throw new SdkError(bound.code, { field: bound.field || "address", address: request.address });
574
+ }
575
+ const network = request.network || bound.keys.network;
576
+ const viewSecret = bound.viewSecret;
577
+ const spendPub = bound.spendPub;
570
578
  const fetchImpl = typeof request.fetch === "function" ? request.fetch : globalThis.fetch;
571
579
  if (typeof fetchImpl !== "function") throw new SdkError("bad-input", { field: "fetch" });
572
580
  const timeoutMs = Number.isFinite(Number(request.timeoutMs)) && Number(request.timeoutMs) > 0 ? Number(request.timeoutMs) : 20000;
@@ -576,15 +584,6 @@ export async function verifyArrivalShadow(request) {
576
584
  let expectedAtomic;
577
585
  try { expectedAtomic = BigInt(request.expectedAtomic); } catch { throw new SdkError("bad-input", { field: "expectedAtomic" }); }
578
586
  if (expectedAtomic <= 0n) throw new SdkError("bad-input", { field: "expectedAtomic" });
579
- if (!isStr(request.spendPub)) throw new SdkError("bad-input", { field: "spendPub" });
580
- if (request.viewSecret === undefined || request.viewSecret === null) throw new SdkError("bad-input", { field: "viewSecret" });
581
- const spendPub = String(request.spendPub).replace(/^0x/, "").toLowerCase();
582
- if (spendPub !== String(addressKeys.spendPub).toLowerCase()) {
583
- throw new SdkError("xmr-address-mismatch", { field: "spendPub", address: request.address });
584
- }
585
- const viewForm = engine.xmrScan.viewKeyFormForAddress(request.viewSecret, addressKeys.viewPub);
586
- if (!viewForm) throw new SdkError("xmr-address-mismatch", { field: "viewSecret", address: request.address });
587
- const viewSecret = engine.xmrScan.viewSecretCandidates(request.viewSecret).find(([form]) => form === viewForm)?.[1] ?? request.viewSecret;
588
587
 
589
588
  let exact = null;
590
589
  let exactError = null;
@@ -593,60 +592,184 @@ export async function verifyArrivalShadow(request) {
593
592
 
594
593
  const checked = [];
595
594
  const failed = [];
596
- let located = null;
597
- let completed = false;
595
+ const staleWitnesses = [];
596
+ const readable = [];
597
+ const observations = [];
598
+ // THE WALK MUST REACH THE HIGHEST TOP ANY SOURCE READ. A witness that is behind the exact nodes OR behind another
599
+ // witness cannot prove absence in the blocks it has not seen; its own `toHeight` is therefore not the completion
600
+ // target. Collect every top first, then walk against the common target.
601
+ const exactTop = exactTopOf(exact);
602
+ let highestTop = exactTop;
598
603
  for (const node of witnessNodes) {
599
604
  if (node.protocol !== "witness-v1") { failed.push({ url: node.url, operator: node.operator, code: "no-slice-witness" }); continue; }
600
605
  let info;
601
606
  try { info = await getInfo(node, fetchImpl, timeoutMs); }
602
607
  catch (error) { failed.push(failureOf(error, node)); checked.push({ url: node.url, operator: node.operator, state: "down" }); continue; }
603
608
  if (!info.synced) {
604
- failed.push({ url: node.url, operator: node.operator, code: "stale", why: "not-synchronized" });
609
+ staleWitnesses.push({ url: node.url, operator: node.operator, code: "stale", why: "not-synchronized" });
605
610
  checked.push({ url: node.url, operator: node.operator, state: "stale", height: info.height });
606
611
  continue;
607
612
  }
608
613
  const top = Math.max(0, info.height - 1);
609
- checked.push({ url: node.url, operator: node.operator, state: "ok", height: info.height });
614
+ const entry = { url: node.url, operator: node.operator, state: "ok", height: info.height };
615
+ checked.push(entry);
616
+ highestTop = highestTop === null ? top : Math.max(highestTop, top);
617
+ readable.push({ node, top, entry });
618
+ }
619
+ const walkResults = [];
620
+ for (const { node, top, entry } of readable) {
621
+ const targetTop = highestTop === null ? top : Math.max(top, highestTop);
610
622
  try {
611
623
  const found = await locateInSlices(node, {
612
624
  expectedAtomic, address: request.address, viewSecret, spendPub, fromHeight, toHeight: top,
625
+ targetTop,
613
626
  nowSec, network, fetchImpl, timeoutMs,
614
627
  });
615
- completed = completed || found.completed;
616
- if (found.located && (!located || found.located.score > located.score)) {
628
+ walkResults.push({ node, top, entry, found });
629
+ } catch (error) {
630
+ entry.state = "error";
631
+ failed.push(failureOf(error, node));
632
+ }
633
+ }
634
+
635
+ // THE TARGET CAN MOVE DURING THE WALK. A witness may serve a tip newer than every `get_info` top, and the
636
+ // parser accepts it; the earlier target would let the other witnesses complete against a block they never read.
637
+ // Raise the target to the highest served tip and judge completion again, after every walk.
638
+ for (const { found } of walkResults) {
639
+ if (found.servedTop === null || found.servedTop === undefined) continue;
640
+ highestTop = highestTop === null ? found.servedTop : Math.max(highestTop, found.servedTop);
641
+ }
642
+
643
+ let located = null;
644
+ let completed = false;
645
+ const completedWitnessOperators = new Set();
646
+ for (const { node, entry, found } of walkResults) {
647
+ const finalCompleted = Boolean(found.completed && found.servedTop !== null
648
+ && highestTop !== null && found.servedTop >= highestTop);
649
+ if (found.failure) {
650
+ failed.push(failureOf(found.failure, node));
651
+ entry.state = "error";
652
+ } else {
653
+ entry.state = finalCompleted ? "ok" : (found.located ? "partial" : "behind");
654
+ }
655
+ completed = completed || finalCompleted;
656
+ if (finalCompleted) completedWitnessOperators.add(node.operator || node.url);
657
+ if (found.located) {
658
+ observations.push({
659
+ operator: node.operator || node.url, url: node.url, seen: true, completed: finalCompleted,
660
+ txid: found.located.txid, height: found.located.height, blockHash: found.located.blockHash,
661
+ amountAtomic: found.located.amountAtomic.toString(), locked: found.located.locked === true,
662
+ });
663
+ if (!located || found.located.score > located.score) {
617
664
  located = found.located;
618
665
  located.operator = node.operator;
619
666
  located.url = node.url;
620
667
  }
621
- } catch (error) {
622
- failed.push(failureOf(error, node));
668
+ } else if (finalCompleted) {
669
+ observations.push({ operator: node.operator || node.url, url: node.url, seen: false, completed: true,
670
+ txid: null, height: null, blockHash: null, amountAtomic: null, locked: null });
623
671
  }
624
672
  }
625
673
 
674
+ if (!located) failed.push(...staleWitnesses);
675
+ const completedOperators = [...completedWitnessOperators];
676
+ const independentOperators = completedOperators.filter((operator) => String(operator).toLowerCase() !== "ninsei");
677
+ const required = 2;
678
+ const witnessQuorum = { required, completed: completedOperators, independent: independentOperators,
679
+ ok: (network === "mainnet" ? independentOperators.length : completedOperators.length) >= required };
680
+
681
+ // ONE OPINION PER OPERATOR, THEN COMPARE THE OPINIONS. A second instance of the same operator may repeat the
682
+ // first, but it may not silently contradict it; a different operator that reports another block, amount or
683
+ // unlock state is a disagreement even when its own walk completed. Without this the first matching candidate
684
+ // hid the contradiction only because of its score or iteration order.
685
+ const normalizedObservation = (observation) => ({
686
+ operator: String(observation.operator || observation.url || ""),
687
+ seen: observation.seen === true,
688
+ txid: observation.txid === null || observation.txid === undefined ? null : String(observation.txid).toLowerCase(),
689
+ height: observation.height === null || observation.height === undefined ? null : Number(observation.height),
690
+ blockHash: observation.blockHash === null || observation.blockHash === undefined
691
+ ? null : String(observation.blockHash).toLowerCase(),
692
+ amountAtomic: observation.amountAtomic === null || observation.amountAtomic === undefined
693
+ ? null : String(observation.amountAtomic),
694
+ locked: observation.locked === null || observation.locked === undefined ? null : observation.locked === true,
695
+ });
696
+ const observationField = (a, b) => {
697
+ for (const field of ["seen", "txid", "height", "blockHash", "amountAtomic", "locked"]) {
698
+ if (a[field] !== b[field]) return field;
699
+ }
700
+ return null;
701
+ };
702
+ const groups = new Map();
703
+ for (const observation of observations) {
704
+ const normalized = normalizedObservation(observation);
705
+ const key = normalized.operator.toLowerCase();
706
+ if (!groups.has(key)) groups.set(key, []);
707
+ groups.get(key).push(normalized);
708
+ }
709
+ const witnessDisagreements = [];
710
+ for (const [operator, entries] of groups) {
711
+ for (let i = 1; i < entries.length; i += 1) {
712
+ const field = observationField(entries[0], entries[i]);
713
+ if (field) witnessDisagreements.push({ operators: [operator], field, against: "same-operator" });
714
+ }
715
+ }
716
+ const representatives = [...groups.values()].map((entries) => entries[0]);
717
+ for (let i = 1; i < representatives.length; i += 1) {
718
+ const field = observationField(representatives[0], representatives[i]);
719
+ if (field) witnessDisagreements.push({ operators: [representatives[0].operator, representatives[i].operator], field });
720
+ }
721
+ const witnessEvidence = { observations: representatives, disagreements: witnessDisagreements };
722
+
626
723
  const witness = located
627
724
  ? { state: "seen", txid: located.txid, height: located.height, blockHash: located.blockHash,
628
- amountAtomic: located.amountAtomic.toString(), operator: located.operator, url: located.url, completed, checked, failed }
629
- : { state: "pending", txid: null, height: null, blockHash: null, amountAtomic: null, completed, checked, failed };
725
+ amountAtomic: located.amountAtomic.toString(), operator: located.operator, url: located.url, completed, checked, failed,
726
+ ...witnessEvidence, quorum: witnessQuorum }
727
+ : { state: "pending", txid: null, height: null, blockHash: null, amountAtomic: null, completed, checked, failed,
728
+ ...witnessEvidence, quorum: witnessQuorum };
630
729
 
631
730
  const problems = [];
632
731
  let agrees = null;
633
732
  if (exactError) problems.push("exact:" + exactError.code);
634
733
  if (located && exact && exact.txid) {
635
- if (String(exact.txid).toLowerCase() !== located.txid) problems.push("txid");
636
- if (Number(exact.height) !== located.height) problems.push("height");
637
- if (String(exact.blockHash || "").toLowerCase() !== located.blockHash) problems.push("blockHash");
638
- if (String(exact.amountAtomic ?? "") !== located.amountAtomic.toString()) problems.push("amount");
734
+ const add = (token) => { if (!problems.includes(token)) problems.push(token); };
735
+ for (const observation of representatives) {
736
+ if (!observation.seen) {
737
+ add("witness:txid");
738
+ witnessDisagreements.push({ operators: [observation.operator], field: "seen", against: "exact" });
739
+ continue;
740
+ }
741
+ if (String(exact.txid).toLowerCase() !== observation.txid) {
742
+ add("txid");
743
+ witnessDisagreements.push({ operators: [observation.operator], field: "txid", against: "exact" });
744
+ }
745
+ if (Number(exact.height) !== observation.height) {
746
+ add("height");
747
+ witnessDisagreements.push({ operators: [observation.operator], field: "height", against: "exact" });
748
+ }
749
+ if (String(exact.blockHash || "").toLowerCase() !== observation.blockHash) {
750
+ add("blockHash");
751
+ witnessDisagreements.push({ operators: [observation.operator], field: "blockHash", against: "exact" });
752
+ }
753
+ if (String(exact.amountAtomic ?? "") !== observation.amountAtomic) {
754
+ add("amount");
755
+ witnessDisagreements.push({ operators: [observation.operator], field: "amountAtomic", against: "exact" });
756
+ }
757
+ }
758
+ if (checked.some((entry) => entry.state !== "ok")) add("witness:not-completed");
759
+ if (witnessDisagreements.length) add("witness:disagreement");
639
760
  agrees = problems.length === 0;
640
761
  } else if (located) {
641
762
  problems.push("exact:no-transaction");
642
763
  agrees = false;
643
764
  } else if (exact && exact.absent === true) {
644
- // ABSENCE NEEDS THE WHOLE SLICE WALK, NOT A SILENT WITNESS. A server that is down, stale or answered a
645
- // partial slice has not shown that the money is absent; its missing answer must not become agreement.
646
- if (witness.completed && witness.failed.length === 0) agrees = true;
765
+ // ABSENCE NEEDS THE WHOLE SLICE WALK AND TWO DISTINCT OPERATORS. A server that is down, stale or answered a
766
+ // partial slice has not shown that the money is absent; one completed operator is also not the exact path's
767
+ // quorum and must not become agreement. Two instances of one operator count once.
768
+ if (witness.completed && witness.failed.length === 0 && witness.quorum.ok && !witnessDisagreements.length) agrees = true;
647
769
  else {
648
770
  agrees = false;
649
- problems.push("witness:not-completed");
771
+ problems.push(witness.completed && witness.failed.length === 0 ? "witness:no-quorum" : "witness:not-completed");
772
+ if (witnessDisagreements.length) problems.push("witness:disagreement");
650
773
  }
651
774
  }
652
775
  return { exact, exactError, witness, agrees, problems };