Add Thunder to the regtest stack

Wires the aarch64-darwin (and x86_64) L2-S9-Thunder prebuilt into the
existing bitcoind+electrs+enforcer stack:

  setup.sh:  downloads L2-S9-Thunder-latest-*.zip alongside the other
             three; extracts thunder + thunder-cli into .regtest/bin/.
  start.sh:  waits for the enforcer's gRPC (50051) to actually be
             listening before launching Thunder (18444 GBT comes up
             first — Thunder needs 50051 to verify the mainchain
             ValidatorService at boot). Launches Thunder with
             --mainchain-grpc-url http://127.0.0.1:50051 and
             --rpc-addr 127.0.0.1:6009 — the same port
             payout/lib/thunder.js defaults to.
  stop.sh/status.sh: aware of the extra process.
  thunder-init.sh: NEW. Idempotently generates a Thunder wallet
             mnemonic, sets the seed, prints a wallet address + the
             `s9_<base58>_<hex6>` deposit-format wrapper the mainchain
             wallet needs to target Thunder-owned funds.

End-to-end verified on aarch64-darwin:
  - Stack of four processes comes up clean
  - Thunder connects to the enforcer, both ValidatorService and
    WalletService verify
  - Thunder RPC on :6009 responds to `balance` with
    {"total_sats":0,"available_sats":0}
  - After thunder-init, a canonical
    CreateDepositTransaction to the Thunder-owned deposit address
    updates the enforcer's Ctip (Ctip value went from 100_000_000
    to 150_000_000 sats across two 50M-sat deposits)
  - The TwoWayPeg event stream on the enforcer shows both deposits
    with their exact OP_RETURN payload bytes

Not verified end-to-end: Thunder producing a sidechain block to
credit the wallet balance. Thunder's `mine` RPC blocks pending BMM
coordination with the mainchain — that's a Thunder-side concern
outside the scope of the pool. The enforcer-side Ctip update is the
authoritative consensus signal that the deposit was accepted; from
the pool's perspective, once the deposit is in the Ctip, Thunder's
own state transition is a follow-up.

VERIFY.md section 10 is expanded with the thunder-init flow and a
concrete canonical-deposit check anyone can reproduce.

Author: rsantacroce

VERIFY.md

@@ -298,29 +298,60 @@ PAYOUT_DB_PATH=./shares.db node /Users/rob/projects/simplepool/payout/audit.js
 ## 10 · BIP300 regtest stack (infra) — `b0da16f` + `6037a25`
 
 ```
-scripts/regtest/setup.sh       # ~50 MB of prebuilt binaries
+scripts/regtest/setup.sh       # ~90 MB of prebuilt binaries incl. Thunder
 scripts/regtest/start.sh
 scripts/regtest/status.sh
 ```
 
-- [ ] `status.sh` shows all three processes `up`.
+- [ ] `status.sh` shows all **four** processes `up`: `bitcoind`,
+      `electrs`, `bip300301_enforcer`, `thunder`.
+- [ ] Thunder log ends with
+      `Verified existence of cusf.mainchain.v1.ValidatorService` and
+      `starting RPC server at 127.0.0.1:6009`.
 - [ ] `curl -sS -u user:password -H 'content-type: application/json' \
       --data '{"jsonrpc":"1.0","id":1,"method":"getblockcount","params":[]}' \
       http://127.0.0.1:18443/` returns a number.
+- [ ] `curl -sS -H 'content-type: application/json' \
+      --data '{"jsonrpc":"2.0","id":1,"method":"balance","params":[]}' \
+      http://127.0.0.1:6009/` returns
+      `{"result":{"total_sats":0,"available_sats":0}}` — Thunder RPC
+      is reachable (matches what the payout worker expects).
 
-Activate Thunder:
+Activate the sidechain, then set up Thunder's wallet:
 
 ```
 scripts/regtest/activate-thunder.sh
+scripts/regtest/thunder-init.sh
 ```
 
