npm - blockyard - Versions diffs - 0.0.1 → 0.1.0 - Mend

blockyard 0.0.1 → 0.1.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.

Files changed (122) hide show

package/CHANGELOG.md +929 -0
package/LICENSE +202 -0
package/NOTICE +4 -0
package/README.md +191 -4
package/SECURITY.md +38 -0
package/bin/blockyard.js +41 -0
package/config/pool-map.json +2620 -0
package/docs/API.md +1577 -0
package/docs/ARCHITECTURE.md +1394 -0
package/docs/AUTO-UPDATE.md +269 -0
package/docs/CONFIGURATION.md +847 -0
package/docs/DEFECTS.md +813 -0
package/docs/EFFECTS-AGENTS.md +448 -0
package/docs/GETTING-STARTED.md +205 -0
package/docs/INSTALL.md +547 -0
package/docs/MEASUREMENTS.md +1401 -0
package/docs/RULES.md +681 -0
package/docs/SECURITY-AUDIT-2026-09-14.md +177 -0
package/docs/SECURITY-AUDIT.md +258 -0
package/docs/SECURITY.md +212 -0
package/docs/TROUBLESHOOTING.md +332 -0
package/docs/USER-GUIDE.md +1262 -0
package/package.json +53 -5
package/public/404.html +9 -0
package/public/css/app.css +2009 -0
package/public/donate-qr.png +0 -0
package/public/index.html +1085 -0
package/public/js/about.js +112 -0
package/public/js/agents.js +1141 -0
package/public/js/app.js +1386 -0
package/public/js/arkanoid.js +806 -0
package/public/js/blockanoid.js +347 -0
package/public/js/blockout.js +347 -0
package/public/js/blockpack.js +428 -0
package/public/js/blockscene3d.js +2830 -0
package/public/js/breakout.js +224 -0
package/public/js/charts.js +635 -0
package/public/js/depthchart.js +315 -0
package/public/js/details3d.js +4342 -0
package/public/js/doom.js +31 -0
package/public/js/dosaudio.js +48 -0
package/public/js/dosgame.js +389 -0
package/public/js/dosio.js +186 -0
package/public/js/dospc.js +1353 -0
package/public/js/dosworker.js +196 -0
package/public/js/explorer.js +405 -0
package/public/js/feepalette.js +149 -0
package/public/js/fmt.js +162 -0
package/public/js/goggles.js +886 -0
package/public/js/kiosk.js +41 -0
package/public/js/login.js +88 -0
package/public/js/markets.js +395 -0
package/public/js/mining.js +1416 -0
package/public/js/panels.js +970 -0
package/public/js/pricechart.js +189 -0
package/public/js/quake.js +20 -0
package/public/js/settings.js +1096 -0
package/public/js/soundcard.js +459 -0
package/public/js/tetris.js +226 -0
package/public/js/tetrust.js +356 -0
package/public/js/tetsound.js +175 -0
package/public/js/theme.js +235 -0
package/public/js/wolf3d.js +22 -0
package/public/js/x86.js +1978 -0
package/public/login.html +33 -0
package/scripts/blockfile-measure.js +156 -0
package/scripts/browser-check.mjs +286 -0
package/scripts/check.js +173 -0
package/scripts/decode-check.js +81 -0
package/scripts/doc-counts.js +109 -0
package/scripts/donate-qr.py +23 -0
package/scripts/dos-bench.js +56 -0
package/scripts/fake-node.js +534 -0
package/scripts/index-bench.js +216 -0
package/scripts/index-benchmark.js +117 -0
package/scripts/index-build.js +40 -0
package/scripts/live-render-check.mjs +89 -0
package/scripts/manage-users.js +132 -0
package/scripts/motion-check.mjs +138 -0
package/scripts/pool-map.js +157 -0
package/scripts/setup.js +432 -0
package/scripts/shots.mjs +278 -0
package/scripts/smoke.sh +327 -0
package/scripts/tls.js +31 -0
package/scripts/ui.js +174 -0
package/server/auth/sessions.js +221 -0
package/server/auth/users.js +243 -0
package/server/chain/blockfile.js +234 -0
package/server/chain/index/build.js +210 -0
package/server/chain/index/heights.js +36 -0
package/server/chain/index/live.js +276 -0
package/server/chain/index/rows.js +145 -0
package/server/chain/index/store.js +154 -0
package/server/chain/index/worker.js +109 -0
package/server/chain/tx.js +310 -0
package/server/collect/gbt.js +229 -0
package/server/collect/logparse.js +765 -0
package/server/collect/logtail.js +189 -0
package/server/collect/markets.js +333 -0
package/server/collect/mining.js +333 -0
package/server/collect/monitor.js +2545 -0
package/server/collect/network.js +295 -0
package/server/collect/nextblock.js +275 -0
package/server/collect/sync.js +386 -0
package/server/config.js +644 -0
package/server/http/api.js +1319 -0
package/server/http/explorer.js +418 -0
package/server/http/games.js +77 -0
package/server/http/server.js +420 -0
package/server/http/sse.js +176 -0
package/server/http/static.js +212 -0
package/server/main.js +673 -0
package/server/netinfo.js +253 -0
package/server/rpc/allowlist.js +130 -0
package/server/rpc/client.js +414 -0
package/server/store/audit.js +148 -0
package/server/store/history.js +220 -0
package/server/store/ledger.js +290 -0
package/server/store/ring.js +173 -0
package/server/tls/selfsigned.js +160 -0
package/server/util/fmt.js +29 -0
package/systemd/blockyard.service +102 -0

