blockyard 0.0.1 → 0.1.0

package/scripts/decode-check.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Replay whole blocks from a live node through server/chain/tx.js and compare every field against the
+// node's own verbose decoding. A decoder is only as good as the last time it was checked against Core.
+//
+//   node scripts/decode-check.js [--node <id>] [--blocks N] [--from <height>] [--heights h1,h2,...]
+//
+// Fetches each block twice, as raw bytes (getblock <hash> 0) and as Core's JSON (getblock <hash> 2),
+// decodes the bytes, and reports every disagreement plus the count of each script type seen. Read-only
+// RPC, through the same client and lane the monitor uses.
+import { loadConfig } from '../server/config.js';
+import { RpcClient } from '../server/rpc/client.js';
+import { decodeBlock } from '../server/chain/tx.js';
+
+const arg = (name, def) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : def; };
+const cfg = loadConfig();
+const node = cfg.nodes.find((n) => n.id === arg('node', null)) ?? cfg.nodes[0];
+const quiet = { info() {}, warn() {}, error() {}, debug() {} };
+const rpc = new RpcClient(node, { ...(cfg.rpc ?? {}), ...(node.rpc ?? {}) }, { log: quiet });
+const call = async (method, params, timeoutMs = 120_000) => {
+  const [r] = await rpc.batch([{ method, params }], { key: `decode-check:${method}:${params[0]}`, priority: 5, maxWaitMs: 120_000, timeoutMs });
+  if (!r.ok) throw new Error(`${method}: ${r.error?.message}`);
+  return r.result;
+};
+
+const info = await call('getblockchaininfo', []);
+const count = Math.max(1, Number(arg('blocks', 3)));
+const from = Number(arg('from', info.blocks - count + 1));
+const sat = (btc) => Math.round(btc * 1e8);
+const mismatches = [];
+const types = {};
+let txs = 0, inputs = 0, outputs = 0, bytes = 0, decodeMs = 0;
+const differ = (where, got, want) => { if (got !== want && mismatches.length < 50) mismatches.push(`${where}: decoded ${JSON.stringify(got)}, node ${JSON.stringify(want)}`); return got !== want; };
+
+const heights = arg('heights', null) ? arg('heights').split(',').map(Number) : Array.from({ length: count }, (_, i) => from + i);
+for (const h of heights) {
+  const hash = await call('getblockhash', [h]);
+  const raw = await call('getblock', [hash, 0]);
+  const want = await call('getblock', [hash, 2], 300_000);
+  const buf = Buffer.from(raw, 'hex');
+  const t0 = performance.now();
+  const got = decodeBlock(buf, info.chain);
+  decodeMs += performance.now() - t0;
+  bytes += buf.length;
+  for (const k of ['hash', 'version', 'previousblockhash', 'merkleroot', 'time', 'bits', 'nonce', 'size', 'nTx']) differ(`block ${h} ${k}`, got[k], want[k]);
+  want.tx.forEach((w, i) => {
+    const g = got.tx[i];
+    const at = `block ${h} tx ${i} (${w.txid.slice(0, 12)})`;
+    txs++;
+    for (const k of ['txid', 'hash', 'version', 'size', 'vsize', 'weight', 'locktime']) differ(`${at} ${k}`, g[k], w[k]);
+    differ(`${at} vin count`, g.vin.length, w.vin.length);
+    w.vin.forEach((wi, j) => {
+      const gi = g.vin[j] ?? {};
+      inputs++;
+      if (wi.coinbase != null) differ(`${at} vin ${j} coinbase`, gi.coinbase, wi.coinbase);
+      else {
+        differ(`${at} vin ${j} txid`, gi.txid, wi.txid);
+        differ(`${at} vin ${j} vout`, gi.vout, wi.vout);
+        differ(`${at} vin ${j} scriptSig`, gi.scriptSig?.hex, wi.scriptSig?.hex);
+      }
+      differ(`${at} vin ${j} sequence`, gi.sequence, wi.sequence);
+      differ(`${at} vin ${j} witness`, JSON.stringify(gi.txinwitness ?? null), JSON.stringify(wi.txinwitness ?? null));
+    });
+    differ(`${at} vout count`, g.vout.length, w.vout.length);
+    w.vout.forEach((wo, j) => {
+      const go = g.vout[j] ?? { scriptPubKey: {} };
+      outputs++;
+      types[wo.scriptPubKey.type] = (types[wo.scriptPubKey.type] ?? 0) + 1;
+      differ(`${at} vout ${j} value`, go.value_sat, sat(wo.value));
+      differ(`${at} vout ${j} n`, go.n, wo.n);
+      differ(`${at} vout ${j} hex`, go.scriptPubKey.hex, wo.scriptPubKey.hex);
+      differ(`${at} vout ${j} type`, go.scriptPubKey.type, wo.scriptPubKey.type);
+      differ(`${at} vout ${j} address`, go.scriptPubKey.address ?? null, wo.scriptPubKey.address ?? null);
+    });
+  });
+}
+
+console.log(`${node.id} (${info.chain}): ${heights.length} blocks (${heights[0]}..${heights[heights.length - 1]}), ${txs} transactions, ${inputs} inputs, ${outputs} outputs, ${(bytes / 1e6).toFixed(1)} MB`);
+console.log(`decoded in ${decodeMs.toFixed(0)} ms (${(bytes / 1e6 / (decodeMs / 1000)).toFixed(1)} MB/s, ${(txs / (decodeMs / 1000)).toFixed(0)} tx/s)`);
+console.log('script types:', JSON.stringify(types));
+console.log(mismatches.length ? `MISMATCHES (${mismatches.length}${mismatches.length >= 50 ? '+' : ''}):\n  ${mismatches.join('\n  ')}` : 'every field matches the node');
+process.exit(mismatches.length ? 1 : 0);