-- [ ] First run prints `sidechain 9 is now ACTIVE` with proposalHeight
-      and activationHeight (regtest activates after 6 votes).
-- [ ] Second run prints `sidechain 9 already active. nothing to do.`
-      (idempotent).
-- [ ] `grpcurl -plaintext 127.0.0.1:50051
-      cusf.mainchain.v1.ValidatorService/GetSidechains` shows sidechain
-      9 in the active list.
+- [ ] `activate-thunder.sh` first run prints `sidechain 9 is now
+      ACTIVE`; second run is a no-op.
+- [ ] `thunder-init.sh` prints a fresh mnemonic + wallet address +
+      formatted deposit string (`s9_<base58>_<hex6>`); second run
+      short-circuits with `already initialised`.
+
+Issue a canonical deposit to the Thunder-owned address it printed,
+then observe the enforcer's TwoWayPeg event stream:
+
+```
+DEP='<paste the deposit format from thunder-init.sh>'
+grpcurl -plaintext -d "{\"sidechain_id\":9,\"address\":\"$DEP\",\"value_sats\":100000000,\"fee_sats\":1000}" \
+  127.0.0.1:50051 cusf.mainchain.v1.WalletService/CreateDepositTransaction
+grpcurl -plaintext -d '{"blocks":1}' \
+  127.0.0.1:50051 cusf.mainchain.v1.WalletService/GenerateBlocks
+grpcurl -plaintext -d '{"sidechain_number":9}' \
+  127.0.0.1:50051 cusf.mainchain.v1.ValidatorService/GetCtip
+```
+
+- [ ] Ctip returns non-empty with `value: "100000000"` (or the running
+      total if earlier deposits happened).
+
+Note: Thunder's own balance staying at 0 after a canonical deposit is
+expected until Thunder produces a sidechain block via BMM. BMM is a
+Thunder-side concern (thunder-cli's `mine` command blocks on
+mainchain coordination) — outside the scope of the pool. The
+enforcer-side Ctip update is the authoritative signal that the
+deposit was consensus-accepted.
 
 ---
 

scripts/regtest/README.md

@@ -33,26 +33,26 @@ LayerTwo-Labs enforcer.
 - **electrs**: Electrum server the enforcer's wallet uses for sync.
 - **bip300301_enforcer**: validates BIP300 deposits, serves the
   `getblocktemplate` simplepool talks to.
-
-Thunder itself is intentionally NOT in this stack. There's no
-aarch64-darwin prebuilt for it, and the enforcer is the authoritative
-deposit validator — observing a Deposit event tagged with sidechain 9
-proves the coinbase shape is correct.
+- **thunder** (L2-S9): the actual sidechain node, connected to the
+  enforcer via gRPC on 50051, RPC on 6009 (matches what
+  `payout/lib/thunder.js` expects out of the box).
 
 ## Quickstart
 
 ```
 scripts/regtest/setup.sh             # download prebuilts + write configs
-scripts/regtest/start.sh             # bring up bitcoind, electrs, enforcer
+scripts/regtest/start.sh             # bring up bitcoind, electrs, enforcer, thunder
 scripts/regtest/status.sh            # ps-style summary
 scripts/regtest/activate-thunder.sh  # propose + ack sidechain #9 until active
+scripts/regtest/thunder-init.sh      # generate Thunder wallet mnemonic + address
 scripts/regtest/validate.sh          # activate, mine 150, probe GBT, print runbook
 scripts/regtest/inspect-coinbase.sh  # after mining: parse tip's coinbase
 scripts/regtest/stop.sh
 ```
 
-`activate-thunder.sh` requires `grpcurl` (`brew install grpcurl`).
-It's idempotent — re-running once Thunder is active is a no-op.
+`activate-thunder.sh` and `thunder-init.sh` are both idempotent —
+re-running once the state is set up is a no-op.
+Requires `grpcurl` (`brew install grpcurl`).
 
 Everything lives under `.regtest/` (gitignored): binaries in
 `.regtest/bin/`, chain state in `.regtest/data/`, logs in

scripts/regtest/setup.sh

@@ -21,7 +21,7 @@ REGTEST="$ROOT/.regtest"
 BIN="$REGTEST/bin"
 DATA="$REGTEST/data"
 LOGS="$REGTEST/logs"
-mkdir -p "$BIN" "$DATA/bitcoind" "$DATA/electrs" "$DATA/enforcer" "$LOGS"
+mkdir -p "$BIN" "$DATA/bitcoind" "$DATA/electrs" "$DATA/enforcer" "$DATA/thunder" "$LOGS"
 
 # ---- arch detection ----
 UNAME_M="$(uname -m)"