package/public/login.html ADDED Viewed

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en" data-blockyard-build="%BLOCKYARD_BUILD%">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>sign in - BlockYard</title>
+<link rel="stylesheet" href="/css/app.css">
+<link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2032%2032%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22g%22%20x1%3D%220%22%20y1%3D%220%22%20x2%3D%221%22%20y2%3D%221%22%3E%3Cstop%20offset%3D%220%22%20stop-color%3D%22%23ffb85c%22%2F%3E%3Cstop%20offset%3D%22.55%22%20stop-color%3D%22%23f7931a%22%2F%3E%3Cstop%20offset%3D%221%22%20stop-color%3D%22%23a8640d%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%2232%22%20height%3D%2232%22%20rx%3D%227.5%22%20fill%3D%22url%28%23g%29%22%2F%3E%3Cg%20fill%3D%22%2316110a%22%20opacity%3D%22.14%22%3E%3Crect%20x%3D%224%22%20y%3D%2224.6%22%20width%3D%228%22%20height%3D%223.6%22%20rx%3D%221%22%2F%3E%3Crect%20x%3D%2213%22%20y%3D%2224.6%22%20width%3D%226%22%20height%3D%223.6%22%20rx%3D%221%22%2F%3E%3Crect%20x%3D%2220%22%20y%3D%2224.6%22%20width%3D%228%22%20height%3D%223.6%22%20rx%3D%221%22%2F%3E%3C%2Fg%3E%3Cpath%20fill%3D%22%231a1206%22%20fill-rule%3D%22evenodd%22%20d%3D%22M5%208h6.6a4.2%204.2%200%200%201%202.35%207.66A4.4%204.4%200%200%201%2012%2024H5Zm3.3%202.9v3.5h3.1a1.75%201.75%200%200%200%200-3.5Zm0%206.4v3.8h3.4a1.9%201.9%200%200%200%200-3.8Z%22%2F%3E%3Cpath%20fill%3D%22%231a1206%22%20d%3D%22M16.8%208h3.3l2.75%205.3L25.6%208h3.3l-4.85%208.8V24h-3.3v-7.2Z%22%2F%3E%3C%2Fsvg%3E">
+</head>
+<body class="login-body">
+  <div class="login-card">
+    <h1>Block<b>Yard</b></h1>
+    <p class="sub" id="sub">Bitcoin node monitor</p>
+    <div class="err hidden" id="err"></div>
+    <form id="f" autocomplete="on">
+      <div class="field">
+        <label for="u">username</label>
+        <input id="u" name="username" autocomplete="username" autocapitalize="none" spellcheck="false" required>
+      </div>
+      <div class="field">
+        <label for="p">password</label>
+        <input id="p" name="password" type="password" autocomplete="current-password" required>
+      </div>
+      <button class="btn primary block" id="go" type="submit">sign in</button>
+    </form>
+    <p class="note tiny faint mt-14" id="hint">Read-only by default. This tool cannot start, stop or reconfigure the node unless the operator has explicitly enabled specific actions.</p>
+  </div>
+  <script type="module" src="/js/login.js"></script>
+</body>
+</html>

