blockyard 0.0.9 → 0.1.0

package/scripts/donate-qr.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
-# Regenerate the donation QR in public/index.html (the <svg class="abqr">) from the address below,
-# with OpenCV's encoder, and check the modules written decode back to the address. Run by hand when
-# the address changes; the SVG is committed, so nothing is generated at run time or in the browser.
+# Regenerate the donation QR (public/donate-qr.png, 4 px a module with the 4-module quiet zone) from
+# the address below, with OpenCV's encoder, and check the modules written decode back to the address.
+# Run by hand when the address changes; the PNG is committed, so nothing is generated at run time or
+# in the browser. It was an inline SVG until 2026-09-15, when Safari painted its ground and none of
+# its module rects; a bitmap is painted the same everywhere.
 import cv2, numpy as np, re, sys
 ADDR = 'bc1q249cv27lc2q7y0x53vkczgfvvgsjzhwxwv42gc'
 img = cv2.QRCodeEncoder.create().encode(ADDR)
@@ -12,9 +14,10 @@ for mm in re.finditer(r'M(\d+) (\d+)h1v1h-1z', d):
     x, y = int(mm.group(1)), int(mm.group(2)); m[y*8:(y+1)*8, x*8:(x+1)*8] = 0
 data, _, _ = cv2.QRCodeDetector().detectAndDecode(m)
 if data != ADDR: sys.exit(f'the QR does not decode to the address: {data!r}')
-svg = f'<svg class="abqr" viewBox="0 0 {size} {size}" width="132" height="132" role="img" aria-label="QR code of the donation address" shape-rendering="crispEdges"><rect width="{size}" height="{size}" fill="#fff"/><path fill="#000" d="{d}"/></svg>'
-p = 'public/index.html'; s = open(p).read()
-s2 = re.sub(r'<svg class="abqr".*?</svg>', svg, s, count=1, flags=re.S)
-if s2 == s and svg not in s: sys.exit('no <svg class="abqr"> in public/index.html to replace')
-open(p, 'w').write(s2)
-print(f'{n}x{n} modules, decodes to {data}')
+png = np.full((size * 4, size * 4), 255, np.uint8)
+for mm in re.finditer(r'M(\d+) (\d+)h1v1h-1z', d):
+    x, y = int(mm.group(1)), int(mm.group(2)); png[y*4:(y+1)*4, x*4:(x+1)*4] = 0
+cv2.imwrite('public/donate-qr.png', png)
+check, _, _ = cv2.QRCodeDetector().detectAndDecode(cv2.imread('public/donate-qr.png'))
+if check != ADDR: sys.exit(f'the PNG does not decode to the address: {check!r}')
+print(f'{n}x{n} modules, public/donate-qr.png decodes to {check}')

package/scripts/dos-bench.js

@@ -0,0 +1,56 @@
+// How fast the DOS Diversions' emulated PC runs on this machine, headless (docs/MEASUREMENTS.md §32).
+//
+// Boots a game from games/ on a clock that counts instructions, lets its title and demos run, and
+// reports instructions a second of wall time and the screens it drew. No browser: the same x86.js
+// and dospc.js the worker runs, on Node's V8.
+//
+//   node scripts/dos-bench.js [doom|quake] [millions of instructions]
+//
+// DOOM runs at 30 million instructions to the virtual second (a fast 486); Quake at 70 million and
+// with `+timedemo demo1`, so its screens drawn over the virtual time are the frame rate its own
+// benchmark reports on a machine exactly as fast as this emulator.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPC } from '../public/js/dospc.js';
+import { createSoundCard } from '../public/js/soundcard.js';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const game = process.argv[2] === 'quake' ? 'quake' : 'doom';
+const SPEC = {
+  doom: { dir: 'doom_dos', exe: 'DOOM.EXE', args: '', ips: 30e6, total: 400 },
+  quake: { dir: 'quake_dos', exe: 'QUAKE.EXE', args: '-nocdaudio +timedemo demo1', ips: 70e6, total: 3000 },
+}[game];
+const DIR = path.join(ROOT, 'games', SPEC.dir);
+const total = Number(process.argv[3] ?? SPEC.total) * 1e6;
+
+if (!fs.existsSync(path.join(DIR, SPEC.exe))) {
+  console.error(`no ${path.join(DIR, SPEC.exe)}: this measures the shareware ${game}, which is not here`);
+  process.exit(1);
+}
+const files = {};
+const walk = (dir, pre) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.')) continue;
+    if (e.isDirectory()) walk(path.join(dir, e.name), `${pre}${e.name}/`);
+    else files[`${pre}${e.name}`] = new Uint8Array(fs.readFileSync(path.join(dir, e.name)));
+  }
+};
+walk(DIR, '');
+
+let pc;
+const now = () => (pc ? pc.cpu.cycles : 0) / SPEC.ips * 1000;
+pc = createPC({ files, now, args: SPEC.args, sound: (mem) => createSoundCard({ mem, rate: 44100 }) });
+pc.boot(files[SPEC.exe]);
+
+const t0 = process.hrtime.bigint();
+let done = 0, graphicsAt = null;
+while (done < total && !pc.exited) {
+  done += pc.run(1e6);
+  if (graphicsAt === null && pc.vga.mode === 0x13) graphicsAt = done;
+}
+const secs = Number(process.hrtime.bigint() - t0) / 1e9;
+console.log(`${game} on node ${process.version}`);
+console.log(`${(done / 1e6).toFixed(0)} M instructions in ${secs.toFixed(2)} s: ${(done / secs / 1e6).toFixed(1)} M a second`);
+console.log(`graphics mode after ${(graphicsAt / 1e6).toFixed(1)} M instructions`);
+console.log(`${(pc.vga.frames / 2).toFixed(0)} pages flipped, ${(pc.vga.writes / 64000).toFixed(0)} screens' worth written, in ${(done / SPEC.ips).toFixed(1)} virtual seconds`);

