blockyard 0.0.9 → 0.1.1

package/server/collect/markets.js

@@ -106,6 +106,22 @@ export const BOOKS = {
 export const DEPTH_STEP = 50;     // dollars a level on the depth grid: fixed, so snapshots compare as the price moves
 export const DEPTH_SPAN = 0.12;   // how far either side of the mid the grid reaches
 export const DEPTH_AGOS = [60, 300, 600, 1800, 3600];
+// BOUNDS ON WHAT AN EXCHANGE CAN MAKE US DO (2026-09-16, audit L5). The grid size was
+// ceil(mid x 0.24 / 50) with the mid taken from the books themselves, so one absurd book --
+// bid 60,000, ask 2e10, answering alone -- made 48 million levels, blocked pollBooks for
+// 10 s and held 5 GB for the hour the snapshot is kept. None of that takes a malicious
+// exchange, only a broken, compromised or intercepted one. So:
+//   - a book whose mid is more than DEPTH_SANE from the median of every other book and
+//     every recent ticker is not drawn; its row says why (an exchange answering nonsense
+//     is reported, never silently dropped -- rule 8);
+//   - the grid never exceeds DEPTH_MAX_LEVELS (at $50 a level that is a mid near $400,000
+//     before it bites; today's is about 370 levels);
+//   - a reply body is read up to MAX_BODY_BYTES and no further (Coinbase's whole book, the
+//     largest, measured 1.1 MB on 2026-09-11), and a redirect is an error, not a new host.
+export const DEPTH_SANE = 0.2;
+export const DEPTH_MAX_LEVELS = 2000;
+export const MAX_BODY_BYTES = 5 * 1024 * 1024;
+const TICKER_REF_MS = 600_000;    // how old a ticker may be and still vouch for a book's price
 const r3 = (v) => Math.round(v * 1000) / 1000;
 
 // A book as cumulative depth on the grid p0 + i*step: bids[i] is the BTC bid at or above that
@@ -136,11 +152,36 @@ export function depthOf(book, p0, n, step = DEPTH_STEP) {
 }
 
 const UA = 'BlockYard (self-hosted Bitcoin node monitor)';
+
+// A reply body, read no further than `limit` bytes (2026-09-16, audit L5). A declared
+// Content-Length past the limit is refused before reading; otherwise the stream is read
+// chunk by chunk and cancelled the moment it passes the limit, so a hostile or broken
+// endpoint costs at most `limit` bytes of memory, not whatever it cares to send inside
+// the 8 s timeout. A reply object with no stream (the tests' stubs) falls back to json().
+export async function readJsonCapped(r, limit = MAX_BODY_BYTES) {
+  const declared = Number(r.headers?.get?.('content-length'));
+  if (Number.isFinite(declared) && declared > limit) throw new Error(`reply of ${declared} bytes is over the ${limit}-byte limit`);
+  const reader = r.body?.getReader?.();
+  if (!reader) return r.json();
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > limit) {
+      reader.cancel().catch(() => {});
+      throw new Error(`reply over the ${limit}-byte limit`);
+    }
+    chunks.push(value);
+  }
+  return JSON.parse(Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))).toString('utf8'));
+}
 const median = (xs) => (xs.length ? (xs.length % 2 ? xs[(xs.length - 1) / 2] : (xs[xs.length / 2 - 1] + xs[xs.length / 2]) / 2) : null);
 
 export class MarketFeed {
   constructor(cfg = {}, { log = () => {}, fetchImpl = globalThis.fetch, now = Date.now, exchanges = EXCHANGES } = {}) {
-    this.cfg = { tickerMs: 15_000, candleMs: 300_000, bookMs: 30_000, idleAfterMs: 600_000, timeoutMs: 8_000, candles: 168, ...cfg };
+    this.cfg = { tickerMs: 15_000, candleMs: 300_000, bookMs: 30_000, idleAfterMs: 600_000, timeoutMs: 8_000, candles: 168, maxBodyBytes: MAX_BODY_BYTES, ...cfg };
     this.log = log;
     this.fetch = fetchImpl;
     this.now = now;
@@ -180,9 +221,11 @@ export class MarketFeed {
   }
 
   async get(url) {
-    const r = await this.fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' }, signal: AbortSignal.timeout(this.cfg.timeoutMs) });
+    // redirect 'error' (2026-09-16, audit L5): every URL above is the exchange's own API
+    // host; a 3xx pointing somewhere else is not followed.
+    const r = await this.fetch(url, { headers: { 'user-agent': UA, accept: 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(this.cfg.timeoutMs) });
     if (!r.ok) throw new Error(`HTTP ${r.status}`);
-    return r.json();
+    return readJsonCapped(r, this.cfg.maxBodyBytes);
   }
 
   async pollTickers() {
@@ -231,15 +274,41 @@ export class MarketFeed {
       }
     }));
     if (!books.size) return;
-    const mids = [...books.values()].map((b) => {
+    const midOf = (b) => {
       let bb = -Infinity, ba = Infinity;
       for (const [p] of b.bids) if (p > bb) bb = p;
       for (const [p] of b.asks) if (p < ba) ba = p;
       return (bb + ba) / 2;
-    }).sort((a, b) => a - b);
+    };
+    const bookMids = new Map([...books].map(([id, b]) => [id, midOf(b)]));
+    // Sanity (2026-09-16, audit L5): each book against everyone else -- the other books'
+    // mids and every ticker younger than ten minutes. With one book answering, the tickers
+    // are the check; with nothing to compare against, the book stands as before.
+    const tickers = this.exchanges.map((ex) => this.rows.get(ex.id)?.ticker)
+      .filter((t) => t?.last > 0 && this.now() - t.at <= TICKER_REF_MS).map((t) => t.last);
+    for (const [id, m] of bookMids) {
+      const others = [...[...bookMids].filter(([k]) => k !== id).map(([, v]) => v), ...tickers].filter((v) => Number.isFinite(v) && v > 0).sort((a, b) => a - b);
+      const ref = median(others);
+      const bad = !(Number.isFinite(m) && m > 0) ? 'no usable mid price'
+        : ref != null && Math.abs(m - ref) / ref > DEPTH_SANE ? `mid ${Math.round(m)} is more than ${DEPTH_SANE * 100}% from the other exchanges (${Math.round(ref)}); book not drawn`
+          : null;
+      if (bad) {
+        books.delete(id);
+        const row = this.rows.get(id);
+        if (row) row.bookError = { message: bad, at: this.now() };
+      }
+    }
+    if (!books.size) return;
+    const mids = [...books.keys()].map((id) => bookMids.get(id)).sort((a, b) => a - b);
     const mid = median(mids);
-    const p0 = Math.floor((mid * (1 - DEPTH_SPAN)) / DEPTH_STEP) * DEPTH_STEP;
-    const n = Math.ceil((mid * 2 * DEPTH_SPAN) / DEPTH_STEP) + 1;
+    let p0 = Math.floor((mid * (1 - DEPTH_SPAN)) / DEPTH_STEP) * DEPTH_STEP;
+    let n = Math.ceil((mid * 2 * DEPTH_SPAN) / DEPTH_STEP) + 1;
+    if (n > DEPTH_MAX_LEVELS) {
+      // Clamped: keep the mid in the middle of the grid rather than letting the grid stop
+      // short of it.
+      n = DEPTH_MAX_LEVELS;
+      p0 = Math.max(0, Math.floor((mid - (n / 2) * DEPTH_STEP) / DEPTH_STEP) * DEPTH_STEP);
+    }
     const snap = { at: this.now(), mid, p0, n, ex: {} };
     for (const [id, bk] of books) snap.ex[id] = depthOf(bk, p0, n);
     this.depthHist.push(snap);

package/server/collect/mining.js

@@ -43,6 +43,16 @@ export function parsePushes(hex) {
     const op = bytes[i];
     let n = op;
     let head = 1;
+    // 2026-09-16 (audit L4): a scriptSig may END on an OP_PUSHDATA opcode with its length
+    // bytes missing -- consensus allows any bytes after the BIP34 height, so a pool can
+    // put this in its own block for free. readUInt16LE/readUInt32LE past the end threw
+    // ERR_OUT_OF_RANGE, the monitor's lane retried that block forever and every later
+    // block waited behind it. The length is read only when all of its bytes are there;
+    // a truncated frame header ends the walk like any other unparseable frame.
+    if (op === 0x4c) head = 2;
+    else if (op === 0x4d) head = 3;
+    else if (op === 0x4e) head = 5;
+    if (i + head > bytes.length) break;
     if (op === 0x4c) { n = bytes[i + 1]; head = 2; }
     else if (op === 0x4d) { n = bytes.readUInt16LE(i + 1); head = 3; }
     else if (op === 0x4e) { n = bytes.readUInt32LE(i + 1); head = 5; }
@@ -54,6 +64,26 @@ export function parsePushes(hex) {
   return { consumed: i, total: bytes.length, pushes: out };
 }
 
+/**
+ * decodeCoinbase that cannot throw (2026-09-16, audit L4). The decoder is meant never to
+ * throw on any bytes, and the fuzz test holds it to that; this is the belt to that pair of
+ * braces for the two lanes that call it on untrusted blocks. A coinbase that still fails
+ * to decode is a fact about THAT block -- permanent, so it is recorded as unparseable (an
+ * unknown pool, `decodeError` saying why) and the lane moves on. Retrying it would only
+ * stall every block queued behind it, which is exactly what L4 found.
+ */
+export function decodeCoinbaseSafe(hex) {
+  try {
+    return decodeCoinbase(hex);
+  } catch (err) {
+    return {
+      parseable: false, truncatedAt: 0, height: null, tagText: null, tag: null,
+      commitment: null, extraNonce: null, raw: typeof hex === 'string' ? hex : '',
+      decodeError: String(err?.message ?? err),
+    };
+  }
+}
+
 /**
  * The longest printable prefix of a push. Pool tags and extra nonces share one frame
  * more often than they get a frame each, so "is this frame text" is the wrong question;
@@ -257,6 +287,8 @@ export function minerRow({ height, hash, decoded, stats, at }) {
     extraNonce: decoded?.extraNonce ?? null,
     commitment: decoded?.commitment ?? null,
     rawCoinbase: decoded?.raw ?? null,
+    // 2026-09-16 (audit L4): present only when the coinbase could not be decoded at all.
+    ...(decoded?.decodeError ? { decodeError: decoded.decodeError } : {}),
   };
 }
 

package/server/collect/monitor.js

@@ -15,12 +15,13 @@
 //    empty in this deployment -- so `health.quality` records every such gap
 //    rather than silently preferring one.
 import { EventEmitter } from 'node:events';
-import { RpcClient, RpcError } from '../rpc/client.js';
+import { RpcClient, RpcError, displayUrl, shortPath } from '../rpc/client.js';
 import { LogTail } from './logtail.js';
 import { CounterRate } from '../store/ring.js';
 import { computeSync, stripFacts } from './sync.js';
 import { SHAPES, RULE_TO_SHAPE } from './logparse.js';
-import { decodeCoinbase, minerRow, ledgerApply, ledgerRows, aliasFor, matchPool } from './mining.js';
+import { decodeCoinbaseSafe, minerRow, ledgerApply, ledgerRows, aliasFor, matchPool } from './mining.js';
+import { NetworkStats } from './network.js';
 import { summarizeTemplate, packagesFromTemplate, blockEconomy, templateCells } from './nextblock.js';
 import { templateFromMempool, LOCAL_TEMPLATE_NOTE } from './gbt.js';
 import fs from 'node:fs';
@@ -38,6 +39,15 @@ export const BLOCKSTATS_FIELDS = ['totalfee', 'txs', 'total_size', 'total_weight
   'swtotal_size', 'swtxs', 'subsidy', 'utxo_increase', 'ins', 'outs', 'avgfee', 'medianfee', 'maxfee',
   'feerate_percentiles', 'height', 'blockhash', 'time', 'mediantime'];
 
+
+// WHAT THE NODE SAYS IS DATA OF A KNOWN SHAPE, OR NOTHING (audit 2026-09-16, L2). These fields went
+// from the RPC reply to the page unchecked, and the page wrote some of them as markup: a node that
+// answered `chain: "main<img src=x onerror=…>"` put an element on the Chain page. The page now
+// escapes them too; the server also refuses to pass on a value that is not the type it names.
+export const chainName = (v) => (typeof v === 'string' && /^[a-z0-9_-]{1,24}$/i.test(v) ? v : null);
+export const boolOrNull = (v) => (typeof v === 'boolean' ? v : null);
+export const countOrNull = (v) => (Number.isFinite(v) && v >= 0 ? v : null);
+
 export class NodeMonitor extends EventEmitter {
   constructor(nodeCfg, { rpc, poll, store, log, history, logCfg, miningCfg }) {
     super();
@@ -93,6 +103,10 @@ export class NodeMonitor extends EventEmitter {
     };
     this.miningQueue = [];
     this.miningBusy = false;
+    // THE NETWORK OVER A WEEK AND A YEAR (2026-09-15; network.js): rewards, the difficulty
+    // period, hashrate samples, a week of pool shares -- refreshed from the mid tier
+    // (a thin handle on this.rpc -- the constructor's `rpc` argument is the lane TIMING block, not the client)
+    this.network = new NetworkStats({ rpc: { batch: (calls, opts) => this.rpc.batch(calls, opts) }, log: this.log, poolMap: () => this.mining.poolMap, aliases: () => this.mining.aliases });
     // THE BLOCK BEING BUILT, assembled here from the mempool (2026-09-13; operator, on how
     // mempool.space manages this against a base Core install: "do it"). It used to be one
     // getblocktemplate call costing this node 1.3-1.5 s of its single RPC thread and 1.79 MB,
@@ -515,6 +529,9 @@ export class NodeMonitor extends EventEmitter {
       this.state.peers.connections = ni.connections;
     }
     this.state.mining = unwrap(res[1]);
+    // ...not in the first half minute: the boot's own backfills have the lane, and the network
+    // row's first gathering (144 block stats, 400 headers) can wait for the live polls to settle
+    if (this.miningCfg.enabled && this.state.chainInfo && Date.now() - this.state.startedAt > 30_000) this.network.refresh(this.state.chainInfo).catch(() => {});
     const tips = unwrap(res[2]);
     if (Array.isArray(tips)) {
       this.state.tips = tips;
@@ -561,8 +578,27 @@ export class NodeMonitor extends EventEmitter {
     let raw = null;
     try {
       raw = await this.rpc.call('getrawmempool', [true], { heavy: true, key: `${this.id}:pool-verbose`, priority: 6 });
+      // A STREAK OF STALE DROPS IS ONE STORY, NOT A HUNDRED (2026-09-15: on a day the node answered
+      // slowly for thirteen hours, this poll -- lowest priority, so last to the lane -- was dropped
+      // as stale every four minutes and each drop was its own warn event: 188 of the feed's 200
+      // rows, everything else pushed out). A drop now opens a quality flag that counts, one event
+      // marks the streak's start, and one marks its end with the count and the span.
+      if (this.poolDrops?.n) {
+        const d = this.poolDrops;
+        this.addEvent({ kind: 'collector_recovered', severity: 'info', tag: 'collector', ts: Date.now(), text: `getrawmempool verbose answers again: dropped as stale ${d.n} time${d.n === 1 ? '' : 's'} over ${Math.round((Date.now() - d.since) / 60000)} min (longest wait ${Math.round(d.maxWait / 1000)}s) -- the node's RPC was too slow for the lowest-priority poll to get a turn` });
+        this.clearQuality('pool-poll-dropped');
+        this.poolDrops = null;
+      }
     } catch (err) {
-      this.addEvent({ kind: 'collector_error', severity: 'warn', tag: 'collector', ts: Date.now(), text: `getrawmempool verbose failed: ${err.message}` });
+      if (err?.kind === 'stale' && /dropped: waited/.test(err.message)) {
+        const waited = Number((/waited (\d+)ms/.exec(err.message) ?? [])[1] ?? 0);
+        const d = (this.poolDrops ??= { n: 0, since: Date.now(), maxWait: 0 });
+        d.n += 1; d.maxWait = Math.max(d.maxWait, waited);
+        if (d.n === 1) this.addEvent({ kind: 'collector_error', severity: 'warn', tag: 'collector', ts: Date.now(), text: `getrawmempool verbose dropped as stale (waited ${Math.round(waited / 1000)}s for the lane): the node's RPC is slow and this poll is the last in line; further drops are counted on the Node & RPC page until it answers again` });
+        this.flagQuality('pool-poll-dropped', `the full-pool poll (getrawmempool verbose) has been dropped as stale ${d.n} time${d.n === 1 ? '' : 's'} since ${new Date(d.since).toISOString().slice(11, 16)} UTC (longest wait ${Math.round(d.maxWait / 1000)}s): the node's RPC is answering slowly and this lowest-priority poll waits behind the live ones; the mempool panels show their last reading meanwhile`, 'warn');
+      } else {
+        this.addEvent({ kind: 'collector_error', severity: 'warn', tag: 'collector', ts: Date.now(), text: `getrawmempool verbose failed: ${err.message}` });
+      }
     }
     if (raw && typeof raw === 'object') {
       this.state.mempoolDist = summarizeMempool(raw);
@@ -861,7 +897,11 @@ export class NodeMonitor extends EventEmitter {
     const rtRes = await this.rpc.batch([{ method: 'getrawtransaction', params: [cbTxid, 2] }], { priority: 3 });
     if (!rtRes?.[0]?.ok) throw new Error(rtRes?.[0]?.error?.message ?? 'getrawtransaction unanswered');
     const vin0 = rtRes[0].result?.vin?.[0] ?? {};
-    const decoded = decodeCoinbase(vin0.coinbase ?? vin0.coinbaseHex ?? '');
+    // 2026-09-16 (audit L4): everything above that throws is the node not answering, and
+    // pumpMining puts the height back and backs off. What follows is the block's own bytes,
+    // and a coinbase we cannot read will read the same way next time -- so it never throws:
+    // the block is recorded as unparseable (an unknown pool) and the queue moves on.
+    const decoded = decodeCoinbaseSafe(vin0.coinbase ?? vin0.coinbaseHex ?? '');
     const stats = this.state.blocks.get(height) ?? {};
     const row = minerRow({
       height, hash,
@@ -1794,8 +1834,8 @@ export class NodeMonitor extends EventEmitter {
       label: s.label,
       color: s.color,
       online: this.rpc.telemetry().online,
-      chain: s.chain,
-      ibd: s.chainInfo?.initialblockdownload ?? null,
+      chain: chainName(s.chain),
+      ibd: boolOrNull(s.chainInfo?.initialblockdownload),
       tip: {
         height: s.chainInfo?.blocks ?? null,
         headers: s.chainInfo?.headers ?? null,
@@ -1814,12 +1854,12 @@ export class NodeMonitor extends EventEmitter {
       sync: computeSync({
         blocks: s.chainInfo?.blocks ?? null,
         headers: s.chainInfo?.headers ?? null,
-        ibd: s.chainInfo?.initialblockdownload ?? null,
+        ibd: boolOrNull(s.chainInfo?.initialblockdownload),
         verificationProgress: s.chainInfo?.verificationprogress ?? null,
         tipTime: s.chainInfo?.time ?? null,
         bestHash: s.chainInfo?.bestblockhash ?? null,
         sizeOnDisk: s.chainInfo?.size_on_disk ?? null,
-        chain: s.chain,
+        chain: chainName(s.chain),
         warnings: s.chainInfo?.warnings ?? [],
         blockRatePerSec: this.blockRateFast.rate(),
         blockRateFastSpanMs: this.blockRateFast.span,
@@ -1848,7 +1888,7 @@ export class NodeMonitor extends EventEmitter {
       hashrateNote: hashrateSuppressed ?? (hashrateRaw == null ? 'difficulty or a block-gap sample is missing' : null),
       avgBlockGapSec: avgGap,
       sizeOnDisk: s.chainInfo?.size_on_disk ?? null,
-      pruned: s.chainInfo?.pruned ?? null,
+      pruned: boolOrNull(s.chainInfo?.pruned),
       chainwork: s.chainInfo?.chainwork ?? null,
       uptimeSec: s.uptimeSec ?? null,
       network: s.networkInfo ? {
@@ -1874,7 +1914,7 @@ export class NodeMonitor extends EventEmitter {
         minFee: mi.mempoolminfee ?? null,
         minRelayFee: mi.minrelaytxfee ?? null,
         incrementalRelayFee: mi.incrementalrelayfee ?? null,
-        unbroadcast: mi.unbroadcastcount ?? null,
+        unbroadcast: countOrNull(mi.unbroadcastcount),
         maxDataCarrier: mi.maxdatacarriersize ?? null,
         permitBareMultisig: mi.permitbaremultisig ?? null,
         ingestRate: s.logState.relayRate ?? s.logState.acceptRate ?? null,
@@ -1996,6 +2036,7 @@ export class NodeMonitor extends EventEmitter {
         uploadMeasured: s.net.totalSent != null && s.net.totalSent > 0 && s.net.outBps != null,
       },
       attribution: this.miningView(),
+      network: this.network.view(),
       blocks: {
         count: blocks.length,
         // 40 in the live frame; /api/blocks?limit= serves up to 400 for the chart.
@@ -2010,7 +2051,7 @@ export class NodeMonitor extends EventEmitter {
       indexes: s.indexes,
       tips: s.tips,
       deployments: s.deployments,
-      rpcInfo: s.rpcInfo,
+      rpcInfo: s.rpcInfo ? { ...s.rpcInfo, logpath: shortPath(s.rpcInfo.logpath) } : null,   // no directories to viewers (audit 2026-09-16, L11)
       log: {
         ...(this.tail ? this.tail.status() : { exists: false, file: null }),
         // 'disabled' is a configuration decision; 'missing' would be a fault. The
@@ -2100,7 +2141,7 @@ export class NodeMonitor extends EventEmitter {
     // the bar without drawing which node it belongs to.
     out.sync.node = s.id;
     out.sync.nodeLabel = s.label;
-    out.sync.endpoint = this.cfg.rpcUrl;
+    out.sync.endpoint = displayUrl(this.cfg.rpcUrl);   // no userinfo to viewers (audit 2026-09-16, L3)
     // One dense row for every state; `strip` is the ordered facts to draw in it.
     out.sync.strip = stripFacts(out.sync);
     return out;
@@ -2185,6 +2226,7 @@ export class NodeMonitor extends EventEmitter {
 
   async stop() {
     this.stopped = true;
+    this.network?.stop();
     for (const t of this.tierTimers.values()) clearTimeout(t);
     if (this.logHealthTimer) clearInterval(this.logHealthTimer);
     if (this.tail) await this.tail.stop();

package/server/collect/network.js

@@ -0,0 +1,305 @@
+// THE NETWORK OVER A WEEK AND A YEAR, from this node alone (operator, 2026-09-15, with a
+// mempool.space screenshot of its mining dashboard: "Why don't we have this view in our mining
+// tab?" -- "Do it", then the adjustments table: "add this too"). Nothing here is fetched from
+// anyone but the node:
+//
+//   rewards      the last 144 blocks' subsidy, fees and transaction counts -- getblockstats, one
+//                call per block, batched, rolled forward a block at a time
+//   epochs       the start of each difficulty period back a year: its height, time and difficulty
+//                (getblockhash + getblockheader, two in-memory lookups per epoch) -- the
+//                adjustment table, the estimate for the current period, the chart's steps
+//   samples      a block every 144 back a year, with its time and difficulty: the daily hashrate
+//                estimate is difficulty * 2^32 / the mean interval across the day
+//   pools        the coinbase of every block of the last week, attributed the way the ledger
+//                does it (decodeCoinbase + the curated pool map) -- a week is ~1000 blocks at
+//                two calls each, so it fills in the background at eight blocks every few seconds
+//                and the view says how far it has got
+//
+// The arithmetic is in pure functions above the class, which is what the tests hold.
+import { decodeCoinbaseSafe, matchPool, aliasFor, tagFingerprint } from './mining.js';
+
+export const EPOCH = 2016;
+export const TARGET_SPACING = 600;
+export const HALVING_INTERVAL = 210_000;
+const DAY_BLOCKS = 144;
+
+/** Sum a window of getblockstats rows into the reward figures. Satoshis in, satoshis out. */
+export function rewardStats(rows) {
+  const r = rows.filter((x) => x && Number.isFinite(x.totalfee) && Number.isFinite(x.subsidy));
+  if (!r.length) return { blocks: 0, minersRewardSat: 0, avgBlockFeeSat: null, avgTxFeeSat: null, txs: 0, from: null, to: null };
+  const fees = r.reduce((a, x) => a + x.totalfee, 0);
+  const subsidy = r.reduce((a, x) => a + x.subsidy, 0);
+  const txs = r.reduce((a, x) => a + Math.max(0, (x.txs ?? 1) - 1), 0);   // the coinbase pays no fee
+  const hs = r.map((x) => x.height);
+  return {
+    blocks: r.length,
+    minersRewardSat: fees + subsidy,
+    avgBlockFeeSat: Math.round(fees / r.length),
+    avgTxFeeSat: txs ? Math.round(fees / txs) : null,
+    txs,
+    from: Math.min(...hs), to: Math.max(...hs),
+  };
+}
+
+/**
+ * Where the current difficulty period stands and what the next adjustment looks like, from the
+ * tip's height and time, the period's first block time, and the two difficulties.
+ * The estimate is what Core would compute if the rest of the period kept the pace so far,
+ * clamped to the protocol's factor-of-four bounds. Before ten blocks there is no pace to speak
+ * of, so the estimate is null.
+ */
+export function difficultyEstimate({ height, tipTime, epochStartTime, difficulty, prevDifficulty = null, now = Date.now() }) {
+  if (!Number.isFinite(height) || !Number.isFinite(tipTime) || !Number.isFinite(epochStartTime)) return null;
+  const epochStart = height - (height % EPOCH);
+  const into = height - epochStart;                       // blocks mined since the period's first
+  const remaining = EPOCH - into;
+  const elapsed = Math.max(1, tipTime - epochStartTime);   // seconds over `into` intervals
+  const pace = into >= 10 ? elapsed / into : null;
+  let estimatePct = null;
+  if (pace != null) {
+    const projected = pace * EPOCH;
+    const factor = Math.max(0.25, Math.min(4, (EPOCH * TARGET_SPACING) / projected));
+    estimatePct = (factor - 1) * 100;
+  }
+  const previousPct = Number.isFinite(prevDifficulty) && prevDifficulty > 0 && Number.isFinite(difficulty) ? (difficulty / prevDifficulty - 1) * 100 : null;
+  const etaSec = remaining * (pace ?? TARGET_SPACING);
+  return { epochStart, into, remaining, elapsedSec: elapsed, paceSec: pace, estimatePct, previousPct, etaSec, at: now + etaSec * 1000 };
+}
+
+/** The next halving: its height, the blocks to go, and when at the target spacing. */
+export function halvingInfo(height, { now = Date.now() } = {}) {
+  if (!Number.isFinite(height)) return null;
+  const nextHeight = (Math.floor(height / HALVING_INTERVAL) + 1) * HALVING_INTERVAL;
+  const blocksLeft = nextHeight - height;
+  const etaSec = blocksLeft * TARGET_SPACING;
+  return { nextHeight, blocksLeft, etaSec, at: now + etaSec * 1000, era: Math.floor(height / HALVING_INTERVAL) };
+}
+
+/**
+ * Hashrate estimates from block samples ({ height, time, difficulty }), any spacing: between two
+ * consecutive samples the mean interval is (t1 - t0) / (h1 - h0), and the hashrate that produces
+ * one block per that interval at the later sample's difficulty is difficulty * 2^32 / interval.
+ * Ascending by height; a sample with a non-positive interval (clock skew) is skipped.
+ */
+export function hashrateSeries(samples) {
+  const s = [...samples].filter((x) => x && Number.isFinite(x.height) && Number.isFinite(x.time) && Number.isFinite(x.difficulty)).sort((a, b) => a.height - b.height);
+  const out = [];
+  for (let i = 1; i < s.length; i++) {
+    const dh = s[i].height - s[i - 1].height, dt = s[i].time - s[i - 1].time;
+    if (dh <= 0 || dt <= 0) continue;
+    const interval = dt / dh;
+    out.push({ t: s[i].time * 1000, height: s[i].height, hashrate: s[i].difficulty * 4294967296 / interval, difficulty: s[i].difficulty });
+  }
+  return out;
+}
+
+/** The adjustment table: each epoch start against the one before it. Newest first. */
+export function adjustments(epochs) {
+  const e = [...epochs].filter((x) => x && Number.isFinite(x.height) && Number.isFinite(x.difficulty)).sort((a, b) => a.height - b.height);
+  const out = [];
+  for (let i = 1; i < e.length; i++) {
+    out.push({ height: e[i].height, time: e[i].time, difficulty: e[i].difficulty, changePct: e[i - 1].difficulty > 0 ? (e[i].difficulty / e[i - 1].difficulty - 1) * 100 : null });
+  }
+  return out.reverse();
+}
+
+/**
+ * Pool shares over the window: blocks inside it grouped by pool, share of the window, and the
+ * window's luck -- the blocks found against the number the target spacing would give.
+ * rows: { height, time, poolKey, name, labelled }.
+ */
+export function poolShares(rows, { now = Date.now(), windowSec = 7 * 86_400 } = {}) {
+  const since = now / 1000 - windowSec;
+  const inWin = rows.filter((r) => r && Number.isFinite(r.time) && r.time >= since);
+  const by = new Map();
+  for (const r of inWin) {
+    const k = r.poolKey ?? 'unknown';
+    const e = by.get(k) ?? { key: k, name: r.name ?? k, labelled: !!r.labelled, blocks: 0 };
+    e.blocks += 1;
+    by.set(k, e);
+  }
+  const pools = [...by.values()].sort((a, b) => b.blocks - a.blocks || a.name.localeCompare(b.name));
+  for (const p of pools) p.sharePct = inWin.length ? (p.blocks / inWin.length) * 100 : 0;
+  // luck against the span actually covered: while the week is still being read, the oldest
+  // block read bounds it, so a half-read week is not reported as half the luck
+  const oldest = inWin.length ? Math.min(...inWin.map((r) => r.time)) : null;
+  const spanSec = oldest == null ? windowSec : Math.min(windowSec, Math.max(TARGET_SPACING, now / 1000 - oldest));
+  const expected = spanSec / TARGET_SPACING;
+  return { blocks: inWin.length, expected, spanSec, luckPct: inWin.length ? (inWin.length / expected) * 100 : null, pools, count: pools.length, windowSec };
+}
+
+// ---------------------------------------------------------------------------- the collector
+export class NetworkStats {
+  /**
+   * @param {object} o
+   * @param {{batch: Function}} o.rpc       the node's RPC client (batch(calls, opts))
+   * @param {Function} [o.log]
+   * @param {Function} [o.poolMap]          () => the curated coinbase map, or null
+   * @param {Function} [o.aliases]          () => the operator's alias table, or null
+   * @param {Function} [o.now]
+   */
+  constructor({ rpc, log = () => {}, poolMap = () => null, aliases = () => null, now = Date.now, windowDays = 7, sampleDays = 366, rewardBlocks = 144 } = {}) {
+    this.rpc = rpc; this.log = log; this.poolMapOf = poolMap; this.aliasesOf = aliases; this.now = now;
+    this.windowDays = windowDays; this.sampleDays = sampleDays; this.rewardBlocks = rewardBlocks;
+    this.rewards = new Map();     // height -> { height, time, totalfee, subsidy, txs }
+    this.epochs = new Map();      // epoch start height -> { height, time, difficulty }
+    this.samples = new Map();     // sample height -> { height, time, difficulty }
+    this.pools = new Map();       // height -> { height, time, poolKey, name, labelled, tagText }
+    this.tip = null; this.tipTime = null; this.difficulty = null; this.networkHashPs = null;
+    this.busy = false; this.stopped = false; this.lastError = null; this.at = null;
+    this.poolTimer = null; this.poolFilling = false; this.poolTodo = [];
+  }
+
+  stop() { this.stopped = true; if (this.poolTimer) clearTimeout(this.poolTimer); }
+
+  /** Called by the monitor whenever fresh chain info lands; cheap when nothing changed. */
+  async refresh(chainInfo) {
+    if (this.stopped || this.busy || !chainInfo || !Number.isFinite(chainInfo.blocks)) return;
+    if (chainInfo.initialblockdownload === true) return;
+    const tip = chainInfo.blocks;
+    this.busy = true;
+    try {
+      const tipChanged = tip !== this.tip;
+      this.tip = tip; this.difficulty = chainInfo.difficulty ?? this.difficulty;
+      // getblockchaininfo carries the tip's time on Core 24+; older builds get one header read
+      if (Number.isFinite(chainInfo.time)) this.tipTime = chainInfo.time;
+      else if (tipChanged || this.tipTime == null) { const h = await this.headers([tip]); this.tipTime = h.get(tip)?.time ?? this.tipTime; }
+      if (tipChanged || this.networkHashPs == null) {
+        const [hr] = await this.rpc.batch([{ method: 'getnetworkhashps', params: [DAY_BLOCKS * this.windowDays] }], { priority: 6 });
+        if (hr?.ok) this.networkHashPs = hr.result;
+      }
+      await this.ensureRewards(tip);
+      await this.ensureEpochs(tip);
+      await this.ensureSamples(tip);
+      this.queuePools(tip);
+      this.at = this.now();
+      this.lastError = null;
+    } catch (err) {
+      this.lastError = err?.message ?? String(err);
+    } finally {
+      this.busy = false;
+    }
+  }
+
+  async ensureRewards(tip) {
+    const want = [];
+    for (let h = tip; h > tip - this.rewardBlocks && h > 0; h--) if (!this.rewards.has(h)) want.push(h);
+    for (let i = 0; i < want.length; i += 12) {   // twelve block reads a batch: a step the live polls can slip between
+      const chunk = want.slice(i, i + 12);
+      const res = await this.rpc.batch(chunk.map((h) => ({ method: 'getblockstats', params: [h, ['height', 'time', 'totalfee', 'subsidy', 'txs']] })), { priority: 6, heavy: true });
+      res.forEach((r, k) => { if (r?.ok && r.result) this.rewards.set(chunk[k], r.result); });
+    }
+    for (const h of [...this.rewards.keys()]) if (h <= tip - this.rewardBlocks - 10) this.rewards.delete(h);
+  }
+
+  /** height -> { height, time, difficulty } for a list of heights, two batched in-memory lookups each. */
+  async headers(heights) {
+    const out = new Map();
+    for (let i = 0; i < heights.length; i += 50) {
+      const chunk = heights.slice(i, i + 50);
+      const hashes = await this.rpc.batch(chunk.map((h) => ({ method: 'getblockhash', params: [h] })), { priority: 6 });
+      const withHash = chunk.map((h, k) => ({ h, hash: hashes[k]?.ok ? hashes[k].result : null })).filter((x) => x.hash);
+      if (!withHash.length) continue;
+      const hdrs = await this.rpc.batch(withHash.map((x) => ({ method: 'getblockheader', params: [x.hash] })), { priority: 6 });
+      hdrs.forEach((r, k) => { if (r?.ok && r.result) out.set(withHash[k].h, { height: withHash[k].h, time: r.result.time, difficulty: r.result.difficulty }); });
+    }
+    return out;
+  }
+
+  async ensureEpochs(tip) {
+    const epochStart = tip - (tip % EPOCH);
+    const perYear = Math.ceil((this.sampleDays * DAY_BLOCKS) / EPOCH) + 1;
+    const want = [];
+    for (let i = 0; i <= perYear; i++) { const h = epochStart - i * EPOCH; if (h >= 0 && !this.epochs.has(h)) want.push(h); }
+    // the block before the current period too, for the previous adjustment's base difficulty
+    if (epochStart > 0 && !this.epochs.has(epochStart - 1)) want.push(epochStart - 1);
+    if (!want.length) return;
+    for (const [h, v] of await this.headers(want)) this.epochs.set(h, v);
+  }
+
+  async ensureSamples(tip) {
+    const anchor = tip - (tip % DAY_BLOCKS);
+    const want = [];
+    for (let i = 0; i <= this.sampleDays; i++) { const h = anchor - i * DAY_BLOCKS; if (h >= 0 && !this.samples.has(h)) want.push(h); }
+    if (want.length) for (const [h, v] of await this.headers(want)) this.samples.set(h, v);
+    for (const h of [...this.samples.keys()]) if (h < anchor - (this.sampleDays + 2) * DAY_BLOCKS) this.samples.delete(h);
+  }
+
+  // ---- the week of coinbases, in the background
+  queuePools(tip) {
+    const floor = Math.max(1, tip - Math.ceil(this.windowDays * DAY_BLOCKS * 1.15));   // a little past a week, then the view trims by time
+    const todo = [];
+    for (let h = tip; h >= floor; h--) if (!this.pools.has(h)) todo.push(h);
+    this.poolTodo = todo;
+    for (const h of [...this.pools.keys()]) if (h < floor - 50) this.pools.delete(h);
+    if (todo.length && !this.poolFilling) this.pumpPools();
+  }
+
+  pumpPools() {
+    if (this.stopped) return;
+    this.poolFilling = true;
+    const chunk = this.poolTodo.splice(0, 8);
+    if (!chunk.length) { this.poolFilling = false; return; }
+    this.fetchPools(chunk)
+      .catch((err) => { this.lastError = `pools: ${err?.message ?? err}`; this.poolTodo.unshift(...chunk); })
+      .finally(() => {
+        if (this.stopped) return;
+        this.poolTimer = setTimeout(() => this.pumpPools(), this.lastError ? 15_000 : 3_000);
+        this.poolTimer.unref?.();
+      });
+  }
+
+  async fetchPools(heights) {
+    const hashes = await this.rpc.batch(heights.map((h) => ({ method: 'getblockhash', params: [h] })), { priority: 7 });
+    const withHash = heights.map((h, k) => ({ h, hash: hashes[k]?.ok ? hashes[k].result : null })).filter((x) => x.hash);
+    const blocks = await this.rpc.batch(withHash.map((x) => ({ method: 'getblock', params: [x.hash, 1] })), { priority: 7, heavy: true });
+    const withCb = withHash.map((x, k) => ({ ...x, block: blocks[k]?.ok ? blocks[k].result : null })).filter((x) => x.block?.tx?.length);
+    const cbs = await this.rpc.batch(withCb.map((x) => ({ method: 'getrawtransaction', params: [x.block.tx[0], 2, x.hash] })), { priority: 7, heavy: true });
+    const map = this.poolMapOf(), aliases = this.aliasesOf();
+    // 2026-09-16 (audit L4): one block's coinbase used to be able to throw out of this loop,
+    // and pumpPools then put the whole chunk of eight back at the front and retried it every
+    // 15 s -- forever, since the bytes never change. Only the RPC calls above are worth a
+    // retry. A block whose coinbase cannot be read is a permanent fact about that block: it
+    // is recorded as an unknown pool (`unparseable`) and the week keeps filling.
+    withCb.forEach((x, k) => {
+      const tx = cbs[k]?.ok ? cbs[k].result : null;
+      const hex = typeof tx?.vin?.[0]?.coinbase === 'string' ? tx.vin[0].coinbase : '';
+      try {
+        const decoded = decodeCoinbaseSafe(hex);
+        const tagText = decoded?.tagText ?? '';
+        const matched = matchPool(map, { tagText, rawHex: hex });
+        const rawKey = decoded?.tag ? decoded.tag : tagFingerprint(tagText);   // the ledger's own key rule (minerRow)
+        const key = matched ? matched.key : rawKey;
+        const name = matched ? matched.name : (aliasFor(aliases, rawKey) ?? rawKey);   // the ledger shows an unlabelled pool by its key
+        this.pools.set(x.h, { height: x.h, time: x.block.time, poolKey: key, name, labelled: !!matched, tagText, ...(decoded?.decodeError ? { unparseable: true } : {}) });
+      } catch {
+        const key = tagFingerprint('');
+        this.pools.set(x.h, { height: x.h, time: x.block.time, poolKey: key, name: key, labelled: false, tagText: '', unparseable: true });
+      }
+    });
+    this.at = this.now();
+  }
+
+  view() {
+    const now = this.now();
+    const tip = this.tip;
+    const epochStart = tip != null ? tip - (tip % EPOCH) : null;
+    const cur = epochStart != null ? this.epochs.get(epochStart) : null;
+    const prev = epochStart != null ? this.epochs.get(epochStart - 1) : null;
+    const est = tip != null && cur ? difficultyEstimate({ height: tip, tipTime: this.tipTime, epochStartTime: cur.time, difficulty: this.difficulty, prevDifficulty: prev?.difficulty ?? null, now }) : null;
+    const series = hashrateSeries([...this.samples.values(), ...(tip != null && this.tipTime != null && this.difficulty != null ? [{ height: tip, time: this.tipTime, difficulty: this.difficulty }] : [])]);
+    const shares = poolShares([...this.pools.values()], { now, windowSec: this.windowDays * 86_400 });
+    const windowFloor = tip != null ? tip - Math.ceil(this.windowDays * DAY_BLOCKS * 1.15) : null;
+    return {
+      at: this.at, lastError: this.lastError, tip,
+      // exactly the newest 144: the map keeps a few extra rows below the window between prunes
+      rewards: rewardStats([...this.rewards.values()].sort((a, b) => b.height - a.height).slice(0, this.rewardBlocks)),
+      difficulty: this.difficulty,
+      adjustment: est,
+      halving: tip != null ? halvingInfo(tip, { now }) : null,
+      adjustments: adjustments([...this.epochs.values()].filter((e) => e.height % EPOCH === 0)).slice(0, 27),   // a year and a period; the card shows six, View more all
+      hashrate: { networkHashPs: this.networkHashPs, windowBlocks: DAY_BLOCKS * this.windowDays, series },
+      pools: { ...shares, filled: this.pools.size, todo: this.poolTodo.length, filling: this.poolFilling, floor: windowFloor },
+    };
+  }
+}