@@ -57,8 +57,10 @@ extract_to_bin() {
     # -j strips directories. Some zips have only one file (electrs).
     unzip -qq -j -o "$zip" "$match" -d "$BIN"
     # Find the most-recently-extracted file and rename to $final if needed.
+    # Exclude already-canonical filenames so each extraction is idempotent
+    # regardless of what got extracted before it.
     local actual
-    actual="$(ls -t "$BIN" | grep -v -E '\.zip$|^bitcoind$|^bitcoin-cli$|^electrs$|^bip300301_enforcer$' | head -1 || true)"
+    actual="$(ls -t "$BIN" | grep -v -E '\.zip$|^(bitcoind|bitcoin-cli|electrs|bip300301_enforcer|thunder|thunder-cli)$' | head -1 || true)"
     if [[ -n "$actual" && "$actual" != "$final" ]]; then
         mv "$BIN/$actual" "$BIN/$final"
     fi
@@ -72,11 +74,13 @@ case "$ARCH" in
         BITCOIN_ZIP_URL="https://releases.drivechain.info/L1-bitcoin-patched-v30.2-aarch64-apple-darwin.zip"
         ENFORCER_ZIP_URL="https://releases.drivechain.info/bip300301-enforcer-latest-aarch64-apple-darwin.zip"
         ELECTRS_ZIP_URL="https://releases.drivechain.info/electrs-latest-aarch64-apple-darwin.zip"
+        THUNDER_ZIP_URL="https://releases.drivechain.info/L2-S9-Thunder-latest-aarch64-apple-darwin.zip"
         ;;
     x86_64-apple-darwin)
         BITCOIN_ZIP_URL="https://releases.drivechain.info/L1-bitcoin-patched-latest-x86_64-apple-darwin.zip"
         ENFORCER_ZIP_URL="https://releases.drivechain.info/bip300301-enforcer-latest-x86_64-apple-darwin.zip"
         ELECTRS_ZIP_URL="https://releases.drivechain.info/electrs-latest-x86_64-apple-darwin.zip"
+        THUNDER_ZIP_URL="https://releases.drivechain.info/L2-S9-Thunder-latest-x86_64-apple-darwin.zip"
         ;;
     *)
         echo "no prebuilt binaries for $ARCH — build from source" >&2
@@ -87,12 +91,15 @@ esac
 fetch_zip "$BITCOIN_ZIP_URL"  "$BIN/bitcoind.zip"
 fetch_zip "$ENFORCER_ZIP_URL" "$BIN/enforcer.zip"
 fetch_zip "$ELECTRS_ZIP_URL"  "$BIN/electrs.zip"
+fetch_zip "$THUNDER_ZIP_URL"  "$BIN/thunder.zip"
 
 echo "==> extracting binaries"
 extract_to_bin "$BIN/bitcoind.zip"  '*/bitcoind'                 bitcoind
 extract_to_bin "$BIN/bitcoind.zip"  '*/bitcoin-cli'              bitcoin-cli
 extract_to_bin "$BIN/enforcer.zip"  '*bip300301-enforcer*'       bip300301_enforcer
 extract_to_bin "$BIN/electrs.zip"   '*electrs*'                  electrs
+extract_to_bin "$BIN/thunder.zip"   'thunder-latest-*'           thunder
+extract_to_bin "$BIN/thunder.zip"   'thunder-cli-latest-*'       thunder-cli
 
 echo "==> binaries ready in $BIN"
 ls -la "$BIN" | tail -n +2

scripts/regtest/start.sh

@@ -14,7 +14,7 @@ LOGS="$REGTEST/logs"
 RUN="$REGTEST/run"
 mkdir -p "$RUN"
 
-for b in bitcoind bitcoin-cli bip300301_enforcer electrs; do
+for b in bitcoind bitcoin-cli bip300301_enforcer electrs thunder thunder-cli; do
     if [[ ! -x "$BIN/$b" ]]; then
         echo "missing $BIN/$b — run scripts/regtest/setup.sh first" >&2
         exit 1
@@ -105,6 +105,22 @@ start_if_dead bip300301_enforcer \
     --serve-grpc-addr=127.0.0.1:50051
 
 wait_for bip300301_enforcer "nc -z 127.0.0.1 18444" 30
