blockyard 0.0.1 → 0.0.9

package/docs/PRIVATE-LEADERBOARD.md

@@ -0,0 +1,230 @@
+# Blockchain leaderboards for the Diversions — scoping report
+
+**Private local document.** Gitignored via `docs/PRIVATE-*.md`. Not a decision, not a commitment —
+a scoping of what this would actually take, written 2026-09-13.
+
+> Note on the privacy guard: `test/privacy.test.js` scans `git ls-files`, so an ignored file is
+> outside it. That is how a real LAN address reached a commit earlier today. Nothing sensitive
+> should go in here on the assumption a test will catch it.
+
+---
+
+## The short answers
+
+| question | answer |
+|---|---|
+| Do we need a Bitcoin address? | **Only if you want on-chain writes or signed identity.** A working leaderboard needs neither. |
+| How do people submit scores? | **A replay, not a score.** The server re-plays the game and computes the score itself. |
+| Can we do it for free? | **Yes, entirely** — if "use the blockchain" means *seed from a block hash and anchor by timestamp*. **No** if it means *one transaction per score*. |
+| What is the hard part? | **Not the blockchain.** It is proving a score was earned rather than typed into a POST body. |
+
+---
+
+## 1. The insight this whole design rests on
+
+The three games were built with a pure-rules / screen split, and the rules are **deterministic by
+construction**. This was done for testability, but it is exactly what a trustworthy leaderboard
+needs.
+
+Verified headless under Node on 2026-09-13:
+
+```
+tetris.js   newGame(seed) with a seeded rng(seed); newGame(12345) twice → identical queue
+arkanoid.js hash01(key) everywhere, NO Math.random — capsules, minion lanes, drift phases
+breakout.js launch angle is an argument, not a roll
+all three   "no DOM, no canvas, no clock"; they import and run fine in plain Node
+```
+
+Entry points for a replay: `step(g, dtMs)` (breakout, arkanoid), `tick(g)` / `move` / `rotate` /
+`hardDrop` (tetris). `tetrust.js` already drives the rules from a **fixed-step accumulator**
+(`while (G.acc >= ms)`), so a game is already a discrete sequence of steps, not a wall-clock
+animation.
+
+**Therefore the server can replay a submitted game and recompute the score.** That is real
+anti-cheat, and it does not involve Bitcoin at all.
+
+## 2. What "use the blockchain" can usefully mean here
+
+Four options, ranked by what they actually buy:
+
+### (a) Block hash as the game seed — free, and the best fit
+
+The tip hash at game start becomes the seed. This gives three properties for nothing:
+
+- **Unpredictable** — nobody can pre-compute a favourable piece order, because nobody knows block
+  N+1's hash. (Miners have a marginal grinding advantage; irrelevant at this stake.)
+- **A lower time bound** — a game seeded from block N provably was not played before block N. That
+  is a real timestamp, from our own node, at zero cost.
+- **A fair shared round** — everyone playing "the block 966,781 round" gets the same piece order, so
+  scores are comparable in a way they never are with per-player seeds. This is the genuinely novel
+  bit: a *per-block tournament*.
+
+We already have the data: `/api/blocks` returns hashes, and the monitor is watching a node anyway.
+
+### (b) OpenTimestamps anchoring — free, proves *when*
+
+Hash the leaderboard state periodically and submit the digest to public OTS calendar servers, which
+aggregate thousands of digests into one transaction. Produces a Bitcoin-anchored proof that the
+leaderboard said X at time T, and costs nothing because the calendar operator pays the fee.
+
+Cost: one outbound HTTPS call to a third party, which conflicts with this project's "outbound
+connections are limited and on demand" stance — it would need to be opt-in and documented in
+`docs/SECURITY.md` alongside the exchange APIs.
+
+### (c) OP_RETURN per score — cheap, not free, and probably wrong
+
+Real numbers from the node right now: fee estimates ≈ **5.65e-06 BTC/kvB ≈ 0.57 sat/vB**, relay
+floor 1 sat/vB. A minimal OP_RETURN transaction is ~200 vB → **~200 sats ≈ 15¢** at $77k.
+
+But: needs a funded wallet, key custody, a UTXO set to manage, change handling, fee bumping when the
+mempool moves, and it puts arcade scores in every archival node on Earth, for ever. It also requires
+passing the node-writes gate, which currently needs four independent yeses and is off by default.
+
+**Recommendation: no.** Use (a) for fairness and (b) for timestamping.
+
+### (d) Signed scores for pseudonymous identity — free via RPC, but legacy addresses only
+
+A player signs their submission with a Bitcoin key; the address is their leaderboard identity. No
+funds, no on-chain footprint.
+
+**Partly wrong as first written, corrected 2026-09-13 after the operator asked "why do we need
+crypto primitives — can't we just use the bitcoind rpc?".** They were right.
+
+*Verifying* a user's signature needs no crypto code at all: **`verifymessage` is already permitted
+by our own allowlist** and the node does the pubkey recovery. Confirmed it genuinely evaluates
+rather than stubbing — a malformed signature errors `-3 Malformed base64 encoding`, and a bech32
+address errors `Address does not refer to key`.
+
+What survives is an **asymmetry**: the node can verify, but it cannot sign *for us*. The Umbrel has
+no wallet loaded (`listwallets` → `[]`), `signmessage` is in our own deny list as a wallet mutator,
+and asking a user's node to hold the monitor's identity is the wrong layer anyway. So:
+
+- **users proving they control an address** → pure RPC, no crypto, no dependency;
+- **the monitor holding its own identity and signing attestations** → local keys, which is a
+  custody decision rather than a coding one.
+
+Node 22 does have enough for the second if wanted: secp256k1 DER sign/verify, `ripemd160`, and
+therefore hash160 — a P2WPKH address derives zero-dependency (verified: produced a valid bech32
+address with a ~40-line encoder). It is *recovery* from a compact signature that Node lacks, and
+only the monitor-side signing path would need it.
+
+**THE REAL CONSTRAINT IS ADDRESS TYPE, NOT CRYPTO.** Measured against the node on 2026-09-13:
+
+| address | `verifymessage` |
+|---|---|
+| P2PKH `1...` | **works** — returned `false` for a wrong signature, i.e. it evaluated |
+| P2SH `3...` | error: `Address does not refer to key` |
+| P2WPKH `bc1q...` | error: `Address does not refer to key` |
+| P2TR `bc1p...` | error: `Address does not refer to key` |
+
+Core's `verifymessage` implements the old "Bitcoin Signed Message" scheme, which is defined only
+for P2PKH. **Most modern wallets — including the one on an Umbrel — hand out `bc1q` or `bc1p`
+addresses, and those users cannot sign this way at all.** That is the main obstacle to the
+user-identity design, and no amount of our own code fixes it, because the limitation is in the
+signing standard rather than in us.
+
+Options, in order of how much they cost:
+
+1. **Accept legacy-only**, and say so in the UI: "paste a `1...` address". Many wallets can still
+   produce one; Sparrow, Electrum and Core itself can sign with a legacy key. Free, honest, and
+   excludes some users.
+2. **BIP-322** — the modern generalised signing scheme covering segwit and taproot, and what `bc1`
+   wallets actually implement. **Checked, and the answer is no:** Core 31.1.0 (`/Satoshi:31.1.0/`)
+   exposes `verifymessage`, `signmessage`, `signmessagewithprivkey`, `signrawtransactionwithkey`,
+   `signrawtransactionwithwallet` and `enumeratesigners` — and **no BIP-322 method of any name**.
+   So the node cannot verify a segwit or taproot signature for us. Supporting `bc1` identities means
+   implementing BIP-322 verification ourselves, which needs precisely the secp256k1 primitives the
+   RPC route was chosen to avoid. That is a substantial piece of work and a dependency-rule
+   conversation, not an afternoon.
+3. **Do not use Bitcoin signing for identity at all** — a chosen display name plus the replay proof.
+   The replay is what makes a score trustworthy; the address only says *who*. If the leaderboard is
+   local or shared-by-export, a name is sufficient and costs nothing.
+
+## 3. Recommended design
+
+**Decision taken 2026-09-13: identity means _users prove who they are_** — the monitor holds no
+key, signs nothing, and custodies nothing. Everything below assumes that.
+
+**Per-block tournaments, verified by replay, identified by address, anchored by timestamp.**
+
+1. A round opens when a block lands. Its hash seeds every game in that round.
+2. The player plays locally, exactly as now.
+3. On game over, the client submits a **replay**: `{ game, seedBlock, seedHash, steps[], claimedScore }`
+   where `steps[]` is the discrete input sequence the fixed-step loop already produces.
+4. The server imports the same pure rules module, replays the steps, and computes the score itself.
+   The claimed score is ignored except as a cross-check — a mismatch is a rejected submission.
+5. Accepted entries join the round's board. When the round closes (next block), the board is hashed
+   and optionally OTS-anchored.
+
+**Identity, if a player wants one** (optional — an anonymous entry is still replay-verified):
+
+- The server issues a challenge string tied to the round (`blockyard:<round>:<nonce>`).
+- The player signs it in their own wallet and pastes address + signature.
+- We call `verifymessage` — already permitted by the allowlist, no crypto code, no key on our box.
+- `validateaddress` first, so a `bc1` address is refused with *"legacy `1...` addresses only, see
+  BIP-322 note"* rather than a confusing `Address does not refer to key`.
+
+Two allowlist additions are needed, one line each: `validateaddress` and `deriveaddresses`. Both
+are read-only and currently denied only because nothing had asked for them.
+
+**Testing this path needs no wallet.** `signmessagewithprivkey` takes a WIF and a message and
+returns a signature, so a test can generate a genuine legacy-address signature as a fixture and
+assert that our verification accepts it and rejects a tampered message — without depending on a
+wallet existing on whatever node the suite runs against. That matters: the Umbrel has none
+(`listwallets` → `[]`), and the fake node in `scripts/fake-node.js` would otherwise have to grow a
+signing implementation.
+
+Why this is worth doing: the leaderboard is **verifiable by anyone**. Given the replay, any third
+party can recompute the score using the same public rules file. That is a much stronger claim than
+most leaderboards can make, and it comes from the determinism that already exists.
+
+## 4. What it actually costs to build
+
+| piece | size | notes |
+|---|---|---|
+| Record inputs in the three screen modules | **M** | The fixed-step loop already exists; capture `(stepIndex, action)` pairs. Arkanoid is the fiddliest — mouse position per step needs quantising or it is unreplayable. |
+| Headless replay harness | **S** | The rules already import under Node. Mostly a loop and a score readout. |
+| Replay determinism tests | **M** | The real work: proving client and server agree on every float. **See §5.** |
+| Submission API + storage | **S** | One POST, one GET, a JSON file per round. |
+| Round lifecycle from block events | **S** | The monitor already emits new-tip events. |
+| Leaderboard UI | **M** | A page, a per-round board, a "verify this replay yourself" button. |
+| OTS anchoring | **S** | Optional, opt-in, one HTTPS call. |
+| **Total** | **~2-4 days** | Assuming local/self-hosted scope. |
+
+## 5. The risks, honestly
+
+- **Floating-point determinism is the sharp edge.** `breakout.js` and `arkanoid.js` advance ball
+  physics with floats. Same JS engine, same order of operations, same result — but client and server
+  are *different Node/browser builds*, and any divergence makes an honest player's replay fail
+  verification. **This must be proven before building anything else**: record N real games in a
+  browser, replay them server-side, and assert bit-identical scores. If it does not hold, the fix is
+  integer or fixed-point physics, which is a rules rewrite. Tetris is much safer here — it is
+  integer grid logic.
+- **Replay size.** A ten-minute Arkanoid game at 60 steps/second is ~36,000 steps. Compressible
+  (most steps are "no input"), but it is not a 20-byte score.
+- **A leaderboard is inherently shared, and this app is not.** Blockyard is a single-user LAN
+  monitor that ships open-access with a `viewer` ceiling. A *global* leaderboard means **you run a
+  hosted service** — with moderation, abuse handling, data retention, and an endpoint strangers
+  POST to. That is a different product with different obligations, not a feature of this one.
+  Three honest scopes:
+  - **Local only** — verified replays, your own high scores, no server. Nearly free to build.
+  - **Shared export** — a signed/anchored replay file you can hand to someone else to verify.
+  - **Hosted leaderboard** — the real product, and the one with ongoing cost and duty of care.
+- **Replay does not stop a bot.** It proves the score was *achievable under the rules*, not that a
+  human earned it. A perfect Tetris bot submits perfectly valid replays. Per-block rounds limit the
+  damage (everyone gets one shot at that seed) but do not eliminate it.
+- **Scope creep into custody.** The moment there is a funded address, this stops being a monitor and
+  becomes something holding other people's money-adjacent state. Option (c) is where that starts,
+  which is the strongest argument against it.
+
+## 6. Recommendation
+
+1. **Spike the determinism question first** (half a day). Everything else is wasted if browser and
+   server disagree on ball physics.
+2. Build **local-only** verified replays with block-hash seeds. Free, no address, no third party, no
+   hosted service, and it delivers the interesting half: provably fair rounds and self-verifying
+   scores.
+3. Add **OTS anchoring** only if "provably at this time" matters to you. Opt-in, documented as an
+   outbound connection.
+4. **Do not** put scores on-chain per-game, and **do not** introduce a funded wallet.
+5. Treat a hosted global leaderboard as a separate product decision, not a Diversions feature.