package/scripts/blockfile-measure.js ADDED Viewed

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// What would an address index over this node's chain cost? Measured on the node's own files, not
+// estimated from blog posts.
+//
+//   node scripts/blockfile-measure.js [--dir <datadir>/blocks] [--files 0,500,...] [--sample N] [--verify]
+//
+// For each sampled blkNNNNN.dat and its revNNNNN.dat it times, separately: the disk read, the XOR,
+// decoding every block (transactions, output scripts, addresses), pairing each block with its undo
+// record (shape, then Core's checksum), and decoding the undo data (every spent output, with its
+// address). It counts what an index would have to store -- a funding row per spendable output, a
+// spending row per input -- and extrapolates across all files by interpolating between the samples,
+// because file contents change a great deal over the chain's history.
+//
+// --verify also checks one block per sampled file against getblock <hash> 3 (every prevout), so the
+// numbers are never measured on a decoder that is quietly wrong.
+//
+// Read-only: the node's files are opened for reading and nothing else.
+import { openSync, readSync, closeSync, fstatSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { Reader, readHeader, readTx, classifyScript } from '../server/chain/tx.js';
+import { xorKey, unxor, records, decodeBlockUndo, pairBlocksWithUndo, MAGIC } from '../server/chain/blockfile.js';
+const arg = (name, def) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : def; };
+const dir = arg('dir', '/storage/core-oracle/blocks');
+const all = readdirSync(dir).filter((f) => /^blk\d{5}\.dat$/.test(f)).sort();
+const last = all.length - 1;
+// the newest file is still being written, so the default sample stops one short of it
+const sample = arg('files', null)
+  ? arg('files').split(',').map(Number)
+  : Array.from({ length: Number(arg('sample', 16)) }, (_, i) => Math.round((i * (last - 1)) / (Number(arg('sample', 16)) - 1)));
+const key = xorKey(dir);
+const verify = process.argv.includes('--verify');
+const ms = (t0) => performance.now() - t0;
+let rpcCall = null;
+if (verify) {
+  const { loadConfig } = await import('../server/config.js');
+  const { RpcClient } = await import('../server/rpc/client.js');
+  const cfg = loadConfig();
+  const node = cfg.nodes.find((n) => n.datadir && dir.startsWith(n.datadir)) ?? cfg.nodes[0];
+  const rpc = new RpcClient(node, { ...(cfg.rpc ?? {}), ...(node.rpc ?? {}) }, { log: { info() {}, warn() {}, error() {}, debug() {} } });
+  rpcCall = async (method, params) => {
+    const [r] = await rpc.batch([{ method, params }], { key: `measure:${method}:${params[0]}`, timeoutMs: 600_000, maxWaitMs: 600_000 });
+    if (!r.ok) throw new Error(`${method}: ${r.error?.message}`);
+    return r.result;
+  };
+}
+function readRaw(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const buf = Buffer.allocUnsafe(size);
+    let got = 0;
+    while (got < size) { const n = readSync(fd, buf, got, size - got, got); if (n === 0) break; got += n; }
+    return buf.subarray(0, got);
+  } finally { closeSync(fd); }
+}
+const rows = [];
+for (const n of sample) {
+  const id = String(n).padStart(5, '0');
+  const r = { file: n };
+  let t = performance.now();
+  const blk = readRaw(path.join(dir, `blk${id}.dat`));
+  const rev = readRaw(path.join(dir, `rev${id}.dat`));
+  r.readMs = ms(t); r.blkMB = blk.length / 1e6; r.revMB = rev.length / 1e6;
+  t = performance.now(); unxor(blk, key); unxor(rev, key); r.xorMs = ms(t);
+  // blocks: full decode, addresses included (classifyScript runs per output inside readTx)
+  t = performance.now();
+  const blocks = [];
+  let txs = 0, outputs = 0, inputs = 0, funding = 0, height0 = null;
+  const scripts = new Set();
+  for (const rec of records(blk, MAGIC.main)) {
+    const rd = new Reader(rec.body);
+    const header = readHeader(rd);
+    const ntx = rd.varint();
+    const inCounts = [];
+    for (let i = 0; i < ntx; i++) {
+      const tx = readTx(rd);
+      txs++; outputs += tx.vout.length;
+      if (i > 0) { inputs += tx.vin.length; inCounts.push(tx.vin.length); }
+      for (const o of tx.vout) if (o.scriptPubKey.type !== 'nulldata') { funding++; scripts.add(createHash('sha256').update(o.scriptPubKey.hex).digest('base64').slice(0, 11)); }
+    }
+    blocks.push({ header, ntx, inCounts });
+  }
+  r.decodeMs = ms(t);
+  Object.assign(r, { blocks: blocks.length, txs, outputs, inputs, funding, distinctScripts: scripts.size });
+  // pair each block with its undo record: tx count first, then Core's checksum
+  t = performance.now();
+  const undos = [...records(rev, MAGIC.main, 32)];
+  const pairs = pairBlocksWithUndo(blocks.map((b) => ({ hash: b.header.hash, previousblockhash: b.header.previousblockhash, ntx: b.ntx })), undos);
+  const paired = [...pairs].map(([i, u]) => [blocks[i], u]);
+  r.pairMs = ms(t); r.paired = paired.length; r.undoRecords = undos.length;
+  // undo: every spent coin, with the address its script pays
+  t = performance.now();
+  let spent = 0, special = 0;
+  for (const [, u] of paired) {
+    for (const coins of decodeBlockUndo(u.body)) for (const c of coins) {
+      spent++;
+      classifyScript(c.script);
+      if (c.script.length === 67) special++;       // an uncompressed-key P2PK, rebuilt from 33 bytes
+    }
+  }
+  r.undoMs = ms(t); r.spent = spent; r.p2pkUncompressedSpent = special;
+  if (verify && paired.length) {
+    const [b, u] = paired[Math.floor(paired.length / 2)];
+    const want = await rpcCall('getblock', [b.header.hash, 3]);
+    const undo = decodeBlockUndo(u.body);
+    let bad = 0, checked = 0;
+    want.tx.slice(1).forEach((tx, i) => tx.vin.forEach((vin, j) => {
+      const c = undo[i][j]; const p = vin.prevout; checked++;
+      if (c.value_sat !== Math.round(p.value * 1e8) || c.script.toString('hex') !== p.scriptPubKey.hex || c.height !== p.height || c.coinbase !== p.generated) bad++;
+    }));
+    r.verified = { height: want.height, coins: checked, mismatches: bad };
+    height0 = want.height;
+  }
+  rows.push(r);
+  const f = (v, d = 0) => v.toFixed(d);
+  console.log(`blk${id}: ${f(r.blkMB)}+${f(r.revMB)} MB read ${f(r.readMs)} ms, xor ${f(r.xorMs)}, decode ${f(r.decodeMs)}, pair ${f(r.pairMs)}, undo ${f(r.undoMs)} | ${r.blocks} blocks (${r.paired} paired), ${txs} tx, ${outputs} out, ${inputs} in${r.verified ? ` | verified h${r.verified.height}: ${r.verified.coins} coins, ${r.verified.mismatches} mismatches` : ''}${height0 == null ? '' : ''}`);
+}
+// extrapolate across every file by linear interpolation between sampled files
+const at = (k, fileNo) => {
+  const s = rows;
+  if (fileNo <= s[0].file) return s[0][k];
+  for (let i = 1; i < s.length; i++) if (fileNo <= s[i].file) {
+    const a = s[i - 1], b = s[i]; const u = (fileNo - a.file) / Math.max(1, b.file - a.file);
+    return a[k] + (b[k] - a[k]) * u;
+  }
+  return s[s.length - 1][k];
+};
+const total = (k) => { let v = 0; for (let fno = 0; fno <= last; fno++) v += at(k, fno); return v; };
+const T = Object.fromEntries(['blkMB', 'revMB', 'readMs', 'xorMs', 'decodeMs', 'pairMs', 'undoMs', 'txs', 'outputs', 'inputs', 'funding', 'spent'].map((k) => [k, total(k)]));
+const h = (x) => (x / 3.6e6).toFixed(2);
+const G = (x) => (x / 1e9).toFixed(2);
+const summary = {
+  files: all.length, sampled: sample.length,
+  data: { blkGB: +(T.blkMB / 1e3).toFixed(1), revGB: +(T.revMB / 1e3).toFixed(1) },
+  counts: { txs: Math.round(T.txs), outputs: Math.round(T.outputs), inputs: Math.round(T.inputs), fundingRows: Math.round(T.funding), spendingRows: Math.round(T.spent) },
+  singleCoreHours: { read: +h(T.readMs), xor: +h(T.xorMs), decodeBlocks: +h(T.decodeMs), pairUndo: +h(T.pairMs), decodeUndo: +h(T.undoMs), cpuTotal: +h(T.xorMs + T.decodeMs + T.pairMs + T.undoMs) },
+  // raw row bytes for two designs, before any storage-engine overhead
+  indexGB: {
+    historyOnly: +G((T.funding + T.spent) * 12),       // script-hash prefix 8 B + height 4 B, and outpoint prefix 8 B + height 4 B
+    withValues: +G((T.funding + T.spent) * 20),        // the same plus an 8 B amount, so a balance needs no node call
+  },
+};
+console.log(JSON.stringify(summary, null, 1));
+const out = arg('json', null);
+if (out) writeFileSync(out, JSON.stringify({ measuredAt: new Date().toISOString(), dir, sample: rows, summary }, null, 1) + '\n');
+process.exit(0);

package/scripts/browser-check.mjs ADDED Viewed

