blockyard 0.0.9 → 0.1.1

package/docs/API.md

@@ -89,7 +89,7 @@ Other statuses: `204` for `OPTIONS` on any path (`Allow: GET,POST,DELETE,HEAD`).
 
 Each route in the table has one of three auth levels:
 
-| Level | Accounts off (default) | Accounts on (`BLOCKYARD_AUTH=1`) |
+| Level | Accounts off (`BLOCKYARD_AUTH=0`) | Accounts on (the default) |
 |---|---|---|
 | `none` | Open. | Open. No session needed. |
 | `any` | Served as the built-in anonymous user (`role: "viewer"`). | Any valid, non-disabled session. Without one: `401`. |
@@ -97,14 +97,14 @@ Each route in the table has one of three auth levels:
 
 The roles are `viewer` < `operator` < `admin`. No route in the table requires `viewer` or `operator` by itself. Those two roles matter in two places only: each node action names a minimum role (section 14), and `POST /api/password` needs `admin` to change *another* user's password.
 
-**Open mode (the default, `auth.enabled=false`).** No sign-in. Anyone who can reach the port can read everything (state, charts, events, peers, mempool, explorer, markets, the read-only RPC console) as `viewer`. The ceiling is fixed and nothing can raise it. As a result:
+**Open mode (`auth.enabled=false`, a choice; the default is accounts on).** No sign-in. Anyone who can reach the port can read everything (state, charts, events, peers, mempool, explorer, markets, the read-only RPC console) as `viewer`. The ceiling is fixed and nothing can raise it. As a result:
 
 - user administration, `/api/audit` and password changes are closed;
 - node writes (`/api/action`) are refused unless `BLOCKYARD_ALLOW_WRITES_WITHOUT_AUTH=1` was set deliberately;
 - `/api/login` answers `403 accounts_disabled`;
 - `GET /login` redirects (`302`) to `/`.
 
-**Accounts mode (`BLOCKYARD_AUTH=1`).** Sign-in, roles, sessions, CSRF protection and a per-user audit trail. On first start with no users, an `admin` account is created. Its password comes from `BLOCKYARD_ADMIN_PASSWORD`, or is generated and printed once to the server log.
+**Accounts mode (the default).** Sign-in, roles, sessions, CSRF protection and a per-user audit trail. On first start with no users, an `admin` account is created. Its password comes from `BLOCKYARD_ADMIN_PASSWORD`, or is generated and printed once to the server log.
 
 ### Session cookie
 
