@ninsei-labs/sdk 0.58.0 → 0.59.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.
@@ -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 });
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 });
251
246
  }
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 };
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,61 @@ 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 failure = null;
517
494
  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 });
495
+ let slice;
496
+ let txs;
497
+ try {
498
+ // The witness reads its tip at slice time, so a block can arrive between the tip read and this request. The
499
+ // parser accepts a newer tip and rejects one below the top the walk started from.
500
+ slice = await readWitnessSlice(node, index, { network, fetchImpl, timeoutMs, tipHeight: toHeight });
501
+ txs = await readSliceTransactions(node, slice, { fetchImpl, timeoutMs });
502
+ } catch (error) {
503
+ // A CANDIDATE FOUND BEFORE THE FAILURE IS STILL A CANDIDATE. The slice walk is evidence, and a later
504
+ // refused slice does not erase the transaction already read from an earlier one. The caller records the
505
+ // failure beside the located candidate; an absence still requires the whole walk.
506
+ failure = error;
507
+ break;
508
+ }
520
509
  for (const block of slice.blocks) {
510
+ // THE SLICE IS A FIXED WINDOW; THE SWAP STARTS AT `fromHeight`. Blocks before the birth height may contain
511
+ // an earlier transfer to the same address, and counting them would make the slice walk disagree with the
512
+ // exact walk that starts at the birth height.
513
+ if (block.height < fromHeight) continue;
521
514
  for (const txid of block.txids) {
522
515
  const tx = txs.get(txid);
523
516
  if (!tx) continue;
@@ -529,19 +522,21 @@ async function locateInSlices(node, { expectedAtomic, address, viewSecret, spend
529
522
  const amountVerified = hit[0].outputs.every((o) => o.amountVerified === true);
530
523
  const locked = hit[0].unlock && hit[0].unlock.locked === true;
531
524
  const score = (amountAtomic >= expectedAtomic ? 4 : 0) + (amountVerified ? 2 : 0) + (locked ? 0 : 1);
532
- const candidate = { txid, height: block.height, blockHash: block.hash, amountAtomic, score };
525
+ const candidate = { txid, height: block.height, blockHash: block.hash, amountAtomic, locked, score };
533
526
  if (!best || score > best.score || (score === best.score && amountAtomic > best.amountAtomic)) best = candidate;
534
527
  }
535
528
  }
536
529
  // 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.
530
+ // the last witness request is still a fixed slice, never the payout height. Completion is judged by the
531
+ // LAST BLOCK the witness actually served, not by the slice index: a witness can stop inside the same
532
+ // 20-block window as the target and still be behind it.
539
533
  if (best && best.score === 7) {
540
- completed = index === last;
534
+ completed = slice.to >= target;
541
535
  break;
542
536
  }
537
+ if (index === last) completed = slice.to >= target;
543
538
  }
544
- return { located: best, completed };
539
+ return { located: best, completed, failure };
545
540
  }
546
541
 