package/scripts/setup.js

@@ -19,6 +19,8 @@
 import { existsSync, statSync, writeFileSync, copyFileSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import net from 'node:net';
+import http from 'node:http';
+import https from 'node:https';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
@@ -177,15 +179,24 @@ export const RPC_PORT = { main: 8332, test: 18332, testnet4: 48332, signet: 3833
 
 /** Is a BlockYard (or anything) already answering on this port? */
 export async function portInUse(host, port) {
-  const at = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}/api/health`;
-  try {
-    const r = await fetch(at, { signal: AbortSignal.timeout(1500) });
-    const j = await r.json().catch(() => null);
-    return { busy: true, blockyard: j?.version ?? null };
-  } catch (err) {
-    const refused = /ECONNREFUSED/.test(err?.cause?.code ?? '') || /ECONNREFUSED/.test(err?.message ?? '') || err?.name === 'TimeoutError';
-    return { busy: !refused, blockyard: null };
-  }
+  // HTTPS is the default (2026-09-15) and its certificate is self-signed, so the probe tries
+  // https first without checking the chain, then plain http
+  const h = host === '0.0.0.0' ? '127.0.0.1' : host;
+  const probe = (mod, scheme) => new Promise((resolve) => {
+    const req = mod.get({ host: h, port, path: '/api/health', timeout: 1500, rejectUnauthorized: false }, (res) => {
+      let text = '';
+      res.on('data', (d) => { text += d; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(text); } catch { /* not ours */ } resolve({ ok: true, scheme, blockyard: j?.version ?? null }); });
+    });
+    req.on('timeout', () => { req.destroy(new Error('timeout')); });
+    req.on('error', (err) => resolve({ ok: false, err }));
+  });
+  const s = await probe(https, 'https');
+  if (s.ok) return { busy: true, blockyard: s.blockyard };
+  const p = await probe(http, 'http');
+  if (p.ok) return { busy: true, blockyard: p.blockyard };
+  const refused = (e) => /ECONNREFUSED/.test(e?.code ?? '') || /ECONNREFUSED/.test(e?.message ?? '') || /timeout/.test(e?.message ?? '');
+  return { busy: !(refused(s.err) && refused(p.err)), blockyard: null };
 }
 
 // ------------------------------------------------------------------------------------ the flow
@@ -298,9 +309,20 @@ async function main() {
 
   // ------------------------------------------------------------------------ 3. the web interface
   out(step(3, STEPS, 'The web interface'));
-  say(c.dim('127.0.0.1 keeps it to this machine; 0.0.0.0 opens it to everyone who can'));
-  say(c.dim('reach the port (docs/SECURITY.md).'));
+  say(c.dim('127.0.0.1 (the default) keeps it to this machine -- reach it from elsewhere over an SSH'));
+  say(c.dim('tunnel; a LAN address, or 0.0.0.0, opens it to everyone who can reach the port. Sign-in'));
+  say(c.dim('is on either way: the first start prints the admin password once, and it serves HTTPS'));
+  say(c.dim('with a certificate it makes for itself -- expect one browser warning per address (docs/SECURITY.md).'));
   a.host = await ask('bind address', arg('host', '127.0.0.1'), validate.host);
+  // ANYTHING BUT LOOPBACK IS SAID TWICE (operator, 2026-09-15: "hardened and on 127.0.0.1,
+  // unless the user explicitly types 0.0.0.0 in the installer"): typing it is the first time,
+  // this question the second -- except when --host named it on the command line, which is as
+  // explicit as it gets
+  if (!['127.0.0.1', '::1'].includes(a.host) && arg('host') !== a.host) {
+    const who = a.host === '0.0.0.0' ? 'everyone who can reach this machine on any interface' : `everyone who can reach ${a.host}`;
+    say(`${c.warn('!')} ${who} will get the sign-in page on port ${arg('port', '21000')}; docs/SECURITY.md before opening it further`);
+    if (!(await yes(`bind ${a.host} rather than 127.0.0.1?`, false))) { a.host = '127.0.0.1'; say(c.dim('127.0.0.1 then -- an SSH tunnel reaches it from elsewhere')); }
+  }
   for (;;) {
     a.port = await ask('port', arg('port', '21000'), validate.port);
     const inUse = await portInUse(a.host, a.port);
@@ -386,7 +408,7 @@ async function main() {
   else say(c.dim('nothing to build'));
 
   // --------------------------------------------------------------------------------- done
-  const url = `http://${a.host === '0.0.0.0' ? '127.0.0.1' : a.host}:${a.port}`;
+  const url = `https://${a.host === '0.0.0.0' ? '127.0.0.1' : a.host}:${a.port}`;
   out();
   out(box([
     `${c.bold('start it')}     ${c.accent('npm start')}${!YES ? c.dim('       (or answer yes below)') : ''}`,

package/scripts/shots.mjs

@@ -129,6 +129,8 @@ for (const [name, p, settle, height = null] of [
   // measures fine; this one is told what it is.
   ['kiosk', 'kiosk', 12000, 1000],
   ['explorer-home', 'explorer', 6000],
+  // the network row, the labelled pie and the year chart (2026-09-16); content-sized like the rest
+  ['mining', 'mining', 12000],
 ]) {
   if (!doing(name)) continue;
   try { await nav(p); done.push(await shoot(name, { settle, height })); } catch (e) { fail(name, e); }
@@ -240,6 +242,10 @@ if (doing('block-space-neon')) {
     await sleep(3000);
     await evl(`document.getElementById('btnSettings')?.click()`);
     await sleep(1200);
+    // THE BLOCK SPACE TAB FIRST (2026-09-16): the sheet opens on its first tab, Appearance since
+    // the themes arrived, and a tab's controls exist only while it is the open one.
+    await evl(`document.querySelector('[data-cfgtab="space"]')?.click()`);
+    await sleep(500);
     // space.neon lives in the Block space group; find its control by data-cfg.
     const on = await evl(`(() => {
       const el=document.querySelector('[data-cfg="space.neon"]');

package/scripts/smoke.sh

@@ -63,7 +63,7 @@ echo "== booting server on :${PORT} (fake node :${FAKE_PORT}) =="
 # signed-in contract (sessions, CSRF, per-user audit, RBAC). The open posture gets its
 # own instance further down, on its own port, so both are asserted rather than one
 # replacing the other.
-BLOCKYARD_CONFIG=none BLOCKYARD_BIND=127.0.0.1 BLOCKYARD_AUTH=1 \
+BLOCKYARD_CONFIG=none BLOCKYARD_BIND=127.0.0.1 BLOCKYARD_AUTH=1 BLOCKYARD_TLS=0 \
 BLOCKYARD_DATA="$DIR" BLOCKYARD_FAKE_NODE=1 BLOCKYARD_PORT="$PORT" BLOCKYARD_ADMIN_PASSWORD="$PW" \
 BLOCKYARD_LOG_LEVEL=warn FAKE_PORT="$FAKE_PORT" node server/main.js >"$DIR/server.log" 2>&1 &
 SRV=$!

package/scripts/tls.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// blockyard tls -- make (or remake) this monitor's own self-signed certificate.
+//
+//   node scripts/tls.js [--out DIR] [--san a,b,c] [--days N] [--force] [--print]
+//
+// The server does this by itself on first start (HTTPS is the default), under <data>/tls,
+// naming the addresses it is reached on. This command is for doing it by hand: after the
+// machine's address changed, to add a name (--san), or to start over (--force). --print writes
+// the certificate to stdout, for pasting into a browser's or another machine's trust store.
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { ROOT } from '../server/config.js';
+import { localAddresses } from '../server/netinfo.js';
+import { ensureSelfSigned } from '../server/tls/selfsigned.js';
+import crypto from 'node:crypto';
+
+const argv = process.argv.slice(2);
+const flag = (n) => argv.includes(`--${n}`);
+const arg = (n, d = null) => { const i = argv.indexOf(`--${n}`); return i >= 0 && argv[i + 1] != null && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+if (flag('help') || flag('h')) {
+  process.stdout.write('usage: blockyard tls [--out DIR] [--san a,b,c] [--days N] [--force] [--print]\n');
+  process.exit(0);
+}
+const dir = arg('out', path.join(process.env.BLOCKYARD_DATA || path.join(ROOT, 'data'), 'tls'));
+const extra = (arg('san', '') || '').split(',').map((s) => s.trim()).filter(Boolean);
+const sans = ['localhost', os.hostname(), '127.0.0.1', '::1', ...localAddresses().map((a) => a.address), ...extra];
+const r = ensureSelfSigned(dir, { sans, mustName: extra, days: Number(arg('days', 825)) || 825, force: flag('force') });
+if (flag('print')) { process.stdout.write(fs.readFileSync(r.certFile, 'utf8')); process.exit(0); }
+const names = (new crypto.X509Certificate(fs.readFileSync(r.certFile, 'utf8')).subjectAltName ?? '').split(',').map((s) => s.trim().replace(/^(DNS|IP Address):/, ''));
+process.stdout.write(`${r.made ? `made a new certificate (${r.why})` : 'the certificate is current; nothing written (--force to remake it)'}\n  cert  ${r.certFile}\n  key   ${r.keyFile}\n  names ${names.join(', ')}\n${r.made ? '  restart BlockYard to serve it; browsers warn once per address\n' : ''}`);

package/server/chain/index/build.js

@@ -42,21 +42,38 @@ async function chainHashes(rpc, tip, onProgress, pace = null) {
   return { table, hashes };
 }
 
-class Pool {
-  constructor(size, workerData) {
-    this.workers = Array.from({ length: size }, () => new Worker(new URL('./worker.js', import.meta.url), { workerData }));
+export class Pool {
+  constructor(size, workerData, script = new URL('./worker.js', import.meta.url)) {
+    this.workers = Array.from({ length: size }, () => new Worker(script, { workerData }));
   }
   // run jobs, at most one per worker; onResult may be async (it is awaited before that worker's next
   // job); `pace`, if given, is awaited before each job is handed out -- the server's background build
   // uses it to hold the workers while the node's RPC is slow, since they share its disk
+  //
+  // A WORKER THAT DIES FAILS THE RUN (2026-09-15, the first Mac install: the build sat at "scan
+  // 5,720 of 5,721, about 1 s left" for an hour and a half). Only `message` was listened for, so a
+  // worker killed outright -- out of memory is the way on a machine with four of them beside the
+  // node -- answered nothing, its job was never finished and never reported, and the other workers
+  // drained the list and left the run waiting for a reply that could not come. `exit` and `error`
+  // are the reply now: the run rejects, naming the job and the way to run again.
   async run(jobs, onResult, pace = null) {
     let next = 0, failed = null;
     await Promise.all(this.workers.map((w) => new Promise((resolve) => {
+      let current = null;
+      const die = (why) => {
+        if (failed) { resolve(); return; }
+        failed = new Error(`an index worker ${why} while on ${current ? JSON.stringify(current) : 'no job'} -- if the machine ran out of memory, run again with fewer workers (addressIndexWorkers in config/local.json; each needs about 2.5 GB)`);
+        resolve();
+      };
+      w.on('exit', (code) => { if (current) die(`exited with code ${code}`); });
+      w.on('error', (err) => die(`threw: ${err?.message ?? err}`));
       const go = async () => {
-        if (failed || next >= jobs.length) { resolve(); return; }
+        if (failed || next >= jobs.length) { current = null; resolve(); return; }
         const job = jobs[next++];
         if (pace) { try { await pace(); } catch (err) { failed = err; resolve(); return; } }
+        current = job;
         w.once('message', async (msg) => {
+          current = null;
           if (msg.type === 'error') { failed = new Error(`${JSON.stringify(msg.job)}: ${msg.message}`); resolve(); return; }
           try { await onResult(msg); } catch (err) { failed = err; resolve(); return; }
           go();

package/server/collect/monitor.js

@@ -21,6 +21,7 @@ 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 { 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';
@@ -93,6 +94,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 +520,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 +569,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);
@@ -1996,6 +2023,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.
@@ -2185,6 +2213,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,295 @@
+// 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 { decodeCoinbase, 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();
+    withCb.forEach((x, k) => {
+      const tx = cbs[k]?.ok ? cbs[k].result : null;
+      const hex = tx?.vin?.[0]?.coinbase ?? '';
+      const decoded = decodeCoinbase(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 });
+    });
+    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 },
+    };
+  }
+}