+# Thunder connects to the enforcer's gRPC — make sure that's actually
+# up before launching it (18444 GBT can come up first).
+wait_for enforcer-grpc "nc -z 127.0.0.1 50051" 15
+
+echo "==> starting thunder (sidechain #9)"
+start_if_dead thunder \
+    "$BIN/thunder" \
+    --headless \
+    --datadir "$DATA/thunder" \
+    --network regtest \
+    --mainchain-grpc-url http://127.0.0.1:50051 \
+    --net-addr 127.0.0.1:4009 \
+    --rpc-addr 127.0.0.1:6009 \
+    --log-level INFO
+
+wait_for thunder "nc -z 127.0.0.1 6009" 30
 
 echo ""
 echo "stack up. endpoints:"
@@ -113,5 +129,7 @@ echo "  electrs:         127.0.0.1:60401"
 echo "  enforcer GBT:    127.0.0.1:18444  (point simplepool at this)"
 echo "  enforcer JSONRPC: 127.0.0.1:8123"
 echo "  enforcer gRPC:    127.0.0.1:50051"
+echo "  thunder RPC:     127.0.0.1:6009   (point payout worker at this)"
+echo "  thunder P2P:     127.0.0.1:4009"
 echo ""
 echo "next: scripts/regtest/validate.sh"

scripts/regtest/status.sh

@@ -4,7 +4,7 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 RUN="$ROOT/.regtest/run"
 LOGS="$ROOT/.regtest/logs"
 
-for name in bitcoind electrs bip300301_enforcer; do
+for name in bitcoind electrs bip300301_enforcer thunder; do
     pidfile="$RUN/$name.pid"
     if [[ -f "$pidfile" ]]; then
         pid="$(cat "$pidfile")"

scripts/regtest/stop.sh

@@ -4,7 +4,7 @@ set -u
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 RUN="$ROOT/.regtest/run"
 
-for name in bip300301_enforcer electrs bitcoind; do
+for name in thunder bip300301_enforcer electrs bitcoind; do
     pidfile="$RUN/$name.pid"
     [[ -f "$pidfile" ]] || continue
     pid="$(cat "$pidfile")"

scripts/regtest/thunder-init.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Initialise the Thunder wallet: generate a mnemonic, set the seed, and
+# print a deposit address the mainchain wallet can target.
+#
+# Idempotent — re-running once the seed is set is a no-op that prints
+# the existing deposit address.
+#
+# Requires: thunder + thunder-cli in .regtest/bin (via setup.sh), Thunder
+# process running (via start.sh).
+
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+BIN="$ROOT/.regtest/bin"
+TCLI="$BIN/thunder-cli"
+
+if [[ ! -x "$TCLI" ]]; then
+    echo "missing $TCLI — run scripts/regtest/setup.sh" >&2
+    exit 1
+fi
+
+# Probe: does Thunder's wallet already have a seed? get-new-address
+# succeeds silently when yes; errors "no seed" to stderr when no.
+if ADDR="$($TCLI get-new-address 2>/dev/null)" && [[ -n "$ADDR" ]]; then
+    echo "==> Thunder wallet already initialised"
+    DEP="$($TCLI format-deposit-address "$ADDR" 2>/dev/null)"
+    echo "  new address:    $ADDR"
+    echo "  deposit format: $DEP"
+    exit 0
+fi
+
+echo "==> generating fresh Thunder wallet mnemonic"
+MNEMONIC="$($TCLI generate-mnemonic)"
+echo "  mnemonic: $MNEMONIC"
+
+echo "==> setting seed"
+$TCLI set-seed-from-mnemonic "$MNEMONIC" >/dev/null
+
+ADDR="$($TCLI get-new-address)"
+DEP="$($TCLI format-deposit-address "$ADDR")"
+
+echo ""
+echo "Thunder wallet ready."
+echo "  new address:    $ADDR"
+echo "  deposit format: $DEP"
+echo ""
+echo "To send a deposit into this wallet from the mainchain:"
+echo "  grpcurl -plaintext -d '{\"sidechain_id\":9, \"address\":\"$DEP\","
+echo "    \"value_sats\":100000000, \"fee_sats\":1000}' \\"
+echo "    127.0.0.1:50051 cusf.mainchain.v1.WalletService/CreateDepositTransaction"
+echo "  grpcurl -plaintext -d '{\"blocks\":1}' \\"
+echo "    127.0.0.1:50051 cusf.mainchain.v1.WalletService/GenerateBlocks"