package/scripts/doc-counts.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// One source of truth for the test count the docs quote.
+//
+// Why this exists as a script rather than as a grep in a test: the documented
+// count drifted out of sync three times on 2026-09-08, and each time the fix was
+// a sed against a string a previous sed had already rewritten, so the replacement
+// matched nothing and the docs went on asserting a stale number. The previous
+// guard compared README against AGENTS.md, which only proves two documents are
+// wrong *together* — it never looked at the suite. 183 vs 180 is exactly that
+// failure, found by hand on 2026-09-09.
+//
+// So: count what the suite declares, and make the docs match it.
+//
+// How the count is derived, and why it is the same number `node --test` prints:
+// every test in this repo is declared at module top level with `test('name', …)`.
+// A nested declaration (`t.test(…)`, or an indented `test(`) would make the two
+// numbers disagree, so the scanner reports nested declarations separately and
+// test/doc-counts.test.js fails loudly if any appear — a scanner that silently
+// undercounts is the same class of bug as the sed that matched nothing.
+//
+//   node scripts/doc-counts.js          # print the number
+//   node scripts/doc-counts.js --check  # exit 1 if the docs disagree
+//   node scripts/doc-counts.js --fix    # rewrite the docs' number
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const DECL = /^(?:test|test\.skip|test\.todo|test\.only)\s*\(/;
+
+/** Test declarations per file: top-level (counted) and nested (a scanner gap). */
+export function scanTests({ root = ROOT, dir = 'test' } = {}) {
+  const base = path.join(root, dir);
+  const rel = (f) => path.relative(root, f).split(path.sep).join('/');   // keyed with '/', on every platform
+  const files = fs.readdirSync(base, { recursive: true, withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.test.js'))
+    .map((e) => path.join(e.parentPath ?? e.path, e.name))
+    .sort();
+  const out = { total: 0, nested: [], perFile: {}, files: files.length };
+  for (const f of files) {
+    let top = 0;
+    for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+      const trimmed = line.trimStart();
+      if (!DECL.test(trimmed)) continue;
+      // Indented means it sits inside another test's body or a helper: a subtest.
+      if (/^\s/.test(line)) out.nested.push(`${rel(f)}: ${trimmed.slice(0, 60)}`);
+      else top += 1;
+    }
+    out.perFile[rel(f)] = top;
+    out.total += top;
+  }
+  return out;
+}
+
+// Every place the docs quote a test count. Deliberately narrow ("N tests" /
+// "N unit tests") so a measurement like "1 test failed" in prose is not edited.
+export const DOC_FILES = ['README.md', 'AGENTS.md'];
+
+export function docCounts({ root = ROOT } = {}) {
+  const found = [];
+  for (const rel of DOC_FILES) {
+    const text = fs.readFileSync(path.join(root, rel), 'utf8');
+    for (const m of text.matchAll(/(\d+)\s+(unit tests|tests)\b/g)) {
+      found.push({ file: rel, count: Number(m[1]), match: m[0], index: m.index });
+    }
+  }
+  return found;
+}
+
+export function rewriteDocs(count, { root = ROOT, dry = false } = {}) {
+  const changes = [];
+  for (const rel of DOC_FILES) {
+    const file = path.join(root, rel);
+    const text = fs.readFileSync(file, 'utf8');
+    const next = text.replace(/(\d+)(\s+(?:unit tests|tests)\b)/g, `${count}$2`);
+    if (next !== text) {
+      changes.push(rel);
+      if (!dry) fs.writeFileSync(file, next);
+    }
+  }
+  return changes;
+}
+
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === fs.realpathSync(process.argv[1]);
+if (isMain) {
+  const scan = scanTests();
+  const mode = process.argv.includes('--check') ? 'check' : process.argv.includes('--fix') ? 'fix' : 'print';
+  if (mode === 'print') {
+    process.stdout.write(`${scan.total}\n`);
+    if (scan.nested.length) process.stderr.write(`warning: ${scan.nested.length} nested test declaration(s) the count cannot see:\n  ${scan.nested.join('\n  ')}\n`);
+  } else {
+    const docs = docCounts();
+    const wrong = docs.filter((d) => d.count !== scan.total);
+    if (mode === 'fix') {
+      const touched = rewriteDocs(scan.total);
+      process.stdout.write(`${scan.total} declared tests; ${touched.length ? `rewrote ${touched.join(', ')}` : 'docs already correct'}\n`);
+    } else if (wrong.length) {
+      process.stderr.write(
+        `documented test count is wrong. The suite declares ${scan.total} tests; the docs say `
+        + `${wrong.map((w) => `${w.file}: "${w.match}"`).join(', ')}.\n`
+        + 'Fix it with: node scripts/doc-counts.js --fix\n',
+      );
+      process.exitCode = 1;
+    } else {
+      process.stdout.write(`docs agree with the suite at ${scan.total}\n`);
+    }
+  }
+}

package/scripts/donate-qr.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+# 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)
+n = img.shape[0]; size = n + 8
+d = ''.join(f'M{x+4} {y+4}h1v1h-1z' for y in range(n) for x in range(n) if img[y, x] == 0)
+m = np.full((size * 8, size * 8), 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)); 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}')
+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`);