blockyard 0.0.1 → 0.0.9

package/server/chain/blockfile.js

@@ -0,0 +1,234 @@
+// CORE'S BLOCK AND UNDO FILES, READ DIRECTLY (docs/DEFECTS.md: "we can read the block files after
+// all -- -blocksxor, not an unknown format").
+//
+// blocks/blkNNNNN.dat holds blocks as Core received them: [magic][u32 size][block bytes], repeated.
+// blocks/revNNNNN.dat holds the undo data Core wrote when it CONNECTED those blocks:
+// [magic][u32 size][undo bytes][32-byte checksum]. Undo data is the one thing that turns a raw block
+// into a full one -- for every input, the output it spent (value, script, height, coinbase or not).
+// It is what `getblock <hash> 3` reads to report `prevout`, and it is what an address index needs for
+// the spending side, without replaying the whole UTXO set.
+//
+// Since Core v28 both files are XOR-obfuscated at rest with the 8-byte key in blocks/xor.dat, applied
+// by absolute file offset. An all-zero key is the old unobfuscated layout, so both read the same way.
+//
+// READ-ONLY, and it must stay so: these are the node's own files. Nothing here opens a file for
+// writing, and the reader copes with the last file being appended to while it reads.
+//
+// Checked against the node: scripts/blockfile-measure.js --verify compares decoded undo coins with
+// `getblock <hash> 3` prevouts for whole blocks.
+import { openSync, readSync, closeSync, fstatSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { hash256, classifyScript } from './tx.js';
+
+export const MAGIC = Object.freeze({ main: 0xd9b4bef9, test: 0x0709110b, testnet4: 0x283f161c, signet: 0x40cf030a, regtest: 0xdab5bffa });
+
+export function xorKey(blocksDir) {
+  try { return readFileSync(path.join(blocksDir, 'xor.dat')); } catch { return Buffer.alloc(8); }
+}
+
+// XOR `buf` in place as the bytes that start at absolute file offset `offset`
+export function unxor(buf, key, offset = 0) {
+  if (!key || key.every((b) => b === 0)) return buf;
+  for (let i = 0; i < buf.length; i++) buf[i] ^= key[(offset + i) % key.length];
+  return buf;
+}
+
+/** A whole file, de-obfuscated, as one Buffer. Files are ~128 MB; reading whole is the fast path. */
+export function readChainFile(file, key) {
+  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 unxor(buf.subarray(0, got), key, 0);
+  } finally { closeSync(fd); }
+}
+
+/**
+ * The records in a de-obfuscated blk or rev file: { offset, size, body } for each, where body is a
+ * subarray (no copy). `trailer` is 32 for rev files (the checksum after each record), 0 for blk.
+ * Pass the file's `key` so a preallocated tail is recognised after de-obfuscation.
+ * A zero magic is the unwritten tail Core preallocates, so framing stops there.
+ */
+export function* records(buf, magic = MAGIC.main, trailer = 0, key = null) {
+  let pos = 0;
+  while (pos + 8 <= buf.length) {
+    const m = buf.readUInt32LE(pos);
+    if (m === 0) return;                                    // preallocated, never written
+    // THE UNWRITTEN TAIL IS ZEROS ON DISK, NOT OBFUSCATED ZEROS. Core preallocates the file it is
+    // appending to and never XORs the space it has not written, so once the buffer is de-obfuscated
+    // that tail reads as the key itself. Found on the live file (blk05755.dat) at the end of a full
+    // index build: "bad magic 716b8de5" is e5 8d 6b 71, the first half of xor.dat. With the key
+    // given, raw zeros are recognised as the end.
+    if (m !== magic && key && !key.every((b) => b === 0)) {
+      let raw0 = true;
+      for (let i = 0; i < 8 && raw0; i++) raw0 = (buf[pos + i] ^ key[(pos + i) % key.length]) === 0;
+      if (raw0) return;
+    }
+    if (m !== magic) throw new Error(`bad magic ${m.toString(16)} at offset ${pos}`);
+    const size = buf.readUInt32LE(pos + 4);
+    const start = pos + 8;
+    if (start + size + trailer > buf.length) return;       // the file is still being written
+    yield { offset: pos, size, body: buf.subarray(start, start + size), ...(trailer ? { checksum: buf.subarray(start + size, start + size + trailer) } : {}) };
+    pos = start + size + trailer;
+  }
+}
+
+// --- undo data -----------------------------------------------------------
+// Core's VARINT (serialize.h), which is NOT CompactSize: MSB base-128 with an offset per byte.
+function readVarInt(buf, st) {
+  let n = 0;
+  for (;;) {
+    const b = buf[st.pos++];
+    if (b === undefined) throw new RangeError('truncated VARINT');
+    n = n * 128 + (b & 0x7f);
+    if (b & 0x80) n += 1; else return n;
+  }
+}
+function readCompactSize(buf, st) {
+  const b = buf[st.pos++];
+  if (b < 0xfd) return b;
+  if (b === 0xfd) { const v = buf.readUInt16LE(st.pos); st.pos += 2; return v; }
+  if (b === 0xfe) { const v = buf.readUInt32LE(st.pos); st.pos += 4; return v; }
+  const v = Number(buf.readBigUInt64LE(st.pos)); st.pos += 8; return v;
+}
+
+// compressor.cpp DecompressAmount
+export function decompressAmount(x) {
+  if (x === 0) return 0;
+  x -= 1;
+  let e = x % 10;
+  x = Math.floor(x / 10);
+  let n;
+  if (e < 9) { const d = (x % 9) + 1; x = Math.floor(x / 9); n = x * 10 + d; } else { n = x + 1; }
+  while (e > 0) { n *= 10; e--; }
+  return n;
+}
+
+// secp256k1 point decompression, for the two compressed forms of an uncompressed-key P2PK script
+const P = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2fn;
+function modpow(b, e, m) { let r = 1n; b %= m; while (e > 0n) { if (e & 1n) r = (r * b) % m; b = (b * b) % m; e >>= 1n; } return r; }
+function decompressPubkey(prefix, x32) {
+  const x = BigInt('0x' + x32.toString('hex'));
+  let y = modpow((x * x * x + 7n) % P, (P + 1n) / 4n, P);
+  if ((y & 1n) !== BigInt(prefix & 1)) y = P - y;
+  return Buffer.concat([Buffer.from([0x04]), x32, Buffer.from(y.toString(16).padStart(64, '0'), 'hex')]);
+}
+
+// compressor.cpp: sizes 0-5 are special script templates, 6+ a raw script of (size - 6) bytes
+function readCompressedScript(buf, st) {
+  const size = readVarInt(buf, st);
+  const take = (n) => { const v = buf.subarray(st.pos, st.pos + n); st.pos += n; return v; };
+  switch (size) {
+    case 0: return Buffer.concat([Buffer.from([0x76, 0xa9, 0x14]), take(20), Buffer.from([0x88, 0xac])]);
+    case 1: return Buffer.concat([Buffer.from([0xa9, 0x14]), take(20), Buffer.from([0x87])]);
+    case 2: case 3: return Buffer.concat([Buffer.from([0x21, size]), take(32), Buffer.from([0xac])]);
+    case 4: case 5: return Buffer.concat([Buffer.from([0x41]), decompressPubkey(size - 2, take(32)), Buffer.from([0xac])]);
+    default: return Buffer.from(take(size - 6));
+  }
+}
+
+/**
+ * One block's undo record: for each non-coinbase transaction in block order, the coins its inputs
+ * spent, in input order -- { height, coinbase, value_sat, script }.
+ */
+export function decodeBlockUndo(body) {
+  const st = { pos: 0 };
+  const ntx = readCompactSize(body, st);
+  const txs = new Array(ntx);
+  for (let i = 0; i < ntx; i++) {
+    const nin = readCompactSize(body, st);
+    const coins = new Array(nin);
+    for (let j = 0; j < nin; j++) {
+      const code = readVarInt(body, st);
+      const height = Math.floor(code / 2);
+      if (height > 0) readVarInt(body, st);                  // the legacy nVersion placeholder, always 0
+      const value_sat = decompressAmount(readVarInt(body, st));
+      const script = readCompressedScript(body, st);
+      coins[j] = { height, coinbase: (code & 1) === 1, value_sat, script };
+    }
+    txs[i] = coins;
+  }
+  if (st.pos !== body.length) throw new RangeError(`${body.length - st.pos} bytes left after the undo record`);
+  return txs;
+}
+
+/** The input counts an undo record describes, without building coins: cheap enough to match on. */
+export function undoShape(body) {
+  const st = { pos: 0 };
+  const ntx = readCompactSize(body, st);
+  const counts = new Array(ntx);
+  for (let i = 0; i < ntx; i++) {
+    const nin = readCompactSize(body, st);
+    counts[i] = nin;
+    for (let j = 0; j < nin; j++) {
+      const height = Math.floor(readVarInt(body, st) / 2);
+      if (height > 0) readVarInt(body, st);
+      readVarInt(body, st);
+      const size = readVarInt(body, st);
+      st.pos += size === 0 || size === 1 ? 20 : size < 6 ? 32 : size - 6;
+    }
+  }
+  return counts;
+}
+
+/** Core's checksum over an undo record: hash256(previous block hash || undo bytes). */
+export function undoChecksumMatches(record, prevHashHex) {
+  const prev = Buffer.from(prevHashHex, 'hex').reverse();
+  return hash256(Buffer.concat([prev, record.body])).equals(record.checksum);
+}
+
+/**
+ * Pair each block with its undo record. `blocks` are { hash, previousblockhash, ntx } in file order;
+ * the result is a Map from block index to undo record. Blocks with no undo (never connected, or
+ * stale) are simply absent. Every pairing is proven by Core's checksum, never assumed.
+ *
+ * IN CHAIN ORDER, NOT BY SEARCH. Core appends an undo record when it CONNECTS a block, so a rev file
+ * lists its blocks in chain order, while the blk file lists them as they arrived. Two searches were
+ * tried first and both were quadratic where the chain is dense with small blocks: trying every
+ * candidate of the same transaction count ran file 0 for 35 minutes without finishing, and hashing
+ * once per distinct body still took 230 s, because blocks of one or two ordinary transactions each
+ * have a unique record. Here each file's blocks are put in chain order by their previous-block
+ * links, the undo records are walked in their own order, and the next unpaired block of the right
+ * shape is checked first -- almost always the one. A miss (a reorg, a stale block) looks a little
+ * further ahead, and only then searches the whole shape group.
+ */
+export function pairBlocksWithUndo(blocks, undoRecords) {
+  const byHash = new Map(blocks.map((b, i) => [b.hash, i]));
+  // depth within this file along previous-block links: roots are blocks whose parent is elsewhere
+  const depth = new Array(blocks.length).fill(-1);
+  const depthOf = (i) => {
+    const path = [];
+    let j = i;
+    while (j !== undefined && depth[j] === -1) { path.push(j); depth[j] = -2; j = byHash.get(blocks[j].previousblockhash); }
+    let d = j === undefined || depth[j] < 0 ? -1 : depth[j];
+    for (let k = path.length - 1; k >= 0; k--) depth[path[k]] = ++d;
+    return depth[i];
+  };
+  for (let i = 0; i < blocks.length; i++) if (depth[i] === -1) depthOf(i);
+  const groups = new Map();                        // non-coinbase tx count -> block indices in chain order
+  const order = blocks.map((_, i) => i).sort((x, y) => depth[x] - depth[y] || x - y);
+  for (const i of order) { const c = blocks[i].ntx - 1; (groups.get(c) ?? groups.set(c, { list: [], next: 0 }).get(c)).list.push(i); }
+  const taken = new Uint8Array(blocks.length);
+  const out = new Map();
+  const prevBuf = (i) => Buffer.from(blocks[i].previousblockhash, 'hex').reverse();
+  const matches = (i, u) => hash256(Buffer.concat([prevBuf(i), u.body])).equals(u.checksum);
+  for (const u of undoRecords) {
+    const g = groups.get(undoShape(u.body).length);
+    if (!g) continue;
+    while (g.next < g.list.length && taken[g.list[g.next]]) g.next++;
+    let found = -1;
+    for (let k = g.next, tried = 0; k < g.list.length && tried < 32; k++) {
+      const i = g.list[k];
+      if (taken[i]) continue;
+      tried++;
+      if (matches(i, u)) { found = i; break; }
+    }
+    if (found < 0) for (const i of g.list) if (!taken[i] && matches(i, u)) { found = i; break; }
+    if (found >= 0) { taken[found] = 1; out.set(found, u); }
+  }
+  return out;
+}
+
+export { classifyScript };