@@ -224,8 +224,8 @@ Auth `none`, not rate limited. Built for uptime probes. `ok` is `true` when at l
 {
   "ok": true,
   "degraded": [],
-  "version": "0.0.9",
-  "build": "0.0.9-fd620adc52",
+  "version": "0.1.0",
+  "build": "0.1.0-fd620adc52",
   "scheme": "http",
   "tls": false,
   "uptimeSec": 1519,
@@ -242,7 +242,7 @@ Auth `none`, not rate limited. Built for uptime probes. `ok` is `true` when at l
 What the About page shows: the monitor's version and live build, and the **shape** of the machine it runs on.
 
 ```json
-{ "version": "0.0.9", "build": "0.0.9-a6ecedff3c", "platform": "linux", "release": "7.0.0-31-generic",
+{ "version": "0.1.0", "build": "0.1.0-a6ecedff3c", "platform": "linux", "release": "7.0.0-31-generic",
   "arch": "x64", "cpus": 32, "cpuModel": "AMD Ryzen 9 9950X3D 16-Core Processor",
   "totalMemGb": 132.3, "node": "v22.23.2", "uptimeSec": 2355 }
 ```
@@ -261,9 +261,9 @@ Auth `none`. Answers "is the code in my tab the code on disk?" The build id is `
 
 ```json
 {
-  "version": "0.0.9",
-  "build": "0.0.9-5223f98d84",
-  "bootBuild": "0.0.9-fd620adc52",
+  "version": "0.1.0",
+  "build": "0.1.0-5223f98d84",
+  "bootBuild": "0.1.0-fd620adc52",
   "matchesClient": null,
   "scheme": "http",
   "tls": false,
@@ -295,6 +295,7 @@ Top-level keys:
 ```
 id label color online chain ibd tip sync progress warnings difficulty hashrateEstEh hashrateNote
 avgBlockGapSec sizeOnDisk pruned chainwork uptimeSec network mempool peers net attribution blocks
+network (the Mining tab's network row: rewards over 144 blocks, adjustment, halving, adjustments[], hashrate { networkHashPs, series[] }, pools { blocks, luckPct, pools[], filled, todo }; collect/network.js)
 fees mining utxo chaintxstats indexes tips deployments rpcInfo log health series app user seq
 ```
 
@@ -331,7 +332,7 @@ Trimmed example:
   "health": { "rpc": { "online": true, "...": "..." }, "cadence": { "fast": { "configuredMs": 4000,
               "effectiveMs": 4000, "stretched": false, "lastRunMs": 120 } }, "quality": [] },
   "series": { "mempool": { "hour": [ { "t": 1789154820000, "v": 18780 } ], "...": "..." } },
-  "app": { "version": "0.0.9", "build": "0.0.9-fd620adc52", "scheme": "http", "uptimeSec": 1536,
+  "app": { "version": "0.1.0", "build": "0.1.0-fd620adc52", "scheme": "http", "uptimeSec": 1536,
            "sseClients": 5, "self": { "rssMb": 175.6, "heapMb": 42.8, "cpuPct": 2.71 }, "serverTime": 1789155688322 },
   "user": { "username": "anonymous", "role": "viewer", "id": "anonymous", "disabled": false, "lastLoginAt": null },
   "seq": 406
@@ -1029,8 +1030,9 @@ To poll incrementally, keep `maxSeq` and pass it back as `since`. The filters ar
 
 Exchange prices from the public REST APIs of Coinbase, Kraken, Bitstamp, Bitfinex and OKX. **This is the only outbound connection BlockYard makes that is not to the node.** It runs server-side, because the page's CSP allows `connect-src 'self'` only.
 
-- **On demand.** Nothing is fetched until someone calls `/api/markets` or `/api/markets/depth`. Each call "touches" the feed. The dashboard's Overview makes that call by default (Display settings → Markets & Price → Price line on Overview), so a monitor with anyone on its landing page is polling. While touched, it polls tickers every 15 s, hourly candles every 5 min and order books every 30 s. It stops 10 minutes after the last touch.
-- `BLOCKYARD_MARKETS=0` (or `markets.enabled=false`) turns it off. Both endpoints then answer `{ "ok": true, "enabled": false, "note": "market data is off on this monitor (...)" }`.
+- **Off by default.** Polling runs only while the Display setting **Markets & Price → Enable market polling** is on (`markets.polling` in the shared settings file, read per request). With it off, both endpoints answer `{ "ok": true, "enabled": false, "polling": false, "note": "market polling is off ..." }`, the call parks the feed, and the monitor makes no outbound connection but to the node.
+- `BLOCKYARD_MARKETS=0` (or `markets.enabled=false`) removes the feed altogether; both endpoints then answer `{ "ok": true, "enabled": false, "note": "market data is off on this server ..." }` whatever the setting.
+- **On demand.** With polling on, nothing is fetched until someone calls `/api/markets` or `/api/markets/depth`. Each call "touches" the feed. The dashboard's Overview makes that call by default (Display settings → Markets & Price → Price line on Overview), so a monitor with anyone on its landing page is polling. While touched, it polls tickers every 15 s, hourly candles every 5 min and order books every 30 s. It stops 10 minutes after the last touch.
 - An exchange that fails keeps its last data and reports `error`. It is never dropped or zero-filled.
 
 ### `GET /api/markets`
@@ -1153,7 +1155,7 @@ The default is **deny**. The rules are applied in this order, and the first matc
 Consequences worth knowing:
 
 - The list is fixed in code, and no setting widens it.
-- `get*` and `list*` wallet reads (for example `getbalance`, `listunspent`) are allowed if the node has a wallet loaded.
+- Wallet RPCs are refused by name, reads included (`getbalance`, `listunspent`, `listdescriptors`, `gethdkeys`, …): some of them return private keys, and the monitor has no use for a wallet.
 - `createrawtransaction` is allowed: it only builds an unsigned transaction and changes nothing.
 - `/api/config` → `allowlist` publishes a summary: the prefixes, the size of the deny list and the default decision.
 
@@ -1222,7 +1224,7 @@ If the node refuses, the answer is `200` with `{ "ok": false, "action", "method"
 
 ## 15. Accounts, sessions, users and audit
 
-These routes are meaningful only with `BLOCKYARD_AUTH=1`. In open mode they answer as noted.
+These routes are meaningful only with accounts on (the default). In open mode they answer as noted.
 
 The user object returned by these routes (`publicUser`):
 
@@ -1378,7 +1380,7 @@ The monitor's own health: process, RPC client, log tail, stream clients and the
 ```json
 {
   "self": { "t": 1789155700000, "rssMb": 175.6, "heapMb": 42.8, "sseClients": 5, "usersActive": 0,
-            "cpuPct": 2.71, "eventRate": 0, "build": "0.0.9-fd620adc52" },
+            "cpuPct": 2.71, "eventRate": 0, "build": "0.1.0-fd620adc52" },
   "nodes": [
     { "id": "main",
       "rpc": { "nodeId": "main", "url": "http://127.0.0.1:8332", "cookieSource": "...", "online": true,

package/docs/ARCHITECTURE.md

@@ -192,8 +192,9 @@ it directly; running the file as a script calls it and prints the banner.
    missing is skipped with a logged reason rather than kept as a permanently
    offline panel. `wireMonitor()` connects each monitor's events to the SSE hub
    and coalesces pushes to one snapshot per second.
-8. `MarketFeed` is created if `markets.enabled` is set. It stays idle until the
-   Markets API is requested.
+8. `MarketFeed` is created if `markets.enabled` is set. It stays idle until the Markets
+   API is requested with the **Enable market polling** setting on (off by default; read from
+   the shared settings file per request, `marketsPollingOn` in `http/api.js`).
 9. One HTTP(S) server is created per bound address, all sharing the same `app`.
    An address missing at boot is skipped with a warning. Boot is fatal only when
    none of the configured addresses exist.
@@ -211,8 +212,8 @@ it directly; running the file as a script calls it and prints the banner.
     `address-index-building` quality flag, `index` events at start, finish and
     failure, and the follower started on completion (section 2.8).
     `app.shutdown()` stops timers, closes streams, stops monitors, saves history
-    and sessions, and closes the listeners. A build in flight is not resumed:
-    the next start begins it again.
+    and sessions, and closes the listeners. A build in flight stops with the
+    process and resumes on the next start from its journal (section 2.8).
 
 `boot({ log })` and `loadConfig({ ifaces, now })` are **seams**: tests inject a
 logger, a fake interface list, or a fake clock instead of intercepting
@@ -346,7 +347,9 @@ Bitstamp, Bitfinex and OKX.
   with its error, never zero-filled. Tickers older than three intervals are marked
   `stale`.
 
-`BLOCKYARD_MARKETS=0` (or `markets.enabled: false`) disables all of it.
+Polling is off by default — the **Enable market polling** Display setting turns it on, and a
+request with it off parks the feed. `BLOCKYARD_MARKETS=0` (or `markets.enabled: false`)
+removes the feed altogether.
 
 ### 2.4 The RPC lane (`server/rpc/client.js`)
 
@@ -523,11 +526,12 @@ flowchart LR
 
 ### 2.7 Auth (`server/auth/*`)
 
-- **Open by default.** With `auth.enabled: false` (the default), every request is
+- **Sign-in by default** (since 2026-09-15; it shipped open in 0.0.9), bound to
+  `127.0.0.1`. With `auth.enabled: false` (`BLOCKYARD_AUTH=0`), every request is
   served as a frozen anonymous user with role `viewer`. That ceiling is hardcoded,
   not configurable. Admin routes return 403 in both modes, CSRF is not needed
   because there is no cookie to ride, and rate limits apply per client address.
-- **Accounts.** `BLOCKYARD_AUTH=1` turns on:
+- **Accounts** (the default; `BLOCKYARD_AUTH=1` restores them after an override):
   - scrypt password hashes (upgraded to current parameters on login)
   - session tokens that are stored hashed, with idle and absolute TTLs
   - double-submit CSRF (the token in a header or body is compared with the
@@ -573,7 +577,24 @@ files. The numbers are in `docs/MEASUREMENTS.md` §28-30 and the history in
   bucket files; a check that every height is indexed exactly once, or the build
   stops rather than publish a hole; each bucket sorted into `seg-XX.rows` plus a
   sparse `seg-XX.idx` (one key per 4,096 rows); and a manifest written last, so an
-  index without one is unfinished. Measured on the whole chain: 29 min 45 s on 16
+  index without one is unfinished. **An interrupted build resumes** from
+  `build-journal.json`, written beside the output with a temporary name, fsync and
+  rename, and carrying a SHA-256 of its own body. The scan resumes per block file:
+  a checkpoint (at most once a minute, and when the scan ends or fails in an orderly
+  way) fsyncs the buckets written since the last one and records the files
+  finished, each bucket's length and running CRC-32, the heights seen and the
+  counters; a resume cuts every bucket back to its journaled length, so rows from a
+  half-appended file are gone, and scans that file again. The sort resumes per
+  bucket: the worker checks the input against the journaled length and CRC, writes
+  the segment with fsync and rename, the journal records it, and only then is the
+  input removed. The journal names the journal version, index format, row and
+  block sizes, chain, tip height and hash and the `--files` selection; a resume
+  works to the journal's tip, not the node's newer one, so the result is byte for
+  byte the index an uninterrupted build would have written. A journal that is torn,
+  of another format or selection, whose tip hash the node's active chain no longer
+  has, or whose files on disk disagree with it is discarded with the reason logged,
+  and the build starts over. The manifest is still last; the journal is removed
+  after it. Measured on the whole chain: 29 min 45 s on 16
   workers, 5.89 billion rows, 123.7 GB (§30). The build reads ~880 GB and writes
   ~120 GB, so `--out` should be a different device from the block files.
 - **Lookups** (`chain/index/store.js`, `IndexStore`). The sparse keys of the 256
@@ -603,8 +624,8 @@ files. The numbers are in `docs/MEASUREMENTS.md` §28-30 and the history in
   the phase's own rate, `paused while the node's RPC is slow`), refreshed at most
   every 5 s; `index` events mark start, finish and failure; on finish the follower
   starts and address pages go live with no restart; failure leaves
-  `address-index-build-failed` naming the command to run by hand. There is no
-  resume: a build stopped with the server starts over next time.
+  `address-index-build-failed` naming the command to run by hand. A build stopped with the server resumes next time; the flag's ETA is
+  computed from what this run has done (`from` in the progress), not from zero.
 - **Following the chain** (`chain/index/live.js`, `LiveIndex`). The base is
   immutable and covers the chain to the block it was built at. The follower polls
   the node's tip, rolls the tail back to the fork if a block it holds is no longer
@@ -659,6 +680,7 @@ loaded from the same origin. There is no build step and no framework.
 | `settings.js` | display settings: `DEFAULTS`, the `PANEL` rows of the settings dialog, `normalise()`, and the option builders (`spaceOptions`, `enabledEffects`, ...) the boards read; stored on the server (`/api/settings`) with a `localStorage` copy |
 | `about.js` | the About page (version, system and node info) |
 | `tetris.js` / `tetrust.js`, `breakout.js` / `blockout.js`, `arkanoid.js` / `blockanoid.js`, `tetsound.js` | the Diversions: pure game rules in the first file of each pair, the tab drawn on the 3D engine in the second, and Tetrust's sound |
+| `x86.js`, `dospc.js`, `soundcard.js`, `dosworker.js`, `dosaudio.js`, `dosio.js`, `dosgame.js`, `doom.js`, `quake.js` | the DOS Diversions: an i386 interpreter, the PC around it (DOS/4GW for DOOM, the go32 stub and CWSDPMI for Quake), a Sound Blaster Pro 2 with an OPL3, the worker the machine runs in, the AudioWorklet it plays through, the pure keyboard/config/text-mode helpers, the shared tab, and each game's own few lines (section 3.4) |
 | `fmt.js` | formatters: decimal units (as the node prints them), `–` for anything absent |
 | `login.js` | the login page (a separate file because of the CSP) |
 
@@ -790,6 +812,102 @@ What this means for front-end code:
 
 ---
 
+### 3.4 The DOS Diversions: Wolfenstein 3D, DOOM and Quake
+
+The shareware `WOLF3D.EXE` v1.4, `DOOM.EXE` v1.9 and `QUAKE.EXE` v1.06 run unmodified on a PC emulated in
+the browser.
+Nothing is ported and no dependency is used; every layer is this repository's own:
+
+```
+wolf3d.js / doom.js / quake.js -> dosgame.js (page)  --scancodes, mouse, run/pause-->  dosworker.js (Worker)
+      ^                                                                      |
+      |  frames (320x200 indices + palette), text-mode cells, stats          |  createPC()      dospc.js
+      +----------------------------------------------------------------------+    createCpu()   x86.js
+dosaudio.js (AudioWorklet) <--stereo PCM over a MessagePort-----------------+    soundcard.js  (SB Pro 2 + OPL3)
+```
+
+- **`x86.js`** is a user-mode i386 with an x87, interpreted. No paging or rings: a DOS extender's
+  program runs in protected mode, and segment registers carry a base and a size. EIP is
+  kept linear and converted at the edges (a pushed return address, a loaded jump target) against
+  the code segment's base, ESP is an offset in SS: DOS/4GW's segments are all at 0, DJGPP's at the
+  program's memory block. A code segment whose descriptor is 16-bit decodes 16-bit (DJGPP's
+  start-up and exit run small 16-bit helpers in DOS memory). **Real mode** is a switch
+  (`cpu.realMode`) for Wolfenstein 3D: a segment's base is its value times sixteen, code is 16-bit,
+  the stack pointer is SP and wraps inside its segment, the string instructions count with SI, DI
+  and CX, and an interrupt pushes a 16-bit frame and goes through the vector table at 0:0. Real-mode
+  code runs through `step()` rather than the decoded cache: it needs about a third of the speed it
+  gets. The page's CSP forbids eval, so there
+  is no JIT; speed comes from keeping every value an int32 (a `>>> 0` above 2^31 is a double and,
+  in a closure variable, an allocation), lazy flags recorded in an `Int32Array`, one try/catch
+  around the loop rather than each instruction, and 32-bit fast paths for the instructions
+  compilers emit most. The FPU keeps its stack in a Float64Array and converts operands through
+  typed-array views. **Decoded instructions are cached**: each is decoded once into three int32s
+  (a handler number with its registers packed beside it, a displacement, an immediate) in an
+  Int32Array per 4 KB page, and `run()` dispatches on the handler number with one switch; the forms
+  it does not specialise run through `step()`. Not closures -- a closure per instruction made every
+  call megamorphic and ran slower than the interpreter. Writes into a page holding decoded code
+  clear only the instructions they overlap (DOOM and Quake both patch constants into their own span
+  drawers on every call), and the machine calls `cpu.invalidate()` after it writes memory directly.
+  The ALU operations have a handler each (their flag bookkeeping inline, not one shared routine
+  branching on the operation), so do the x87 forms Quake runs most, and the loop forms a memory
+  operand's address inline before the switch: the switch is too big for V8 to inline helpers into
+  every case, and those calls were most of what was left. About 141 million instructions a second on
+  Quake headless on one core and 115-118 in a Chromium worker; Quake's timedemo 52.5 fps of wall time
+  (MEASUREMENTS §32-35).
+- **`dospc.js`** is the machine, and it plays whichever DOS extender the program was bound to.
+  `boot()` tells them apart by the file: an EXE with neither an LE nor a COFF image inside is a
+  plain DOS program, and `bootMZ` loads it as DOS did -- a PSP, the image after it with its segment
+  relocations applied, the rest of conventional memory its block, the vector table filled with
+  pointers at stubs the machine answers (a program that installs its own handler gets it called),
+  and DOS's allocator behind INT 21h 48h/49h/4Ah, which Wolfenstein 3D uses to shrink itself and
+  claim the rest. `loadLE` finds DOOM's LE executable inside the DOS/4GW
+  stub, loads it at +1 MB and applies its fixups; `parseCoff`/`bootCoff` find Quake's COFF image
+  behind the go32 stub and do what that stub leaves behind -- a memory block with the sections in
+  it, selectors based at it, a transfer buffer with the PSP right below it (DJGPP's libc finds the
+  PSP by subtracting 100h), and the "stubinfo" crt0 reads through FS. The extenders themselves never
+  run; this file answers INT 21h (files from an in-memory, case-insensitive directory tree, written
+  files handed to the host on close, and a real system file table, because DJGPP's `fstat` walks
+  it), INT 31h DPMI (descriptors with base and size, memory blocks, protected-mode vectors,
+  simulated real-mode interrupts), INT 10h/16h/33h, and the hardware a DOS game programs directly:
+  the 8259s, the 8254 (with the BIOS tick count kept in step with it, which DJGPP's `uclock` reads),
+  the keyboard controller, and a VGA with planar memory, unchained mode, write mode 1's latched copy
+  (Wolfenstein 3D and DOOM copy between pages with it) and CRTC page flipping (how DOOM and
+  Wolfenstein 3D draw) as well as the linear window (how Quake does). The clock is injected (`now()`): wall
+  time in the worker, instruction count in tests, so a headless boot is the same run every time.
+- **`soundcard.js`** is a Sound Blaster Pro 2 at 220h/IRQ 7/DMA 1 — the DSP's command set and the
+  8237 DMA controller it pulls samples through — and an OPL3 modelled as operators with
+  documented envelope rates. `tick(t)` produces output for the machine time that passed and raises
+  the end-of-block interrupt from inside the same loop.
+- **`dosworker.js`** takes a game's name, fetches its files (`dosio.js` `GAMES`), and runs the
+  machine in ~10 ms slices, yielding between them so input arrives. It sends a frame when the CRTC
+  start address or the palette changed, or once the linear window has been written and a slice has
+  passed without more writes (never half of Quake's copy). The frame buffer bounces between the
+  worker and the page so no frame allocates. Savegames and configs are kept in IndexedDB, one
+  database a game.
+- **`dosgame.js`** is a game's tab: it draws, captures input, pauses when the tab is not on screen
+  (the worker's clock stops, so nothing moves), and uses a ScriptProcessor when `audioWorklet` is
+  unavailable — a plain-HTTP LAN address is not a secure context. `doom.js` and `quake.js` give it
+  names, key lists and switches, and so does `wolf3d.js`.
+
+The game files are served from `games/<game>_dos/` by `server/http/games.js`
+(`/games/<game>/<path>`: a game it names, at most one directory and 8.3 names of `.EXE`, `.WAD`,
+`.PAK`, `.CFG` and `.WL1`, behind the session when accounts are on) rather than from `public/`, whose every
+file feeds the build id.
+
+**Provenance** (2026-09-16, audit I6). The files are the three shareware releases, kept byte for byte
+(`.gitattributes` marks `games/**` binary so git never rewrites them), and are served to the browser,
+never executed on the server:
+
+| Directory | Release | Its own terms, as shipped |
+|---|---|---|
+| `games/wolf3d_dos/` | Wolfenstein 3D v1.4 shareware (Apogee Software, 1992) | none beyond `file_id.diz`: the release's shareware licence text is not bundled |
+| `games/doom_dos/` | DOOM v1.9 shareware (id Software; `DOOM1.WAD`) | `README.TXT`, `ORDER.FRM`, the DOOM FAQ v6.666 |
+| `games/quake_dos/` | Quake v1.06 shareware (id Software, 1 October 1996) | `LICINFO.TXT`, `SLICNSE.TXT`, `READV106.TXT` |
+
+`games/SHA256SUMS` lists the SHA-256 of every tracked file under `games/` (`cd games && sha256sum -c
+SHA256SUMS`), and `test/audit-2026-09-16-low-scripts.test.js` recomputes them, so a changed game file
+is a failing test rather than an unnoticed one.
+
 ## 4. The 3D engine
 
 The 3D viewer turns a set of transactions, or any caller-supplied tiles, into

package/docs/CONFIGURATION.md

@@ -95,18 +95,20 @@ Durations are in milliseconds unless the name says otherwise (`retentionHours`).
 
 | key | default | meaning |
 |---|---|---|
-| `server.host` | `"0.0.0.0"` | Address to listen on. Kept for compatibility; `server.hosts` wins when both are set. |
+| `server.host` | `"127.0.0.1"` | Address to listen on — this machine only, by default. Kept for compatibility; `server.hosts` wins when both are set. |
 | `server.hosts` | *(unset; falls back to `host`)* | Addresses to listen on: an array (`["192.0.2.10", "2001:db8::10"]`), or a single string with commas (`"192.0.2.10,198.51.100.7"`). One HTTP server is started per address, and all of them share sessions, rate limits and monitors. Entries must be address literals: IPv4, IPv6, `0.0.0.0`, `::`, or `localhost`. Hostnames are refused. See [Binding](#binding-to-specific-addresses). |
 | `server.port` | `21000` | TCP port. It is the same port on every address. It must be an integer from 1 to 65535. |
 | `server.allowCidrs` | `[]` | Client allowlist. Empty means every client that can reach the port is admitted. Otherwise only addresses inside one of the networks connect, and everyone else gets HTTP 403 (the reason goes to the server log). Entries are CIDRs or bare addresses (a bare address means `/32` or `/128`), IPv4 or IPv6, compared bit by bit. An entry that cannot be parsed stops the boot. |
 | `server.trustProxy` | `false` | When `true`, the client address is the **first** entry of the `X-Forwarded-For` header instead of the socket's peer address. That address feeds the CIDR allowlist, the rate limits and the audit log. Turn it on only when a reverse proxy you control is the sole way in and it sets that header. Otherwise any client can pick its own address and walk past `allowCidrs`. |
-| `server.tls.cert` | `null` | Path to a PEM certificate. TLS is on only when `cert` and `key` are both set, and then every listener serves HTTPS. |
+| `server.tls.enabled` | `true` | HTTPS on every listener. With no `cert`/`key` named, the server makes its own self-signed certificate under `<data>/tls/` on first start (see INSTALL §9). `false` serves plain HTTP, for a reverse proxy that terminates TLS. |
+| `server.tls.cert` | `null` | Path to a PEM certificate of your own, used instead of the made one. Set it together with `key`. |
 | `server.tls.key` | `null` | Path to the PEM private key for `cert`. This file is secret. |
 | `server.tls.hstsMs` | `172800000` (2 days) | `max-age` of the `Strict-Transport-Security` header. It is sent on TLS responses only. `0` turns it off. `includeSubDomains` and `preload` are never sent. |
 
 When TLS is on, `auth.secureCookie` is forced to `true`. At startup the server logs
 the certificate's SHA-256 fingerprint and whether it is self-signed. It also warns
-when the certificate expires within 14 days.
+when the certificate expires within 14 days — and remakes its own, if it made it, at that
+point or when the certificate no longer names a bound address.
 
 ### nodes
 
@@ -127,7 +129,7 @@ node gets its own charts and event stream.
 | `logFile` | none | The node's log file, tailed only when `log.enabled` is `true`. With the log source off (the default) this field is ignored, and a line in the startup log says so. |
 | `logStaleMs` | *(uses `log.staleMs`)* | Per-node override for how long the log may go without new bytes before the monitor reports it as silent. Use a smaller value for a node that is known to log often. |
 | `addressIndex` | none | Directory of the address index, built from this node's own block files (`<datadir>/blocks`). With it, the explorer's address page shows history, balance, unspent outputs and per-transaction amounts; without it, Core cannot answer those and the page says so. If the directory holds no finished index (no `manifest.json`) when the server starts, **the server builds one in the background** (see the next two keys). One index serves every node on the same chain. The server keeps it current as blocks arrive (a follower per directory writes `live.log` and `layers/` inside it, so the directory must be writable by the service); the page says if it is behind or has stopped following. See `docs/MEASUREMENTS.md` §30. |
-| `addressIndexBuild` | *(unset)* | `"manual"` keeps the server from building a missing address index on start. Otherwise a missing index is built inside the server on worker threads while every page keeps serving: the progress is the `address-index-building` quality flag on the Overview (phase, done of total, rows, time left, and whether it is paused), an event of kind `index` marks the start, the finish and a failure (the browser shows each as a notification), the follower starts the moment the build finishes so address pages go live with no restart, and a failure raises `address-index-build-failed` with the command to run by hand. The build is paced by the node's own RPC: it holds while the node is failing, its breaker is open or its average latency is above `rpc.slowLatencyMs`, and eases off above 40% of it. A build interrupted by a stop does not resume; the next start begins it again. `npm run setup --build-later` writes this key. |
+| `addressIndexBuild` | *(unset)* | `"manual"` keeps the server from building a missing address index on start. Otherwise a missing index is built inside the server on worker threads while every page keeps serving: the progress is the `address-index-building` quality flag on the Overview (phase, done of total, rows, time left, and whether it is paused), an event of kind `index` marks the start, the finish and a failure (the browser shows each as a notification), the follower starts the moment the build finishes so address pages go live with no restart, and a failure raises `address-index-build-failed` with the command to run by hand. The build is paced by the node's own RPC: it holds while the node is failing, its breaker is open or its average latency is above `rpc.slowLatencyMs`, and eases off above 40% of it. A build interrupted by a stop resumes on the next start: a journal in the index directory records the block files already scanned and the buckets already sorted, so only the work it cannot prove finished is done again (at most about a minute of scanning), and the log says where it resumed. A journal for another tip that the node no longer has, another index format, or one that is damaged is thrown away with the reason in the log, and the build starts over. `npm run setup --build-later` writes this key. |
 | `addressIndexWorkers` | half of a dedicated build's count, at most 4 | Worker threads for the background build. A dedicated build (`scripts/index-build.js`) uses `cpus − 4`, one per ~2.5 GB of memory, at most 16; the server takes half of that, at most 4, because the node shares the disk. **Use 1 on a spinning disk**: parallel readers seek against each other and against the node. The installer writes the number you give it. |
 | `optional` | `false` | Marks a node whose absence is expected, such as a test or benchmark node. Its failures are logged at a lower severity, a missing datadir is reported at `info` instead of `warn`, and it does not count as a required node in `/api/health`. |
 | `color` | `"#f7931a"` | Accent colour for this node in the UI. |
@@ -250,7 +252,7 @@ sessions, CSRF protection and a per-user audit trail.
 
 | key | default | meaning |
 |---|---|---|
-| `auth.enabled` | `false` | Turn accounts on. |
+| `auth.enabled` | `true` | Accounts. `false` is open mode: anyone who can reach the port reads the monitor as a viewer. |
 | `auth.dataDir` | same as `store.dir` | Where `users.json` and `sessions.json` live. |
 | `auth.sessionTtlMs` | `259200000` (72 h) | Absolute session lifetime, counted from sign-in. |
 | `auth.idleTtlMs` | `28800000` (8 h) | A session unused for this long expires. Until 2026-09-13 the two defaults were the other way round, so the idle check could never fire and a session was 8 h whatever you did. |
@@ -262,6 +264,7 @@ sessions, CSRF protection and a per-user audit trail.
 | `auth.loginMaxAttempts` | `8` | Intended: failed logins per username before lockout. See [Known quirks](#known-quirks); the effective value is 8 whatever you set. |
 | `auth.loginWindowMs` | `300000` (5 min) | Intended: window in which failed attempts are counted. See [Known quirks](#known-quirks); the effective value is 5 minutes. |
 | `auth.lockoutMs` | `600000` (10 min) | How long a username stays locked after too many failures. |
+| `auth.openNodeConfigFromNetwork` | `false` | With accounts off, the node connection form (test and save) answers only a caller on this machine's loopback address, and never behind `server.trustProxy`. A browser check cannot stop a script, and a script that can save the connection decides where the node's cookie is sent after the next restart. `true` lets any client that reaches the port use the form. With accounts on, the form needs an admin either way. |
 | `auth.cookieName` | `"blockyard_sid"` | Name of the session cookie. |
 | `auth.secureCookie` | `false` | Mark the session cookie `Secure`. Forced to `true` when `server.tls` is on. Set it yourself only when a TLS-terminating reverse proxy sits in front, because browsers never send a `Secure` cookie over plain HTTP. |
 
@@ -340,17 +343,18 @@ Available actions:
 The Markets tab fetches public BTC/USD prices, hourly candles and order books from
 five exchanges over HTTPS: Coinbase, Kraken, Bitstamp, Bitfinex and OKX (OKX quotes
 BTC/USDT). The fetches run on the server, not in the browser. This is BlockYard's
-only outbound connection other than the node. Exchanges see this server's IP
-address and a User-Agent, nothing about the node. Polling starts when a browser asks
-for market data -- the Markets and Kiosk tabs, and Overview's price line, which is on by
-default (Display settings → Markets & Price → Price line on Overview) -- and stops
-`idleAfterMs` after the last request, so an unwatched monitor makes no exchange traffic.
-With that line switched off, only Markets and Kiosk start it. The exchange list is fixed
-in code.
+only outbound connection other than the node, and **polling is off by default**: a fresh
+install makes no request to anyone but the node until someone ticks **Display settings → Markets & Price → Enable market polling** in the browser (a Display
+setting, stored in `config/blockyard.json` and shared by every screen; no restart).
+Exchanges then see this server's IP address and a User-Agent, nothing about the node. Polling starts when a browser asks for market data
+-- the Markets and Kiosk tabs, and Overview's price line (Display settings → Markets &
+Price → Price line on Overview) -- and stops `idleAfterMs` after the last request, so an
+unwatched monitor makes no exchange traffic. With that line switched off, only Markets
+and Kiosk start it. The exchange list is fixed in code.
 
 | key | default | meaning |
 |---|---|---|
-| `markets.enabled` | `true` | `false` removes the feed entirely, and no request is ever made. |
+| `markets.enabled` | `true` | `false` removes the feed entirely: no request is ever made, Markets and Kiosk say so, and the **Enable market polling** checkbox cannot turn it on. |
 | `markets.tickerMs` | `15000` | Ticker (last, bid, ask, 24 h volume) refresh. |
 | `markets.candleMs` | `300000` | Hourly candle refresh. |
 | `markets.bookMs` | `30000` | Order book refresh, for the depth chart. |
@@ -378,12 +382,13 @@ Environment variables override `config/local.json`.
 | variable | sets | type | default | meaning |
 |---|---|---|---|---|
 | `BLOCKYARD_CONFIG` | *(which file is read)* | path or `none` | `<repo>/config/local.json` | Configuration file to read. `none`/`off`/`no`/`-` reads no file. |
-| `BLOCKYARD_BIND` | `server.host` | list | `0.0.0.0` | Listen address(es), for example `127.0.0.1` or `192.0.2.10,2001:db8::10`. If both are set, this wins over `BLOCKYARD_HOST`. Ignored when the file sets `server.hosts` (see [Known quirks](#known-quirks)). |
-| `BLOCKYARD_HOST` | `server.host` | list | `0.0.0.0` | Same as `BLOCKYARD_BIND`. |
+| `BLOCKYARD_BIND` | `server.host` | list | `127.0.0.1` | Listen address(es), for example `0.0.0.0` or `192.0.2.10,2001:db8::10`. If both are set, this wins over `BLOCKYARD_HOST`. Ignored when the file sets `server.hosts` (see [Known quirks](#known-quirks)). |
+| `BLOCKYARD_HOST` | `server.host` | list | `127.0.0.1` | Same as `BLOCKYARD_BIND`. |
 | `BLOCKYARD_PORT` | `server.port` | number | `21000` | Listen port. |
 | `BLOCKYARD_ALLOW_CIDRS` | `server.allowCidrs` | list | *(empty: everyone)* | Client allowlist, for example `192.0.2.0/24,2001:db8::/32`. |
 | `BLOCKYARD_TRUST_PROXY` | `server.trustProxy` | boolean | `false` | Take the client address from `X-Forwarded-For`. |
-| `BLOCKYARD_TLS_CERT` | `server.tls.cert` | path | unset | PEM certificate. Set it together with `BLOCKYARD_TLS_KEY`. |
+| `BLOCKYARD_TLS` | `server.tls.enabled` | boolean | `true` | `0` serves plain HTTP (behind a TLS-terminating proxy). |
+| `BLOCKYARD_TLS_CERT` | `server.tls.cert` | path | unset | PEM certificate of your own, instead of the made one. Set it together with `BLOCKYARD_TLS_KEY`. |
 | `BLOCKYARD_TLS_KEY` | `server.tls.key` | path | unset | PEM private key. Set it together with `BLOCKYARD_TLS_CERT`. |
 | `BLOCKYARD_NODE_URL` | `nodes[0].rpcUrl` | URL | `http://127.0.0.1:8332` | RPC endpoint of the first node. |
 | `BLOCKYARD_DATADIR` | `nodes[0].datadir` | path | `/home/bitcoin/.bitcoin` | Data directory of the first node. It also **clears** `nodes[0].cookieFile`, so the cookie is looked up under the new datadir. |
@@ -396,7 +401,8 @@ Environment variables override `config/local.json`.
 | `BLOCKYARD_RPC_STALE_DROP` | `rpc.staleDropMs` | number | `12000` | Drop poll answers older than this. |
 | `BLOCKYARD_DATA` | `store.dir` | path | `<repo>/data` | Data directory. Also the default `auth.dataDir`. |
 | `BLOCKYARD_RETENTION_HOURS` | `store.retentionHours` | number | `72` | Chart history retention. |
-| `BLOCKYARD_AUTH` | `auth.enabled` | boolean | `false` | Turn accounts on. |
+| `BLOCKYARD_AUTH` | `auth.enabled` | boolean | `true` | Accounts; `0` is open mode. |
+| `BLOCKYARD_OPEN_NODE_CONFIG_FROM_NETWORK` | `auth.openNodeConfigFromNetwork` | boolean | `false` | In open mode, let any client use the node connection form, not only this machine. |
 | `BLOCKYARD_SECURE_COOKIE` | `auth.secureCookie` | boolean | `false` | `Secure` session cookie. Use it behind a TLS terminator; it is automatic with built-in TLS. |
 | `BLOCKYARD_ADMIN_PASSWORD` | *(none)* | string | *(generated)* | Password for the `admin` account created on first boot when accounts are on and no users exist. It is ignored once any user exists. It is a secret, so do not leave it in a unit file after first boot. |
 | `BLOCKYARD_ENABLE_ACTIONS` | `actions.enabled` | boolean | `false` | Master switch for node writes. |
@@ -404,7 +410,7 @@ Environment variables override `config/local.json`.
 | `BLOCKYARD_ALLOW_WRITES_WITHOUT_AUTH` | `actions.allowWritesWithoutAuth` | boolean | `false` | Permit actions while accounts are off. |
 | `BLOCKYARD_LOG_SOURCE` | `log.enabled` | boolean | `false` | `1` tails node log files; `0` (or unset) runs on RPC alone. |
 | `BLOCKYARD_LOG_LEVEL` | `log.level` | string | `info` | `debug`, `info`, `warn` or `error`. |
-| `BLOCKYARD_MARKETS` | `markets.enabled` | boolean | `true` | `0` turns the Markets feed off. |
+| `BLOCKYARD_MARKETS` | `markets.enabled` | boolean | `true` | `0` removes the Markets feed; the polling checkbox then cannot turn it on. |
 | `BLOCKYARD_MINING` | *(none)* | `0` or anything | on | `0` turns off miner attribution, which decodes each block's coinbase to show the pool tag. Block sizes, fees and weights are unaffected. Only the literal `0` disables it. |
 | `BLOCKYARD_MINING_BACKFILL` | *(none)* | number | `36` | How many recent blocks are attributed to miners at startup. |
 | `BLOCKYARD_MINING_TEMPLATE` | *(none)* | `0` or anything | on | `0` turns off the "block being built" card. Since 2026-09-13 the template is **assembled from the mempool this monitor already reads**, so leaving it on costs your node no RPC call at all — it costs this process ~50-70 ms of CPU per assembly. Before that it was a `getblocktemplate` worth over a second of the node's single RPC thread, which is why the switch exists. Only the literal `0` disables it. |
@@ -577,10 +583,10 @@ instead:
 BLOCKYARD_ADMIN_PASSWORD='choose-a-long-passphrase' npm start
 ```
 
-Then create personal accounts with `npm run user -- create <name> <role>`. Without
-TLS, the startup log warns that the session cookie crosses the network in clear
-text. Pair accounts with one of the TLS options below, or with a loopback bind and
-an SSH tunnel.
+Then create personal accounts with `npm run user -- create <name> <role>`. HTTPS is on by
+default with the monitor's own certificate; if you turn it off (`BLOCKYARD_TLS=0`) on a bind
+that crosses the LAN, the startup log warns that the session cookie crosses the network in
+clear text. Pair that with a TLS-terminating proxy, or with a loopback bind and an SSH tunnel.
 
 Accounts plus two node writes that operators may run:
 
@@ -596,7 +602,8 @@ Accounts plus two node writes that operators may run:
 
 ### TLS
 
-Built-in HTTPS on every listener:
+HTTPS is on by default, with a certificate the server makes for itself. A certificate of your
+own, on every listener:
 
 ```json
 {
@@ -632,9 +639,9 @@ matters here too: it makes the proxy the only way in.
 
 ### Binding to specific addresses
 
-The default `0.0.0.0` listens on every IPv4 interface the machine has, including VPN
-tunnels and container bridges. To serve exactly one LAN address and one VPN
-address, and admit only clients from those networks:
+The default `127.0.0.1` answers this machine only. `0.0.0.0` listens on every IPv4
+interface the machine has, including VPN tunnels and container bridges. To serve exactly
+one LAN address and one VPN address, and admit only clients from those networks:
 
 ```json
 {
@@ -661,9 +668,11 @@ Things to know about specific binds:
 - For this machine only, use `"hosts": ["127.0.0.1"]` and reach it with
   `ssh -L 21000:127.0.0.1:21000 user@monitor-host`.
 
-### Markets off
+### Markets off, for good
 
-No outbound connections except to the node:
+Out of the box there are no outbound connections except to the node, because market polling is
+a checkbox that ships unticked (**Display settings → Markets & Price → Enable market polling**). To be certain a machine never reaches out whatever anyone
+ticks, remove the feed from the server:
 
 ```json
 {
@@ -713,7 +722,7 @@ sudo systemctl edit blockyard
 
 ```ini
 [Service]
-Environment=BLOCKYARD_AUTH=1
+Environment=BLOCKYARD_BIND=192.0.2.10
 Environment=BLOCKYARD_DATA=/var/lib/blockyard
 ```
 
@@ -738,7 +747,7 @@ accounts and chart history, and never commit or publish it.
 | `audit.1.jsonl` … `audit.N.jsonl` | the server | sensitive | Rotated audit files, newest first. There are at most `store.auditKeep` of them, and rotation happens at `store.auditMaxBytes`. |
 | `history.json` | the server | no, but reveals node details | Snapshot of chart series, events and recent blocks, restored on startup and pruned to `store.retentionHours`. Can be tens of MB. |
 | `pool-aliases.json` | **you**, optionally | no | Hand-written display names for mining pools: a JSON object from pool key to label, for example `{"examplepool": "Example Pool"}`. The pool key is the lowercased coinbase tag the Mining page shows, or `unknown:<hex>` for blocks without a readable tag. Absent by default, in which case the coinbase text is shown as written. |
-| `pool-map.json` | `node scripts/pool-map.js` | no | Coinbase-tag-to-pool-name map built from the public mempool/mining-pools data set (MIT), with source URL and content hash. **A copy ships in `config/pool-map.json`** (151 pools), so pools are labelled from the first start; one here, written by the script (which needs network access), **overrides** the shipped copy. The server reads `BLOCKYARD_POOL_MAP` if set, else `<store.dir>/pool-map.json` if it exists, else the shipped file. The script always writes `<repo>/data/pool-map.json`, so move it, or set `BLOCKYARD_POOL_MAP`, if you use a different `store.dir`. `--file <pools-v2.json>` builds it offline. |
+| `pool-map.json` | `node scripts/pool-map.js` | no | Coinbase-tag-to-pool-name map built from the public mempool/mining-pools data set (MIT), with source URL and content hash. **A copy ships in `config/pool-map.json`** (151 pools), so pools are labelled from the first start; one here, written by the script (which needs network access), **overrides** the shipped copy. The server reads `BLOCKYARD_POOL_MAP` if set, else `<store.dir>/pool-map.json` if it exists, else the shipped file. The script always writes `<repo>/data/pool-map.json`, so move it, or set `BLOCKYARD_POOL_MAP`, if you use a different `store.dir`. `--file <pools-v2.json>` builds it offline. Before replacing an existing file it prints the pools added, removed and changed and writes only with `--yes` or a "y" at the prompt; `--expect-sha256 <hex>` refuses a download that is not exactly those bytes; redirects are followed to HTTPS only. |
 | `fake-node.log` | development mode only | no | Log of the simulated node when `BLOCKYARD_FAKE_NODE=1`. |
 | `*.tmp` | the server | as the target file | Short-lived files from atomic writes (write, fsync, rename). A leftover one after a crash is safe to delete. |
 

package/docs/DEFECTS.md

@@ -744,7 +744,10 @@ Kept as checked rather than deleted, so nobody re-derives them.
   budget has no room for a fourth figure and rules 4/9 forbid merging them. They now
   appear as three separately-labelled rows behind `detail`, where "not printed by this
   build" is a possible answer and the absence is visible.
-- [ ] **An interrupted index build starts over.** Noted 2026-09-14. `buildIndex` empties its output
+- [x] **An interrupted index build starts over.** Noted 2026-09-14. Fixed 2026-09-16: the build
+  keeps `build-journal.json` beside its output and resumes per scanned block file and per sorted
+  bucket, cutting the buckets back to what the journal proves (`server/chain/index/build.js`, THE
+  BUILD JOURNAL). What was noted: `buildIndex` empties its output
   directory before it begins (`server/chain/index/build.js`), and the server treats an index as
   built only when `manifest.json` exists (`server/main.js`), so a build stopped by Ctrl-C, a crash
   or a reboot keeps nothing of its scan: the installer says so when it is stopped, and the server's

package/docs/GETTING-STARTED.md

@@ -137,8 +137,8 @@ node scripts/index-build.js --out data/index --workers 4
 ```
 
 Last question: **start BlockYard now, in this terminal?** — yes runs it right there (Ctrl-C
-stops it, and stops a background build with it; there is no resume, so it starts over on the
-next start); `--start` does the same without asking.
+stops it, and stops a background build with it; the next start resumes the build where it
+stopped); `--start` does the same without asking.
 
 Scripted, with no questions (a fresh machine, a Makefile):
 
@@ -147,10 +147,17 @@ node scripts/setup.js --yes --rpc-url http://127.0.0.1:8332 \
   --datadir "$HOME/Library/Application Support/Bitcoin" --index-dir "$PWD/data/index" --workers 4
 ```
 
-Every question has a flag: `--datadir`, `--rpc-url`, `--label`, `--rpc-user` / `--rpc-password`,
-`--host`, `--port`, `--index-dir`, `--workers`. `--build-here` builds in the terminal and
-`--build-later` leaves it to you; `--start` boots the monitor at the end; `--force` replaces an
-existing `config/local.json` (with a backup).
+Every question has a flag: `--datadir`, `--rpc-url`, `--label`, `--rpc-user` /
+`--rpc-password-file`, `--host`, `--port`, `--index-dir`, `--workers`. `--build-here` builds in the
+terminal and `--build-later` leaves it to you; `--start` boots the monitor at the end; `--force`
+replaces an existing `config/local.json` (with a backup, also mode `0600`, and git-ignored).
+
+The RPC password, when the node needs one: `--rpc-password-file PATH` reads the first line of a
+file, and `--rpc-password -` reads it from stdin (with `--yes`, e.g.
+`pass show node/rpc | node scripts/setup.js --yes --rpc-user monitor --rpc-password - ...`).
+`--rpc-password P` still works but prints a warning: a password on the command line is visible to
+every user of the machine in `ps` and stays in your shell history. Typed at the interactive prompt,
+it is not echoed.
 
 ## 5. Run it
 
@@ -158,12 +165,15 @@ existing `config/local.json` (with a backup).
 npm start
 ```
 
-The log says `BlockYard 0.0.9 listening on http://127.0.0.1:21000`, then `address index: building
+The log says `BlockYard 0.1.1 listening on https://127.0.0.1:21000` (its own self-signed
+certificate, made on this first start; the browser warns once and remembers it), then `created the
+first admin account (admin)` with a generated password **shown once** — copy it, or set
+`BLOCKYARD_ADMIN_PASSWORD` before the first start to choose it — then `address index: building
 /Users/you/blockyard/data/index from main's block files with 4 workers -- the Overview shows the
 progress` (and `address index build: paused while the node's RPC is answering in … s` /
 `resumed` if the node struggles) and, when that is done, `address index built: … rows to block N
 in … min -- address pages are live` followed by `address index /Users/you/blockyard/data/index:
-following main from block N`. Open <http://127.0.0.1:21000>. The
+following main from block N`. Open <https://127.0.0.1:21000> and sign in as `admin`. The
 Overview fills in within about thirty seconds; Block space lands a little after. Open Explorer,
 click the latest block, then any output address: while the index is building the page says so
 with the progress; once it is built, its balance, history and unspent outputs appear.