547
542
  /**
@@ -562,11 +557,20 @@ export async function verifyArrivalShadow(request) {
562
557
  if (!witnessNodes.some((node) => node.protocol === "witness-v1")) {
563
558
  throw new SdkError("bad-input", { field: "witnessNodes", why: "no-witness-v1" });
564
559
  }
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;
560
+ // THE SAME ENGINE BINDING AS `verifyArrival`. The shadow path does not carry a second copy of the view/spend rule.
561
+ if (!isStr(request.address)) throw new SdkError("bad-input", { field: "address" });
562
+ if (!isStr(request.spendPub)) throw new SdkError("bad-input", { field: "spendPub" });
563
+ if (request.viewSecret === undefined || request.viewSecret === null) throw new SdkError("bad-input", { field: "viewSecret" });
564
+ const bound = engine.xmrScan.watchedAddressVerdict({
565
+ address: request.address, viewSecret: request.viewSecret, spendPub: request.spendPub,
566
+ });
567
+ if (!bound.ok) {
568
+ if (bound.code === "bad-input") throw new SdkError("bad-input", { field: bound.field || "address", why: bound.why });
569
+ throw new SdkError(bound.code, { field: bound.field || "address", address: request.address });
570
+ }
571
+ const network = request.network || bound.keys.network;
572
+ const viewSecret = bound.viewSecret;
573
+ const spendPub = bound.spendPub;
570
574
  const fetchImpl = typeof request.fetch === "function" ? request.fetch : globalThis.fetch;
571
575
  if (typeof fetchImpl !== "function") throw new SdkError("bad-input", { field: "fetch" });
572
576
  const timeoutMs = Number.isFinite(Number(request.timeoutMs)) && Number(request.timeoutMs) > 0 ? Number(request.timeoutMs) : 20000;
@@ -576,15 +580,6 @@ export async function verifyArrivalShadow(request) {
576
580
  let expectedAtomic;
577
581
  try { expectedAtomic = BigInt(request.expectedAtomic); } catch { throw new SdkError("bad-input", { field: "expectedAtomic" }); }
578
582
  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
583
 
589
584
  let exact = null;
590
585
  let exactError = null;
@@ -593,60 +588,166 @@ export async function verifyArrivalShadow(request) {
593
588
 
594
589
  const checked = [];
595
590
  const failed = [];
596
- let located = null;
597
- let completed = false;
591
+ const staleWitnesses = [];
592
+ const readable = [];
593
+ const observations = [];
594
+ // THE WALK MUST REACH THE HIGHEST TOP ANY SOURCE READ. A witness that is behind the exact nodes OR behind another
595
+ // witness cannot prove absence in the blocks it has not seen; its own `toHeight` is therefore not the completion
596
+ // target. Collect every top first, then walk against the common target.
597
+ const exactTop = exactTopOf(exact);
598
+ let highestTop = exactTop;
598
599
  for (const node of witnessNodes) {
599
600
  if (node.protocol !== "witness-v1") { failed.push({ url: node.url, operator: node.operator, code: "no-slice-witness" }); continue; }
600
601
  let info;
601
602
  try { info = await getInfo(node, fetchImpl, timeoutMs); }
602
603
  catch (error) { failed.push(failureOf(error, node)); checked.push({ url: node.url, operator: node.operator, state: "down" }); continue; }
603
604
  if (!info.synced) {
604
- failed.push({ url: node.url, operator: node.operator, code: "stale", why: "not-synchronized" });
605
+ staleWitnesses.push({ url: node.url, operator: node.operator, code: "stale", why: "not-synchronized" });
605
606
  checked.push({ url: node.url, operator: node.operator, state: "stale", height: info.height });
606
607
  continue;
607
608
  }
608
609
  const top = Math.max(0, info.height - 1);
609
- checked.push({ url: node.url, operator: node.operator, state: "ok", height: info.height });
610
+ const entry = { url: node.url, operator: node.operator, state: "ok", height: info.height };
611
+ checked.push(entry);
612
+ highestTop = highestTop === null ? top : Math.max(highestTop, top);
613
+ readable.push({ node, top, entry });
614
+ }
615
+ let located = null;
616
+ let completed = false;
617
+ const completedWitnessOperators = new Set();
618
+ for (const { node, top, entry } of readable) {
619
+ const targetTop = highestTop === null ? top : Math.max(top, highestTop);
610
620
  try {
611
621
  const found = await locateInSlices(node, {
612
622
  expectedAtomic, address: request.address, viewSecret, spendPub, fromHeight, toHeight: top,
623
+ targetTop,
613
624
  nowSec, network, fetchImpl, timeoutMs,
614
625
  });
615
626
  completed = completed || found.completed;
616
- if (found.located && (!located || found.located.score > located.score)) {
617
- located = found.located;
618
- located.operator = node.operator;
619
- located.url = node.url;
627
+ if (found.completed) completedWitnessOperators.add(node.operator || node.url);
628
+ if (found.failure) {
629
+ failed.push(failureOf(found.failure, node));
630
+ entry.state = "error";
631
+ } else if (!found.completed) entry.state = found.located ? "partial" : "behind";
632
+ if (found.located) {
633
+ observations.push({
634
+ operator: node.operator || node.url, url: node.url, seen: true, completed: found.completed,
635
+ txid: found.located.txid, height: found.located.height, blockHash: found.located.blockHash,
636
+ amountAtomic: found.located.amountAtomic.toString(), locked: found.located.locked === true,
637
+ });
638
+ if (!located || found.located.score > located.score) {
639
+ located = found.located;
640
+ located.operator = node.operator;
641
+ located.url = node.url;
642
+ }
643
+ } else if (found.completed) {
644
+ observations.push({ operator: node.operator || node.url, url: node.url, seen: false, completed: true,
645
+ txid: null, height: null, blockHash: null, amountAtomic: null, locked: null });
620
646
  }
621
647
  } catch (error) {
648
+ entry.state = "error";
622
649
  failed.push(failureOf(error, node));
623
650
  }
624
651
  }
625
652
 
653
+ if (!located) failed.push(...staleWitnesses);
654
+ const completedOperators = [...completedWitnessOperators];
655
+ const independentOperators = completedOperators.filter((operator) => String(operator).toLowerCase() !== "ninsei");
656
+ const required = 2;
657
+ const witnessQuorum = { required, completed: completedOperators, independent: independentOperators,
658
+ ok: (network === "mainnet" ? independentOperators.length : completedOperators.length) >= required };
659
+
660
+ // ONE OPINION PER OPERATOR, THEN COMPARE THE OPINIONS. A second instance of the same operator may repeat the
661
+ // first, but it may not silently contradict it; a different operator that reports another block, amount or
662
+ // unlock state is a disagreement even when its own walk completed. Without this the first matching candidate
663
+ // hid the contradiction only because of its score or iteration order.
664
+ const normalizedObservation = (observation) => ({
665
+ operator: String(observation.operator || observation.url || ""),
666
+ seen: observation.seen === true,
667
+ txid: observation.txid === null || observation.txid === undefined ? null : String(observation.txid).toLowerCase(),
668
+ height: observation.height === null || observation.height === undefined ? null : Number(observation.height),
669
+ blockHash: observation.blockHash === null || observation.blockHash === undefined
670
+ ? null : String(observation.blockHash).toLowerCase(),
671
+ amountAtomic: observation.amountAtomic === null || observation.amountAtomic === undefined
672
+ ? null : String(observation.amountAtomic),
673
+ locked: observation.locked === null || observation.locked === undefined ? null : observation.locked === true,
674
+ });
675
+ const observationField = (a, b) => {
676
+ for (const field of ["seen", "txid", "height", "blockHash", "amountAtomic", "locked"]) {
677
+ if (a[field] !== b[field]) return field;
678
+ }
679
+ return null;
680
+ };
681
+ const groups = new Map();
682
+ for (const observation of observations) {
683
+ const normalized = normalizedObservation(observation);
684
+ const key = normalized.operator.toLowerCase();
685
+ if (!groups.has(key)) groups.set(key, []);
686
+ groups.get(key).push(normalized);
687
+ }
688
+ const witnessDisagreements = [];
689
+ for (const [operator, entries] of groups) {
690
+ for (let i = 1; i < entries.length; i += 1) {
691
+ const field = observationField(entries[0], entries[i]);
692
+ if (field) witnessDisagreements.push({ operators: [operator], field, against: "same-operator" });
693
+ }
694
+ }
695
+ const representatives = [...groups.values()].map((entries) => entries[0]);
696
+ for (let i = 1; i < representatives.length; i += 1) {
697
+ const field = observationField(representatives[0], representatives[i]);
698
+ if (field) witnessDisagreements.push({ operators: [representatives[0].operator, representatives[i].operator], field });
699
+ }
700
+ const witnessEvidence = { observations: representatives, disagreements: witnessDisagreements };
701
+
626
702
  const witness = located
627
703
  ? { 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 };
704
+ amountAtomic: located.amountAtomic.toString(), operator: located.operator, url: located.url, completed, checked, failed,
705
+ ...witnessEvidence, quorum: witnessQuorum }
706
+ : { state: "pending", txid: null, height: null, blockHash: null, amountAtomic: null, completed, checked, failed,
707
+ ...witnessEvidence, quorum: witnessQuorum };
630
708
 
631
709
  const problems = [];
632
710
  let agrees = null;
633
711
  if (exactError) problems.push("exact:" + exactError.code);
634
712
  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");
713
+ const add = (token) => { if (!problems.includes(token)) problems.push(token); };
714
+ for (const observation of representatives) {
715
+ if (!observation.seen) {
716
+ add("witness:txid");
717
+ witnessDisagreements.push({ operators: [observation.operator], field: "seen", against: "exact" });
718
+ continue;
719
+ }
720
+ if (String(exact.txid).toLowerCase() !== observation.txid) {
721
+ add("txid");
722
+ witnessDisagreements.push({ operators: [observation.operator], field: "txid", against: "exact" });
723
+ }
724
+ if (Number(exact.height) !== observation.height) {
725
+ add("height");
726
+ witnessDisagreements.push({ operators: [observation.operator], field: "height", against: "exact" });
727
+ }
728
+ if (String(exact.blockHash || "").toLowerCase() !== observation.blockHash) {
729
+ add("blockHash");
730
+ witnessDisagreements.push({ operators: [observation.operator], field: "blockHash", against: "exact" });
731
+ }
732
+ if (String(exact.amountAtomic ?? "") !== observation.amountAtomic) {
733
+ add("amount");
734
+ witnessDisagreements.push({ operators: [observation.operator], field: "amountAtomic", against: "exact" });
735
+ }
736
+ }
737
+ if (witnessDisagreements.length) add("witness:disagreement");
639
738
  agrees = problems.length === 0;
640
739
  } else if (located) {
641
740
  problems.push("exact:no-transaction");
642
741
  agrees = false;
643
742
  } 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;
743
+ // ABSENCE NEEDS THE WHOLE SLICE WALK AND TWO DISTINCT OPERATORS. A server that is down, stale or answered a
744
+ // partial slice has not shown that the money is absent; one completed operator is also not the exact path's
745
+ // quorum and must not become agreement. Two instances of one operator count once.
746
+ if (witness.completed && witness.failed.length === 0 && witness.quorum.ok && !witnessDisagreements.length) agrees = true;
647
747
  else {
648
748
  agrees = false;
649
- problems.push("witness:not-completed");
749
+ problems.push(witness.completed && witness.failed.length === 0 ? "witness:no-quorum" : "witness:not-completed");
750
+ if (witnessDisagreements.length) problems.push("witness:disagreement");
650
751
  }
651
752
  }
652
753
  return { exact, exactError, witness, agrees, problems };