package/server/chain/index/build.js

@@ -0,0 +1,193 @@
+// BUILD THE ADDRESS INDEX from the node's own block and undo files (docs/MEASUREMENTS.md §28-30).
+//
+//   1. heights  the active chain's block hashes, 0..tip, from getblockhash in batches, into a table
+//               every worker shares -- a block not in it (stale, or newer than the build) is skipped
+//   2. scan     every blk/rev pair on a worker pool; each file's rows come back partitioned by the
+//               key's first byte and are appended to 256 bucket files
+//   3. check    every height 0..tip indexed exactly once, or the build stops rather than publish a hole
+//   4. sort     each bucket sorted (and de-duplicated) on the pool into seg-XX.rows + seg-XX.idx
+//   5. manifest written last, atomically: an index without one is an unfinished build
+//
+// The node's files are only read. Output goes to `out`, which should be on a different device from
+// the block files if one is available: the build reads ~880 GB and writes ~120 GB.
+import { Worker } from 'node:worker_threads';
+import { openSync, writeSync, closeSync, mkdirSync, readdirSync, rmSync, renameSync, writeFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { HeightTable } from './heights.js';
+import { xorKey } from '../blockfile.js';
+import { ROW } from './rows.js';
+
+export const FORMAT = 1;
+export const BLOCK_ROWS = 4096;
+
+async function chainHashes(rpc, tip, onProgress, pace = null) {
+  const table = new HeightTable(1 << 21);
+  const hashes = new Array(tip + 1);
+  // small batches at the lowest priority: the monitor's own polls interleave between them, and
+  // on a machine shared with the node a 5,000-call batch held the lane for seconds (2026-09-14)
+  const BATCH = 1000;
+  for (let from = 0; from <= tip; from += BATCH) {
+    if (pace) await pace();   // the batches load the node too: hold while it is slow (2026-09-14)
+    const calls = [];
+    for (let h = from; h <= Math.min(tip, from + BATCH - 1); h++) calls.push({ method: 'getblockhash', params: [h] });
+    const got = await rpc.batch(calls, { key: `index:hashes:${from}`, timeoutMs: 120_000, maxWaitMs: 600_000, priority: 9 });
+    got.forEach((g, i) => {
+      if (!g.ok) throw new Error(`getblockhash ${from + i}: ${g.error?.message}`);
+      hashes[from + i] = g.result;
+      table.set(g.result, from + i);
+    });
+    onProgress?.({ phase: 'heights', done: Math.min(tip + 1, from + BATCH), total: tip + 1 });
+  }
+  return { table, hashes };
+}
+
+class Pool {
+  constructor(size, workerData) {
+    this.workers = Array.from({ length: size }, () => new Worker(new URL('./worker.js', import.meta.url), { 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
+  async run(jobs, onResult, pace = null) {
+    let next = 0, failed = null;
+    await Promise.all(this.workers.map((w) => new Promise((resolve) => {
+      const go = async () => {
+        if (failed || next >= jobs.length) { resolve(); return; }
+        const job = jobs[next++];
+        if (pace) { try { await pace(); } catch (err) { failed = err; resolve(); return; } }
+        w.once('message', async (msg) => {
+          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();
+        });
+        w.postMessage(job);
+      };
+      go();
+    })));
+    if (failed) throw failed;
+  }
+  close() { return Promise.all(this.workers.map((w) => w.terminate())); }
+}
+
+/** Workers for a build on this machine: four cores left for the node, ~2.5 GB of memory each, sixteen at most. */
+export function defaultWorkers(cpus = os.cpus().length, totalMem = os.totalmem()) {
+  return Math.max(1, Math.min(16, cpus - 4, Math.floor(totalMem / 2.5e9)));
+}
+
+/**
+ * A pace for a build that shares its machine with the node (every build does now): before each
+ * file is handed to a worker, wait while the node's RPC is failing, its breaker is open, or its
+ * answers average more than `slowMs`; ease off (one file per `easeMs`) while they are merely slow.
+ * Reads from the lane's own telemetry, so it costs the node nothing to ask. (2026-09-14, the first
+ * Mac install: a build at full speed on the node's disk turned its RPC into 18 s answers and
+ * 90 s timeouts.)
+ */
+// `slowMs` is the monitor's own idea of slow (rpc.slowLatencyMs, 5 s by default): a node whose
+// heavy reads take a second when perfectly well -- the first Mac -- was being held at one second
+// and eased at a quarter of it, and a healthy build ran at a sixth of its speed (2026-09-14)
+export function rpcPacer(rpc, { slowMs = 5000, easeMs = 250, holdMs = 10_000, onChange = null } = {}) {
+  let held = false;
+  return async () => {
+    for (;;) {
+      const t = rpc?.telemetry?.() ?? {};
+      const failing = !!t.breakerOpen || (t.lastError && (!t.lastGoodAt || t.lastError.at > t.lastGoodAt) && Date.now() - t.lastError.at < 60_000);
+      const avg = Number.isFinite(t.avgLatencyMs) ? t.avgLatencyMs : 0;
+      if (failing || avg > slowMs) {
+        if (!held) { held = true; onChange?.(true, t); }
+        await new Promise((r) => setTimeout(r, holdMs));
+        continue;
+      }
+      if (held) { held = false; onChange?.(false, t); }
+      if (avg > slowMs * 0.4) await new Promise((r) => setTimeout(r, easeMs));
+      return;
+    }
+  };
+}
+
+export async function buildIndex({ rpc, blocksDir, out, workers = defaultWorkers(), files = null, onProgress = () => {}, pace = null }) {
+  const t0 = performance.now();
+  const stats = { format: FORMAT, workers, phases: {} };
+  const info = await rpc.batch([{ method: 'getblockchaininfo', params: [] }], { key: 'index:info', timeoutMs: 60_000 });
+  if (!info[0].ok) throw new Error(`getblockchaininfo: ${info[0].error?.message}`);
+  const { chain, blocks: tip } = info[0].result;
+  if (chain !== 'main') throw new Error(`only mainnet block files are framed here so far (the node is on ${chain})`);
+
+  let t = performance.now();
+  const { table, hashes } = await chainHashes(rpc, tip, onProgress, pace);
+  stats.phases.heightsSec = (performance.now() - t) / 1000;
+
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(out, { recursive: true });
+  const all = readdirSync(blocksDir).filter((f) => /^blk\d{5}\.dat$/.test(f)).map((f) => Number(f.slice(3, 8))).sort((a, b) => a - b);
+  const fileList = files ?? all;
+  const pool = new Pool(workers, { blocksDir, key: xorKey(blocksDir), heightsBuffer: table.buffer, heightsCapacity: table.capacity, blockRowsPerIndex: BLOCK_ROWS });
+
+  try {
+    // --- scan -------------------------------------------------------------------
+    t = performance.now();
+    // AT MOST 64 BUCKET FILES OPEN AT ONCE (2026-09-14): 256 held open for the whole scan is the
+    // entire soft limit on a stock macOS (`ulimit -n` 256). The least recently written is closed
+    // and reopened for append when a 65th is needed -- a few thousand extra opens over a build.
+    const fds = new Array(256).fill(null), lru = [];
+    const MAX_OPEN = 64;
+    const bucketFile = (b) => path.join(out, `bucket-${b.toString(16).padStart(2, '0')}.unsorted`);
+    const fdFor = (b) => {
+      if (fds[b] === null) {
+        if (lru.length >= MAX_OPEN) { const old = lru.shift(); closeSync(fds[old]); fds[old] = null; }
+        fds[b] = openSync(bucketFile(b), 'a');
+      } else lru.splice(lru.indexOf(b), 1);
+      lru.push(b);
+      return fds[b];
+    };
+    const seen = new Uint8Array(tip + 1);
+    let rows = 0, scanned = 0, readMs = 0, workMs = 0, stale = 0, missingUndo = 0, dupHeights = 0;
+    await pool.run(fileList.map((file) => ({ type: 'scan', file })), (msg) => {
+      const data = Buffer.from(msg.data);
+      for (const [b, from, to] of msg.parts) {
+        const fd = fdFor(b);
+        for (let o = from; o < to;) o += writeSync(fd, data, o, to - o);
+      }
+      for (const h of msg.heights) { if (seen[h]) dupHeights++; seen[h] = 1; }
+      rows += msg.rows; scanned++; readMs += msg.readMs; workMs += msg.ms; stale += msg.stale; missingUndo += msg.missingUndo;
+      onProgress({ phase: 'scan', done: scanned, total: fileList.length, rows, file: msg.file });
+    }, pace);
+    for (const fd of fds) if (fd !== null) closeSync(fd);
+    stats.phases.scanSec = (performance.now() - t) / 1000;
+    stats.scan = { files: scanned, rawRows: rows, workerReadSec: readMs / 1000, workerCpuSec: workMs / 1000, staleBlocks: stale, missingUndo, duplicateHeights: dupHeights };
+
+    // --- check ------------------------------------------------------------------
+    let missing = 0, firstMissing = -1;
+    for (let h = 0; h <= tip; h++) if (!seen[h]) { missing++; if (firstMissing < 0) firstMissing = h; }
+    stats.check = { tip, missingHeights: missing, firstMissing };
+    if (!files && missing) throw new Error(`${missing} heights were not indexed (first ${firstMissing}); refusing to publish an index with holes`);
+
+    // --- sort -------------------------------------------------------------------
+    t = performance.now();
+    const buckets = [];
+    for (let b = 0; b < 256; b++) { try { if (statSync(bucketFile(b)).size) buckets.push(b); } catch { /* an empty bucket */ } }
+    const counts = new Array(256).fill(0);
+    let sortedRows = 0, dupes = 0, sortCpu = 0;
+    await pool.run(buckets.map((bucket) => ({ type: 'sort', bucket, dir: out })), (msg) => {
+      counts[msg.bucket] = msg.rows; sortedRows += msg.rows; dupes += msg.dupes; sortCpu += msg.ms;
+      onProgress({ phase: 'sort', done: buckets.indexOf(msg.bucket) + 1, total: buckets.length, rows: sortedRows });
+    });
+    stats.phases.sortSec = (performance.now() - t) / 1000;
+    stats.sort = { rows: sortedRows, duplicateRowsDropped: dupes, workerCpuSec: sortCpu / 1000 };
+
+    // --- manifest ---------------------------------------------------------------
+    let bytes = 0;
+    for (const f of readdirSync(out)) bytes += statSync(path.join(out, f)).size;
+    stats.totalSec = (performance.now() - t0) / 1000;
+    const manifest = {
+      format: FORMAT, rowBytes: ROW, blockRows: BLOCK_ROWS, chain,
+      tip: { height: tip, hash: hashes[tip] }, files: files ? fileList : 'all',
+      rows: sortedRows, bucketRows: counts, bytes, builtAt: new Date().toISOString(), stats,
+    };
+    writeFileSync(path.join(out, 'manifest.json.tmp'), JSON.stringify(manifest, null, 1) + '\n');
+    renameSync(path.join(out, 'manifest.json.tmp'), path.join(out, 'manifest.json'));
+    return manifest;
+  } finally {
+    await pool.close();
+  }
+}

package/server/chain/index/heights.js

@@ -0,0 +1,36 @@
+// Block hash -> height for the chain an index build covers, in a SharedArrayBuffer so every build
+// worker reads the same table without a copy (966,000 entries is ~70 MB as a Map of hex strings,
+// and there are sixteen workers). Open addressing on the first 8 bytes of the block hash; a hash
+// prefix collision among a million blocks is odds of ~1 in 3.7e7, and a collision would put two
+// blocks at one height -- which the build checks for, since it counts every height exactly once.
+// The LAST 16 hex digits of the displayed hash, not the first: a displayed hash begins with the
+// proof of work, so a recent block's first 16 digits are all zero and every one of them would collide.
+export class HeightTable {
+  constructor(capacity = 1 << 21) {
+    this.capacity = capacity;
+    this.buffer = new SharedArrayBuffer(capacity * 12);
+    this._bind();
+  }
+  static attach(buffer, capacity) {
+    const t = Object.create(HeightTable.prototype);
+    t.capacity = capacity; t.buffer = buffer; t._bind();
+    return t;
+  }
+  _bind() {
+    this.keys = new BigUint64Array(this.buffer, 0, this.capacity);
+    this.values = new Int32Array(this.buffer, this.capacity * 8, this.capacity);
+  }
+  static #prefix(hashHex) { return BigInt('0x' + hashHex.slice(-16)) | 1n; }     // never the empty 0
+  set(hashHex, height) {
+    const k = HeightTable.#prefix(hashHex);
+    let i = Number(k % BigInt(this.capacity));
+    while (this.keys[i] !== 0n && this.keys[i] !== k) i = (i + 1) % this.capacity;
+    this.keys[i] = k; this.values[i] = height;
+  }
+  get(hashHex) {
+    const k = HeightTable.#prefix(hashHex);
+    let i = Number(k % BigInt(this.capacity));
+    while (this.keys[i] !== 0n) { if (this.keys[i] === k) return this.values[i]; i = (i + 1) % this.capacity; }
+    return -1;
+  }
+}