@@ -0,0 +1,286 @@
+// Look at the page with a real browser, and ask the vision model what it sees.
+//
+// Two kinds of evidence, deliberately kept apart:
+//   HARD   -- pixels sampled in the page by Runtime.evaluate, and element rects. The
+//            canvas is same-origin, so getImageData answers "did anything actually get
+//            painted, and in which colours" without any judgement at all.
+//   SOFT   -- a screenshot handed to the local vision model (qwen3.8 on the bench host).
+//            Good for "does this read as a block being filled", "is the legend legible",
+//            "do these overlap". Bad at precise numbers. Where the two disagree, the
+//            pixels win, and the report says so.
+//
+// Zero dependencies: Chromium speaks CDP over a plain WebSocket, and Node 22 ships one.
+//
+//   BLOCKYARD_BASE=https://<lan>:8088 [BROWSER_CDP=http://127.0.0.1:9333] \
+//   [VISION_BASE=http://198.51.100.20:8888 VISION_MODEL=<model-id>] \
+//     node scripts/browser-check.mjs [overview|mining]
+import { execFileSync } from 'node:child_process';
+const BASE = process.env.BLOCKYARD_BASE;
+const CDP = process.env.BROWSER_CDP ?? 'http://127.0.0.1:9333';
+const VISION_BASE = process.env.VISION_BASE;   // the local vision model, e.g. vLLM on the bench host
+const VISION_MODEL = process.env.VISION_MODEL ?? 'qwen3.8-flash-next';
+const PAGE = process.argv[2] ?? 'mining';
+if (!BASE) {
+  console.log('usage: BLOCKYARD_BASE=https://<address>:8088 node scripts/browser-check.mjs [overview|mining]');
+  console.log('       needs a headless chromium with --remote-debugging-port and --ignore-certificate-errors');
+  process.exit(2);
+}
+const URL = `${BASE}/#${PAGE}`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// ------------------------------------------------------------------ CDP client
+const targets = JSON.parse(await (await fetch(`${CDP}/json/list`)).text());
+const page = targets.find((t) => t.type === 'page');
+if (!page) { console.log('no page target; is chromium running headless with --remote-debugging-port?'); process.exit(1); }
+const ws = new WebSocket(page.webSocketDebuggerUrl);
+await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+let nextId = 1;
+const pending = new Map();
+const events = [];
+const consoleErrors = [];
+const exceptions = [];
+ws.onmessage = (ev) => {
+  const msg = JSON.parse(ev.data);
+  if (msg.id && pending.has(msg.id)) { pending.get(msg.id)(msg); pending.delete(msg.id); }
+  if (msg.method) {
+    events.push(msg.method);
+    if (msg.method === 'Runtime.exceptionThrown') {
+      exceptions.push(msg.params.exceptionDetails?.exception?.description ?? msg.params.exceptionDetails?.text);
+    }
+    if (msg.method === 'Runtime.consoleAPICalled' && ['error', 'warning'].includes(msg.params.type)) {
+      consoleErrors.push((msg.params.args ?? []).map((a) => a.value ?? a.description ?? a.type).join(' '));
+    }
+    if (msg.method === 'Log.entryAdded' && ['error', 'warning'].includes(msg.params.entry.level)) {
+      consoleErrors.push(`[${msg.params.entry.source}] ${msg.params.entry.text}`.slice(0, 200));
+    }
+  }
+};
+const send = (method, params = {}) => new Promise((res) => {
+  const id = nextId++;
+  pending.set(id, (msg) => res(msg.result ?? msg.error ?? {}));
+  ws.send(JSON.stringify({ id, method, params }));
+});
+await send('Page.enable');
+await send('Runtime.enable');
+await send('Log.enable');
+await send('Network.enable');
+await send('Emulation.setDeviceMetricsOverride', { width: 1440, height: 1900, deviceScaleFactor: 1, mobile: false });
+const loadWait = new Promise((res) => {
+  const wait = (ev) => { if (ev === 'Page.loadEventFired') res(true); };
+  const orig = ws.onmessage;
+  ws.onmessage = (m) => { orig(m); wait(JSON.parse(m.data).method); };
+  setTimeout(() => res(false), 25_000);
+});
+// Cache-bust deliberately: Page.navigate to a URL that differs from the current one only
+// in its #fragment is a NO-OP, so reusing a still-open browser silently re-measures the
+// document that was loaded before the last deploy. Every "old code path" and "blank
+// canvas" reading this harness ever produced against a warm browser was this.
+//
+// ...and the query-string bust is NOT enough on its own. It changes the
+// DOCUMENT url only; the ES MODULES the document imports keep their own urls,
+// so a warm browser serves them from cache and the harness measures the
+// PREVIOUS build's JavaScript against the current build's HTML. Measured
+// 2026-09-10: the viewer's projection was replaced outright, the server was
+// confirmed to be serving the new file, every unit test agreed -- and the
+// screenshot kept showing the old camera, from a headless shell that had been
+// up 48 hours. Disabling the network cache is what makes this harness
+// trustworthy for a JS change at all.
+await send('Network.enable', {});
+await send('Network.setCacheDisabled', { cacheDisabled: true });
+const busted = URL + (URL.includes('?') ? '&' : '?') + 't=' + Date.now();
+await send('Page.navigate', { url: busted });
+const loaded = await loadWait;
+// A document can load and still not be the app (a redirect to the login page loads
+// perfectly well). Assert the shell is here before judging anything drawn inside it.
+// NOTE what this does NOT check: document.body.firstChild. Leading whitespace is a text
+// node in every ordinary document, and an earlier throwaway probe asserted on exactly
+// that and "proved" the app rendered nothing when it had rendered fine all along.
+const shell = await send('Runtime.evaluate', {
+  expression: `JSON.stringify({ bodyKids: document.body.children.length, nav: !!document.querySelector('#nav'), login: location.pathname.startsWith('/login') })`,
+  returnByValue: true,
+}).then((r) => JSON.parse(r?.result?.value || '{}'));
+if (!shell.bodyKids || !shell.nav || shell.login) {
+  console.error(`not the app: bodyKids=${shell.bodyKids} nav=${shell.nav} path=${shell.login ? '/login' : '?'}`);
+  await browser.close();
+  process.exit(1);
+}
+// The mining page asks the node for a block template on load (~1.3 s) and the map tweens
+// for ~520 ms after that. Judge nothing before it has settled.
+//
+// AND switch the SPA to the requested page the way a user does — by clicking the nav
+// button. Loading `/#mining` in this harness has repeatedly measured the OVERVIEW instead
+// (every canvas zeroSized or from the wrong page), because the hash route is applied
+// inside boot's async tail and a hash-only change on a warm document is no kind of
+// navigation at all (rule 25). Clicking is deterministic; hoping for the hash is not.
+await sleep(3000);
+if (PAGE !== 'overview') {
+  await send('Runtime.evaluate', { expression: `document.querySelector('#nav button[data-page=${JSON.stringify(PAGE)}]')?.click()` });
+}
+await sleep(4000);
+// Prove we are on the page we claim to be measuring, before judging a single pixel.
+const onPage = JSON.parse(await send('Runtime.evaluate', {
+  expression: `(() => { const on = document.querySelector('.page.on'); return JSON.stringify({page: on?.dataset?.page ?? null, hash: location.hash}) })()`,
+  returnByValue: true,
+}).then((r) => r?.result?.value ?? '{}'));
+if (onPage.page && onPage.page !== PAGE) {
+  console.error(`not on #${PAGE}: the app is showing "${onPage.page}". The page switch failed; every measurement below would describe the wrong page.`);
+  ws.close();
+  process.exit(1);
+}
+// Refuse to review a page that did not load. Without this guard a broken invocation
+// (an empty BLOCKYARD_BASE once sent it to https://:8088) produced a blank screenshot,
+// the vision model confidently reported "the page is completely empty", and that read
+// would have been believed. Check the document before asking anyone to judge it.
+const sanity = await send('Runtime.evaluate', {
+  expression: `JSON.stringify({
+    href: location.href,
+    title: document.title,
+    nav: !!document.getElementById('nav'),
+    nodes: document.body ? document.body.childElementCount : 0,
+    text: document.body ? document.body.innerText.replace(/\\s+/g,' ').slice(0,120) : ''
+  })`,
+  returnByValue: true,
+});
+let sanityObj = {};
+try { sanityObj = JSON.parse(sanity.result?.value ?? '{}'); } catch { /* reported below */ }
+if (!sanityObj.nav || !sanityObj.nodes) {
+  console.log(`\n== ${URL} ==`);
+  console.log(`ABORT: nothing to look at. href=${sanityObj.href} title=${JSON.stringify(sanityObj.title)} bodyChildren=${sanityObj.nodes}`);
+  console.log('The browser reached a document with no app in it. Check BLOCKYARD_BASE (and that the service is up) before reading anything into a screenshot.');
+  if (consoleErrors.length) consoleErrors.slice(0, 5).forEach((e) => console.log(`   ! ${e}`));
+  ws.close();
+  process.exit(3);
+}
+// ------------------------------------------------------- HARD: measure the page
+const PROBE = () => {
+  const out = { canvases: {}, rects: {}, cssom: {}, text: {}, scroll: {} };
+  const px = (id, label) => {
+    const c = document.getElementById(id);
+    if (!(c instanceof HTMLCanvasElement)) { out.canvases[id] = { missing: true }; return; }
+    const r = c.getBoundingClientRect();
+    out.rects[id] = { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) };
+    if (!r.width || !r.height) { out.canvases[id] = { zeroSized: true }; return; }
+    let ctx;
+    try { ctx = c.getContext('2d', { willReadFrequently: true }); } catch { out.canvases[id] = { noContext: true }; return; }
+    const dpr = c.width / r.width || 1;
+    const data = ctx.getImageData(0, 0, c.width, c.height).data;
+    const colours = new Map();
+    let lit = 0;
+    for (let i = 0; i < data.length; i += 4 * 17) {          // sampled every 17 px, fast and enough
+      const a = data[i + 3];
+      if (a < 8) continue;
+      const key = `${data[i] >> 3},${data[i + 1] >> 3},${data[i + 2] >> 3}`;
+      colours.set(key, (colours.get(key) ?? 0) + 1);
+      if (data[i] + data[i + 1] + data[i + 2] > 200) lit++;
+    }
+    const top = [...colours.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6);
+    out.canvases[id] = {
+      sampled: label, dpr: +dpr.toFixed(2),
+      // If nothing painted, say what the drawing code left behind: __hasData is set by
+      // paint(), __rects by the treemap layout. hasData=true with 0 colours means it drew
+      // and something wiped it; false means the draw never ran at all.
+      hasData: !!c.__hasData, rects: c.__rects?.size ?? 0, cells: c.__cells ?? 0,
+      backing: `${c.width}x${c.height}`,
+      distinctColours: colours.size, litPixels: lit,
+      topColourShares: top.map(([k, v]) => `${k}:${(100 * v / [...colours.values()].reduce((a, b) => a + b, 0)).toFixed(0)}%`),
+      paintedPixelsPct: +((100 * [...colours.values()].reduce((a, b) => a + b, 0)) / (data.length / (4 * 17))).toFixed(1),
+    };
+  };
+  ['gnMempoolTreemap', 'ovGnTreemap', 'ovTrain', 'ovMpChart', 'ovFeeChart', 'mnFeeLandscape']
+    .forEach((id) => px(id, document.getElementById(id) ? 'present' : 'absent'));
+  // CSSOM applied? If the CSP/CSSOM conversion is broken the marks have no background.
+  const dots = [...document.querySelectorAll('.bdot')].slice(0, 6);
+  out.cssom.bdotBackgrounds = dots.map((d) => getComputedStyle(d).backgroundColor);
+  const cards = [...document.querySelectorAll('.bcard')].slice(0, 8);
+  out.cssom.cardPoolVars = cards.map((c) => getComputedStyle(c).getPropertyValue('--pool').trim() || '(none)');
+  const rail = document.querySelector('.rail');
+  out.cssom.railDuration = rail ? getComputedStyle(rail).animationDuration : '(no rail)';
+  const bar = document.querySelector('.bfill span');
+  out.cssom.fillWidth = bar ? `${getComputedStyle(bar).width} (data-w=${bar.dataset?.w ?? '-'})` : '(no fill)';
+  // Distinguish "we never set it" from "the browser computed something else": inline CSSOM
+  // values are what applyMiningStyles writes, computed values are what actually renders.
+  out.cssom.cardInlinePool = [...document.querySelectorAll('.bcard')].slice(0, 4)
+    .map((c) => `${c.style.getPropertyValue('--pool') || '(unset)'}|computed:${getComputedStyle(c).getPropertyValue('--pool').trim() || '(none)'}`);
+  // Card geometry: overlapping cards is the classic flexbox overflow failure.
+  const flows = [...document.querySelectorAll('.flow, .flowwrap')];
+  out.rects.flowOverflow = flows.map((f) => ({ scrollW: f.scrollWidth, clientW: f.clientWidth, clipped: f.scrollWidth > f.clientWidth + 2 }));
+  const txt = (id) => { const el = document.getElementById(id); const s = (el?.textContent ?? '').trim(); return s.length > 160 ? `${s.slice(0, 160)}…` : s; };
+  ['ovFeesCard', 'ovMpVsBlock', 'ovMpVsBlockKv', 'ovMempoolCard', 'ovGnTreemapNote', 'gnMempoolNote', 'mnPools', 'ovCaveats']
+    .forEach((id) => { out.text[id] = txt(id); });
+  out.scroll = { bodyH: document.body.scrollHeight, winH: innerHeight };
+  return out;
+};
+const probed = await send('Runtime.evaluate', { expression: `(${PROBE.toString()})()`, returnByValue: true });
+const hard = probed.result?.value ?? { error: probed.error ?? 'no value' };
+const shot = await send('Page.captureScreenshot', { format: 'png' });
+const png = shot.data ?? null;
+// ------------------------------------------------------- SOFT: ask the vision model
+let soft = null;
+if (png && VISION_BASE) {
+  const prompt = [
+    'You are reviewing a screenshot of a self-hosted Bitcoin node monitor (dark theme).',
+    `This is the "${PAGE}" page. Report only what you can see, and say "cannot tell" rather than guessing.`,
+    'Answer each numbered question in one short sentence:',
+    '1. Are any large areas blank, empty boxes, or placeholder dashes? Name them.',
+    '2. Is there a treemap of rectangles (a block-space map)? Do the rectangles vary in size and colour, and is any large unfilled band visible?',
+    '3. Is there a row of block cards? Read the height numbers you can see, left to right, and say whether one is marked as current.',
+    '4. Is any text unreadable because of low contrast, overlap, or clipping?',
+    '5. Does anything look obviously broken (misaligned, clipped, overlapping, wrong colours)?',
+    '6. What is the single most damaging visual problem on this page, if any?',
+  ].join('\n');
+  const res = await fetch(`${VISION_BASE}/v1/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      model: VISION_MODEL,
+      max_tokens: 700,
+      temperature: 0.2,
+      messages: [{ role: 'user', content: [
+        { type: 'text', text: prompt },
+        { type: 'image_url', image_url: { url: `data:image/png;base64,${png}` } },
+      ] }],
+    }),
+  });
+  const j = await res.json().catch(() => null);
+  const m = j?.choices?.[0]?.message ?? {};
+  // This deployment is a reasoning model: it can answer with content=null and the text in
+  // `reasoning`. Reading only `content` reports a confident-looking empty review, which is
+  // the worst possible failure for a check whose whole job is to notice problems.
+  soft = m.content ?? m.reasoning ?? JSON.stringify(j).slice(0, 400);
+}
+// ------------------------------------------------------------------- report
+console.log(`\n== ${URL} ${loaded ? '' : '(load event not seen)'} ==`);
+console.log(`console errors/warnings: ${consoleErrors.length}`);
+consoleErrors.slice(0, 8).forEach((e) => console.log(`   ! ${e}`));
+if (exceptions.length) { console.log(`uncaught exceptions: ${exceptions.length}`); exceptions.slice(0, 5).forEach((e) => console.log(`   !! ${String(e).split('\n')[0]}`)); }
+console.log('\n-- HARD: canvas pixels sampled in the page --');
+for (const [id, v] of Object.entries(hard.canvases ?? {})) console.log(`   ${id.padEnd(18)} ${JSON.stringify(v)}`);
+console.log('-- HARD: CSSOM + geometry --');
+console.log('   ', JSON.stringify(hard.cssom));
+console.log('   flow:', JSON.stringify(hard.rects?.flowOverflow));
+console.log('-- HARD: text on the page --');
+for (const [id, v] of Object.entries(hard.text ?? {})) if (v) console.log(`   ${id.padEnd(16)}: ${String(v).slice(0, 120)}`);
+console.log(`   page height ${hard.scroll?.bodyH} vs window ${hard.scroll?.winH}`);
+if (png) {
+  const fs = await import('node:fs');
+  const path = `/tmp/browser-check-${PAGE}.png`;
+  fs.writeFileSync(path, Buffer.from(png, 'base64'));
+  console.log(`\nscreenshot: ${path} (${Math.round(png.length * 3 / 4 / 1024)} KB)`);
+}
+console.log(`\n-- SOFT: ${VISION_MODEL} on the screenshot --`);
+console.log(soft ? soft.split('\n').map((l) => `   ${l.trim()}`).filter((l) => l.trim()).join('\n') : '   (no VISION_BASE set, so the screenshot was not reviewed)');
+console.log('\nHARD evidence is measured in the page; SOFT is a model\'s reading. Where they disagree, the pixels win.');
+ws.close();

package/scripts/check.js ADDED Viewed

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// CHECK A NODE BEFORE RUNNING AGAINST IT: the RPC server answers, the credentials work, the
+// chain is the one configured, the indexes the explorer needs are there, the block files can be
+// read (the address index is built from them), the node's log is where it should be, and an
+// address index, if configured, is readable, writable and not far behind.
+//
+//   npm run check                 # every node in config/local.json
+//   node scripts/check.js --node <id>
+//
+// Prints one line per check and exits 1 if anything FAILED. `npm run setup` runs the same checks
+// on the answers it is given before it writes config/local.json. The checks are a function
+// (runChecks) so they can be tested against a stub node, with the printing kept out here.
+import { existsSync, statSync, readdirSync, accessSync, readFileSync, realpathSync, constants as FS } from 'node:fs';
+import path from 'node:path';
+import { loadConfig, configProblems, resolveCookie } from '../server/config.js';
+import { RpcClient } from '../server/rpc/client.js';
+import { MAGIC, xorKey, readChainFile, records } from '../server/chain/blockfile.js';
+import { c, checkLine } from './ui.js';
+import { fileURLToPath } from 'node:url';
+const QUIET = { info() {}, warn() {}, error() {}, debug() {} };
+/** The RPC client a check talks through; setup and the tests pass their own. */
+export function clientFor(node, cfg) {
+  return new RpcClient(node, { ...(cfg?.rpc ?? {}), ...(node.rpc ?? {}) }, { log: QUIET });
+}
+const CORE_VERSION_MIN = 250000;   // getblock verbosity 3 (the follower's one call) arrived in 25.0
+/**
+ * Every check for one node. `rpc` is anything with batch(calls) -> [{ok, result, error}].
+ * Returns { ok, checks: [{ name, status: 'ok'|'warn'|'fail'|'info', detail }], facts }.
+ */
+export async function runChecks(node, { rpc, fs = { existsSync, statSync, readdirSync, accessSync, readFileSync }, readBlockFile = readChainFile } = {}) {
+  const checks = [];
+  const facts = {};
+  const add = (name, status, detail) => { checks.push({ name, status, detail }); return status; };
+  // credentials
+  const cred = resolveCookie(node);
+  if (!cred) add('credentials', 'fail', `no cookie file found under ${node.datadir ?? '(no datadir)'} and no rpcUser/rpcPassword`);
+  else add('credentials', 'ok', cred.source === 'config' ? `rpcUser "${cred.user}" from the config` : `cookie ${cred.source}`);
+  // the RPC server
+  // every call is timed: how fast the node answers is half of what an install needs to know
+  const ms = (t0) => `${Date.now() - t0 >= 1000 ? `${((Date.now() - t0) / 1000).toFixed(1)} s` : `${Date.now() - t0} ms`}`;
+  const one = async (method, params = [], timeoutMs = 20000) => {
+    const t0 = Date.now();
+    try { const [r] = await rpc.batch([{ method, params }], { timeoutMs }); r.ms = ms(t0); return r; }
+    catch (err) { return { ok: false, ms: ms(t0), error: { message: err.message, kind: err.kind } }; }
+  };
+  const info = await one('getblockchaininfo');
+  if (!info.ok) {
+    add('rpc', 'fail', `${node.rpcUrl}: ${info.error.message}`);
+    return { ok: false, checks, facts };
+  }
+  const chain = info.result.chain;
+  facts.chain = chain; facts.blocks = info.result.blocks; facts.headers = info.result.headers;
+  add('rpc', 'ok', `${node.rpcUrl} answers in ${info.ms}: chain ${chain}, block ${info.result.blocks.toLocaleString()} of ${info.result.headers.toLocaleString()} headers${info.result.initialblockdownload ? ', still in initial block download' : ''}${info.result.pruned ? ', PRUNED' : ''}`);
+  if (node.chainHint && node.chainHint !== chain) add('chain', 'fail', `config says chainHint "${node.chainHint}" but the node is on "${chain}"`);
+  if (info.result.pruned) add('pruned', 'fail', 'a pruned node has discarded old block files; the address index needs every one of them');
+  const net = await one('getnetworkinfo');
+  if (net.ok) {
+    facts.version = net.result.version; facts.subversion = net.result.subversion;
+    const v = net.result.version;
+    add('version', v >= CORE_VERSION_MIN ? 'ok' : 'fail', `${net.result.subversion} (${v})${v < CORE_VERSION_MIN ? ` -- the address index follower needs getblock verbosity 3, Bitcoin Core 25.0 or later` : ''}`);
+  } else add('version', 'warn', `getnetworkinfo: ${net.error.message}`);
+  const idx = await one('getindexinfo');
+  if (idx.ok) {
+    const tx = idx.result.txindex;
+    if (!tx) add('txindex', 'fail', 'txindex is off: the explorer cannot look a confirmed transaction up by id (set txindex=1 in bitcoin.conf)');
+    else add('txindex', tx.synced ? 'ok' : 'warn', tx.synced ? `synced to ${tx.best_block_height.toLocaleString()}` : `still building (${tx.best_block_height.toLocaleString()} of ${info.result.blocks.toLocaleString()})`);
+    const cs = idx.result.coinstatsindex;
+    add('coinstatsindex', cs ? (cs.synced ? 'ok' : 'warn') : 'info', cs ? (cs.synced ? 'synced: the Chain page has UTXO figures' : 'still building') : 'off: the Chain page marks UTXO figures unindexed (optional)');
+  } else add('txindex', 'warn', `getindexinfo: ${idx.error.message}`);
+  // the explorer's one heavy need from the node: a block with every input's prevout
+  const best = await one('getbestblockhash');
+  if (best.ok) {
+    const blk = await one('getblock', [best.result, 3], 120_000);
+    if (blk.ok) {
+      const withPrevout = blk.result.tx.slice(1, 4).every((t) => t.vin.every((v) => v.prevout));
+      const slow = blk.ms.endsWith(' s') && parseFloat(blk.ms) >= 5;
+      add('getblock 3', withPrevout ? (slow ? 'warn' : 'ok') : 'fail', withPrevout ? `the tip block decodes with prevouts (${blk.result.tx.length.toLocaleString()} transactions) in ${blk.ms}${slow ? ' -- slow: the block files are on a slow disk, or the node is busy' : ''}` : 'the node answered verbosity 3 without prevouts');
+    } else add('getblock 3', 'fail', `getblock <tip> 3: ${blk.error.message} -- the address index follower cannot run`);
+  }
+  // the mempool, verbose: the monitor's heaviest regular read, every 20 s; how long the node takes
+  // over it is what decides whether the block-space board fills
+  const mp = await one('getrawmempool', [true], 120_000);
+  if (mp.ok) {
+    const n = Object.keys(mp.result).length;
+    const slow = mp.ms.endsWith(' s') && parseFloat(mp.ms) >= 10;
+    add('mempool', slow ? 'warn' : 'ok', `${n.toLocaleString()} transactions, verbose, in ${mp.ms}${slow ? ' -- slow: the board and the block being built will lag behind this' : ''}`);
+  } else add('mempool', 'warn', `getrawmempool verbose: ${mp.error.message} after ${mp.ms}`);
+  const addr = await one('getaddresstxids', [{ addresses: [] }]);
+  add('address index rpc', 'info', addr.ok ? 'the node has insight-style address RPCs (unused: BlockYard keeps its own index)' : 'the node has no address index, as expected of Bitcoin Core; BlockYard builds its own');
+  // the data directory: block files and the log
+  if (!node.datadir) add('datadir', 'fail', 'no datadir configured: the address index is built from the node\'s block files');
+  else if (!fs.existsSync(node.datadir)) add('datadir', 'fail', `${node.datadir} does not exist on this machine`);
+  else {
+    const blocksDir = path.join(node.datadir, 'blocks');
+    let names = null;
+    try { names = fs.readdirSync(blocksDir); } catch (err) { add('block files', 'fail', `${blocksDir}: ${err.message}`); }
+    if (names) {
+      const blk = names.filter((f) => /^blk\d{5}\.dat$/.test(f)).sort();
+      const rev = names.filter((f) => /^rev\d{5}\.dat$/.test(f)).sort();
+      const xor = names.includes('xor.dat');
+      facts.blockFiles = blk.length; facts.undoFiles = rev.length;
+      if (!blk.length) add('block files', 'fail', `${blocksDir} holds no blk*.dat`);
+      else {
+        let bytes = 0;
+        for (const f of [...blk, ...rev]) { try { bytes += fs.statSync(path.join(blocksDir, f)).size; } catch { /* counted as far as readable */ } }
+        facts.blockBytes = bytes;
+        add('block files', rev.length === blk.length ? 'ok' : 'warn', `${blk.length} block files and ${rev.length} undo files, ${(bytes / 1e9).toFixed(1)} GB${xor ? ', XOR-obfuscated (xor.dat present)' : ''}${rev.length !== blk.length ? ' -- every block file needs its undo file' : ''}`);
+        // prove they can be read: the first file's first record is the genesis block
+        try {
+          const key = xorKey(blocksDir);
+          const buf = readBlockFile(path.join(blocksDir, blk[0]), key);
+          const first = records(buf, MAGIC[chain] ?? MAGIC.main, 0, key).next().value;
+          const genesis = first && first.body.subarray(4, 36).every((b) => b === 0);
+          add('read a block', genesis ? 'ok' : 'fail', genesis ? `${blk[0]} opens and its first record is the genesis block` : `${blk[0]} opens but its first record is not a ${chain} genesis block: wrong chain, or a key this reader does not know`);
+        } catch (err) { add('read a block', 'fail', `${blk[0]}: ${err.message}`); }
+      }
+    }
+    const logs = [path.join(node.datadir, chain === 'main' ? '' : ({ test: 'testnet3', testnet4: 'testnet4', signet: 'signet', regtest: 'regtest' }[chain] ?? chain), 'debug.log')];
+    const log = logs.find((f) => fs.existsSync(f));
+    if (log) { const st = fs.statSync(log); facts.logFile = log; add('node log', 'info', `${log} (${(st.size / 1e6).toFixed(1)} MB) -- found; not parsed on Bitcoin Core, and not needed`); }
+    else add('node log', 'info', `no debug.log under ${node.datadir} -- not needed`);
+  }
+  // an address index, if there is one
+  if (node.addressIndex) {
+    const dir = node.addressIndex;
+    const manifest = path.join(dir, 'manifest.json');
+    if (!fs.existsSync(manifest)) add('address index', node.addressIndexBuild === 'manual' ? 'warn' : 'info', `${dir}: not built yet${node.addressIndexBuild === 'manual' ? ` (node scripts/index-build.js --out ${dir})` : ' -- BlockYard builds it when it starts'}`);
+    else {
+      try {
+        const m = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+        const behind = info.result.blocks - m.tip.height;
+        facts.indexTip = m.tip.height;
+        add('address index', behind > 200 ? 'warn' : 'ok', `${dir}: built at ${m.builtAt ?? '?'} to block ${m.tip.height.toLocaleString()}, ${behind.toLocaleString()} behind the node${behind > 200 ? ' (the follower catches up 50 blocks a poll)' : ''}`);
+      } catch (err) { add('address index', 'fail', `${manifest}: ${err.message}`); }
+      try { fs.accessSync(dir, FS.W_OK); add('index writable', 'ok', 'the follower can write live.log and layers/ there'); }
+      catch { add('index writable', 'fail', `${dir} is not writable by this user; the follower writes live.log and layers/ inside it`); }
+    }
+  }
+  return { ok: !checks.some((c) => c.status === 'fail'), checks, facts };
+}
+export function printChecks(label, { ok, checks }) {
+  console.log(`\n  ${c.bold(label)}`);
+  for (const ch of checks) console.log(checkLine(ch.status, ch.name, ch.detail));
+  console.log(ok ? `    ${c.ok(c.bold('everything this needs is there'))}` : `    ${c.bad(c.bold('something this needs is missing'))}${c.dim(' (the ✗ lines say what)')}`);
+}
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) {
+  const arg = (name) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : null; };
+  const cfg = loadConfig();
+  for (const p of configProblems()) console.log(checkLine('fail', 'config', p));
+  const nodes = arg('node') ? cfg.nodes.filter((n) => n.id === arg('node')) : cfg.nodes;
+  if (!nodes.length) { console.log(`no node ${arg('node') ?? ''} in ${cfg.__configFile ?? 'the configuration'}`); process.exit(2); }
+  let allOk = configProblems().length === 0;
+  for (const node of nodes) {
+    const r = await runChecks(node, { rpc: clientFor(node, cfg) });
+    printChecks(`node "${node.id}" (${node.label ?? ''})`, r);
+    allOk &&= r.ok;
+  }
+  process.exit(allOk ? 0 : 1);
+}