79 files changed, 19313 insertions, 1015 deletions

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..e22b5a4
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  linux-headless:
+    name: Linux headless selftests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Install Linux dependencies
+        run: make deps-linux
+
+      - name: Run Linux selftests
+        run: make tests
+
+      - name: Run Python tool regressions
+        run: python3 tests/scripts/test_bitflash_tools.py
+
+      - name: Run P2P message fuzz smoke
+        run: make fuzz-net-message-smoke
+
+      - name: Run script fuzz smoke
+        run: make fuzz-script-smoke
+
+  windows-ucrt64:
+    name: Windows UCRT64 selftests
+    runs-on: windows-latest
+    defaults:
+      run:
+        shell: msys2 {0}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up MSYS2
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: UCRT64
+          update: true
+          install: >-
+            git
+            make
+            mingw-w64-ucrt-x86_64-gcc
+            mingw-w64-ucrt-x86_64-glfw
+            mingw-w64-ucrt-x86_64-openssl
+            mingw-w64-ucrt-x86_64-db
+            mingw-w64-ucrt-x86_64-sqlite3
+            mingw-w64-ucrt-x86_64-libsodium
+            mingw-w64-ucrt-x86_64-nlohmann-json
+            mingw-w64-ucrt-x86_64-boost
+            mingw-w64-ucrt-x86_64-cmake
+            autoconf
+            automake
+            libtool
+
+      - name: Build Windows dependencies
+        run: make deps-windows
+
+      - name: Run Windows selftests
+        run: cd src && make -f makefile.mingw tests
diff --git a/.gitignore b/.gitignore
index 111f7ba..77b1660 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,9 @@ src/obj/
 *.dll
 bitflash-node
 src/bitflash-node
+src/obj-node/
+src/test_bip32
+src/test_compactblock
 
 # Release artefacts (produced by 'make windows' / 'make linux')
 Bitflash-*-windows/
@@ -18,11 +21,16 @@ SHA256SUMS.asc
 # Runtime data / logs
 debug.log
 db.log
+build-*.log
 *.dat
 wallet.dat
 nostr.key
 btf_enc.key
 
+# Python cache (upstream's release commit accidentally shipped one)
+__pycache__/
+*.pyc
+
 # Third-party build trees (rebuilt by the build scripts)
 RandomX/
 deps/
diff --git a/Makefile b/Makefile
index abd75c5..342ec07 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,7 @@
 #
 #   make linux    build Bitflash-*-x86_64.AppImage
 #   make windows  build Bitflash-*-windows.zip (from MSYS2 UCRT64)
+#   make windows-tor build Bitflash-*-windows-with-tor.zip
 #   make tests    build and run standalone unit tests
 #   make checksums create SHA256SUMS for release assets
 #   make verify-release TAG=v1.2.13
@@ -10,7 +11,10 @@
 ROOT    := $(shell pwd)
 NPROC   := $(shell nproc 2>/dev/null || echo 2)
 SUDO    := $(shell [ "$$(id -u)" = "0" ] && echo "" || echo "sudo")
-VERSION := 1.2.15
+# Not "1.2.20". This tree is upstream v1.2.20 plus our own hardening commits and
+# a hand-merged payout ledger, so a binary built here must not be mistakable for
+# the upstream release of that number -- it names every release artifact.
+VERSION := 1.2.20+sec
 
 # ---- Pinned third-party sources -------------------------------------------
 #
@@ -33,10 +37,23 @@ VERSION := 1.2.15
 # resolves the object by its own hash). Bump deliberately, and rebuild and
 # resync before shipping the result.
 #
+# The check has to decide the exit status, so each recipe below joins its
+# commands with && the whole way to the closing echo. Ending that chain with a
+# `;` meant a failed `test` only skipped the build steps: the echo still ran,
+# the target still exited 0, and make announced a pinned dependency that
+# nothing had verified.
+#
 # RandomX pin is the commit this tree has been building and syncing against
-# (post-v2.0.1 master, 2026-05-24) -- chosen to change nothing today.
+# (post-v2.0.1 master, 2026-05-24) -- identical to upstream's pin.
+#
+# libsecp256k1 is pinned to upstream v1.2.18's commit rather than the one this
+# fork carried, so signature validation matches the binaries the rest of the
+# network runs. Consensus code must not differ from the network by accident.
+# There must be exactly ONE assignment of each of these variables in this file:
+# upstream defines them near the top too, and GNU Make takes the last `:=`, so
+# a second block silently decides the build.
 SECP256K1_REPO   := https://github.com/bitcoin-core/secp256k1
-SECP256K1_COMMIT := 6e2c8bc4ecdc6e71dbe7a368f360d8d453ce435d
+SECP256K1_COMMIT := 7fecac74aed8e1fd9078380d67dd04663705c989
 RANDOMX_REPO     := https://github.com/tevador/RandomX
 RANDOMX_COMMIT   := 1e9d4b2df63fa6edf46b06789486e23c0fcaa55a
 
@@ -48,6 +65,32 @@ APPIMAGETOOL_SHA256 := ed4ce84f0d9caff66f50bcca6ff6f35aae54ce8135408b3fa33abfc3c
 
 # ---- Linux ----------------------------------------------------------------
 
+# RandomX used to build in $(HOME)/RandomX, and deps-randomx would rm -rf that
+# path whenever the library was missing -- deleting a tree the build did not
+# create and does not own (issue #27; a hand-managed pinned checkout there is
+# what this machine's miners build against). The default is now in-tree, like
+# secp256k1-build. A host that deliberately keeps RandomX elsewhere can set
+# RANDOMX_DIR=... explicitly; the recipe below will still never delete a
+# directory that lacks the marker file this build writes after a successful
+# build. Exported so src/Makefile's own RANDOMX_DIR ?= picks the same tree.
+#
+# Every use of it below is quoted, and the recipe rejects a value that cannot
+# name exactly one directory before it reaches anything destructive. Unquoted,
+# the marker guard could be stepped around: a value holding a glob that matches
+# two directories made `[ -d $(RANDOMX_DIR) ]` a two-argument test, which dies
+# with "unexpected operator" instead of answering, so the && short-circuited,
+# the guard was skipped, and the rm -rf below ran against every match. A value
+# holding a space or a `&&` broke the outer test the same way and reported
+# "already built". Whitespace and glob characters are refused outright rather
+# than merely quoted, because src/Makefile interpolates this same value into
+# -I$(RANDOMX_DIR)/src and -L$(RANDOMX_DIR)/build unquoted, where neither can
+# survive. A relative value is refused rather than silently made absolute: it
+# would mean two different directories to this Makefile and to src/Makefile,
+# whose cwd is src/, and a command-line assignment reaches the sub-make through
+# MAKEFLAGS, where it outranks anything exported from here.
+RANDOMX_DIR ?= $(ROOT)/randomx-build
+export RANDOMX_DIR
+
 linux: deps-linux
         $(MAKE) -C src -f Makefile -j$(NPROC)
         strip src/bitflash
@@ -67,46 +110,79 @@ linux-node: deps-linux
 
 deps-linux: deps-apt deps-secp256k1 deps-randomx
 
+# libboost-dev, not libboost-system-dev: Boost.System has been header-only
+# since 1.69 and Ubuntu 26.04 (resolute) no longer ships the -system package.
+# This tree only includes two boost headers and links no boost library. The
+# apt-get update comes first: a fresh image's package lists are empty, and
+# install then fails on the first name it cannot find.
+#
+# A failed update is deliberately not fatal: one unreachable repository should
+# not block an install the lists already on disk can satisfy. It does say so,
+# though -- "unable to locate package" several seconds later is otherwise hard
+# to connect back to it. The install is the last command in the branch, so its
+# status is the target's, and that one does abort.
 deps-apt:
         @if command -v apt-get >/dev/null 2>&1; then \
+          $(SUDO) apt-get update || \
+            echo "  warning: apt-get update failed, using the package lists on disk"; \
           $(SUDO) apt-get install -y build-essential cmake git pkg-config autoconf \
             libtool libssl-dev libdb5.3++-dev libsodium-dev nlohmann-json3-dev \
-            libboost-system-dev libglfw3-dev libgl-dev python3-pil; \
+            libboost-dev libglfw3-dev libgl-dev libsqlite3-dev \
+            python3-pil clang; \
         else \
           echo "Not an apt system — install: g++ cmake git autoconf libtool"; \
-          echo "  libssl libdb++ libsodium nlohmann-json boost glfw3 opengl python3-pil"; \
+          echo "  libssl libdb++ libsodium nlohmann-json boost glfw3 opengl sqlite3 python3-pil"; \
         fi
 
 deps-secp256k1:
         @if [ ! -f /usr/local/lib/libsecp256k1.a ]; then \
           echo "==> building libsecp256k1"; \
-          rm -rf $(ROOT)/secp256k1-build; \
-          git init -q $(ROOT)/secp256k1-build; \
+          rm -rf $(ROOT)/secp256k1-build && \
+          git init -q $(ROOT)/secp256k1-build && \
           cd $(ROOT)/secp256k1-build && \
           git remote add origin $(SECP256K1_REPO) && \
           git fetch -q --depth 1 origin $(SECP256K1_COMMIT) && \
-          git checkout -q $(SECP256K1_COMMIT) && \
-          ./autogen.sh && \
+          git checkout -q --detach FETCH_HEAD && \
+          test "$$(git rev-parse HEAD)" = "$(SECP256K1_COMMIT)" && \
+          echo "==> libsecp256k1 pinned at $(SECP256K1_COMMIT)" && \
+          cd $(ROOT)/secp256k1-build && ./autogen.sh && \
           ./configure --enable-module-schnorrsig --enable-module-extrakeys \
             --disable-shared --with-pic --disable-benchmark --disable-tests && \
-          make -j$(NPROC) && $(SUDO) make install && $(SUDO) ldconfig; \
+          make -j$(NPROC) && $(SUDO) make install && $(SUDO) ldconfig && \
           echo "==> libsecp256k1 done"; \
         else \
           echo "==> libsecp256k1 already installed"; \
         fi
 
 deps-randomx:
-        @if [ ! -f $(HOME)/RandomX/build/librandomx.a ]; then \
+        @ws="$$(printf ' \t')"; \
+        case "$(RANDOMX_DIR)" in \
+          "")        echo "ERROR: RANDOMX_DIR is empty"; exit 1 ;; \
+          /)         echo "ERROR: RANDOMX_DIR is /, refusing"; exit 1 ;; \
+          *[$$ws]*)  echo "ERROR: RANDOMX_DIR contains whitespace: $(RANDOMX_DIR)"; exit 1 ;; \
+          *[*?[]*)   echo "ERROR: RANDOMX_DIR contains a glob character: $(RANDOMX_DIR)"; exit 1 ;; \
+          /*)        ;; \
+          *)         echo "ERROR: RANDOMX_DIR must be an absolute path: $(RANDOMX_DIR)"; exit 1 ;; \
+        esac
+        @if [ ! -f "$(RANDOMX_DIR)/build/librandomx.a" ]; then \
+          if [ -d "$(RANDOMX_DIR)" ] && [ ! -f "$(RANDOMX_DIR)/.bitflash-built" ]; then \
+            echo "ERROR: $(RANDOMX_DIR) exists but was not created by this build"; \
+            echo "       refusing to rm -rf it -- remove it yourself or set RANDOMX_DIR"; \
+            exit 1; \
+          fi; \
           echo "==> building RandomX"; \
-          rm -rf $(HOME)/RandomX; \
-          git init -q $(HOME)/RandomX; \
-          cd $(HOME)/RandomX && \
+          rm -rf "$(RANDOMX_DIR)" && \
+          git init -q "$(RANDOMX_DIR)" && \
+          cd "$(RANDOMX_DIR)" && \
           git remote add origin $(RANDOMX_REPO) && \
           git fetch -q --depth 1 origin $(RANDOMX_COMMIT) && \
-          git checkout -q $(RANDOMX_COMMIT); \
-          mkdir -p $(HOME)/RandomX/build; \
-          cd $(HOME)/RandomX/build && cmake .. -DCMAKE_BUILD_TYPE=Release && \
-          make -j$(NPROC) randomx; \
+          git checkout -q --detach FETCH_HEAD && \
+          test "$$(git rev-parse HEAD)" = "$(RANDOMX_COMMIT)" && \
+          echo "==> RandomX pinned at $(RANDOMX_COMMIT)" && \
+          mkdir -p "$(RANDOMX_DIR)/build" && \
+          cd "$(RANDOMX_DIR)/build" && cmake .. -DCMAKE_BUILD_TYPE=Release && \
+          make -j$(NPROC) randomx && \
+          touch "$(RANDOMX_DIR)/.bitflash-built" && \
           echo "==> RandomX done"; \
         else \
           echo "==> RandomX already built"; \
@@ -157,13 +233,22 @@ img = ico.convert('RGBA'); \
 img.save(d + '/bitflash.png'); \
 import shutil; shutil.copy(d + '/bitflash.png', \
 d + '/usr/share/icons/hicolor/256x256/apps/bitflash.png')"
-        @for lib in libsodium.so.23 libdb_cxx-5.3.so libglfw.so.3; do \
+        @for lib in libsodium.so.23 libdb_cxx-5.3.so libsqlite3.so.0 libglfw.so.3; do \
           path=$$(ldconfig -p | grep " $$lib " | awk '{print $$NF}' | head -1); \
           [ -z "$$path" ] && path=$$(find /usr/lib /lib -name "$$lib" 2>/dev/null | head -1); \
           [ -n "$$path" ] && cp -L "$$path" $(APPDIR)/usr/lib/ && echo "  bundled $$lib" || echo "  missing $$lib"; \
         done
+# appimagetool's output used to be piped through grep ... || true, which
+# discarded its exit status: the target succeeded and announced "Built:"
+# even when no AppImage existed. Run the tool bare so its status decides,
+# then require the artefact to exist, be non-empty, and be newer than the
+# binary it was packaged from before saying so.
         @ARCH=x86_64 $(APPIMAGETOOL) --no-appstream $(APPDIR) \
-          $(ROOT)/Bitflash-$(VERSION)-x86_64.AppImage 2>&1 | grep -E "^Built|^Error" || true
+          $(ROOT)/Bitflash-$(VERSION)-x86_64.AppImage
+        @test -s $(ROOT)/Bitflash-$(VERSION)-x86_64.AppImage || \
+          { echo "ERROR: Bitflash-$(VERSION)-x86_64.AppImage missing or empty"; exit 1; }
+        @test $(ROOT)/Bitflash-$(VERSION)-x86_64.AppImage -nt src/bitflash || \
+          { echo "ERROR: Bitflash-$(VERSION)-x86_64.AppImage is not newer than src/bitflash"; exit 1; }
         @echo "Built: Bitflash-$(VERSION)-x86_64.AppImage"
 
 # ---- Windows (MSYS2 UCRT64) -----------------------------------------------
@@ -175,29 +260,42 @@ deps-windows:
           mingw-w64-ucrt-x86_64-glfw \
           mingw-w64-ucrt-x86_64-openssl \
           mingw-w64-ucrt-x86_64-db \
+          mingw-w64-ucrt-x86_64-sqlite3 \
           mingw-w64-ucrt-x86_64-libsodium \
           mingw-w64-ucrt-x86_64-nlohmann-json \
           mingw-w64-ucrt-x86_64-boost \
           mingw-w64-ucrt-x86_64-cmake \
           autoconf automake libtool
         @if [ ! -f deps/lib/libsecp256k1.a ]; then \
-          rm -rf secp256k1-build; \
-          git clone --depth 1 https://github.com/bitcoin-core/secp256k1 secp256k1-build; \
-          cd secp256k1-build && ./autogen.sh && \
+          rm -rf secp256k1-build && \
+          git init -q secp256k1-build && \
+          cd secp256k1-build && \
+          git remote add origin $(SECP256K1_REPO) && \
+          git fetch -q --depth 1 origin $(SECP256K1_COMMIT) && \
+          git checkout -q --detach FETCH_HEAD && \
+          test "$$(git rev-parse HEAD)" = "$(SECP256K1_COMMIT)" && \
+          echo "==> secp256k1 pinned at $(SECP256K1_COMMIT)" && \
+          cd $(ROOT)/secp256k1-build && ./autogen.sh && \
           ./configure --prefix=$(ROOT)/deps \
             --enable-module-schnorrsig --enable-module-extrakeys \
             --disable-shared --with-pic --disable-benchmark --disable-tests && \
-          make install; \
+          make install && \
           echo "==> secp256k1 done"; \
         else \
           echo "==> secp256k1 already built"; \
         fi
         @if [ ! -f RandomX/build/librandomx.a ]; then \
-          rm -rf RandomX; \
-          git clone --depth 1 https://github.com/tevador/RandomX; \
-          mkdir -p RandomX/build; \
-          cd RandomX/build && cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release && \
-          make randomx; \
+          rm -rf RandomX && \
+          git init -q RandomX && \
+          cd RandomX && \
+          git remote add origin $(RANDOMX_REPO) && \
+          git fetch -q --depth 1 origin $(RANDOMX_COMMIT) && \
+          git checkout -q --detach FETCH_HEAD && \
+          test "$$(git rev-parse HEAD)" = "$(RANDOMX_COMMIT)" && \
+          echo "==> RandomX pinned at $(RANDOMX_COMMIT)" && \
+          mkdir -p $(ROOT)/RandomX/build && \
+          cd $(ROOT)/RandomX/build && cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release && \
+          make randomx && \
           echo "==> RandomX done"; \
         else \
           echo "==> RandomX already built"; \
@@ -213,6 +311,9 @@ windows: deps-windows
         @zip -r Bitflash-$(VERSION)-windows.zip Bitflash-$(VERSION)-windows/
         @echo "Built: Bitflash-$(VERSION)-windows.zip"
 
+windows-tor: windows
+        ./scripts/package-windows-tor.sh
+
 # ---- Clean ----------------------------------------------------------------
 
 clean:
@@ -224,6 +325,12 @@ clean:
 tests:
         $(MAKE) -C src -f Makefile tests
 
+fuzz-net-message-smoke: deps-linux
+        $(MAKE) -C src -f Makefile fuzz-net-message-smoke
+
+fuzz-script-smoke: deps-linux
+        $(MAKE) -C src -f Makefile fuzz-script-smoke
+
 checksums:
         ./scripts/make-release-checksums.sh
 
@@ -233,6 +340,6 @@ sign-checksums:
 verify-release:
         ./scripts/verify-release.sh $(if $(TAG),$(TAG),latest)
 
-.PHONY: linux windows clean appimage \
-        tests checksums sign-checksums verify-release \
+.PHONY: linux windows windows-tor clean appimage \
+        tests fuzz-net-message-smoke fuzz-script-smoke checksums sign-checksums verify-release \
         deps-linux deps-windows deps-apt deps-secp256k1 deps-randomx
diff --git a/README.md b/README.md
index 9a55a5b..4453529 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,20 @@
-## Bitflash `BTF`
+<div align="center">
+
+<img src="docs/social.png" width="820" alt="Bitflash"/>
+
+# Bitflash `BTF`
+
 CPU-only cryptocurrency. A revival of Bitcoin 0.1.0 with RandomX proof of work and anonymous `.btf` addressing over Nostr.
 
-## Bitflash community
-Discord: https://discord.gg/TJG6vnXS9
+![PoW](https://img.shields.io/badge/PoW-RandomX%20(CPU)-2ea44f?style=for-the-badge)
+![Privacy](https://img.shields.io/badge/addresses-.btf%20anonymous-2ea44f?style=for-the-badge)
+![Tor](https://img.shields.io/badge/tor-onion%20service-7d4698?style=for-the-badge)
+![Fair Launch](https://img.shields.io/badge/premine-none-2ea44f?style=for-the-badge)
+[![Discord](https://img.shields.io/badge/discord-join-5865F2?style=for-the-badge)](https://discord.gg/n7B2Eamn3)
+
+**[Download](https://releases.bitflash.network/)** · **[Discord](https://discord.gg/n7B2Eamn3)**
+
+</div>
 
 ---
 
@@ -12,7 +24,7 @@ Bitflash keeps Satoshi's original consensus rules and replaces two things:
 
 **RandomX proof of work.** Memory-hard algorithm used by Monero. A laptop competes equally with a server. ASICs and GPUs have no advantage.
 
-**Anonymous addressing.** Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes reach each other through encrypted rendezvous tunnels, so no port forwarding is needed and a node behind CGNAT works normally.
+**Anonymous addressing.** Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes reach each other through encrypted rendezvous tunnels by default, and can advertise a signed direct `.onion` endpoint for Tor peers.
 
 No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute blocks.
 
@@ -20,27 +32,128 @@ No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute bl
 
 Worth being precise, because the difference matters if you are relying on it.
 
-**A peer you reach over `.btf` does not learn your IP.** All outbound connections go through a rendezvous tunnel; there is no IP-based peer dialling left in the node. The relay forwards encrypted bytes and cannot read or alter them.
+**A peer you reach over `.btf` does not learn your IP.** Outbound peer discovery uses rendezvous tunnels by default. If both sides use Tor and the peer advertises a signed `.onion` endpoint, the node connects directly to that hidden service instead. In both cases the peer does not see your clearnet IP.
 
-**The rendezvous relay does see your IP.** It has to — it is the thing your TCP connection terminates on. Relays are run by volunteers, so treat that as a party who knows you are on the network.
+**The rendezvous relay sees your IP unless you use Tor.** It has to — it is the thing your TCP connection terminates on. With `-tor`, the relay sees Tor instead. With a signed direct `.onion` peer endpoint, the relay is not on that connection path at all.
 
 **The node still listens on 8433.** Nothing dials by IP any more, but the listener is still there, so anyone who already knows your address and can reach that port may connect directly. If that matters to you, firewall it.
 
-This is unlinkability between peers, not anonymity against a network observer. It is not Tor.
+This is unlinkability between peers, not anonymity against a network observer.
+For Tor routing and direct onion peer endpoints, start the node with `-tor`;
+see [Tor mode](docs/tor.md).
+For a plain SOCKS5 proxy without Tor-specific defaults, use
+`-socks=HOST:PORT`.
 
 ---
 
 ## Quick start
 
+Download the [latest release](https://releases.bitflash.network/) and run. No
+install, no configuration — it connects automatically and starts syncing.
+
 **Linux:** make the `.AppImage` executable and run it.
 
-**Windows:** extract the `-windows.zip` and run `Bitflash.exe`.
+**Windows:** extract the `-windows-with-tor.zip` and run `Bitflash.exe`. Tor is
+bundled and a managed Tor instance starts automatically, so onion transport
+works with no separate install. Pass `-nomanagedtor` to turn it off.
+
+Every release ships a `SHA256SUMS` covering the assets. Verifying takes a second
+and is worth doing:
+
+```bash
+sha256sum -c SHA256SUMS
+```
+
+For newer signed releases, verify the checksum file itself first:
+
+```bash
+gpg --verify SHA256SUMS.asc SHA256SUMS
+sha256sum -c SHA256SUMS
+```
+
+The helper below downloads the release assets, verifies `SHA256SUMS.asc` when it
+is present, then checks the hashes:
+
+```bash
+scripts/verify-release.sh latest
+```
+
+See [release verification](docs/release-verification.md) for the full release
+audit flow and the maintainer signing step.
+
+Public mirrors should make the latest checksum files available both under the
+versioned release directory and at the release root:
+
+```text
+https://releases.bitflash.network/v1.2.20/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS        # alias to latest
+```
+
+Bitflash also ships a deterministic UTXO-set commitment tool:
+
+```bash
+python3 scripts/verify-utxo-set.py --out utxo-report.json --json
+```
+
+It reconstructs the best chain from local block files, computes the current
+UTXO root and supply, and writes canonical JSON that independent auditors can
+compare or timestamp externally with OpenTimestamps. See
+[UTXO-set commitments](docs/utxo-commitment.md).
+
+The same root can prove one unspent output without sharing the full UTXO set:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+See [UTXO inclusion proofs](docs/utxo-proofs.md).
+
+Bitflash also ships a deterministic fair-launch verifier:
+
+```bash
+python3 scripts/verify-fair-launch.py --max-blocks 1000 --out bitflash-fair-launch-report.json --json
+```
+
+The report reads the local chain directly, checks the genesis launch baseline,
+and produces canonical JSON whose hash can be compared by independent auditors
+or timestamped externally with OpenTimestamps. See
+[fair-launch verification](docs/fair-launch.md).
+
+For a static local block explorer, generate HTML and JSON from either a data
+directory or explicit block files:
+
+```bash
+python3 scripts/build-explorer.py --datadir ~/.bitflash ./explorer-out
+python3 scripts/build-explorer.py ~/.bitflash/blk0001.dat ~/.bitflash/blk0002.dat ./explorer-out
+```
+
+The generated explorer is static and self-contained: `index.html`,
+`style.css`, `explorer.js`, `blocks.json`, `block/*.json`, and `logo.png`. It is
+safe to host behind a strict policy such as `default-src 'none'; img-src 'self';
+style-src 'self'; script-src 'self'; connect-src 'self'; base-uri 'none';
+form-action 'none'`.
 
 **Keep your node current.** Consensus rules have changed since the first
-releases — 1.0.0 fixed a bug that let anyone spend anyone's coins. A node on an older build will accept
+releases — 1.2.1 fixed a bug that let anyone spend anyone's coins, and 1.2.2
+added a per-block signature-operation cap. A node on an older build will accept
 blocks that current nodes reject, which puts it on a different chain without any
 warning.
 
+Two more reasons, both measured rather than theorised:
+
+- **Before 1.2.13** a node closed a disconnected peer's socket twice and left the
+  closed handle in its `select()` set, where it made `select()` fail on every
+  iteration. The node then spent its socket loop in an error path instead of
+  reading its peers — the deaf-node behaviour reported since 1.2.7. Two nodes
+  side by side on one machine, same network: the one without the fix held 11
+  peers and logged 741 spurious disconnections; the one with it held 21 and
+  logged none. On 1.2.13 in production, two mining nodes hold 13 and 18 peers
+  with zero.
+- **Before 1.2.11** a long-running Windows node accumulated sockets it never
+  released — 1262 of them in 26 hours on one machine, each holding an ephemeral
+  port. Restarting returned them; upgrading stops them accumulating.
+
 Your wallet and chain data live in `%APPDATA%\Bitflash` (Windows) or
 `~/.bitflash` (Linux) and are shared by every version, so upgrading is just
 replacing the binary. Never delete that directory to "fix" something without a
@@ -50,6 +163,19 @@ backup — it holds your keys.
 
 ## Your wallet: the phrase and the file
 
+Since 1.2.12 a wallet can hold twelve words that rebuild it. Since 1.2.13 those
+words also cover the address the window shows you. **Both still matter** — the
+phrase and the file back up different things, and the difference is where people
+lose money.
+
+Since 1.2.20 the file is a single self-contained `wallet.sqlite` by default. A
+fresh data directory starts on it; an existing Berkeley DB `wallet.dat` keeps
+working and the desktop app converts it in one click on first run, never
+touching the original, which stays as a fallback. Choose a backend explicitly
+with `-walletbackend=sqlite` or `-walletbackend=bdb`, recorded in a
+`wallet-backend` marker in the data directory. See
+[wallet storage](docs/storage.md).
+
 The derivation is written down in [docs/derivation.md](docs/derivation.md), with
 test vectors and a script that reproduces them from scratch. It is there so the
 twelve words keep working even if this software does not: paths, address format
@@ -63,8 +189,11 @@ bitflash -newphrase                          # create it, show it once, exit
 bitflash -restorephrase="twelve words here"  # rebuild a wallet from it
 ```
 
-`-newphrase` installs a BIP32 seed, derives the wallet's key pool and default
-receiving address from it, and prints the words once. It refuses if a phrase
+`-newphrase` installs a BIP39/BIP32 seed and derives the wallet as a BIP44 tree
+along `m/44'/4346950'/0'/…` — coin type **4346950** is `0x425446`, the ASCII
+bytes `BTF`, registered in [SLIP-0044](https://github.com/satoshilabs/slips/blob/master/slip-0044.md).
+It builds the key pool and default receiving address from the seed, and prints
+the words once. It refuses if a phrase
 already exists: replacing one silently would strand every coin on addresses the
 written-down words no longer describe.
 
@@ -84,8 +213,17 @@ from the words. The wallet names such an address `Your Address (created before
 the recovery phrase)` so you can tell them apart. This is why file backups still
 matter.
 
+> **If you created a phrase on 1.2.12, run `-restorephrase` with the same twelve
+> words.** That release installed the seed but left the visible address and the
+> key pool random, so the wallet went on handing out addresses the words cannot
+> reproduce while the window said a phrase existed. Restoring repairs it.
+
 ### The file
 
+Under the SQLite default the wallet is one self-contained `wallet.sqlite`, and
+`-backupwallet` writes a matching `.sqlite` copy that opens on its own — no
+sidecar directory. The Berkeley DB notes below apply to a legacy `wallet.dat`.
+
 **Copying `wallet.dat` on its own is not a backup.** Berkeley DB ties the file
 to the environment in the `database/` subdirectory beside it, so a lone
 `wallet.dat` will not open elsewhere — the keys are all still in there, and the
@@ -123,7 +261,7 @@ as a verdict to somebody who has just lost a wallet.
 
 ### When wallet.dat itself will not open
 
-Everything above still runs through Berkeley DB. If the database is the thing
+A legacy `wallet.dat` runs on Berkeley DB. If that database is the thing
 that is broken — a build that will not read it, a file truncated by a bad copy,
 an environment beyond recovery — the keys are usually still fine, and you can
 take them out as text:
@@ -157,15 +295,48 @@ Open **Options** from the menu bar. Under Mining Mode:
 
 Pool announcements are published on Nostr with live status fields, so external tools can query the latest pool state by `.btf` address.
 
+Pool operators also write a local `pool_status.json` every ten seconds and a
+`pool_rounds.json` proof ledger whenever they find blocks or pay miners. By
+default both are created in the data directory; use `-poolstatusfile=PATH` and
+`-poolroundsfile=PATH` to write them somewhere a dashboard or web sync can read.
+The files are informational only: nodes still discover pools through Nostr and
+`.btf`, not through any web domain.
+See [public pool directory](docs/pool-directory.md) for the website/API shape.
+
 **Participant** — mine to someone else's pool. Enter or select the pool's `.btf` address and enable Start Mining.
 
-SRBMiner and XMRig connect to operator pools through the `.btf` path:
+The built-in participant miner connects to operator pools through the `.btf`
+path. Use it — **third-party RandomX miners such as XMRig and SRBMiner cannot
+mine Bitflash pools**, and no amount of configuration changes that. In RandomX
+mode they speak the Monero-style JSON-RPC protocol (`login`/`job`/`submit`) and
+assume a Monero-style job: the nonce at byte 39 of the blob, and a 32-byte seed
+hash given as 64 hex characters. Bitflash pools speak Bitcoin-style Stratum
+(`mining.subscribe`/`mining.notify`/`mining.submit`) over an 80-byte header
+whose nonce is at byte 76 — byte 39 falls inside the merkle root — and key
+RandomX from a fixed 36-byte string that is not a hash at all.
+
+`-stratumbridge` carries that same Bitcoin-style Stratum over the `.btf` path,
+so a miner on this machine can reach a pool it otherwise could not address. It
+is a byte relay, not a protocol translator, so it helps only a miner that
+already speaks the pool's dialect, and it does not make the miners above work:
+
+```bash
+./bitflash -nogui -stratumbridge=POOL_BTF_ADDRESS -stratumbridgeport=3333
+```
+
+Estimate rewards and electricity cost locally:
 
 ```bash
-SRBMiner-MULTI --algorithm randomx --pool POOL_BTF_ADDRESS --wallet YOUR_BTF_ADDRESS --password x
-xmrig -a rx/0 -o POOL_BTF_ADDRESS -u YOUR_BTF_ADDRESS -p x
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --network-hashrate 1.56 --network-hashrate-unit mh/s \
+  --watts 140 --kwh-cost 0.10 \
+  --price 0.001 --pool-fee 1
 ```
 
+See [mining calculator](docs/mining-calculator.md). Price is manual until
+Bitflash has a reliable public market.
+
 ---
 
 ## Headless / server mode
@@ -174,7 +345,11 @@ xmrig -a rx/0 -o POOL_BTF_ADDRESS -u YOUR_BTF_ADDRESS -p x
 ./bitflash -nogui                     # node only
 ./bitflash -nogui -gen                # node + solo mining
 ./bitflash -nogui -gen -operator      # pool operator
+./bitflash -nogui -gen -operator \
+  -poolstatusfile=/var/www/pool_status.json \
+  -poolroundsfile=/var/www/pool_rounds.json
 ./bitflash -nogui -gen -participant=POOL_BTF_ADDRESS  # mine to pool
+./bitflash -nogui -stratumbridge=POOL_BTF_ADDRESS      # Stratum over .btf (see Mining)
 ```
 
 Every option takes `-` or `/`. **Under MSYS2 use the `-` form** — the shell
@@ -190,7 +365,13 @@ Other options worth knowing:
 
 ```bash
 -datadir=PATH    # wallet and chain data elsewhere
--port=N          # P2P listen port, default 8433
+-testnet         # isolated test network genesis, datadir, port 18433, and magic
+-port=N          # P2P listen port, default 8433; testnet default 18433
+-socks=HOST:PORT # SOCKS5 for outbound Nostr, .btf relay, and onion peer dials
+-tor[=HOST:PORT] # Tor mode; default local Tor SOCKS5 proxy is 127.0.0.1:9050
+-managedtor[=PATH] # start Tor, create a hidden service, advertise its onion
+-nomanagedtor    # disable the automatic bundled-Tor startup
+-onionservice=HOST.onion:PORT # advertise this node's Tor hidden service
 -debug           # verbose log; without it debug.log is nearly silent
 -help            # full list
 ```
@@ -199,10 +380,32 @@ Other options worth knowing:
 needed — the data directory takes an exclusive lock, so a second node pointed at
 the same one will refuse to start.
 
+`-socks=127.0.0.1:9050` routes outbound Nostr discovery, `.btf` rendezvous
+dials, and direct `.onion` peer dials through a local SOCKS5 proxy such as Tor.
+When it is set, the node skips
+plain HTTP external-IP probes instead of leaking a direct request outside the
+proxy. IPv6 proxy endpoints use brackets, for example `-socks=[::1]:9050`.
+
+`-tor` is a privacy shorthand for the usual local Tor SOCKS5 listener at
+`127.0.0.1:9050`. It routes outbound Nostr discovery, `.btf` rendezvous dials,
+and signed direct `.onion` peer dials through Tor, and keeps external-IP probes
+disabled. Use `-tor=HOST:PORT` when Tor listens somewhere else.
+
+The desktop app starts a managed Tor automatically when no other Tor option is
+set, so onion transport works out of the box; `-nomanagedtor` turns that off.
+For a headless node, ask for it explicitly:
+
+`-managedtor[=PATH]` starts a Tor process for this node, writes a local `torrc`,
+creates a v3 hidden service for port `8433`, routes outbound discovery through
+that Tor instance, and signs the generated `.onion:8433` endpoint into the
+node's `.btf` descriptor. Without `PATH`, Bitflash looks for `tor/tor.exe`,
+`tor.exe`, or `tor` beside the binary and then on `PATH`. The hidden-service key
+is stored under the Bitflash data directory in `managed-tor/onion-service/`.
+
 ### When something looks wrong
 
 **Menu > Diagnostics**, and the same report in `debug.log` every ten minutes:
-peers held against peers `select()` is actually watching, blocks received and how
+peers held against peers the socket loop is actually watching, blocks received and how
 many arrived without a parent, the proof-of-work mode with the live miner thread
 count, sockets by the part of the program that opened them, and per peer how long
 since the last message each way. There is a copy button — if you open an issue,
@@ -284,6 +487,19 @@ make windows
 ```
 Installs deps via pacman, produces `Bitflash-*-windows.zip`.
 
+To build the Windows package that also carries the Tor Expert Bundle:
+
+```bash
+make windows-tor
+```
+
+That produces `Bitflash-*-windows-with-tor.zip`. The release script downloads
+the Tor Expert Bundle from the official Tor archive, verifies its pinned SHA256,
+optionally verifies the Tor Project GPG signature when `gpg` is available, and
+places `tor/tor.exe` beside `Bitflash.exe` so `-managedtor` works without a
+separate Tor install. For release builds, use `TOR_VERIFY_GPG=required make
+windows-tor` to require the extra signature check.
+
 ---
 
 ## At a glance
@@ -303,7 +519,8 @@ Installs deps via pacman, produces `Bitflash-*-windows.zip`.
 | Addressing | `.btf` rendezvous — see the caveats above |
 | Premine | None |
 | Pool server | Built-in — `.btf` rendezvous only |
-| Wallet recovery | Twelve-word phrase (BIP39 + BIP32), plus file backup |
+| Wallet recovery | Twelve-word phrase (BIP39 + BIP32 + BIP44, coin type 4346950), plus file backup |
+| Wallet storage | SQLite `wallet.sqlite` by default, or Berkeley DB `wallet.dat` |
 
 The halving interval is the number most people get wrong coming from Bitcoin.
 Same 210,000 blocks, but at two minutes instead of ten, so it arrives in about
@@ -311,4 +528,6 @@ ten months rather than four years.
 
 ---
 
+Young network. Keep your node current and don't put in more than you are willing to lose.
+
 MIT. Built on Bitcoin 0.1.0 (Satoshi Nakamoto, 2009).
diff --git a/docs/dependencies.md b/docs/dependencies.md
new file mode 100644
index 0000000..9fd45b6
--- /dev/null
+++ b/docs/dependencies.md
@@ -0,0 +1,18 @@
+# Build Dependencies
+
+Bitflash links consensus-adjacent cryptographic and proof-of-work code from
+external repositories. Fresh builds must not follow upstream `master` silently:
+a changed upstream branch can break reproducible builds or change behavior in
+code that every node relies on.
+
+The top-level `Makefile` pins source dependencies by full commit hash:
+
+| dependency | repository | pinned commit |
+|---|---|---|
+| libsecp256k1 | https://github.com/bitcoin-core/secp256k1 | `7fecac74aed8e1fd9078380d67dd04663705c989` |
+| RandomX | https://github.com/tevador/RandomX | `1e9d4b2df63fa6edf46b06789486e23c0fcaa55a` |
+
+When updating either dependency, rebuild from a clean dependency directory and
+run the full selftest suite before opening the PR. The PR should explain why the
+dependency changed and whether the update can affect consensus, addresses,
+signatures, proof-of-work validation, or mining.
diff --git a/docs/fair-launch.md b/docs/fair-launch.md
new file mode 100644
index 0000000..9603910
--- /dev/null
+++ b/docs/fair-launch.md
@@ -0,0 +1,70 @@
+# Bitflash fair-launch verifier
+
+Bitflash ships a deterministic fair-launch audit script:
+
+```bash
+python3 scripts/verify-fair-launch.py --max-blocks 1000 --out bitflash-fair-launch-report.json --json
+```
+
+The verifier reads `blk*.dat` directly from the local Bitflash data directory.
+It does not use Berkeley DB, does not call the node binary, and does not need
+network access. It uses the same shared Python chain parser as the UTXO
+commitment and proof tools, so block serialization fixes land in one place.
+
+The report proves the launch baseline that can be checked from the chain:
+
+- the genesis block hash matches the source constant;
+- the genesis merkle root matches the source constant;
+- the genesis transaction is a single coinbase transaction;
+- the genesis output total is exactly `50.00000000 BTF`;
+- the scanned block range and mined coinbase total are reproducible.
+
+For machines that do not have a synced data directory yet, the source constants
+can be checked without disk blocks:
+
+```bash
+python3 scripts/verify-fair-launch.py --reconstruct-genesis
+```
+
+## Deterministic output
+
+Use `--json` or `--out` for canonical JSON. The JSON is written with sorted
+keys, fixed separators, ASCII escaping, and one trailing newline. It deliberately
+does not include local paths or wall-clock generation time, so two auditors
+scanning the same block range produce the same bytes.
+
+That makes the report shareable:
+
+```bash
+python3 scripts/verify-fair-launch.py --max-blocks 1000 --out report.json --json
+sha256sum report.json
+```
+
+If another auditor runs the same command against the same chain prefix, the
+`sha256sum` should match.
+
+## OpenTimestamps
+
+OpenTimestamps is optional and external. It anchors the report in Bitcoin
+without adding any bridge or dependency to Bitflash consensus.
+
+After generating a canonical JSON report:
+
+```bash
+ots stamp report.json
+ots verify report.json.ots
+```
+
+The `.ots` file proves that the exact report bytes existed no later than the
+Bitcoin block that confirms the timestamp.
+
+## What this does not claim
+
+This is not a retroactive genesis commitment. The Bitflash genesis block already
+exists, so adding a new on-chain commitment to genesis would create a different
+chain. This verifier instead audits the launch state that is already on-chain
+and makes the result reproducible and timestampable.
+
+It also does not prove real-world miner identity. It proves the genesis state,
+the absence of non-coinbase premine in genesis, and the deterministic coinbase
+totals over the scanned prefix.
diff --git a/docs/mining-calculator.md b/docs/mining-calculator.md
new file mode 100644
index 0000000..e6cb61b
--- /dev/null
+++ b/docs/mining-calculator.md
@@ -0,0 +1,108 @@
+# Bitflash mining calculator
+
+`scripts/bitflash-mining-calculator.py` is a local WhatToMine-style calculator
+for Bitflash.
+
+It does not fetch market prices, does not talk to exchanges, and does not
+change consensus. Price is a manual input until Bitflash has a reliable public
+market.
+
+## Examples
+
+Estimate from network hashrate:
+
+```bash
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --network-hashrate 1.56 --network-hashrate-unit mh/s \
+  --watts 140 --kwh-cost 0.10 \
+  --price 0.001 --pool-fee 1
+```
+
+Estimate from Bitflash difficulty:
+
+```bash
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --difficulty 45600 \
+  --watts 140 --kwh-cost 0.10
+```
+
+Machine-readable output:
+
+```bash
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --network-hashrate 1.56 --network-hashrate-unit mh/s \
+  --json
+```
+
+## Bitflash Difficulty Scale
+
+Bitflash does not use Bitcoin's SHA256 difficulty-1 constant for pool shares.
+The chain's easiest RandomX target is `bnProofOfWorkLimit = ~uint256(0) >> 12`,
+so difficulty 1 expects about `4096` hashes.
+
+The calculator uses:
+
+```text
+network_hashrate = difficulty * 4096 / block_time_seconds
+```
+
+At the default two-minute block target:
+
+```text
+network_hashrate = difficulty * 4096 / 120
+```
+
+If you already know network hashrate, pass `--network-hashrate` directly and
+the script derives the equivalent Bitflash difficulty for display.
+
+## Reward Estimate
+
+The expected daily reward is:
+
+```text
+blocks_per_day = 86400 / block_time_seconds
+miner_share = miner_hashrate / network_hashrate
+gross_btf_per_day = blocks_per_day * block_reward * miner_share
+net_btf_per_day = gross_btf_per_day * (1 - pool_fee_percent / 100)
+```
+
+Electricity is:
+
+```text
+electricity_per_day = watts / 1000 * 24 * kwh_cost
+```
+
+This is an expectation, not a promise. Solo mining variance can be very large,
+especially when the miner has a small share of the network.
+
+## Future Website Use
+
+The script is intentionally standalone so the same math can later back a
+website widget or status dashboard. Until a public price exists, a website
+calculator should keep price as a manual field and label fiat profit as
+speculative.
+
+## Website Fields
+
+A public calculator should ask for:
+
+- miner hashrate and unit;
+- power draw in watts;
+- electricity price per kWh;
+- pool fee percent;
+- optional BTF price;
+- either current Bitflash difficulty or current network hashrate.
+
+The output should separate:
+
+- estimated BTF per day;
+- estimated gross fiat revenue, if a manual price was provided;
+- electricity cost;
+- net profit/loss;
+- the difficulty/hashrate assumptions used.
+
+Never present the fiat number as a market quote unless it comes from a real
+public market. Before that exists, label it as a manual scenario.
diff --git a/docs/pool-directory.md b/docs/pool-directory.md
new file mode 100644
index 0000000..ff0640a
--- /dev/null
+++ b/docs/pool-directory.md
@@ -0,0 +1,61 @@
+# Public Pool Directory
+
+`pool.bitflash.network` should be a public directory, not a network dependency.
+Nodes discover pools through Nostr and `.btf`; the website only helps humans
+compare operators.
+
+Operators can publish the `pool_status.json` and `pool_rounds.json` files
+produced by:
+
+```bash
+bitflash -nogui -gen -operator \
+  -poolstatusfile=/var/www/pool_status.json \
+  -poolroundsfile=/var/www/pool_rounds.json
+```
+
+Build a static directory from one or more status files:
+
+```bash
+python3 scripts/build-pool-index.py --out-dir public/pool \
+  https://operator-one.example/pool_status.json \
+  https://operator-two.example/pool_status.json
+```
+
+The generated output contains:
+
+- `index.html`: human-readable ranking page.
+- `pools.json`: machine-readable API for `api.bitflash.network/pools.json`.
+
+The website is a convenience layer, not a consensus or discovery dependency.
+Nodes discover pools through Nostr descriptors and `.btf`; a missing website
+must not stop mining or pool operation.
+
+When a source is an HTTP(S) `pool_status.json`, the directory links to a
+`pool_rounds.json` proof file next to it. That file records the block height,
+block hash, coinbase txid, coinbase value, pool fee, total shares, per-address
+share counts, computed payouts, and payout txids once paid.
+
+Ranking order is intentionally simple:
+
+1. online pools first;
+2. higher reported hashrate;
+3. more authorized miners;
+4. lower fee;
+5. name as a stable tie-breaker.
+
+An entry is considered online when the source says the pool is running and its
+status file is no more than 120 seconds old.
+
+## Recommended Hostnames
+
+Use:
+
+```text
+pool.bitflash.network        human-readable pool directory
+api.bitflash.network/pools.json
+status.bitflash.network      relay/node health, not pool ranking
+docs.bitflash.network        operator setup guide
+```
+
+The GUI may use the API as a shortcut for humans, but it should keep the
+existing decentralized pool discovery path as the source of truth.
diff --git a/docs/release-verification.md b/docs/release-verification.md
index ecacd5f..b8eaf5e 100644
--- a/docs/release-verification.md
+++ b/docs/release-verification.md
@@ -3,60 +3,100 @@
 Bitflash releases publish binaries and a `SHA256SUMS` file. The checksum file
 proves that the file you downloaded matches the file the release page names.
 A detached signature, `SHA256SUMS.asc`, proves that the checksum file itself was
-signed by a trusted release key.
+signed by the Bitflash release key.
 
 That gives users two separate checks:
 
-1. `gpg --verify SHA256SUMS.asc SHA256SUMS` checks who signed the checksums.
-2. `sha256sum -c SHA256SUMS` checks the binaries against those checksums.
+1. `gpg --verify SHA256SUMS.asc SHA256SUMS` — who signed the checksums.
+2. `sha256sum -c SHA256SUMS` — the binaries against those checksums.
 
-## User Check
+But the first check is only worth something if you require a **specific** key.
+A good signature by *some* key proves nothing; anyone can make one.
 
-From a shell with `curl` or `wget` and `sha256sum`:
+## The release signing key
+
+```text
+fingerprint  910A 2B4C CA87 9E81 FB4B  2AEA 1D4A 53D3 B78A A4B8
+uid          Bitflash Releases (bitflash.network release signing)
+             <releases@bitflash.network>
+```
+
+The public key is published at
+`https://releases.bitflash.network/bitflash-release-key.asc` and embedded in
+`scripts/verify-release.sh`, so the tool's trust anchor lives in this
+repository rather than on the server it verifies.
+
+## User check
+
+From a shell with `curl` or `wget`, `sha256sum` and `gpg`:
 
 ```bash
 scripts/verify-release.sh latest
 ```
 
-For a specific release:
+The public release host should expose latest-file aliases for convenience:
 
-```bash
-scripts/verify-release.sh v1.2.13
+```text
+https://releases.bitflash.network/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS.asc
 ```
 
-For release audits, require the signature:
+Those aliases must point at the current versioned directory. They do not replace
+signature verification; they only make the common manual path shorter.
+
+For a specific release:
 
 ```bash
-scripts/verify-release.sh v1.2.13 --require-signature
+scripts/verify-release.sh v1.2.15
 ```
 
-Older releases may not have `SHA256SUMS.asc`. In that case the script warns and
-still checks file integrity. New release audits should use `--require-signature`.
-
-## Maintainer Flow
+The script downloads the release, imports the pinned key into a throwaway
+keyring, and **refuses anything that is not a valid signature by the key above**
+before checking the hashes. Releases from before signing was introduced ship
+only `SHA256SUMS`; without `--require-signature` those are checked for integrity
+and reported as unsigned.
 
-After building release assets in the repository root:
+By hand, if you would rather not run the script:
 
 ```bash
-scripts/make-release-checksums.sh --sign --local-user RELEASE_KEY_ID
+curl -O https://releases.bitflash.network/bitflash-release-key.asc
+gpg --import bitflash-release-key.asc
+gpg --verify SHA256SUMS.asc SHA256SUMS   # must name the fingerprint above
+sha256sum -c SHA256SUMS
 ```
 
-Upload all built assets plus:
+## Maintainer flow
 
-```text
-SHA256SUMS
-SHA256SUMS.asc
+The signing key lives on a dedicated location, not in the build tree. After
+building the release assets in the repository root, write and sign the
+checksums:
+
+```bash
+sha256sum Bitflash-*.zip Bitflash-*.AppImage bitflash-node-* > SHA256SUMS
+gpg --armor --detach-sign --output SHA256SUMS.asc SHA256SUMS
 ```
 
-Keep the private signing key offline or on a dedicated release machine. Publish
-the public key fingerprint in the release notes and keep using the same key for
-future releases unless there is a clearly announced rotation.
+Publish, alongside the assets, `SHA256SUMS` and `SHA256SUMS.asc`, and update
+`latest.txt` on the releases host to the new tag. Keep using the same key; if it
+is ever rotated, announce the new fingerprint clearly and update the embedded
+key in `verify-release.sh`.
+
+For Windows releases with managed Tor built in, run `make windows-tor`. It
+creates `Bitflash-*-windows-with-tor.zip` by downloading the Tor Expert Bundle,
+checking the pinned SHA256 in `scripts/package-windows-tor.sh`, optionally
+verifying the Tor Project `.asc` signature, and placing `tor/tor.exe` next to
+`Bitflash.exe`. For release builds, run `TOR_VERIFY_GPG=required make
+windows-tor` so the signature check is mandatory. Include that zip in
+`SHA256SUMS` like any other release asset.
 
-## Why This Matters
+## Why this matters
 
 `SHA256SUMS` alone protects against a broken download, but not against someone
-replacing both a binary and the checksum file. Signing `SHA256SUMS` means an
-attacker must also have the release signing key to make the replacement verify.
+replacing both a binary and the checksum file. Signing `SHA256SUMS`, and
+requiring a pinned key, means an attacker must also hold the release signing key
+to make the replacement verify. Serving from bitflash.network makes this the
+guarantee that matters: without a pinned key, "trust the site" is the only
+thing standing behind a download.
 
 This is not reproducible builds yet. It is the smaller, immediate step that
-makes every release asset auditable by users before they run it.
+makes every release asset auditable before anyone runs it.
diff --git a/docs/rendezvous.md b/docs/rendezvous.md
new file mode 100644
index 0000000..68b5df3
--- /dev/null
+++ b/docs/rendezvous.md
@@ -0,0 +1,336 @@
+# Bitflash `.btf` Rendezvous Protocol
+
+This is the specification of how Bitflash nodes reach each other, and how miners
+reach pools, without revealing an IP address and without any central directory.
+It documents the protocol as implemented in `src/btfaddr.cpp`, `src/btfchan.cpp`,
+`src/btfrv.cpp`, `src/btftunnel.cpp` and `src/nostr.cpp`.
+
+The design is ported from the Itzal hidden service design. A `.btf` address names
+a public key, a node proves ownership of that key by signing a service
+descriptor, other nodes find the descriptor over Nostr, and the two sides then
+meet through an untrusted relay over an end to end encrypted tunnel. The relay
+carries ciphertext only and never learns the plaintext.
+
+## 1. Overview
+
+A connection to a `.btf` service has three layers:
+
+1. **Discovery (Nostr).** The service publishes a signed descriptor as a Nostr
+   event. A caller fetches it by the service public key and verifies the
+   signature. The descriptor says which rendezvous relay the service is waiting
+   at, which encryption key to use, and optionally which Tor hidden service can
+   be dialed directly.
+2. **Rendezvous (TCP).** Caller and service both connect out to the same relay
+   and are paired by public key. Neither needs an inbound port or a public IP.
+   After pairing the relay is a blind byte pipe.
+3. **Direct onion fallback bypass.** If the descriptor carries a valid signed
+   `.onion:port` endpoint and the caller is running with Tor mode, the caller
+   tries that endpoint before using rendezvous. This removes the rendezvous
+   relay from the data path for peers that choose to run hidden services.
+4. **Encrypted channel (X25519 + XChaCha20-Poly1305).** Over the paired pipe the
+   caller and service run an ephemeral to static handshake and then exchange
+   authenticated frames. The relay sees only ciphertext.
+
+The caller ends up holding an ordinary local socket that behaves like a direct
+TCP connection to the peer. The node treats it exactly like any other peer
+socket.
+
+## 2. Identities and keys
+
+A node holds two independent keypairs.
+
+- **Signing / identity key**: a secp256k1 x-only key (BIP340 Schnorr). This is
+  the `.btf` identity and also the node's Nostr identity. Persisted in
+  `nostr.key`.
+- **Encryption key**: an X25519 (Curve25519) keypair. Persisted in
+  `btf_enc.key`. Its public half is published in the descriptor as `enc` and is
+  used for the tunnel key agreement.
+
+The identity key names the service and authenticates the descriptor. The
+encryption key secures the tunnel. They are separate so the long term identity
+never performs Diffie-Hellman and the encryption key can be rotated in a new
+signed descriptor.
+
+## 3. The `.btf` address
+
+An address is the identity public key plus a short checksum, Base32 encoded, with
+the suffix `.btf`.
+
+```
+label   = Base32( pubkey[32] || checksum[2] )
+address = label + ".btf"
+```
+
+- `pubkey` is the 32 byte secp256k1 x-only public key.
+- `checksum` is the first two bytes of `SHA256(".btf-checksum-v1" || pubkey)`.
+- Base32 uses the lowercase alphabet `abcdefghijklmnopqrstuvwxyz234567`, no
+  padding. The 34 byte payload encodes to 55 characters.
+- Parsing is case insensitive, trims surrounding whitespace, and strips a
+  trailing dot. A wrong checksum is rejected.
+
+The address is self certifying: it *is* the public key, so no registry has to be
+trusted to map a name to a key.
+
+## 4. Discovery over Nostr
+
+Nodes publish and read three kinds of parameterized replaceable Nostr events.
+Parameterized replaceable means the newest event for a given author and `d` tag
+supersedes the older one, so a descriptor is always the latest state.
+
+| Purpose | kind | `d` tag |
+|---|---|---|
+| Service descriptor | 38501 | `btf-descriptor-2` |
+| Rendezvous relay announcement | 38502 | `btf-relay-2` |
+| Pool announcement | 38503 | `btf-pool-2` |
+
+The Nostr event is signed with the node's identity key, so the event author
+equals the `.btf` public key. That binds the descriptor to the address at the
+Nostr layer, and the descriptor is *also* signed inside its own content (see
+below), so a relay operator cannot forge or swap a descriptor for an address it
+does not control.
+
+**Resolving an address.** To reach `X.btf`, a caller parses the address to the 32
+byte key and sends a Nostr `REQ` filtered by `authors = [X]`, `kinds = [38501]`,
+`#d = ["btf-descriptor-2"]`, `limit = 1`. It verifies the returned descriptor and
+uses its `meeting_node` and `enc`.
+
+**Relay auto discovery.** A relay operator runs a rendezvous relay and publishes a
+kind 38502 event carrying `host:port`. Every node that reads it adds the relay to
+the set it can register at and dial through. No seed list edit or maintainer
+approval is needed. A small curated seed list is still shipped for bootstrap:
+
+```
+92.246.128.180:8434
+31.44.4.249:8434
+90.156.222.107:8434
+```
+
+The default rendezvous port is `8434`.
+
+## 5. The service descriptor
+
+The descriptor is a JSON object, signed with the identity key over a domain
+separated digest of its own fields.
+
+Legacy descriptor:
+
+```json
+{
+  "v": 2,
+  "pubkey": "<hex 32-byte x-only identity key>",
+  "enc": "<hex 32-byte X25519 public key>",
+  "meeting_node": "host:port",
+  "created": <unix seconds>,
+  "sig": "<hex 64-byte BIP340 Schnorr signature>"
+}
+```
+
+Onion-capable descriptor:
+
+```json
+{
+  "v": 3,
+  "pubkey": "<hex 32-byte x-only identity key>",
+  "enc": "<hex 32-byte X25519 public key>",
+  "meeting_node": "host:port",
+  "onion": "<56-char-v3-name>.onion:8433",
+  "created": <unix seconds>,
+  "sig": "<legacy v2 signature>",
+  "sig3": "<signature over the onion-capable digest>"
+}
+```
+
+The legacy signed digest is:
+
+```
+digest = SHA256( ".btf-descriptor-v2"
+               || pubkey[32]
+               || enc            (raw bytes of the string)
+               || meeting_node   (raw bytes of the string)
+               || created        (8 bytes, big endian) )
+```
+
+`sig` is kept on v3 descriptors so old nodes can still resolve and dial through
+the rendezvous relay. The onion-capable digest is:
+
+```
+digest3 = SHA256( ".btf-descriptor-v3-onion"
+                || pubkey[32]
+                || enc            (raw bytes of the string)
+                || meeting_node   (raw bytes of the string)
+                || onion          (raw bytes of the normalized string)
+                || created        (8 bytes, big endian) )
+```
+
+`sig` and `sig3` are deterministic BIP340 Schnorr signatures (no auxiliary
+randomness) over their respective digests by the identity key.
+
+**Verification** (untrusted input, must never throw): parse the JSON, require all
+fields with the right types, confirm `pubkey` equals the address being resolved,
+recompute the digest, and verify the Schnorr signature. Any failure rejects the
+descriptor.
+
+If `onion` is present, readers accept it only when it is a normalized v3 onion
+endpoint and `sig3` verifies. A bad or tampered onion field is ignored; the v2
+descriptor can still be used for rendezvous fallback if `sig` verifies.
+
+`created` lets a reader prefer the freshest descriptor when more than one is
+seen. A node without a direct onion endpoint only publishes a descriptor once it
+has actually registered at a `meeting_node`, so it never advertises a relay it
+cannot be reached at. A node with a direct onion endpoint may publish before
+rendezvous registration using `meeting_node = "rendezvous-pending"`; Tor peers
+can still dial the signed onion endpoint, and rendezvous becomes fallback once
+registration succeeds.
+
+## 6. Rendezvous transport
+
+The relay is a small TCP server. Every connection opens with a fixed 33 byte
+header:
+
+```
+byte 0     role: 'S' (service) or 'C' (client)
+bytes 1..32 target public key (the .btf identity, 32 bytes)
+```
+
+**Service registration (`S`).** The service connects out to the relay and sends
+`'S' || own_pubkey`. The relay stores the connection in a table keyed by the
+public key and leaves it open, waiting. There is one slot per key: a new
+registration for the same key replaces and closes the old one. The service does
+not block waiting to be paired at registration time; it is considered registered
+the moment the relay reads the header, which is what lets it publish a descriptor
+pointing at this relay.
+
+**Client dial (`C`).** The caller connects out to the same relay and sends
+`'C' || target_pubkey`. The relay looks up the waiting service:
+
+- If present, it removes it from the table, writes a single `0x01` byte to both
+  sockets, and then forwards raw bytes in both directions until either side
+  closes. From this point the relay is a blind pipe.
+- If absent, it writes `0x00` to the caller and closes.
+
+Both sides connect *outbound* to the relay, so neither needs a public IP or an
+open inbound port. The relay never sees the identity of the caller (the caller
+sends no key of its own, only the target it wants).
+
+**Liveness.** A registration socket is idle by design and can outlive the network
+path that created it (a NAT drops the idle mapping, the relay restarts, a route
+changes) with no FIN and nothing readable. TCP keepalive was measured and does
+not reliably detect this. The service therefore imposes its own timeout on the
+wait for the pairing byte and re-registers on expiry. Expiring is not a failure;
+it costs one reconnect per interval and returns the loop to a known state.
+
+## 7. The encrypted channel
+
+Once paired through the relay, the caller and service run an end to end handshake
+and then exchange authenticated frames. The primitive is libsodium
+`crypto_box_curve25519xchacha20poly1305` (X25519 key agreement, XChaCha20-Poly1305
+AEAD), the same construction as Rust's `crypto_box` ChaChaBox.
+
+**Handshake (ephemeral to static).**
+
+1. The caller generates a fresh ephemeral X25519 keypair, computes
+   `shared = X25519(eph_sk, service_enc_pub)` reduced to a box key
+   (`crypto_box_beforenm`), and sends the 32 byte ephemeral public key over the
+   paired pipe.
+2. The service reads the ephemeral public key and computes the same
+   `shared = X25519(enc_sk, eph_pub)`.
+
+Because the caller uses a new ephemeral key per connection, each session has an
+independent key and forward secrecy against later compromise of the service
+encryption key.
+
+**Framing.** Every message is length prefixed:
+
+```
+frame = len[4]  (big endian, length of the body that follows)
+        body    = nonce[24] || ciphertext || mac[16]
+```
+
+The nonce is 24 random bytes per frame (XChaCha20), the MAC is 16 bytes
+(Poly1305). A body shorter than `nonce + mac` or larger than 1 MiB is rejected.
+Decryption that fails authentication drops the frame and tears the tunnel down.
+
+The tunnel is transparent: the application is handed a local socket pair end and
+reads and writes plaintext. Two pump threads move data between that socket and
+the relay socket, encrypting outbound and decrypting inbound.
+
+## 8. End to end connection flow
+
+To dial `X.btf`:
+
+1. Parse `X.btf` to the 32 byte identity key.
+2. Fetch and verify the descriptor over Nostr (kind 38501). Obtain
+   `meeting_node` and `enc`.
+3. Connect to `meeting_node`, send `'C' || X`, and wait for `0x01`.
+4. Generate an ephemeral X25519 key, derive the shared key against `enc`, send
+   the ephemeral public key.
+5. Exchange XChaCha20-Poly1305 frames. Hand the application a local socket that
+   speaks the ordinary peer protocol.
+
+A service, symmetrically: registers at a relay (`'S' || own_pubkey`), publishes a
+descriptor pointing at that relay, waits for `0x01`, reads the caller ephemeral
+public key, derives the shared key with its encryption secret, and serves the
+tunnel.
+
+## 9. Security properties
+
+- **Address unforgeability.** The address is the identity key and the descriptor
+  is Schnorr signed by it, and the Nostr event is signed by it. A relay or Nostr
+  operator cannot publish a working descriptor for an address it does not own.
+- **Relay confidentiality.** The relay forwards ciphertext and never holds the
+  channel key. It cannot read or modify traffic undetected; a tampered frame
+  fails the Poly1305 tag and the tunnel closes.
+- **Caller anonymity to the service and relay.** The caller presents no identity
+  key, only the target it wants to reach. It connects outbound, so its address is
+  not published anywhere.
+- **Forward secrecy.** The caller's per connection ephemeral key means a later
+  compromise of the service encryption key does not decrypt past sessions.
+- **IP privacy.** Neither side needs a public IP or an inbound port for
+  rendezvous. With a signed `.onion` endpoint, the reachable side exposes only a
+  Tor hidden service and the relay is not in the peer connection path.
+
+## 10. Threat model and limitations
+
+- **The relay is trusted for availability, not for confidentiality.** It can
+  refuse to pair, drop a connection, or go offline. This is why relays are
+  plural, auto discovered, and re-registration is periodic. It cannot read
+  traffic.
+- **Traffic analysis is not addressed.** A network observer, or the relay, can
+  see connection timing and byte volumes. There is no padding or mixing.
+- **Single slot registration causes churn.** One waiting slot per key per relay
+  means a race or a stale registration can briefly make a service unreachable at
+  that relay. Multiple relays and the wait timeout bound the damage, but this is
+  a known source of connection churn.
+- **Descriptor freshness is best effort.** `created` is a self reported
+  timestamp; readers prefer the newest descriptor they have seen but there is no
+  global clock.
+- **Discovery depends on public Nostr relays.** If the relays a node uses are all
+  unreachable, discovery stalls until one is reachable again. Relay TLS is
+  verified, which closes a man in the middle path on discovery, but availability
+  still rests on the relay set.
+- **Direct onion needs Tor.** With `-managedtor`, Bitflash starts a Tor process,
+  writes a local hidden-service config, and advertises the generated onion
+  endpoint. With `-onionservice`, an operator can still run Tor manually and
+  provide the endpoint. In both cases Tor owns the hidden-service private key and
+  uptime.
+
+## 11. Wire reference
+
+| Item | Value |
+|---|---|
+| `.btf` Base32 alphabet | `abcdefghijklmnopqrstuvwxyz234567`, no padding |
+| Address payload | `pubkey[32] || checksum[2]`, 55 Base32 chars |
+| Address checksum | `SHA256(".btf-checksum-v1" || pubkey)[0..2]` |
+| Descriptor domain sep | `.btf-descriptor-v2`; optional onion sep `.btf-descriptor-v3-onion` |
+| Descriptor version | `2`; `3` when a signed onion endpoint is present |
+| Descriptor signature | BIP340 Schnorr, deterministic (no aux rand), v3 keeps `sig` plus `sig3` |
+| Nostr descriptor event | kind `38501`, `d = btf-descriptor-2` |
+| Nostr relay event | kind `38502`, `d = btf-relay-2` |
+| Nostr pool event | kind `38503`, `d = btf-pool-2` |
+| Rendezvous port (default) | `8434` |
+| Rendezvous header | `role[1] ('S'/'C') || pubkey[32]`, 33 bytes |
+| Rendezvous pairing byte | `0x01` paired, `0x00` no service |
+| Channel primitive | `crypto_box_curve25519xchacha20poly1305` |
+| Nonce / MAC / key sizes | 24 / 16 / 32 bytes |
+| Frame | `len[4 big endian] || nonce[24] || ct || mac[16]` |
+| Max frame body | 1 MiB |
diff --git a/docs/site.md b/docs/site.md
new file mode 100644
index 0000000..9526a61
--- /dev/null
+++ b/docs/site.md
@@ -0,0 +1,115 @@
+# Public Site Contract
+
+The public Bitflash sites are generated from this repository. If a deployed
+page and the source disagree, the deployed page is stale.
+
+## Canonical Navigation
+
+Every public page should use the same top navigation:
+
+| label | target |
+|---|---|
+| home | `https://bitflash.network/` |
+| code | `https://git.bitflash.network/bitflash/bitflash` |
+| docs | `https://docs.bitflash.network/` |
+| downloads | `https://releases.bitflash.network/` |
+| explorer | `https://explorer.bitflash.network/` |
+| status | `https://status.bitflash.network/` |
+
+The `code` link intentionally points at the repository, not the Forgejo
+instance root. A visitor choosing "code" wants the source tree.
+
+## Documentation Pages To Publish
+
+The docs index should expose these source files:
+
+| page | source | why it matters |
+|---|---|---|
+| Manual | `README.md` | run, mine, recover, operate |
+| Key derivation and address format | `docs/derivation.md` | independent wallet recovery |
+| Release verification | `docs/release-verification.md` | pinned signing-key flow |
+| Dependencies | `docs/dependencies.md` | pinned secp256k1/RandomX supply chain |
+| Rendezvous and .btf addressing | `docs/rendezvous.md` | network design and caveats |
+| Tor mode | `docs/tor.md` | `-tor`, `-socks`, onion relay operation |
+| Fair launch verifier | `docs/fair-launch.md` | no-premine launch audit |
+| UTXO set commitment | `docs/utxo-commitment.md` | deterministic supply/root audit |
+| UTXO inclusion proofs | `docs/utxo-proofs.md` | proof for one unspent output |
+| Mining calculator | `docs/mining-calculator.md` | local WhatToMine-style estimates |
+| Public pool directory | `docs/pool-directory.md` | `pool_status.json`, `pools.json`, ranking |
+
+## Release Mirror Aliases
+
+Each release remains under its versioned directory:
+
+```text
+https://releases.bitflash.network/v1.2.19/SHA256SUMS
+https://releases.bitflash.network/v1.2.19/SHA256SUMS.asc
+```
+
+The release root should also alias the latest files:
+
+```text
+https://releases.bitflash.network/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS.asc
+https://releases.bitflash.network/Bitflash-latest-windows.zip
+https://releases.bitflash.network/Bitflash-latest-x86_64.AppImage
+https://releases.bitflash.network/bitflash-node-latest-x86_64
+```
+
+The aliases are convenience only. Verification must still require the pinned
+release key documented in `docs/release-verification.md`.
+
+## Static Explorer
+
+`scripts/build-explorer.py` writes a static explorer with no backend:
+
+```text
+index.html
+style.css
+explorer.js
+logo.png
+blocks.json
+block/<height>.json
+```
+
+Serve it with a strict content policy:
+
+```text
+default-src 'none';
+img-src 'self';
+style-src 'self';
+script-src 'self';
+connect-src 'self';
+base-uri 'none';
+form-action 'none';
+frame-ancestors 'none';
+```
+
+The viewer must never use `innerHTML` for chain data. A malicious transaction
+must be rendered as text, not interpreted as markup.
+
+## Cache Policy
+
+Recommended defaults:
+
+| path | cache |
+|---|---|
+| HTML pages | `public, max-age=0, must-revalidate` |
+| `status.json` | `no-store` |
+| `blocks.json`, `block/*.json` | `public, max-age=0, must-revalidate` |
+| release assets | `public, max-age=14400, must-revalidate` |
+| `SHA256SUMS`, signatures, keys | `public, max-age=0, must-revalidate` |
+
+## Security Headers
+
+Recommended for all static pages:
+
+```text
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+Referrer-Policy: no-referrer
+Permissions-Policy: interest-cohort=(), geolocation=(), camera=(), microphone=()
+```
+
+Forgejo has its own application headers and should not blindly inherit the
+static-site CSP.
diff --git a/docs/social.png b/docs/social.png
index 19e2a3b..9a08b02 100644
--- a/docs/social.png
+++ b/docs/social.png
diff --git a/docs/storage.md b/docs/storage.md
new file mode 100644
index 0000000..c7de4e7
--- /dev/null
+++ b/docs/storage.md
@@ -0,0 +1,159 @@
+# Bitflash Storage Inventory
+
+This document records the Berkeley DB surface that still exists in Bitflash.
+It is a migration map, not a promise that all stores should move at once.
+
+The immediate priority is `wallet.dat`: it holds spend authority and recovery
+metadata. `blkindex.dat` can be rebuilt from block files, so it is important for
+startup correctness but less dangerous than wallet storage.
+
+## Berkeley DB Environment
+
+All `CDB` stores use one Berkeley DB environment rooted at:
+
+```text
+<datadir>/database/
+```
+
+The environment creates log files such as:
+
+```text
+database/log.0000000001
+```
+
+Those logs are part of the legacy BDB risk model. They are not user-facing
+wallet files, but they can contain historical records while the environment is
+live. Wallet encryption already rewrites `wallet.dat` and purges BDB environment
+logs after the encrypted file is installed.
+
+## Common Records
+
+Every `CDB` file can carry:
+
+| Key | Value | Purpose |
+|---|---|---|
+| `"version"` | `int` | Database format version written when a DB is opened in create mode. |
+
+Keys and values are serialized with the existing `CDataStream` format. A future
+SQLite migration must preserve byte-for-byte value semantics until a higher
+level schema migration is intentionally introduced.
+
+## `wallet.dat`
+
+`wallet.dat` is accessed through `CWalletDB`.
+Read-only tooling should go through `ScanWalletRecords()` instead of opening a
+Berkeley DB cursor directly. That keeps migration checks, audits, and future
+backends behind one record-stream boundary. Wallet rewrite code should also use
+that boundary when it needs to copy existing records into a newly written
+wallet file.
+
+| Key shape | Value | Secret? | Meaning |
+|---|---|---:|---|
+| `("name", address)` | `string` | No | Address book label. |
+| `("tx", txid)` | `CWalletTx` | No | Wallet transaction state, including spend flags and metadata. |
+| `("key", pubkey)` | `CPrivKey` | Yes | Plain private key record for unencrypted wallets or old backups. |
+| `"defaultkey"` | `vector<unsigned char>` | No | Default public key shown by the wallet. |
+| `"hdmaster"` | `vector<unsigned char>` | Yes | Plain BIP32 master private key material. |
+| `"hdchaincode"` | `vector<unsigned char>` | Yes | Plain BIP32 chain code. |
+| `"hdnext"` | `unsigned int` | No | Legacy deterministic derivation next index. |
+| `"hdschema"` | `int` | No | Deterministic derivation schema (`legacy` or `bip44`). |
+| `"hdcointype"` | `unsigned int` | No | BIP44 coin type. Bitflash is `4346950`. |
+| `"hdreceivenext"` | `unsigned int` | No | BIP44 external receive-chain next index. |
+| `"hdchangenext"` | `unsigned int` | No | BIP44 internal change-chain next index. |
+| `("mkey", id)` | `CWalletMasterKey` | Sensitive | Encrypted wallet master-key metadata. |
+| `("ckey", pubkey)` | `vector<unsigned char>` | Yes | Private key encrypted under the wallet master key. |
+| `"cryptedhdmaster"` | `vector<unsigned char>` | Yes | Encrypted BIP32 master private key material. |
+| `"cryptedhdchaincode"` | `vector<unsigned char>` | Yes | Encrypted BIP32 chain code. |
+| `"walletminversion"` | `int` | No | Minimum wallet format version required to open this wallet safely. |
+| `("pool", index)` | `vector<unsigned char>` | No | Public key reserved in the key pool. The private key lives in `key`/`ckey`. |
+| `("setting", name)` | typed setting value | Usually no | Wallet/UI settings such as mining mode, fees, and backup timestamps. |
+
+### Wallet Migration Rules
+
+A future wallet backend must keep these properties:
+
+1. Unknown future wallet formats fail closed with a clear message.
+2. Encrypted wallets must encrypt private keys and HD seed material.
+3. A locked encrypted wallet may expose public keys and balances, but not
+   private keys or decrypted HD seed material.
+4. `-backupwallet` must produce a wallet file that opens in a different datadir
+   without copying `database/`, and must not leave a half-written final backup
+   path if the copy or install step fails.
+5. `-recoveryaudit` must distinguish:
+   - no recovery phrase installed;
+   - recovery phrase present;
+   - recovery phrase encrypted and locked, requiring unlock before coverage can
+     be audited.
+
+## SQLite Wallet Store
+
+Since v1.2.20 SQLite is the default wallet backend. It is a byte-preserving
+record store, not a new wallet format -- the same serialized `CDataStream` bytes
+`wallet.dat` uses:
+
+```sql
+CREATE TABLE wallet_records (
+  key BLOB PRIMARY KEY NOT NULL,
+  value BLOB NOT NULL
+);
+PRAGMA user_version=1;
+```
+
+A fresh data directory starts on `wallet.sqlite`. An existing `wallet.dat` keeps
+running on Berkeley DB until it is converted: the GUI offers a one-click
+conversion on first run, and `-walletbackend=sqlite` / `-walletbackend=bdb`
+(recorded in a plain-text `wallet-backend` marker file in the datadir) select a
+backend explicitly. Conversion never modifies `wallet.dat`; it stays as a
+fallback, and the change takes effect on restart.
+
+Every wallet operation runs on either backend: read, write, erase, key-pool and
+HD-seed writes (the two halves of the seed bracketed in one SQLite transaction),
+`-backupwallet` (checkpoint then copy the self-contained file), `-encryptwallet`
+(an atomic rebuild-and-swap in one transaction), and the `-walletstorageaudit` /
+`-walletstoragecheck` diagnostics, which read the active backend's file.
+
+The migration tooling remains available for scripted use. `-walletsqliteexport=FILE`
+streams every raw `wallet.dat` record through `ScanWalletRecords()` into a SQLite
+file in one transaction, refusing to overwrite. `-walletsqliteverify=FILE`
+compares the two streams and prints only counts. `-walletsqliteloadcheck=FILE`
+parses an export with the same record types the loader uses.
+`-walletsqliterestore=FILE` rebuilds a `wallet.dat` from an export in an empty
+data directory. Failed exports and restores remove their incomplete output.
+
+## `blkindex.dat`
+
+`blkindex.dat` is accessed through `CTxDB`.
+
+| Key shape | Value | Rebuildable? | Meaning |
+|---|---|---:|---|
+| `("tx", txid)` | `CTxIndex` | Yes | Transaction disk position and spent-output index state. |
+| `("owner", hash160, CDiskTxPos)` | `int height` | Yes | Legacy owner transaction index cursor range. |
+| `("blockindex", blockhash)` | `CDiskBlockIndex` | Yes | Block index entry. |
+| `"hashBestChain"` | `uint256` | Yes | Current best-chain tip hash. |
+
+`blkindex.dat` can be rebuilt from `blk*.dat` plus consensus validation. A
+future migration may therefore prefer a rebuild path over a byte-preserving
+conversion path.
+
+## Other Legacy Stores
+
+None. Upstream still documents `reviews.dat` (`CReviewDB`) and `market.dat`
+(`CMarketDB`) here; this fork deleted the 2009 marketplace outright, along
+with `CReviewDB`, `market.cpp` and `market.h`, so neither file is opened or
+created by this tree. A datadir carrying them from an older build is simply
+ignored.
+
+The old IP address database (`addr.dat`) has been removed. Peer discovery is
+handled by Nostr, `.btf`, rendezvous relays, and direct onion peers.
+
+## Migration Order (shipped in v1.2.20)
+
+1. Storage self-tests were added around Berkeley DB behavior first.
+2. The SQLite backend landed behind an explicit flag, then behind a
+   `wallet-backend` marker and a GUI conversion wizard.
+3. BDB-to-SQLite migration is a one-way copy that leaves `wallet.dat` as a backup.
+4. SQLite became the default for new wallets only after cross-version restore,
+   encryption, backup, and recovery-audit tests passed -- and a live coin-proof
+   of receive, spend, restart, and encrypt on real mainnet funds.
+5. Treat `blkindex.dat` separately; it is safer to rebuild than to migrate under
+   pressure.
diff --git a/docs/tor.md b/docs/tor.md
new file mode 100644
index 0000000..0016f8b
--- /dev/null
+++ b/docs/tor.md
@@ -0,0 +1,231 @@
+# Tor mode
+
+Bitflash can route outbound discovery traffic through a local Tor SOCKS5 proxy.
+This is transport plumbing only: it does not change consensus, wallet keys,
+mining, `.btf` addresses, or the encrypted rendezvous protocol.
+
+## Client mode
+
+Start Tor locally, then start Bitflash with:
+
+```bash
+bitflash -tor
+```
+
+`-tor` is shorthand for:
+
+```bash
+bitflash -socks=127.0.0.1:9050
+```
+
+If Tor listens somewhere else:
+
+```bash
+bitflash -tor=127.0.0.1:9150
+bitflash -tor=[::1]:9050
+```
+
+For a SOCKS5 proxy that is not Tor, use `-socks` directly:
+
+```bash
+bitflash -socks=127.0.0.1:9050
+bitflash -socks=[::1]:9050
+```
+
+If both `-tor` and `-socks` are present, Tor mode wins and the node prints a
+warning. That keeps a command line with `-tor` from silently becoming a custom
+proxy route.
+
+## Managed Tor mode
+
+`-managedtor` starts a Tor process for this node, writes a local `torrc`, creates
+a v3 hidden service for the normal Bitflash P2P listener, routes outbound
+discovery through that Tor instance, and signs the generated `.onion:8433`
+endpoint into the node's `.btf` descriptor.
+
+```bash
+bitflash -managedtor
+```
+
+Without a value, Bitflash looks for Tor in this order:
+
+1. `tor/tor.exe` or `tor/tor` beside the Bitflash binary;
+2. `tor.exe` or `tor` beside the Bitflash binary;
+3. `tor.exe` or `tor` on `PATH`.
+
+Windows releases can also be built as `Bitflash-*-windows-with-tor.zip`. That
+package includes the official Tor Expert Bundle under `tor/`, so the first path
+above exists immediately after extraction and `bitflash -managedtor` needs no
+separate Tor install.
+
+The bundled-Tor package is created by:
+
+```bash
+make windows-tor
+```
+
+The packaging script verifies a pinned SHA256 for the downloaded Tor Expert
+Bundle before copying it into the release directory. When `gpg` is available it
+also verifies the matching `.asc` signature against the pinned Tor Browser
+Developers signing-key fingerprint. Release builds should use
+`TOR_VERIFY_GPG=required make windows-tor` to make that second check mandatory.
+The Tor binary is bundled; the runtime data directory, hidden-service key, and
+control cookie are still created under the user's Bitflash data directory.
+
+To point at a specific Tor executable:
+
+```bash
+bitflash -managedtor=/opt/tor/bin/tor
+bitflash -managedtor=C:\Tor Browser\Browser\TorBrowser\Tor\tor.exe
+```
+
+Managed Tor writes its state under the Bitflash data directory:
+
+```text
+managed-tor/
+  torrc
+  data/
+  onion-service/
+```
+
+The private key for the onion address lives in `managed-tor/onion-service/`.
+Back up that directory if you want the same onion address after moving the node.
+Delete it only if you intentionally want a fresh onion endpoint.
+
+`-managedtor` takes precedence over `-tor` and `-socks`, because it must choose
+the local SOCKS port it starts. Diagnostics report the current managed Tor
+state, including the SOCKS port and onion endpoint once Tor has generated it.
+
+When Tor mode is enabled:
+
+- outbound Nostr relay dials use Tor;
+- outbound `.btf` rendezvous relay dials use Tor;
+- outbound direct peer dials prefer signed `.onion` endpoints when a peer
+  advertises one;
+- destination names are sent to Tor as SOCKS5 domain-name CONNECT requests, so
+  the local DNS resolver does not see them;
+- direct `.onion` dials are refused unless a SOCKS5/Tor proxy is enabled;
+- plain HTTP external-IP probes are skipped.
+
+Tor mode affects outbound discovery and relay dials. It does not encrypt
+`wallet.dat`, hide mining rewards on-chain, or change the `.btf` identity. A
+relay still sees the TCP client that connected to it; with Tor mode that client
+is the Tor exit or onion circuit endpoint instead of the user's direct IP.
+
+## What to test
+
+Use the public status page only as a rough health check. To prove the local node
+is using Tor/SOCKS, test from the node machine:
+
+```bash
+bitflash -tor -debug
+```
+
+Then confirm in `debug.log` that Nostr and rendezvous dials report the proxy
+path. A DNS leak test should show no local resolver lookup for relay hostnames:
+the SOCKS5 request uses the domain-name form and asks the proxy to resolve it.
+
+## Onion rendezvous relay
+
+An operator can expose a Bitflash rendezvous relay as a Tor hidden service. The
+node does not create hidden services itself; Tor owns that configuration.
+
+Example `torrc`:
+
+```text
+HiddenServiceDir /var/lib/tor/bitflash-rendezvous/
+HiddenServicePort 8434 127.0.0.1:8434
+```
+
+After restarting Tor, read the generated onion name:
+
+```bash
+sudo cat /var/lib/tor/bitflash-rendezvous/hostname
+```
+
+Then run the relay on localhost/VPS as usual and announce the onion endpoint from
+nodes that use Tor:
+
+```bash
+bitflash -tor -rvrelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
+bitflash -tor -announcerelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
+```
+
+For a pool operator that wants the pool descriptor to point at an onion
+rendezvous relay, use both:
+
+```bash
+bitflash -operator -tor \
+  -rvrelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434 \
+  -announcerelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
+```
+
+## Manual direct full-node hidden service
+
+Managed Tor is the preferred path for ordinary nodes. Operators can still expose
+the P2P listener through a separately managed Tor service:
+
+```text
+HiddenServiceDir /var/lib/tor/bitflash-node/
+HiddenServicePort 8433 127.0.0.1:8433
+```
+
+After restarting Tor, read the generated onion name:
+
+```bash
+sudo cat /var/lib/tor/bitflash-node/hostname
+```
+
+Then start Bitflash with Tor outbound enabled and advertise that hidden service:
+
+```bash
+bitflash -tor \
+  -onionservice=exampleexampleexampleexampleexampleexampleexampleexample.onion:8433
+```
+
+That onion endpoint is signed into this node's self-certifying `.btf`
+descriptor. New peers that resolve the descriptor and also run with `-tor` try
+the `.onion:8433` P2P connection first. If it fails, they fall back to the
+ordinary encrypted rendezvous path. Older nodes ignore the onion field and still
+use the rendezvous relay because the descriptor keeps the legacy signature too.
+
+If the node has `-onionservice` but has not registered at any rendezvous relay
+yet, it can still publish an onion-capable descriptor with
+`meeting_node = rendezvous-pending`. Tor-capable peers can dial the hidden
+service directly from that descriptor. Rendezvous becomes a fallback, not a
+precondition for being discoverable.
+
+This means rendezvous relays stop being the only way to reach a node that has
+published a hidden service. They remain useful bootstrap/fallback infrastructure,
+but an already-discovered onion-capable peer can be reached directly over Tor.
+
+Tor owns the private key under `HiddenServiceDir`; back it up if you want the
+onion name to stay stable.
+
+## Release smoke test
+
+After building a Windows binary with managed Tor support, run the two-node smoke
+test before cutting a release:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\smoke-managed-tor-onion.ps1 `
+  -Bitflash .\src\bitflash.exe `
+  -Tor C:\path\to\tor.exe
+```
+
+The script creates two temporary datadirs, starts node A with `-managedtor`,
+waits for it to publish its `.btf` identity and generated `.onion` endpoint,
+then starts node B with its own `-managedtor`, `-oniononly`, and
+`-connectbtf=<node-a>`. It passes only when node B logs that it connected to
+node A `via direct onion`; rendezvous fallback cannot satisfy the test.
+
+By default the script waits 120 seconds after node A's descriptor self-resolves
+before it starts node B. Tor can create the local `hostname` before the hidden
+service descriptor is visible enough for client circuits, and early dials often
+fail with SOCKS5 reply `0x01`. Override this with `-OnionWarmupSec N` when
+testing a slow or already-warmed Tor environment.
+
+This test still uses Nostr for descriptor discovery, because that is how nodes
+learn each other's signed `.btf` descriptors. It does not require a Bitflash
+rendezvous relay to carry the P2P connection: once the descriptor includes the
+signed onion endpoint, the actual node connection goes directly through Tor.
diff --git a/docs/utxo-commitment.md b/docs/utxo-commitment.md
new file mode 100644
index 0000000..ab43deb
--- /dev/null
+++ b/docs/utxo-commitment.md
@@ -0,0 +1,125 @@
+# Bitflash UTXO-set commitment
+
+`scripts/verify-utxo-set.py` reconstructs a deterministic commitment to the
+current UTXO set from local `blk*.dat` files.
+
+This is intentionally not a consensus rule yet. It is an audit tool: independent
+operators can run it against the same chain prefix and compare the resulting
+root and canonical JSON hash.
+
+```bash
+python3 scripts/verify-utxo-set.py --max-blocks 1000 --out utxo-report.json --json
+```
+
+Use `--max-blocks 0` or omit the option to scan every available block file:
+
+```bash
+python3 scripts/verify-utxo-set.py --out utxo-report.json --json
+```
+
+## What It Verifies
+
+The verifier:
+
+- parses Bitflash block files directly with the shared Python chain parser;
+- streams `blk*.dat` records instead of loading full block files into memory;
+- reconstructs the best chain rooted at the Bitflash genesis block;
+- ignores side blocks that may also be present in `blk*.dat`;
+- verifies every scanned block merkle root;
+- applies spends and creates outputs in deterministic order;
+- reports current UTXO count, current supply, mined coinbase total, fees, and
+  historical duplicate-output overwrites;
+- computes a deterministic UTXO root.
+
+## Commitment Algorithm
+
+The UTXO map is keyed by:
+
+```text
+txid:vout
+```
+
+Keys are sorted lexicographically. Each leaf is:
+
+```text
+SHA256("BTFUTXO1|" || outpoint || "|" || value_satoshis || "|" ||
+       script_pub_key_hex || "|" || created_height || "|" || created_txid)
+```
+
+The tree is then reduced pairwise. If a level has an odd number of hashes, the
+last hash is duplicated. Each parent is:
+
+```text
+SHA256("BTFNODE1|" || left_hash || right_hash)
+```
+
+The final hash is the UTXO-set root.
+
+## Inclusion Proofs
+
+After a root has been computed, `scripts/prove-utxo.py` can create a compact
+inclusion proof for one unspent output:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+The verifier does not need local block files. It recomputes the target leaf,
+walks the sibling path, and compares the result with the expected root. See
+[UTXO inclusion proofs](utxo-proofs.md).
+
+## Deterministic Output
+
+`--json` and `--out` write canonical JSON with sorted keys, fixed separators,
+ASCII escaping, and one trailing newline. It contains no local path and no
+generation timestamp, so two auditors scanning the same chain prefix should
+produce byte-identical reports.
+
+```bash
+python3 scripts/verify-utxo-set.py --out utxo-report.json --json
+sha256sum utxo-report.json
+```
+
+## OpenTimestamps
+
+The canonical JSON can be timestamped in Bitcoin without adding any dependency
+to Bitflash consensus:
+
+```bash
+ots stamp utxo-report.json
+ots verify utxo-report.json.ots
+```
+
+## Historical Duplicates
+
+Bitflash inherited early Bitcoin behavior around duplicate transaction IDs.
+The verifier reports duplicate-output overwrites as warnings and uses
+last-write-wins semantics for the UTXO map, matching the legacy index model.
+Those warnings are part of the report so auditors can see the historical debt
+instead of relying on a polished summary.
+
+For synthetic chains or future clean consensus ranges, auditors can make
+duplicates a hard failure:
+
+```bash
+python3 scripts/verify-utxo-set.py --strict-duplicates
+```
+
+The default remains compatible with the current historical chain because it has
+known legacy duplicate-output overwrites.
+
+## Shared Parser
+
+The audit scripts share `scripts/bitflash_chain.py` for block parsing,
+main-chain selection, UTXO application, canonical JSON, and genesis
+reconstruction. That keeps `verify-utxo-set.py`, `verify-fair-launch.py`,
+`prove-utxo.py`, and the explorer on the same serialization rules.
+
+## Future Consensus Path
+
+This tool is the low-risk first step toward consensus commitments. A future
+hard-fork design can commit this root, or a Utreexo-style accumulator root, in
+coinbase or block headers after a fixed activation height. Until then this
+script provides reproducible supply and state commitments without changing what
+nodes accept.
diff --git a/docs/utxo-proofs.md b/docs/utxo-proofs.md
new file mode 100644
index 0000000..4947c3c
--- /dev/null
+++ b/docs/utxo-proofs.md
@@ -0,0 +1,61 @@
+# Bitflash UTXO inclusion proofs
+
+`scripts/prove-utxo.py` creates a deterministic inclusion proof for one
+currently unspent output. `scripts/verify-utxo-proof.py` verifies that proof
+against the UTXO root produced by `scripts/verify-utxo-set.py`.
+
+This is intentionally outside consensus. It turns the audit root into something
+useful for a specific coin without changing what nodes accept.
+
+## Create A Proof
+
+Use an unspent output in `txid:vout` form:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+```
+
+The proof contains:
+
+- the target UTXO;
+- its sorted leaf index;
+- the leaf hash;
+- the Merkle sibling path;
+- the UTXO root and chain tip used to create it.
+
+It does not contain the full UTXO set.
+
+## Verify A Proof
+
+Verify against the root embedded in the proof:
+
+```bash
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+Or verify against a root copied from another machine, dashboard, block explorer,
+or future node export:
+
+```bash
+python3 scripts/verify-utxo-proof.py utxo-proof.json \
+  --root ROOT_FROM_REPORT_OR_EXPORT
+```
+
+The verifier does not need local `blk*.dat` files. It only needs the proof and
+the expected root.
+
+## Scope
+
+This first proof format supports inclusion only. Absence and range proofs are
+left for a later design because they require a more careful commitment scheme
+and are easier to get subtly wrong.
+
+The proof uses the exact same leaf and node domains as the UTXO commitment:
+
+```text
+BTFUTXO1
+BTFNODE1
+```
+
+That keeps the verifier language-neutral and gives future implementations a
+small, stable target.
diff --git a/scripts/bitflash-mining-calculator.py b/scripts/bitflash-mining-calculator.py
new file mode 100644
index 0000000..1fcc1a9
--- /dev/null
+++ b/scripts/bitflash-mining-calculator.py
@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Estimate Bitflash mining rewards and electricity cost.
+
+This is a local WhatToMine-style calculator for Bitflash. It does not fetch
+prices, does not talk to the node, and does not affect consensus.
+"""
+
+import argparse
+import json
+import math
+import sys
+
+
+HASHES_AT_DIFF_1 = 4096.0
+DEFAULT_BLOCK_TIME = 120.0
+DEFAULT_BLOCK_REWARD = 50.0
+
+
+UNITS = {
+    "h": 1.0,
+    "h/s": 1.0,
+    "hs": 1.0,
+    "kh": 1_000.0,
+    "kh/s": 1_000.0,
+    "khs": 1_000.0,
+    "mh": 1_000_000.0,
+    "mh/s": 1_000_000.0,
+    "mhs": 1_000_000.0,
+    "gh": 1_000_000_000.0,
+    "gh/s": 1_000_000_000.0,
+    "ghs": 1_000_000_000.0,
+}
+
+
+def parse_hashrate(value, unit):
+    try:
+        n = float(value)
+    except ValueError:
+        raise SystemExit("invalid hashrate: %s" % value)
+    mul = UNITS.get(unit.lower())
+    if mul is None:
+        raise SystemExit("unknown hashrate unit: %s" % unit)
+    if n < 0:
+        raise SystemExit("hashrate must not be negative")
+    return n * mul
+
+
+def fmt_hashrate(hps):
+    units = [("GH/s", 1_000_000_000.0), ("MH/s", 1_000_000.0), ("kH/s", 1_000.0), ("H/s", 1.0)]
+    for name, div in units:
+        if hps >= div:
+            return "%.4g %s" % (hps / div, name)
+    return "%.4g H/s" % hps
+
+
+def fmt_money(x):
+    return "%.8f" % x
+
+
+def estimate(args):
+    miner_hps = parse_hashrate(args.hashrate, args.hashrate_unit)
+    if args.network_hashrate is not None:
+        network_hps = parse_hashrate(args.network_hashrate, args.network_hashrate_unit)
+        difficulty = network_hps * args.block_time / HASHES_AT_DIFF_1
+        network_source = "network_hashrate"
+    else:
+        if args.difficulty is None:
+            raise SystemExit("provide either --network-hashrate or --difficulty")
+        difficulty = float(args.difficulty)
+        if difficulty <= 0:
+            raise SystemExit("difficulty must be positive")
+        network_hps = difficulty * HASHES_AT_DIFF_1 / args.block_time
+        network_source = "difficulty"
+
+    if network_hps <= 0:
+        raise SystemExit("network hashrate must be positive")
+
+    block_reward = float(args.block_reward)
+    block_time = float(args.block_time)
+    pool_fee_percent = float(args.pool_fee)
+    price = float(args.price)
+    watts = float(args.watts)
+    kwh_cost = float(args.kwh_cost)
+    if block_reward < 0 or block_time <= 0 or pool_fee_percent < 0 or price < 0 or watts < 0 or kwh_cost < 0:
+        raise SystemExit("numeric inputs must be non-negative; block time must be positive")
+
+    share = miner_hps / network_hps
+    blocks_per_day = 86400.0 / block_time
+    gross_btf_day = blocks_per_day * block_reward * share
+    net_btf_day = gross_btf_day * max(0.0, 1.0 - pool_fee_percent / 100.0)
+    revenue_day = net_btf_day * price
+    cost_day = watts / 1000.0 * 24.0 * kwh_cost
+    profit_day = revenue_day - cost_day
+    expected_seconds_per_block = math.inf if miner_hps <= 0 else difficulty * HASHES_AT_DIFF_1 / miner_hps
+
+    periods = {
+        "hour": 1.0 / 24.0,
+        "day": 1.0,
+        "week": 7.0,
+        "month_30d": 30.0,
+    }
+    rows = {}
+    for name, days in periods.items():
+        rows[name] = {
+            "btf": net_btf_day * days,
+            "revenue": revenue_day * days,
+            "electricity_cost": cost_day * days,
+            "profit": profit_day * days,
+        }
+
+    return {
+        "schema": "bitflash-mining-calculator-1",
+        "network_source": network_source,
+        "inputs": {
+            "miner_hashrate_hps": miner_hps,
+            "miner_hashrate": fmt_hashrate(miner_hps),
+            "network_hashrate_hps": network_hps,
+            "network_hashrate": fmt_hashrate(network_hps),
+            "difficulty": difficulty,
+            "block_time_seconds": block_time,
+            "block_reward_btf": block_reward,
+            "pool_fee_percent": pool_fee_percent,
+            "price_per_btf": price,
+            "power_watts": watts,
+            "electricity_per_kwh": kwh_cost,
+        },
+        "estimates": {
+            "miner_network_share": share,
+            "blocks_per_day": blocks_per_day,
+            "expected_time_to_solo_block_seconds": expected_seconds_per_block,
+            "expected_time_to_solo_block_hours": expected_seconds_per_block / 3600.0,
+            "gross_btf_per_day": gross_btf_day,
+            "net_btf_per_day": net_btf_day,
+            "periods": rows,
+        },
+    }
+
+
+def print_text(result):
+    i = result["inputs"]
+    e = result["estimates"]
+    print("Bitflash mining calculator")
+    print("schema: %s" % result["schema"])
+    print()
+    print("Network")
+    print("  source:      %s" % result["network_source"])
+    print("  hashrate:    %s" % i["network_hashrate"])
+    print("  difficulty:  %.8f" % i["difficulty"])
+    print("  block time:  %.0fs" % i["block_time_seconds"])
+    print("  reward:      %s BTF" % fmt_money(i["block_reward_btf"]))
+    print()
+    print("Miner")
+    print("  hashrate:    %s" % i["miner_hashrate"])
+    print("  share:       %.8f%%" % (e["miner_network_share"] * 100.0))
+    if math.isinf(e["expected_time_to_solo_block_seconds"]):
+        print("  solo block:  never")
+    else:
+        print("  solo block:  %.2f hours expected average" % e["expected_time_to_solo_block_hours"])
+    print()
+    print("Economics")
+    print("  price:       $%.8f / BTF" % i["price_per_btf"])
+    print("  power:       %.2f W" % i["power_watts"])
+    print("  kWh cost:    $%.4f" % i["electricity_per_kwh"])
+    print("  pool fee:    %.2f%%" % i["pool_fee_percent"])
+    print()
+    print("Estimated rewards")
+    print("  %-9s %16s %12s %12s %12s" % ("period", "BTF", "revenue", "power", "profit"))
+    for name in ["hour", "day", "week", "month_30d"]:
+        row = e["periods"][name]
+        print("  %-9s %16s $%11.4f $%11.4f $%11.4f" % (
+            name,
+            fmt_money(row["btf"]),
+            row["revenue"],
+            row["electricity_cost"],
+            row["profit"],
+        ))
+    print()
+    print("Note: this is an expectation, not a promise. Solo mining variance can be huge.")
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--hashrate", required=True, help="miner hashrate number")
+    ap.add_argument("--hashrate-unit", default="kh/s", choices=sorted(UNITS), help="miner hashrate unit")
+    ap.add_argument("--network-hashrate", help="network hashrate number")
+    ap.add_argument("--network-hashrate-unit", default="kh/s", choices=sorted(UNITS), help="network hashrate unit")
+    ap.add_argument("--difficulty", type=float, help="Bitflash difficulty; diff 1 expects 4096 hashes")
+    ap.add_argument("--block-time", type=float, default=DEFAULT_BLOCK_TIME, help="target block time in seconds")
+    ap.add_argument("--block-reward", type=float, default=DEFAULT_BLOCK_REWARD, help="block reward in BTF")
+    ap.add_argument("--pool-fee", type=float, default=0.0, help="pool fee percent")
+    ap.add_argument("--price", type=float, default=0.0, help="price per BTF in USD or your chosen fiat unit")
+    ap.add_argument("--watts", type=float, default=0.0, help="miner or whole-system power in watts")
+    ap.add_argument("--kwh-cost", type=float, default=0.0, help="electricity cost per kWh")
+    ap.add_argument("--json", action="store_true", help="print JSON")
+    args = ap.parse_args(argv)
+
+    result = estimate(args)
+    if args.json:
+        print(json.dumps(result, sort_keys=True, indent=2))
+    else:
+        print_text(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/bitflash_chain.py b/scripts/bitflash_chain.py
new file mode 100644
index 0000000..4a3231c
--- /dev/null
+++ b/scripts/bitflash_chain.py
@@ -0,0 +1,450 @@
+#!/usr/bin/env python3
+"""Shared Bitflash block/chain parser for deterministic audit tools."""
+
+import datetime as _dt
+import hashlib
+import json
+import mmap
+import os
+import struct
+from pathlib import Path
+
+
+MAGIC = bytes([0xBF, 0x20, 0x5C, 0xFD])
+MAX_BLOCK_PAYLOAD = 32 * 1024 * 1024
+UTXO_LEAF_DOMAIN = "BTFUTXO1"
+UTXO_NODE_DOMAIN_TAG = "BTFNODE1"
+UTXO_NODE_DOMAIN = (UTXO_NODE_DOMAIN_TAG + "|").encode("ascii")
+COIN = 100_000_000
+GENESIS_HASH = "5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169"
+GENESIS_MERKLE = "1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325"
+GENESIS_TIME = 1_753_315_200
+GENESIS_BITS = 0x1F0FFFFF
+GENESIS_NONCE = 3141
+GENESIS_TEXT = "Bitflash 24/Jul/2026 Fair launch: one CPU one vote, no premine"
+
+
+class ParseError(Exception):
+    pass
+
+
+class Reader:
+    def __init__(self, data):
+        self.data = data
+        self.pos = 0
+
+    def take(self, n):
+        if self.pos + n > len(self.data):
+            raise ParseError("unexpected end of data")
+        out = self.data[self.pos:self.pos + n]
+        self.pos += n
+        return out
+
+    def u8(self):
+        return self.take(1)[0]
+
+    def u32(self):
+        return struct.unpack("<I", self.take(4))[0]
+
+    def i32(self):
+        return struct.unpack("<i", self.take(4))[0]
+
+    def i64(self):
+        return struct.unpack("<q", self.take(8))[0]
+
+
+def sha256(data):
+    return hashlib.sha256(data).digest()
+
+
+def sha256d(data):
+    return hashlib.sha256(hashlib.sha256(data).digest()).digest()
+
+
+def hash_hex(serialized):
+    return sha256d(serialized)[::-1].hex()
+
+
+def compact_size(r):
+    first = r.u8()
+    if first < 253:
+        return first
+    if first == 253:
+        return struct.unpack("<H", r.take(2))[0]
+    if first == 254:
+        return r.u32()
+    return struct.unpack("<Q", r.take(8))[0]
+
+
+def read_varbytes(r):
+    return r.take(compact_size(r))
+
+
+def ser_compact_size(n):
+    if n < 253:
+        return bytes([n])
+    if n <= 0xFFFF:
+        return b"\xfd" + struct.pack("<H", n)
+    if n <= 0xFFFFFFFF:
+        return b"\xfe" + struct.pack("<I", n)
+    return b"\xff" + struct.pack("<Q", n)
+
+
+def ser_varbytes(b):
+    return ser_compact_size(len(b)) + b
+
+
+def ser_tx(tx):
+    out = bytearray()
+    out += struct.pack("<i", tx["version"])
+    out += ser_compact_size(len(tx["vin"]))
+    for txin in tx["vin"]:
+        out += bytes.fromhex(txin["prevout_hash"])[::-1]
+        out += struct.pack("<I", txin["prevout_n"])
+        out += ser_varbytes(bytes.fromhex(txin["script_sig_hex"]))
+        out += struct.pack("<I", txin["sequence"])
+    out += ser_compact_size(len(tx["vout"]))
+    for txout in tx["vout"]:
+        out += struct.pack("<q", txout["value_satoshis"])
+        out += ser_varbytes(bytes.fromhex(txout["script_pub_key_hex"]))
+    out += struct.pack("<I", tx["lock_time"])
+    return bytes(out)
+
+
+def parse_tx(r):
+    start = r.pos
+    tx = {"version": r.i32(), "vin": [], "vout": [], "lock_time": 0}
+    for _ in range(compact_size(r)):
+        tx["vin"].append({
+            "prevout_hash": r.take(32)[::-1].hex(),
+            "prevout_n": r.u32(),
+            "script_sig_hex": read_varbytes(r).hex(),
+            "sequence": r.u32(),
+        })
+    for _ in range(compact_size(r)):
+        value = r.i64()
+        tx["vout"].append({
+            "value_satoshis": value,
+            "value_btf": format_money(value),
+            "script_pub_key_hex": read_varbytes(r).hex(),
+        })
+    tx["lock_time"] = r.u32()
+    raw = r.data[start:r.pos]
+    tx["txid"] = hash_hex(raw)
+    return tx
+
+
+def merkle_root(txids):
+    if not txids:
+        return "0" * 64
+    layer = [bytes.fromhex(x)[::-1] for x in txids]
+    while len(layer) > 1:
+        nxt = []
+        for i in range(0, len(layer), 2):
+            left = layer[i]
+            right = layer[i + 1] if i + 1 < len(layer) else left
+            nxt.append(sha256d(left + right))
+        layer = nxt
+    return layer[0][::-1].hex()
+
+
+def parse_block(payload, file_name="", offset=0):
+    r = Reader(payload)
+    header = r.take(80)
+    version, = struct.unpack("<i", header[0:4])
+    prev = header[4:36][::-1].hex()
+    merkle = header[36:68][::-1].hex()
+    ntime, bits, nonce = struct.unpack("<III", header[68:80])
+    txs = [parse_tx(r) for _ in range(compact_size(r))]
+    if r.pos != len(payload):
+        raise ParseError("trailing bytes inside block")
+    txids = [tx["txid"] for tx in txs]
+    return {
+        "hash": hash_hex(header),
+        "version": version,
+        "previous_hash": prev,
+        "merkle_root": merkle,
+        "computed_merkle_root": merkle_root(txids),
+        "time": ntime,
+        "time_utc": utc(ntime),
+        "bits": "0x%08x" % bits,
+        "nonce": nonce,
+        "tx_count": len(txs),
+        "transactions": txs,
+        "source_file": file_name,
+        "source_offset": offset,
+        "size": len(payload),
+    }
+
+
+def iter_block_files(datadir):
+    for path in sorted(Path(datadir).glob("blk*.dat")):
+        yield path
+
+
+def iter_blocks_from_file(path):
+    path = Path(path)
+    with path.open("rb") as f:
+        f.seek(0, os.SEEK_END)
+        file_size = f.tell()
+        if file_size == 0:
+            return
+        f.seek(0)
+        mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ)
+        try:
+            pos = 0
+            while True:
+                offset = mm.find(MAGIC, pos)
+                if offset < 0 or offset + 8 > file_size:
+                    break
+                size = struct.unpack("<I", mm[offset + 4:offset + 8])[0]
+                payload_offset = offset + 8
+                end = payload_offset + size
+                if size == 0 or size > MAX_BLOCK_PAYLOAD or end > file_size:
+                    pos = offset + 1
+                    continue
+                payload = mm[payload_offset:end]
+                try:
+                    yield parse_block(payload, path.name, payload_offset)
+                except ParseError:
+                    pos = offset + 1
+                    continue
+                pos = end
+        finally:
+            mm.close()
+
+
+def read_blocks_from_files(paths, max_blocks=0):
+    blocks = []
+    for path in paths:
+        for block in iter_blocks_from_file(path):
+            blocks.append(block)
+            if max_blocks and len(blocks) >= max_blocks:
+                return blocks
+    return blocks
+
+
+def read_blocks(datadir, max_blocks=0):
+    return read_blocks_from_files(iter_block_files(datadir), max_blocks)
+
+
+def select_main_chain(blocks):
+    by_hash = {}
+    for block in blocks:
+        by_hash.setdefault(block["hash"], block)
+    if GENESIS_HASH not in by_hash:
+        raise ParseError("genesis block not found in block files")
+
+    children = {}
+    for block in by_hash.values():
+        children.setdefault(block["previous_hash"], []).append(block)
+    for v in children.values():
+        v.sort(key=lambda b: (b["hash"], b["source_file"], b["source_offset"]))
+
+    best = []
+    stack = [(by_hash[GENESIS_HASH], [by_hash[GENESIS_HASH]])]
+    while stack:
+        block, path = stack.pop()
+        if len(path) > len(best) or (len(path) == len(best) and block["hash"] < best[-1]["hash"]):
+            best = path
+        for child in children.get(block["hash"], []):
+            stack.append((child, path + [child]))
+    return best
+
+
+def is_coinbase(tx):
+    return (
+        len(tx["vin"]) == 1
+        and tx["vin"][0]["prevout_hash"] == "0" * 64
+        and tx["vin"][0]["prevout_n"] == 0xFFFFFFFF
+    )
+
+
+def utxo_leaf_hash(outpoint, utxo):
+    payload = "|".join([
+        UTXO_LEAF_DOMAIN,
+        outpoint,
+        str(utxo["value_satoshis"]),
+        utxo["script_pub_key_hex"],
+        str(utxo["created_height"]),
+        utxo["created_txid"],
+    ]).encode("ascii")
+    return sha256(payload)
+
+
+def utxo_root(utxos):
+    leaves = [utxo_leaf_hash(k, utxos[k]) for k in sorted(utxos)]
+    if not leaves:
+        return sha256(b"BTFUTXO1|empty").hex()
+    layer = leaves
+    while len(layer) > 1:
+        nxt = []
+        for i in range(0, len(layer), 2):
+            left = layer[i]
+            right = layer[i + 1] if i + 1 < len(layer) else left
+            nxt.append(sha256(UTXO_NODE_DOMAIN + left + right))
+        layer = nxt
+    return layer[0].hex()
+
+
+def apply_blocks(blocks, strict_duplicates=False):
+    utxos = {}
+    spent = 0
+    missing_spends = []
+    duplicate_outputs = []
+    total_coinbase = 0
+    total_fees = 0
+    normal_txs = 0
+
+    for height, block in enumerate(blocks):
+        if block["computed_merkle_root"] != block["merkle_root"]:
+            raise ParseError("bad merkle root at height %d" % height)
+        for tx in block["transactions"]:
+            coinbase = is_coinbase(tx)
+            input_value = 0
+            output_value = sum(out["value_satoshis"] for out in tx["vout"])
+            if coinbase:
+                total_coinbase += output_value
+            else:
+                normal_txs += 1
+                for txin in tx["vin"]:
+                    prev = "%s:%d" % (txin["prevout_hash"], txin["prevout_n"])
+                    prev_utxo = utxos.pop(prev, None)
+                    if prev_utxo is None:
+                        missing_spends.append({
+                            "height": height,
+                            "txid": tx["txid"],
+                            "missing_outpoint": prev,
+                        })
+                    else:
+                        spent += prev_utxo["value_satoshis"]
+                        input_value += prev_utxo["value_satoshis"]
+                if input_value >= output_value:
+                    total_fees += input_value - output_value
+            for n, out in enumerate(tx["vout"]):
+                key = "%s:%d" % (tx["txid"], n)
+                if key in utxos:
+                    if strict_duplicates:
+                        raise ParseError("duplicate output at height %d: %s" % (height, key))
+                    duplicate_outputs.append({"height": height, "outpoint": key})
+                utxos[key] = {
+                    "txid": tx["txid"],
+                    "vout": n,
+                    "value_satoshis": out["value_satoshis"],
+                    "value_btf": out["value_btf"],
+                    "script_pub_key_hex": out["script_pub_key_hex"],
+                    "created_height": height,
+                    "created_block_hash": block["hash"],
+                    "created_txid": tx["txid"],
+                    "coinbase": coinbase,
+                }
+
+    total_unspent = sum(u["value_satoshis"] for u in utxos.values())
+    return {
+        "utxos": utxos,
+        "stats": {
+            "utxo_count": len(utxos),
+            "spent_outputs": spent,
+            "total_unspent_satoshis": total_unspent,
+            "total_unspent_btf": format_money(total_unspent),
+            "total_coinbase_satoshis": total_coinbase,
+            "total_coinbase_btf": format_money(total_coinbase),
+            "coinbase_minus_unspent_satoshis": total_coinbase - total_unspent,
+            "coinbase_minus_unspent_btf": format_money(total_coinbase - total_unspent),
+            "total_fees_satoshis": total_fees,
+            "total_fees_btf": format_money(total_fees),
+            "normal_transactions": normal_txs,
+            "missing_spends": missing_spends,
+            "duplicate_outputs": duplicate_outputs,
+        },
+    }
+
+
+def genesis_transaction():
+    script_sig = (
+        bytes.fromhex("04ffff001d")
+        + b"\x01\x04"
+        + bytes([len(GENESIS_TEXT)])
+        + GENESIS_TEXT.encode("ascii")
+    )
+    pubkey_num = bytes.fromhex(
+        "5f1df16b2b704c8a578d0bbaf74d385cde12c11ee50455f3c438ef4c3fbcf649"
+        "b6de611feae06279a60939e028a8d65c10b73071a6f16719274855feb0fd8a6704"
+    )
+    script_pub_key = bytes([65]) + pubkey_num[::-1] + b"\xac"
+    tx = {
+        "version": 1,
+        "vin": [{
+            "prevout_hash": "0" * 64,
+            "prevout_n": 0xFFFFFFFF,
+            "script_sig_hex": script_sig.hex(),
+            "sequence": 0xFFFFFFFF,
+        }],
+        "vout": [{
+            "value_satoshis": 50 * COIN,
+            "value_btf": format_money(50 * COIN),
+            "script_pub_key_hex": script_pub_key.hex(),
+        }],
+        "lock_time": 0,
+    }
+    tx["txid"] = hash_hex(ser_tx(tx))
+    return tx
+
+
+def reconstructed_genesis():
+    tx = genesis_transaction()
+    header = (
+        struct.pack("<i", 1)
+        + bytes(32)
+        + bytes.fromhex(tx["txid"])[::-1]
+        + struct.pack("<III", GENESIS_TIME, GENESIS_BITS, GENESIS_NONCE)
+    )
+    return {
+        "hash": hash_hex(header),
+        "version": 1,
+        "previous_hash": "0" * 64,
+        "merkle_root": tx["txid"],
+        "computed_merkle_root": tx["txid"],
+        "time": GENESIS_TIME,
+        "time_utc": utc(GENESIS_TIME),
+        "bits": "0x%08x" % GENESIS_BITS,
+        "nonce": GENESIS_NONCE,
+        "tx_count": 1,
+        "transactions": [tx],
+        "source_file": "reconstructed-from-source-constants",
+        "source_offset": 0,
+        "size": 80 + len(ser_compact_size(1)) + len(ser_tx(tx)),
+    }
+
+
+def ser_block(block):
+    header = (
+        struct.pack("<i", block["version"])
+        + bytes.fromhex(block["previous_hash"])[::-1]
+        + bytes.fromhex(block["merkle_root"])[::-1]
+        + struct.pack("<III", block["time"], int(block["bits"], 16), block["nonce"])
+    )
+    txs = block["transactions"]
+    return header + ser_compact_size(len(txs)) + b"".join(ser_tx(tx) for tx in txs)
+
+
+def format_money(value):
+    sign = "-" if value < 0 else ""
+    value = abs(value)
+    return "%s%d.%08d" % (sign, value // COIN, value % COIN)
+
+
+def utc(ts):
+    return _dt.datetime.fromtimestamp(ts, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def default_datadir():
+    if os.name == "nt" and os.environ.get("APPDATA"):
+        return os.path.join(os.environ["APPDATA"], "Bitflash")
+    if os.environ.get("HOME"):
+        return os.path.join(os.environ["HOME"], ".bitflash")
+    return "."
+
+
+def canonical_bytes(report):
+    return (json.dumps(report, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
diff --git a/scripts/build-explorer.py b/scripts/build-explorer.py
new file mode 100755
index 0000000..dbb8e17
--- /dev/null
+++ b/scripts/build-explorer.py
@@ -0,0 +1,376 @@
+#!/usr/bin/env python3
+"""Build a static Bitflash block explorer from local blk*.dat files."""
+
+import argparse
+import hashlib
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+
+ADDRESS_VERSION = 25
+B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+
+def b58check(payload):
+    v = bytes([ADDRESS_VERSION]) + payload
+    v += chain.sha256d(v)[:4]
+    n = int.from_bytes(v, "big")
+    s = ""
+    while n > 0:
+        n, r = divmod(n, 58)
+        s = B58[r] + s
+    for byte in v:
+        if byte == 0:
+            s = "1" + s
+        else:
+            break
+    return s
+
+
+def hash160(b):
+    return hashlib.new("ripemd160", hashlib.sha256(b).digest()).digest()
+
+
+def spk_info(script_hex):
+    try:
+        spk = bytes.fromhex(script_hex)
+    except ValueError:
+        return {"type": "malformed", "hex": script_hex[:80]}
+    if (
+        len(spk) == 25 and spk[0] == 0x76 and spk[1] == 0xA9
+        and spk[2] == 0x14 and spk[23] == 0x88 and spk[24] == 0xAC
+    ):
+        return {"type": "p2pkh", "address": b58check(spk[3:23])}
+    if len(spk) >= 35 and spk[-1] == 0xAC:
+        if spk[0] == 0x41 and len(spk) == 67:
+            pk = spk[1:66]
+            return {"type": "p2pk", "pubkey": pk.hex(), "address": b58check(hash160(pk))}
+        if spk[0] == 0x21 and len(spk) == 35:
+            pk = spk[1:34]
+            return {"type": "p2pk", "pubkey": pk.hex(), "address": b58check(hash160(pk))}
+    return {"type": "other", "hex": script_hex[:80]}
+
+
+def explorer_tx(tx):
+    vin = []
+    for txin in tx["vin"]:
+        coinbase = (
+            txin["prevout_hash"] == "0" * 64
+            and txin["prevout_n"] == 0xFFFFFFFF
+        )
+        vin.append({
+            "coinbase": coinbase,
+            "prev": None if coinbase else txin["prevout_hash"],
+            "vout": None if coinbase else txin["prevout_n"],
+        })
+    vout = []
+    for out in tx["vout"]:
+        vout.append(dict({"value": out["value_satoshis"]}, **spk_info(out["script_pub_key_hex"])))
+    return {"txid": tx["txid"], "vin": vin, "vout": vout, "size": len(chain.ser_tx(tx))}
+
+
+def parse_args(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--datadir", help="Bitflash data directory containing blk*.dat")
+    ap.add_argument("--max-blocks", type=int, default=0,
+                    help="number of blocks to scan; 0 means all block files")
+    ap.add_argument("paths", nargs="+",
+                    help="with --datadir: <out-dir>; otherwise: <blk*.dat>... <out-dir>")
+    args = ap.parse_args(argv)
+    if args.datadir:
+        if len(args.paths) != 1:
+            raise SystemExit("usage with --datadir: build-explorer.py --datadir DATADIR <out-dir>")
+        args.block_files = None
+        args.out_dir = args.paths[0]
+    else:
+        if len(args.paths) < 2:
+            raise SystemExit("usage: build-explorer.py <blk*.dat>... <out-dir>")
+        args.block_files = args.paths[:-1]
+        args.out_dir = args.paths[-1]
+    return args
+
+
+def load_blocks(args):
+    if args.datadir:
+        return chain.read_blocks(args.datadir, args.max_blocks)
+    return chain.read_blocks_from_files(args.block_files, args.max_blocks)
+
+
+def build_explorer(raw_blocks, out_dir):
+    try:
+        blocks = chain.select_main_chain(raw_blocks)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    out = Path(out_dir)
+    (out / "block").mkdir(parents=True, exist_ok=True)
+
+    summaries = []
+    for height, block in enumerate(blocks):
+        txs = [explorer_tx(tx) for tx in block["transactions"]]
+        detail = {
+            "height": height,
+            "hash": block["hash"],
+            "prev": block["previous_hash"],
+            "merkleRoot": block["merkle_root"],
+            "version": block["version"],
+            "time": block["time"],
+            "bits": int(block["bits"], 16),
+            "nonce": block["nonce"],
+            "size": block["size"],
+            "txs": txs,
+        }
+        cb = txs[0]["vout"][0] if txs and txs[0]["vout"] else {}
+        summaries.append({
+            "height": height,
+            "hash": block["hash"],
+            "time": block["time"],
+            "nTx": len(txs),
+            "size": block["size"],
+            "cbValue": cb.get("value", 0),
+            "cbAddr": cb.get("address", ""),
+        })
+        (out / "block" / ("%d.json" % height)).write_text(
+            json.dumps(detail, sort_keys=True, separators=(",", ":")) + "\n",
+            encoding="ascii",
+        )
+
+    summaries.sort(key=lambda x: -x["height"])
+    (out / "blocks.json").write_text(
+        json.dumps({
+            "network": "bitflash",
+            "tipHeight": len(blocks) - 1,
+            "count": len(blocks),
+            "blocks": summaries,
+        }, sort_keys=True, separators=(",", ":")) + "\n",
+        encoding="ascii",
+    )
+    (out / "index.html").write_text(INDEX_HTML, encoding="utf-8")
+    (out / "style.css").write_text(STYLE_CSS, encoding="utf-8")
+    (out / "explorer.js").write_text(EXPLORER_JS, encoding="utf-8")
+    logo = Path(__file__).resolve().parents[1] / "docs" / "logo.png"
+    if logo.exists():
+        shutil.copyfile(logo, out / "logo.png")
+    return len(blocks), len(blocks) - 1
+
+
+def main(argv):
+    args = parse_args(argv)
+    raw_blocks = load_blocks(args)
+    if not raw_blocks:
+        raise SystemExit("no Bitflash blocks parsed")
+    count, tip = build_explorer(raw_blocks, args.out_dir)
+    print("explorer built: %d main-chain blocks, tip %d, into %s" % (count, tip, args.out_dir))
+    return 0
+
+
+INDEX_HTML = r"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Bitflash Block Explorer</title>
+<meta name="description" content="Read-only Bitflash block explorer generated from local blk*.dat files.">
+<link rel="icon" href="logo.png" type="image/png">
+<link rel="stylesheet" href="style.css">
+<script src="explorer.js" defer></script>
+</head>
+<body>
+<header class="topbar">
+  <a class="brand" href="https://bitflash.network/"><img src="logo.png" width="22" height="22" alt="">Bitflash</a>
+  <nav aria-label="Bitflash sites">
+    <a href="https://bitflash.network/">home</a>
+    <a href="https://git.bitflash.network/bitflash/bitflash">code</a>
+    <a href="https://docs.bitflash.network/">docs</a>
+    <a href="https://releases.bitflash.network/">downloads</a>
+    <a href="https://explorer.bitflash.network/" aria-current="page">explorer</a>
+    <a href="https://status.bitflash.network/">status</a>
+  </nav>
+  <span class="meta" id="tip"></span>
+</header>
+<div class="wrap">
+  <h1>Block explorer <button class="link" id="home" hidden>back to blocks</button></h1>
+  <p class="note">Read-only view of the main chain: blocks, their transactions, and the coinbase payout. There is no mempool and no per-address history here.</p>
+  <div id="listview">
+    <input id="q" placeholder="Search by height or block hash">
+    <div class="scroll"><table>
+      <thead><tr><th>Height</th><th>Time (UTC)</th><th>Txs</th><th>Size</th><th>Coinbase</th><th>To</th></tr></thead>
+      <tbody id="rows"></tbody>
+    </table></div>
+    <p class="mut" id="more"></p>
+  </div>
+  <div id="detail" hidden></div>
+</div>
+</body>
+</html>
+"""
+
+
+STYLE_CSS = r""":root{
+  color-scheme: light dark;
+  --bg:#fff; --bg-2:#f6f6f6; --fg:#111; --dim:#6b6b6b; --line:#d7d7d7; --line-hard:#111;
+  --accent:#0b7a34; --accent-2:#12a047; --bar:3rem;
+  --mono: ui-monospace,"Cascadia Mono","Segoe UI Mono",Consolas,"DejaVu Sans Mono","Liberation Mono","Courier New",monospace;
+}
+@media (prefers-color-scheme: dark){:root{
+  --bg:#000; --bg-2:#0b0b0b; --fg:#dcdcdc; --dim:#8a8a8a; --line:#242424; --line-hard:#4a4a4a;
+  --accent:#2ee06a; --accent-2:#6bff9f;
+}}
+*{box-sizing:border-box;}
+html,body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 var(--mono);-webkit-text-size-adjust:100%;}
+a{color:var(--accent);}
+.topbar{display:flex;align-items:center;gap:1rem;flex-wrap:wrap;min-height:var(--bar);
+        padding:.5rem clamp(.9rem,2.5vw,3rem);border-bottom:1px solid var(--line);position:sticky;top:0;background:var(--bg);z-index:5;}
+.brand{display:flex;align-items:center;gap:.6rem;text-decoration:none;color:var(--fg);font-weight:bold;}
+.brand img{width:22px;height:22px;display:block;}
+.topbar nav{display:flex;flex-wrap:wrap;gap:.15rem 1.4rem;font-size:.86rem;}
+.topbar nav a{text-decoration:none;color:var(--dim);}
+.topbar nav a::before{content:"/";color:var(--line-hard);margin-right:.3rem;}
+.topbar nav a:hover{color:var(--fg);text-decoration:underline;}
+.topbar nav a[aria-current="page"]{color:var(--accent);font-weight:bold;}
+.topbar nav a[aria-current="page"]::before{color:var(--accent);}
+.topbar .meta{margin-left:auto;font-size:.76rem;color:var(--dim);letter-spacing:.06em;}
+.wrap{padding:1.4rem clamp(.9rem,2.5vw,3rem) 4rem;}
+h1{font-size:1rem;margin:0 0 .3rem;letter-spacing:.02em;}
+h2{font-size:.95rem;margin:1.2rem 0 .4rem;}
+.mut{color:var(--dim);}
+.note{color:var(--dim);font-size:.82rem;max-width:60rem;margin:.2rem 0 1rem;}
+input{width:100%;max-width:28rem;padding:.5rem .7rem;border:1px solid var(--line);background:var(--bg-2);color:var(--fg);font:inherit;font-size:.86rem;}
+input:focus{outline:none;border-color:var(--accent);}
+.scroll{overflow-x:auto;}
+table{width:100%;border-collapse:collapse;margin-top:.8rem;font-size:.86rem;}
+th,td{text-align:left;padding:.5rem .6rem;border-bottom:1px solid var(--line);font-variant-numeric:tabular-nums;}
+th{font-size:.72rem;text-transform:uppercase;letter-spacing:.1em;color:var(--dim);font-weight:normal;}
+tr.blk{cursor:pointer;}
+tr.blk:hover td{background:var(--bg-2);}
+code{font-size:.8rem;word-break:break-all;color:var(--fg);}
+.card{border:1px solid var(--line);background:var(--bg-2);padding:.9rem 1rem;margin-top:.8rem;}
+.kv{display:grid;grid-template-columns:11rem 1fr;gap:.25rem .8rem;font-size:.82rem;}
+.kv div:nth-child(odd){color:var(--dim);}
+.tx{border-top:1px solid var(--line);padding:.7rem 0;}
+.io{display:grid;grid-template-columns:1fr 1fr;gap:1rem;}
+@media (max-width:640px){.io{grid-template-columns:1fr;}.kv{grid-template-columns:7rem 1fr;}.topbar .meta{margin-left:0;width:100%;}}
+.pill{display:inline-block;font-size:.68rem;padding:.05rem .5rem;border:1px solid var(--line);color:var(--dim);text-transform:uppercase;letter-spacing:.05em;}
+button.link{background:none;border:none;color:var(--accent);cursor:pointer;font:inherit;padding:0;text-decoration:underline;}
+"""
+
+
+EXPLORER_JS = r"""
+var SUM = [], SHOWN = 200;
+function btf(sat){ return (sat/1e8).toFixed(8).replace(/0+$/,'').replace(/\.$/,'')+" BTF"; }
+function ts(t){ return new Date(t*1000).toISOString().replace('T',' ').replace('.000Z',' UTC'); }
+function short(h){ return h ? h.slice(0,10)+"..."+h.slice(-6) : "-"; }
+function E(tag, cls, text){
+  var e = document.createElement(tag);
+  if(cls) e.className = cls;
+  if(text !== undefined) e.textContent = text;
+  return e;
+}
+function code(text){ return E('code', '', text); }
+function clear(e){ while(e.firstChild) e.removeChild(e.firstChild); }
+function append(parent){
+  for(var i=1;i<arguments.length;i++) parent.appendChild(arguments[i]);
+  return parent;
+}
+function row(cells, cls){
+  var tr = E('tr', cls || '');
+  cells.forEach(function(c){ append(tr, E('td', '', c)); });
+  return tr;
+}
+function renderList(filter){
+  var q=(filter||"").trim().toLowerCase(), rows=document.getElementById('rows');
+  clear(rows);
+  var list = q ? SUM.filter(function(b){ return String(b.height)===q || b.hash.indexOf(q)===0; }) : SUM.slice(0,SHOWN);
+  if(!list.length){
+    var empty = E('tr');
+    var td = E('td', 'mut', 'no match');
+    td.colSpan = 6;
+    append(empty, td); append(rows, empty);
+  }
+  list.forEach(function(b){
+    var tr = row([String(b.height), ts(b.time), String(b.nTx), b.size+' B', btf(b.cbValue), ''], 'blk');
+    tr.dataset.h = b.height;
+    clear(tr.children[5]);
+    append(tr.children[5], code(b.cbAddr || '-'));
+    tr.onclick = function(){ openBlock(tr.dataset.h); };
+    append(rows, tr);
+  });
+  document.getElementById('more').textContent = (!q && SUM.length>SHOWN) ? ("showing latest "+SHOWN+" of "+SUM.length+" blocks; search to find any") : "";
+}
+function kv(parent, key, value, isCode){
+  append(parent, E('div', '', key));
+  append(parent, isCode ? append(E('div'), code(value)) : E('div', '', value));
+}
+function ioSide(title, items, render){
+  var side = E('div');
+  append(side, E('div', 'mut', title));
+  items.forEach(function(item){ append(side, render(item)); });
+  return side;
+}
+function openBlock(h){
+  fetch('block/'+h+'.json').then(function(r){return r.json();}).then(function(b){
+    var detail = document.getElementById('detail');
+    clear(detail);
+    append(detail, E('h2', '', 'Block '+b.height));
+    var card = E('div', 'card'), grid = E('div', 'kv');
+    kv(grid, 'Height', String(b.height));
+    kv(grid, 'Hash', b.hash, true);
+    var prev = E('div');
+    if(b.height > 0){
+      var btn = E('button', 'link');
+      append(btn, code(short(b.prev)));
+      btn.onclick = function(){ openBlock(b.height - 1); };
+      append(prev, btn);
+    } else {
+      append(prev, code(short(b.prev)));
+    }
+    append(grid, E('div', '', 'Previous'), prev);
+    kv(grid, 'Merkle root', b.merkleRoot, true);
+    kv(grid, 'Time (UTC)', ts(b.time));
+    kv(grid, 'Bits / Nonce', b.bits.toString(16)+' / '+b.nonce);
+    kv(grid, 'Size / Txs', b.size+' B / '+b.txs.length);
+    append(card, grid); append(detail, card);
+    b.txs.forEach(function(t, i){
+      var tx = E('div', 'tx');
+      var head = E('div');
+      append(head, code(t.txid));
+      if(i === 0) append(head, E('span', 'pill', 'coinbase'));
+      var io = E('div', 'io');
+      append(io, ioSide('Inputs', t.vin, function(v){
+        var d = E('div');
+        if(v.coinbase) append(d, E('span', 'pill', 'coinbase'));
+        else append(d, code(short(v.prev)+':'+v.vout));
+        return d;
+      }));
+      append(io, ioSide('Outputs', t.vout, function(o){
+        var d = E('div');
+        var to = o.address ? o.address : (o.pubkey ? 'pubkey '+o.pubkey.slice(0,16)+'...' : o.type);
+        append(d, document.createTextNode(btf(o.value)+' -> '), code(to));
+        return d;
+      }));
+      append(tx, head, io); append(detail, tx);
+    });
+    document.getElementById('listview').hidden = true;
+    detail.hidden = false;
+    document.getElementById('home').hidden = false;
+    window.scrollTo(0,0);
+  });
+}
+document.getElementById('home').onclick=function(){
+  document.getElementById('detail').hidden = true;
+  document.getElementById('listview').hidden = false;
+  this.hidden = true;
+};
+document.getElementById('q').oninput=function(){ renderList(this.value); };
+fetch('blocks.json').then(function(r){return r.json();}).then(function(d){
+  SUM=d.blocks; document.getElementById('tip').textContent='tip height '+d.tipHeight+' - '+d.count+' blocks';
+  renderList('');
+});
+"""
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/build-pool-index.py b/scripts/build-pool-index.py
new file mode 100644
index 0000000..d3eb386
--- /dev/null
+++ b/scripts/build-pool-index.py
@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+#
+# Build a static public pool directory from one or more Bitflash pool_status.json
+# files. Inputs may be local paths or http(s) URLs.
+
+import argparse
+import html
+import json
+import os
+import time
+import urllib.parse
+import urllib.request
+
+
+def load_json(source):
+    if source.startswith("http://") or source.startswith("https://"):
+        with urllib.request.urlopen(source, timeout=10) as r:
+            return json.loads(r.read().decode("utf-8"))
+    with open(source, "r", encoding="utf-8-sig") as f:
+        return json.load(f)
+
+
+def normalize_pool(source, obj, now):
+    operator = obj.get("operator", {})
+    pool = obj.get("pool", {})
+    node = obj.get("node", {})
+    rounds_file = operator.get("roundsFile") or "pool_rounds.json"
+    rounds_url = ""
+    if source.startswith("http://") or source.startswith("https://"):
+        rounds_url = urllib.parse.urljoin(source, rounds_file)
+    updated = int(obj.get("updatedAt") or 0)
+    age = max(0, now - updated) if updated else None
+    online = bool(node.get("poolRunning")) and age is not None and age <= 120
+    return {
+        "source": source,
+        "name": operator.get("name") or "Bitflash Pool",
+        "btfAddress": operator.get("btfAddress") or "",
+        "feePercent": float(operator.get("feePercent") or 0.0),
+        "dashboardUrl": operator.get("dashboardUrl") or "",
+        "height": int(node.get("height") or 0),
+        "online": online,
+        "ageSeconds": age,
+        "authorizedMiners": int(pool.get("authorizedMiners") or 0),
+        "blocksFoundSession": int(pool.get("blocksFoundSession") or 0),
+        "roundShares": int(pool.get("roundShares") or 0),
+        "hashRate": float(pool.get("hashRate") or 0.0),
+        "roundsUrl": rounds_url,
+        "recentRounds": obj.get("recentRounds", []),
+    }
+
+
+def rank_key(pool):
+    return (
+        1 if pool["online"] else 0,
+        pool["hashRate"],
+        pool["authorizedMiners"],
+        -pool["feePercent"],
+        pool["name"].lower(),
+    )
+
+
+def render_html(pools, generated_at):
+    rows = []
+    for p in pools:
+        dash = p["dashboardUrl"]
+        rounds = p.get("roundsUrl", "")
+        # Only linkify http(s). The dashboard URL comes from an operator's
+        # self-published status file, so a "javascript:" or "data:" scheme
+        # would become a clickable script-injection on this public page.
+        dash_lower = dash.lower()
+        if dash_lower.startswith("http://") or dash_lower.startswith("https://"):
+            dash_html = '<a href="{0}" rel="noopener noreferrer">dashboard</a>'.format(
+                html.escape(dash, quote=True))
+        else:
+            dash_html = "-"
+        rounds_lower = rounds.lower()
+        if rounds_lower.startswith("http://") or rounds_lower.startswith("https://"):
+            rounds_html = '<a href="{0}" rel="noopener noreferrer">proof</a>'.format(
+                html.escape(rounds, quote=True))
+        else:
+            rounds_html = "-"
+        rows.append(
+            "<tr>"
+            "<td>{status}</td>"
+            "<td><strong>{name}</strong><br><code>{addr}</code></td>"
+            "<td>{fee:.2f}%</td>"
+            "<td>{miners}</td>"
+            "<td>{hashrate:.2f}</td>"
+            "<td>{blocks}</td>"
+            "<td>{height}</td>"
+            "<td>{age}</td>"
+            "<td>{dash}</td>"
+            "<td>{rounds}</td>"
+            "</tr>".format(
+                status="online" if p["online"] else "stale",
+                name=html.escape(p["name"]),
+                addr=html.escape(p["btfAddress"]),
+                fee=p["feePercent"],
+                miners=p["authorizedMiners"],
+                hashrate=p["hashRate"],
+                blocks=p["blocksFoundSession"],
+                height=p["height"],
+                age="{}s".format(p["ageSeconds"]) if p["ageSeconds"] is not None else "-",
+                dash=dash_html,
+                rounds=rounds_html,
+            )
+        )
+
+    return """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Bitflash Pools</title>
+  <style>
+    body {{ font: 15px/1.45 system-ui, sans-serif; margin: 32px; color: #111; }}
+    table {{ border-collapse: collapse; width: 100%; }}
+    th, td {{ border-bottom: 1px solid #ddd; padding: 10px; text-align: left; vertical-align: top; }}
+    th {{ font-size: 12px; text-transform: uppercase; letter-spacing: .08em; }}
+    code {{ font-size: 12px; word-break: break-all; }}
+    .note {{ color: #555; max-width: 780px; }}
+  </style>
+</head>
+<body>
+  <h1>Bitflash Pools</h1>
+  <p class="note">This directory is informational. Bitflash nodes discover pools through Nostr and .btf; this page only helps humans compare public operators.</p>
+  <table>
+    <thead>
+      <tr><th>Status</th><th>Pool</th><th>Fee</th><th>Miners</th><th>H/s</th><th>Blocks</th><th>Height</th><th>Age</th><th>Link</th><th>Proof</th></tr>
+    </thead>
+    <tbody>
+      {rows}
+    </tbody>
+  </table>
+  <p class="note">Generated at {generated_at}. JSON: <a href="pools.json">pools.json</a>.</p>
+</body>
+</html>
+""".format(rows="\n      ".join(rows), generated_at=generated_at)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out-dir", default="pool-site")
+    ap.add_argument("sources", nargs="+", help="pool_status.json paths or URLs")
+    args = ap.parse_args()
+
+    now = int(time.time())
+    pools = []
+    errors = []
+    for source in args.sources:
+        try:
+            pools.append(normalize_pool(source, load_json(source), now))
+        except Exception as e:
+            errors.append({"source": source, "error": str(e)})
+
+    pools.sort(key=rank_key, reverse=True)
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    generated_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now))
+    with open(os.path.join(args.out_dir, "pools.json"), "w", encoding="utf-8") as f:
+        json.dump({
+            "schema": "bitflash-pool-directory-1",
+            "generatedAt": generated_at,
+            "pools": pools,
+            "errors": errors,
+        }, f, indent=2, sort_keys=True)
+        f.write("\n")
+
+    with open(os.path.join(args.out_dir, "index.html"), "w", encoding="utf-8") as f:
+        f.write(render_html(pools, generated_at))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/check-money-log-lines.sh b/scripts/check-money-log-lines.sh
new file mode 100755
index 0000000..c9f348b
--- /dev/null
+++ b/scripts/check-money-log-lines.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Money-moving payout lines must print every time they fire: they are the
+# audit trail for obligations created, moved and destroyed, and LogPrint's
+# burst collapse can stand one line in for any number of events inside one
+# 3-second window (issue #3: 100 voids totalling 4,950 BTF read as one
+# 49.49 BTF line). Every line carrying one of the phrases below must use
+# LogPrintAlways, which keeps the category gate but skips the collapse.
+#
+# Adding a payout line that reports money moving? Use LogPrintAlways and
+# add its phrase here. A phrase found in a plain LogPrint call fails this
+# check; anything else passes, so a non-money line is never held up by it.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+phrases='was orphaned -- voiding|orphaned while queued|\[payout\] paid %s to %s|FAILED to pay|writing off|SKIPPED bad address'
+
+# Call sites span several lines; flatten each call to a single line first so
+# the phrase and the macro it belongs to are matched together. Only a line
+# whose first token is the macro starts a call, so comments mentioning
+# LogPrint are never mistaken for one.
+bad=$(awk '
+    /^[ \t]*LogPrint(Always)?[(]/ {
+        if (collecting) print buf
+        buf = $0; collecting = 1; next
+    }
+    collecting {
+        buf = buf $0
+        if (/;[ \t]*$/) { print buf; collecting = 0 }
+    }
+    END { if (collecting) print buf }
+' src/rpc.cpp | grep -E '^[[:space:]]*LogPrint[(]' | grep -E "$phrases" || true)
+
+if [ -n "$bad" ]; then
+    echo "error: money-moving payout line(s) on collapsing LogPrint:" >&2
+    echo "$bad" >&2
+    exit 1
+fi
+echo "ok: every money-moving payout line in src/rpc.cpp uses LogPrintAlways"
diff --git a/scripts/make-release-checksums.sh b/scripts/make-release-checksums.sh
index 5b29e2d..9c4f45a 100644..100755
--- a/scripts/make-release-checksums.sh
+++ b/scripts/make-release-checksums.sh
@@ -10,6 +10,7 @@ Usage: scripts/make-release-checksums.sh [--sign] [--local-user KEYID]
 
 Creates SHA256SUMS for release assets in the current directory:
   Bitflash-*-windows.zip
+  Bitflash-*-windows-with-tor.zip
   Bitflash-*-x86_64.AppImage
   bitflash-node-*-x86_64
 
@@ -44,6 +45,7 @@ fi
 assets=()
 for pattern in \
   "Bitflash-*-windows.zip" \
+  "Bitflash-*-windows-with-tor.zip" \
   "Bitflash-*-x86_64.AppImage" \
   "bitflash-node-*-x86_64"
 do
diff --git a/scripts/package-windows-tor.sh b/scripts/package-windows-tor.sh
new file mode 100755
index 0000000..c8cca3b
--- /dev/null
+++ b/scripts/package-windows-tor.sh
@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="${VERSION:-$(sed -n 's/^VERSION[[:space:]]*:= *//p' "$ROOT/Makefile" | head -1)}"
+
+TOR_VERSION="${TOR_VERSION:-15.0.19}"
+TOR_ARCHIVE_NAME="tor-expert-bundle-windows-x86_64-${TOR_VERSION}.tar.gz"
+TOR_URL="${TOR_URL:-https://archive.torproject.org/tor-package-archive/torbrowser/${TOR_VERSION}/${TOR_ARCHIVE_NAME}}"
+TOR_SHA256="${TOR_SHA256:-6AC067402C7B4A3DC37887ED3754B3914B67FDC220C966190683E9CCF91ABF0F}"
+TOR_ASC_URL="${TOR_ASC_URL:-${TOR_URL}.asc}"
+TOR_SIGNING_KEY_FINGERPRINT="${TOR_SIGNING_KEY_FINGERPRINT:-EF6E286DDA85EA2A4BA7DE684E2C6E8793298290}"
+TOR_VERIFY_GPG="${TOR_VERIFY_GPG:-auto}"
+
+BUNDLE_DIR="${BUNDLE_DIR:-$ROOT/Bitflash-${VERSION}-windows}"
+OUT_ZIP="${OUT_ZIP:-$ROOT/Bitflash-${VERSION}-windows-with-tor.zip}"
+CACHE_DIR="${CACHE_DIR:-$ROOT/.cache}"
+ARCHIVE="${TOR_ARCHIVE:-$CACHE_DIR/$TOR_ARCHIVE_NAME}"
+ASC_FILE="${TOR_ASC:-$ARCHIVE.asc}"
+
+usage() {
+  cat <<EOF
+Usage: scripts/package-windows-tor.sh
+
+Creates Bitflash-${VERSION}-windows-with-tor.zip from an existing
+Bitflash-${VERSION}-windows/ release directory.
+
+Environment overrides:
+  VERSION       Bitflash release version, default read from Makefile
+  TOR_VERSION   Tor Expert Bundle version, default ${TOR_VERSION}
+  TOR_URL       Download URL, default official Tor archive URL
+  TOR_ASC_URL   Signature URL, default TOR_URL.asc
+  TOR_SHA256    Expected archive SHA256
+  TOR_ARCHIVE   Use an existing archive instead of downloading
+  TOR_ASC       Use an existing detached signature
+  TOR_VERIFY_GPG auto, required, or off; default auto
+  BUNDLE_DIR    Existing unpacked Windows release directory
+  OUT_ZIP       Output zip path
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "missing required command: $1" >&2
+    exit 1
+  }
+}
+
+need sha256sum
+need tar
+need zip
+
+download() {
+  local url="$1"
+  local out="$2"
+  if command -v curl >/dev/null 2>&1; then
+    curl -L --fail --output "$out" "$url"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O "$out" "$url"
+  else
+    echo "missing required command: curl or wget" >&2
+    exit 1
+  fi
+}
+
+if [ ! -d "$BUNDLE_DIR" ]; then
+  echo "missing Windows release directory: $BUNDLE_DIR" >&2
+  echo "run 'make windows' first, or set BUNDLE_DIR" >&2
+  exit 1
+fi
+if [ ! -f "$BUNDLE_DIR/Bitflash.exe" ]; then
+  echo "missing Bitflash.exe in $BUNDLE_DIR" >&2
+  exit 1
+fi
+BUNDLE_PARENT="$(cd "$(dirname "$BUNDLE_DIR")" && pwd)"
+BUNDLE_NAME="$(basename "$BUNDLE_DIR")"
+OUT_PARENT="$(mkdir -p "$(dirname "$OUT_ZIP")" && cd "$(dirname "$OUT_ZIP")" && pwd)"
+OUT_NAME="$(basename "$OUT_ZIP")"
+OUT_ZIP_ABS="$OUT_PARENT/$OUT_NAME"
+
+mkdir -p "$CACHE_DIR"
+if [ ! -f "$ARCHIVE" ]; then
+  download "$TOR_URL" "$ARCHIVE"
+fi
+
+got="$(sha256sum "$ARCHIVE" | awk '{print tolower($1)}')"
+want="$(printf '%s' "$TOR_SHA256" | tr 'A-F' 'a-f')"
+if [ "$got" != "$want" ]; then
+  echo "Tor archive SHA256 mismatch" >&2
+  echo "  expected: $want" >&2
+  echo "       got: $got" >&2
+  exit 1
+fi
+
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/bitflash-tor-package.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT
+
+case "$TOR_VERIFY_GPG" in
+  auto|required|off) ;;
+  *) echo "TOR_VERIFY_GPG must be auto, required, or off" >&2; exit 2 ;;
+esac
+
+if [ "$TOR_VERIFY_GPG" != "off" ]; then
+  if command -v gpg >/dev/null 2>&1; then
+    if [ ! -f "$ASC_FILE" ]; then
+      download "$TOR_ASC_URL" "$ASC_FILE"
+    fi
+    gnupg_home="$tmp/gnupg"
+    mkdir -p "$gnupg_home"
+    chmod 0700 "$gnupg_home"
+    gpg --homedir "$gnupg_home" --batch --auto-key-locate nodefault,wkd,keyserver \
+      --locate-keys torbrowser@torproject.org >/dev/null 2>&1 || {
+        if [ "$TOR_VERIFY_GPG" = "required" ]; then
+          echo "could not import Tor Browser Developers signing key" >&2
+          exit 1
+        fi
+        echo "WARNING: skipped Tor GPG signature verification; signing key import failed" >&2
+      }
+    if gpg --homedir "$gnupg_home" --batch --with-colons --fingerprint "$TOR_SIGNING_KEY_FINGERPRINT" \
+        2>/dev/null | grep -q "^fpr:::::::::${TOR_SIGNING_KEY_FINGERPRINT}:"; then
+      gpg --homedir "$gnupg_home" --batch --verify "$ASC_FILE" "$ARCHIVE" >/dev/null 2>&1 || {
+        echo "Tor archive GPG signature verification failed" >&2
+        exit 1
+      }
+      echo "Tor archive GPG signature verified against ${TOR_SIGNING_KEY_FINGERPRINT}"
+    elif [ "$TOR_VERIFY_GPG" = "required" ]; then
+      echo "Tor signing key fingerprint mismatch" >&2
+      exit 1
+    else
+      echo "WARNING: skipped Tor GPG signature verification; signing key fingerprint was not available" >&2
+    fi
+  elif [ "$TOR_VERIFY_GPG" = "required" ]; then
+    echo "missing required command for TOR_VERIFY_GPG=required: gpg" >&2
+    exit 1
+  else
+    echo "WARNING: gpg not found; relying on pinned SHA256 only" >&2
+  fi
+fi
+
+mkdir -p "$tmp/extract"
+tar -xzf "$ARCHIVE" -C "$tmp/extract"
+
+if [ ! -f "$tmp/extract/tor/tor.exe" ]; then
+  echo "Tor archive did not contain tor/tor.exe" >&2
+  exit 1
+fi
+
+rm -rf "$BUNDLE_DIR/tor"
+mkdir -p "$BUNDLE_DIR/tor"
+cp -R "$tmp/extract/tor/." "$BUNDLE_DIR/tor/"
+if [ -d "$tmp/extract/docs" ]; then
+  mkdir -p "$BUNDLE_DIR/tor/docs"
+  cp -R "$tmp/extract/docs/." "$BUNDLE_DIR/tor/docs/"
+fi
+if [ -d "$tmp/extract/data" ]; then
+  mkdir -p "$BUNDLE_DIR/tor/data-defaults"
+  cp -R "$tmp/extract/data/." "$BUNDLE_DIR/tor/data-defaults/"
+fi
+
+cat > "$BUNDLE_DIR/TOR-EXPERT-BUNDLE.txt" <<EOF
+Bitflash managed Tor bundle
+
+This Windows package includes the Tor Expert Bundle so -managedtor can start
+Tor without requiring a separate Tor install.
+
+Tor Expert Bundle: ${TOR_VERSION}
+Archive URL: ${TOR_URL}
+Archive SHA256: ${TOR_SHA256}
+
+Bitflash uses tor/tor.exe from this package. Runtime state, hidden-service keys,
+and control authentication cookies are written under the user's Bitflash data
+directory, not inside this release directory.
+EOF
+
+rm -f "$OUT_ZIP_ABS"
+(
+  cd "$BUNDLE_PARENT"
+  zip -qr "$OUT_ZIP_ABS" "$BUNDLE_NAME"
+)
+
+echo "Bundled Tor Expert Bundle ${TOR_VERSION}"
+echo "Built: $OUT_ZIP_ABS"
diff --git a/scripts/prove-utxo.py b/scripts/prove-utxo.py
new file mode 100644
index 0000000..105e677
--- /dev/null
+++ b/scripts/prove-utxo.py
@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Create a Bitflash UTXO inclusion proof from local blk*.dat files.
+
+The proof is deliberately outside consensus. It proves that one txid:vout is
+included in the deterministic UTXO root produced by verify-utxo-set.py.
+"""
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+SCHEMA = "bitflash-utxo-inclusion-proof-1"
+
+
+def canonical_bytes(obj):
+    return (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+
+
+def split_outpoint(outpoint):
+    parts = outpoint.split(":")
+    if len(parts) != 2 or len(parts[0]) != 64:
+        raise SystemExit("outpoint must be txid:vout")
+    try:
+        vout = int(parts[1], 10)
+    except ValueError:
+        raise SystemExit("vout must be a decimal integer")
+    if vout < 0:
+        raise SystemExit("vout must not be negative")
+    return parts[0].lower(), vout
+
+
+def build_merkle_proof(keys, leaf_hashes, index):
+    current_index = index
+    layer = list(leaf_hashes)
+    proof = []
+    level = 0
+    while len(layer) > 1:
+        if current_index % 2 == 0:
+            sibling_index = current_index + 1
+            duplicated = sibling_index >= len(layer)
+            sibling = layer[current_index] if duplicated else layer[sibling_index]
+            side = "right"
+        else:
+            sibling_index = current_index - 1
+            duplicated = False
+            sibling = layer[sibling_index]
+            side = "left"
+        proof.append({
+            "level": level,
+            "side": side,
+            "hash": sibling.hex(),
+            "duplicated": duplicated,
+        })
+
+        next_layer = []
+        for i in range(0, len(layer), 2):
+            left = layer[i]
+            right = layer[i + 1] if i + 1 < len(layer) else left
+            next_layer.append(hashlib.sha256(chain.UTXO_NODE_DOMAIN + left + right).digest())
+        layer = next_layer
+        current_index //= 2
+        level += 1
+    return proof, layer[0].hex()
+
+
+def build_proof(args):
+    txid, vout = split_outpoint(args.outpoint)
+    outpoint = "%s:%d" % (txid, vout)
+
+    raw_blocks = chain.read_blocks(args.datadir, args.max_blocks)
+    if not raw_blocks:
+        raise SystemExit("no Bitflash blocks found in %s" % args.datadir)
+    try:
+        blocks = chain.select_main_chain(raw_blocks)
+        state = chain.apply_blocks(blocks, strict_duplicates=args.strict_duplicates)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    utxos = state["utxos"]
+    stats = state["stats"]
+    if outpoint not in utxos:
+        raise SystemExit("outpoint is not unspent in the scanned chain: %s" % outpoint)
+
+    keys = sorted(utxos)
+    leaf_hashes = [chain.utxo_leaf_hash(k, utxos[k]) for k in keys]
+    index = keys.index(outpoint)
+    proof_path, root = build_merkle_proof(keys, leaf_hashes, index)
+    direct_root = chain.utxo_root(utxos)
+    if root != direct_root:
+        raise SystemExit("internal proof root mismatch")
+
+    tip = blocks[-1]
+    utxo = utxos[outpoint]
+    report = {
+        "schema": SCHEMA,
+        "deterministic": True,
+        "chain": {
+            "name": "Bitflash",
+            "ticker": "BTF",
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
+        },
+        "commitment": {
+            "algorithm": "sorted-outpoint-merkle-sha256",
+            "leaf_domain": chain.UTXO_LEAF_DOMAIN,
+            "node_domain": chain.UTXO_NODE_DOMAIN_TAG,
+            "root": root,
+            "leaf_count": len(keys),
+        },
+        "target": {
+            "outpoint": outpoint,
+            "txid": txid,
+            "vout": vout,
+            "leaf_index": index,
+            "leaf_hash": leaf_hashes[index].hex(),
+            "utxo": utxo,
+        },
+        "proof": proof_path,
+        "scanned": {
+            "raw_block_count": len(raw_blocks),
+            "side_blocks_ignored": len(raw_blocks) - len(blocks),
+            "main_chain_block_count": len(blocks),
+            "first_height": 0,
+            "last_height": len(blocks) - 1,
+            "tip_hash": tip["hash"],
+            "tip_time": tip["time"],
+            "tip_time_utc": tip["time_utc"],
+        },
+        "warnings": {
+            "legacy_duplicate_output_overwrites": len(stats["duplicate_outputs"]),
+        },
+        "verdict": "UTXO_INCLUSION_PROOF_CREATED",
+    }
+    return report
+
+
+def print_text(proof):
+    data_hash = hashlib.sha256(canonical_bytes(proof)).hexdigest()
+    target = proof["target"]
+    utxo = target["utxo"]
+    print("Bitflash UTXO inclusion proof")
+    print("schema: %s" % proof["schema"])
+    print("canonical proof sha256: %s" % data_hash)
+    print()
+    print("Target")
+    print("  outpoint: %s" % target["outpoint"])
+    print("  value:    %s BTF" % utxo["value_btf"])
+    print("  height:   %d" % utxo["created_height"])
+    print("  index:    %d of %d" % (target["leaf_index"], proof["commitment"]["leaf_count"]))
+    print()
+    print("Commitment")
+    print("  root:     %s" % proof["commitment"]["root"])
+    print("  path:     %d sibling hashes" % len(proof["proof"]))
+    print("  tip:      %s" % proof["scanned"]["tip_hash"])
+    print()
+    print("Verdict: %s" % proof["verdict"])
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("outpoint", help="unspent output to prove, as txid:vout")
+    ap.add_argument("--datadir", default=chain.default_datadir(), help="Bitflash data directory")
+    ap.add_argument("--max-blocks", type=int, default=0,
+                    help="number of blocks to scan; 0 means all block files")
+    ap.add_argument("--strict-duplicates", action="store_true",
+                    help="fail instead of using legacy last-write-wins duplicate output handling")
+    ap.add_argument("--json", action="store_true", help="print canonical JSON")
+    ap.add_argument("--out", help="write canonical JSON proof to this path")
+    args = ap.parse_args(argv)
+
+    proof = build_proof(args)
+    data = canonical_bytes(proof)
+    if args.out:
+        Path(args.out).write_bytes(data)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(proof)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/smoke-managed-tor-onion.ps1 b/scripts/smoke-managed-tor-onion.ps1
new file mode 100644
index 0000000..70658c7
--- /dev/null
+++ b/scripts/smoke-managed-tor-onion.ps1
@@ -0,0 +1,174 @@
+param(
+    [string]$Bitflash,
+    [string]$Tor,
+    [string]$WorkDir,
+    [int]$TimeoutSec = 600,
+    [int]$OnionWarmupSec = 120
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-RepoRoot {
+    $scriptDir = Split-Path -Parent $PSCommandPath
+    return (Resolve-Path (Join-Path $scriptDir "..")).Path
+}
+
+function Get-FreeTcpPort {
+    $listener = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0)
+    $listener.Start()
+    try {
+        return ([Net.IPEndPoint]$listener.LocalEndpoint).Port
+    }
+    finally {
+        $listener.Stop()
+    }
+}
+
+function Wait-RegexInFile {
+    param(
+        [string]$Path,
+        [string]$Pattern,
+        [datetime]$Deadline,
+        [string]$Label
+    )
+
+    while ((Get-Date) -lt $Deadline) {
+        if (Test-Path $Path) {
+            $text = Get-Content -Raw -ErrorAction SilentlyContinue $Path
+            if ($null -ne $text) {
+                $m = [regex]::Match($text, $Pattern)
+                if ($m.Success) {
+                    return $m
+                }
+            }
+        }
+        Start-Sleep -Milliseconds 500
+    }
+    throw "timed out waiting for $Label"
+}
+
+function Stop-TestProcesses {
+    param(
+        [System.Diagnostics.Process[]]$Processes,
+        [string[]]$DataDirKeys
+    )
+
+    foreach ($p in $Processes) {
+        try {
+            $p.Refresh()
+            if (!$p.HasExited) {
+                Stop-Process -Id $p.Id -Force
+            }
+        }
+        catch {}
+    }
+
+    foreach ($key in $DataDirKeys) {
+        if ([string]::IsNullOrWhiteSpace($key)) {
+            continue
+        }
+        try {
+            Get-CimInstance Win32_Process -Filter "name = 'tor.exe'" |
+                Where-Object { $_.CommandLine -like "*$key*" } |
+                ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
+        }
+        catch {}
+    }
+}
+
+$repo = Resolve-RepoRoot
+if ([string]::IsNullOrWhiteSpace($Bitflash)) {
+    $Bitflash = Join-Path $repo "src\bitflash.exe"
+}
+if ([string]::IsNullOrWhiteSpace($Tor)) {
+    $candidates = @(
+        (Join-Path $repo "src\tor\tor.exe"),
+        (Join-Path $repo "Bitflash-$(Select-String -Path (Join-Path $repo 'Makefile') -Pattern '^VERSION[ ]*:=' | ForEach-Object { ($_.Line -split ':=')[1].Trim() })-windows\tor\tor.exe")
+    )
+    foreach ($candidate in $candidates) {
+        if (Test-Path $candidate) {
+            $Tor = $candidate
+            break
+        }
+    }
+}
+if ([string]::IsNullOrWhiteSpace($WorkDir)) {
+    $WorkDir = Join-Path $env:TEMP ("bitflash-managed-tor-two-node-" + (Get-Date -Format "yyyyMMddHHmmss"))
+}
+
+if (!(Test-Path $Bitflash)) {
+    throw "Bitflash binary not found: $Bitflash"
+}
+if (!(Test-Path $Tor)) {
+    throw "Tor binary not found. Pass -Tor or build the Windows-with-Tor package."
+}
+
+New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null
+$dataA = Join-Path $WorkDir "node-a"
+$dataB = Join-Path $WorkDir "node-b"
+New-Item -ItemType Directory -Force -Path $dataA | Out-Null
+New-Item -ItemType Directory -Force -Path $dataB | Out-Null
+
+$portA = Get-FreeTcpPort
+$portB = Get-FreeTcpPort
+$deadline = (Get-Date).AddSeconds($TimeoutSec)
+$oldPath = $env:PATH
+$env:PATH = "C:\msys64\ucrt64\bin;C:\msys64\usr\bin;" + $env:PATH
+
+$procA = $null
+$procB = $null
+$dataKeys = @((Split-Path $WorkDir -Leaf))
+
+try {
+    $argsA = @(
+        "-datadir=$dataA",
+        "-port=$portA",
+        "-managedtor=$Tor",
+        "-nogui",
+        "-debug",
+        "-checkblocks=0"
+    )
+    $procA = Start-Process -FilePath $Bitflash -ArgumentList $argsA -WorkingDirectory (Split-Path $Bitflash -Parent) -PassThru -WindowStyle Hidden
+    $logA = Join-Path $dataA "debug.log"
+
+    $btfMatch = Wait-RegexInFile -Path $logA -Pattern "Nostr: node \.btf address = ([a-z2-7]+\.btf)" -Deadline $deadline -Label "node A .btf address"
+    $btfA = $btfMatch.Groups[1].Value
+
+    $onionMatch = Wait-RegexInFile -Path $logA -Pattern "Managed Tor hidden service ready: ([a-z2-7]{56}\.onion:\d+)" -Deadline $deadline -Label "node A managed onion"
+    $onionA = $onionMatch.Groups[1].Value
+
+    Wait-RegexInFile -Path $logA -Pattern "Nostr: \.btf self-resolve OK via .*" -Deadline $deadline -Label "node A descriptor self-resolve" | Out-Null
+    if ($OnionWarmupSec -gt 0) {
+        Write-Host "Waiting $OnionWarmupSec second(s) for Tor hidden-service descriptor propagation"
+        Start-Sleep -Seconds $OnionWarmupSec
+    }
+
+    $argsB = @(
+        "-datadir=$dataB",
+        "-port=$portB",
+        "-managedtor=$Tor",
+        "-oniononly",
+        "-connectbtf=$btfA",
+        "-nogui",
+        "-debug",
+        "-checkblocks=0"
+    )
+    $procB = Start-Process -FilePath $Bitflash -ArgumentList $argsB -WorkingDirectory (Split-Path $Bitflash -Parent) -PassThru -WindowStyle Hidden
+    $logB = Join-Path $dataB "debug.log"
+
+    Wait-RegexInFile -Path $logB -Pattern ("connected " + [regex]::Escape($btfA) + " via direct onion ") -Deadline $deadline -Label "node B direct onion connection to node A" | Out-Null
+
+    Write-Host "Managed Tor two-node onion smoke test passed"
+    Write-Host "  node A .btf:   $btfA"
+    Write-Host "  node A onion:  $onionA"
+    Write-Host "  node A port:   $portA"
+    Write-Host "  node B port:   $portB"
+    Write-Host "  work dir:      $WorkDir"
+}
+finally {
+    $env:PATH = $oldPath
+    $procs = @()
+    if ($null -ne $procA) { $procs += $procA }
+    if ($null -ne $procB) { $procs += $procB }
+    Stop-TestProcesses -Processes $procs -DataDirKeys $dataKeys
+}
diff --git a/scripts/verify-fair-launch.py b/scripts/verify-fair-launch.py
new file mode 100644
index 0000000..c33c8be
--- /dev/null
+++ b/scripts/verify-fair-launch.py
@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Produce a deterministic Bitflash fair-launch audit report."""
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+
+def build_report(blocks, source_mode):
+    genesis = blocks[0]
+    launch_outputs = genesis["transactions"][0]["vout"] if genesis["transactions"] else []
+    coinbase_outputs = []
+    total_mined = 0
+    non_coinbase_txs = 0
+
+    for height, block in enumerate(blocks):
+        if not block["transactions"]:
+            continue
+        cb = block["transactions"][0]
+        if chain.is_coinbase(cb):
+            amount = sum(out["value_satoshis"] for out in cb["vout"])
+            total_mined += amount
+            coinbase_outputs.append({
+                "height": height,
+                "block_hash": block["hash"],
+                "coinbase_txid": cb["txid"],
+                "value_satoshis": amount,
+                "value_btf": chain.format_money(amount),
+                "outputs": cb["vout"],
+            })
+        non_coinbase_txs += sum(1 for tx in block["transactions"] if not chain.is_coinbase(tx))
+
+    checks = {
+        "genesis_hash_matches_source": genesis["hash"] == chain.GENESIS_HASH,
+        "genesis_merkle_matches_source": genesis["merkle_root"] == chain.GENESIS_MERKLE,
+        "computed_merkle_matches_header": genesis["computed_merkle_root"] == genesis["merkle_root"],
+        "genesis_has_single_transaction": genesis["tx_count"] == 1,
+        "genesis_transaction_is_coinbase": bool(genesis["transactions"] and chain.is_coinbase(genesis["transactions"][0])),
+        "genesis_supply_is_50_btf": sum(out["value_satoshis"] for out in launch_outputs) == 50 * chain.COIN,
+    }
+
+    report = {
+        "schema": "bitflash-fair-launch-report-1",
+        "deterministic": True,
+        "source_mode": source_mode,
+        "chain": {
+            "name": "Bitflash",
+            "ticker": "BTF",
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
+        },
+        "source_constants": {
+            "genesis_hash": chain.GENESIS_HASH,
+            "genesis_merkle_root": chain.GENESIS_MERKLE,
+            "genesis_time": chain.GENESIS_TIME,
+            "genesis_time_utc": chain.utc(chain.GENESIS_TIME),
+            "genesis_bits": "0x%08x" % chain.GENESIS_BITS,
+            "genesis_nonce": chain.GENESIS_NONCE,
+            "genesis_message": chain.GENESIS_TEXT,
+        },
+        "scanned": {
+            "block_count": len(blocks),
+            "first_height": 0,
+            "last_height": len(blocks) - 1,
+            "non_coinbase_transactions": non_coinbase_txs,
+            "total_coinbase_satoshis": total_mined,
+            "total_coinbase_btf": chain.format_money(total_mined),
+        },
+        "genesis": {
+            "hash": genesis["hash"],
+            "merkle_root": genesis["merkle_root"],
+            "computed_merkle_root": genesis["computed_merkle_root"],
+            "time": genesis["time"],
+            "time_utc": genesis["time_utc"],
+            "bits": genesis["bits"],
+            "nonce": genesis["nonce"],
+            "tx_count": genesis["tx_count"],
+            "coinbase_txid": genesis["transactions"][0]["txid"] if genesis["transactions"] else "",
+            "outputs": launch_outputs,
+        },
+        "coinbase_outputs": coinbase_outputs,
+        "checks": checks,
+        "verdict": "FAIR_LAUNCH_BASELINE_VERIFIED" if all(checks.values()) else "CHECKS_FAILED",
+        "external_timestamping": {
+            "status": "not_embedded",
+            "recommended": "OpenTimestamps",
+            "instructions": [
+                "Save the canonical JSON report.",
+                "Run: ots stamp bitflash-fair-launch-report.json",
+                "Later verify with: ots verify bitflash-fair-launch-report.json.ots",
+            ],
+        },
+    }
+    report["attestation_payload_sha256"] = hashlib.sha256(chain.canonical_bytes(report)).hexdigest()
+    return report
+
+
+def print_text(report):
+    checks = report["checks"]
+    print("Bitflash fair-launch verifier")
+    print("schema: %s" % report["schema"])
+    print("source: %s" % report["source_mode"])
+    print("attestation payload sha256: %s" % report["attestation_payload_sha256"])
+    print()
+    print("Genesis")
+    print("  hash:    %s" % report["genesis"]["hash"])
+    print("  merkle:  %s" % report["genesis"]["merkle_root"])
+    print("  time:    %s" % report["genesis"]["time_utc"])
+    print("  txs:     %d" % report["genesis"]["tx_count"])
+    print("  supply:  %s BTF" % chain.format_money(sum(o["value_satoshis"] for o in report["genesis"]["outputs"])))
+    print()
+    print("Scanned")
+    print("  blocks:  %d" % report["scanned"]["block_count"])
+    print("  height:  %d..%d" % (report["scanned"]["first_height"], report["scanned"]["last_height"]))
+    print("  minted:  %s BTF" % report["scanned"]["total_coinbase_btf"])
+    print("  normal transactions in range: %d" % report["scanned"]["non_coinbase_transactions"])
+    print()
+    print("Checks")
+    for key in sorted(checks):
+        print("  %s %s" % ("OK  " if checks[key] else "FAIL", key))
+    print()
+    print("Verdict: %s" % report["verdict"])
+    print()
+    print("OpenTimestamps")
+    print("  canonical JSON can be stamped later with: ots stamp <report.json>")
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--datadir", default=chain.default_datadir(), help="Bitflash data directory")
+    ap.add_argument("--max-blocks", type=int, default=100, help="number of blocks to scan from blk*.dat")
+    ap.add_argument("--json", action="store_true", help="print canonical JSON")
+    ap.add_argument("--out", help="write canonical JSON to this path")
+    ap.add_argument("--reconstruct-genesis", action="store_true",
+                    help="do not read disk; reconstruct only the genesis block from source constants")
+    args = ap.parse_args(argv)
+
+    if args.reconstruct_genesis:
+        blocks = [chain.reconstructed_genesis()]
+        source_mode = "reconstructed-genesis"
+    else:
+        blocks = chain.read_blocks(args.datadir, args.max_blocks)
+        if not blocks:
+            raise SystemExit("no Bitflash blocks found in %s; use --reconstruct-genesis for a source-only check" % args.datadir)
+        source_mode = "local-block-files"
+
+    try:
+        report = build_report(blocks, source_mode)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    data = chain.canonical_bytes(report)
+
+    if args.out:
+        Path(args.out).write_bytes(data)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(report)
+    return 0 if report["verdict"] == "FAIR_LAUNCH_BASELINE_VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/verify-release.sh b/scripts/verify-release.sh
index c651e78..4fd4558 100644..100755
--- a/scripts/verify-release.sh
+++ b/scripts/verify-release.sh
@@ -1,23 +1,50 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-repo="bitflash-coin/bitflash"
-tag="${1:-latest}"
+# Verifies a Bitflash release: the checksum file's signature against a pinned
+# key, then the assets against the checksums.
+#
+# The signing key is embedded below, not fetched. That is the whole point of a
+# pinned key: the trust anchor ships with this script (in git), so it does not
+# depend on the same server that serves the release. A server that is
+# compromised can swap the binaries and the checksums, but it cannot forge a
+# signature by this key.
+
+host="https://releases.bitflash.network"
 require_signature=0
 
+# The Bitflash release signing key. Verification requires this exact key --
+# gpg's own "good signature" is not enough, because a good signature by *some*
+# key proves nothing. See issue #138.
+RELEASE_KEY_FP="910A2B4CCA879E81FB4B2AEA1D4A53D3B78AA4B8"
+read -r -d '' RELEASE_KEY <<'KEY' || true
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mDMEanSOmRYJKwYBBAHaRw8BAQdAXj24i2BYUcAmOpoXwjE4ZTynHsifCZ+niwQK
+HqO0nMa0UEJpdGZsYXNoIFJlbGVhc2VzIChiaXRmbGFzaC5uZXR3b3JrIHJlbGVh
+c2Ugc2lnbmluZykgPHJlbGVhc2VzQGJpdGZsYXNoLm5ldHdvcms+iJAEExYKADgW
+IQSRCitMyoeegftLKuodSlPTt4qkuAUCanSOmQIbAwULCQgHAgYVCgkICwIEFgID
+AQIeAQIXgAAKCRAdSlPTt4qkuIi9AP96X3OcstiCTTgKOr16Vhds3LyuZ19q3Apq
+4KAcNuOUMAD+NqgJ1CqkLGPXfZLCtYBCRHXNYWxMMEk+ViLcRtdLMg4=
+=mxic
+-----END PGP PUBLIC KEY BLOCK-----
+KEY
+
 usage() {
   cat <<'EOF'
 Usage: scripts/verify-release.sh [tag|latest] [--require-signature]
 
 Downloads the release checksum file and every asset named in it, then verifies:
-  1. SHA256SUMS.asc, if present, against SHA256SUMS with gpg.
+  1. SHA256SUMS.asc against SHA256SUMS, requiring the pinned Bitflash release
+     key (fingerprint 910A 2B4C CA87 9E81 FB4B 2AEA 1D4A 53D3 B78A A4B8).
   2. SHA256SUMS against the downloaded assets.
 
-Use --require-signature for release audits. Without it, older releases that
-ship only SHA256SUMS are checked for integrity and reported as unsigned.
+Releases from before signing was introduced ship only SHA256SUMS; without
+--require-signature those are checked for integrity and reported as unsigned.
 EOF
 }
 
+tag="${1:-latest}"
 for arg in "${@:2}"; do
   case "$arg" in
     --require-signature) require_signature=1 ;;
@@ -25,19 +52,9 @@ for arg in "${@:2}"; do
     *) echo "unknown option: $arg" >&2; usage >&2; exit 2 ;;
   esac
 done
+if [ "$tag" = "-h" ] || [ "$tag" = "--help" ]; then usage; exit 0; fi
 
-if [ "$tag" = "-h" ] || [ "$tag" = "--help" ]; then
-  usage
-  exit 0
-fi
-
-need() {
-  if ! command -v "$1" >/dev/null 2>&1; then
-    echo "missing required command: $1" >&2
-    exit 1
-  fi
-}
-
+need() { command -v "$1" >/dev/null 2>&1 || { echo "missing required command: $1" >&2; exit 1; }; }
 need sed
 need awk
 
@@ -46,39 +63,25 @@ if command -v sha256sum >/dev/null 2>&1; then
 elif command -v shasum >/dev/null 2>&1; then
   sha_check=(shasum -a 256 -c SHA256SUMS)
 else
-  echo "missing required command: sha256sum or shasum" >&2
-  exit 1
+  echo "missing required command: sha256sum or shasum" >&2; exit 1
 fi
 
 download() {
-  local url="$1"
-  local out="$2"
-  if command -v curl >/dev/null 2>&1; then
-    curl -fsSL "$url" -o "$out"
-  elif command -v wget >/dev/null 2>&1; then
-    wget -q "$url" -O "$out"
-  else
-    echo "missing required command: curl or wget" >&2
-    exit 1
-  fi
+  if command -v curl >/dev/null 2>&1; then curl -fsSL "$1" -o "$2"
+  elif command -v wget >/dev/null 2>&1; then wget -q "$1" -O "$2"
+  else echo "missing required command: curl or wget" >&2; exit 1; fi
 }
 
 if [ "$tag" = "latest" ]; then
-  tag="$(download "https://api.github.com/repos/$repo/releases/latest" - |
-    sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' |
-    head -1)"
-  if [ -z "$tag" ]; then
-    echo "could not resolve latest release tag" >&2
-    exit 1
-  fi
+  tag="$(download "$host/latest.txt" - 2>/dev/null | tr -d '[:space:]' || true)"
+  [ -n "$tag" ] || { echo "could not resolve the latest release tag from $host/latest.txt" >&2; exit 1; }
 fi
 
 workdir="$(mktemp -d "${TMPDIR:-/tmp}/bitflash-release-verify.XXXXXX")"
 cleanup() { rm -rf "$workdir"; }
 trap cleanup EXIT
 
-base_url="https://github.com/$repo/releases/download/$tag"
-
+base_url="$host/$tag"
 echo "Verifying Bitflash $tag"
 echo "Working directory: $workdir"
 cd "$workdir"
@@ -86,27 +89,32 @@ cd "$workdir"
 download "$base_url/SHA256SUMS" SHA256SUMS
 
 if download "$base_url/SHA256SUMS.asc" SHA256SUMS.asc 2>/dev/null; then
-  if ! command -v gpg >/dev/null 2>&1; then
-    echo "SHA256SUMS.asc exists, but gpg is not installed" >&2
+  need gpg
+  # Verify in a throwaway keyring holding ONLY the pinned key, and require that
+  # the signature validates against it with the pinned fingerprint. This is the
+  # difference between "signed" and "signed by Bitflash".
+  keyring="$workdir/keyring"
+  mkdir -p "$keyring"; chmod 700 "$keyring"
+  printf '%s\n' "$RELEASE_KEY" | GNUPGHOME="$keyring" gpg --batch --quiet --import 2>/dev/null
+  status="$(GNUPGHOME="$keyring" gpg --batch --status-fd=1 --verify SHA256SUMS.asc SHA256SUMS 2>/dev/null || true)"
+  if printf '%s' "$status" | grep -q "VALIDSIG.*$RELEASE_KEY_FP"; then
+    echo "Signature OK -- signed by the pinned Bitflash release key"
+  else
+    echo "SIGNATURE REJECTED: not a valid signature by the pinned release key" >&2
+    echo "  expected key: $RELEASE_KEY_FP" >&2
     exit 1
   fi
-  gpg --verify SHA256SUMS.asc SHA256SUMS
-  echo "Signature OK"
 else
   if [ "$require_signature" -eq 1 ]; then
-    echo "release does not publish SHA256SUMS.asc" >&2
-    exit 1
+    echo "release does not publish SHA256SUMS.asc" >&2; exit 1
   fi
-  echo "WARNING: no SHA256SUMS.asc found; checking hashes only"
+  echo "WARNING: no SHA256SUMS.asc found; checking hashes only (unsigned release)"
 fi
 
 awk '{print $2}' SHA256SUMS | while IFS= read -r file; do
-  file="${file#\*}"
-  file="${file#./}"
+  file="${file#\*}"; file="${file#./}"
   [ -z "$file" ] && continue
-  case "$file" in
-    */*|..*) echo "refusing unexpected checksum path: $file" >&2; exit 1 ;;
-  esac
+  case "$file" in */*|..*) echo "refusing unexpected checksum path: $file" >&2; exit 1 ;; esac
   echo "Downloading $file"
   download "$base_url/$file" "$file"
 done
diff --git a/scripts/verify-utxo-proof.py b/scripts/verify-utxo-proof.py
new file mode 100644
index 0000000..50d9356
--- /dev/null
+++ b/scripts/verify-utxo-proof.py
@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Verify a Bitflash UTXO inclusion proof against a UTXO root."""
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+SCHEMA = "bitflash-utxo-inclusion-proof-1"
+
+
+def canonical_bytes(obj):
+    return (json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("ascii")
+
+
+def load_proof(path):
+    try:
+        return json.loads(Path(path).read_text(encoding="ascii"))
+    except Exception as e:
+        raise SystemExit("could not read proof: %s" % e)
+
+
+def verify(proof, expected_root=None):
+    failures = []
+    if proof.get("schema") != SCHEMA:
+        failures.append("unexpected schema")
+    commitment = proof.get("commitment", {})
+    if commitment.get("algorithm") != "sorted-outpoint-merkle-sha256":
+        failures.append("unexpected commitment algorithm")
+    if commitment.get("leaf_domain") != chain.UTXO_LEAF_DOMAIN:
+        failures.append("unexpected leaf domain")
+    if commitment.get("node_domain") != chain.UTXO_NODE_DOMAIN_TAG:
+        failures.append("unexpected node domain")
+
+    target = proof.get("target", {})
+    outpoint = target.get("outpoint", "")
+    utxo = target.get("utxo", {})
+    if outpoint != "%s:%s" % (target.get("txid"), target.get("vout")):
+        failures.append("target outpoint does not match txid:vout")
+
+    try:
+        current = chain.utxo_leaf_hash(outpoint, utxo)
+        leaf_ok = target.get("leaf_hash") == current.hex()
+    except Exception as e:
+        failures.append("could not hash target leaf: %s" % e)
+        current = b"\x00" * 32
+        leaf_ok = False
+
+    if not leaf_ok:
+        failures.append("target leaf hash mismatch")
+
+    for i, step in enumerate(proof.get("proof", [])):
+        try:
+            sibling = bytes.fromhex(step["hash"])
+        except Exception:
+            failures.append("bad sibling hash at proof level %d" % i)
+            sibling = b"\x00" * 32
+        if len(sibling) != 32:
+            failures.append("bad sibling hash length at proof level %d" % i)
+        side = step.get("side")
+        if side == "right":
+            current = chain.sha256(chain.UTXO_NODE_DOMAIN + current + sibling)
+        elif side == "left":
+            current = chain.sha256(chain.UTXO_NODE_DOMAIN + sibling + current)
+        else:
+            failures.append("bad sibling side at proof level %d" % i)
+
+    computed_root = current.hex()
+    root = expected_root or commitment.get("root")
+    if computed_root != root:
+        failures.append("computed root does not match expected root")
+
+    return {
+        "schema": "bitflash-utxo-proof-verification-1",
+        "deterministic": True,
+        "target": {
+            "outpoint": outpoint,
+            "value_satoshis": utxo.get("value_satoshis"),
+            "value_btf": utxo.get("value_btf"),
+            "created_height": utxo.get("created_height"),
+        },
+        "commitment": {
+            "expected_root": root,
+            "computed_root": computed_root,
+            "leaf_hash": target.get("leaf_hash"),
+            "path_length": len(proof.get("proof", [])),
+        },
+        "checks": {
+            "schema_is_supported": proof.get("schema") == SCHEMA,
+            "leaf_hash_matches_target": leaf_ok,
+            "root_matches": computed_root == root,
+        },
+        "failures": failures,
+        "verdict": "UTXO_PROOF_VERIFIED" if not failures else "UTXO_PROOF_FAILED",
+    }
+
+
+def print_text(result):
+    data_hash = hashlib.sha256(canonical_bytes(result)).hexdigest()
+    print("Bitflash UTXO proof verifier")
+    print("schema: %s" % result["schema"])
+    print("canonical verification sha256: %s" % data_hash)
+    print()
+    print("Target")
+    print("  outpoint: %s" % result["target"]["outpoint"])
+    print("  value:    %s BTF" % result["target"]["value_btf"])
+    print("  height:   %s" % result["target"]["created_height"])
+    print()
+    print("Commitment")
+    print("  expected: %s" % result["commitment"]["expected_root"])
+    print("  computed: %s" % result["commitment"]["computed_root"])
+    print("  path:     %d sibling hashes" % result["commitment"]["path_length"])
+    print()
+    print("Checks")
+    for key in sorted(result["checks"]):
+        print("  %s %s" % ("OK  " if result["checks"][key] else "FAIL", key))
+    if result["failures"]:
+        print()
+        print("Failures")
+        for failure in result["failures"]:
+            print("  - %s" % failure)
+    print()
+    print("Verdict: %s" % result["verdict"])
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("proof", help="canonical JSON proof from prove-utxo.py")
+    ap.add_argument("--root", help="expected UTXO root; defaults to root embedded in proof")
+    ap.add_argument("--json", action="store_true", help="print canonical JSON")
+    args = ap.parse_args(argv)
+
+    result = verify(load_proof(args.proof), args.root)
+    data = canonical_bytes(result)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(result)
+    return 0 if result["verdict"] == "UTXO_PROOF_VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/scripts/verify-utxo-set.py b/scripts/verify-utxo-set.py
new file mode 100644
index 0000000..b5bf3d5
--- /dev/null
+++ b/scripts/verify-utxo-set.py
@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Build a deterministic Bitflash UTXO-set commitment from local blk*.dat."""
+
+import argparse
+import hashlib
+import sys
+from pathlib import Path
+
+import bitflash_chain as chain
+
+
+def build_report(raw_blocks, include_utxos=False, strict_duplicates=False):
+    blocks = chain.select_main_chain(raw_blocks)
+    state = chain.apply_blocks(blocks, strict_duplicates=strict_duplicates)
+    utxos = state["utxos"]
+    stats = state["stats"]
+    tip = blocks[-1]
+    root = chain.utxo_root(utxos)
+    checks = {
+        "genesis_hash_matches_source": blocks[0]["hash"] == chain.GENESIS_HASH,
+        "genesis_merkle_matches_source": blocks[0]["merkle_root"] == chain.GENESIS_MERKLE,
+        "all_scanned_merkle_roots_match": all(b["computed_merkle_root"] == b["merkle_root"] for b in blocks),
+        "no_missing_spends": len(stats["missing_spends"]) == 0,
+    }
+    warnings = {
+        "legacy_duplicate_output_overwrites": len(stats["duplicate_outputs"]),
+    }
+    report = {
+        "schema": "bitflash-utxo-set-commitment-1",
+        "deterministic": True,
+        "chain": {
+            "name": "Bitflash",
+            "ticker": "BTF",
+            "message_start_hex": chain.MAGIC.hex(),
+            "coin": chain.COIN,
+        },
+        "commitment": {
+            "algorithm": "sorted-outpoint-merkle-sha256",
+            "leaf_domain": "BTFUTXO1",
+            "node_domain": "BTFNODE1",
+            "root": root,
+        },
+        "scanned": {
+            "raw_block_count": len(raw_blocks),
+            "side_blocks_ignored": len(raw_blocks) - len(blocks),
+            "main_chain_block_count": len(blocks),
+            "first_height": 0,
+            "last_height": len(blocks) - 1,
+            "tip_hash": tip["hash"],
+            "tip_time": tip["time"],
+            "tip_time_utc": tip["time_utc"],
+        },
+        "stats": stats,
+        "checks": checks,
+        "warnings": warnings,
+        "verdict": "UTXO_COMMITMENT_VERIFIED" if all(checks.values()) else "CHECKS_FAILED",
+    }
+    if include_utxos:
+        report["utxos"] = {k: utxos[k] for k in sorted(utxos)}
+    return report
+
+
+def print_text(report):
+    data_hash = hashlib.sha256(chain.canonical_bytes(report)).hexdigest()
+    print("Bitflash UTXO-set commitment verifier")
+    print("schema: %s" % report["schema"])
+    print("canonical report sha256: %s" % data_hash)
+    print()
+    print("Commitment")
+    print("  root:   %s" % report["commitment"]["root"])
+    print("  algo:   %s" % report["commitment"]["algorithm"])
+    print()
+    print("Scanned")
+    print("  main chain blocks: %d" % report["scanned"]["main_chain_block_count"])
+    print("  raw disk blocks:   %d" % report["scanned"]["raw_block_count"])
+    print("  side ignored:      %d" % report["scanned"]["side_blocks_ignored"])
+    print("  height: %d..%d" % (report["scanned"]["first_height"], report["scanned"]["last_height"]))
+    print("  tip:    %s" % report["scanned"]["tip_hash"])
+    print()
+    print("Supply")
+    print("  utxos:  %d" % report["stats"]["utxo_count"])
+    print("  supply: %s BTF" % report["stats"]["total_unspent_btf"])
+    print("  mined:  %s BTF" % report["stats"]["total_coinbase_btf"])
+    print("  delta:  %s BTF" % report["stats"]["coinbase_minus_unspent_btf"])
+    print("  fees:   %s BTF" % report["stats"]["total_fees_btf"])
+    if report["warnings"]["legacy_duplicate_output_overwrites"]:
+        print("  legacy duplicate overwrites: %d" % report["warnings"]["legacy_duplicate_output_overwrites"])
+    print()
+    print("Checks")
+    for key in sorted(report["checks"]):
+        print("  %s %s" % ("OK  " if report["checks"][key] else "FAIL", key))
+    print()
+    print("Verdict: %s" % report["verdict"])
+    print()
+    print("OpenTimestamps")
+    print("  canonical JSON can be stamped later with: ots stamp <report.json>")
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--datadir", default=chain.default_datadir(), help="Bitflash data directory")
+    ap.add_argument("--max-blocks", type=int, default=0,
+                    help="number of blocks to scan; 0 means all block files")
+    ap.add_argument("--include-utxos", action="store_true",
+                    help="include the full sorted UTXO map in JSON output")
+    ap.add_argument("--strict-duplicates", action="store_true",
+                    help="fail instead of using legacy last-write-wins duplicate output handling")
+    ap.add_argument("--json", action="store_true", help="print canonical JSON")
+    ap.add_argument("--out", help="write canonical JSON to this path")
+    args = ap.parse_args(argv)
+
+    blocks = chain.read_blocks(args.datadir, args.max_blocks)
+    if not blocks:
+        raise SystemExit("no Bitflash blocks found in %s" % args.datadir)
+    try:
+        report = build_report(blocks, include_utxos=args.include_utxos,
+                              strict_duplicates=args.strict_duplicates)
+    except chain.ParseError as e:
+        raise SystemExit(str(e))
+    data = chain.canonical_bytes(report)
+    if args.out:
+        Path(args.out).write_bytes(data)
+    if args.json:
+        sys.stdout.buffer.write(data)
+    else:
+        print_text(report)
+    return 0 if report["verdict"] == "UTXO_COMMITMENT_VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
diff --git a/src/Makefile b/src/Makefile
index 171afe0..c997ae3 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -2,10 +2,13 @@
 # Called by: make linux (root Makefile)
 
 CXX ?= g++
+FUZZ_CXX ?= clang++
 
 SECP_INC    ?= /usr/local/include
 SECP_LIB    ?= /usr/local/lib
-RANDOMX_DIR ?= $(HOME)/RandomX
+# The root Makefile exports RANDOMX_DIR (default: <repo>/randomx-build, built
+# by deps-randomx). This fallback only applies when src/ is built standalone.
+RANDOMX_DIR ?= $(abspath $(CURDIR)/..)/randomx-build
 
 IMGUI_DIR = imgui
 
@@ -29,14 +32,17 @@ WARNFLAGS = -Wformat -Werror=format \
             -Wno-narrowing -Wno-unused-result
 
 CXXFLAGS = -std=gnu++14 -O2 $(WARNFLAGS) -fpermissive -pthread \
-           -DSECP256K1_STATIC \
+           -DSECP256K1_STATIC -DBITFLASH_NODE_BUILD \
            -I$(SECP_INC) -I$(RANDOMX_DIR)/src \
            -I/usr/include/nlohmann \
            -I$(IMGUI_DIR)
+FUZZ_CXXFLAGS = $(filter-out -O2,$(CXXFLAGS)) -O1 -g -fno-omit-frame-pointer \
+                -fsanitize=fuzzer-no-link,address,undefined
+FUZZ_LDFLAGS = -fsanitize=fuzzer,address,undefined
 
 LIBS = -L$(SECP_LIB) -lsecp256k1 \
        -L$(RANDOMX_DIR)/build -lrandomx \
-       -lsodium -lssl -lcrypto -ldb_cxx -lpthread \
+       -lsodium -lssl -lcrypto -ldb_cxx -lsqlite3 -lpthread \
        -lglfw -lGL
 
 # Every header a .cpp here includes has to be listed, not just the interesting
@@ -49,7 +55,8 @@ LIBS = -L$(SECP_LIB) -lsecp256k1 \
 HEADERS = headers_core.h headers.h util.h main.h serialize.h uint256.h \
           key.h bignum.h script.h db.h base58.h net.h nostr.h \
           randomx_pow.h btfaddr.h btfchan.h btfrv.h btftunnel.h \
-          selftest.h walletcmd.h compat.h sockcount.h font_roboto.h
+          selftest.h walletcmd.h wallet_sqlite.h compat.h sockcount.h proxy.h tor.h font_roboto.h \
+          compactblock.h
 
 IMGUI_OBJS = obj/imgui.o obj/imgui_draw.o obj/imgui_tables.o \
              obj/imgui_widgets.o obj/imgui_impl_glfw.o obj/imgui_impl_opengl3.o
@@ -57,7 +64,8 @@ IMGUI_OBJS = obj/imgui.o obj/imgui_draw.o obj/imgui_tables.o \
 NODE_OBJS = obj/util.o obj/script.o obj/db.o obj/net.o obj/main.o \
             obj/sha.o obj/nostr.o obj/randomx_pow.o \
             obj/btfaddr.o obj/btfchan.o obj/btfrv.o obj/btftunnel.o obj/rpc.o \
-            obj/selftest.o obj/bip32.o obj/walletcmd.o
+            obj/selftest.o obj/bip32.o obj/walletcmd.o obj/wallet_sqlite.o \
+            obj/proxy.o obj/tor.o obj/compactblock.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o
 
@@ -96,7 +104,7 @@ obj/imgui_impl_opengl3.o: $(IMGUI_DIR)/imgui_impl_opengl3.cpp
         $(CXX) -c $(CXXFLAGS) -o $@ $<
 
 bitflash: $(IMGUI_OBJS) $(NODE_OBJS) $(GUI_OBJS)
-        $(CXX) $(CXXFLAGS) -o $@ $^ $(LIBS)
+        $(CXX) $(CXXFLAGS) $(LDHARDFLAGS) -o $@ $^ $(LIBS)
         @echo "Built: bitflash"
 
 # ---- headless node ---------------------------------------------------------
@@ -110,13 +118,31 @@ bitflash: $(IMGUI_OBJS) $(NODE_OBJS) $(GUI_OBJS)
 # Objects go to obj-node/ because main_gui.cpp is compiled twice, with and
 # without -DBITFLASH_NO_GUI, and the two must not overwrite each other.
 
+# RandomX links a hand-written assembly JIT stub, jit_compiler_x86_static.S,
+# which carries no .note.GNU-stack marker. Older binutils -- Debian 12's, which
+# is what builds against the oldest glibc we ship to -- reads a missing marker
+# as "this object wants an executable stack" and marks the whole binary RWE,
+# switching NX off for the process. Newer toolchains default the other way, so
+# identical source produced GNU_STACK RW on Ubuntu 26.04 and RWE on bookworm,
+# announced by nothing louder than a linker warning in the middle of the build.
+#
+# Assert it here rather than inherit whichever default the build host happens
+# to carry. The JIT maps its own W^X pages and never executes from the stack,
+# so nothing needs the permission this takes away. Check with:
+#   readelf -lW bitflash-node | grep -A1 GNU_STACK   # expect RW, not RWE
+LDHARDFLAGS = -Wl,-z,noexecstack
+
 NODE_LIBS = -L$(SECP_LIB) -lsecp256k1 \
             -L$(RANDOMX_DIR)/build -lrandomx \
-            -lsodium -lssl -lcrypto -ldb_cxx -lpthread
+            -lsodium -lssl -lcrypto -ldb_cxx -lsqlite3 -lpthread
 
 NODE_ONLY_OBJS = $(patsubst obj/%,obj-node/%,$(NODE_OBJS)) \
                  obj-node/main_gui.o obj-node/headless.o
 
+FUZZ_BASE_OBJS = $(patsubst obj/%,obj-fuzz/%,$(NODE_OBJS))
+FUZZ_NET_MESSAGE_OBJS = $(FUZZ_BASE_OBJS) obj-fuzz/fuzz_net_message.o
+FUZZ_SCRIPT_OBJS = $(FUZZ_BASE_OBJS) obj-fuzz/fuzz_script.o
+
 obj-node/%.o: %.cpp $(HEADERS)
         @mkdir -p obj-node
         $(CXX) -c $(CXXFLAGS) -DBITFLASH_NO_GUI -o $@ $<
@@ -126,21 +152,85 @@ obj-node/sha.o: sha.cpp sha.h
         $(CXX) -c $(CXXFLAGS) -DBITFLASH_NO_GUI -O3 -o $@ $<
 
 bitflash-node: $(NODE_ONLY_OBJS)
-        $(CXX) $(CXXFLAGS) -o $@ $^ $(NODE_LIBS)
+        $(CXX) $(CXXFLAGS) $(LDHARDFLAGS) -o $@ $^ $(NODE_LIBS)
         @echo "Built: bitflash-node (headless, no libGL needed)"
 
+obj-fuzz/%.o: %.cpp $(HEADERS)
+        @mkdir -p obj-fuzz
+        $(FUZZ_CXX) -c $(FUZZ_CXXFLAGS) -DBITFLASH_FUZZ -o $@ $<
+
+obj-fuzz/sha.o: sha.cpp sha.h
+        @mkdir -p obj-fuzz
+        $(FUZZ_CXX) -c $(FUZZ_CXXFLAGS) -DBITFLASH_FUZZ -O1 -o $@ $<
+
+obj-fuzz/fuzz_net_message.o: fuzz_net_message.cpp $(HEADERS)
+        @mkdir -p obj-fuzz
+        $(FUZZ_CXX) -c $(FUZZ_CXXFLAGS) -DBITFLASH_FUZZ -o $@ $<
+
+obj-fuzz/fuzz_script.o: fuzz_script.cpp $(HEADERS)
+        @mkdir -p obj-fuzz
+        $(FUZZ_CXX) -c $(FUZZ_CXXFLAGS) -DBITFLASH_FUZZ -o $@ $<
+
+fuzz-net-message: $(FUZZ_NET_MESSAGE_OBJS)
+        $(FUZZ_CXX) $(filter-out -fsanitize=fuzzer-no-link%,$(FUZZ_CXXFLAGS)) \
+          $(FUZZ_LDFLAGS) -o $@ $^ $(NODE_LIBS)
+        @echo "Built: fuzz-net-message"
+
+fuzz-script: $(FUZZ_SCRIPT_OBJS)
+        $(FUZZ_CXX) $(filter-out -fsanitize=fuzzer-no-link%,$(FUZZ_CXXFLAGS)) \
+          $(FUZZ_LDFLAGS) -o $@ $^ $(NODE_LIBS)
+        @echo "Built: fuzz-script"
+
+fuzz-net-message-smoke: fuzz-net-message
+        @mkdir -p ../work/fuzz-corpus/net-message
+        @printf '\277\040\134\375ping\000\000\000\000\000\000\000\000\000\000\000\000' > ../work/fuzz-corpus/net-message/ping-header
+        @printf '\277\040\134\375version\000\000\000\000\000\000\000\000\000' > ../work/fuzz-corpus/net-message/version-header
+        ./fuzz-net-message -runs=128 ../work/fuzz-corpus/net-message
+
+fuzz-script-smoke: fuzz-script
+        @mkdir -p ../work/fuzz-corpus/script
+        @printf '\000\121' > ../work/fuzz-corpus/script/op-true
+        @printf '\001\166\251\024\001\002\003\004\005\006\007\010\011\012\013\014\015\016\017\020\021\022\023\024\210\254' > ../work/fuzz-corpus/script/p2pkh-shape
+        @printf '\000\115\377\377' > ../work/fuzz-corpus/script/truncated-pushdata2
+        ./fuzz-script -runs=128 ../work/fuzz-corpus/script
+
 clean:
-        rm -rf obj obj-node bitflash bitflash-node test_bip32
+        rm -rf obj obj-node obj-fuzz bitflash bitflash-node fuzz-net-message fuzz-script test_bip32 test_compactblock
 
 test_bip32: test_bip32.cpp bip32.cpp bip32.h bip39_english.h
         $(CXX) $(CXXFLAGS) -o $@ test_bip32.cpp bip32.cpp -lssl -lcrypto
 
-tests: test_bip32 bitflash-node
+# Upstream shipped test_compactblock.cpp with no build rule at all, so it was
+# never compiled there. It links the standalone way test_bip32 does: it supplies
+# its own mapTransactions and GetAppDir so main.cpp stays out of the link, and
+# only needs sha.cpp/util.cpp for Hash() and the logging helpers.
+#
+# TEST_LIBS is overridable for the same reason NODE_LIBS is: the pinned dep tree
+# ships libsodium as a static archive only, so a build against it passes
+# TEST_LIBS="... -l:libsodium.a ...".
+TEST_LIBS ?= -lsodium -lssl -lcrypto -lpthread
+
+test_compactblock: test_compactblock.cpp compactblock.cpp compactblock.h $(HEADERS)
+        $(CXX) $(CXXFLAGS) -o $@ test_compactblock.cpp compactblock.cpp sha.cpp util.cpp \
+          $(TEST_LIBS)
+
+tests: test_bip32 test_compactblock bitflash-node
         ./test_bip32
+        ./test_compactblock
         ./bitflash-node -selftest=wallet-keypool
         ./bitflash-node -selftest=wallet-hd
         ./bitflash-node -selftest=wallet-format
+        ./bitflash-node -selftest=wallet-sqlite
+        ./bitflash-node -selftest=wallet-sqlite-migration
         ./bitflash-node -selftest=wallet-crypto
         ./bitflash-node -selftest=wallet-encrypt
         ./bitflash-node -selftest=net-message
+        ./bitflash-node -selftest=network-params
         ./bitflash-node -selftest=consensus-limits
+        ./bitflash-node -selftest=pool-stratum
+        ./bitflash-node -selftest=payout-ledger
+        ./bitflash-node -selftest=parse-money
+        ./bitflash-node -selftest=socks5-proxy
+        ./bitflash-node -selftest=managed-tor
+
+.PHONY: tests fuzz-net-message-smoke fuzz-script-smoke
diff --git a/src/bignum.h b/src/bignum.h
index 9da104b..6a295b2 100644
--- a/src/bignum.h
+++ b/src/bignum.h
@@ -155,7 +155,9 @@ public:
         for (int i = 0; i < 8; i++)
         {
             unsigned char c = (n >> 56) & 0xff;
-            n <<= 8;
+            n = (int64)((uint64)n << 8);  // shift in unsigned space; <<= on a
+                                          // signed int64 with the top byte set
+                                          // is overflow UB (fuzzer/UBSan finding)
             if (fLeadingZeroes)
             {
                 if (c == 0)
diff --git a/src/btfaddr.cpp b/src/btfaddr.cpp
index 6edcc91..502220e 100644
--- a/src/btfaddr.cpp
+++ b/src/btfaddr.cpp
@@ -19,6 +19,8 @@
 #include <cstring>
 #include <algorithm>
 #include <cctype>
+#include <cerrno>
+#include <cstdlib>
 
 using json = nlohmann::json;
 
@@ -166,10 +168,47 @@ static bool HexDecode(const std::string& s, unsigned char* out, size_t n)
     return true;
 }
 
+bool NormalizeOnionEndpoint(const std::string& in, std::string& out)
+{
+    out.clear();
+    std::string s = ToLowerTrim(in);
+    size_t colon = s.rfind(':');
+    if (colon == std::string::npos || colon == 0 || colon + 1 >= s.size())
+        return false;
+
+    std::string host = s.substr(0, colon);
+    std::string port = s.substr(colon + 1);
+    while (!host.empty() && host.back() == '.') host.pop_back();
+    static const char* suffix = ".onion";
+    const size_t suffixLen = strlen(suffix);
+    if (host.size() != 56 + suffixLen)
+        return false;
+    if (host.compare(host.size() - suffixLen, suffixLen, suffix) != 0)
+        return false;
+    for (size_t i = 0; i < 56; i++)
+    {
+        char c = host[i];
+        if (!((c >= 'a' && c <= 'z') || (c >= '2' && c <= '7')))
+            return false;
+    }
+    for (size_t i = 0; i < port.size(); i++)
+        if (!isdigit((unsigned char)port[i]))
+            return false;
+
+    errno = 0;
+    char* end = NULL;
+    long nPort = strtol(port.c_str(), &end, 10);
+    if (errno == ERANGE || end == NULL || *end != '\0' || nPort <= 0 || nPort > 65535)
+        return false;
+
+    out = host + ":" + port;
+    return true;
+}
+
 // Digest signed over the descriptor fields (domain-separated).
-static void DescriptorDigest(const unsigned char pubkey[32], const std::string& enc,
-                             const std::string& meeting_node, uint64_t created,
-                             unsigned char out[32])
+static void DescriptorDigestV2(const unsigned char pubkey[32], const std::string& enc,
+                               const std::string& meeting_node, uint64_t created,
+                               unsigned char out[32])
 {
     static const char* DS = ".btf-descriptor-v2";
     SHA256_CTX ctx;
@@ -184,9 +223,27 @@ static void DescriptorDigest(const unsigned char pubkey[32], const std::string&
     SHA256_Final(out, &ctx);
 }
 
+static void DescriptorDigestV3(const unsigned char pubkey[32], const std::string& enc,
+                               const std::string& meeting_node, const std::string& onion,
+                               uint64_t created, unsigned char out[32])
+{
+    static const char* DS = ".btf-descriptor-v3-onion";
+    SHA256_CTX ctx;
+    SHA256_Init(&ctx);
+    SHA256_Update(&ctx, (const unsigned char*)DS, strlen(DS));
+    SHA256_Update(&ctx, pubkey, 32);
+    SHA256_Update(&ctx, (const unsigned char*)enc.data(), enc.size());
+    SHA256_Update(&ctx, (const unsigned char*)meeting_node.data(), meeting_node.size());
+    SHA256_Update(&ctx, (const unsigned char*)onion.data(), onion.size());
+    unsigned char be[8];
+    for (int i = 0; i < 8; i++) be[i] = (unsigned char)((created >> (8 * (7 - i))) & 0xff);
+    SHA256_Update(&ctx, be, 8);
+    SHA256_Final(out, &ctx);
+}
+
 std::string SignDescriptor(void* ctxv, const unsigned char seckey[32],
                            const std::string& enc, const std::string& meeting_node,
-                           uint64_t created)
+                           uint64_t created, const std::string& onion)
 {
     secp256k1_context* ctx = (secp256k1_context*)ctxv;
     secp256k1_keypair kp;
@@ -197,17 +254,28 @@ std::string SignDescriptor(void* ctxv, const unsigned char seckey[32],
     secp256k1_xonly_pubkey_serialize(ctx, pubkey, &xpub);
 
     unsigned char digest[32];
-    DescriptorDigest(pubkey, enc, meeting_node, created, digest);
+    DescriptorDigestV2(pubkey, enc, meeting_node, created, digest);
 
     unsigned char sig[64];
     // Deterministic signature (NULL aux_rand), matching Itzal's no-aux-rand signing.
     if (!secp256k1_schnorrsig_sign32(ctx, sig, digest, &kp, NULL)) return std::string();
 
     json v = json::object();
-    v["v"]            = 2;
+    v["v"]            = onion.empty() ? 2 : 3;
     v["pubkey"]       = HexEncode(pubkey, 32);
     v["enc"]          = enc;
     v["meeting_node"] = meeting_node;
+    if (!onion.empty())
+    {
+        std::string onionNorm;
+        if (!NormalizeOnionEndpoint(onion, onionNorm)) return std::string();
+        unsigned char digest3[32];
+        DescriptorDigestV3(pubkey, enc, meeting_node, onionNorm, created, digest3);
+        unsigned char sig3[64];
+        if (!secp256k1_schnorrsig_sign32(ctx, sig3, digest3, &kp, NULL)) return std::string();
+        v["onion"] = onionNorm;
+        v["sig3"]  = HexEncode(sig3, 64);
+    }
     v["created"]      = created;
     v["sig"]          = HexEncode(sig, 64);
     return v.dump();
@@ -242,15 +310,47 @@ bool VerifyDescriptor(void* ctxv, const std::string& jsonStr,
         if (!HexDecode(v["sig"].get<std::string>(), sig, 64)) return false;
 
         unsigned char digest[32];
-        DescriptorDigest(expect_pubkey, enc, meeting_node, created, digest);
+        DescriptorDigestV2(expect_pubkey, enc, meeting_node, created, digest);
 
         secp256k1_xonly_pubkey xpub;
         if (!secp256k1_xonly_pubkey_parse(ctx, &xpub, expect_pubkey)) return false;
         if (!secp256k1_schnorrsig_verify(ctx, sig, digest, 32, &xpub)) return false;
 
+        std::string onion;
+        if (v.contains("onion"))
+        {
+            // A descriptor that carries an onion endpoint must prove it. The
+            // endpoint is covered by sig3 and only sig3, so any failure here --
+            // missing sig3, bad hex, unnormalised endpoint, bad signature --
+            // means the descriptor was tampered with, and a tampered
+            // descriptor is rejected outright. Upstream dropped just the onion
+            // and accepted the rest, which let any relay convert an onion
+            // descriptor into a rendezvous-only one by deleting a field.
+            //
+            // Residual, by design: removing BOTH "onion" and "sig3" still
+            // verifies, because the result is indistinguishable from a peer
+            // that never had an onion endpoint. Closing that requires binding
+            // the onion into the primary sig (the V2 digest), which every
+            // upstream 1.2.18/1.2.19 verifier would reject -- an upstream
+            // protocol change, not something this fork can do unilaterally.
+            if (!v["onion"].is_string()) return false;
+            if (!v.contains("sig3") || !v["sig3"].is_string()) return false;
+            std::string onionNorm;
+            std::string onionRaw = v["onion"].get<std::string>();
+            if (!NormalizeOnionEndpoint(onionRaw, onionNorm) || onionNorm != onionRaw)
+                return false;
+            unsigned char sig3[64];
+            unsigned char digest3[32];
+            DescriptorDigestV3(expect_pubkey, enc, meeting_node, onionNorm, created, digest3);
+            if (!HexDecode(v["sig3"].get<std::string>(), sig3, 64)) return false;
+            if (!secp256k1_schnorrsig_verify(ctx, sig3, digest3, 32, &xpub)) return false;
+            onion = onionNorm;
+        }
+
         memcpy(out.pubkey, expect_pubkey, 32);
         out.enc = enc;
         out.meeting_node = meeting_node;
+        out.onion = onion;
         out.created = created;
         return true;
     }
diff --git a/src/btfaddr.h b/src/btfaddr.h
index 1addf8f..55a3ebd 100644
--- a/src/btfaddr.h
+++ b/src/btfaddr.h
@@ -52,15 +52,21 @@ struct Descriptor
     unsigned char pubkey[32];
     std::string   enc;          // service x25519 public key (hex) for the E2E channel
     std::string   meeting_node; // rendezvous node the service is registered at
+    std::string   onion;        // optional direct Tor hidden-service endpoint (host.onion:port)
     uint64_t      created;
 };
 
+// Normalize and validate a direct Tor hidden-service endpoint. Only v3 onion
+// names are accepted: 56 base32 chars plus ".onion", followed by ":PORT".
+bool NormalizeOnionEndpoint(const std::string& in, std::string& out);
+
 // Sign a descriptor. `ctx` is a secp256k1_context* (passed as void* to keep this
 // header free of secp headers); `seckey` is the 32-byte service secret key.
 // Returns the descriptor JSON as a string, or "" on failure.
 std::string SignDescriptor(void* ctx, const unsigned char seckey[32],
                            const std::string& enc, const std::string& meeting_node,
-                           uint64_t created);
+                           uint64_t created,
+                           const std::string& onion = std::string());
 
 // Verify a descriptor is validly signed by `expect_pubkey` (the key the resolved
 // `.btf` address encodes). Returns true and fills `out` on success.
diff --git a/src/btfrv.cpp b/src/btfrv.cpp
index 905717f..7d705ef 100644
--- a/src/btfrv.cpp
+++ b/src/btfrv.cpp
@@ -5,6 +5,9 @@
 // Windows/Winsock implementation (Layer 6 will #ifdef this for Linux/BSD sockets).
 
 #include "btfrv.h"
+#ifdef BITFLASH_NODE_BUILD
+#include "proxy.h"
+#endif
 
 // Portable sockets: Winsock on Windows, BSD sockets on Linux/POSIX (for the
 // headless relay `bitflashd` that runs on the VPS).
@@ -37,6 +40,8 @@ typedef int SOCKET;
 #include <thread>
 #include <mutex>
 #include <atomic>
+#include <chrono>
+#include <system_error>
 
 namespace btf
 {
@@ -92,6 +97,11 @@ static bool WriteN(SOCKET s, const void* buf, int n)
 
 static SOCKET ConnectTo(const char* host, unsigned short port)
 {
+#ifdef BITFLASH_NODE_BUILD
+    SOCKET s = BtfConnectSocket(host, port, SOCK_RV_DIAL, 10);
+    if (s == INVALID_SOCKET)
+        return INVALID_SOCKET;
+#else
     struct addrinfo hints, *res = NULL;
     memset(&hints, 0, sizeof(hints));
     hints.ai_family = AF_UNSPEC; // IPv4 or IPv6 (some relays are v6-only)
@@ -130,6 +140,7 @@ static SOCKET ConnectTo(const char* host, unsigned short port)
     }
     freeaddrinfo(res);
     if (s == INVALID_SOCKET) return INVALID_SOCKET;
+#endif
 
     // Clear the timeout -- the socket is now a live tunnel and must not
     // time out when idle. recv() will block until data arrives or peer closes.
@@ -200,8 +211,28 @@ static void HandleIncoming(SOCKET s)
         bool a = WriteN(svc, &ok, 1);
         bool b = WriteN(s, &ok, 1);
         if (!a || !b) { CLOSESOCK(svc); CLOSESOCK(s); return; }
-        std::thread(Forward, s, svc).detach();
-        std::thread(Forward, svc, s).detach();
+        // One thread pumps s -> svc; this thread pumps svc -> s. Spawning a
+        // thread per direction left no clean way to fail the second spawn:
+        // std::thread throws std::system_error when pthread_create is refused
+        // (NPROC limit, container pids cgroup, memory pressure), the first
+        // pump was already detached, and closing its sockets from here would
+        // race it -- so nothing caught the throw and it reached
+        // std::terminate, killing the relay over one pair it could not serve.
+        // Running one direction on this thread leaves exactly one spawn to
+        // guard, and a failure here has nothing running yet to race.
+        try
+        {
+            std::thread(Forward, s, svc).detach();
+        }
+        catch (const std::system_error& e)
+        {
+            fprintf(stderr, "rendezvous relay: cannot spawn forward thread (%s), pair dropped\n",
+                    e.what());
+            CLOSESOCK(svc);
+            CLOSESOCK(s);
+            return;
+        }
+        Forward(svc, s);
     }
     else
     {
@@ -227,6 +258,7 @@ bool RvRelayRun(unsigned short port)
     if (bind(g_listen, (struct sockaddr*)&addr, sizeof(addr)) != 0) { CLOSESOCK(g_listen); return false; }
     if (listen(g_listen, 16) != 0) { CLOSESOCK(g_listen); return false; }
 
+    int nSpawnFails = 0;
     while (!g_stop)
     {
         struct sockaddr_in cli;
@@ -237,7 +269,27 @@ bool RvRelayRun(unsigned short port)
             if (g_stop) break;
             continue;
         }
-        std::thread(HandleIncoming, s).detach();
+        try
+        {
+            std::thread(HandleIncoming, s).detach();
+            nSpawnFails = 0;
+        }
+        catch (const std::system_error& e)
+        {
+            // A refused pthread_create is backpressure, not a reason to die:
+            // the condition behind it (NPROC, pids cgroup, memory) does not
+            // clear in milliseconds, and the connection count feeding it is
+            // attacker-influenced. Drop this one peer, stop accepting for a
+            // moment -- longer each time, capped -- and keep serving the
+            // connections already established.
+            fprintf(stderr, "rendezvous relay: cannot spawn connection thread (%s), connection dropped\n",
+                    e.what());
+            CLOSESOCK(s);
+            nSpawnFails++;
+            int nWaitMs = nSpawnFails < 5 ? nSpawnFails * 1000 : 5000;
+            for (int i = 0; i < nWaitMs && !g_stop; i += 100)
+                std::this_thread::sleep_for(std::chrono::milliseconds(100));
+        }
     }
     CLOSESOCK(g_listen);
     g_listen = INVALID_SOCKET;
@@ -325,17 +377,29 @@ bool RvServiceWaitPaired(RvSocket s, int nTimeoutSecs)
 }
 
 RvSocket RvClientConnect(const char* relay_host, unsigned short port,
-                         const unsigned char target_pubkey[32])
+                         const unsigned char target_pubkey[32],
+                         RvClientFail* pFail)
 {
+    if (pFail) *pFail = RVC_FAIL_DIAL;
     if (!RvInit()) return RV_INVALID;
     SOCKET s = ConnectTo(relay_host, port);
     if (s == INVALID_SOCKET) return RV_INVALID;
+    if (pFail) *pFail = RVC_FAIL_PAIR;
     unsigned char hdr[33];
     hdr[0] = (unsigned char)'C';
     memcpy(hdr + 1, target_pubkey, 32);
     if (!WriteN(s, hdr, 33)) { CLOSESOCK(s); return RV_INVALID; }
     unsigned char paired = 0;
-    if (!ReadN(s, &paired, 1) || paired != 0x01) { CLOSESOCK(s); return RV_INVALID; }
+    if (!ReadN(s, &paired, 1)) { CLOSESOCK(s); return RV_INVALID; }
+    if (paired != 0x01)
+    {
+        // The relay answered and declined: HandleIncoming writes 0x00 and
+        // closes when no service is parked under this pubkey right now.
+        if (pFail) *pFail = RVC_FAIL_REFUSED;
+        CLOSESOCK(s);
+        return RV_INVALID;
+    }
+    if (pFail) *pFail = RVC_FAIL_NONE;
     return (RvSocket)s;
 }
 
diff --git a/src/btfrv.h b/src/btfrv.h
index 9cd7476..1e85cb0 100644
--- a/src/btfrv.h
+++ b/src/btfrv.h
@@ -57,10 +57,25 @@ RvSocket RvServiceRegister(const char* relay_host, unsigned short port,
 bool RvServiceWaitPaired(RvSocket s, int nTimeoutSecs = 0);
 
 // ---- client side (the node dialing a .btf address) ----
+// Where a failed RvClientConnect stopped. RV_INVALID alone collapses three
+// different situations -- relay unreachable, relay reachable but nobody
+// registered, connection died mid-pairing -- and they point at different
+// components. The caller can only report the right one if this side says
+// which it saw.
+enum RvClientFail
+{
+    RVC_FAIL_NONE = 0,
+    RVC_FAIL_DIAL,    // TCP connect to the relay itself failed
+    RVC_FAIL_REFUSED, // relay answered 0x00: no service registered under this pubkey
+    RVC_FAIL_PAIR,    // relay connection died before pairing completed
+};
+
 // Connect through the relay to the service registered under `target_pubkey`.
-// Returns the paired socket, or RV_INVALID on error.
+// Returns the paired socket, or RV_INVALID on error -- with `pFail`, if
+// given, naming the stage that failed.
 RvSocket RvClientConnect(const char* relay_host, unsigned short port,
-                         const unsigned char target_pubkey[32]);
+                         const unsigned char target_pubkey[32],
+                         RvClientFail* pFail = 0);
 
 // Blocking read/write of exactly n bytes over a rendezvous socket. Return false
 // on error/EOF.
diff --git a/src/btftunnel.cpp b/src/btftunnel.cpp
index 63d178b..4058f6b 100644
--- a/src/btftunnel.cpp
+++ b/src/btftunnel.cpp
@@ -25,8 +25,12 @@ typedef int SOCKET;
 #endif
 #include "sockcount.h"
 #include <cstring>
+#include <cstdio>
+#include <memory>
+#include <new>
 #include <vector>
 #include <thread>
+#include <system_error>
 
 namespace btf
 {
@@ -119,35 +123,155 @@ static void PumpIn(SOCKET pumpEnd, RvSocket rv, std::vector<unsigned char> key)
     shutdown((SOCKET)rv, SD_BOTH);
 }
 
+// The pump end and the rendezvous socket, owned jointly by whoever is still
+// using them. Closed once, by the last reference to go.
+//
+// Joint ownership rather than "the inbound pump owns the cleanup", because
+// either pump can reach its exit first and BOTH touch BOTH descriptors on the
+// way out -- PumpOut ends in shutdown(rv), shutdown(pumpEnd) and PumpIn ends in
+// the mirror image. A single owner therefore has no exit at which the other is
+// guaranteed to be finished. Holding a reference for the whole body of each
+// pump gives it one: the close cannot happen until the last pump has stopped
+// touching the descriptors, so no shutdown() can land on a number that has
+// already been closed and handed back out by the kernel to an unrelated
+// connection.
+struct TunnelEnds
+{
+    SOCKET   pumpEnd;
+    RvSocket rv;
+    TunnelEnds(SOCKET p, RvSocket r) : pumpEnd(p), rv(r) {}
+    ~TunnelEnds() { BtfCloseSocket(pumpEnd); RvClose(rv); }
+private:
+    TunnelEnds(const TunnelEnds&);
+    TunnelEnds& operator=(const TunnelEnds&);
+};
+
 // Start the two pumps and hand back the app-facing socket. When both pumps
 // finish, close the pump end and the rendezvous socket.
+//
+// That sentence used to be a comment describing something the code did not do.
+// The inbound pump closed both descriptors as soon as it exited, without
+// waiting for the outbound pump, which then called shutdown() on both at its
+// own exit. Whether that shutdown hit a live descriptor or a closed one came
+// down to which pump got there first, and the rendezvous socket dying before
+// the app socket -- a relay restart, the far side hanging up -- is precisely
+// the order that puts the inbound pump ahead. Measured over 25 such teardowns
+// against the real code: 29 shutdowns landed on an already-closed descriptor.
+//
+// appEnd is not part of this. It is handed to the caller on success and closed
+// here on every failure path; no pump ever touches it.
+//
+// Every tunnel is two threads, and a tunnel is one peer connection (a .btf
+// dial or accept, a pool miner, a participant's pool session) -- so the
+// thread count scales with peer count, which is attacker-influenced. When
+// pthread_create is refused std::thread throws std::system_error; uncaught it
+// reached std::terminate and took the whole process down over one connection
+// it could not serve. Both spawns are guarded, and the failure paths return
+// INVALID_SOCKET, which every caller already handles by dropping just that
+// connection.
 static btf_socket_t StartTunnel(RvSocket rv, const unsigned char shared[32])
 {
     btf_socket_t appEnd, pumpEnd;
     if (!MakeLocalPair(appEnd, pumpEnd)) { RvClose(rv); return INVALID_SOCKET; }
 
     std::vector<unsigned char> key(shared, shared + 32);
-    std::thread(PumpOut, pumpEnd, rv, key).detach();
-    std::thread([pumpEnd, rv, key]() {
-        PumpIn(pumpEnd, rv, key);
+
+    // make_shared, not shared_ptr(new ...): it allocates before it constructs,
+    // so it either comes back owning both descriptors or throws having taken
+    // ownership of neither. The two-step form can run the deleter and then
+    // throw, which would close both here and again below.
+    std::shared_ptr<TunnelEnds> ends;
+    try
+    {
+        ends = std::make_shared<TunnelEnds>(pumpEnd, rv);
+    }
+    catch (const std::bad_alloc&)
+    {
+        fprintf(stderr, "btf tunnel: out of memory starting tunnel, tunnel dropped\n");
         BtfCloseSocket(pumpEnd);
+        BtfCloseSocket(appEnd);
         RvClose(rv);
-    }).detach();
+        return INVALID_SOCKET;
+    }
+
+    try
+    {
+        std::thread([ends, key]() { PumpIn(ends->pumpEnd, ends->rv, key); }).detach();
+    }
+    catch (const std::system_error& e)
+    {
+        // Nothing is running yet: `ends` is the only reference, and returning
+        // drops it, which is what closes pumpEnd and rv.
+        fprintf(stderr, "btf tunnel: cannot spawn inbound pump (%s), tunnel dropped\n",
+                e.what());
+        BtfCloseSocket(appEnd);
+        return INVALID_SOCKET;
+    }
+
+    try
+    {
+        std::thread([ends, key]() { PumpOut(ends->pumpEnd, ends->rv, key); }).detach();
+    }
+    catch (const std::system_error& e)
+    {
+        // The inbound pump may be parked in RvReadN(rv) or may already have
+        // exited -- when the spawn is refused because the process is loaded,
+        // the rendezvous socket is often dead for the same reason, and then
+        // PumpIn returns on its first length read. Either way this thread
+        // still holds a reference, so both descriptors are still open: the
+        // shutdown wakes the pump if it is parked and is harmless if it is
+        // not. The close belongs to whichever reference goes last.
+        fprintf(stderr, "btf tunnel: cannot spawn outbound pump (%s), tunnel dropped\n",
+                e.what());
+        shutdown((SOCKET)ends->rv, SD_BOTH);
+        shutdown(ends->pumpEnd, SD_BOTH);
+        BtfCloseSocket(appEnd);
+        return INVALID_SOCKET;
+    }
     return appEnd;
 }
 
+const char* TunnelFailText(TunnelFail f)
+{
+    switch (f)
+    {
+    case TUNNEL_FAIL_NONE:      return "no failure";
+    case TUNNEL_FAIL_INIT:      return "local socket/crypto init failed";
+    case TUNNEL_FAIL_DIAL:      return "meeting node unreachable (tcp dial failed)";
+    case TUNNEL_FAIL_REFUSED:   return "relay reachable, but no service registered there for this address";
+    case TUNNEL_FAIL_PAIR:      return "relay connection died before pairing completed";
+    case TUNNEL_FAIL_HANDSHAKE: return "end-to-end handshake failed";
+    case TUNNEL_FAIL_LOCAL:     return "local tunnel setup failed";
+    }
+    return "unknown failure";
+}
+
 btf_socket_t BtfClientTunnel(const char* meeting_host, unsigned short port,
                              const unsigned char target_pubkey[32],
-                             const unsigned char service_enc_pub[32])
+                             const unsigned char service_enc_pub[32],
+                             TunnelFail* pFail)
 {
+    if (pFail) *pFail = TUNNEL_FAIL_INIT;
     if (!TunnelInit()) return INVALID_SOCKET;
-    RvSocket rv = RvClientConnect(meeting_host, port, target_pubkey);
-    if (rv == RV_INVALID) return INVALID_SOCKET;
+    RvClientFail rvFail = RVC_FAIL_NONE;
+    RvSocket rv = RvClientConnect(meeting_host, port, target_pubkey, &rvFail);
+    if (rv == RV_INVALID)
+    {
+        if (pFail)
+            *pFail = rvFail == RVC_FAIL_DIAL    ? TUNNEL_FAIL_DIAL
+                   : rvFail == RVC_FAIL_REFUSED ? TUNNEL_FAIL_REFUSED
+                                                : TUNNEL_FAIL_PAIR;
+        return INVALID_SOCKET;
+    }
 
     unsigned char eph_pub[32], shared[32];
+    if (pFail) *pFail = TUNNEL_FAIL_HANDSHAKE;
     if (!ChanClientHandshake(service_enc_pub, eph_pub, shared)) { RvClose(rv); return INVALID_SOCKET; }
     if (!RvWriteN(rv, eph_pub, 32)) { RvClose(rv); return INVALID_SOCKET; }
-    return StartTunnel(rv, shared);
+    if (pFail) *pFail = TUNNEL_FAIL_LOCAL;
+    btf_socket_t app = StartTunnel(rv, shared);
+    if (app != INVALID_SOCKET && pFail) *pFail = TUNNEL_FAIL_NONE;
+    return app;
 }
 
 btf_socket_t BtfServiceWrap(RvSocket rv, const unsigned char my_enc_sk[32])
diff --git a/src/btftunnel.h b/src/btftunnel.h
index 24a7509..3cc87cd 100644
--- a/src/btftunnel.h
+++ b/src/btftunnel.h
@@ -36,12 +36,33 @@ namespace btf
 // Initialize (sockets + libsodium). Idempotent.
 bool TunnelInit();
 
+// Which stage of BtfClientTunnel failed. INVALID_SOCKET alone says only "no
+// tunnel"; a caller that then guesses at causes in its log line sends whoever
+// reads it to the wrong component (issue #17: "relay unreachable or pool not
+// listening" blamed two healthy parts). The stage is what this side actually
+// knows -- report that.
+enum TunnelFail
+{
+    TUNNEL_FAIL_NONE = 0,
+    TUNNEL_FAIL_INIT,      // local socket/crypto init failed
+    TUNNEL_FAIL_DIAL,      // TCP connect to the meeting node failed
+    TUNNEL_FAIL_REFUSED,   // relay reachable, but no service registered under the pubkey
+    TUNNEL_FAIL_PAIR,      // relay connection died before pairing completed
+    TUNNEL_FAIL_HANDSHAKE, // end-to-end channel handshake failed
+    TUNNEL_FAIL_LOCAL,     // local pump plumbing (socket pair / threads) failed
+};
+
+// Short description of a TunnelFail for log lines.
+const char* TunnelFailText(TunnelFail f);
+
 // Client: dial the service registered under `target_pubkey` at the meeting node
 // (host:port), box to its static x25519 `service_enc_pub`, and return a local
-// plaintext SOCKET tunneled end-to-end to the service. INVALID_SOCKET on error.
+// plaintext SOCKET tunneled end-to-end to the service. INVALID_SOCKET on error
+// -- with `pFail`, if given, naming the stage that failed.
 btf_socket_t BtfClientTunnel(const char* meeting_host, unsigned short port,
                              const unsigned char target_pubkey[32],
-                             const unsigned char service_enc_pub[32]);
+                             const unsigned char service_enc_pub[32],
+                             TunnelFail* pFail = 0);
 
 // Service: wrap an already-paired rendezvous socket (RvServiceRegister followed
 // by RvServiceWaitPaired -- the pairing byte MUST already be consumed) with
diff --git a/src/compactblock.cpp b/src/compactblock.cpp
new file mode 100644
index 0000000..1ca6118
--- /dev/null
+++ b/src/compactblock.cpp
@@ -0,0 +1,175 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// See compactblock.h.
+
+#include "headers.h"
+#include "compactblock.h"
+#include <sodium.h>
+#include <map>
+
+uint256 CCmpctBlock::HeaderHash() const
+{
+    // Same technique CBlock::GetHash() uses: the header fields are laid out
+    // contiguously and in the same order here as in CBlock, so hashing the
+    // raw member range gives the identical block-identity hash.
+    return Hash(BEGIN(nVersion), END(nNonce));
+}
+
+uint64 ComputeShortTxId(const uint256& hashPrevBlock, uint64 shortIdNonce, const uint256& txid)
+{
+    // Derive a 16-byte SipHash key from (hashPrevBlock, shortIdNonce), so
+    // short IDs are specific to this block: they can't be precomputed
+    // before the block (and its freshly-chosen nonce) exist, and the same
+    // transaction gets a different short ID in every block it appears in
+    // (relevant across reorgs/re-announcements).
+    unsigned char keyMaterial[32 + sizeof(uint64)];
+    memcpy(keyMaterial, BEGIN(hashPrevBlock), 32);
+    memcpy(keyMaterial + 32, &shortIdNonce, sizeof(uint64));
+    uint256 keyHash = Hash((const char*)keyMaterial, (const char*)keyMaterial + sizeof(keyMaterial));
+
+    unsigned char out[crypto_shorthash_BYTES]; // 8 bytes
+    crypto_shorthash(out, (const unsigned char*)BEGIN(txid), 32, (const unsigned char*)BEGIN(keyHash));
+
+    uint64 id = 0;
+    memcpy(&id, out, sizeof(uint64));
+    return id & 0xFFFFFFFFFFFFULL; // low 48 bits -- matches the wire field width
+}
+
+bool BuildCompactBlock(const CBlock& block, CCmpctBlock& out)
+{
+    if (block.vtx.empty())
+        return false; // every real block has at least the coinbase
+
+    out.nVersion      = block.nVersion;
+    out.hashPrevBlock  = block.hashPrevBlock;
+    out.hashMerkleRoot = block.hashMerkleRoot;
+    out.nTime          = block.nTime;
+    out.nBits          = block.nBits;
+    out.nNonce         = block.nNonce;
+
+    // Upstream ignored the RAND_bytes return value here. On failure nonceBytes
+    // is left uninitialised and an indeterminate shortIdNonce goes out on the
+    // wire -- which is precisely the value this file relies on being
+    // unpredictable to stop short IDs being precomputed or ground against.
+    // Fail closed instead, matching every other RAND_bytes call site in this
+    // tree (bip32.cpp, db.cpp): the caller falls back to full-block relay,
+    // which is always correct.
+    unsigned char nonceBytes[sizeof(uint64)];
+    if (RAND_bytes(nonceBytes, sizeof(nonceBytes)) != 1)
+        return false;
+    memcpy(&out.shortIdNonce, nonceBytes, sizeof(uint64));
+
+    out.vPrefilledIndex.clear();
+    out.vPrefilledTx.clear();
+    out.vShortTxId.clear();
+
+    // Only the coinbase is prefilled (index 0) -- see file comment in
+    // compactblock.h for why that's enough for this chain's scale.
+    out.vPrefilledIndex.push_back(0);
+    out.vPrefilledTx.push_back(block.vtx[0]);
+
+    for (size_t i = 1; i < block.vtx.size(); i++)
+        out.vShortTxId.push_back(ComputeShortTxId(out.hashPrevBlock, out.shortIdNonce, block.vtx[i].GetHash()));
+
+    return true;
+}
+
+bool TryReconstructBlock(const CCmpctBlock& cmpct, CBlock& outBlock, std::vector<unsigned int>& vMissingIndex)
+{
+    vMissingIndex.clear();
+
+    size_t nTotal = cmpct.vPrefilledIndex.size() + cmpct.vShortTxId.size();
+    if (cmpct.vPrefilledIndex.size() != cmpct.vPrefilledTx.size() || nTotal == 0)
+        return false; // malformed
+
+    // nTotal comes straight off the wire once this is wired into the P2P
+    // layer, and serialize.h only bounds a vector length by MAX_SIZE
+    // (0x02000000), so an unbounded assign() below would let one 60-odd-byte
+    // message ask this node for ~33M default-constructed CTransactions. The
+    // smallest a transaction can serialise to is 10 bytes (nVersion, empty
+    // vin, empty vout, nLockTime), so no block within MAX_BLOCK_SIZE can hold
+    // more than MAX_BLOCK_SIZE/10 of them; anything above that is not a block
+    // we could ever accept. Rejecting here just falls back to full-block
+    // relay, which is always correct.
+    if (nTotal > MAX_BLOCK_SIZE / 10)
+        return false; // implausible tx count -- refuse to size a vector from it
+
+    outBlock.SetNull();
+    outBlock.nVersion      = cmpct.nVersion;
+    outBlock.hashPrevBlock  = cmpct.hashPrevBlock;
+    outBlock.hashMerkleRoot = cmpct.hashMerkleRoot;
+    outBlock.nTime          = cmpct.nTime;
+    outBlock.nBits          = cmpct.nBits;
+    outBlock.nNonce         = cmpct.nNonce;
+    outBlock.vtx.assign(nTotal, CTransaction());
+
+    std::vector<bool> vFilled(nTotal, false);
+    for (size_t i = 0; i < cmpct.vPrefilledIndex.size(); i++)
+    {
+        unsigned int idx = cmpct.vPrefilledIndex[i];
+        if (idx >= nTotal)
+            return false; // malformed
+        outBlock.vtx[idx] = cmpct.vPrefilledTx[i];
+        vFilled[idx] = true;
+    }
+
+    // Index every mempool tx by its short ID under this block's keying, so
+    // resolving each block position is a map lookup rather than a linear
+    // scan of the mempool per short ID.
+    std::map<uint64, const CTransaction*> mapShortIdToTx;
+    for (std::map<uint256, CTransaction>::const_iterator mi = mapTransactions.begin();
+         mi != mapTransactions.end(); ++mi)
+    {
+        uint64 sid = ComputeShortTxId(cmpct.hashPrevBlock, cmpct.shortIdNonce, mi->first);
+        // A short-ID collision between two distinct mempool transactions is
+        // possible (48 bits, birthday bound ~2^24 mempool entries) though
+        // very unlikely at this chain's scale; on collision, prefer keeping
+        // neither mapped rather than risk resolving to the wrong tx --
+        // that position just falls through to getblocktxn like a genuine
+        // miss, which is always correct, only occasionally not optimal.
+        if (mapShortIdToTx.count(sid))
+            mapShortIdToTx[sid] = NULL;
+        else
+            mapShortIdToTx[sid] = &mi->second;
+    }
+
+    size_t shortIdPos = 0;
+    for (size_t idx = 0; idx < nTotal; idx++)
+    {
+        if (vFilled[idx])
+            continue;
+        if (shortIdPos >= cmpct.vShortTxId.size())
+            return false; // malformed: more unfilled positions than short IDs
+        uint64 sid = cmpct.vShortTxId[shortIdPos++];
+
+        std::map<uint64, const CTransaction*>::const_iterator found = mapShortIdToTx.find(sid);
+        if (found != mapShortIdToTx.end() && found->second != NULL)
+        {
+            outBlock.vtx[idx] = *found->second;
+            vFilled[idx] = true;
+        }
+        else
+        {
+            vMissingIndex.push_back(idx);
+        }
+    }
+
+    return vMissingIndex.empty();
+}
+
+bool FillMissingAndFinish(CBlock& outBlock, const std::vector<unsigned int>& vMissingIndex,
+                           const std::vector<CTransaction>& vTxn)
+{
+    if (vMissingIndex.size() != vTxn.size())
+        return false; // peer didn't answer what was asked
+
+    for (size_t i = 0; i < vMissingIndex.size(); i++)
+    {
+        unsigned int idx = vMissingIndex[i];
+        if (idx >= outBlock.vtx.size())
+            return false; // malformed
+        outBlock.vtx[idx] = vTxn[i];
+    }
+    return true;
+}
diff --git a/src/compactblock.h b/src/compactblock.h
new file mode 100644
index 0000000..745ee3b
--- /dev/null
+++ b/src/compactblock.h
@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// Compact block relay (BIP152-style). Instead of sending a peer's full set
+// of transactions for a block they're about to receive -- almost all of
+// which they already have in their mempool from normal tx relay -- send a
+// short (48-bit, keyed-hash) ID per transaction instead. A peer that already
+// has every referenced transaction reconstructs the full block locally from
+// its mempool without any of the transaction bytes crossing the wire at
+// all; only genuinely missing transactions (typically just the coinbase)
+// need a follow-up round trip.
+//
+// Compatibility: this is purely additive. A peer that never sends
+// "sendcmpct" is never sent a compact block -- it keeps getting full
+// "block" messages exactly as before (see the getdata handler in
+// main.cpp). Old, unupgraded nodes on the live network are completely
+// unaffected; ProcessMessage's unknown-command handling means they simply
+// never see the new message types. No coordinated network upgrade needed.
+//
+// Deliberately scoped down from full BIP152: no high-bandwidth (unsolicited
+// push) mode, no differential-index encoding for prefilled transactions,
+// only the current chain tip is ever offered in compact form (an old block
+// is unlikely to still overlap much with any peer's current mempool, so the
+// bandwidth win doesn't apply -- full "block" is sent for those, same as
+// today). Only the coinbase is prefilled; every other transaction position
+// carries a short ID.
+
+#ifndef BITFLASH_COMPACTBLOCK_H
+#define BITFLASH_COMPACTBLOCK_H
+
+// Requires CBlock/CTransaction already visible -- #include "headers.h" (or
+// main.h) before this file. Deliberately doesn't include main.h itself:
+// main.h has no include guard (matches this codebase's existing headers, it
+// relies on being pulled in exactly once via headers.h), so a second
+// #include "main.h" here would break every translation unit that already
+// brought it in via headers.h first.
+#include <vector>
+
+// The compact representation of a block: header fields, a per-block nonce
+// (keys the short-ID hash so IDs can't be precomputed/ground across blocks),
+// the coinbase in full, and a 48-bit short ID for every other transaction
+// in block order.
+class CCmpctBlock
+{
+public:
+    // header
+    int          nVersion;
+    uint256      hashPrevBlock;
+    uint256      hashMerkleRoot;
+    unsigned int nTime;
+    unsigned int nBits;
+    unsigned int nNonce;
+
+    // Keys the short-ID hash for this block specifically -- chosen fresh
+    // per block (not reused from nNonce, which is public PoW data an
+    // attacker already knows and could otherwise grind against).
+    uint64 shortIdNonce;
+
+    // Sent in full. In this implementation: always exactly the coinbase,
+    // at index 0.
+    std::vector<unsigned int> vPrefilledIndex;
+    std::vector<CTransaction> vPrefilledTx;
+
+    // One short ID per NON-prefilled transaction, in ascending block-index
+    // order (i.e. the Nth entry here belongs to the Nth block position that
+    // isn't in vPrefilledIndex).
+    std::vector<uint64> vShortTxId;
+
+    IMPLEMENT_SERIALIZE
+    (
+        READWRITE(this->nVersion);
+        nVersion = this->nVersion;
+        READWRITE(hashPrevBlock);
+        READWRITE(hashMerkleRoot);
+        READWRITE(nTime);
+        READWRITE(nBits);
+        READWRITE(nNonce);
+        READWRITE(shortIdNonce);
+        READWRITE(vPrefilledIndex);
+        READWRITE(vPrefilledTx);
+        READWRITE(vShortTxId);
+    )
+
+    uint256 HeaderHash() const;
+};
+
+// Compute the 48-bit short ID for a transaction under a given block's
+// short-ID nonce. Keyed (via the block's hashPrevBlock + shortIdNonce) so
+// IDs from one block can't be precomputed before that block exists, and
+// differ block to block even for the same transaction.
+uint64 ComputeShortTxId(const uint256& hashPrevBlock, uint64 shortIdNonce, const uint256& txid);
+
+// Build the compact form of `block` (which must have vtx[0] as the
+// coinbase, as every block on this chain does).
+bool BuildCompactBlock(const CBlock& block, CCmpctBlock& out);
+
+// Attempt to reconstruct a full block from a received compact block using
+// the local mempool. On full success, returns true and fills `outBlock`.
+// On partial success (some transactions not found locally), returns false
+// and fills `vMissingIndex` with the block-position indices that still need
+// to be requested via "getblocktxn" -- outBlock is left partially built
+// (coinbase and any resolved positions filled; caller must not use it until
+// FillMissingAndFinish completes it).
+bool TryReconstructBlock(const CCmpctBlock& cmpct, CBlock& outBlock, std::vector<unsigned int>& vMissingIndex);
+
+// Complete a partially-reconstructed block (from a prior TryReconstructBlock
+// that returned false) using the transactions received in a "blocktxn"
+// response. vTxn must be in the same order as the indices this node
+// requested via "getblocktxn" for this block.
+bool FillMissingAndFinish(CBlock& outBlock, const std::vector<unsigned int>& vMissingIndex,
+                           const std::vector<CTransaction>& vTxn);
+
+#endif
diff --git a/src/db.cpp b/src/db.cpp
index 6f9461b..bf1958d 100644
--- a/src/db.cpp
+++ b/src/db.cpp
@@ -3,6 +3,7 @@
 // file license.txt or http://www.opensource.org/licenses/mit-license.php.
 
 #include "headers.h"
+#include "wallet_sqlite.h"
 
 
 
@@ -52,8 +53,34 @@ static bool fDbEnvInit = false;
 // Why LoadWallet() refused, in words meant for the person who has to act on it.
 // Empty unless the reason is one we can name.
 string strWalletLoadError;
-DbEnv dbenv(0u);
+static DbEnv* pdbenv = NULL;
+static FILE* pdbErrFile = NULL;
 static map<string, int> mapFileUseCount;
+static CWalletDBSQLite* pWalletSQLiteRuntime = NULL;
+
+DbEnv& GetDbEnv()
+{
+    if (!pdbenv)
+        pdbenv = new DbEnv(0u);
+    return *pdbenv;
+}
+
+static void CloseDbEnv()
+{
+    if (pdbenv)
+    {
+        try { pdbenv->close(0); }
+        catch (...) { }
+        delete pdbenv;
+        pdbenv = NULL;
+    }
+    if (pdbErrFile)
+    {
+        fclose(pdbErrFile);
+        pdbErrFile = NULL;
+    }
+    fDbEnvInit = false;
+}
 
 class CDBInit
 {
@@ -64,15 +91,189 @@ public:
     ~CDBInit()
     {
         if (fDbEnvInit)
-        {
-            try { dbenv.close(0); }
-            catch (...) { }
-            fDbEnvInit = false;
-        }
+            CloseDbEnv();
     }
 }
 instance_of_cdbinit;
 
+bool WalletSQLiteRuntimeActive()
+{
+    return pWalletSQLiteRuntime != NULL;
+}
+
+bool WalletSQLiteRuntimeOpen(const string& strPath, string& strErrorRet, bool fMustExist)
+{
+    strErrorRet.clear();
+    // Callers that load an existing wallet want the clear "does not exist"
+    // message rather than silently creating a blank one; the create path passes
+    // fMustExist=false so Open() (SQLITE_OPEN_CREATE) can make a fresh file.
+    if (fMustExist && !FileExists(strPath.c_str()))
+    {
+        strErrorRet = strprintf("SQLite wallet does not exist: %s",
+                                strPath.c_str());
+        return false;
+    }
+
+    WalletSQLiteRuntimeClose();
+    std::auto_ptr<CWalletDBSQLite> db(new CWalletDBSQLite());
+    if (!db->Open(strPath, strErrorRet))
+        return false;
+
+    pWalletSQLiteRuntime = db.release();
+    return true;
+}
+
+void WalletSQLiteRuntimeClose()
+{
+    if (pWalletSQLiteRuntime)
+    {
+        // Fold the write-ahead log into the main file on the way out. WAL +
+        // synchronous=FULL already makes every committed write durable across a
+        // kill, so this is housekeeping, not the thing that protects the data:
+        // if it fails, or the node is killed before it runs, the wallet is
+        // still whole. Best effort, never throws.
+        string strCheckpointError;
+        pWalletSQLiteRuntime->Checkpoint(strCheckpointError);
+        delete pWalletSQLiteRuntime;
+        pWalletSQLiteRuntime = NULL;
+    }
+}
+
+bool WalletSQLiteRuntimeReadRecord(const vector<unsigned char>& vchKey,
+                                   vector<unsigned char>& vchValueRet)
+{
+    if (!pWalletSQLiteRuntime)
+        return false;
+    string strError;
+    return pWalletSQLiteRuntime->ReadRecord(vchKey, vchValueRet, strError);
+}
+
+bool WalletSQLiteRuntimeWriteRecord(const vector<unsigned char>& vchKey,
+                                    const vector<unsigned char>& vchValue,
+                                    bool fOverwrite)
+{
+    if (!pWalletSQLiteRuntime)
+        return false;
+    string strError;
+    return pWalletSQLiteRuntime->WriteRecord(vchKey, vchValue, strError,
+                                             fOverwrite);
+}
+
+bool WalletSQLiteRuntimeEraseRecord(const vector<unsigned char>& vchKey)
+{
+    if (!pWalletSQLiteRuntime)
+        return false;
+    string strError;
+    return pWalletSQLiteRuntime->EraseRecord(vchKey, strError);
+}
+
+// Transaction bracket for the SQLite runtime. When the SQLite backend is not
+// active these are no-ops that succeed, so a caller can wrap a group of related
+// writes and Berkeley DB keeps its existing per-write behaviour unchanged while
+// SQLite gets all-or-nothing.
+bool WalletSQLiteRuntimeBeginTxn()
+{
+    if (!pWalletSQLiteRuntime)
+        return true;
+    string strError;
+    if (pWalletSQLiteRuntime->BeginTransaction(strError))
+        return true;
+    printf("WalletSQLiteRuntimeBeginTxn() : %s\n", strError.c_str());
+    return false;
+}
+
+bool WalletSQLiteRuntimeCommitTxn()
+{
+    if (!pWalletSQLiteRuntime)
+        return true;
+    string strError;
+    if (pWalletSQLiteRuntime->CommitTransaction(strError))
+        return true;
+    printf("WalletSQLiteRuntimeCommitTxn() : %s\n", strError.c_str());
+    return false;
+}
+
+void WalletSQLiteRuntimeRollbackTxn()
+{
+    if (!pWalletSQLiteRuntime)
+        return;
+    string strError;
+    pWalletSQLiteRuntime->RollbackTransaction(strError);
+}
+
+// Open the SQLite wallet read-only as the active runtime. Used by the one-shot
+// storage diagnostics, which run before the normal wallet load and must be able
+// to inspect a wallet that the loader would refuse -- so this opens the file for
+// scanning without loading or validating its records.
+bool WalletSQLiteRuntimeOpenReadOnly(const string& strPath, string& strErrorRet)
+{
+    strErrorRet.clear();
+    if (!FileExists(strPath.c_str()))
+    {
+        strErrorRet = strprintf("SQLite wallet does not exist: %s", strPath.c_str());
+        return false;
+    }
+
+    WalletSQLiteRuntimeClose();
+    std::auto_ptr<CWalletDBSQLite> db(new CWalletDBSQLite());
+    if (!db->OpenReadOnly(strPath, strErrorRet))
+        return false;
+
+    pWalletSQLiteRuntime = db.release();
+    return true;
+}
+
+bool WalletSQLiteRuntimeCheckpoint(string& strErrorRet)
+{
+    if (!pWalletSQLiteRuntime)
+    {
+        strErrorRet = "SQLite wallet backend is not active";
+        return false;
+    }
+    return pWalletSQLiteRuntime->Checkpoint(strErrorRet);
+}
+
+// The persistent record of which backend this datadir uses, so the choice
+// survives a restart without a command-line flag. A plain text file holding
+// "sqlite" or "bdb" -- visible and hand-editable on purpose, no hidden state.
+static string WalletBackendMarkerPath()
+{
+    return GetAppDir() + "/wallet-backend";
+}
+
+string ReadWalletBackendMarker()
+{
+    FILE* pf = fopen(WalletBackendMarkerPath().c_str(), "rb");
+    if (!pf)
+        return "";
+    char buf[16] = {0};
+    size_t n = fread(buf, 1, sizeof(buf) - 1, pf);
+    fclose(pf);
+    string s(buf, n);
+    while (!s.empty() && isspace((unsigned char)s[s.size() - 1]))
+        s.erase(s.size() - 1);
+    while (!s.empty() && isspace((unsigned char)s[0]))
+        s.erase(0, 1);
+    if (s == "sqlite" || s == "bdb")
+        return s;
+    return "";
+}
+
+bool WriteWalletBackendMarker(const string& strBackend)
+{
+    if (strBackend != "sqlite" && strBackend != "bdb")
+        return false;
+    FILE* pf = fopen(WalletBackendMarkerPath().c_str(), "wb");
+    if (!pf)
+        return false;
+    bool fOk = fwrite(strBackend.c_str(), 1, strBackend.size(), pf) == strBackend.size();
+    if (fputc('\n', pf) == EOF)
+        fOk = false;
+    if (fclose(pf) != 0)
+        fOk = false;
+    return fOk;
+}
+
 
 CDB::CDB(const char* pszFile, const char* pszMode, bool fTxn) : pdb(NULL)
 {
@@ -104,24 +305,30 @@ CDB::CDB(const char* pszFile, const char* pszMode, bool fTxn) : pdb(NULL)
 
             printf("dbenv.open strAppDir=%s\n", strAppDir.c_str());
 
-            dbenv.set_lg_dir(strLogDir.c_str());
-            dbenv.set_lg_max(10000000);
-            dbenv.set_lk_max_locks(10000);
-            dbenv.set_lk_max_objects(10000);
-            dbenv.set_errfile(fopen("db.log", "a")); /// debug
-            ///dbenv.log_set_config(DB_LOG_AUTO_REMOVE, 1); /// causes corruption
-            ret = dbenv.open(strAppDir.c_str(),
-                             DB_CREATE     |
-                             DB_INIT_LOCK  |
-                             DB_INIT_LOG   |
-                             DB_INIT_MPOOL |
-                             DB_INIT_TXN   |
-                             DB_THREAD     |
-                             DB_PRIVATE    |
-                             DB_RECOVER,
-                             0);
+            DbEnv& env = GetDbEnv();
+            env.set_lg_dir(strLogDir.c_str());
+            env.set_lg_max(10000000);
+            env.set_lk_max_locks(10000);
+            env.set_lk_max_objects(10000);
+            pdbErrFile = fopen("db.log", "a"); /// debug
+            if (pdbErrFile)
+                env.set_errfile(pdbErrFile);
+            ///env.log_set_config(DB_LOG_AUTO_REMOVE, 1); /// causes corruption
+            ret = env.open(strAppDir.c_str(),
+                           DB_CREATE     |
+                           DB_INIT_LOCK  |
+                           DB_INIT_LOG   |
+                           DB_INIT_MPOOL |
+                           DB_INIT_TXN   |
+                           DB_THREAD     |
+                           DB_PRIVATE    |
+                           DB_RECOVER,
+                           0);
             if (ret > 0)
+            {
+                CloseDbEnv();
                 throw runtime_error(strprintf("CDB() : error %d opening database environment\n", ret));
+            }
             fDbEnvInit = true;
 
             // A Berkeley DB file records, in every page header, a log sequence
@@ -151,7 +358,7 @@ CDB::CDB(const char* pszFile, const char* pszMode, bool fTxn) : pdb(NULL)
                         continue;
                     try
                     {
-                        if (dbenv.lsn_reset(pszName, 0) == 0)
+                        if (env.lsn_reset(pszName, 0) == 0)
                             printf("CDB() : adopted %s from another environment "
                                    "(log sequence numbers reset)\n", pszName);
                     }
@@ -164,7 +371,7 @@ CDB::CDB(const char* pszFile, const char* pszMode, bool fTxn) : pdb(NULL)
         ++mapFileUseCount[strFile];
     }
 
-    pdb = new Db(&dbenv, 0);
+    pdb = new Db(&GetDbEnv(), 0);
 
     ret = pdb->open(NULL,      // Txn pointer
                     pszFile,   // Filename
@@ -199,7 +406,8 @@ void CDB::Close()
     try { pdb->close(0); } catch (...) { }
     delete pdb;
     pdb = NULL;
-    try { dbenv.txn_checkpoint(0, 0, 0); } catch (...) { }
+    if (fDbEnvInit)
+        try { GetDbEnv().txn_checkpoint(0, 0, 0); } catch (...) { }
 
     CRITICAL_BLOCK(cs_db)
         --mapFileUseCount[strFile];
@@ -279,7 +487,8 @@ void DBFlush(bool fShutdown)
         // takes the process down before the wallet has been put down cleanly,
         // which is the difference between a portable wallet.dat and one welded
         // to this directory -- the lsn_reset just below is what frees it.
-        try { dbenv.txn_checkpoint(0, 0, 0); }
+        DbEnv& env = GetDbEnv();
+        try { env.txn_checkpoint(0, 0, 0); }
         catch (const std::exception& e)
         { printf("DBFlush() : checkpoint failed: %s\n", e.what()); }
 
@@ -290,7 +499,7 @@ void DBFlush(bool fShutdown)
             int nRefCount = (*mi).second;
             if (nRefCount == 0)
             {
-                try { dbenv.lsn_reset(strFile.c_str(), 0); }
+                try { env.lsn_reset(strFile.c_str(), 0); }
                 catch (const std::exception& e)
                 { printf("DBFlush() : lsn_reset(%s) failed: %s\n", strFile.c_str(), e.what()); }
                 mapFileUseCount.erase(mi++);
@@ -310,9 +519,8 @@ void DBFlush(bool fShutdown)
             // Found while making wallet encryption clean up after itself:
             // calling DBFlush(true) a second time crashed here every time.
             if (mapFileUseCount.empty())
-                try { dbenv.log_archive(NULL, DB_ARCH_REMOVE); } catch (...) { }
-            try { dbenv.close(0); } catch (...) { }
-            fDbEnvInit = false;
+                try { env.log_archive(NULL, DB_ARCH_REMOVE); } catch (...) { }
+            CloseDbEnv();
         }
     }
 }
@@ -614,6 +822,294 @@ bool CTxDB::LoadBlockIndex()
 // CWalletDB
 //
 
+CWalletDB::CWalletDB(const char* pszMode, bool fTxn) :
+    CDB(WalletSQLiteRuntimeActive() ? NULL : "wallet.dat", pszMode, fTxn)
+{
+}
+
+class CSQLiteWalletRuntimeLoadVisitor : public CWalletRecordVisitor
+{
+public:
+    bool fHaveStoredMineMode;
+    bool fHaveStoredHDCoinType;
+    string strLastType;
+
+    CSQLiteWalletRuntimeLoadVisitor() :
+        fHaveStoredMineMode(false),
+        fHaveStoredHDCoinType(false)
+    {
+    }
+
+    bool VisitWalletRecord(const CDataStream& ssKeyIn,
+                           const CDataStream& ssValueIn,
+                           string& strErrorRet)
+    {
+        CDataStream ssKey = ssKeyIn;
+        CDataStream ssValue = ssValueIn;
+        string strType;
+        ssKey >> strType;
+        strLastType = strType;
+
+        if (strType == "name")
+        {
+            string strAddress;
+            ssKey >> strAddress;
+            ssValue >> mapAddressBook[strAddress];
+        }
+        else if (strType == "tx")
+        {
+            uint256 hash;
+            ssKey >> hash;
+            CWalletTx& wtx = mapWallet[hash];
+            ssValue >> wtx;
+
+            if (wtx.GetHash() != hash)
+                printf("Error in SQLite wallet export, hash mismatch\n");
+        }
+        else if (strType == "key")
+        {
+            vector<unsigned char> vchPubKey;
+            ssKey >> vchPubKey;
+            CPrivKey vchPrivKey;
+            ssValue >> vchPrivKey;
+
+            mapKeys[vchPubKey] = vchPrivKey;
+            mapPubKeys[Hash160(vchPubKey)] = vchPubKey;
+        }
+        else if (strType == "mkey")
+        {
+            unsigned int nID = 0;
+            ssKey >> nID;
+            CWalletMasterKey kMasterKey;
+            ssValue >> kMasterKey;
+            mapMasterKeys[nID] = kMasterKey;
+            nWalletMasterKeyMaxID = max(nWalletMasterKeyMaxID, nID);
+            fWalletEncrypted = true;
+            fWalletLocked = true;
+        }
+        else if (strType == "ckey")
+        {
+            vector<unsigned char> vchPubKey;
+            ssKey >> vchPubKey;
+            vector<unsigned char> vchCryptedSecret;
+            ssValue >> vchCryptedSecret;
+            if (!AddCryptedKey(vchPubKey, vchCryptedSecret))
+            {
+                strErrorRet = "SQLite wallet export has an unreadable encrypted key record";
+                return false;
+            }
+        }
+        else if (strType == "defaultkey")
+        {
+            ssValue >> vchDefaultKey;
+        }
+        else if (strType == "hdmaster")
+        {
+            ssValue >> vchHDMaster;
+        }
+        else if (strType == "hdchaincode")
+        {
+            ssValue >> vchHDChainCode;
+        }
+        else if (strType == "hdnext")
+        {
+            ssValue >> nHDNext;
+        }
+        else if (strType == "hdschema")
+        {
+            ssValue >> nHDKeySchema;
+        }
+        else if (strType == "hdcointype")
+        {
+            ssValue >> nHDCoinType;
+            fHaveStoredHDCoinType = true;
+        }
+        else if (strType == "hdreceivenext")
+        {
+            ssValue >> nHDReceiveNext;
+        }
+        else if (strType == "hdchangenext")
+        {
+            ssValue >> nHDChangeNext;
+        }
+        else if (strType == "cryptedhdmaster")
+        {
+            ssValue >> vchCryptedHDMaster;
+            fWalletEncrypted = true;
+            fWalletLocked = true;
+        }
+        else if (strType == "cryptedhdchaincode")
+        {
+            ssValue >> vchCryptedHDChainCode;
+            fWalletEncrypted = true;
+            fWalletLocked = true;
+        }
+        else if (strType == "walletminversion")
+        {
+            int nMinVersion = 0;
+            ssValue >> nMinVersion;
+            if (nMinVersion > WALLET_FORMAT_SUPPORTED)
+            {
+                strWalletLoadError = strprintf(
+                    "This SQLite wallet export was written by a newer version of "
+                    "Bitflash (wallet format %d; this build understands %d). "
+                    "Upgrade Bitflash before opening it.",
+                    nMinVersion, WALLET_FORMAT_SUPPORTED);
+                strErrorRet = strWalletLoadError;
+                return false;
+            }
+        }
+        else if (strType == "pool")
+        {
+            int64 nIndex;
+            ssKey >> nIndex;
+            vector<unsigned char> vchPubKey;
+            ssValue >> vchPubKey;
+            mapKeyPool[nIndex] = vchPubKey;
+        }
+        else if (strType == "setting")
+        {
+            string strKey;
+            ssKey >> strKey;
+            if (strKey == "nTransactionFee")    ssValue >> nTransactionFee;
+            if (strKey == "addrIncoming")       ssValue >> addrIncoming;
+
+            if (!fMineModeFromCommandLine)
+            {
+                if (strKey == "nMineMode")          { ssValue >> nMineMode; fHaveStoredMineMode = true; }
+                if (strKey == "fGenerateBitcoins")  ssValue >> fGenerateBitcoins;
+                if (strKey == "strParticipantPool") ssValue >> strParticipantPool;
+            }
+        }
+
+        if (ssKey.fail())
+        {
+            strErrorRet = strprintf("malformed SQLite wallet record key while handling '%s'",
+                                    strLastType.c_str());
+            return false;
+        }
+        if (ssValue.fail())
+        {
+            strErrorRet = strprintf("malformed SQLite wallet record value while handling '%s'",
+                                    strLastType.c_str());
+            return false;
+        }
+        return true;
+    }
+
+    vector<unsigned char> vchDefaultKey;
+};
+
+static bool FinishLoadedWallet(const vector<unsigned char>& vchDefaultKey,
+                               bool fMayCreateDefaultKey)
+{
+    if (!vchDefaultKey.empty() && mapPubKeys.count(Hash160(vchDefaultKey)))
+    {
+        keyUser.SetPubKey(vchDefaultKey);
+        if (mapKeys.count(vchDefaultKey))
+            keyUser.SetPrivKey(mapKeys[vchDefaultKey]);
+    }
+    else if (IsWalletEncrypted())
+    {
+        printf("LoadWallet: encrypted wallet has no usable default public key. "
+               "The file was left untouched.\n");
+        return false;
+    }
+    else
+    {
+        if (!fMayCreateDefaultKey)
+        {
+            strWalletLoadError =
+                "SQLite wallet export has no usable default public key";
+            printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+            return false;
+        }
+
+        keyUser.MakeNewKey();
+        if (!AddKey(keyUser))
+            return false;
+        if (!SetAddressBookName(PubKeyToAddress(keyUser.GetPubKey()), "Your Address"))
+            return false;
+        CWalletDB().WriteDefaultKey(keyUser.GetPubKey());
+    }
+
+    return true;
+}
+
+static bool ReconcileLoadedWalletMetadata(bool fHaveStoredMineMode,
+                                          bool fHaveStoredHDCoinType)
+{
+    // An encrypted wallet has a seed; it just has not been decrypted yet.
+    //
+    // The reset in the else branch was written when "no seed in memory after
+    // loading" could only mean "this wallet has no seed". With encryption that
+    // is no longer true, and taking the else branch here wiped the schema and
+    // the derivation counters that had just been read correctly out of the
+    // file. Unlocking later restores the seed but nothing restores those, so a
+    // BIP44 wallet came back deriving legacy addresses -- different addresses
+    // from the ones its own recovery phrase produces, while the audit reported
+    // the phrase as covering nothing.
+    if (HaveHDSeed() || !vchCryptedHDMaster.empty())
+    {
+        if (nHDKeySchema == HD_SCHEMA_NONE)
+        {
+            nHDKeySchema = HD_SCHEMA_LEGACY;
+            printf("LoadWallet: deterministic seed has no schema metadata; "
+                   "treating it as legacy m/index'\n");
+        }
+        else if (nHDKeySchema != HD_SCHEMA_LEGACY &&
+                 nHDKeySchema != HD_SCHEMA_BIP44)
+        {
+            printf("LoadWallet: deterministic wallet schema %d (%s) is not "
+                   "supported by this build\n",
+                   nHDKeySchema, HDKeySchemaName(nHDKeySchema).c_str());
+            return false;
+        }
+        if (!fHaveStoredHDCoinType)
+        {
+            nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH;
+            printf("LoadWallet: deterministic seed has no BIP44 coin type metadata; "
+                   "using Bitflash coin type %u\n", nHDCoinType);
+        }
+    }
+    else
+    {
+        nHDKeySchema = HD_SCHEMA_NONE;
+        nHDNext = 0;
+        nHDReceiveNext = 0;
+        nHDChangeNext = 0;
+        nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH;
+    }
+
+    // fGenerateBitcoins and nMineMode only mean anything together, and a
+    // wallet.dat can easily hold one without the other: Bitcoin 0.1.0 already
+    // wrote fGenerateBitcoins when mining was toggled, years before this fork
+    // had a mode at all. Restoring that lone flag put a node into the one state
+    // the miner cannot act on -- generate on, mode relay -- so every miner
+    // thread started and returned at the relay guard, and the machine sat there
+    // looking like it was mining while hashing nothing. That happened to a
+    // 32-core node on the first 1.2.11 start.
+    //
+    // So the flag is only believed when the mode it belongs to was stored with
+    // it, and the pair is made coherent either way.
+    if (!fMineModeFromCommandLine)
+    {
+        if (!fHaveStoredMineMode)
+        {
+            if (fGenerateBitcoins)
+                printf("LoadWallet: ignoring a stored fGenerateBitcoins with no mining mode "
+                       "beside it -- it predates this setting and cannot be read on its own\n");
+            fGenerateBitcoins = 0;
+        }
+        else
+        {
+            fGenerateBitcoins = (nMineMode != MINE_RELAY) ? 1 : 0;
+        }
+    }
+
+    return true;
+}
+
 bool CWalletDB::LoadWallet(vector<unsigned char>& vchDefaultKeyRet)
 {
     // Whether wallet.dat actually carried a mining mode, as opposed to just the
@@ -872,9 +1368,9 @@ bool CWalletDB::LoadWallet(vector<unsigned char>& vchDefaultKeyRet)
         }
         if (!fHaveStoredHDCoinType)
         {
-            nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL;
+            nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH;
             printf("LoadWallet: deterministic seed has no BIP44 coin type metadata; "
-                   "using provisional Bitflash coin type %u\n", nHDCoinType);
+                   "using Bitflash coin type %u\n", nHDCoinType);
         }
     }
     else
@@ -883,7 +1379,7 @@ bool CWalletDB::LoadWallet(vector<unsigned char>& vchDefaultKeyRet)
         nHDNext = 0;
         nHDReceiveNext = 0;
         nHDChangeNext = 0;
-        nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL;
+        nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH;
     }
 
     // fGenerateBitcoins and nMineMode only mean anything together, and a
@@ -924,34 +1420,269 @@ bool CWalletDB::LoadWallet(vector<unsigned char>& vchDefaultKeyRet)
     return true;
 }
 
+bool ScanWalletRecords(CWalletRecordVisitor& visitor, string& strErrorRet)
+{
+    // Under the SQLite backend there is no Berkeley DB cursor to walk; scan the
+    // active SQLite store instead. This is the single choke point every "read
+    // every wallet record" caller goes through (storage audit and check among
+    // them), so routing it here makes those honour -walletbackend=sqlite.
+    if (WalletSQLiteRuntimeActive())
+    {
+        strErrorRet.clear();
+        return pWalletSQLiteRuntime->ScanRecords(visitor, strErrorRet);
+    }
+
+    class CWalletScanDB : public CWalletDB
+    {
+    public:
+        CWalletScanDB() : CWalletDB("r") { }
+        using CDB::GetCursor;
+        using CDB::ReadAtCursor;
+    };
+
+    strErrorRet.clear();
+    CWalletScanDB dbWallet;
+    Dbc* pcursor = dbWallet.GetCursor();
+    if (!pcursor)
+    {
+        strErrorRet = "could not open a wallet cursor";
+        return false;
+    }
+    CAutoCursor cursorGuard(pcursor);
+
+    loop
+    {
+        CDataStream ssKey(SER_DISK);
+        CDataStream ssValue(SER_DISK);
+        int ret = dbWallet.ReadAtCursor(pcursor, ssKey, ssValue);
+        if (ret == DB_NOTFOUND)
+            break;
+        if (ret != 0)
+        {
+            strErrorRet = strprintf("could not read wallet record: Berkeley DB error %d", ret);
+            return false;
+        }
+        if (!visitor.VisitWalletRecord(ssKey, ssValue, strErrorRet))
+            return false;
+    }
+
+    return true;
+}
+
 bool LoadWallet()
 {
     vector<unsigned char> vchDefaultKey;
     if (!CWalletDB("cr").LoadWallet(vchDefaultKey))
         return false;
 
-    if (!vchDefaultKey.empty() && mapPubKeys.count(Hash160(vchDefaultKey)))
+    return FinishLoadedWallet(vchDefaultKey, true);
+}
+
+bool LoadWalletFromSQLite(const string& strPath)
+{
+    strWalletLoadError.clear();
+
+    if (!FileExists(strPath.c_str()))
     {
-        // Set keyUser
-        keyUser.SetPubKey(vchDefaultKey);
-        if (mapKeys.count(vchDefaultKey))
-            keyUser.SetPrivKey(mapKeys[vchDefaultKey]);
+        strWalletLoadError = strprintf("SQLite wallet export does not exist: %s",
+                                       strPath.c_str());
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
     }
-    else if (IsWalletEncrypted())
+
+    CWalletDBSQLite sqlite;
+    string strError;
+    if (!sqlite.OpenReadOnly(strPath, strError))
     {
-        printf("LoadWallet: encrypted wallet has no usable default public key. "
-               "The file was left untouched.\n");
+        strWalletLoadError = strError;
+        printf("LoadWallet: cannot open SQLite wallet export: %s\n",
+               strError.c_str());
         return false;
     }
-    else
+
+    CSQLiteWalletRuntimeLoadVisitor visitor;
+    try
     {
-        // Create new keyUser and set as default key
-        keyUser.MakeNewKey();
-        if (!AddKey(keyUser))
-            return false;
-        if (!SetAddressBookName(PubKeyToAddress(keyUser.GetPubKey()), "Your Address"))
-            return false;
-        CWalletDB().WriteDefaultKey(keyUser.GetPubKey());
+        CRITICAL_BLOCK(cs_mapKeys)
+        CRITICAL_BLOCK(cs_mapWallet)
+        {
+            if (!sqlite.ScanRecords(visitor, strError))
+            {
+                if (strWalletLoadError.empty())
+                    strWalletLoadError = strError;
+                printf("LoadWallet: SQLite wallet export could not be read. "
+                       "Failed while handling a '%s' record: %s\n",
+                       visitor.strLastType.c_str(), strError.c_str());
+                return false;
+            }
+        }
+    }
+    catch (const std::exception& e)
+    {
+        strWalletLoadError = strprintf(
+            "SQLite wallet export could not be read while handling a '%s' record: %s",
+            visitor.strLastType.c_str(), e.what());
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+    catch (...)
+    {
+        strWalletLoadError = strprintf(
+            "SQLite wallet export could not be read while handling a '%s' record",
+            visitor.strLastType.c_str());
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+
+    if (!ReconcileLoadedWalletMetadata(visitor.fHaveStoredMineMode,
+                                       visitor.fHaveStoredHDCoinType))
+    {
+        if (strWalletLoadError.empty())
+            strWalletLoadError = "SQLite wallet metadata is not supported by this build";
+        return false;
+    }
+
+    return FinishLoadedWallet(visitor.vchDefaultKey, false);
+}
+
+// Open a SQLite wallet read-write and keep it open as the active runtime
+// backend, then load its records into memory the same way LoadWalletFromSQLite
+// does. Unlike the read-only staging path, this leaves pWalletSQLiteRuntime set
+// so every later CWalletDB read/write/erase routes to this file for the life of
+// the process. The Berkeley DB wallet.dat is never opened.
+bool LoadWalletFromSQLiteRuntime(const string& strPath)
+{
+    strWalletLoadError.clear();
+
+    if (!FileExists(strPath.c_str()))
+    {
+        strWalletLoadError = strprintf("SQLite wallet does not exist: %s",
+                                       strPath.c_str());
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+
+    string strError;
+    if (!WalletSQLiteRuntimeOpen(strPath, strError))
+    {
+        strWalletLoadError = strError;
+        printf("LoadWallet: cannot open SQLite wallet backend: %s\n",
+               strError.c_str());
+        return false;
+    }
+
+    CSQLiteWalletRuntimeLoadVisitor visitor;
+    try
+    {
+        CRITICAL_BLOCK(cs_mapKeys)
+        CRITICAL_BLOCK(cs_mapWallet)
+        {
+            if (!pWalletSQLiteRuntime->ScanRecords(visitor, strError))
+            {
+                WalletSQLiteRuntimeClose();
+                if (strWalletLoadError.empty())
+                    strWalletLoadError = strError;
+                printf("LoadWallet: SQLite wallet backend could not be read. "
+                       "Failed while handling a '%s' record: %s\n",
+                       visitor.strLastType.c_str(), strError.c_str());
+                return false;
+            }
+        }
+    }
+    catch (const std::exception& e)
+    {
+        WalletSQLiteRuntimeClose();
+        strWalletLoadError = strprintf(
+            "SQLite wallet backend could not be read while handling a '%s' record: %s",
+            visitor.strLastType.c_str(), e.what());
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+    catch (...)
+    {
+        WalletSQLiteRuntimeClose();
+        strWalletLoadError = strprintf(
+            "SQLite wallet backend could not be read while handling a '%s' record",
+            visitor.strLastType.c_str());
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+
+    // Refuse an empty or non-wallet SQLite file up front, with a message that
+    // names the likely cause. FinishLoadedWallet below already rejects a
+    // missing default key (it is the fMayCreateDefaultKey=false path), but its
+    // wording -- "no usable default public key" -- reads as corruption when the
+    // real story is usually "this file was never an exported wallet". A blank
+    // wallet.sqlite left by a typo or a half-run export should say so.
+    if (visitor.vchDefaultKey.empty())
+    {
+        WalletSQLiteRuntimeClose();
+        strWalletLoadError =
+            "SQLite wallet has no default key record; it may be empty or not a "
+            "wallet export. Create it with -walletsqliteexport.";
+        printf("LoadWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+
+    if (!ReconcileLoadedWalletMetadata(visitor.fHaveStoredMineMode,
+                                       visitor.fHaveStoredHDCoinType))
+    {
+        WalletSQLiteRuntimeClose();
+        if (strWalletLoadError.empty())
+            strWalletLoadError = "SQLite wallet metadata is not supported by this build";
+        return false;
+    }
+
+    // Never fabricate a default key: an export always carries one, and a file
+    // that does not is refused with the wallet left open to no writes rather
+    // than quietly minted into a new identity.
+    if (!FinishLoadedWallet(visitor.vchDefaultKey, false))
+    {
+        WalletSQLiteRuntimeClose();
+        return false;
+    }
+
+    return true;
+}
+
+// Create a brand-new wallet directly in the SQLite backend. For a fresh install
+// where SQLite is the default there is no wallet.dat to export from, so open a
+// new wallet.sqlite (Open() creates the file and its schema) and let
+// FinishLoadedWallet mint the first default key straight into it -- the same
+// call the Berkeley DB create path uses, so a new wallet is identical either
+// way. Refuses to touch an existing file, and cleans up on failure so a broken
+// half-initialised wallet.sqlite is never left for the next start to load.
+bool CreateNewSQLiteWallet(const string& strPath)
+{
+    strWalletLoadError.clear();
+
+    if (FileExists(strPath.c_str()))
+    {
+        strWalletLoadError = strprintf("SQLite wallet already exists: %s",
+                                       strPath.c_str());
+        printf("CreateNewSQLiteWallet: %s\n", strWalletLoadError.c_str());
+        return false;
+    }
+
+    string strError;
+    if (!WalletSQLiteRuntimeOpen(strPath, strError, false))
+    {
+        strWalletLoadError = strError;
+        printf("CreateNewSQLiteWallet: cannot create SQLite wallet: %s\n",
+               strError.c_str());
+        return false;
+    }
+
+    vector<unsigned char> vchNoDefaultKey;
+    if (!FinishLoadedWallet(vchNoDefaultKey, true))
+    {
+        WalletSQLiteRuntimeClose();
+        remove(strPath.c_str());
+        remove((strPath + "-wal").c_str());
+        remove((strPath + "-shm").c_str());
+        if (strWalletLoadError.empty())
+            strWalletLoadError = "could not initialise the new SQLite wallet";
+        return false;
     }
 
     return true;
@@ -974,21 +1705,99 @@ bool LoadWallet()
 // this file was written are not spendable from it. Backing up once is not
 // enough, and that is a property of the wallet format rather than of this
 // function.
+// Back up the active SQLite wallet. The store is checkpointed so the WAL is
+// folded into the main file, then the single self-contained wallet.sqlite is
+// copied through a temp file and renamed into place (same temp/old/rename dance
+// as the Berkeley DB path, for Windows' non-overwriting rename). No lsn_reset:
+// a checkpointed SQLite file needs nothing beside it to open.
+static bool BackupWalletSQLite(const string& strDest)
+{
+    string strSrc = GetAppDir() + "/wallet.sqlite";
+    if (!FileExists(strSrc.c_str()))
+        return error("BackupWallet() : %s does not exist\n", strSrc.c_str());
+
+    string strCheckpointError;
+    if (!WalletSQLiteRuntimeCheckpoint(strCheckpointError))
+        return error("BackupWallet() : checkpoint failed: %s\n", strCheckpointError.c_str());
+
+    string strTemp = strprintf("%s.tmp.%lld", strDest.c_str(), GetTime());
+    for (int i = 1; FileExists(strTemp.c_str()); i++)
+        strTemp = strprintf("%s.tmp.%lld.%d", strDest.c_str(), GetTime(), i);
+    string strOld = strprintf("%s.old.%lld", strDest.c_str(), GetTime());
+    for (int i = 1; FileExists(strOld.c_str()); i++)
+        strOld = strprintf("%s.old.%lld.%d", strDest.c_str(), GetTime(), i);
+
+    FILE* pfIn = fopen(strSrc.c_str(), "rb");
+    if (!pfIn)
+        return error("BackupWallet() : cannot read %s\n", strSrc.c_str());
+    FILE* pfOut = fopen(strTemp.c_str(), "wb");
+    if (!pfOut)
+    {
+        fclose(pfIn);
+        return error("BackupWallet() : cannot write %s\n", strTemp.c_str());
+    }
+
+    char buf[65536];
+    size_t n;
+    bool fOk = true;
+    while ((n = fread(buf, 1, sizeof(buf), pfIn)) > 0)
+        if (fwrite(buf, 1, n, pfOut) != n) { fOk = false; break; }
+    if (ferror(pfIn))
+        fOk = false;
+    fclose(pfIn);
+    if (fclose(pfOut) != 0)
+        fOk = false;
+    if (!fOk)
+    {
+        remove(strTemp.c_str());   // half a wallet is worse than none
+        return error("BackupWallet() : copy to %s failed\n", strTemp.c_str());
+    }
+
+    bool fHadOldDest = FileExists(strDest.c_str());
+    if (fHadOldDest && rename(strDest.c_str(), strOld.c_str()) != 0)
+    {
+        remove(strTemp.c_str());
+        return error("BackupWallet() : could not move old %s aside\n", strDest.c_str());
+    }
+    if (rename(strTemp.c_str(), strDest.c_str()) != 0)
+    {
+        remove(strTemp.c_str());
+        if (fHadOldDest)
+            rename(strOld.c_str(), strDest.c_str());
+        return error("BackupWallet() : could not install %s\n", strDest.c_str());
+    }
+    if (fHadOldDest)
+        remove(strOld.c_str());
+    return true;
+}
+
 bool BackupWallet(const string& strDest)
 {
     if (strDest.empty())
         return error("BackupWallet() : no destination given\n");
 
+    // Under the SQLite backend the live wallet is wallet.sqlite, not wallet.dat.
+    if (WalletSQLiteRuntimeActive())
+        return BackupWalletSQLite(strDest);
+
     string strSrc = GetAppDir() + "/wallet.dat";
     if (!FileExists(strSrc.c_str()))
         return error("BackupWallet() : %s does not exist\n", strSrc.c_str());
 
+    string strTemp = strprintf("%s.tmp.%lld", strDest.c_str(), GetTime());
+    for (int i = 1; FileExists(strTemp.c_str()); i++)
+        strTemp = strprintf("%s.tmp.%lld.%d", strDest.c_str(), GetTime(), i);
+    string strOld = strprintf("%s.old.%lld", strDest.c_str(), GetTime());
+    for (int i = 1; FileExists(strOld.c_str()); i++)
+        strOld = strprintf("%s.old.%lld.%d", strDest.c_str(), GetTime(), i);
+
     CRITICAL_BLOCK(cs_db)
     {
         // Committing first, so the copy is not missing the newest records.
         // Both calls can throw, and a failed backup must not take the node
         // down with it.
-        try { dbenv.txn_checkpoint(0, 0, 0); }
+        DbEnv& env = GetDbEnv();
+        try { env.txn_checkpoint(0, 0, 0); }
         catch (const std::exception& e)
         { return error("BackupWallet() : checkpoint failed: %s\n", e.what()); }
 
@@ -997,11 +1806,11 @@ bool BackupWallet(const string& strDest)
             FILE* pfIn = fopen(strSrc.c_str(), "rb");
             if (!pfIn)
                 return error("BackupWallet() : cannot read %s\n", strSrc.c_str());
-            FILE* pfOut = fopen(strDest.c_str(), "wb");
+            FILE* pfOut = fopen(strTemp.c_str(), "wb");
             if (!pfOut)
             {
                 fclose(pfIn);
-                return error("BackupWallet() : cannot write %s\n", strDest.c_str());
+                return error("BackupWallet() : cannot write %s\n", strTemp.c_str());
             }
 
             char buf[65536];
@@ -1018,18 +1827,39 @@ bool BackupWallet(const string& strDest)
 
             if (!fOk)
             {
-                remove(strDest.c_str());   // half a wallet is worse than none
-                return error("BackupWallet() : copy to %s failed\n", strDest.c_str());
+                remove(strTemp.c_str());   // half a wallet is worse than none
+                return error("BackupWallet() : copy to %s failed\n", strTemp.c_str());
             }
 
             // Without this the copy is welded to this node's database/ dir.
-            int ret = dbenv.lsn_reset(strDest.c_str(), 0);
+            int ret = env.lsn_reset(strTemp.c_str(), 0);
             if (ret != 0)
                 printf("BackupWallet() : warning -- lsn_reset returned %d; the copy "
                        "may only open beside this node's database/ directory\n", ret);
+
+            bool fHadOldDest = FileExists(strDest.c_str());
+            if (fHadOldDest && rename(strDest.c_str(), strOld.c_str()) != 0)
+            {
+                remove(strTemp.c_str());
+                return error("BackupWallet() : could not move old %s aside\n", strDest.c_str());
+            }
+            if (rename(strTemp.c_str(), strDest.c_str()) != 0)
+            {
+                remove(strTemp.c_str());
+                if (fHadOldDest)
+                    rename(strOld.c_str(), strDest.c_str());
+                return error("BackupWallet() : could not install %s\n", strDest.c_str());
+            }
+            if (fHadOldDest)
+                remove(strOld.c_str());
         }
         catch (const std::exception& e)
-        { return error("BackupWallet() : %s\n", e.what()); }
+        {
+            remove(strTemp.c_str());
+            if (FileExists(strOld.c_str()) && !FileExists(strDest.c_str()))
+                rename(strOld.c_str(), strDest.c_str());
+            return error("BackupWallet() : %s\n", e.what());
+        }
     }
 
     // Recorded here rather than by whoever called, so that a backup taken with
@@ -1307,73 +2137,71 @@ public:
     {
         return Write(make_pair(string("pool"), nIndex), vchPubKey);
     }
+};
 
-    bool CopyPublicRecordsTo(CWalletRewriteDB& dbTo, int& nCopiedRet, string& strErrorRet)
+static bool IsWalletEncryptionPrivateRecord(const string& strType)
+{
+    return strType == "key" ||
+           strType == "pool" ||
+           strType == "hdmaster" ||
+           strType == "hdchaincode" ||
+           strType == "mkey" ||
+           strType == "ckey" ||
+           strType == "cryptedhdmaster" ||
+           strType == "cryptedhdchaincode" ||
+           strType == "walletminversion";
+}
+
+class CWalletPublicRecordCopyVisitor : public CWalletRecordVisitor
+{
+public:
+    CWalletRewriteDB& dbTo;
+    int& nCopied;
+
+    CWalletPublicRecordCopyVisitor(CWalletRewriteDB& dbToIn, int& nCopiedIn)
+        : dbTo(dbToIn), nCopied(nCopiedIn) { }
+
+    bool VisitWalletRecord(const CDataStream& ssKey,
+                           const CDataStream& ssValue,
+                           string& strErrorRet)
     {
-        nCopiedRet = 0;
-        Dbc* pcursor = GetCursor();
-        if (!pcursor)
+        string strType;
+        try
         {
-            strErrorRet = "could not open a wallet cursor";
-            return false;
+            CDataStream ssType = ssKey;
+            ssType >> strType;
         }
-
-        unsigned int fFlags = DB_NEXT;
-        loop
+        catch (...)
         {
-            CDataStream ssKey;
-            CDataStream ssValue;
-            int ret = ReadAtCursor(pcursor, ssKey, ssValue, fFlags);
-            if (ret == DB_NOTFOUND)
-                break;
-            if (ret != 0)
-            {
-                pcursor->close();
-                strErrorRet = strprintf("could not read wallet record: Berkeley DB error %d", ret);
-                return false;
-            }
-
-            string strType;
-            try
-            {
-                CDataStream ssType = ssKey;
-                ssType >> strType;
-            }
-            catch (...)
-            {
-                pcursor->close();
-                strErrorRet = "wallet.dat has a record whose key type cannot be read";
-                return false;
-            }
+            strErrorRet = "wallet.dat has a record whose key type cannot be read";
+            return false;
+        }
 
-            if (strType == "key" ||
-                strType == "pool" ||
-                strType == "hdmaster" ||
-                strType == "hdchaincode" ||
-                strType == "mkey" ||
-                strType == "ckey" ||
-                strType == "cryptedhdmaster" ||
-                strType == "cryptedhdchaincode" ||
-                strType == "walletminversion")
-                continue;
+        if (IsWalletEncryptionPrivateRecord(strType))
+            return true;
 
-            if (!dbTo.WriteRaw(ssKey, ssValue))
-            {
-                pcursor->close();
-                strErrorRet = strprintf("could not copy wallet record '%s'", strType.c_str());
-                return false;
-            }
-            nCopiedRet++;
+        if (!dbTo.WriteRaw(ssKey, ssValue))
+        {
+            strErrorRet = strprintf("could not copy wallet record '%s'", strType.c_str());
+            return false;
         }
-
-        pcursor->close();
+        nCopied++;
         return true;
     }
 };
 
-static string WalletEncryptBackupPath()
+static bool CopyPublicWalletRecordsTo(CWalletRewriteDB& dbTo,
+                                      int& nCopiedRet,
+                                      string& strErrorRet)
 {
-    string strBase = GetAppDir() + "/wallet.dat.before-encrypt.";
+    nCopiedRet = 0;
+    CWalletPublicRecordCopyVisitor visitor(dbTo, nCopiedRet);
+    return ScanWalletRecords(visitor, strErrorRet);
+}
+
+static string WalletEncryptBackupPathFor(const char* pszBaseName)
+{
+    string strBase = GetAppDir() + "/" + pszBaseName + ".before-encrypt.";
     string strPath = strBase + i64tostr(GetTime()) + ".bak";
     for (int i = 1; FileExists(strPath.c_str()); i++)
         strPath = strBase + i64tostr(GetTime()) + "." + itostr(i) + ".bak";
@@ -1396,6 +2224,199 @@ static bool EncryptPrivateKeyForWallet(const CKeyingMaterial& vchMasterKey,
     return true;
 }
 
+static void SecureClearBytes(vector<unsigned char>& vch)
+{
+    if (!vch.empty())
+        OPENSSL_cleanse(&vch[0], vch.size());
+    vch.clear();
+}
+
+// The SQLite counterpart of CWalletPublicRecordCopyVisitor: same skip list,
+// same byte-for-byte copy, but the destination is a CWalletDBSQLite record
+// store rather than a Berkeley DB file.
+class CWalletPublicRecordCopyToSQLiteVisitor : public CWalletRecordVisitor
+{
+public:
+    CWalletDBSQLite& dbTo;
+    int& nCopied;
+
+    CWalletPublicRecordCopyToSQLiteVisitor(CWalletDBSQLite& dbToIn, int& nCopiedIn)
+        : dbTo(dbToIn), nCopied(nCopiedIn) { }
+
+    bool VisitWalletRecord(const CDataStream& ssKey,
+                           const CDataStream& ssValue,
+                           string& strErrorRet)
+    {
+        string strType;
+        try
+        {
+            CDataStream ssType = ssKey;
+            ssType >> strType;
+        }
+        catch (...)
+        {
+            strErrorRet = "SQLite wallet has a record whose key type cannot be read";
+            return false;
+        }
+
+        if (IsWalletEncryptionPrivateRecord(strType))
+            return true;
+
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+        vector<unsigned char> vchValue(ssValue.begin(), ssValue.end());
+        bool fOk = dbTo.WriteRecord(vchKey, vchValue, strErrorRet, true);
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!vchValue.empty())
+            memset(&vchValue[0], 0, vchValue.size());
+        if (!fOk)
+        {
+            strErrorRet = strprintf("could not copy wallet record '%s': %s",
+                                    strType.c_str(), strErrorRet.c_str());
+            return false;
+        }
+        nCopied++;
+        return true;
+    }
+};
+
+// Persist an encrypted wallet under the SQLite backend. Everything the caller
+// computed -- the master key, the re-encrypted private keys, the fresh crypted
+// key pool, the encrypted HD seed -- lands in a brand new wallet.sqlite built
+// in one transaction, which is then swapped in for the plaintext original.
+//
+// A fresh file rather than an in-place rewrite for two reasons: it keeps the
+// whole change atomic (a crash before the rename leaves the old wallet whole),
+// and it guarantees no plaintext key survives in a freed page the way an
+// in-place DELETE would leave behind until a VACUUM.
+static bool EncryptWalletPersistSQLite(
+    const vector<pair<vector<unsigned char>, vector<unsigned char> > >& vCryptedKeys,
+    const vector<pair<vector<unsigned char>, vector<unsigned char> > >& vNewPoolKeys,
+    const vector<pair<int64, vector<unsigned char> > >& vNewPool,
+    const CWalletMasterKey& kMasterKey,
+    const vector<unsigned char>& vchCryptedHDMasterNew,
+    const vector<unsigned char>& vchCryptedHDChainCodeNew,
+    unsigned int nHDNextNew,
+    int& nCopiedRet,
+    string& strBackupRet,
+    string& strErrorRet)
+{
+    nCopiedRet = 0;
+    if (!pWalletSQLiteRuntime)
+    {
+        strErrorRet = "SQLite wallet backend is not active";
+        return false;
+    }
+
+    string strWalletPath = GetAppDir() + "/wallet.sqlite";
+    string strTempPath = GetAppDir() + "/" +
+        strprintf("wallet.sqlite.encrypting.%lld", GetTime());
+    remove(strTempPath.c_str());
+    remove((strTempPath + "-wal").c_str());
+    remove((strTempPath + "-shm").c_str());
+
+    {
+        CWalletDBSQLite dbTmp;
+        if (!dbTmp.Open(strTempPath, strErrorRet))
+        {
+            remove(strTempPath.c_str());
+            return false;
+        }
+        if (!dbTmp.BeginTransaction(strErrorRet))
+        {
+            dbTmp.Close();
+            remove(strTempPath.c_str());
+            return false;
+        }
+
+        // The public records come from the live SQLite store -- under this
+        // backend ScanWalletRecords() has no Berkeley DB behind it to read.
+        CWalletPublicRecordCopyToSQLiteVisitor visitor(dbTmp, nCopiedRet);
+        bool fOk = pWalletSQLiteRuntime->ScanRecords(visitor, strErrorRet);
+
+        // Encrypted metadata, serialized byte-for-byte the way the Berkeley DB
+        // path (CWalletRewriteDB) writes it, so a wallet encrypted under either
+        // backend is the same set of records. ckey uses INSERT-only to match
+        // WriteCryptedKey; the rest overwrite.
+        fOk = fOk &&
+            dbTmp.WriteTypedRecord(string("walletminversion"),
+                                   (int)WALLET_FORMAT_ENCRYPTED, strErrorRet, true) &&
+            dbTmp.WriteTypedRecord(make_pair(string("mkey"),
+                                       (unsigned int)(nWalletMasterKeyMaxID + 1)),
+                                   kMasterKey, strErrorRet, true);
+        for (size_t i = 0; fOk && i < vCryptedKeys.size(); i++)
+            fOk = dbTmp.WriteTypedRecord(make_pair(string("ckey"), vCryptedKeys[i].first),
+                                         vCryptedKeys[i].second, strErrorRet, false);
+        for (size_t i = 0; fOk && i < vNewPoolKeys.size(); i++)
+            fOk = dbTmp.WriteTypedRecord(make_pair(string("ckey"), vNewPoolKeys[i].first),
+                                         vNewPoolKeys[i].second, strErrorRet, false);
+        if (fOk && !vchCryptedHDMasterNew.empty())
+            fOk = dbTmp.WriteTypedRecord(string("cryptedhdmaster"),
+                                         vchCryptedHDMasterNew, strErrorRet, true) &&
+                  dbTmp.WriteTypedRecord(string("cryptedhdchaincode"),
+                                         vchCryptedHDChainCodeNew, strErrorRet, true);
+        if (fOk)
+            fOk = dbTmp.WriteTypedRecord(string("hdnext"), nHDNextNew, strErrorRet, true);
+        for (size_t i = 0; fOk && i < vNewPool.size(); i++)
+            fOk = dbTmp.WriteTypedRecord(make_pair(string("pool"), vNewPool[i].first),
+                                         vNewPool[i].second, strErrorRet, true);
+
+        if (!fOk)
+        {
+            string strIgnore;
+            dbTmp.RollbackTransaction(strIgnore);
+            dbTmp.Close();
+            remove(strTempPath.c_str());
+            remove((strTempPath + "-wal").c_str());
+            remove((strTempPath + "-shm").c_str());
+            return false;
+        }
+
+        if (!dbTmp.CommitTransaction(strErrorRet))
+        {
+            dbTmp.Close();
+            remove(strTempPath.c_str());
+            remove((strTempPath + "-wal").c_str());
+            remove((strTempPath + "-shm").c_str());
+            return false;
+        }
+        string strCheckpointError;
+        dbTmp.Checkpoint(strCheckpointError);
+        dbTmp.Close();
+    }
+
+    // The rebuilt wallet is committed and self-contained. Close the live handle
+    // so the file can be swapped: Windows will not rename a file that still has
+    // an open handle, and the node exits right after this.
+    WalletSQLiteRuntimeClose();
+
+    string strBackupPath = WalletEncryptBackupPathFor("wallet.sqlite");
+    if (rename(strWalletPath.c_str(), strBackupPath.c_str()) != 0)
+    {
+        strErrorRet = strprintf("could not move the original SQLite wallet to %s",
+                                strBackupPath.c_str());
+        remove(strTempPath.c_str());
+        return false;
+    }
+    // The moved-aside wallet owns any leftover write-ahead log or shared-memory
+    // sidecar; drop stale ones so they cannot shadow the new wallet.
+    remove((strWalletPath + "-wal").c_str());
+    remove((strWalletPath + "-shm").c_str());
+
+    if (rename(strTempPath.c_str(), strWalletPath.c_str()) != 0)
+    {
+        rename(strBackupPath.c_str(), strWalletPath.c_str());
+        strErrorRet = "could not install the encrypted SQLite wallet; the original was restored";
+        remove(strTempPath.c_str());
+        return false;
+    }
+    remove((strTempPath + "-wal").c_str());
+    remove((strTempPath + "-shm").c_str());
+
+    strBackupRet = strBackupPath;
+    return true;
+}
+
 bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& strErrorRet)
 {
     strBackupRet.clear();
@@ -1415,6 +2436,7 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
     map<vector<unsigned char>, CPrivKey> mapPlainKeys;
     vector<unsigned char> vchPlainHDMaster;
     vector<unsigned char> vchPlainHDChainCode;
+    bool fHadHDSeed = false;
     unsigned int nHDNextSnapshot = 0;
     {
         CRITICAL_BLOCK(cs_mapKeys)
@@ -1425,6 +2447,7 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
         {
             vchPlainHDMaster = vchHDMaster;
             vchPlainHDChainCode = vchHDChainCode;
+            fHadHDSeed = !vchPlainHDMaster.empty() || !vchPlainHDChainCode.empty();
             nHDNextSnapshot = nHDNext;
         }
     }
@@ -1475,11 +2498,13 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
 
     vector<unsigned char> vchCryptedHDMasterNew;
     vector<unsigned char> vchCryptedHDChainCodeNew;
-    if (!vchPlainHDMaster.empty() || !vchPlainHDChainCode.empty())
+    if (fHadHDSeed)
     {
         if (vchPlainHDMaster.size() != 32 || vchPlainHDChainCode.size() != 32)
         {
             strErrorRet = "wallet has an incomplete HD seed";
+            SecureClearBytes(vchPlainHDMaster);
+            SecureClearBytes(vchPlainHDChainCode);
             return false;
         }
         if (!EncryptSecret(vchMasterKey, vchPlainHDMaster,
@@ -1488,8 +2513,12 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
                            WalletSecretIV("hdchaincode"), vchCryptedHDChainCodeNew))
         {
             strErrorRet = "could not encrypt the HD seed";
+            SecureClearBytes(vchPlainHDMaster);
+            SecureClearBytes(vchPlainHDChainCode);
             return false;
         }
+        SecureClearBytes(vchPlainHDMaster);
+        SecureClearBytes(vchPlainHDChainCode);
     }
 
     vector<pair<int64, vector<unsigned char> > > vNewPool;
@@ -1498,7 +2527,7 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
     for (int i = 0; i < KEYPOOL_SIZE; i++)
     {
         CKey key;
-        if (!vchPlainHDMaster.empty())
+        if (fHadHDSeed)
         {
             string strDeriveError;
             if (!DeriveHDKey(nHDNextNew, key, strDeriveError))
@@ -1526,15 +2555,32 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
         vNewPool.push_back(make_pair((int64)i + 1, vchPubKey));
     }
 
+    // Every ciphertext is computed; nothing has touched the store yet. Under
+    // the SQLite backend, persist by rebuilding wallet.sqlite in one atomic
+    // transaction and swapping it in. The Berkeley DB path below is unchanged.
+    if (WalletSQLiteRuntimeActive())
+    {
+        int nCopiedSQLite = 0;
+        if (!EncryptWalletPersistSQLite(vCryptedKeys, vNewPoolKeys, vNewPool,
+                                        kMasterKey, vchCryptedHDMasterNew,
+                                        vchCryptedHDChainCodeNew, nHDNextNew,
+                                        nCopiedSQLite, strBackupRet, strErrorRet))
+            return false;
+        printf("EncryptWallet() : copied %d public record(s), encrypted %u key(s), "
+               "rebuilt %d key-pool entry(s) [SQLite]\n",
+               nCopiedSQLite, (unsigned int)(vCryptedKeys.size() + vNewPoolKeys.size()),
+               (int)vNewPool.size());
+        return true;
+    }
+
     string strTempFile = strprintf("wallet.encrypting.%lld.dat", GetTime());
     string strTempPath = GetAppDir() + "/" + strTempFile;
     remove(strTempPath.c_str());
 
     int nCopied = 0;
     {
-        CWalletRewriteDB dbSource("wallet.dat", "r");
         CWalletRewriteDB dbTarget(strTempFile.c_str(), "c+");
-        if (!dbSource.CopyPublicRecordsTo(dbTarget, nCopied, strErrorRet))
+        if (!CopyPublicWalletRecordsTo(dbTarget, nCopied, strErrorRet))
         {
             remove(strTempPath.c_str());
             return false;
@@ -1594,7 +2640,7 @@ bool EncryptWallet(const string& strPassphrase, string& strBackupRet, string& st
     DBFlush(true);
 
     string strWalletPath = GetAppDir() + "/wallet.dat";
-    string strBackupPath = WalletEncryptBackupPath();
+    string strBackupPath = WalletEncryptBackupPathFor("wallet.dat");
     if (rename(strWalletPath.c_str(), strBackupPath.c_str()) != 0)
     {
         strErrorRet = strprintf("could not move the original wallet to %s", strBackupPath.c_str());
diff --git a/src/db.h b/src/db.h
index 37a252f..859e3fb 100644
--- a/src/db.h
+++ b/src/db.h
@@ -46,7 +46,7 @@ public:
 };
 
 
-extern DbEnv dbenv;
+extern DbEnv& GetDbEnv();
 extern void DBFlush(bool fShutdown);
 // Close the environment and delete its logs. Only the encryption command calls
 // this: the logs hold the plaintext records the old wallet wrote.
@@ -235,7 +235,7 @@ public:
         if (!pdb)
             return false;
         DbTxn* ptxn = NULL;
-        int ret = dbenv.txn_begin(GetTxn(), &ptxn, 0);
+        int ret = GetDbEnv().txn_begin(GetTxn(), &ptxn, 0);
         if (!ptxn || ret != 0)
             return false;
         vTxn.push_back(ptxn);
@@ -333,6 +333,24 @@ private:
 // Legacy IP-based peer address database (CAddrDB / addr.dat) removed --
 // peer discovery is entirely Nostr/.btf-based now.
 
+bool WalletSQLiteRuntimeActive();
+bool WalletSQLiteRuntimeOpen(const string& strPath, string& strErrorRet, bool fMustExist=true);
+void WalletSQLiteRuntimeClose();
+bool WalletSQLiteRuntimeReadRecord(const vector<unsigned char>& vchKey,
+                                   vector<unsigned char>& vchValueRet);
+bool WalletSQLiteRuntimeWriteRecord(const vector<unsigned char>& vchKey,
+                                    const vector<unsigned char>& vchValue,
+                                    bool fOverwrite);
+bool WalletSQLiteRuntimeEraseRecord(const vector<unsigned char>& vchKey);
+bool WalletSQLiteRuntimeBeginTxn();
+bool WalletSQLiteRuntimeCommitTxn();
+void WalletSQLiteRuntimeRollbackTxn();
+bool WalletSQLiteRuntimeOpenReadOnly(const string& strPath, string& strErrorRet);
+bool WalletSQLiteRuntimeCheckpoint(string& strErrorRet);
+string ReadWalletBackendMarker();
+bool WriteWalletBackendMarker(const string& strBackend);
+bool CreateNewSQLiteWallet(const string& strPath);
+
 
 
 
@@ -340,64 +358,141 @@ private:
 class CWalletDB : public CDB
 {
 public:
-    CWalletDB(const char* pszMode="r+", bool fTxn=false) : CDB("wallet.dat", pszMode, fTxn) { }
+    CWalletDB(const char* pszMode="r+", bool fTxn=false);
 private:
     CWalletDB(const CWalletDB&);
     void operator=(const CWalletDB&);
+
+    template<typename K, typename T>
+    bool ReadWalletRecord(const K& key, T& value)
+    {
+        if (!WalletSQLiteRuntimeActive())
+            return Read(key, value);
+
+        CDataStream ssKey(SER_DISK);
+        ssKey.reserve(1000);
+        ssKey << key;
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+        vector<unsigned char> vchValue;
+
+        bool fOk = WalletSQLiteRuntimeReadRecord(vchKey, vchValue);
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!ssKey.empty())
+            memset(&ssKey[0], 0, ssKey.size());
+        if (!fOk)
+            return false;
+
+        CDataStream ssValue(vchValue, SER_DISK);
+        ssValue >> value;
+        bool fReadOk = !ssValue.fail();
+        if (!vchValue.empty())
+            memset(&vchValue[0], 0, vchValue.size());
+        if (!ssValue.empty())
+            memset(&ssValue[0], 0, ssValue.size());
+        return fReadOk;
+    }
+
+    template<typename K, typename T>
+    bool WriteWalletRecord(const K& key, const T& value, bool fOverwrite=true)
+    {
+        if (!WalletSQLiteRuntimeActive())
+            return Write(key, value, fOverwrite);
+
+        CDataStream ssKey(SER_DISK);
+        ssKey.reserve(1000);
+        ssKey << key;
+        CDataStream ssValue(SER_DISK);
+        ssValue.reserve(10000);
+        ssValue << value;
+
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+        vector<unsigned char> vchValue(ssValue.begin(), ssValue.end());
+        bool fOk = WalletSQLiteRuntimeWriteRecord(vchKey, vchValue, fOverwrite);
+
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!vchValue.empty())
+            memset(&vchValue[0], 0, vchValue.size());
+        if (!ssKey.empty())
+            memset(&ssKey[0], 0, ssKey.size());
+        if (!ssValue.empty())
+            memset(&ssValue[0], 0, ssValue.size());
+        return fOk;
+    }
+
+    template<typename K>
+    bool EraseWalletRecord(const K& key)
+    {
+        if (!WalletSQLiteRuntimeActive())
+            return Erase(key);
+
+        CDataStream ssKey(SER_DISK);
+        ssKey.reserve(1000);
+        ssKey << key;
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+        bool fOk = WalletSQLiteRuntimeEraseRecord(vchKey);
+
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!ssKey.empty())
+            memset(&ssKey[0], 0, ssKey.size());
+        return fOk;
+    }
 public:
     bool ReadName(const string& strAddress, string& strName)
     {
         strName = "";
-        return Read(make_pair(string("name"), strAddress), strName);
+        return ReadWalletRecord(make_pair(string("name"), strAddress), strName);
     }
 
     bool WriteName(const string& strAddress, const string& strName)
     {
         mapAddressBook[strAddress] = strName;
-        return Write(make_pair(string("name"), strAddress), strName);
+        return WriteWalletRecord(make_pair(string("name"), strAddress), strName);
     }
 
     bool EraseName(const string& strAddress)
     {
         mapAddressBook.erase(strAddress);
-        return Erase(make_pair(string("name"), strAddress));
+        return EraseWalletRecord(make_pair(string("name"), strAddress));
     }
 
     bool ReadTx(uint256 hash, CWalletTx& wtx)
     {
-        return Read(make_pair(string("tx"), hash), wtx);
+        return ReadWalletRecord(make_pair(string("tx"), hash), wtx);
     }
 
     bool WriteTx(uint256 hash, const CWalletTx& wtx)
     {
-        return Write(make_pair(string("tx"), hash), wtx);
+        return WriteWalletRecord(make_pair(string("tx"), hash), wtx);
     }
 
     bool EraseTx(uint256 hash)
     {
-        return Erase(make_pair(string("tx"), hash));
+        return EraseWalletRecord(make_pair(string("tx"), hash));
     }
 
     bool ReadKey(const vector<unsigned char>& vchPubKey, CPrivKey& vchPrivKey)
     {
         vchPrivKey.clear();
-        return Read(make_pair(string("key"), vchPubKey), vchPrivKey);
+        return ReadWalletRecord(make_pair(string("key"), vchPubKey), vchPrivKey);
     }
 
     bool WriteKey(const vector<unsigned char>& vchPubKey, const CPrivKey& vchPrivKey)
     {
-        return Write(make_pair(string("key"), vchPubKey), vchPrivKey, false);
+        return WriteWalletRecord(make_pair(string("key"), vchPubKey), vchPrivKey, false);
     }
 
     bool ReadDefaultKey(vector<unsigned char>& vchPubKey)
     {
         vchPubKey.clear();
-        return Read(string("defaultkey"), vchPubKey);
+        return ReadWalletRecord(string("defaultkey"), vchPubKey);
     }
 
     bool WriteDefaultKey(const vector<unsigned char>& vchPubKey)
     {
-        return Write(string("defaultkey"), vchPubKey);
+        return WriteWalletRecord(string("defaultkey"), vchPubKey);
     }
 
     // --- Deterministic (BIP32) seed ---------------------------------------
@@ -415,62 +510,75 @@ public:
     {
         vchMasterRet.clear();
         vchChainCodeRet.clear();
-        return Read(string("hdmaster"), vchMasterRet)
-            && Read(string("hdchaincode"), vchChainCodeRet);
+        return ReadWalletRecord(string("hdmaster"), vchMasterRet)
+            && ReadWalletRecord(string("hdchaincode"), vchChainCodeRet);
     }
 
     bool WriteHDMaster(const vector<unsigned char>& vchMaster, const vector<unsigned char>& vchChainCode)
     {
-        return Write(string("hdmaster"), vchMaster)
-            && Write(string("hdchaincode"), vchChainCode);
+        // hdmaster and hdchaincode are halves of one seed: a wallet with one but
+        // not the other is an incomplete HD wallet (-walletstoragecheck flags
+        // exactly that). Under the SQLite runtime write them in one transaction
+        // so a failure or crash between the two cannot leave that half-state.
+        // Berkeley DB keeps its existing per-write behaviour -- the bracket is a
+        // no-op there.
+        if (!WalletSQLiteRuntimeBeginTxn())
+            return false;
+        if (!WriteWalletRecord(string("hdmaster"), vchMaster) ||
+            !WriteWalletRecord(string("hdchaincode"), vchChainCode))
+        {
+            WalletSQLiteRuntimeRollbackTxn();
+            return false;
+        }
+        return WalletSQLiteRuntimeCommitTxn();
     }
 
     bool WriteWalletMinVersion(int nVersion)
     {
-        return Write(string("walletminversion"), nVersion);
+        return WriteWalletRecord(string("walletminversion"), nVersion);
     }
 
     bool WriteMasterKey(unsigned int nID, const CWalletMasterKey& kMasterKey)
     {
-        return Write(make_pair(string("mkey"), nID), kMasterKey, true);
+        return WriteWalletRecord(make_pair(string("mkey"), nID), kMasterKey, true);
     }
 
     bool WriteCryptedKey(const vector<unsigned char>& vchPubKey,
                          const vector<unsigned char>& vchCryptedSecret)
     {
-        return Write(make_pair(string("ckey"), vchPubKey), vchCryptedSecret, false);
+        return WriteWalletRecord(make_pair(string("ckey"), vchPubKey), vchCryptedSecret, false);
     }
 
     bool WriteCryptedHDMaster(const vector<unsigned char>& vchCryptedMaster,
                               const vector<unsigned char>& vchCryptedChainCode)
     {
-        return Write(string("cryptedhdmaster"), vchCryptedMaster)
-            && Write(string("cryptedhdchaincode"), vchCryptedChainCode);
+        return WriteWalletRecord(string("cryptedhdmaster"), vchCryptedMaster)
+            && WriteWalletRecord(string("cryptedhdchaincode"), vchCryptedChainCode);
     }
 
     bool WriteHDNext(unsigned int nNext)
     {
-        return Write(string("hdnext"), nNext);
+        return WriteWalletRecord(string("hdnext"), nNext);
     }
 
     bool WriteHDSchema(int nSchema)
     {
-        return Write(string("hdschema"), nSchema);
+        return WriteWalletRecord(string("hdschema"), nSchema);
     }
 
     bool WriteHDCoinType(unsigned int nCoinType)
     {
-        return Write(string("hdcointype"), nCoinType);
+        return WriteWalletRecord(string("hdcointype"), nCoinType);
     }
 
     bool WriteHDReceiveNext(unsigned int nNext)
     {
-        return Write(string("hdreceivenext"), nNext);
+        return WriteWalletRecord(string("hdreceivenext"), nNext);
     }
 
     bool WriteHDChangeNext(unsigned int nNext)
     {
-        return Write(string("hdchangenext"), nNext);
+        return WriteWalletRecord(string("hdchangenext"), nNext);
     }
 
     // Keys generated ahead of time and not yet handed out. The private key of
@@ -478,30 +586,43 @@ public:
     // record only says that this one is still unspoken for.
     bool WritePool(int64 nIndex, const vector<unsigned char>& vchPubKey)
     {
-        return Write(make_pair(string("pool"), nIndex), vchPubKey);
+        return WriteWalletRecord(make_pair(string("pool"), nIndex), vchPubKey);
     }
 
     bool ErasePool(int64 nIndex)
     {
-        return Erase(make_pair(string("pool"), nIndex));
+        return EraseWalletRecord(make_pair(string("pool"), nIndex));
     }
 
     template<typename T>
     bool ReadSetting(const string& strKey, T& value)
     {
-        return Read(make_pair(string("setting"), strKey), value);
+        return ReadWalletRecord(make_pair(string("setting"), strKey), value);
     }
 
     template<typename T>
     bool WriteSetting(const string& strKey, const T& value)
     {
-        return Write(make_pair(string("setting"), strKey), value);
+        return WriteWalletRecord(make_pair(string("setting"), strKey), value);
     }
 
     bool LoadWallet(vector<unsigned char>& vchDefaultKeyRet);
 };
 
+class CWalletRecordVisitor
+{
+public:
+    virtual ~CWalletRecordVisitor() { }
+    virtual bool VisitWalletRecord(const CDataStream& ssKey,
+                                   const CDataStream& ssValue,
+                                   string& strErrorRet) = 0;
+};
+
+bool ScanWalletRecords(CWalletRecordVisitor& visitor, string& strErrorRet);
+
 bool LoadWallet();
+bool LoadWalletFromSQLite(const string& strPath);
+bool LoadWalletFromSQLiteRuntime(const string& strPath);
 
 // Writes a wallet.dat that opens on its own, anywhere -- see the definition in
 // db.cpp for why a plain file copy does not. Still a point-in-time snapshot:
diff --git a/src/fuzz_net_message.cpp b/src/fuzz_net_message.cpp
new file mode 100644
index 0000000..1104d90
--- /dev/null
+++ b/src/fuzz_net_message.cpp
@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// libFuzzer harness for the P2P message envelope parser. It feeds arbitrary
+// receive-buffer bytes into ProcessMessages() through a dummy CNode, without
+// opening sockets or starting node threads.
+
+#include "headers_core.h"
+
+#include <stdint.h>
+#include <stddef.h>
+
+// Stand-ins normally supplied by the GUI/headless entry objects.
+map<string,string> mapAddressBook;
+bool gPoolServerRunning = false;
+void MainFrameRepaint() {}
+
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
+{
+    // Keep this first target focused on parser behavior, not multi-megabyte
+    // allocation pressure. The protocol size guards have their own selftest.
+    if (size > 4096)
+        return 0;
+
+    CNode node(INVALID_SOCKET, CAddress("127.0.0.1"));
+    node.nVersion = 0; // exercise pre-version gating plus the version parser
+    if (size > 0)
+        node.vRecv.write((const char*)data, (int)size);
+
+    ProcessMessages(&node);
+    return 0;
+}
diff --git a/src/fuzz_script.cpp b/src/fuzz_script.cpp
new file mode 100644
index 0000000..28c84f6
--- /dev/null
+++ b/src/fuzz_script.cpp
@@ -0,0 +1,59 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// libFuzzer harness for raw script parsing and evaluation. It keeps the
+// target deliberately small: arbitrary bytes become one CScript, then the
+// parser, standard-script extractors and EvalScript all see that same input.
+
+#include "headers_core.h"
+
+#include <stdint.h>
+#include <stddef.h>
+
+// Stand-ins normally supplied by the GUI/headless entry objects.
+map<string,string> mapAddressBook;
+bool gPoolServerRunning = false;
+void MainFrameRepaint() {}
+
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size)
+{
+    if (size < 1 || size > 4096)
+        return 0;
+
+    try
+    {
+        int nHashType = data[0];
+        const unsigned char* pbegin = data + 1;
+        const unsigned char* pend = data + size;
+        CScript script(pbegin, pend);
+
+        CScript::const_iterator pc = script.begin();
+        opcodetype opcode;
+        vector<unsigned char> vchPush;
+        while (pc < script.end())
+        {
+            if (!script.GetOp(pc, opcode, vchPush))
+                break;
+        }
+
+        script.GetSigOpCount();
+        script.ToString();
+
+        vector<unsigned char> vchPubKey;
+        ExtractPubKey(script, false, vchPubKey);
+        uint160 hash160;
+        ExtractHash160(script, hash160);
+
+        CTransaction tx;
+        tx.vin.push_back(CTxIn(COutPoint(), CScript()));
+        tx.vout.push_back(CTxOut(0, CScript()));
+
+        vector<vector<unsigned char> > stack;
+        EvalScript(script, tx, 0, nHashType, &stack);
+    }
+    catch (...)
+    {
+    }
+
+    return 0;
+}
diff --git a/src/gui.cpp b/src/gui.cpp
index 8f1d204..ff6059a 100644
--- a/src/gui.cpp
+++ b/src/gui.cpp
@@ -11,10 +11,16 @@
 #include <ctime>
 #include <cstdio>
 #include <sstream>
+#ifdef _WIN32
+#include <shellapi.h>   // ShellExecuteA, to open the website in the browser
+#else
+#include <unistd.h>
+#endif
 #include <iomanip>
 #include <atomic>
 #include <mutex>
 #include <thread>
+#include <system_error>
 #include "bip32.h"
 #include "walletcmd.h"
 #include "font_roboto.h"
@@ -172,7 +178,11 @@ static bool PathIsInsideDataDir(const std::string& strPath)
 
 static void SetDefaultBackupPath()
 {
-    std::string path = DefaultBackupDir() + "/wallet-backup-" + BackupTimeSuffix() + ".dat";
+    // Match the extension to the live backend: BackupWallet copies wallet.sqlite
+    // under the SQLite backend and wallet.dat under Berkeley DB, so a ".dat"
+    // default name would put SQLite contents in a misleadingly-named file.
+    const char* pszExt = WalletSQLiteRuntimeActive() ? ".sqlite" : ".dat";
+    std::string path = DefaultBackupDir() + "/wallet-backup-" + BackupTimeSuffix() + pszExt;
     strncpy(g_backupPath, path.c_str(), sizeof(g_backupPath)-1);
     g_backupPath[sizeof(g_backupPath)-1] = '\0';
 }
@@ -910,8 +920,16 @@ static void DrawOptionsDialog()
 
             if (nMineMode == MINE_OPERATOR) {
                 if (!gPoolServerRunning) {
-                    gPoolServerRunning = true;
-                    _beginthread(ThreadRPCServer, 0, NULL);
+                    // Claim the server is up only once it is. The flag used to
+                    // be set first and the result never looked at, so a refused
+                    // spawn left an operator with a pool that reports itself
+                    // running, no RPC server for miners to reach, and nothing
+                    // anywhere saying why. The flag also latches: with it set,
+                    // this branch is never retried.
+                    if (_beginthread(ThreadRPCServer, 0, NULL) == (uintptr_t)-1)
+                        printf("Error: _beginthread(ThreadRPCServer) failed -- pool server not started\n");
+                    else
+                        gPoolServerRunning = true;
                 } else if (!gPoolRunning) {
                     gPoolRunning = true;
                 }
@@ -1124,11 +1142,28 @@ static void DrawRestorePhraseDialog()
                 }
                 g_restoreDerived.store(0);
                 g_restoreRecovered.store(0);
+                // Set before the spawn, not after: RestoreThread clears this
+                // flag itself when it finishes, and a short restore can beat
+                // us back here and have its `false` overwritten, leaving the
+                // dialog disabled forever.
                 g_restoreRunning.store(true);
                 // On its own thread: a restore walks the whole chain once per
                 // batch and would otherwise freeze the window for as long as it
-                // takes.
-                std::thread(RestoreThread, std::string(g_restoreInput)).detach();
+                // takes. A refused spawn is one restore that does not happen,
+                // not a reason to take the window down with an uncaught
+                // std::system_error -- and the flag has to come back off, or
+                // the dialog sits greyed out reporting a search nobody is
+                // running.
+                try
+                {
+                    std::thread(RestoreThread, std::string(g_restoreInput)).detach();
+                }
+                catch (const std::system_error& e)
+                {
+                    g_restoreRunning.store(false);
+                    std::lock_guard<std::mutex> lock(g_restoreResultMutex);
+                    g_restoreResult = std::string("Could not start the search: ") + e.what();
+                }
             }
         }
         if (fBusy)
@@ -1250,15 +1285,15 @@ static void DrawWalletSafetyDialog()
         if (g_recoveryAudit.fHaveSeed)
         {
             ImGui::Text("Derivation schema: %s", HDKeySchemaName(g_recoveryAudit.nSchema).c_str());
-            ImGui::Text("BIP44 coin type: %u (provisional BITFLASH)", g_recoveryAudit.nCoinType);
+            ImGui::Text("BIP44 coin type: %u (SLIP-0044 BITFLASH)", g_recoveryAudit.nCoinType);
         }
         ImGui::Text("Phrase-backed spendable balance: %s BTF",
                     FmtMoney(g_recoveryAudit.nRecoverableCredit).c_str());
-        ImGui::Text("Wallet.dat-only spendable balance: %s BTF",
+        ImGui::Text("Not phrase-backed spendable balance: %s BTF",
                     FmtMoney(g_recoveryAudit.nLegacyCredit).c_str());
         ImGui::Text("Phrase-backed immature mining rewards: %s BTF",
                     FmtMoney(g_recoveryAudit.nRecoverableImmatureCredit).c_str());
-        ImGui::Text("Wallet.dat-only immature mining rewards: %s BTF",
+        ImGui::Text("Not phrase-backed immature mining rewards: %s BTF",
                     FmtMoney(g_recoveryAudit.nLegacyImmatureCredit).c_str());
         if (!g_recoveryAudit.fDeriveComplete)
         {
@@ -1272,8 +1307,8 @@ static void DrawWalletSafetyDialog()
             ImGui::PushStyleColor(ImGuiCol_Text, ImVec4(1.0f, 0.75f, 0.25f, 1.0f));
             ImGui::TextWrapped(
                 "Some coins are on keys the phrase does not reproduce. "
-                "Keep wallet.dat backups until that balance has been moved to a "
-                "phrase-backed address.");
+                "Keep a file backup of this wallet until that balance has been "
+                "moved to a phrase-backed address.");
             ImGui::PopStyleColor();
         }
         else if (HaveHDSeed() &&
@@ -1369,16 +1404,38 @@ static void DrawDiagnosticsDialog()
     ImGui::End();
 }
 
+static void OpenURL(const char* pszUrl)
+{
+#ifdef _WIN32
+    ShellExecuteA(NULL, "open", pszUrl, NULL, NULL, SW_SHOWNORMAL);
+#else
+    std::string cmd = std::string("xdg-open '") + pszUrl + "' >/dev/null 2>&1 &";
+    int r = system(cmd.c_str());
+    (void)r;
+#endif
+}
+
 static void DrawAboutDialog()
 {
     if (!g_showAbout) return;
-    ImGui::SetNextWindowSize(ImVec2(380.0f, 170.0f), ImGuiCond_Always);
+    ImGui::SetNextWindowSize(ImVec2(380.0f, 205.0f), ImGuiCond_Always);
     ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(),
                             ImGuiCond_Always, ImVec2(0.5f, 0.5f));
     if (ImGui::Begin("About Bitflash", &g_showAbout,
         ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoCollapse))
     {
-        ImGui::TextColored(ImVec4(1.0f, 0.6f, 0.0f, 1.0f), "Bitflash  BTF  v1.1.0");
+        ImGui::TextColored(ImVec4(1.0f, 0.6f, 0.0f, 1.0f),
+                           "Bitflash  BTF  v" BITFLASH_VERSION_STRING);
+        ImGui::Spacing();
+        ImGui::PushStyleColor(ImGuiCol_Text, ImVec4(0.40f, 0.70f, 1.0f, 1.0f));
+        ImGui::TextUnformatted("https://bitflash.network");
+        ImGui::PopStyleColor();
+        if (ImGui::IsItemHovered())
+        {
+            ImGui::SetMouseCursor(ImGuiMouseCursor_Hand);
+            if (ImGui::IsMouseClicked(0))
+                OpenURL("https://bitflash.network");
+        }
         ImGui::Spacing();
         ImGui::TextWrapped(
             "CPU-only cryptocurrency. RandomX proof of work. "
@@ -1391,6 +1448,184 @@ static void DrawAboutDialog()
     ImGui::End();
 }
 
+// First-run offer to move a Berkeley DB wallet to the SQLite backend. Only the
+// button actions touch anything: "Convert" exports wallet.dat to wallet.sqlite
+// and records the backend marker (wallet.dat is left untouched, so a restart
+// picks up SQLite while the old file stays as a fallback); "Keep Berkeley DB"
+// just records that choice so the offer does not return; "Decide later" leaves
+// no marker and asks again next start.
+static bool        g_showBackendWizard = false;
+static std::string g_wizardStatus;
+static bool        g_wizardConverted   = false;
+static int         g_restartArgc       = 0;
+static char**      g_restartArgv       = NULL;
+
+#ifdef _WIN32
+// Quote one argument so CommandLineToArgvW parses it back to exactly this
+// string: only backslashes that immediately precede a double quote (including
+// the closing one) are doubled, so ordinary Windows paths are not mangled.
+static std::string QuoteArgWin(const std::string& a)
+{
+    if (!a.empty() && a.find_first_of(" \t\"") == std::string::npos)
+        return a;
+    std::string r = "\"";
+    size_t bs = 0;
+    for (size_t i = 0; i < a.size(); i++)
+    {
+        if (a[i] == '\\') { bs++; continue; }
+        if (a[i] == '"') { r.append(bs * 2 + 1, '\\'); r += '"'; bs = 0; continue; }
+        r.append(bs, '\\'); bs = 0; r += a[i];
+    }
+    r.append(bs * 2, '\\');
+    r += "\"";
+    return r;
+}
+#endif
+
+// Relaunch Bitflash with the same arguments and datadir, then ask this instance
+// to exit -- but only once the relaunch has actually started, so a failure never
+// leaves the user with no node running. The new instance waits (-restartwait)
+// before it opens the network port and the block index, so this one is gone
+// first and they never fight over the same files.
+static void RestartApplication()
+{
+    bool fLaunched = false;
+#ifdef _WIN32
+    char exePath[MAX_PATH];
+    if (GetModuleFileNameA(NULL, exePath, MAX_PATH) == 0)
+        return;
+    std::string strCmd = QuoteArgWin(exePath);
+    bool fHasDataDir = false;
+    for (int i = 1; i < g_restartArgc; i++)
+    {
+        std::string a = g_restartArgv[i] ? g_restartArgv[i] : "";
+        if (a.find("-datadir=") == 0 || a.find("/datadir=") == 0)
+            fHasDataDir = true;
+        strCmd += " " + QuoteArgWin(a);
+    }
+    if (!fHasDataDir)
+        strCmd += " " + QuoteArgWin("-datadir=" + GetAppDir());
+    strCmd += " -restartwait";
+
+    std::vector<char> cmdBuf(strCmd.begin(), strCmd.end());
+    cmdBuf.push_back('\0');
+    STARTUPINFOA si; memset(&si, 0, sizeof(si)); si.cb = sizeof(si);
+    PROCESS_INFORMATION pi; memset(&pi, 0, sizeof(pi));
+    if (CreateProcessA(NULL, &cmdBuf[0], NULL, NULL, FALSE, 0, NULL, NULL, &si, &pi))
+    {
+        CloseHandle(pi.hProcess);
+        CloseHandle(pi.hThread);
+        fLaunched = true;
+    }
+#else
+    pid_t pid = fork();
+    if (pid == 0)
+    {
+        // Child: wait for the parent to release the port and files, then re-exec.
+        // /proc/self/exe is the reliable absolute path; argv[0] may be relative
+        // or a bare name that execv() cannot resolve.
+        sleep(2);
+        char exePath[4096];
+        ssize_t len = readlink("/proc/self/exe", exePath, sizeof(exePath) - 1);
+        if (len > 0)
+        {
+            exePath[len] = '\0';
+            execv(exePath, g_restartArgv);
+        }
+        if (g_restartArgv)
+            execv(g_restartArgv[0], g_restartArgv);
+        _exit(127);
+    }
+    fLaunched = (pid > 0);
+#endif
+
+    if (fLaunched)
+    {
+        fShutdown = true;
+        if (glfwGetCurrentContext())
+            glfwSetWindowShouldClose(glfwGetCurrentContext(), true);
+    }
+    else
+        g_wizardStatus = "Could not relaunch automatically -- please restart "
+                         "Bitflash yourself to switch to the SQLite wallet.";
+}
+
+static void DrawBackendWizardDialog()
+{
+    if (!g_showBackendWizard) return;
+    ImGui::SetNextWindowSize(ImVec2(560.0f, 0.0f), ImGuiCond_Always);
+    ImGui::SetNextWindowPos(ImGui::GetMainViewport()->GetCenter(),
+                            ImGuiCond_Always, ImVec2(0.5f, 0.5f));
+    if (ImGui::Begin("Wallet Storage", &g_showBackendWizard,
+        ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoCollapse))
+    {
+        if (g_wizardConverted)
+        {
+            ImGui::TextColored(ImVec4(0.35f, 1.0f, 0.45f, 1.0f), "Converted to SQLite.");
+            ImGui::TextWrapped("%s", g_wizardStatus.c_str());
+            ImGui::Spacing();
+            ImGui::TextWrapped(
+                "The switch takes effect when Bitflash restarts. Until then it is "
+                "still running on the old Berkeley DB wallet. Your wallet.dat is "
+                "kept untouched as a fallback.");
+            ImGui::Spacing();
+            if (ImGui::Button("Restart Now", ImVec2(140.0f, 0.0f)))
+                RestartApplication();
+            ImGui::SameLine();
+            if (ImGui::Button("Later", ImVec2(120.0f, 0.0f)))
+                g_showBackendWizard = false;
+            ImGui::Spacing();
+            ImGui::TextDisabled(
+                "If you keep mining before restarting, new coins go to the old "
+                "wallet until you switch.");
+        }
+        else
+        {
+            ImGui::TextWrapped(
+                "Bitflash can store your wallet in a new SQLite format: a single "
+                "file that is easier to back up and does not depend on the "
+                "database/ directory beside it.");
+            ImGui::Spacing();
+            ImGui::TextWrapped(
+                "Your current Berkeley DB wallet (wallet.dat) is kept exactly as it "
+                "is -- nothing is deleted, and you can go back to it at any time. "
+                "The change takes effect after you restart.");
+            ImGui::Spacing();
+            if (ImGui::Button("Convert to SQLite", ImVec2(180.0f, 0.0f)))
+            {
+                int nCopied = 0;
+                std::string strError;
+                if (DoConvertWalletToSQLite(nCopied, strError))
+                {
+                    g_wizardStatus =
+                        strprintf("%d record(s) copied to wallet.sqlite.", nCopied);
+                    g_wizardConverted = true;
+                }
+                else
+                    g_wizardStatus = "Conversion failed: " + strError;
+            }
+            ImGui::SameLine();
+            if (ImGui::Button("Keep Berkeley DB", ImVec2(160.0f, 0.0f)))
+            {
+                WriteWalletBackendMarker("bdb");
+                g_showBackendWizard = false;
+            }
+            ImGui::SameLine();
+            if (ImGui::Button("Decide later", ImVec2(120.0f, 0.0f)))
+                g_showBackendWizard = false;
+
+            if (!g_wizardStatus.empty())
+            {
+                ImGui::Spacing();
+                ImGui::PushStyleColor(ImGuiCol_Text, ImVec4(1.0f, 0.45f, 0.35f, 1.0f));
+                ImGui::TextWrapped("%s", g_wizardStatus.c_str());
+                ImGui::PopStyleColor();
+            }
+        }
+    }
+    ImGui::End();
+}
+
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
@@ -1457,6 +1692,21 @@ int RunGUI(int argc, char* argv[])
     g_mineRadio = nMineMode;
     strncpy(g_participantPool, strParticipantPool.c_str(), sizeof(g_participantPool)-1);
 
+    // Kept for the wizard's "Restart Now": relaunch with the same command line.
+    g_restartArgc = argc;
+    g_restartArgv = argv;
+
+    // First run on a Berkeley DB wallet with no recorded choice yet: offer to
+    // convert to SQLite. Never when already on SQLite, once wallet.sqlite exists,
+    // or once a choice has been recorded in the backend marker.
+    if (!WalletSQLiteRuntimeActive() &&
+        FileExists((GetAppDir() + "/wallet.dat").c_str()) &&
+        !FileExists((GetAppDir() + "/wallet.sqlite").c_str()) &&
+        ReadWalletBackendMarker().empty())
+    {
+        g_showBackendWizard = true;
+    }
+
     int frame = 0;
     while (!glfwWindowShouldClose(window) && !fShutdown)
     {
@@ -1480,6 +1730,7 @@ int RunGUI(int argc, char* argv[])
         DrawRestorePhraseDialog();
         DrawDiagnosticsDialog();
         DrawAboutDialog();
+        DrawBackendWizardDialog();
         DrawStatusBar();
 
         ImGui::Render();
diff --git a/src/headers_core.h b/src/headers_core.h
index 6a60b52..2824126 100644
--- a/src/headers_core.h
+++ b/src/headers_core.h
@@ -1,6 +1,11 @@
 // Core node headers -- no GUI framework dependency.
 // Included by gui.cpp and all non-GUI source files.
 
+// The one place the human-readable release version lives -- bump it at release.
+// It is what the About dialog shows. Protocol and transaction versions elsewhere
+// (nVersion fields) are unrelated and must not be changed for a release.
+#define BITFLASH_VERSION_STRING "1.2.20"
+
 #ifdef _MSC_VER
 #pragma warning(disable:4786)
 #endif
diff --git a/src/main.cpp b/src/main.cpp
index 77aba89..0fa6b89 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -14,6 +14,7 @@
 #include <atomic>
 #include <mutex>
 #include <thread>
+#include <system_error>
 #include "bip32.h"
 #include "btfaddr.h"
 #include "btftunnel.h"
@@ -41,12 +42,30 @@ unsigned int nTransactionsUpdated = 0;
 map<COutPoint, CInPoint> mapNextTx;
 
 map<uint256, CBlockIndex*> mapBlockIndex;
-// Bitflash genesis -- mined under RandomX PoW on 2026-07-22
-// (nTime 1753142400, nBits 0x1f0fffff, RandomX key "Bitflash/RandomX/v1/...")
-// Bitflash 2026 stable relaunch genesis (2-min blocks, RandomX). Mined values.
-unsigned int GENESIS_NONCE = 3141;
-uint256 hashGenesisBlock("0x5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169");
-uint256 hashGenesisMerkleRoot("0x1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325");
+// Bitflash mainnet genesis -- mined under RandomX PoW for the 2026 stable
+// relaunch. Testnet gets its own resettable genesis below so block indexes,
+// headers, and wallet scans cannot be accidentally mixed across networks.
+static const unsigned int MAINNET_GENESIS_TIME  = 1753315200; // 2026-07-24 00:00:00 UTC
+static const unsigned int MAINNET_GENESIS_NONCE = 3141;
+static const char* MAINNET_GENESIS_TIMESTAMP =
+    "Bitflash 24/Jul/2026 Fair launch: one CPU one vote, no premine";
+static const char* MAINNET_GENESIS_HASH =
+    "0x5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169";
+static const char* MAINNET_GENESIS_MERKLE =
+    "0x1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325";
+
+static const unsigned int TESTNET_GENESIS_TIME  = 1787184000; // 2026-08-20 00:00:00 UTC
+static const unsigned int TESTNET_GENESIS_NONCE = 3199;
+static const char* TESTNET_GENESIS_TIMESTAMP =
+    "Bitflash testnet 20/Aug/2026: resettable public test chain";
+static const char* TESTNET_GENESIS_HASH =
+    "0xa9d11c6d697bcb7aea0653bc088b12dcf9f44e732df205162cf085fd9d9963eb";
+static const char* TESTNET_GENESIS_MERKLE =
+    "0x510b293105e3ff85b8d4c3920e357f85d1a86bf199eb4e7d11f04f380030ec5c";
+
+unsigned int GENESIS_NONCE = MAINNET_GENESIS_NONCE;
+uint256 hashGenesisBlock(MAINNET_GENESIS_HASH);
+uint256 hashGenesisMerkleRoot(MAINNET_GENESIS_MERKLE);
 CBlockIndex* pindexGenesisBlock = NULL;
 int nBestHeight = -1;
 uint256 hashBestChain = 0;
@@ -64,6 +83,137 @@ CBlockIndex* pindexBest = NULL;
 map<uint256, CBlock*> mapOrphanBlocks;
 multimap<uint256, CBlock*> mapOrphanBlocksByPrev;
 
+// Block bodies we have sent a getdata for and not yet received, so the
+// failover pass in SendMessages can tell "requested and being served" from
+// "requested and gone quiet" and re-issue the request to a different peer
+// (#33). Keyed by block hash; setAsked is the peers already tried since the
+// round last restarted, so the retry rotates instead of hammering the
+// announcer that is not serving. Guarded by cs_main, which both the message
+// handlers and SendMessages already hold.
+//
+// Capped small on purpose. At the tip there is one block in flight; during
+// initial download there are legitimately hundreds outstanding to one peer,
+// and rotating those would duplicate the whole download to every other peer.
+//
+// The cap is a shared resource and nothing on the path from inv to insertion
+// can tell a real block hash from 32 random bytes -- AlreadyHave only asks
+// whether we already hold the block, and there is no header to check work
+// against. So the table does not refuse a new hash when it is full; it makes
+// room. See MakeRoomInBlockFetch for the rule, which is what stops one peer
+// filling all eight slots and switching failover off for everybody.
+//
+// The initialisers matter: the insertion path uses operator[] and then tests
+// nTimeFirstAsked == 0 to detect a fresh entry. That worked on
+// value-initialisation alone, but only for as long as nobody gave this struct
+// a constructor.
+struct CBlockFetch
+{
+    int64 nTimeFirstAsked = 0;  // when the first getdata for this block went out
+    int64 nTimeAsked      = 0;  // when the latest getdata went out
+    CAddress addrAnnounced;     // peer whose announcement put this hash here
+    set<CAddress> setAsked;     // peers tried since the round last restarted
+};
+map<uint256, CBlockFetch> mapBlockFetch;
+static const int BLOCK_FETCH_TRACK_MAX = 8;
+// A block nobody has served for this long is not a fetch problem: the hash may
+// have been announced and never existed. Drop the entry rather than getdata
+// forever; a re-announcement recreates it.
+static const int BLOCK_FETCH_GIVEUP_SECS = 10 * 60;
+
+// Failover firing at all is worth saying out loud: it means peers are
+// announcing blocks they then do not serve, which is the pathology of #33 and
+// the thing nobody could otherwise see. Naming the peer on every re-request is
+// a different matter. A peer can drive that line as often as it likes by
+// announcing hashes it will not serve, and what it prints is a peer address,
+// which is the one thing the .btf transport otherwise takes trouble not to
+// spread around. So the per-peer detail sits behind the net category and the
+// unconditional line is a count over a window no peer can shorten: the first
+// failover after a quiet spell prints at once, because the change from "blocks
+// arrive" to "blocks are announced and not served" is the event worth seeing,
+// and everything after it is summarised once a minute.
+static const int BLOCK_FETCH_REPORT_SECS = 60;
+static int64 nBlockFetchWindowStart = 0;
+static int   nBlockFetchFailovers   = 0;
+
+// How stale our own best block may be before we stop calling this the tip.
+// Blocks target two minutes, so this is thirty intervals: far longer than any
+// stall worth failing over from -- the one in #33 ran sixteen minutes -- and
+// far shorter than catching up, which starts hours or days back.
+static const int BLOCK_FETCH_TIP_AGE_SECS = 60 * 60;
+
+// Whether this node is tracking the tip rather than still catching up.
+//
+// Measured off the age of our own best block, not off any height a peer told
+// us. nStartingHeight is optional in the version message and every node
+// released so far sends the short form, so it is -1 for essentially every
+// peer; and where it is filled in later it is filled in from the height of a
+// block that peer served us, which during catch-up tracks our own height and
+// would report "at the tip" for the whole download. Block timestamps are the
+// one clock here that peers cannot move: CheckBlock refuses anything more than
+// two hours ahead and AcceptBlock refuses anything at or before the previous
+// median, so the only way to make this read "at the tip" falsely is to mine,
+// and all that buys is the 15s spacing this code had unconditionally anyway.
+bool IsBlockFetchNearTip()
+{
+    return pindexBest && (int64)pindexBest->nTime > GetTime() - BLOCK_FETCH_TIP_AGE_SECS;
+}
+
+// Drop one entry so a hash announced by addrNew can be tracked.
+//
+// Refusing the insertion instead was a remote off-switch for the whole
+// feature. An inv carrying eight hashes that never existed filled every slot
+// -- nothing between inv and here can tell those from real blocks -- and no
+// genuinely new block was tracked again until the give-up timer expired ten
+// minutes later, re-armable for one message per ten minutes from a single
+// connection.
+//
+// So evict instead, by occupancy: a peer may only take a slot from a peer
+// holding strictly more slots than itself, and otherwise recycles one of its
+// own. That is what keeps eviction from becoming the same attack in a new
+// shape. A peer that has filled the table is by definition the heaviest
+// holder, so its own entries are the only ones it can displace, while a peer
+// announcing its first block holds nothing and therefore always evicts from
+// the heaviest -- a genuine announcement is never refused a slot, whatever the
+// attacker holds or however many connections it holds it from. The one case
+// that costs a real fetch is eight distinct peers holding one entry each,
+// where a ninth takes the oldest; that is a busy healthy node, not an attack,
+// and losing the oldest of eight beats refusing the ninth.
+static void MakeRoomInBlockFetch(const CAddress& addrNew)
+{
+    if (mapBlockFetch.empty())
+        return;
+
+    map<CAddress, int> mapHeld;
+    for (map<uint256, CBlockFetch>::iterator mi = mapBlockFetch.begin(); mi != mapBlockFetch.end(); ++mi)
+        mapHeld[(*mi).second.addrAnnounced]++;
+
+    int nMine = mapHeld.count(addrNew) ? mapHeld[addrNew] : 0;
+
+    int nMax = 0;
+    CAddress addrVictim;
+    for (map<CAddress, int>::iterator mi = mapHeld.begin(); mi != mapHeld.end(); ++mi)
+        if ((*mi).second > nMax)
+        {
+            nMax = (*mi).second;
+            addrVictim = (*mi).first;
+        }
+
+    // Nobody is holding more than this peer, so it recycles its own oldest
+    // rather than taking a slot off an equal.
+    if (nMax <= nMine)
+        addrVictim = addrNew;
+
+    map<uint256, CBlockFetch>::iterator miVictim = mapBlockFetch.end();
+    for (map<uint256, CBlockFetch>::iterator mi = mapBlockFetch.begin(); mi != mapBlockFetch.end(); ++mi)
+        if ((*mi).second.addrAnnounced == addrVictim &&
+            (miVictim == mapBlockFetch.end() ||
+             (*mi).second.nTimeFirstAsked < (*miVictim).second.nTimeFirstAsked))
+            miVictim = mi;
+
+    if (miVictim != mapBlockFetch.end())
+        mapBlockFetch.erase(miVictim);
+}
+
 map<uint256, CDataStream*> mapOrphanTransactions;
 multimap<uint256, CDataStream*> mapOrphanTransactionsByPrev;
 
@@ -109,7 +259,11 @@ string strPayoutFile;                // participant: /payoutfile with one addres
 int    nHashThreads      = 0;        // participant: /hashthreads override (0 = cores-1)
 string strPoolName       = "Bitflash Pool";
 string strPoolDashboardUrl;
+string strPoolStatusFile;
+string strPoolRoundsFile;
 double dPoolFeePercent   = 0.0;
+bool   fStratumBridge    = false;
+int    nStratumBridgePort = 3333;
 
 static std::atomic<uint64> gParticipantSharesSent{0};
 static std::atomic<uint64> gParticipantSharesAccepted{0};
@@ -118,6 +272,63 @@ static std::atomic<uint64> gParticipantHashRateX1000{0};
 static std::mutex gParticipantStatusMutex;
 static std::string gParticipantStatus;
 
+void SelectGenesisParams(bool fTestNetIn)
+{
+    static bool fGenesisParamsSelected = false;
+    static bool fGenesisParamsTestNet = false;
+    if (fGenesisParamsSelected && fGenesisParamsTestNet == fTestNetIn)
+        return;
+
+    fGenesisParamsSelected = true;
+    fGenesisParamsTestNet = fTestNetIn;
+
+    if (fTestNetIn)
+    {
+        GENESIS_NONCE = TESTNET_GENESIS_NONCE;
+        hashGenesisBlock = uint256(TESTNET_GENESIS_HASH);
+        hashGenesisMerkleRoot = uint256(TESTNET_GENESIS_MERKLE);
+    }
+    else
+    {
+        GENESIS_NONCE = MAINNET_GENESIS_NONCE;
+        hashGenesisBlock = uint256(MAINNET_GENESIS_HASH);
+        hashGenesisMerkleRoot = uint256(MAINNET_GENESIS_MERKLE);
+    }
+}
+
+void SelectChainParams(bool fTestNetIn)
+{
+    SelectNetworkParams(fTestNetIn);
+    SelectGenesisParams(fTestNetIn);
+}
+
+static CBlock BuildGenesisBlock()
+{
+    const char* pszTimestamp = IsTestNet() ?
+        TESTNET_GENESIS_TIMESTAMP : MAINNET_GENESIS_TIMESTAMP;
+
+    CTransaction txNew;
+    txNew.vin.resize(1);
+    txNew.vout.resize(1);
+    txNew.vin[0].scriptSig = CScript() << 486604799 << CBigNum(4) <<
+        vector<unsigned char>((unsigned char*)pszTimestamp,
+                              (unsigned char*)pszTimestamp + strlen(pszTimestamp));
+    txNew.vout[0].nValue = 50 * COIN;
+    txNew.vout[0].scriptPubKey = CScript() <<
+        CBigNum("0x5F1DF16B2B704C8A578D0BBAF74D385CDE12C11EE50455F3C438EF4C3FBCF649B6DE611FEAE06279A60939E028A8D65C10B73071A6F16719274855FEB0FD8A6704") <<
+        OP_CHECKSIG;
+
+    CBlock block;
+    block.vtx.push_back(txNew);
+    block.hashPrevBlock = 0;
+    block.hashMerkleRoot = block.BuildMerkleTree();
+    block.nVersion = 1;
+    block.nTime = IsTestNet() ? TESTNET_GENESIS_TIME : MAINNET_GENESIS_TIME;
+    block.nBits = 0x1f0fffff; // = bnProofOfWorkLimit (Bitflash RandomX floor)
+    block.nNonce = GENESIS_NONCE;
+    return block;
+}
+
 void SetParticipantMiningStatus(const std::string& status)
 {
     // Updates the GUI status string only. Logging is done at each call site
@@ -190,6 +401,9 @@ int ParticipantHashThreadCount()
     return nWorkers - 1;
 }
 
+static void SecureClearBytes(vector<unsigned char>& vch);
+static void SecureClearKeyingMaterial(CKeyingMaterial& vch);
+
 bool AddKey(const CKey& key)
 {
     if (IsWalletEncrypted())
@@ -199,9 +413,13 @@ bool AddKey(const CKey& key)
         vector<unsigned char> vchCryptedSecret;
         if (IsWalletLocked())
             return error("AddKey() : wallet is locked\n");
-        if (!EncryptSecret(vWalletMasterKey, vector<unsigned char>(vchPrivKey.begin(), vchPrivKey.end()),
-                           WalletKeyIV(key.GetPubKey()), vchCryptedSecret))
+        vector<unsigned char> vchPlainSecret(vchPrivKey.begin(), vchPrivKey.end());
+        if (!EncryptSecret(vWalletMasterKey, vchPlainSecret, WalletKeyIV(key.GetPubKey()), vchCryptedSecret))
+        {
+            SecureClearBytes(vchPlainSecret);
             return error("AddKey() : encrypting key failed\n");
+        }
+        SecureClearBytes(vchPlainSecret);
         if (!AddCryptedKey(key.GetPubKey(), vchCryptedSecret))
             return false;
         return CWalletDB().WriteCryptedKey(key.GetPubKey(), vchCryptedSecret);
@@ -225,17 +443,31 @@ bool IsWalletLocked()
     return fWalletEncrypted && fWalletLocked;
 }
 
+static void SecureClearBytes(vector<unsigned char>& vch)
+{
+    if (!vch.empty())
+        OPENSSL_cleanse(&vch[0], vch.size());
+    vch.clear();
+}
+
+static void SecureClearKeyingMaterial(CKeyingMaterial& vch)
+{
+    if (!vch.empty())
+        OPENSSL_cleanse(&vch[0], vch.size());
+    vch.clear();
+}
+
 void LockWallet()
 {
     if (!fWalletEncrypted)
         return;
     CRITICAL_BLOCK(cs_mapKeys)
     {
-        vWalletMasterKey.clear();
+        SecureClearKeyingMaterial(vWalletMasterKey);
         if (!vchCryptedHDMaster.empty())
-            vchHDMaster.clear();
+            SecureClearBytes(vchHDMaster);
         if (!vchCryptedHDChainCode.empty())
-            vchHDChainCode.clear();
+            SecureClearBytes(vchHDChainCode);
         fWalletLocked = true;
     }
 }
@@ -260,14 +492,14 @@ bool DeriveWalletPassphraseKey(const string& strPassphrase,
                            chKey, chIV);
     if (n != 32)
     {
-        memset(chKey, 0, sizeof(chKey));
-        memset(chIV, 0, sizeof(chIV));
+        OPENSSL_cleanse(chKey, sizeof(chKey));
+        OPENSSL_cleanse(chIV, sizeof(chIV));
         return false;
     }
     vchKeyRet.assign(chKey, chKey + sizeof(chKey));
     vchIVRet.assign(chIV, chIV + sizeof(chIV));
-    memset(chKey, 0, sizeof(chKey));
-    memset(chIV, 0, sizeof(chIV));
+    OPENSSL_cleanse(chKey, sizeof(chKey));
+    OPENSSL_cleanse(chIV, sizeof(chIV));
     return true;
 }
 
@@ -328,6 +560,8 @@ bool DecryptSecret(const CKeyingMaterial& vchKey,
         vchPlaintextRet.swap(vchOut);
         fOk = true;
     }
+    if (!fOk)
+        SecureClearBytes(vchOut);
     EVP_CIPHER_CTX_free(ctx);
     return fOk;
 }
@@ -403,6 +637,7 @@ bool GetWalletPrivKey(const vector<unsigned char>& vchPubKey,
         }
 
         CPrivKey vchPrivKey(vchPlaintext.begin(), vchPlaintext.end());
+        SecureClearBytes(vchPlaintext);
         CKey key;
         if (!key.SetPrivKey(vchPrivKey) || key.GetPubKey() != vchPubKey)
         {
@@ -437,11 +672,20 @@ bool UnlockWallet(const string& strPassphrase, string& strErrorRet)
             vector<unsigned char> vchMasterPlain;
             if (!DecryptSecret(vchPassKey, kMasterKey.vchCryptedKey,
                                vchPassIV, vchMasterPlain))
+            {
+                SecureClearBytes(vchPassIV);
                 continue;
+            }
             if (vchMasterPlain.size() != 32)
+            {
+                SecureClearBytes(vchMasterPlain);
+                SecureClearBytes(vchPassIV);
                 continue;
+            }
 
             CKeyingMaterial vchCandidate(vchMasterPlain.begin(), vchMasterPlain.end());
+            SecureClearBytes(vchMasterPlain);
+            SecureClearBytes(vchPassIV);
             bool fValid = mapCryptedKeys.empty();
             for (map<vector<unsigned char>, vector<unsigned char> >::iterator mci = mapCryptedKeys.begin();
                  mci != mapCryptedKeys.end(); ++mci)
@@ -450,6 +694,7 @@ bool UnlockWallet(const string& strPassphrase, string& strErrorRet)
                 if (!DecryptSecret(vchCandidate, (*mci).second, WalletKeyIV((*mci).first), vchPlaintext))
                     break;
                 CPrivKey vchPrivKey(vchPlaintext.begin(), vchPlaintext.end());
+                SecureClearBytes(vchPlaintext);
                 CKey key;
                 if (key.SetPrivKey(vchPrivKey) && key.GetPubKey() == (*mci).first)
                     fValid = true;
@@ -465,10 +710,12 @@ bool UnlockWallet(const string& strPassphrase, string& strErrorRet)
                                        WalletSecretIV("hdmaster"), vchPlainHDMaster) ||
                         vchPlainHDMaster.size() != 32)
                     {
+                        SecureClearBytes(vchPlainHDMaster);
                         strErrorRet = "could not decrypt HD master key";
                         return false;
                     }
                     vchHDMaster = vchPlainHDMaster;
+                    SecureClearBytes(vchPlainHDMaster);
                 }
                 if (!vchCryptedHDChainCode.empty())
                 {
@@ -477,10 +724,12 @@ bool UnlockWallet(const string& strPassphrase, string& strErrorRet)
                                        WalletSecretIV("hdchaincode"), vchPlainHDChainCode) ||
                         vchPlainHDChainCode.size() != 32)
                     {
+                        SecureClearBytes(vchPlainHDChainCode);
                         strErrorRet = "could not decrypt HD chain code";
                         return false;
                     }
                     vchHDChainCode = vchPlainHDChainCode;
+                    SecureClearBytes(vchPlainHDChainCode);
                 }
                 fWalletLocked = false;
                 return true;
@@ -625,7 +874,7 @@ unsigned int nHDNext = 0;
 int nHDKeySchema = HD_SCHEMA_NONE;
 unsigned int nHDReceiveNext = 0;
 unsigned int nHDChangeNext = 0;
-unsigned int nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL;
+unsigned int nHDCoinType = HD_BIP44_COIN_TYPE_BITFLASH;
 
 string HDKeySchemaName(int nSchema)
 {
@@ -781,7 +1030,7 @@ bool SetHDSeedFromMnemonic(const string& strMnemonic, string& strErrorRet)
 
         if (!CWalletDB().WriteHDMaster(master.privateKey, master.chainCode) ||
             !CWalletDB().WriteHDSchema(HD_SCHEMA_BIP44) ||
-            !CWalletDB().WriteHDCoinType(HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL) ||
+            !CWalletDB().WriteHDCoinType(HD_BIP44_COIN_TYPE_BITFLASH) ||
             !CWalletDB().WriteHDNext(0) ||
             !CWalletDB().WriteHDReceiveNext(1) ||
             !CWalletDB().WriteHDChangeNext(0))
@@ -794,7 +1043,7 @@ bool SetHDSeedFromMnemonic(const string& strMnemonic, string& strErrorRet)
         nHDKeySchema   = HD_SCHEMA_BIP44;
         nHDReceiveNext = 1;
         nHDChangeNext  = 0;
-        nHDCoinType    = HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL;
+        nHDCoinType    = HD_BIP44_COIN_TYPE_BITFLASH;
 
         // Index 0 is spoken for before it is derived, so a failure below cannot
         // leave the pool free to hand it out as an ordinary key. The cost of
@@ -1670,7 +1919,7 @@ void CWalletTx::RelayWalletTransaction(CTxDB& txdb)
         uint256 hash = GetHash();
         if (!txdb.ContainsTx(hash))
         {
-            if (LogAcceptsCategory("net")) printf("Relaying wtx %s\n", hash.ToString().substr(0,6).c_str());
+            if (LogAcceptsCategory("relay")) printf("Relaying wtx %s\n", hash.ToString().substr(0,6).c_str());
             RelayMessage(CInv(MSG_TX, hash), (CTransaction)*this);
         }
     }
@@ -2480,11 +2729,21 @@ string GetAppDir()
     {
         return ".";
     }
-    static bool fMkdirDone;
-    if (!fMkdirDone)
+    static string strCreatedBaseDir;
+    if (strCreatedBaseDir != strDir)
     {
-        fMkdirDone = true;
         _mkdir(strDir.c_str());
+        strCreatedBaseDir = strDir;
+    }
+    if (IsTestNet())
+    {
+        strDir += "/testnet";
+        static string strCreatedTestnetDir;
+        if (strCreatedTestnetDir != strDir)
+        {
+            _mkdir(strDir.c_str());
+            strCreatedTestnetDir = strDir;
+        }
     }
     return strDir;
 }
@@ -2636,22 +2895,36 @@ bool LoadBlockIndex(bool fAllowNew)
         //     CTxOut(nValue=50.00000000, scriptPubKey=0x5F1DF16B2B704C8A578D0B)
         //   vMerkleTree: 4a5e1e
 
-        // Bitflash genesis block -- own header (fair launch, 2026 stable relaunch)
-        char* pszTimestamp = "Bitflash 24/Jul/2026 Fair launch: one CPU one vote, no premine";
-        CTransaction txNew;
-        txNew.vin.resize(1);
-        txNew.vout.resize(1);
-        txNew.vin[0].scriptSig     = CScript() << 486604799 << CBigNum(4) << vector<unsigned char>((unsigned char*)pszTimestamp, (unsigned char*)pszTimestamp + strlen(pszTimestamp));
-        txNew.vout[0].nValue       = 50 * COIN;
-        txNew.vout[0].scriptPubKey = CScript() << CBigNum("0x5F1DF16B2B704C8A578D0BBAF74D385CDE12C11EE50455F3C438EF4C3FBCF649B6DE611FEAE06279A60939E028A8D65C10B73071A6F16719274855FEB0FD8A6704") << OP_CHECKSIG;
-        CBlock block;
-        block.vtx.push_back(txNew);
-        block.hashPrevBlock = 0;
-        block.hashMerkleRoot = block.BuildMerkleTree();
-        block.nVersion = 1;
-        block.nTime    = 1753315200; // 2026-07-24 00:00:00 UTC (stable relaunch)
-        block.nBits    = 0x1f0fffff; // = bnProofOfWorkLimit (Bitflash RandomX floor)
-        block.nNonce   = GENESIS_NONCE;
+        // Bitflash genesis block -- own header (fair launch)
+        //
+        // Upstream moved the construction into BuildGenesisBlock() so mainnet
+        // and the isolated testnet can share it. The mainnet inputs it uses are
+        // byte-identical to what this block built inline before the merge --
+        // timestamp string, nTime, nNonce, scriptPubKey, nBits and nVersion all
+        // verified equal against MAINNET_GENESIS_* -- so the mainnet genesis
+        // hash is unchanged. The warning below is why that was checked rather
+        // than assumed, and it still applies to those constants:
+        //
+        // Do not change MAINNET_GENESIS_TIMESTAMP, the scriptPubKey,
+        // MAINNET_GENESIS_TIME or MAINNET_GENESIS_NONCE. They are the inputs to
+        // the genesis hash, and the genesis hash is consensus. Changing one on
+        // its own trips the assert below, which is loud and reverts cleanly;
+        // changing one and regenerating GENESIS_NONCE and hashGenesisBlock to
+        // match -- which is exactly what the re-mining branch below prints out
+        // and invites -- gives a node that starts without complaint, builds its
+        // own chain from height 0, and rejects every real peer as being on a
+        // different chain. That one fails silently, and the damage scales with
+        // how many people run the "fixed" build.
+        //
+        // MAINNET_GENESIS_TIME is 1753315200, which is 2025-07-24T00:00:00Z,
+        // while the headline in MAINNET_GENESIS_TIMESTAMP reads 2026 -- as does
+        // the comment upstream put on that constant, which is wrong about the
+        // year. This is a known discrepancy and not a typo in the value: it is
+        // only consensus-critical as an input to the genesis hash, the block
+        // hashes to hashGenesisBlock with it, and every node on the network
+        // agrees. The mismatch is in the launched chain and cannot be corrected
+        // -- see the warning above before deciding otherwise.
+        CBlock block = BuildGenesisBlock();
 
         // If the nonce has not been found yet, mine the genesis once (RandomX)
         // and print the values to be hardcoded in the constants above.
@@ -2676,6 +2949,11 @@ bool LoadBlockIndex(bool fAllowNew)
             printf("powhash = %s\n", block.GetPoWHash().ToString().c_str());
             printf("hash    = %s\n", block.GetHash().ToString().c_str());
             printf("merkle  = %s\n", block.hashMerkleRoot.ToString().c_str());
+            printf("----------------------------------------\n");
+            printf("These constants bring up a NEW chain. Do not paste them\n");
+            printf("into a build for this network to make an edited nTime or\n");
+            printf("pszTimestamp fit -- a node whose genesis differs starts\n");
+            printf("cleanly on a chain of its own and rejects every real peer.\n");
             printf("========================================\n");
         }
 
@@ -3221,15 +3499,61 @@ bool ProcessMessage(CNode* pfrom, string strCommand, CDataStream& vRecv)
         vRecv >> *pblock;
 
         //// debug print
-        if (LogAcceptsCategory("net")) { printf("received block:\n"); pblock->print(); }
+        if (LogAcceptsCategory("relay")) { printf("received block:\n"); pblock->print(); }
 
         CInv inv(MSG_BLOCK, pblock->GetHash());
         pfrom->AddInventoryKnown(inv);
 
+        // GetHash() covers the 80-byte header and nothing else, so the hash
+        // coming out right does not make this the block we asked for. Every
+        // peer that saw X announced holds X's header, and can answer our
+        // getdata with that header bolted onto a transaction list of its own
+        // invention -- the reply still hashes to X. hashMerkleRoot is the only
+        // thing binding the header to the body, so check it here, before the
+        // mapBlockFetch entry is touched and before CheckBlock spends a
+        // RandomX hash on a body already known to be forged.
+        //
+        // There is no honest way to arrive here. Peer traffic rides the .btf
+        // channel, which is XChaCha20-Poly1305, so a body that arrives at all
+        // arrived intact: a mismatch is the peer's own construction, not line
+        // noise. Drop the peer and leave the fetch outstanding so the failover
+        // sweep asks somebody else for the real X, rather than recording X as
+        // delivered on the strength of a header anyone could copy.
+        if (pblock->hashMerkleRoot != pblock->BuildMerkleTree())
+        {
+            if (LogAcceptsCategory("net"))
+                printf("peer %s served a forged body for %s\n",
+                       pfrom->addr.ToString().c_str(), inv.ToString().c_str());
+            // One line per connection: ProcessMessages keeps draining the
+            // receive buffer after fDisconnect is set, so a peer that packs
+            // many forged bodies into one buffer must not get one log line
+            // for each of them.
+            if (!pfrom->fDisconnect)
+                printf("block fetch: a peer answered the request for %s with a body that is not "
+                       "that block -- dropping it\n", inv.hash.ToString().substr(0,14).c_str());
+            pfrom->fDisconnect = true;
+            return error("ProcessMessage() : forged block body for %s",
+                         inv.hash.ToString().substr(0,14).c_str());
+        }
+
         if (ProcessBlock(pfrom, pblock.release()))
         {
             mapAlreadyAskedFor.erase(inv);
 
+            // The body arrived and validated, so the fetch really is over:
+            // the block is now in mapBlockIndex, or parked in mapOrphanBlocks,
+            // and either way AlreadyHave answers for it from here on.
+            //
+            // This has to stay inside the success branch, next to the erase
+            // above. When validation rejects a body nothing is stored,
+            // AlreadyHave stays false, and the mapAskFor entry was already
+            // consumed when the getdata went out -- so erasing the tracking
+            // here would leave the block requested from nobody at all until
+            // some peer happened to re-announce it. That is exactly the stall
+            // of #33, and erasing before ProcessBlock made it reachable on
+            // demand.
+            mapBlockFetch.erase(inv.hash);
+
             // A peer that just handed us a block is demonstrably at least at
             // that block's height. Without this, nStartingHeight is a snapshot
             // taken once during the version handshake and never touched again,
@@ -3354,12 +3678,119 @@ bool SendMessages(CNode* pto)
             const CInv& inv = (*pto->mapAskFor.begin()).second;
             if (LogAcceptsCategory("net")) printf("sending getdata: %s\n", inv.ToString().c_str());
             if (!AlreadyHave(txdb, inv))
+            {
                 vAskFor.push_back(inv);
+                // Blocks get their delivery tracked so the failover pass
+                // below can chase the ones that go quiet.
+                if (inv.type == MSG_BLOCK)
+                {
+                    // Full, and this is a hash we are not already tracking:
+                    // make room rather than drop it on the floor, or one peer
+                    // announcing eight hashes turns failover off for everyone.
+                    if (!mapBlockFetch.count(inv.hash) &&
+                        mapBlockFetch.size() >= BLOCK_FETCH_TRACK_MAX)
+                        MakeRoomInBlockFetch(pto->addr);
+
+                    if (mapBlockFetch.count(inv.hash) ||
+                        mapBlockFetch.size() < BLOCK_FETCH_TRACK_MAX)
+                    {
+                        CBlockFetch& fetch = mapBlockFetch[inv.hash];
+                        if (fetch.nTimeFirstAsked == 0)
+                        {
+                            fetch.nTimeFirstAsked = GetTime();
+                            // Who is answerable for this hash existing. Set
+                            // once, on creation: the failover sweep asks other
+                            // peers later, and none of them chose to announce
+                            // it, so none of them should be charged for it.
+                            fetch.addrAnnounced = pto->addr;
+                        }
+                        fetch.nTimeAsked = GetTime();
+                        fetch.setAsked.insert(pto->addr);
+                    }
+                }
+            }
             pto->mapAskFor.erase(pto->mapAskFor.begin());
         }
         if (!vAskFor.empty())
             pto->PushMessage("getdata", vAskFor);
 
+
+        //
+        // Message: getdata (block fetch failover)
+        //
+        // A requested block that has not arrived in BLOCK_FETCH_RETRY_SECS is
+        // not still in transit -- a body is at most 1 MB and somebody
+        // demonstrably has it -- so ask somebody else instead of waiting on
+        // whoever was asked first (#33). Each peer the message handler visits
+        // takes at most one turn per block per round; once every connected
+        // peer has had its turn and a further interval passes with nobody
+        // new to ask, the round restarts. A peer that declared itself a
+        // client cannot serve block bodies and is no use as a target.
+        if (!pto->fClient)
+        {
+            vector<CInv> vFailover;
+            int64 nNowSecs = GetTime();
+            for (map<uint256, CBlockFetch>::iterator mi = mapBlockFetch.begin(); mi != mapBlockFetch.end();)
+            {
+                CBlockFetch& fetch = (*mi).second;
+                CInv inv(MSG_BLOCK, (*mi).first);
+                if (AlreadyHave(txdb, inv))
+                {
+                    // Arrived by some other road -- our own miner, an orphan
+                    // parked in mapOrphanBlocks. Nothing left to chase.
+                    mapBlockFetch.erase(mi++);
+                    continue;
+                }
+                if (nNowSecs - fetch.nTimeFirstAsked > BLOCK_FETCH_GIVEUP_SECS)
+                {
+                    printf("block fetch: giving up on %s -- no peer served it in %d s\n",
+                           inv.ToString().c_str(), (int)(nNowSecs - fetch.nTimeFirstAsked));
+                    mapBlockFetch.erase(mi++);
+                    continue;
+                }
+                if (nNowSecs - fetch.nTimeAsked >= BLOCK_FETCH_RETRY_SECS)
+                {
+                    // The handler loop visits every peer within ~100ms, so a
+                    // request stale by two full intervals means nobody outside
+                    // setAsked was there to ask. Start the round over.
+                    if (nNowSecs - fetch.nTimeAsked >= 2 * BLOCK_FETCH_RETRY_SECS)
+                        fetch.setAsked.clear();
+                    if (!fetch.setAsked.count(pto->addr))
+                    {
+                        // Which block, how long, and which peer we are trying
+                        // next. Behind the category because it names a peer
+                        // and a peer decides how often it is written.
+                        if (LogAcceptsCategory("net"))
+                            printf("block fetch failover: %s unanswered for %d s, re-requesting from %s\n",
+                                   inv.ToString().c_str(), (int)(nNowSecs - fetch.nTimeAsked),
+                                   pto->addr.ToString().c_str());
+
+                        // The unconditional half: no addresses, and at most
+                        // one line per BLOCK_FETCH_REPORT_SECS however hard a
+                        // peer tries. See the counters for the reasoning.
+                        nBlockFetchFailovers++;
+                        if (nNowSecs - nBlockFetchWindowStart >= BLOCK_FETCH_REPORT_SECS)
+                        {
+                            printf("block fetch: %d block request%s went unanswered and %s been "
+                                   "re-asked of other peers (%d tracked)\n",
+                                   nBlockFetchFailovers, nBlockFetchFailovers == 1 ? "" : "s",
+                                   nBlockFetchFailovers == 1 ? "has" : "have",
+                                   (int)mapBlockFetch.size());
+                            nBlockFetchWindowStart = nNowSecs;
+                            nBlockFetchFailovers   = 0;
+                        }
+
+                        vFailover.push_back(inv);
+                        fetch.nTimeAsked = nNowSecs;
+                        fetch.setAsked.insert(pto->addr);
+                    }
+                }
+                ++mi;
+            }
+            if (!vFailover.empty())
+                pto->PushMessage("getdata", vFailover);
+        }
+
     }
     return true;
 }
@@ -3620,6 +4051,14 @@ static void ParticipantHashWorker(ParticipantJobShared* sh, int idx, int nWorker
     RandomXDestroyMinerVM(vm);
 }
 
+// Run one participant session: resolve the pool, open the tunnel, subscribe,
+// hash, submit shares. Returns true only if the pool actually handed out work
+// -- at least one well-formed mining.notify arrived. Everything else is false,
+// including a tunnel that opened and was dropped before any job.
+//
+// The caller's reconnect backoff keys off this return value, so any path added
+// here that leaves the session without work MUST return false. "The session
+// ended tidily" is not the question being asked.
 static bool PoolParticipantMiner()
 {
     // ------------------------------------------------------------------
@@ -3697,6 +4136,33 @@ static bool PoolParticipantMiner()
     }
     LogPrint("worker", "[worker] pool resolved to meeting node %s\n", meetingHostPort.c_str());
 
+    // The descriptor names ONE meeting node, but the pool parks a
+    // registration at every relay it knows (one accept thread per relay,
+    // rpc.cpp:AcceptOneFn), so any seed relay can pair us. Insisting on the
+    // advertised entry forever turns one bad path into a miner that idles
+    // indefinitely while a working path exists (issue #17); after a few
+    // consecutive tunnel failures, rotate the seed relays into the attempts
+    // too. Only ONE participant session runs (StartMinerThreads), so these
+    // statics are single-threaded.
+    static const int TUNNEL_FAILOVER_AFTER = 3;
+    static int nTunnelFails = 0;      // consecutive tunnel failures, this pool
+    static size_t iFailoverRelay = 0; // rotation cursor over vBtfMeetingRelays
+    static std::string strFailPool;   // pool the counters belong to
+    if (strFailPool != strParticipantPool) {
+        strFailPool = strParticipantPool;
+        nTunnelFails = 0;
+        iFailoverRelay = 0;
+    }
+    if (nTunnelFails >= TUNNEL_FAILOVER_AFTER && !vBtfMeetingRelays.empty()) {
+        std::string alt = vBtfMeetingRelays[iFailoverRelay++ % vBtfMeetingRelays.size()];
+        if (alt != meetingHostPort) {
+            LogPrint("worker", "[worker] advertised meeting node %s failed %d"
+                     " times in a row -- trying seed relay %s instead\n",
+                     meetingHostPort.c_str(), nTunnelFails, alt.c_str());
+            meetingHostPort = alt;
+        }
+    }
+
     size_t colon = meetingHostPort.rfind(':');
     if (colon == std::string::npos) {
         LogPrint("worker", "[worker] bad meeting node format '%s'\n", meetingHostPort.c_str());
@@ -3716,15 +4182,18 @@ static bool PoolParticipantMiner()
     // Step 2b: open encrypted tunnel to pool
     // ------------------------------------------------------------------
     SetParticipantMiningStatus("opening tunnel");
+    btf::TunnelFail tunnelFail = btf::TUNNEL_FAIL_NONE;
     s = btf::BtfClientTunnel(host.c_str(), (unsigned short)port,
-                             target_pubkey, service_enc_pub);
+                             target_pubkey, service_enc_pub, &tunnelFail);
     if (s == INVALID_SOCKET) {
-        LogPrint("worker", "[worker] tunnel connect FAILED via %s"
-                 " (relay unreachable or pool not listening)\n",
-                 meetingHostPort.c_str());
-        SetParticipantMiningStatus("tunnel connect failed");
+        nTunnelFails++;
+        LogPrint("worker", "[worker] tunnel connect FAILED via %s: %s\n",
+                 meetingHostPort.c_str(), btf::TunnelFailText(tunnelFail));
+        SetParticipantMiningStatus(std::string("tunnel connect failed: ")
+                                   + btf::TunnelFailText(tunnelFail));
         return false;
     }
+    nTunnelFails = 0;
     LogPrint("worker", "[worker] tunnel open via %s\n", meetingHostPort.c_str());
     SetParticipantMiningStatus("tunnel open");
     }
@@ -3857,9 +4326,32 @@ connected:
     std::vector<ParticipantShareHit> shareHits;
     std::mutex shareHitsMtx;
     std::vector<std::thread> hashThreads;
-    for (int i = 0; i < nWorkers; i++)
-        hashThreads.emplace_back(ParticipantHashWorker, &jobShared, i, nWorkers,
-                                 &shareHits, &shareHitsMtx);
+    try
+    {
+        for (int i = 0; i < nWorkers; i++)
+            hashThreads.emplace_back(ParticipantHashWorker, &jobShared, i, nWorkers,
+                                     &shareHits, &shareHitsMtx);
+    }
+    catch (const std::system_error& e)
+    {
+        // A refused pthread_create used to reach std::terminate here and
+        // kill the worker mid-session -- observed twice on an otherwise
+        // healthy participant. Stop the workers that did start the same way
+        // the disconnect path below does, drop this pool connection, and let
+        // the caller's reconnect loop try again once the pressure clears.
+        LogPrint("worker", "[worker] cannot spawn hash threads (%s)"
+                 " -- dropping pool connection\n", e.what());
+        SetParticipantMiningStatus("hash thread spawn failed");
+        {
+            std::lock_guard<std::mutex> lk(jobShared.mtx);
+            jobShared.stop = true;
+            jobShared.haveJob = false;
+        }
+        for (std::thread& t : hashThreads)
+            t.join();
+        closesocket(s);
+        return false;
+    }
     LogPrint("worker", "[worker] spawned %d hash threads on shared RandomX dataset\n",
              nWorkers);
     const uint64 sessionStartHashes = gParticipantHashes.load();
@@ -3870,8 +4362,17 @@ connected:
     std::string jobId;
     unsigned char header[80] = {};
     uint256 target;
+    // Cached answer to "which block is this job built on", for the
+    // mining.notify handler below -- see the comment there. Session-local, so
+    // a reconnect re-resolves rather than trusting an answer obtained before
+    // a possible change of pool.
+    uint256 hashPrevResolved;           // prevhash the cached answer describes
+    bool fPrevResolved       = false;   // whether that answer exists yet
+    int  nPrevHeight         = -1;      // its height, or -1 == unknown to us
+    int  nBestHeightResolved = -1;      // nBestHeight when we last resolved
     double currentDifficulty = 1.0; // updated by mining.set_difficulty from pool
     bool haveJob         = false;
+    bool gotAnyJob       = false; // any job at all this session -- the return value
     bool gotSubscribeAck = false;
     bool gotAuthorizeAck = false;
     int64 authWaitStart  = 0;
@@ -3988,8 +4489,9 @@ connected:
                                     jobId = newJobId;
                                     memcpy(header, hdrBytes.data(), 80);
                                     memcpy(&target, tgtBytes.data(), 32);
-                                    haveJob = true;
-                                    nNonce  = 1;
+                                    haveJob   = true;
+                                    gotAnyJob = true;
+                                    nNonce    = 1;
                                     {
                                         std::lock_guard<std::mutex> lk(jobShared.mtx);
                                         memcpy(jobShared.header, header, 80);
@@ -3998,8 +4500,64 @@ connected:
                                         jobShared.jobSeq++;
                                         jobShared.haveJob = true;
                                     }
-                                    LogPrint("worker", "[pool->worker] new job %s received\n",
-                                             jobId.c_str());
+                                    // Log the chain position the pool is
+                                    // building on, so a stale or private
+                                    // fork is auditable from worker logs.
+                                    // The prevhash comes from the header we
+                                    // actually hash (== p[2] of the notify);
+                                    // a brief cs_main lookup is safe here --
+                                    // this thread holds no other lock.
+                                    //
+                                    // Resolving it is the expensive half, and
+                                    // this is the socket-reading thread: block
+                                    // validation can hold cs_main for a long
+                                    // time, and every moment spent waiting on
+                                    // it here is a moment set_difficulty and
+                                    // share responses are not being handled.
+                                    // Most notifies in a round are a new job
+                                    // on the SAME tip, so the answer is cached
+                                    // and re-resolved only when it could come
+                                    // out differently: a prevhash we have not
+                                    // resolved, or one we could NOT resolve
+                                    // last time while the chain has since
+                                    // moved (unknown -> known). A block's
+                                    // height is fixed once mapBlockIndex knows
+                                    // it, so a cached "known" never goes
+                                    // stale. nBestHeight is read unlocked on
+                                    // purpose -- it only decides whether to
+                                    // repeat a lookup, never what gets
+                                    // printed, so a stale read costs at most
+                                    // one deferred or one extra lookup.
+                                    // The line still prints in full for every
+                                    // job, cached or not.
+                                    uint256 hashPrev;
+                                    memcpy(&hashPrev, header + 4, 32);
+                                    if (LogAcceptsCategory("worker"))
+                                    {
+                                        int nBestHeightNow = nBestHeight;
+                                        if (!fPrevResolved
+                                            || hashPrev != hashPrevResolved
+                                            || (nPrevHeight < 0 && nBestHeightNow != nBestHeightResolved))
+                                        {
+                                            nPrevHeight = -1;
+                                            CRITICAL_BLOCK(cs_main)
+                                            {
+                                                map<uint256, CBlockIndex*>::iterator mi = mapBlockIndex.find(hashPrev);
+                                                if (mi != mapBlockIndex.end())
+                                                    nPrevHeight = (*mi).second->nHeight;
+                                            }
+                                            hashPrevResolved    = hashPrev;
+                                            nBestHeightResolved = nBestHeightNow;
+                                            fPrevResolved       = true;
+                                        }
+                                        if (nPrevHeight >= 0)
+                                            LogPrint("worker", "[pool->worker] new job %s received, prevhash %s (known, job height %d)\n",
+                                                     jobId.c_str(), hashPrev.GetHex().c_str(),
+                                                     nPrevHeight + 1);
+                                        else
+                                            LogPrint("worker", "[pool->worker] new job %s received, prevhash %s (unknown to our chain)\n",
+                                                     jobId.c_str(), hashPrev.GetHex().c_str());
+                                    }
                                     SetParticipantMiningStatus("hashing job " + jobId);
                                 }
                             }
@@ -4125,9 +4683,197 @@ connected:
              (unsigned long long)hashesSinceSample,
              (unsigned long long)sessionSharesSent,
              (unsigned long long)sessionSharesAccepted);
+    // Not "we got here", which is true of a tunnel the pool accepted and then
+    // dropped without ever sending a job -- exactly the case the caller's
+    // backoff exists for. Reaching the end of the session is not evidence the
+    // session was worth anything; a job is.
+    return gotAnyJob;
+}
+
+// ---------------------------------------------------------------------------
+// Local Stratum bridge -- lets external miners speak plain Stratum to
+// 127.0.0.1 while Bitflash opens the .btf tunnel to the selected pool.
+// ---------------------------------------------------------------------------
+
+struct StratumBridgeClientCtx
+{
+    SOCKET miner;
+    std::string pool;
+};
+
+static bool BridgeSendAll(SOCKET s, const char* p, int n)
+{
+    int off = 0;
+    while (off < n)
+    {
+        int r = send(s, p + off, n - off, 0);
+        if (r <= 0)
+            return false;
+        off += r;
+    }
     return true;
 }
 
+static void BridgePump(SOCKET a, SOCKET b)
+{
+    char buf[8192];
+    while (!fShutdown)
+    {
+        fd_set rd;
+        FD_ZERO(&rd);
+        FD_SET(a, &rd);
+        FD_SET(b, &rd);
+        SOCKET maxfd = a > b ? a : b;
+        struct timeval tv = {1, 0};
+        int r = select((int)maxfd + 1, &rd, NULL, NULL, &tv);
+        if (r <= 0)
+            continue;
+
+        if (FD_ISSET(a, &rd))
+        {
+            int n = recv(a, buf, sizeof(buf), 0);
+            if (n <= 0 || !BridgeSendAll(b, buf, n))
+                break;
+        }
+        if (FD_ISSET(b, &rd))
+        {
+            int n = recv(b, buf, sizeof(buf), 0);
+            if (n <= 0 || !BridgeSendAll(a, buf, n))
+                break;
+        }
+    }
+}
+
+static void ThreadStratumBridgeClient(void* arg)
+{
+    StratumBridgeClientCtx* ctx = (StratumBridgeClientCtx*)arg;
+    SOCKET miner = ctx->miner;
+    std::string pool = ctx->pool;
+    delete ctx;
+
+    unsigned char target_pubkey[32];
+    if (!btf::ParseAddress(pool, target_pubkey))
+    {
+        LogPrint("worker", "[bridge] invalid pool .btf address: %s\n", pool.c_str());
+        BtfCloseSocket(miner);
+        return;
+    }
+
+    std::string meetingHostPort;
+    unsigned char service_enc_pub[32];
+    if (!BtfResolve(pool, meetingHostPort, service_enc_pub))
+    {
+        LogPrint("worker", "[bridge] failed to resolve pool %s\n", pool.c_str());
+        BtfCloseSocket(miner);
+        return;
+    }
+
+    size_t colon = meetingHostPort.rfind(':');
+    if (colon == std::string::npos)
+    {
+        LogPrint("worker", "[bridge] bad pool endpoint '%s'\n", meetingHostPort.c_str());
+        BtfCloseSocket(miner);
+        return;
+    }
+    std::string host = meetingHostPort.substr(0, colon);
+    int port = atoi(meetingHostPort.substr(colon + 1).c_str());
+    if (port <= 0 || port > 65535)
+    {
+        LogPrint("worker", "[bridge] bad pool port in '%s'\n", meetingHostPort.c_str());
+        BtfCloseSocket(miner);
+        return;
+    }
+
+    SOCKET poolSock = btf::BtfClientTunnel(host.c_str(), (unsigned short)port,
+                                           target_pubkey, service_enc_pub);
+    if (poolSock == INVALID_SOCKET)
+    {
+        LogPrint("worker", "[bridge] tunnel connect failed for pool %s via %s\n",
+                 pool.c_str(), meetingHostPort.c_str());
+        BtfCloseSocket(miner);
+        return;
+    }
+
+    LogPrint("worker", "[bridge] miner connected to pool %s via %s\n",
+             pool.c_str(), meetingHostPort.c_str());
+    BridgePump(miner, poolSock);
+    BtfCloseSocket(poolSock);
+    BtfCloseSocket(miner);
+    LogPrint("worker", "[bridge] miner disconnected from pool %s\n", pool.c_str());
+}
+
+void ThreadStratumBridge(void*)
+{
+    if (strParticipantPool.empty())
+    {
+        printf("Stratum bridge: no pool selected. Use /stratumbridge=POOL_BTF_ADDRESS\n");
+        return;
+    }
+
+    SOCKET listener = BtfSocketTag(socket(AF_INET, SOCK_STREAM, IPPROTO_TCP),
+                                   SOCK_STRATUM_BRIDGE);
+    if (listener == INVALID_SOCKET)
+    {
+        printf("Stratum bridge: could not create listen socket\n");
+        return;
+    }
+
+    int yes = 1;
+    setsockopt(listener, SOL_SOCKET, SO_REUSEADDR, (char*)&yes, sizeof(yes));
+
+    sockaddr_in addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = htonl(0x7f000001);
+    addr.sin_port = htons((unsigned short)nStratumBridgePort);
+
+    if (bind(listener, (sockaddr*)&addr, sizeof(addr)) != 0 ||
+        listen(listener, 16) != 0)
+    {
+        printf("Stratum bridge: could not listen on 127.0.0.1:%d\n",
+               nStratumBridgePort);
+        BtfCloseSocket(listener);
+        return;
+    }
+
+    printf("Stratum bridge: listening on 127.0.0.1:%d for pool %s\n",
+           nStratumBridgePort, strParticipantPool.c_str());
+
+    while (!fShutdown)
+    {
+        fd_set rd;
+        FD_ZERO(&rd);
+        FD_SET(listener, &rd);
+        struct timeval tv = {1, 0};
+        if (select((int)listener + 1, &rd, NULL, NULL, &tv) <= 0)
+            continue;
+
+        sockaddr_in cli;
+#ifdef _WIN32
+        int len = sizeof(cli);
+#else
+        socklen_t len = sizeof(cli);
+#endif
+        SOCKET miner = BtfSocketTag(accept(listener, (sockaddr*)&cli, &len),
+                                    SOCK_STRATUM_BRIDGE);
+        if (miner == INVALID_SOCKET)
+            continue;
+
+        StratumBridgeClientCtx* ctx = new StratumBridgeClientCtx();
+        ctx->miner = miner;
+        ctx->pool = strParticipantPool;
+        if (_beginthread(ThreadStratumBridgeClient, 0, ctx) == (uintptr_t)-1)
+        {
+            delete ctx;
+            BtfCloseSocket(miner);
+            LogPrint("worker", "[bridge] failed to spawn client thread\n");
+        }
+    }
+
+    BtfCloseSocket(listener);
+    printf("Stratum bridge: stopped\n");
+}
+
 bool BitcoinMiner(int nThreadId)
 {
     // Relay mode: never mines, just relays/syncs. (Shouldn't normally get here
@@ -4138,11 +4884,51 @@ bool BitcoinMiner(int nThreadId)
     // Participant mode: connect to external pool instead of mining solo/operator
     if (nMineMode == MINE_PARTICIPANT)
     {
+        // An attempt that never got work backs off (10s doubling to 120s)
+        // instead of hammering the same path every flat 10s, and a streak
+        // lasting minutes is said at printf level: the identical once-per-10s
+        // LogPrint line is how a worker idled all night unnoticed (issue #17).
+        //
+        // Only a session the pool actually sent a job to resets either. The
+        // weaker test -- "the session returned" -- was gameable: a pool that
+        // completes the tunnel and drops without ever sending work leaves by
+        // the same tidy cleanup path a healthy one does, which would pin the
+        // retry at 10s forever and defeat the backoff in exactly the scenario
+        // it exists for.
+        int   nRetrySecs    = 10;
+        int64 nFailingSince = 0;
         while (fGenerateBitcoins && nMineMode == MINE_PARTICIPANT && !fShutdown) {
-            PoolParticipantMiner();
+            bool fGotWork = PoolParticipantMiner();
             if (fGenerateBitcoins && nMineMode == MINE_PARTICIPANT && !fShutdown) {
-                LogPrint("worker", "PoolParticipantMiner: reconnecting in 10s\n");
-                for (int i = 0; i < 10 && !fShutdown; i++) Sleep(1000);
+                if (fGotWork) {
+                    nRetrySecs    = 10;
+                    nFailingSince = 0;
+                } else {
+                    if (nFailingSince == 0)
+                        nFailingSince = GetTime();
+                    int64 nMins = (GetTime() - nFailingSince) / 60;
+                    if (nMins >= 1)
+                        printf("[worker] connection to pool %s has been failing"
+                               " for %lld minutes\n",
+                               strParticipantPool.c_str(), (long long)nMins);
+                }
+                LogPrint("worker", "PoolParticipantMiner: reconnecting in %ds\n",
+                         nRetrySecs);
+                // Poll everything the enclosing while polls, not just
+                // fShutdown. Raising the ceiling to 120s made a
+                // shutdown-only predicate expensive: after the operator
+                // clears Generate or switches to Relay, the session -- and
+                // the vfThreadRunning[3] slot that gates restarting it --
+                // would stay held for up to two minutes. Measured 119s
+                // before, 1s after.
+                for (int i = 0; i < nRetrySecs && !fShutdown && fGenerateBitcoins
+                                && nMineMode == MINE_PARTICIPANT; i++)
+                    Sleep(1000);
+                if (!fGotWork && nRetrySecs < 120) {
+                    nRetrySecs *= 2;
+                    if (nRetrySecs > 120)
+                        nRetrySecs = 120;
+                }
             }
         }
         return true;
@@ -4244,7 +5030,6 @@ bool BitcoinMiner(int nThreadId)
             map<uint256, CTxIndex> mapTestPool;
             vector<char> vfAlreadyAdded(mapTransactions.size());
             bool fFoundSomething = true;
-            unsigned int nBlockSize = 0;
             // Assembly must stop below the consensus cap that CheckBlock()
             // enforces, or we mine a block our own node then rejects.
             //
@@ -4255,9 +5040,30 @@ bool BitcoinMiner(int nThreadId)
             // meant solving a block and throwing it away -- with this pool at
             // ~90% of hashrate, that is the network stalling, not just us.
             //
-            // Half the cap, keeping the original margin: the test runs before
-            // a transaction is added, so the loop can overshoot by one tx.
-            while (fFoundSomething && nBlockSize < MAX_BLOCK_SIZE/2)
+            // The budget test then sat only on this outer while, and the
+            // comment claimed that bounded the overshoot to a single
+            // transaction. It did not. The inner for walks all of
+            // mapTransactions with no test of its own, so one pass could append
+            // the entire mempool: the overshoot was bounded by mempool size,
+            // which is to say not bounded at all. Ask per transaction, before
+            // appending, and the overshoot is zero rather than small.
+            //
+            // Seeded with what the block already weighs -- header, tx count,
+            // coinbase -- because CheckBlock() weighs the whole serialized
+            // block and not just the transactions we chose to add to it.
+            unsigned int nBlockSize = ::GetSerializeSize(*pblock, SER_DISK);
+            // Sigops are a budget too, and CheckBlock() enforces one that no
+            // assembler here counted against. Bytes do not bound validation
+            // cost: every OP_CHECKSIG is an elliptic-curve verification, so a
+            // template well inside the size limit can still be refused for
+            // demanding more work than a block is allowed to. Counted with
+            // CTransaction::GetSigOpCount, the function CheckBlock() itself
+            // sums, so the two cannot disagree about what a transaction costs.
+            //
+            // Seeded from the coinbase because CheckBlock() sums over all of
+            // vtx, coinbase included.
+            unsigned int nBlockSigOps = pblock->vtx[0].GetSigOpCount();
+            while (fFoundSomething && nBlockSize < MAX_BLOCK_SIZE_GEN)
             {
                 fFoundSomething = false;
                 unsigned int n = 0;
@@ -4269,6 +5075,29 @@ bool BitcoinMiner(int nThreadId)
                     if (tx.IsCoinBase() || !tx.IsFinal())
                         continue;
 
+                    // Skip, not break: a transaction too big for the room left
+                    // says nothing about the next one, which may still fit.
+                    //
+                    // This is also the only ceiling on a single transaction's
+                    // size anywhere on the path into a block. CheckTransaction
+                    // does not cap it and neither does AcceptTransaction, so
+                    // the mempool will hold one of any size the wire allows;
+                    // without this test a lone 1.5 MB transaction offering a
+                    // fat fee is selected, and every template built from that
+                    // mempool is one CheckBlock() throws away. The fee is never
+                    // paid, because the block never confirms.
+                    //
+                    // Deliberately before ConnectInputs and not after:
+                    // ConnectInputs adds this transaction's fee to nFees by
+                    // reference on success. Passing it and then declining the
+                    // transaction would credit the coinbase for a fee no
+                    // transaction in the block pays, and the block would be
+                    // rejected for a wholly different reason.
+                    unsigned int nTxSize   = ::GetSerializeSize(tx, SER_NETWORK);
+                    unsigned int nTxSigOps = tx.GetSigOpCount();
+                    if (!BlockTemplateFits(nBlockSize, nBlockSigOps, nTxSize, nTxSigOps))
+                        continue;
+
                     // Transaction fee requirements, mainly only needed for flood control
                     // Under 10K (about 80 inputs) is free for first 100 transactions
                     // Base rate is 0.01 per KB
@@ -4280,7 +5109,8 @@ bool BitcoinMiner(int nThreadId)
                     swap(mapTestPool, mapTestPoolTmp);
 
                     pblock->vtx.push_back(tx);
-                    nBlockSize += ::GetSerializeSize(tx, SER_NETWORK);
+                    nBlockSize   += nTxSize;
+                    nBlockSigOps += nTxSigOps;
                     vfAlreadyAdded[n] = true;
                     fFoundSomething = true;
                 }
@@ -4329,7 +5159,7 @@ bool BitcoinMiner(int nThreadId)
                     //// debug print
                     if (LogAcceptsCategory("net")) printf("BitcoinMiner:\n");
                     if (LogAcceptsCategory("net")) printf("RandomX proof-of-work found  \n  powhash: %s  \ntarget: %s\n", hash.GetHex().c_str(), hashTarget.GetHex().c_str());
-                    if (LogAcceptsCategory("net")) pblock->print();
+                    if (LogAcceptsCategory("relay")) pblock->print();
 
                 SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_NORMAL);
                 CRITICAL_BLOCK(cs_main)
@@ -4435,6 +5265,9 @@ WalletRecoveryAudit GetWalletRecoveryAudit()
     CRITICAL_BLOCK(cs_keyPool)
     {
         audit.fHaveSeed = HaveHDSeed();
+        audit.fSeedEncryptedLocked = !audit.fHaveSeed &&
+                                     (!vchCryptedHDMaster.empty() ||
+                                      !vchCryptedHDChainCode.empty());
         audit.nSchema = nHDKeySchema;
         audit.nDerivedKnown = nHDNext;
         audit.nReceiveNext = nHDReceiveNext;
@@ -4681,9 +5514,17 @@ bool SelectCoins(int64 nTargetValue, set<CWalletTx*>& setCoinsRet)
 
 
 
-bool CreateTransaction(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew, int64& nFeeRequiredRet)
+// presultRet, when given, says WHY this returned false: the caller cannot work
+// it out afterwards. "Coin selection came up short" and "the wallet could not
+// build the transaction" are indistinguishable from the outside -- both are
+// just `false` -- and the difference decides whether a pool defers a payment
+// or counts it against the payment's retry budget. See WalletSendResult.
+bool CreateTransaction(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew, int64& nFeeRequiredRet,
+                       WalletSendResult* presultRet)
 {
     nFeeRequiredRet = 0;
+    if (presultRet)
+        *presultRet = WALLET_SEND_FAILED;
     CRITICAL_BLOCK(cs_main)
     {
         // txdb must be opened before the mapWallet lock
@@ -4714,10 +5555,21 @@ bool CreateTransaction(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew, in
                 // fixed this in 107d9e288.
                 int64 nTotalValue = nValue + nFee;
 
-                // Choose coins to use
+                // Choose coins to use.
+                //
+                // Failing here is a funding shortfall and nothing else: there
+                // is not enough spendable coin for nValue plus the fee this
+                // pass is working with. On the second and later passes that
+                // fee is GetMinFee() of the transaction the first pass built,
+                // so this is also how a wallet that can afford the amount but
+                // not the 11 * CENT charged at 10,000 bytes reports itself.
                 set<CWalletTx*> setCoins;
                 if (!SelectCoins(nTotalValue, setCoins))
+                {
+                    if (presultRet)
+                        *presultRet = WALLET_SEND_INSUFFICIENT_FUNDS;
                     return false;
+                }
                 int64 nValueIn = 0;
                 foreach(CWalletTx* pcoin, setCoins)
                     nValueIn += pcoin->GetCredit();
@@ -4787,6 +5639,8 @@ bool CreateTransaction(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew, in
             }
         }
     }
+    if (presultRet)
+        *presultRet = WALLET_SEND_OK;
     return true;
 }
 
@@ -4849,13 +5703,24 @@ bool CommitTransactionSpent(const CWalletTx& wtxNew)
 
 
 
-bool SendMoney(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew)
+// outcomeRet reports what happened rather than only whether it worked. A
+// caller that has to decide what a failure MEANS -- the pool payout thread --
+// cannot reconstruct it from a balance reading afterwards, because the fee
+// that was actually required depends on the size of a transaction that was
+// never built. See WalletSendResult.
+bool SendMoney(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew,
+               SendMoneyOutcome& outcomeRet)
 {
+    outcomeRet.result       = WALLET_SEND_FAILED;
+    outcomeRet.nFeeRequired = 0;
     CRITICAL_BLOCK(cs_main)
     {
         int64 nFeeRequired;
-        if (!CreateTransaction(scriptPubKey, nValue, wtxNew, nFeeRequired))
+        WalletSendResult createResult = WALLET_SEND_FAILED;
+        if (!CreateTransaction(scriptPubKey, nValue, wtxNew, nFeeRequired, &createResult))
         {
+            outcomeRet.result       = createResult;
+            outcomeRet.nFeeRequired = nFeeRequired;
             string strError;
             if (nValue + nFeeRequired > GetBalance())
                 // Not an oversized transaction -- this branch is simply "the
@@ -4893,6 +5758,13 @@ bool SendMoney(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew)
         }
         wtxNew.RelayWalletTransaction();
     }
+    outcomeRet.result = WALLET_SEND_OK;
     MainFrameRepaint();
     return true;
 }
+
+bool SendMoney(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew)
+{
+    SendMoneyOutcome ignored;
+    return SendMoney(scriptPubKey, nValue, wtxNew, ignored);
+}
diff --git a/src/main.h b/src/main.h
index 27f89ac..26b3b69 100644
--- a/src/main.h
+++ b/src/main.h
@@ -33,6 +33,35 @@ static const unsigned int MAX_BLOCK_SIGOPS = 20000;
 // limit (32 MB), not a block rule. Bitcoin 0.1.0 predated the later 1 MB block
 // cap, so this tree inherited no real block-size consensus limit.
 static const unsigned int MAX_BLOCK_SIZE = 1000000;
+// How much of that cap a template we build may fill. Half, which is what both
+// assemblers already aimed at -- this only gives the number a name and one
+// place to live. They had already drifted on how it was enforced, which is the
+// bug this exists to stop repeating.
+//
+// NOT a consensus rule. CheckBlock() decides what the network accepts; this
+// decides what we are willing to produce, and it has to stay under that.
+static const unsigned int MAX_BLOCK_SIZE_GEN = MAX_BLOCK_SIZE / 2;
+
+// Room for one more transaction in a template that currently weighs
+// nBlockSize bytes and spends nBlockSigOps signature operations?
+//
+// Asked BEFORE the transaction is appended, never after. A template that has
+// already overshot is one CheckBlock() rejects, and asking afterwards only
+// measures the waste. Both assemblers call this, so neither can drift into a
+// different idea of what fits.
+//
+// Size gets a margin (half the cap); sigops do not. There is no cheap way to
+// spend the sigop budget usefully and no reason to reserve headroom in it, so
+// assembly holds itself to the same number CheckBlock() enforces -- and to the
+// same comparison. CheckBlock() fails on `> MAX_BLOCK_SIGOPS`, so a block
+// sitting exactly on the limit is valid and this has to accept it too.
+// Assembly and validation disagreeing by one is how the size bug started.
+inline bool BlockTemplateFits(unsigned int nBlockSize, unsigned int nBlockSigOps,
+                              unsigned int nTxSize, unsigned int nTxSigOps)
+{
+    return (nBlockSize + nTxSize <= MAX_BLOCK_SIZE_GEN &&
+            nBlockSigOps + nTxSigOps <= MAX_BLOCK_SIGOPS);
+}
 static const int64 COIN = 100000000;
 // Total Bitflash emission: identical to Bitcoin (21 million).
 // MAX_MONEY guards against the value overflow bug (CVE-2010-5139), which in
@@ -65,6 +94,8 @@ extern map<uint256, CBlockIndex*> mapBlockIndex;
 extern uint256 hashGenesisBlock;
 extern uint256 hashGenesisMerkleRoot;
 extern unsigned int GENESIS_NONCE;
+void SelectGenesisParams(bool fTestNetIn);
+void SelectChainParams(bool fTestNetIn);
 extern CBlockIndex* pindexGenesisBlock;
 extern int nBestHeight;
 extern uint256 hashBestChain;
@@ -97,7 +128,11 @@ extern bool   fPoolMineBlind;       // /poolmineblind: mine on even when deaf to
 extern int    nHashThreads;       // participant: /hashthreads override (0 = cores-1)
 extern string strPoolName;        // operator: announced pool name
 extern string strPoolDashboardUrl; // operator: optional dashboard URL
+extern string strPoolStatusFile;   // operator: optional JSON status output path
+extern string strPoolRoundsFile;   // operator: optional public round proof path
 extern double dPoolFeePercent;     // operator: announced fee percent
+extern bool   fStratumBridge;      // participant helper: local Stratum bridge
+extern int    nStratumBridgePort;  // local bridge listen port, default 3333
 extern bool fSoloMineTest; // /solomine: mine without requiring a peer (local test)
 // Threads to hash with; 0 = decide from the hardware. Set by /genproclimit.
 extern int nMinerThreads;
@@ -226,9 +261,9 @@ static const unsigned int HD_BIP44_PURPOSE = 44;
 static const unsigned int HD_BIP44_ACCOUNT = 0;
 static const unsigned int HD_BIP44_CHAIN_RECEIVE = 0;
 static const unsigned int HD_BIP44_CHAIN_CHANGE = 1;
-// Provisional until Bitflash has an official SLIP-0044 assignment.
-// Proposed registry row: 4346950 | BITFLASH | Bitflash.
-static const unsigned int HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL = 4346950;
+// Official SLIP-0044 assignment (registered 2026-08-07):
+// 4346950 | BITFLASH | Bitflash   (4346950 == 0x425446 == "BTF")
+static const unsigned int HD_BIP44_COIN_TYPE_BITFLASH = 4346950;
 extern int nHDKeySchema;
 extern unsigned int nHDReceiveNext;            // BIP44 external chain
 extern unsigned int nHDChangeNext;             // BIP44 internal chain
@@ -285,6 +320,7 @@ void LimitOrphanBlocks(unsigned int nMaxOrphans);
 // distinguishable, which the dedup filter would otherwise collapse into one.
 bool BitcoinMiner(int nThreadId = 1);
 void ThreadRPCServer(void* parg);  // rpc.cpp -- .btf pool server
+void ThreadStratumBridge(void* parg); // main.cpp -- local Stratum -> .btf bridge
 void GetParticipantMiningStats(uint64& sharesSent, uint64& sharesAccepted, double& hashRate);
 void SetParticipantMiningStatus(const std::string& status);
 std::string GetParticipantMiningStatus();
@@ -301,6 +337,7 @@ int64 GetBalance();
 struct WalletRecoveryAudit
 {
     bool fHaveSeed;
+    bool fSeedEncryptedLocked;
     bool fDeriveComplete;
     int nSchema;
     unsigned int nDerivedKnown;
@@ -320,12 +357,13 @@ struct WalletRecoveryAudit
     WalletRecoveryAudit()
     {
         fHaveSeed = false;
+        fSeedEncryptedLocked = false;
         fDeriveComplete = true;
         nSchema = HD_SCHEMA_NONE;
         nDerivedKnown = 0;
         nReceiveNext = 0;
         nChangeNext = 0;
-        nCoinType = HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL;
+        nCoinType = HD_BIP44_COIN_TYPE_BITFLASH;
         nRecoverableTx = 0;
         nLegacyTx = 0;
         nRecoverableImmatureTx = 0;
@@ -337,9 +375,52 @@ struct WalletRecoveryAudit
     }
 };
 WalletRecoveryAudit GetWalletRecoveryAudit();
-bool CreateTransaction(CScript scriptPubKey, int64 nValue, CWalletTx& txNew, int64& nFeeRequiredRet);
+
+// Why a send did not go through.
+//
+// The pool's payout thread has to decide, on every failed SendMoney, whether
+// the failure was the wallet's condition (wait for it to change) or a fault
+// (something is wrong with this payment). It used to guess by re-reading
+// GetBalance() afterwards and allowing a fixed CENT of headroom for the fee.
+// That cannot work: the fee here is a step function of the SERIALISED SIZE of
+// a transaction that no longer exists, and the step is from 0 to 11 * CENT at
+// 10,000 bytes -- so a one-CENT allowance is either unnecessary or an order of
+// magnitude short, never right. A pool wallet close to broke selects many
+// small inputs BECAUSE it is close to broke, which is what pushes the
+// transaction over 10 KB, so the guess is wrong exactly when the money is
+// tight.
+//
+// The wallet already knows the answer; it just did not say. SelectCoins()
+// failing is "there is not enough spendable coin to cover the amount plus
+// whatever fee this size of transaction requires", and it is the only reason
+// CreateTransaction() can fail that is about funding rather than about the
+// wallet being broken.
+enum WalletSendResult
+{
+    WALLET_SEND_OK = 0,
+    WALLET_SEND_INSUFFICIENT_FUNDS, // coin selection could not cover amount+fee
+    WALLET_SEND_FAILED              // anything else: could not build, sign or accept
+};
+
+// What the wallet did with a send request. nFeeRequired is the fee the
+// transaction turned out to need, which for a failed send is what coin
+// selection was asked for on top of the amount and could not find -- 0 if it
+// never got that far.
+struct SendMoneyOutcome
+{
+    WalletSendResult result       = WALLET_SEND_OK;
+    int64            nFeeRequired = 0;
+};
+
+bool CreateTransaction(CScript scriptPubKey, int64 nValue, CWalletTx& txNew, int64& nFeeRequiredRet,
+                       WalletSendResult* presultRet=NULL);
 bool CommitTransactionSpent(const CWalletTx& wtxNew);
+// The three-argument form is kept, and kept as a distinct declaration rather
+// than a defaulted argument, because gui.cpp declares SendMoney itself instead
+// of including this header.
 bool SendMoney(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew);
+bool SendMoney(CScript scriptPubKey, int64 nValue, CWalletTx& wtxNew,
+               SendMoneyOutcome& outcomeRet);
 
 
 
diff --git a/src/main_gui.cpp b/src/main_gui.cpp
index bee4b95..2e4eb91 100644
--- a/src/main_gui.cpp
+++ b/src/main_gui.cpp
@@ -1,7 +1,10 @@
 // Bitflash entry point -- starts node threads then runs GUI (or headless).
 
 #include "headers_core.h"
+#include "nostr.h"
+#include "proxy.h"
 #include "selftest.h"
+#include "tor.h"
 #include "walletcmd.h"
 #include <thread>          // hardware_concurrency, to sanity-check /genproclimit
 #ifndef _WIN32
@@ -108,9 +111,16 @@ static void PrintUsage()
     printf("  /help, -help, --help, /?\n");
     printf("  /datadir=PATH\n");
     printf("  /debug\n");
+    printf("  /debugrelay                (/debug plus per-message relay chatter and block dumps)\n");
+    printf("  /maxdebugfilesize=N        (roll debug.log at N MB, default 1024; 0 = never)\n");
     printf("  /gen\n");
     printf("  /nogui or /daemon\n");
-    printf("  /selftest=wallet-keypool, wallet-hd, wallet-format, wallet-crypto, or wallet-encrypt\n");
+    printf("  /selftest=wallet-keypool, wallet-hd, wallet-format, wallet-storage-sanity,\n");
+    printf("            db-env-reopen, wallet-sqlite, wallet-sqlite-migration,\n");
+    printf("            wallet-crypto, wallet-encrypt, wallet-portability,\n");
+    printf("            net-message,\n");
+    printf("            consensus-limits, pool-stratum,\n");
+    printf("            parse-money, network-params, socks5-proxy, or managed-tor\n");
     printf("\n");
     printf("Mining mode:\n");
     printf("  /operator\n");
@@ -118,22 +128,36 @@ static void PrintUsage()
     printf("  /payoutaddr=BTF_ADDRESS  (participant: pay shares to this address, no wallet needed)\n");
     printf("  /payoutfile=FILE         (participant: rotate payout addresses from file)\n");
     printf("  /hashthreads=N           (participant: mining threads, default cores-1)\n");
+    printf("  /stratumbridge=POOL_BTF_ADDRESS\n");
+    printf("  /stratumbridgeport=N       (default 3333; listen on 127.0.0.1)\n");
     printf("  /solomine\n");
     printf("  /genproclimit=N            (mining threads; 0 or absent = every core but one)\n");
+    printf("  /nolargepages              (do not ask for 2 MB pages for the RandomX\n");
+    printf("                              cache, dataset and scratchpads)\n");
     printf("  /checkblocks=N             (blocks re-verified at startup, default 288, 0 = all)\n");
     printf("\n");
     printf("Pool operator announcement:\n");
     printf("  /poolname=NAME\n");
     printf("  /poolfee=PCT\n");
     printf("  /pooldashboard=URL  (alias: /pooldash=URL)\n");
+    printf("  /poolstatusfile=PATH       (write pool status JSON for dashboards)\n");
+    printf("  /poolroundsfile=PATH       (write public pool round proofs JSON)\n");
     printf("\n");
     printf(".btf and rendezvous:\n");
     printf("  /connectbtf=PEER_BTF_ADDRESS\n");
     printf("  /rvrelay=HOST:PORT\n");
     printf("  /announcerelay=HOST:PORT\n");
+    printf("  /onionservice=HOST.onion:PORT  (advertise this node's Tor hidden service)\n");
     printf("\n");
     printf("Network:\n");
-    printf("  /port=N                    (P2P listen port, default 8433)\n");
+    printf("  /testnet                   (isolated test network genesis, datadir, port, and magic)\n");
+    printf("  /port=N                    (P2P listen port, default 8433; testnet 18433)\n");
+    printf("  /socks=HOST:PORT           (SOCKS5 proxy for Nostr, .btf relay, and onion dials)\n");
+    printf("  /tor[=HOST:PORT]           (Tor mode; default SOCKS5 proxy is 127.0.0.1:9050)\n");
+    printf("  /managedtor[=PATH]         (start Tor, create a hidden service, advertise its onion)\n");
+    printf("  /automanagedtor            (auto-start a bundled Tor if one sits next to the executable)\n");
+    printf("  /nomanagedtor              (disable automatic bundled Tor startup)\n");
+    printf("  /oniononly                 (do not fall back to rendezvous when a .btf onion dial fails)\n");
     printf("  /btfseed=ADDRESS:ENCHEX    (extra bootstrap peer, repeatable)\n");
     printf("\n");
     printf("Wallet:\n");
@@ -160,6 +184,26 @@ static void PrintUsage()
     printf("  /recoveryaudit             (show how much spendable balance is\n");
     printf("                              covered by the recovery phrase;\n");
     printf("                              exits 2 when wallet.dat is still needed)\n");
+    printf("  /walletstorageaudit        (count wallet.dat record types without\n");
+    printf("                              printing wallet values, then exit)\n");
+    printf("  /walletstorageauditjson=FILE\n");
+    printf("                              (write the same audit as deterministic JSON)\n");
+    printf("  /walletstoragecheck        (fail closed on inconsistent or unsafe\n");
+    printf("                              wallet.dat storage state)\n");
+    printf("  /walletsqliteexport=FILE   (copy raw wallet.dat records into an\n");
+    printf("                              SQLite store, then exit)\n");
+    printf("  /walletsqliteverify=FILE   (compare wallet.dat with a SQLite export,\n");
+    printf("                              printing counts only, then exit)\n");
+    printf("  /walletsqliterestore=FILE  (rebuild wallet.dat from a SQLite export in\n");
+    printf("                              an empty data directory, then exit)\n");
+    printf("  /walletsqliteloadcheck=FILE\n");
+    printf("                              (parse a SQLite export like the wallet loader)\n");
+    printf("  /walletsqlite=FILE         (stage-load a SQLite wallet export, then exit)\n");
+    printf("  /walletbackend=sqlite      (opt-in: run the node on <datadir>/wallet.sqlite\n");
+    printf("                              instead of wallet.dat; export one first)\n");
+    printf("  /createwallet              (headless only: permit creating a new wallet in a\n");
+    printf("                              datadir that has none -- otherwise refused, since\n");
+    printf("                              a missing wallet is usually a mount/backup fault)\n");
     printf("  /rescan                    (walk the chain for coins this wallet owns\n");
     printf("                              but never recorded, then exit)\n");
     printf("\n");
@@ -173,9 +217,60 @@ static void ParseStartupArguments(int argc, char* argv[])
     if (arg(argc,argv,"/datadir") || arg(argc,argv,"-datadir"))
         strSetDataDir = argval2(argc, argv, "/datadir", "-datadir");
 
+    bool fUseTestNet = arg(argc, argv, "/testnet") || arg(argc, argv, "-testnet");
+    SelectChainParams(fUseTestNet);
+
     if (arg(argc,argv,"/debug") || arg(argc,argv,"-debug"))
         fDebug = true;
 
+    // /debugrelay -- everything /debug shows, plus the per-message firehose
+    // ("relay" and "nostrdiscovery" categories: sending: tx, Relaying wtx,
+    // raw CBlock dumps, per-peer discovery lines). That traffic was ~90% of
+    // a 13-hour production debug.log (issue #35), so plain /debug leaves it
+    // off; the message text itself is unchanged for anyone grepping it.
+    if (arg(argc,argv,"/debugrelay") || arg(argc,argv,"-debugrelay"))
+    {
+        fDebug = true;
+        fDebugRelay = true;
+    }
+
+    // /maxdebugfilesize=N -- roll debug.log to debug.log.old once it passes
+    // N MB, checked on each write. Default is 1024 (see util.cpp); 0 turns
+    // the check off and leaves rotation entirely to logrotate.
+    string strMaxDebugSize = argval2(argc, argv, "/maxdebugfilesize", "-maxdebugfilesize");
+    if (!strMaxDebugSize.empty())
+    {
+        // Parsed with atoi64() before, which is strtoll() with the endptr
+        // thrown away: it returns 0 for anything it cannot read, so
+        // /maxdebugfilesize=1G and =1024MB both came out as 0 -- "never
+        // roll", identical to asking for that on purpose, with nothing said
+        // to the operator. The old code also multiplied without a range
+        // check, so a big enough N wrapped to a negative cap, which the roll
+        // reads as "off" too. Every rejection is now reported and leaves the
+        // default in place; the value is a plain count of MB, no suffix.
+        const char* psz = strMaxDebugSize.c_str();
+        char* pszEnd = NULL;
+        errno = 0;
+        int64 nMB = strtoll(psz, &pszEnd, 10);
+        // INT64_MAX, without depending on which limits header this tree pulls in.
+        const int64 nMaxMB = (int64)((~(uint64)0) >> 1) / (1024 * 1024);
+        const char* pszWhy = NULL;
+        if (pszEnd == psz)
+            pszWhy = "not a number";
+        else if (*pszEnd != '\0')
+            pszWhy = "trailing characters -- the value is a count of MB, with no unit suffix";
+        else if (errno == ERANGE || nMB < 0)
+            pszWhy = "not a size in MB";
+        else if (nMB > nMaxMB)
+            pszWhy = "larger than a file size can be";
+        if (pszWhy)
+            fprintf(stderr, "Ignoring /maxdebugfilesize=%s: %s (keeping %lld MB)\n",
+                    strMaxDebugSize.c_str(), pszWhy,
+                    (long long)(nMaxDebugFileSize / 1024 / 1024));
+        else
+            nMaxDebugFileSize = nMB * 1024 * 1024;
+    }
+
     if (arg(argc,argv,"/gen") || arg(argc,argv,"-gen"))
     {
         fGenerateBitcoins = 1;
@@ -195,6 +290,11 @@ static void ParseStartupArguments(int argc, char* argv[])
     if (!strCheckBlocks.empty())
         nCheckBlocksOnLoad = atoi(strCheckBlocks.c_str());
 
+    // Must be read before LoadBlockIndex(), which is what first calls
+    // RandomXInit() and fixes how the cache is allocated.
+    if (arg(argc,argv,"/nolargepages") || arg(argc,argv,"-nolargepages"))
+        fRandomXLargePages = false;
+
     // /genproclimit=N -- threads to hash with. 0 or absent means automatic,
     // which is every core but one. Named after Bitcoin's own option so it reads
     // familiarly to anyone who has run one of these before.
@@ -240,6 +340,22 @@ static void ParseStartupArguments(int argc, char* argv[])
     if (!hashThreads.empty())
         nHashThreads = atoi(hashThreads.c_str());
 
+    if (arg(argc,argv,"/stratumbridge") || arg(argc,argv,"-stratumbridge"))
+    {
+        fStratumBridge = true;
+        string bridgePool = argval2(argc, argv, "/stratumbridge", "-stratumbridge");
+        if (!bridgePool.empty())
+            strParticipantPool = bridgePool;
+    }
+
+    string bridgePort = argval2(argc, argv, "/stratumbridgeport", "-stratumbridgeport");
+    if (!bridgePort.empty())
+    {
+        int nPort = atoi(bridgePort.c_str());
+        if (nPort > 0 && nPort <= 65535)
+            nStratumBridgePort = nPort;
+    }
+
     string poolName = argval2(argc, argv, "/poolname", "-poolname");
     if (!poolName.empty())
         strPoolName = poolName;
@@ -260,9 +376,18 @@ static void ParseStartupArguments(int argc, char* argv[])
     if (!poolFee.empty())
         dPoolFeePercent = atof(poolFee.c_str());
 
+    string poolStatusFile = argval2(argc, argv, "/poolstatusfile", "-poolstatusfile");
+    if (!poolStatusFile.empty())
+        strPoolStatusFile = poolStatusFile;
+
+    string poolRoundsFile = argval2(argc, argv, "/poolroundsfile", "-poolroundsfile");
+    if (!poolRoundsFile.empty())
+        strPoolRoundsFile = poolRoundsFile;
+
     string btfConnect = argval2(argc, argv, "/connectbtf", "-connectbtf");
     if (!btfConnect.empty())
         strBtfConnect = btfConnect;
+    fBtfOnionOnly = arg(argc, argv, "/oniononly") || arg(argc, argv, "-oniononly");
 
     string rvRelay = argval2(argc, argv, "/rvrelay", "-rvrelay");
     if (!rvRelay.empty())
@@ -283,10 +408,102 @@ static void ParseStartupArguments(int argc, char* argv[])
         }
     }
 
+    // net.cpp has described nListenPort as "tunable via /port" since it was
+    // written, but nothing ever read the option, so the port was fixed at 8433
+    // and a second node could not start on a machine already running one. Parse
+    // it before Tor setup so a managed hidden service maps the real listener.
+    string strPort = argval2(argc, argv, "/port", "-port");
+    if (!strPort.empty())
+    {
+        int nPort = atoi(strPort.c_str());
+        if (nPort <= 0 || nPort > 65535)
+            fprintf(stderr, "Ignoring /port=%s: not a port number\n", strPort.c_str());
+        else
+        {
+            nListenPort = htons((unsigned short)nPort);
+            // Or we would announce a port we never bound.
+            addrLocalHost.port = nListenPort;
+        }
+    }
+
     string announceRelay = argval2(argc, argv, "/announcerelay", "-announcerelay");
     if (!announceRelay.empty())
         strBtfAnnounceRelay = announceRelay;
 
+    string onionService = argval2(argc, argv, "/onionservice", "-onionservice");
+    if (!onionService.empty())
+    {
+        string err;
+        if (!BtfSetLocalOnionEndpoint(onionService, err))
+            fprintf(stderr, "Ignoring /onionservice=%s: %s\n", onionService.c_str(), err.c_str());
+        else
+            fprintf(stderr, "Direct onion peer endpoint advertised: %s\n",
+                    BtfLocalOnionEndpoint().c_str());
+    }
+
+    bool fManagedTor = arg(argc, argv, "/managedtor") || arg(argc, argv, "-managedtor");
+    bool fNoManagedTor = arg(argc, argv, "/nomanagedtor") || arg(argc, argv, "-nomanagedtor");
+    bool fTorMode = arg(argc, argv, "/tor") || arg(argc, argv, "-tor");
+    string socksProxy = argval2(argc, argv, "/socks", "-socks");
+    string bundledTorPath;
+    // Managed Tor is opt-in on this fork. Upstream 1.2.19 auto-starts a
+    // bundled tor whenever one sits next to the executable, which silently
+    // moves Nostr/.btf traffic onto Tor, creates a hidden service, and starts
+    // publishing descriptors with meeting_node="rendezvous-pending" on nodes
+    // that never asked for it -- against our pinned-relay posture. The
+    // upstream behavior remains available under the explicit /automanagedtor.
+    bool fAutoManagedTor = !fManagedTor && !fNoManagedTor && !fTorMode &&
+                            socksProxy.empty() &&
+                            (arg(argc, argv, "/automanagedtor") || arg(argc, argv, "-automanagedtor")) &&
+                            BtfBundledTorPath(bundledTorPath);
+    if (fManagedTor || fAutoManagedTor)
+    {
+        if (fManagedTor && (fTorMode || !socksProxy.empty()))
+            fprintf(stderr, "Warning: /managedtor takes precedence over /tor and /socks\n");
+
+        string torPath = fManagedTor ? argval2(argc, argv, "/managedtor", "-managedtor") : bundledTorPath;
+        string err;
+        if (!BtfStartManagedTor(torPath, err))
+        {
+            if (fAutoManagedTor)
+                fprintf(stderr, "Bundled Tor not enabled automatically: %s\n", err.c_str());
+            else
+                fprintf(stderr, "Ignoring /managedtor=%s: %s\n", torPath.c_str(), err.c_str());
+        }
+        else
+            fprintf(stderr, "Managed Tor enabled%s: %s\n",
+                    fAutoManagedTor ? " automatically" : "",
+                    BtfManagedTorStatus().c_str());
+    }
+    else if (fTorMode)
+    {
+        if (!socksProxy.empty())
+            fprintf(stderr, "Warning: /tor takes precedence over /socks=%s\n",
+                    socksProxy.c_str());
+
+        string torProxy = argval2(argc, argv, "/tor", "-tor");
+        string err;
+        if (!BtfEnableTorProxy(torProxy, err))
+            fprintf(stderr, "Ignoring /tor=%s: %s\n", torProxy.c_str(), err.c_str());
+        else
+            fprintf(stderr, "Tor mode enabled through SOCKS5 proxy %s\n",
+                    BtfSocks5ProxyName().c_str());
+    }
+    else
+    {
+        if (!socksProxy.empty())
+        {
+            string err;
+            if (!BtfSetSocks5Proxy(socksProxy, err))
+                fprintf(stderr, "Ignoring /socks=%s: %s\n", socksProxy.c_str(), err.c_str());
+            else
+                fprintf(stderr, "SOCKS5 proxy enabled for outbound discovery/relay dials: %s\n",
+                        BtfSocks5ProxyName().c_str());
+        }
+    }
+    if (fBtfOnionOnly && !BtfSocks5ProxyEnabled())
+        fprintf(stderr, "Warning: /oniononly without /tor, /managedtor, or /socks cannot dial .onion peers\n");
+
     // /btfseed=ADDRESS:ENCHEX -- extra bootstrap peers, repeatable. Useful for
     // testing the seed path and for private networks that ship no compiled list.
     for (int i = 1; i < argc; i++)
@@ -306,22 +523,6 @@ static void ParseStartupArguments(int argc, char* argv[])
         vBtfExtraSeeds.push_back(make_pair(val.substr(0, colon), val.substr(colon + 1)));
     }
 
-    // net.cpp has described nListenPort as "tunable via /port" since it was
-    // written, but nothing ever read the option, so the port was fixed at 8433
-    // and a second node could not start on a machine already running one.
-    string strPort = argval2(argc, argv, "/port", "-port");
-    if (!strPort.empty())
-    {
-        int nPort = atoi(strPort.c_str());
-        if (nPort <= 0 || nPort > 65535)
-            fprintf(stderr, "Ignoring /port=%s: not a port number\n", strPort.c_str());
-        else
-        {
-            nListenPort = htons((unsigned short)nPort);
-            // Or we would announce a port we never bound.
-            addrLocalHost.port = nListenPort;
-        }
-    }
 }
 
 // Report a startup failure somewhere the user will actually see it.
@@ -368,6 +569,36 @@ static void FatalStartupError(bool fHeadless, const string& strWhat, const strin
 #endif
 }
 
+#ifdef _WIN32
+// Windows equivalent of the SIGINT/SIGTERM handler the headless loop installs on
+// POSIX. Without it a headless node on Windows had no way to reach the clean
+// StopNode()+DBFlush() path: Ctrl-C, closing the console window, a service stop
+// and OS shutdown all killed it mid-write, and a wallet.dat left unflushed by
+// Berkeley DB will not reopen. For CLOSE/LOGOFF/SHUTDOWN the OS terminates us
+// shortly after the handler returns, so we set fShutdown and then block until the
+// main loop signals the flush is done -- returning any sooner throws the flush
+// away, which is the whole bug. (A `taskkill /F` is still an uncatchable hard
+// kill; nothing can help there, and nothing should pretend to.)
+static volatile bool g_fHeadlessShutdownDone = false;
+static BOOL WINAPI HeadlessConsoleCtrlHandler(DWORD dwCtrlType)
+{
+    switch (dwCtrlType)
+    {
+    case CTRL_C_EVENT:
+    case CTRL_BREAK_EVENT:
+    case CTRL_CLOSE_EVENT:
+    case CTRL_LOGOFF_EVENT:
+    case CTRL_SHUTDOWN_EVENT:
+        fShutdown = true;
+        while (!g_fHeadlessShutdownDone)
+            Sleep(50);
+        return TRUE;
+    default:
+        return FALSE;
+    }
+}
+#endif
+
 int main(int argc, char* argv[])
 {
     if (arg(argc,argv,"/help") || arg(argc,argv,"-help") ||
@@ -384,10 +615,119 @@ int main(int argc, char* argv[])
 
     ParseStartupArguments(argc, argv);
 
+#ifdef _WIN32
+    // Set by the GUI "Restart Now" button: give the previous instance a moment
+    // to release the network port and the block-index files before this one
+    // opens them, so a relaunch does not race the process it is replacing.
+    if (arg(argc, argv, "/restartwait") || arg(argc, argv, "-restartwait"))
+        Sleep(2500);
+#endif
+
+    // Hidden self-test helper. It must run before LoadWallet(): several
+    // storage-sanity scenarios deliberately make wallet.dat unsafe to load.
+    string strSelfTestMutateWallet =
+        argval2(argc, argv, "/selftestmutatewallet", "-selftestmutatewallet");
+    if (!strSelfTestMutateWallet.empty())
+        return RunSelfTestMutateWallet(strSelfTestMutateWallet);
+
     string strSelfTest = argval2(argc, argv, "/selftest", "-selftest");
     if (!strSelfTest.empty())
         return RunSelfTest(strSelfTest);
 
+    // Storage diagnostics must run before LoadWallet(). Their job is to
+    // explain wallet.dat states that the normal wallet loader may refuse.
+    string strWalletStorageAuditJson =
+        argval2(argc, argv, "/walletstorageauditjson", "-walletstorageauditjson");
+    bool fDiagWantsAudit = arg(argc,argv,"/walletstorageaudit") ||
+                           arg(argc,argv,"-walletstorageaudit") ||
+                           !strWalletStorageAuditJson.empty();
+    bool fDiagWantsCheck = arg(argc,argv,"/walletstoragecheck") ||
+                           arg(argc,argv,"-walletstoragecheck");
+
+    // These diagnostics normally read wallet.dat. Under -walletbackend=sqlite
+    // the live wallet is wallet.sqlite, so open it read-only as the active
+    // store and let the same scan walk the right file. This runs before the
+    // normal backend resolution further down, so validate the value here too.
+    string strDiagBackend = argval2(argc, argv, "/walletbackend", "-walletbackend");
+    if ((fDiagWantsAudit || fDiagWantsCheck) && !strDiagBackend.empty() &&
+        strDiagBackend != "sqlite" && strDiagBackend != "bdb")
+    {
+        AttachTerminal();
+        fprintf(stderr, "Unknown wallet backend '%s'. Use -walletbackend=sqlite "
+                        "or -walletbackend=bdb.\n", strDiagBackend.c_str());
+        return 1;
+    }
+    bool fDiagSQLite = (strDiagBackend == "sqlite") &&
+                       (fDiagWantsAudit || fDiagWantsCheck);
+    if (fDiagSQLite)
+    {
+        AttachTerminal();
+        string strSQLitePath = GetAppDir() + "/wallet.sqlite";
+        string strOpenErr;
+        if (!WalletSQLiteRuntimeOpenReadOnly(strSQLitePath, strOpenErr))
+        {
+            fprintf(stderr, "Cannot open the SQLite wallet for diagnostics: %s\n",
+                    strOpenErr.c_str());
+            return 1;
+        }
+    }
+
+    if (fDiagWantsAudit)
+    {
+        int nRet = CmdWalletStorageAudit(strWalletStorageAuditJson);
+        if (fDiagSQLite)
+            WalletSQLiteRuntimeClose();
+        else
+            DBFlush(true);
+        return nRet;
+    }
+
+    if (fDiagWantsCheck)
+    {
+        int nRet = CmdWalletStorageCheck();
+        if (fDiagSQLite)
+            WalletSQLiteRuntimeClose();
+        else
+            DBFlush(true);
+        return nRet;
+    }
+
+    string strWalletSQLiteExport =
+        argval2(argc, argv, "/walletsqliteexport", "-walletsqliteexport");
+    if (!strWalletSQLiteExport.empty())
+    {
+        int nRet = CmdWalletSQLiteExport(strWalletSQLiteExport);
+        DBFlush(true);
+        return nRet;
+    }
+
+    string strWalletSQLiteVerify =
+        argval2(argc, argv, "/walletsqliteverify", "-walletsqliteverify");
+    if (!strWalletSQLiteVerify.empty())
+    {
+        int nRet = CmdWalletSQLiteVerify(strWalletSQLiteVerify);
+        DBFlush(true);
+        return nRet;
+    }
+
+    string strWalletSQLiteRestore =
+        argval2(argc, argv, "/walletsqliterestore", "-walletsqliterestore");
+    if (!strWalletSQLiteRestore.empty())
+    {
+        int nRet = CmdWalletSQLiteRestore(strWalletSQLiteRestore);
+        DBFlush(true);
+        return nRet;
+    }
+
+    string strWalletSQLiteLoadCheck =
+        argval2(argc, argv, "/walletsqliteloadcheck", "-walletsqliteloadcheck");
+    if (!strWalletSQLiteLoadCheck.empty())
+    {
+        int nRet = CmdWalletSQLiteLoadCheck(strWalletSQLiteLoadCheck);
+        DBFlush(true);
+        return nRet;
+    }
+
     // Berkeley DB reports failure by throwing, and CDB's constructor lets it
     // through. Nothing on this path caught anything, so an unreadable
     // blkindex.dat or wallet.dat -- one written by another platform's Berkeley
@@ -432,18 +772,197 @@ int main(int argc, char* argv[])
     printf("Loading wallet...\n");
     try
     {
-        if (!LoadWallet())
+        string strWalletBackend =
+            argval2(argc, argv, "/walletbackend", "-walletbackend");
+        string strWalletSQLite =
+            argval2(argc, argv, "/walletsqlite", "-walletsqlite");
+
+        // A misspelled backend must not fall through to Berkeley DB silently --
+        // someone who typed -walletbackend=sqlit meant to run on SQLite, and
+        // opening wallet.dat instead of telling them is the wrong surprise.
+        if (!strWalletBackend.empty() &&
+            strWalletBackend != "sqlite" && strWalletBackend != "bdb")
         {
-            // LoadWallet() explains itself into strWalletLoadError when it
-            // knows why -- an unsupported wallet format, for one, which is the
-            // case this whole path exists to make visible.
-            FatalStartupError(fHeadlessStartup, "Cannot open wallet.dat.",
-                              strWalletLoadError);
+            AttachTerminal();
+            FatalStartupError(fHeadlessStartup,
+                strprintf("Unknown wallet backend '%s'.", strWalletBackend.c_str()),
+                "Use -walletbackend=sqlite for the SQLite backend, or "
+                "-walletbackend=bdb for the Berkeley DB wallet.dat.");
             return 1;
         }
 
+        if (strWalletBackend == "sqlite")
+        {
+            // Explicit opt-in via the flag. The node runs on
+            // <datadir>/wallet.sqlite and never opens wallet.dat, but the user
+            // has to have exported one first -- there is no silent migration,
+            // and wallet.dat is left
+            // exactly where it is so a plain restart goes back to it.
+            AttachTerminal();
+            string strSQLitePath = GetAppDir() + "/wallet.sqlite";
+            if (!FileExists(strSQLitePath.c_str()))
+            {
+                string strGuide = strprintf(
+                    "No SQLite wallet was found at\n"
+                    "  %s\n\n"
+                    "The SQLite wallet backend is opt-in and needs an exported\n"
+                    "wallet first. Your Berkeley DB wallet.dat is not touched by\n"
+                    "any of this.\n\n"
+                    "  Step 1  Export your existing wallet to SQLite:\n"
+                    "            bitflash -walletsqliteexport=\"%s\"\n"
+                    "  Step 2  Start again with the SQLite backend:\n"
+                    "            bitflash -walletbackend=sqlite\n\n"
+                    "To go back to Berkeley DB at any time, just start without\n"
+                    "-walletbackend=sqlite. wallet.dat is still your wallet.",
+                    strSQLitePath.c_str(), strSQLitePath.c_str());
+                FatalStartupError(fHeadlessStartup,
+                                  "The SQLite wallet backend needs an exported wallet first.",
+                                  strGuide);
+                return 1;
+            }
+
+            if (!LoadWalletFromSQLiteRuntime(strSQLitePath))
+            {
+                FatalStartupError(fHeadlessStartup,
+                                  "Cannot open the SQLite wallet backend.",
+                                  strWalletLoadError);
+                return 1;
+            }
+
+            fprintf(stderr,
+                    "Wallet backend: SQLite\n"
+                    "  %s\n"
+                    "Your Berkeley DB wallet.dat is left untouched. Restart without\n"
+                    "-walletbackend=sqlite to go back to it.\n",
+                    strSQLitePath.c_str());
+            fflush(stderr);
+            // Fall through and run the node normally: every CWalletDB read,
+            // write, and erase now routes to this SQLite file.
+        }
+        else if (!strWalletSQLite.empty())
+        {
+            AttachTerminal();
+            if (!LoadWalletFromSQLite(strWalletSQLite))
+            {
+                FatalStartupError(fHeadlessStartup,
+                                  "Cannot open SQLite wallet export.",
+                                  strWalletLoadError);
+                return 1;
+            }
+
+            fprintf(stderr, "SQLite wallet loaded: read-only staging backend\n");
+            fprintf(stderr, "SQLite runtime writes are not enabled yet; exiting before "
+                            "network, mining, GUI, or wallet mutation starts.\n");
+            fflush(stderr);
+            DBFlush(true);
+            return 0;
+        }
+        else if (strWalletBackend == "bdb")
+        {
+            // Explicit -walletbackend=bdb overrides the marker and the default:
+            // force Berkeley DB (LoadWallet creates wallet.dat if none exists).
+            if (!LoadWallet())
+            {
+                FatalStartupError(fHeadlessStartup, "Cannot open wallet.dat.",
+                                  strWalletLoadError);
+                return 1;
+            }
+        }
+        else
+        {
+            // No explicit -walletbackend on the command line. Resolve it from
+            // the persistent marker, then defaults: an existing wallet.sqlite
+            // stays on SQLite, an existing wallet.dat stays on Berkeley DB (the
+            // GUI offers to convert), and a fresh install starts on SQLite --
+            // the new default. wallet.dat is never touched by any of this.
+            string strSQLitePath = GetAppDir() + "/wallet.sqlite";
+            bool fSQLiteExists = FileExists(strSQLitePath.c_str());
+            bool fWalletDatExists = FileExists((GetAppDir() + "/wallet.dat").c_str());
+            string strMarker = ReadWalletBackendMarker();
+
+            bool fUseSQLite = false;
+            bool fCreateSQLite = false;
+            if (strMarker == "sqlite")
+            {
+                if (fSQLiteExists)          fUseSQLite = true;
+                else if (fWalletDatExists)  fUseSQLite = false;  // marker stale; real wallet is BDB
+                else { fUseSQLite = true; fCreateSQLite = true; }
+            }
+            else if (strMarker == "bdb")
+            {
+                fUseSQLite = false;
+            }
+            else  // no marker recorded yet
+            {
+                if (fSQLiteExists && !fWalletDatExists) fUseSQLite = true;
+                else if (fWalletDatExists)              fUseSQLite = false;
+                else { fUseSQLite = true; fCreateSQLite = true; }
+            }
+
+            // A headless node whose datadir holds no wallet of either kind is
+            // far more often an operations fault -- datadir not mounted, or
+            // wallet.dat caught mid-rename by a backup -- than a first run.
+            // Creating one here is not the harmless default it looks like:
+            // success also writes the backend marker, and from then on
+            // restoring the real wallet.dat no longer takes effect, because the
+            // marker keeps the node on the empty wallet it just made. Under
+            // 1.2.19 the same fault created a wallet.dat that a restore
+            // overwrote, so operators could recover by putting the file back.
+            // Refuse instead, and name the flag that makes it deliberate.
+            if (fCreateSQLite && fHeadlessStartup &&
+                !arg(argc, argv, "/createwallet") && !arg(argc, argv, "-createwallet"))
+            {
+                AttachTerminal();
+                fprintf(stderr,
+                        "No wallet found in %s\n"
+                        "Refusing to create one. On a headless node an absent wallet is\n"
+                        "usually a mount or backup fault, and creating one would record a\n"
+                        "backend marker that makes restoring the real wallet a no-op.\n"
+                        "Pass -createwallet to start a new one deliberately, or\n"
+                        "-walletbackend=bdb to run on a Berkeley DB wallet.dat.\n",
+                        GetAppDir().c_str());
+                fflush(stderr);
+                return 1;
+            }
+
+            if (fUseSQLite)
+            {
+                AttachTerminal();
+                bool fOk = fCreateSQLite
+                    ? CreateNewSQLiteWallet(strSQLitePath)
+                    : LoadWalletFromSQLiteRuntime(strSQLitePath);
+                if (!fOk)
+                {
+                    FatalStartupError(fHeadlessStartup,
+                        fCreateSQLite ? "Cannot create the SQLite wallet."
+                                      : "Cannot open the SQLite wallet.",
+                        strWalletLoadError);
+                    return 1;
+                }
+                // Record the choice so it is stable from here on.
+                if (ReadWalletBackendMarker() != "sqlite")
+                    WriteWalletBackendMarker("sqlite");
+                fprintf(stderr, "Wallet backend: SQLite\n  %s\n%s",
+                        strSQLitePath.c_str(),
+                        fCreateSQLite ? "A new wallet was created here.\n" : "");
+                fflush(stderr);
+                // Fall through and run the node; CWalletDB routes to this file.
+            }
+            else if (!LoadWallet())
+            {
+                // LoadWallet() explains itself into strWalletLoadError when it
+                // knows why -- an unsupported wallet format, for one, which is
+                // the case this whole path exists to make visible.
+                FatalStartupError(fHeadlessStartup, "Cannot open wallet.dat.",
+                                  strWalletLoadError);
+                return 1;
+            }
+        }
+
         // After the block index, so there is a chain to compare the wallet
-        // against, and before anything reports a balance.
+        // against, and before anything reports a balance. Works on either
+        // backend: RescanSpentFlags writes corrected flags through CWalletDB,
+        // which routes to SQLite when that backend is active.
         RescanSpentFlags();
     }
     catch (const std::exception& e)
@@ -668,7 +1187,12 @@ int main(int argc, char* argv[])
         return 0;
     }
 
-    if (!StartNode(strErrors)) { fprintf(stderr,"StartNode: %s\n",strErrors.c_str()); return 1; }
+    if (!StartNode(strErrors))
+    {
+        fprintf(stderr,"StartNode: %s\n",strErrors.c_str());
+        BtfStopManagedTor();
+        return 1;
+    }
 
     if (nMineMode == MINE_OPERATOR) {
         gPoolServerRunning = true;
@@ -676,6 +1200,10 @@ int main(int argc, char* argv[])
         if (_beginthread(ThreadRPCServer, 0, NULL) == (uintptr_t)-1)
             printf("Error: _beginthread(ThreadRPCServer) failed\n");
     }
+    if (fStratumBridge) {
+        if (_beginthread(ThreadStratumBridge, 0, NULL) == (uintptr_t)-1)
+            printf("Error: _beginthread(ThreadStratumBridge) failed\n");
+    }
     if (fGenerateBitcoins)
         StartMinerThreads();
 
@@ -688,18 +1216,30 @@ int main(int argc, char* argv[])
 #endif
 
     if (fHeadless) {
-#ifndef _WIN32
+#ifdef _WIN32
+        SetConsoleCtrlHandler(HeadlessConsoleCtrlHandler, TRUE);
+#else
         auto sig=[](int){fShutdown=true;};
         signal(SIGINT,sig); signal(SIGTERM,sig);
 #endif
         printf("Running headless. Ctrl-C to stop.\n");
         while (!fShutdown) Sleep(500);
         StopNode();
+        BtfStopManagedTor();
         // Checkpoints, releases wallet.dat from this directory's Berkeley DB
         // environment, and closes it. Declared since 2009 and never once
         // called here, which is why a wallet.dat copied elsewhere would not
         // open -- issue #40. Not optional.
         DBFlush(true);
+        // Checkpoint and close the SQLite wallet backend if one is active. A
+        // no-op on the Berkeley DB path. Safe to kill before this runs: WAL +
+        // synchronous=FULL already made every committed write durable.
+        WalletSQLiteRuntimeClose();
+#ifdef _WIN32
+        // wallet.dat is safely flushed and closed now; let a pending console
+        // control handler (CLOSE/LOGOFF/SHUTDOWN) return so the OS can finish.
+        g_fHeadlessShutdownDone = true;
+#endif
         return 0;
     }
 
@@ -709,7 +1249,9 @@ int main(int argc, char* argv[])
     int ret = RunGUI(argc, argv);
     fShutdown = true;
     StopNode();
+    BtfStopManagedTor();
     DBFlush(true);
+    WalletSQLiteRuntimeClose();
     return ret;
 #endif
 }
diff --git a/src/makefile.mingw b/src/makefile.mingw
index 72f8bbf..362794a 100644
--- a/src/makefile.mingw
+++ b/src/makefile.mingw
@@ -14,14 +14,9 @@ WARNFLAGS = -Wformat -Werror=format \
             -Wno-deprecated-declarations -Wno-write-strings \
             -Wno-narrowing -Wno-unused-result
 
-# FD_SETSIZE has to be defined before winsock2.h and it has to be the same
-# number in every translation unit -- fd_set carries an array of that length,
-# so disagreeing about it means disagreeing about sizeof(fd_set). That is why
-# it lives here as a -D and not as a #define in a header. Windows defaults to
-# 64, which capped this node at 63 watchable peers no matter how many it had.
 CXXFLAGS = -std=gnu++14 -O2 $(WARNFLAGS) -fpermissive -pthread \
-           -DWIN32 -DNOPCH -DFD_SETSIZE=1024 \
-           -DSECP256K1_STATIC \
+           -DWIN32 -DNOPCH \
+           -DSECP256K1_STATIC -DBITFLASH_NODE_BUILD \
            -I$(DEPS)/include -I$(RANDOMX)/src \
            -I$(DEPS)/include/nlohmann \
            -IC:/msys64/ucrt64/include \
@@ -29,7 +24,7 @@ CXXFLAGS = -std=gnu++14 -O2 $(WARNFLAGS) -fpermissive -pthread \
 
 LIBS = -L$(DEPS)/lib -lsecp256k1 \
        -L$(RANDOMX)/build -lrandomx \
-       -lsodium -lssl -lcrypto -ldb_cxx -lpthread \
+       -lsodium -lssl -lcrypto -ldb_cxx -lsqlite3 -lpthread \
        -LC:/msys64/ucrt64/lib \
        -lglfw3 -lopengl32 -lgdi32 \
        -lkernel32 -luser32 -lcomdlg32 -lwinspool -lwinmm \
@@ -42,7 +37,8 @@ IMGUI_OBJS = obj/imgui.o obj/imgui_draw.o obj/imgui_tables.o \
 NODE_OBJS = obj/util.o obj/script.o obj/db.o obj/net.o obj/main.o \
             obj/sha.o obj/nostr.o obj/randomx_pow.o \
             obj/btfaddr.o obj/btfchan.o obj/btfrv.o obj/btftunnel.o obj/rpc.o \
-            obj/selftest.o obj/bip32.o obj/walletcmd.o
+            obj/selftest.o obj/bip32.o obj/walletcmd.o obj/wallet_sqlite.o \
+            obj/proxy.o obj/tor.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o obj/bitflash_res.o
 
@@ -56,7 +52,7 @@ GUI_OBJS = obj/gui.o obj/main_gui.o obj/bitflash_res.o
 HEADERS = headers_core.h headers.h util.h main.h serialize.h uint256.h \
           key.h bignum.h script.h db.h base58.h net.h nostr.h \
           randomx_pow.h btfaddr.h btfchan.h btfrv.h btftunnel.h \
-          selftest.h walletcmd.h sockcount.h compat.h font_roboto.h
+          selftest.h walletcmd.h wallet_sqlite.h sockcount.h proxy.h tor.h compat.h font_roboto.h
 
 all: bitflash.exe
 
@@ -112,7 +108,16 @@ tests: test_bip32.exe bitflash.exe
         ./bitflash.exe -selftest=wallet-keypool
         ./bitflash.exe -selftest=wallet-hd
         ./bitflash.exe -selftest=wallet-format
+        ./bitflash.exe -selftest=wallet-sqlite
+        ./bitflash.exe -selftest=wallet-sqlite-migration
         ./bitflash.exe -selftest=wallet-crypto
         ./bitflash.exe -selftest=wallet-encrypt
+        ./bitflash.exe -selftest=wallet-sqlite-encrypt
+        ./bitflash.exe -selftest=wallet-backend-default
+        ./bitflash.exe -selftest=wallet-convert
         ./bitflash.exe -selftest=net-message
+        ./bitflash.exe -selftest=network-params
         ./bitflash.exe -selftest=consensus-limits
+        ./bitflash.exe -selftest=pool-stratum
+        ./bitflash.exe -selftest=socks5-proxy
+        ./bitflash.exe -selftest=managed-tor
diff --git a/src/net.cpp b/src/net.cpp
index 34c608c..0576402 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -13,15 +13,35 @@
 #include <thread>          // hardware_concurrency, for the miner thread count
 #ifdef _WIN32
 #include <winsock2.h>
+#else
+#include <poll.h>
 #endif
 #include <openssl/rand.h>
+#include <cerrno>
+#include <cstdlib>
 #include "btfaddr.h"
 #include "btftunnel.h"
+#include "proxy.h"
+#include "tor.h"
 
 void ThreadReconnectCachedBtfPeers(void* parg);
 void ThreadMessageHandler2(void* parg);
 void ThreadSocketHandler2(void* parg);
 
+#ifdef _WIN32
+typedef WSAPOLLFD BtfPollFd;
+static int BtfPoll(BtfPollFd* pfd, unsigned int nfd, int nTimeoutMs)
+{
+    return WSAPoll(pfd, nfd, nTimeoutMs);
+}
+#else
+typedef struct pollfd BtfPollFd;
+static int BtfPoll(BtfPollFd* pfd, unsigned int nfd, int nTimeoutMs)
+{
+    return poll(pfd, (nfds_t)nfd, nTimeoutMs);
+}
+#endif
+
 
 
 
@@ -30,10 +50,14 @@ void ThreadSocketHandler2(void* parg);
 //
 // Global state variables
 //
+static const char pchMainnetMessageStart[4] = { 0xbf, 0x20, 0x5c, 0xfd };
+static const char pchTestnetMessageStart[4] = { (char)0xce, (char)0xe2, (char)0xc0, (char)0xff };
+static bool fTestNet = false;
+char pchMessageStart[4] = { 0xbf, 0x20, 0x5c, 0xfd };
 bool fClient = false;
 uint64 nLocalServices = (fClient ? 0 : NODE_NETWORK);
-CAddress addrLocalHost(0, DEFAULT_PORT, nLocalServices);
-unsigned short nListenPort = DEFAULT_PORT; // local P2P port (tunable via /port)
+CAddress addrLocalHost(0, GetDefaultPort(), nLocalServices);
+unsigned short nListenPort = GetDefaultPort(); // local P2P port (tunable via /port)
 CNode nodeLocalHost(INVALID_SOCKET, CAddress("127.0.0.1", nLocalServices));
 CNode* pnodeLocalHost = &nodeLocalHost;
 bool fShutdown = false;
@@ -45,6 +69,8 @@ deque<pair<int64, CInv> > vRelayExpiration;
 CCriticalSection cs_mapRelay;
 map<CInv, int64> mapAlreadyAskedFor;
 string strBtfConnect; // .btf peer to keep connected to (from /connectbtf)
+bool fBtfOnionOnly = false; // require direct onion transport for .btf peers
+static const int BTF_ONION_CONNECT_TIMEOUT_SECS = 120;
 
 int   nPeersWatched        = 0;
 int64 nBlocksReceived      = 0;
@@ -68,6 +94,29 @@ static int64 nBtfHandshakeSilent = 0;
 static string strBtfLastDialFail;
 static string strBtfLastHandshakeTimeout;
 
+bool IsTestNet()
+{
+    return fTestNet;
+}
+
+unsigned short GetDefaultPort()
+{
+    return htons(fTestNet ? TESTNET_PORT : MAINNET_PORT);
+}
+
+void SelectNetworkParams(bool fTestNetIn)
+{
+    if (fTestNet == fTestNetIn)
+        return;
+
+    fTestNet = fTestNetIn;
+    memcpy(pchMessageStart,
+           fTestNet ? pchTestnetMessageStart : pchMainnetMessageStart,
+           sizeof(pchMessageStart));
+    nListenPort = GetDefaultPort();
+    addrLocalHost.port = nListenPort;
+}
+
 void BtfChurnNoteResolveAttempt()
 {
     CRITICAL_BLOCK(cs_btfChurn)
@@ -153,7 +202,7 @@ static const char* pszSockSite[SOCK_SITES] = {
     "external-ip probe", "listen socket", "inbound accept",
     "rendezvous dial", "rendezvous listen", "rendezvous accept",
     "loopback pair listener", "loopback pair app end", "loopback pair pump end",
-    "nostr relay"
+    "nostr relay", "direct onion peer", "stratum bridge"
 };
 
 static string SockAccountingText()
@@ -246,20 +295,27 @@ string GetDiagnosticsText()
     int64 nNow = GetTime();
     string str;
 
-    int nInbound = 0, nHeld = 0;
+    int nInbound = 0, nHeld = 0, nDirectOnion = 0, nRendezvous = 0;
     vector<CNode*> vCopy;
     CRITICAL_BLOCK(cs_vNodes)
     {
         vCopy = vNodes;
         nHeld = (int)vNodes.size();
         foreach(CNode* pnode, vNodes)
+        {
             if (pnode->fInbound)
                 nInbound++;
+            if (pnode->strBtfMeeting.find(".onion:") != string::npos)
+                nDirectOnion++;
+            else if (!pnode->strBtfMeeting.empty())
+                nRendezvous++;
+        }
     }
 
     int nMedian = GetPeerMedianHeight();
 
     str += "Bitflash node diagnostics\n";
+    str += strprintf("  network           %s\n", IsTestNet() ? "testnet" : "mainnet");
     str += strprintf("  uptime            %s\n",
                      FormatAge(nNodeStartTime ? nNow - nNodeStartTime : -1).c_str());
     if (nMedian < 0)
@@ -274,9 +330,26 @@ string GetDiagnosticsText()
 
     // The number that would have made the deafness obvious. Anything held but
     // not watched is a socket this node will never read again.
-    str += strprintf("  peers watched     %d of %d that select() can hold%s\n",
-                     nPeersWatched, (int)FD_SETSIZE - 1,
+    str += strprintf("  peers watched     %d of %d held by poll%s\n",
+                     nPeersWatched, nHeld,
                      nHeld > nPeersWatched ? "   <-- NOT ALL PEERS ARE BEING READ" : "");
+    str += strprintf("  managed Tor       %s\n", BtfManagedTorStatus().c_str());
+
+    string strTorMode = "disabled";
+    if (BtfManagedTorEnabled())
+        strTorMode = "managed";
+    else if (BtfTorProxyEnabled())
+        strTorMode = "external";
+    else if (BtfSocks5ProxyEnabled())
+        strTorMode = "socks5";
+    string strOnion = BtfLocalOnionEndpoint();
+    str += strprintf("  Tor mode          %s%s\n",
+                     strTorMode.c_str(),
+                     fBtfOnionOnly ? " (onion-only)" : "");
+    str += strprintf("  onion endpoint    %s\n",
+                     strOnion.empty() ? "none" : strOnion.c_str());
+    str += strprintf("  .btf peers         %d direct onion, %d rendezvous\n",
+                     nDirectOnion, nRendezvous);
 
     if (nBlocksReceived > 0)
         str += strprintf("  blocks received   %lld  (%lld arrived without a parent, %.1f%%)\n",
@@ -293,6 +366,7 @@ string GetDiagnosticsText()
                                      nMining,
                                      (RandomXFastReady() ? 2080 : 256) + 2 * nMining).c_str()
                          : ", not mining");
+    str += strprintf("  large pages       %s\n", RandomXLargePagesStatus());
 
     str += SockAccountingText();
 
@@ -361,6 +435,9 @@ string GetDiagnosticsText()
 
 bool GetMyExternalIP(unsigned int& ipRet)
 {
+    if (BtfSocks5ProxyEnabled())
+        return error("GetMyExternalIP() skipped while SOCKS5 proxy is enabled\n");
+
     // Try several plain-text IP echo services in order.
     // Each returns just the IPv4 address as the first line of the HTTP body.
     struct { const char* host; const char* path; } services[] = {
@@ -524,6 +601,7 @@ struct CachedBtfPeer
 {
     string btfAddr;
     string meeting;
+    string onion;
     string encHex;
     int64  lastSeen;
     // The peer's own signed descriptor, as it announced itself. Kept verbatim
@@ -582,6 +660,8 @@ void LoadCachedBtfPeers(vector<CachedBtfPeer>& out)
             CachedBtfPeer p;
             p.btfAddr  = o["btf"].get<string>();
             p.meeting  = o["meeting"].get<string>();
+            if (o.contains("onion") && o["onion"].is_string())
+                btf::NormalizeOnionEndpoint(o["onion"].get<string>(), p.onion);
             p.encHex   = o["enc"].get<string>();
             p.lastSeen = o.value("seen", (int64)0);
             if (o.contains("desc") && o["desc"].is_string())
@@ -605,7 +685,8 @@ static CCriticalSection cs_btfPeerCache;
 // learned about by exchange must not cost us the ability to pass it on.
 static void RememberBtfPeer(const string& strBtfAddr, const string& strMeeting,
                             const unsigned char enc_pub[32],
-                            const string& strDesc = string())
+                            const string& strDesc = string(),
+                            const string& strOnion = string())
 {
     CRITICAL_BLOCK(cs_btfPeerCache)
     {
@@ -613,11 +694,15 @@ static void RememberBtfPeer(const string& strBtfAddr, const string& strMeeting,
         LoadCachedBtfPeers(peers);
 
         string strKeepDesc = strDesc;
+        string strKeepOnion;
+        btf::NormalizeOnionEndpoint(strOnion, strKeepOnion);
         for (size_t i = 0; i < peers.size(); i++)
             if (peers[i].btfAddr == strBtfAddr)
             {
                 if (strKeepDesc.empty())
                     strKeepDesc = peers[i].desc;
+                if (strKeepOnion.empty())
+                    strKeepOnion = peers[i].onion;
                 peers.erase(peers.begin() + i);
                 break;
             }
@@ -625,6 +710,7 @@ static void RememberBtfPeer(const string& strBtfAddr, const string& strMeeting,
         CachedBtfPeer p;
         p.btfAddr  = strBtfAddr;
         p.meeting  = strMeeting;
+        p.onion    = strKeepOnion;
         p.encHex   = BytesToHex(enc_pub, 32);
         p.lastSeen = GetTime();
         p.desc     = strKeepDesc;
@@ -639,6 +725,8 @@ static void RememberBtfPeer(const string& strBtfAddr, const string& strMeeting,
             nlohmann::json o;
             o["btf"]     = q.btfAddr;
             o["meeting"] = q.meeting;
+            if (!q.onion.empty())
+                o["onion"] = q.onion;
             o["enc"]     = q.encHex;
             o["seen"]    = q.lastSeen;
             if (!q.desc.empty())
@@ -727,7 +815,7 @@ static int TryBtfSeeds()
         foreach(const string& strRelay, relays)
         {
             if (fShutdown) return nConnected;
-            if (ConnectNodeBtfResolved(s.first, strRelay, enc))
+            if (ConnectNodeBtfResolved(s.first, strRelay, "", enc))
             {
                 LogPrint("net", "btfseed: reached %s via %s\n",
                          s.first.c_str(), strRelay.c_str());
@@ -765,7 +853,7 @@ void ThreadReconnectCachedBtfPeers(void* parg)
         if (fShutdown) return;
         unsigned char enc[32];
         if (!HexToBytes(p.encHex, enc, 32)) continue;
-        if (ConnectNodeBtfResolved(p.btfAddr, p.meeting, enc))
+        if (ConnectNodeBtfResolved(p.btfAddr, p.meeting, p.onion, enc))
         {
             nConnected++;
             if (nConnected >= 8) break; // enough to bootstrap; the rest can wait
@@ -856,14 +944,37 @@ int BtfPexAccept(const vector<string>& vDesc)
         if (!HexToBytes(d.enc, enc, 32))
             continue;
 
-        RememberBtfPeer(strAddr, d.meeting_node, enc, strDesc);
+        RememberBtfPeer(strAddr, d.meeting_node, enc, strDesc, d.onion);
         nKept++;
     }
     return nKept;
 }
 
+static bool SplitHostPort(const string& strHostPort, string& strHost, unsigned short& nPort)
+{
+    size_t colon = strHostPort.rfind(':');
+    if (colon == string::npos || colon == 0 || colon + 1 >= strHostPort.size())
+        return false;
+    string port = strHostPort.substr(colon + 1);
+    for (size_t i = 0; i < port.size(); i++)
+        if (!isdigit((unsigned char)port[i]))
+            return false;
+
+    errno = 0;
+    char* end = NULL;
+    long n = strtol(port.c_str(), &end, 10);
+    if (errno == ERANGE || end == NULL || *end != '\0' || n <= 0 || n > 65535)
+        return false;
+
+    strHost = strHostPort.substr(0, colon);
+    nPort = (unsigned short)n;
+    return true;
+}
+
 static CNode* ConnectNodeBtfTail(const string& strBtfAddr, const unsigned char pk[32],
-                                  const string& strMeeting, const unsigned char enc_pub[32])
+                                  const string& strMeeting, const string& strOnion,
+                                  const unsigned char enc_pub[32],
+                                  const string& strDesc = string())
 {
     CAddress addr = BtfMarkerAddr(pk);
     CNode* pnode = FindNode(addr.ip);
@@ -873,16 +984,54 @@ static CNode* ConnectNodeBtfTail(const string& strBtfAddr, const unsigned char p
         return pnode;
     }
 
-    BtfChurnNoteDialAttempt(strBtfAddr, strMeeting);
-    size_t colon = strMeeting.rfind(':');
-    if (colon == string::npos)
+    string strOnionNorm;
+    if (BtfSocks5ProxyEnabled() && btf::NormalizeOnionEndpoint(strOnion, strOnionNorm))
     {
-        BtfChurnNoteDialResult(strBtfAddr, strMeeting, false);
+        string strOnionHost;
+        unsigned short nOnionPort = 0;
+        if (SplitHostPort(strOnionNorm, strOnionHost, nOnionPort))
+        {
+            BtfChurnNoteDialAttempt(strBtfAddr, strOnionNorm);
+            SOCKET hOnionSocket = BtfConnectSocket(strOnionHost, nOnionPort, SOCK_ONION_PEER,
+                                                   BTF_ONION_CONNECT_TIMEOUT_SECS);
+            if (hOnionSocket != INVALID_SOCKET)
+            {
+                if (fDebug)
+                    LogPrint("net", "connected %s via direct onion %s\n",
+                             strBtfAddr.c_str(), strOnionNorm.c_str());
+                BtfChurnNoteDialResult(strBtfAddr, strOnionNorm, true);
+                RememberBtfPeer(strBtfAddr, strMeeting, enc_pub, strDesc, strOnionNorm);
+
+                pnode = new CNode(hOnionSocket, addr, false);
+                pnode->strBtfAddr = strBtfAddr;
+                pnode->strBtfMeeting = string("onion ") + strOnionNorm;
+                pnode->AddRef();
+                CRITICAL_BLOCK(cs_vNodes)
+                    vNodes.push_back(pnode);
+                return pnode;
+            }
+            if (fDebug)
+                LogPrint("net", "ConnectNodeBtf: direct onion to %s at %s failed%s\n",
+                         strBtfAddr.c_str(), strOnionNorm.c_str(),
+                         fBtfOnionOnly ? "" : ", falling back to rendezvous");
+            BtfChurnNoteDialResult(strBtfAddr, strOnionNorm, false);
+            if (fBtfOnionOnly)
+                return NULL;
+        }
+    }
+
+    if (fBtfOnionOnly)
+    {
+        if (fDebug)
+            LogPrint("net", "ConnectNodeBtf: onion-only mode refused rendezvous fallback for %s\n",
+                     strBtfAddr.c_str());
         return NULL;
     }
-    string strHost = strMeeting.substr(0, colon);
-    int nPort = atoi(strMeeting.substr(colon + 1).c_str());
-    if (nPort <= 0 || nPort > 65535)
+
+    BtfChurnNoteDialAttempt(strBtfAddr, strMeeting);
+    string strHost;
+    unsigned short nPort = 0;
+    if (!SplitHostPort(strMeeting, strHost, nPort))
     {
         BtfChurnNoteDialResult(strBtfAddr, strMeeting, false);
         return NULL;
@@ -902,7 +1051,7 @@ static CNode* ConnectNodeBtfTail(const string& strBtfAddr, const unsigned char p
     BtfChurnNoteDialResult(strBtfAddr, strMeeting, true);
 
     // This one answered -- worth trying first next time we start.
-    RememberBtfPeer(strBtfAddr, strMeeting, enc_pub);
+    RememberBtfPeer(strBtfAddr, strMeeting, enc_pub, strDesc, strOnionNorm);
 
     // Add node
     pnode = new CNode(hSocket, addr, false);
@@ -932,9 +1081,10 @@ CNode* ConnectNodeBtf(const string& strBtfAddr)
         LogPrint("net", "trying %s\n", strBtfAddr.c_str());
 
     string strMeeting;
+    string strOnion;
     unsigned char enc_pub[32];
     BtfChurnNoteResolveAttempt();
-    if (!BtfResolve(strBtfAddr, strMeeting, enc_pub))
+    if (!BtfResolve(strBtfAddr, strMeeting, enc_pub, &strOnion))
     {
         BtfChurnNoteResolveResult(false);
         if (fDebug)
@@ -942,7 +1092,7 @@ CNode* ConnectNodeBtf(const string& strBtfAddr)
         return NULL;
     }
     BtfChurnNoteResolveResult(true);
-    return ConnectNodeBtfTail(strBtfAddr, pk, strMeeting, enc_pub);
+    return ConnectNodeBtfTail(strBtfAddr, pk, strMeeting, strOnion, enc_pub);
 }
 
 // Same as ConnectNodeBtf, but skips the Nostr resolve step because the caller
@@ -951,7 +1101,8 @@ CNode* ConnectNodeBtf(const string& strBtfAddr)
 // address). Makes zero relay connections -- only talks to the peer's
 // rendezvous meeting node.
 CNode* ConnectNodeBtfResolved(const string& strBtfAddr, const string& strMeeting,
-                              const unsigned char enc_pub[32])
+                              const string& strOnion, const unsigned char enc_pub[32],
+                              const string& strDesc)
 {
     unsigned char pk[32];
     if (!btf::ParseAddress(strBtfAddr, pk))
@@ -961,7 +1112,7 @@ CNode* ConnectNodeBtfResolved(const string& strBtfAddr, const string& strMeeting
     }
     if (BtfLocalAddress() == strBtfAddr)
         return NULL; // ourselves
-    return ConnectNodeBtfTail(strBtfAddr, pk, strMeeting, enc_pub);
+    return ConnectNodeBtfTail(strBtfAddr, pk, strMeeting, strOnion, enc_pub, strDesc);
 }
 
 // Anonymous inbound listener (this node's `.btf` hidden service). Registers at
@@ -1127,7 +1278,7 @@ void CNode::Disconnect()
 
     // Invalidate before anything else can look at it. This used to close the
     // socket and leave the handle number sitting in the object, so ~CNode
-    // closed it a second time and the select loop kept arming it in the
+    // closed it a second time and the socket loop kept arming it in the
     // meantime. See the note on ~CNode in net.h.
     BtfCloseSocket(hSocket);
     hSocket = INVALID_SOCKET;
@@ -1276,52 +1427,49 @@ void ThreadSocketHandler2(void* parg)
         //
         // Find which sockets have data to receive
         //
-        struct timeval timeout;
-        timeout.tv_sec  = 0;
-        timeout.tv_usec = 50000; // frequency to poll pnode->vSend
-
-        fd_set fdsetRecv;
-        fd_set fdsetSend;
-        FD_ZERO(&fdsetRecv);
-        FD_ZERO(&fdsetSend);
-        SOCKET hSocketMax = 0;
-        FD_SET(hListenSocket, &fdsetRecv);
-        hSocketMax = max(hSocketMax, hListenSocket);
-        // FD_SET drops silently once the set is full, so count what goes in
-        // and say so. A peer that never makes it into the set is never read,
-        // and that is indistinguishable from a peer with nothing to say --
-        // the failure this whole path used to hide.
-        unsigned int nWatched = 1; // the listen socket
+        static const int nPollTimeoutMs = 50; // frequency to poll pnode->vSend
+
+        struct NodePollResult
+        {
+            CNode* pnode;
+            SOCKET hSocket;
+            bool fRecv;
+            bool fSend;
+            bool fInvalid;
+            NodePollResult(CNode* pnodeIn, SOCKET hSocketIn)
+                : pnode(pnodeIn), hSocket(hSocketIn), fRecv(false), fSend(false), fInvalid(false) {}
+        };
+
+        vector<BtfPollFd> vPoll;
+        vector<NodePollResult> vPollNodes;
+
+        BtfPollFd listenPoll;
+        memset(&listenPoll, 0, sizeof(listenPoll));
+        listenPoll.fd = hListenSocket;
+        listenPoll.events = POLLIN;
+        vPoll.push_back(listenPoll);
+
         CRITICAL_BLOCK(cs_vNodes)
         {
             foreach(CNode* pnode, vNodes)
             {
-                if (nWatched >= FD_SETSIZE)
-                    break;
                 // A disconnected node stays in vNodes until its references go.
-                // Arming its closed handle asks select() to watch a number the
-                // operating system may already have given to somebody else.
+                // Do not watch a closed handle number: the OS may already have
+                // handed it to a different connection.
                 if (pnode->hSocket == INVALID_SOCKET)
                     continue;
-                FD_SET(pnode->hSocket, &fdsetRecv);
-                nWatched++;
-                hSocketMax = max(hSocketMax, pnode->hSocket);
+
+                BtfPollFd pfd;
+                memset(&pfd, 0, sizeof(pfd));
+                pfd.fd = pnode->hSocket;
+                pfd.events = POLLIN;
                 TRY_CRITICAL_BLOCK(pnode->cs_vSend)
                     if (!pnode->vSend.empty())
-                        FD_SET(pnode->hSocket, &fdsetSend);
+                        pfd.events |= POLLOUT;
+                vPoll.push_back(pfd);
+                vPollNodes.push_back(NodePollResult(pnode, pnode->hSocket));
             }
-            if (vNodes.size() + 1 > (size_t)FD_SETSIZE)
-            {
-                static int64 nLastWarned = 0;
-                if (GetTime() - nLastWarned > 60)
-                {
-                    nLastWarned = GetTime();
-                    printf("WARNING: %d peers but select() can only watch %d -- %d are not being read\n",
-                           (int)vNodes.size(), (int)FD_SETSIZE - 1,
-                           (int)vNodes.size() - (int)FD_SETSIZE + 1);
-                }
-            }
-            nPeersWatched = (int)nWatched - 1;   // less the listen socket
+            nPeersWatched = (int)vPollNodes.size();
         }
 
         // Say the state of the node out loud now and then, so a log pulled off
@@ -1342,32 +1490,17 @@ void ThreadSocketHandler2(void* parg)
         }
 
         vfThreadRunning[0] = false;
-        int nSelect = select(hSocketMax + 1, &fdsetRecv, &fdsetSend, NULL, &timeout);
+        int nPoll = BtfPoll(&vPoll[0], (unsigned int)vPoll.size(), nPollTimeoutMs);
         vfThreadRunning[0] = true;
         CheckForShutdown(0);
-        if (nSelect == SOCKET_ERROR)
+        if (nPoll == SOCKET_ERROR)
         {
-            // This used to answer a failed select() by marking every
-            // descriptor from 0 to hSocketMax ready, which is code written for
-            // POSIX, where a descriptor is a small integer. A Windows SOCKET is
-            // a kernel handle in the thousands, so the loop iterated over
-            // numbers that are not sockets and told the rest of the function
-            // that every peer had data. One bad handle in the set makes
-            // select() fail on every pass, so a single closed socket put the
-            // whole thread into that state permanently.
-            //
-            // Find the bad handle instead and let it be dropped.
             int nErr = WSAGetLastError();
-            LogPrint("net", "select failed: %d\n", nErr);
-            FD_ZERO(&fdsetRecv);
-            FD_ZERO(&fdsetSend);
+            LogPrint("net", "poll failed: %d\n", nErr);
             CRITICAL_BLOCK(cs_vNodes)
             {
                 foreach(CNode* pnode, vNodes)
                 {
-                    // Already disconnected: its handle is gone on purpose, and
-                    // reporting it here would name the wrong node for a select()
-                    // failure it did not cause.
                     if (pnode->hSocket == INVALID_SOCKET)
                         continue;
                     int nType = 0;
@@ -1376,24 +1509,27 @@ void ThreadSocketHandler2(void* parg)
 #else
                     socklen_t nTypeLen = sizeof(nType);
 #endif
-                    if (pnode->hSocket != INVALID_SOCKET &&
-                        getsockopt(pnode->hSocket, SOL_SOCKET, SO_TYPE, (char*)&nType, &nTypeLen) != 0)
+                    if (getsockopt(pnode->hSocket, SOL_SOCKET, SO_TYPE, (char*)&nType, &nTypeLen) != 0)
                     {
                         printf("dropping node %s: its socket is no longer valid\n",
                                pnode->addr.ToString().c_str());
                         pnode->fDisconnect = true;
 
-                        // Stop referring to it, or it goes back into the next
-                        // select() set and fails it again.
+                        // Stop referring to it, or it goes into the next poll
+                        // set and fails it again.
                         //
                         // Marking fDisconnect is not enough: a node is only
                         // removed from vNodes once it has drained or once
                         // DISCONNECT_DRAIN_SECS has passed, so one dead
-                        // descriptor kept failing select() for a full minute --
-                        // and a failed select() zeroes both sets above, which
-                        // means NO peer is read on that pass. Measured on a
-                        // wedged pool: 1,027 consecutive passes over 61
-                        // seconds, one bad socket, the entire node deaf.
+                        // descriptor kept failing the wait for a full minute --
+                        // and a failed wait skips the service loop below
+                        // entirely, which means NO peer is read on that pass.
+                        // Measured on a wedged pool under the old select()
+                        // implementation: 1,027 consecutive passes over 61
+                        // seconds, one bad socket, the entire node deaf. poll()
+                        // reports a bad descriptor as POLLNVAL on that entry
+                        // rather than failing the whole call, so this path is
+                        // now the backstop rather than the common case.
                         //
                         // Not closed, only forgotten. getsockopt just told us
                         // this descriptor is not ours any more; closing it now
@@ -1402,7 +1538,17 @@ void ThreadSocketHandler2(void* parg)
                     }
                 }
             }
-            Sleep(timeout.tv_usec/1000);
+            Sleep(nPollTimeoutMs);
+        }
+        else
+        {
+            for (size_t i = 0; i < vPollNodes.size(); i++)
+            {
+                short revents = vPoll[i + 1].revents; // poll[0] is the listener
+                vPollNodes[i].fRecv = (revents & (POLLIN | POLLERR | POLLHUP)) != 0;
+                vPollNodes[i].fSend = (revents & POLLOUT) != 0;
+                vPollNodes[i].fInvalid = (revents & POLLNVAL) != 0;
+            }
         }
         RandAddSeed();
 
@@ -1418,7 +1564,7 @@ void ThreadSocketHandler2(void* parg)
         //
         // Accept new connections
         //
-        if (FD_ISSET(hListenSocket, &fdsetRecv))
+        if (nPoll != SOCKET_ERROR && (vPoll[0].revents & POLLIN))
         {
             struct sockaddr_in sockaddr;
 #ifdef _WIN32
@@ -1437,18 +1583,47 @@ void ThreadSocketHandler2(void* parg)
             {
                 // Refuse rather than accept a connection this node cannot
                 // watch. Without this the listen socket kept taking peers --
-                // it is always in the select set -- while everything past the
+                // it is always watched -- while everything past the
                 // limit sat open and unread, which fed on itself: the deafer
                 // the node got, the more connections it collected.
                 unsigned int nNodes = 0;
                 CRITICAL_BLOCK(cs_vNodes)
                     nNodes = (unsigned int)vNodes.size();
+                // Also count how many connections this one address already
+                // holds. A single IP that keeps opening sockets -- a broken
+                // node or a deliberate connection-exhaustion flood -- must not
+                // be able to take the whole table, which is what starved the
+                // relays.
+                //
+                // Loopback is exempt. Onion peers reach a managed-Tor node
+                // through its local hidden-service listener, so every one of
+                // them accepts as 127.0.0.1; capping loopback would cap all
+                // inbound onion peers as a single group, which is the opposite
+                // of where the network is headed. The global MAX_CONNECTIONS
+                // still bounds the total, and the direct-IP flood this defends
+                // against never arrives over loopback. (Per-onion-identity
+                // limiting, once a peer's identity is known past accept(), is
+                // the right tool for onion and is left for later.)
+                bool fLoopback = (addr.GetByte(3) == 127);
+                unsigned int nFromThisIP = 0;
+                if (!fLoopback)
+                    CRITICAL_BLOCK(cs_vNodes)
+                        for (vector<CNode*>::iterator it = vNodes.begin(); it != vNodes.end(); ++it)
+                            if ((*it)->addr.ip == addr.ip)
+                                nFromThisIP++;
+
                 if (nNodes >= MAX_CONNECTIONS)
                 {
                     LogPrint("net", "refusing connection from %s, already at %u\n",
                              addr.ToString().c_str(), nNodes);
                     BtfCloseSocket(hSocket);
                 }
+                else if (!fLoopback && nFromThisIP >= MAX_CONNECTIONS_PER_IP)
+                {
+                    LogPrint("net", "refusing connection from %s, already %u from that address\n",
+                             addr.ToString().c_str(), nFromThisIP);
+                    BtfCloseSocket(hSocket);
+                }
                 else
                 {
                     LogPrint("net", "accepted connection from %s\n", addr.ToString().c_str());
@@ -1464,22 +1639,28 @@ void ThreadSocketHandler2(void* parg)
         //
         // Service each socket
         //
-        vector<CNode*> vNodesCopy;
-        CRITICAL_BLOCK(cs_vNodes)
-            vNodesCopy = vNodes;
-        foreach(CNode* pnode, vNodesCopy)
+        for (size_t i = 0; i < vPollNodes.size(); i++)
         {
             CheckForShutdown(0);
-            SOCKET hSocket = pnode->hSocket;
-            // Forgotten above because it was already invalid. FD_ISSET on it
-            // is meaningless and recv()/send() would be operating on -1.
-            if (hSocket == INVALID_SOCKET)
+            NodePollResult& poll = vPollNodes[i];
+            CNode* pnode = poll.pnode;
+            SOCKET hSocket = poll.hSocket;
+
+            if (hSocket == INVALID_SOCKET || pnode->hSocket != hSocket)
                 continue;
 
+            if (poll.fInvalid)
+            {
+                LogPrint("net", "poll reported invalid socket for %s\n",
+                         pnode->addr.ToString().c_str());
+                pnode->fDisconnect = true;
+                continue;
+            }
+
             //
             // Receive
             //
-            if (FD_ISSET(hSocket, &fdsetRecv))
+            if (poll.fRecv)
             {
                 TRY_CRITICAL_BLOCK(pnode->cs_vRecv)
                 {
@@ -1519,7 +1700,7 @@ void ThreadSocketHandler2(void* parg)
             //
             // Send
             //
-            if (FD_ISSET(hSocket, &fdsetSend))
+            if (poll.fSend)
             {
                 TRY_CRITICAL_BLOCK(pnode->cs_vSend)
                 {
@@ -1915,6 +2096,14 @@ bool StartNode(string& strError)
     // IP address, and port for the socket that is being bound
     int nRetryLimit = 15;
     struct sockaddr_in sockaddr = addrLocalHost.GetSockAddr();
+    // Managed Tor forwards hidden-service traffic to 127.0.0.1:<port>, which a
+    // LAN-only bind cannot receive -- so a node that advertises an onion
+    // endpoint must listen on all local interfaces. Upstream 1.2.19 bound
+    // INADDR_ANY unconditionally, which also widened the P2P listener of every
+    // non-Tor node to VPN tunnels, docker bridges and secondary NICs. Keep the
+    // wildcard bind conditional on actually having an onion endpoint.
+    if (!BtfLocalOnionEndpoint().empty())
+        sockaddr.sin_addr.s_addr = INADDR_ANY;
     if (bind(hListenSocket, (struct sockaddr*)&sockaddr, sizeof(sockaddr)) == SOCKET_ERROR)
     {
         int nErr = WSAGetLastError();
@@ -1959,7 +2148,7 @@ bool StartNode(string& strError)
     if (addrIncoming.ip)
         addrLocalHost.ip = addrIncoming.ip;
 
-    _beginthread([](void*) {
+    if (_beginthread([](void*) {
         unsigned int ip = addrLocalHost.ip;
         if (GetMyExternalIP(ip)) {
             addrLocalHost.ip = ip;
@@ -1967,7 +2156,8 @@ bool StartNode(string& strError)
             CWalletDB().WriteSetting("addrIncoming", addrIncoming);
             printf("External IP updated: %s\n", addrLocalHost.ToStringIP().c_str());
         }
-    }, 0, NULL);
+    }, 0, NULL) == (uintptr_t)-1)
+        printf("Error: _beginthread(GetMyExternalIP) failed\n");
 
     // Peers that answered last time, dialled straight away. The relays are the
     // only way to find anyone otherwise, and reaching them plus walking their
diff --git a/src/net.h b/src/net.h
index 8b0245a..0988542 100644
--- a/src/net.h
+++ b/src/net.h
@@ -12,7 +12,13 @@ class CBlockIndex;
 
 
 
-static const unsigned short DEFAULT_PORT = htons(8433);
+// Held in host byte order, unlike the DEFAULT_PORT constant these replace,
+// which was htons(8433). Nothing is lost: net.cpp's GetDefaultPort() applies
+// htons() itself and is what every caller now uses, so the value that reaches
+// a sockaddr is byte-for-byte what it was. Mainnet stays on 8433.
+static const unsigned short MAINNET_PORT = 8433;
+static const unsigned short TESTNET_PORT = 18433;
+static const unsigned int PUBLISH_HOPS = 5;
 enum
 {
     NODE_NETWORK = (1 << 0),
@@ -23,13 +29,24 @@ enum
 
 
 
+// Defined in main.cpp. True while this node is tracking the tip rather than
+// still catching up, measured off the age of our own best block -- see there
+// for why that and not a peer-reported height. Declared here because net.h is
+// parsed before main.h and CNode::AskFor needs it.
+bool IsBlockFetchNearTip();
+
 bool GetMyExternalIP(unsigned int& ipRet);
+bool IsTestNet();
+unsigned short GetDefaultPort();
+void SelectNetworkParams(bool fTestNetIn);
 CNode* ConnectNodeBtf(const string& strBtfAddr);
 CNode* ConnectNodeBtfResolved(const string& strBtfAddr, const string& strMeeting,
-                              const unsigned char enc_pub[32]);
+                              const string& strOnion, const unsigned char enc_pub[32],
+                              const string& strDesc=string());
 void ThreadBtfAccept(void* parg);
 void ThreadBtfConnect(void* parg);
 extern string strBtfConnect;
+extern bool fBtfOnionOnly;
 // Bootstrap seeds added at runtime with /btfseed=ADDRESS:ENCHEX (repeatable).
 // The compiled-in list lives in net.cpp; these are appended to it.
 extern std::vector<std::pair<std::string, std::string> > vBtfExtraSeeds;
@@ -87,30 +104,52 @@ static const int          BTF_RECV_TIMEOUT_SECS    = 30 * 60;
 static const int          BTF_SEND_STALL_SECS      = 10 * 60;
 static const int          BTF_HANDSHAKE_GRACE_SECS = 60;
 
+// How long a requested block gets before it is asked for again, in seconds.
+// Used twice: CNode::AskFor spaces the queued per-announcer block retries this
+// far apart instead of the two minutes transactions get, and the failover
+// sweep in main.cpp re-issues a getdata to a different peer once a sent
+// request has gone unanswered this long. A block body is at most 1 MB and
+// somebody demonstrably has it -- they announced it -- so on this timescale
+// "not here yet" means "not coming from that peer", not "still in transit".
+static const int          BLOCK_FETCH_RETRY_SECS   = 15;
+
 // A serialized object cannot be larger than MAX_SIZE, so no valid network
 // message needs the old 256 MB header allowance. Keep the wire cap aligned with
-// what the deserializer can accept and bound how long one peer may sit on a
-// partial payload after a complete header has arrived.
+// what the deserializer can accept. How long a peer may sit on a partial
+// payload after a complete header has arrived is BTF_MSG_WAIT_MAX_SECS, below.
 static const unsigned int MAX_PROTOCOL_MESSAGE_SIZE = MAX_SIZE;
-static const int          BTF_INCOMPLETE_MESSAGE_TIMEOUT_SECS = 2 * 60;
 
 // Ceiling on simultaneous connections.
 //
-// ThreadSocketHandler watches every peer through one select(), and select()
-// cannot watch more descriptors than FD_SETSIZE. On Windows FD_SET simply
-// stops adding once the set is full -- no error, no log -- so every socket
-// past the limit stays open and is never read again. Nothing capped vNodes,
-// so a node accepted connections it had no way to service, and because new
-// entries go on the end of vNodes it was always the newest connection that
-// starved, including the ones dialed to fix connectivity.
+// ThreadSocketHandler watches every peer in one socket loop. This used to be a
+// select() loop, which made FD_SETSIZE the real limit and silently starved
+// sockets past that bitmap. It is now poll()/WSAPoll(), so the ceiling below is
+// a deliberate resource bound rather than a descriptor-set accident.
 //
 // Measured on two nodes before this ceiling existed: 277 and 90 CNode objects
 // against 93 and 90 live sockets, and a status bar reporting hundreds of
 // peers for a node that was really talking to thirty.
 //
-// 125 is Bitcoin's number and sits far below FD_SETSIZE on both platforms.
+// 125 is Bitcoin's number and remains a conservative public-node default.
 static const unsigned int MAX_CONNECTIONS = 125;
 
+// Cap inbound connections from any single address. Without it one source can
+// hold every slot up to MAX_CONNECTIONS -- exactly what happened to the
+// rendezvous relays, where a single IP parked hundreds of connections and
+// starved real peers. A legitimate peer, even a relay talking to a relay,
+// needs only a handful; 32 leaves generous room while denying any one address
+// more than a quarter of the table. The firewall connlimit on the relays does
+// the same thing a layer lower; this makes every build carry the defense.
+//
+// Loopback (127.0.0.0/8) is exempt in the accept path. A managed-Tor node
+// receives every inbound onion peer over its local hidden-service listener, so
+// they all appear as 127.0.0.1 -- capping loopback would cap onion peers as a
+// group, which is exactly wrong for a network moving toward onion-only. The
+// global MAX_CONNECTIONS still bounds the total; a per-onion-identity limit,
+// applied once identity is known after accept(), is the right future tool for
+// onion floods.
+static const unsigned int MAX_CONNECTIONS_PER_IP = 32;
+
 // A node marked for disconnect is normally held until its buffers drain, so
 // a last message still goes out. But vSend cannot drain through a socket
 // whose far end is gone, and that made such a node immortal: it stayed in
@@ -176,7 +215,7 @@ static const int          BTF_BEHIND_WARN_INTERVAL_SECS = 5 * 60;
 //
 // These counters exist so it can. Cheap to keep, and they name the failures
 // that actually happened rather than the ones that sound impressive.
-extern int   nPeersWatched;        // peers in the last select() set
+extern int   nPeersWatched;        // peers in the last poll() set
 extern int64 nBlocksReceived;      // blocks handed to ProcessBlock
 extern int64 nBlocksWithoutParent; // ...of those, how many arrived orphaned
 
@@ -236,15 +275,17 @@ void CheckForShutdown(int n);
 // The message start string is designed to be unlikely to occur in normal data.
 // The characters are rarely used upper ascii, not valid as UTF-8, and produce
 // a large 4-byte int at any alignment.
-// Magic bytes unique to the Bitflash network (0xbf = "BF"). Second byte bumped
-// to 0x20 for the 2026 stable relaunch so the old test chain can't interfere.
-static const char pchMessageStart[4] = { 0xbf, 0x20, 0x5c, 0xfd };
+// Magic bytes unique to the selected Bitflash network. Mainnet uses 0xbf =
+// "BF"; testnet swaps the whole sequence so a test node cannot handshake with
+// mainnet before consensus-level testnet activation exists.
+extern char pchMessageStart[4];
 
 class CMessageHeader
 {
 public:
     enum { COMMAND_SIZE=12 };
-    char pchMessageStart[sizeof(::pchMessageStart)];
+    enum { MESSAGE_START_SIZE=4 };
+    char pchMessageStart[MESSAGE_START_SIZE];
     char pchCommand[COMMAND_SIZE];
     unsigned int nMessageSize;
 
@@ -335,7 +376,7 @@ public:
         nServices = 0;
         memcpy(pchReserved, pchIPv4, sizeof(pchReserved));
         ip = 0;
-        port = DEFAULT_PORT;
+        port = GetDefaultPort();
         nTime = GetAdjustedTime();
         nLastFailed = 0;
     }
@@ -365,7 +406,7 @@ public:
         nServices = nServicesIn;
         memcpy(pchReserved, pchIPv4, sizeof(pchReserved));
         ip = 0;
-        port = DEFAULT_PORT;
+        port = GetDefaultPort();
         nTime = GetAdjustedTime();
         nLastFailed = 0;
 
@@ -656,9 +697,6 @@ public:
     int64 nLastSend;
     int64 nLastRecv;
     int64 nLastSendEmpty;
-    int64 nIncompleteMessageStart;
-    unsigned int nIncompleteMessageSize;
-    string strIncompleteMessageCommand;
     string strBtfAddr;
     string strBtfMeeting;
 
@@ -699,11 +737,13 @@ public:
         nLastSend = 0;
         nLastRecv = 0;
         nLastSendEmpty = GetTime();
-        nIncompleteMessageStart = 0;
-        nIncompleteMessageSize = 0;
-        strIncompleteMessageCommand.clear();
         strBtfAddr.clear();
         strBtfMeeting.clear();
+        // Not waiting on anything yet. Left indeterminate, the first partial
+        // message this peer sends is measured against whatever was in this
+        // memory, and ProcessMessages drops it as unreadable on first contact.
+        nMsgWaitSince = 0;
+        nMsgWaitSize = 0;
         nStartingHeight = -1;
 
         // Push a version message
@@ -798,13 +838,51 @@ public:
         static int64 nLastTime;
         nLastTime = nNow = max(nNow, ++nLastTime);
 
-        // Each retry is 2 minutes after the last
-        nRequestTime = max(nRequestTime + 2 * 60 * 1000000, nNow);
+        // Each retry is 2 minutes after the last -- and because nRequestTime
+        // is shared across peers, the same spacing is what strings requests
+        // for one inv across its announcers. For transactions that is pacing;
+        // for a new block it was the stall of issue #33: nine peers announce
+        // the block, the first one asked does not serve it, and the ninth
+        // candidate is not even asked until sixteen minutes in, with the pool
+        // mining on the stale tip the whole time.
+        //
+        // Blocks retry on the fetch timescale, but only while we are at the
+        // tip. That is where the stall costs something -- the pool keeps
+        // handing out jobs against a dead tip -- and it is also where the
+        // spacing is nearly free: one block is in flight, and its body has
+        // almost always arrived before the second announcer's turn comes
+        // round, so AlreadyHave drops the duplicate before a getdata is sent.
+        //
+        // While catching up neither half holds. A peer working through a
+        // 500-deep queue can be minutes away from block N without anything
+        // being wrong, so at 15s the second announcer is asked at +15s, the
+        // third at +30s, and the bulk download arrives once per announcer --
+        // up to eight times over. Nothing caps that: the eight-entry cap is on
+        // mapBlockFetch, which is a different mechanism from this spacing.
+        // Two minutes is the right number there, and it is what this line did
+        // before. Failover at the tip does not depend on this being 15s in any
+        // case: mapBlockFetch re-issues a stalled getdata to the next peer on
+        // its own timer, which is what actually fixes #33.
+        bool fFast = (inv.type == MSG_BLOCK && IsBlockFetchNearTip());
+        int64 nRetryUsecs = (fFast ? BLOCK_FETCH_RETRY_SECS : 2 * 60) * 1000000LL;
+        nRequestTime = max(nRequestTime + nRetryUsecs, nNow);
         mapAskFor.insert(make_pair(nRequestTime, inv));
     }
 
 
 
+    // "sending: tx (N bytes)" alone was ~71% of a 13-hour production
+    // debug.log (issue #35), so tx sends are demoted to the /debugrelay-gated
+    // "relay" category; every other command's send trace stays on "net".
+    // The line is emitted in pieces across BeginMessage/EndMessage/
+    // AbortMessage, so all three must agree on the category or orphaned
+    // "(N bytes)" fragments would leak into a plain -debug log.
+    // Valid only mid-message (nPushPos != -1).
+    const char* SendLogCategory() const
+    {
+        return strcmp(GetMessageCommand(), "tx") == 0 ? "relay" : "net";
+    }
+
     void BeginMessage(const char* pszCommand)
     {
         EnterCriticalSection(&cs_vSend);
@@ -812,17 +890,19 @@ public:
             AbortMessage();
         nPushPos = vSend.size();
         vSend << CMessageHeader(pszCommand, 0);
-        if (LogAcceptsCategory("net")) printf("sending: %-12s ", pszCommand);
+        if (LogAcceptsCategory(SendLogCategory())) printf("sending: %-12s ", pszCommand);
     }
 
     void AbortMessage()
     {
         if (nPushPos == -1)
             return;
+        // Capture before nPushPos is cleared; GetMessageCommand() needs it.
+        const char* pszCategory = SendLogCategory();
         vSend.resize(nPushPos);
         nPushPos = -1;
         LeaveCriticalSection(&cs_vSend);
-        if (LogAcceptsCategory("net")) printf("(aborted)\n");
+        if (LogAcceptsCategory(pszCategory)) printf("(aborted)\n");
     }
 
     void EndMessage()
@@ -830,7 +910,11 @@ public:
         extern int nDropMessagesTest;
         if (nDropMessagesTest > 0 && GetRand(nDropMessagesTest) == 0)
         {
-            if (LogAcceptsCategory("net")) printf("dropmessages DROPPING SEND MESSAGE\n");
+            // Same category as the "sending: " this line interrupts, so a tx
+            // does not announce its own drop under "net" having been gated
+            // off under "relay". nPushPos can be -1 here, and then
+            // GetMessageCommand() returns "" and this is "net" as before.
+            if (LogAcceptsCategory(SendLogCategory())) printf("dropmessages DROPPING SEND MESSAGE\n");
             AbortMessage();
             return;
         }
@@ -842,10 +926,10 @@ public:
         unsigned int nSize = vSend.size() - nPushPos - sizeof(CMessageHeader);
         memcpy((char*)&vSend[nPushPos] + offsetof(CMessageHeader, nMessageSize), &nSize, sizeof(nSize));
 
-        if (LogAcceptsCategory("net")) printf("(%d bytes)  ", nSize);
+        if (LogAcceptsCategory(SendLogCategory())) printf("(%d bytes)  ", nSize);
         //for (int i = nPushPos+sizeof(CMessageHeader); i < min(vSend.size(), nPushPos+sizeof(CMessageHeader)+20U); i++)
         //    printf("%02x ", vSend[i] & 0xff);
-        if (LogAcceptsCategory("net")) printf("\n");
+        if (LogAcceptsCategory(SendLogCategory())) printf("\n");
 
         nPushPos = -1;
         LeaveCriticalSection(&cs_vSend);
diff --git a/src/nostr.cpp b/src/nostr.cpp
index 3f43302..f44dc08 100644
--- a/src/nostr.cpp
+++ b/src/nostr.cpp
@@ -7,6 +7,10 @@
 #include <openssl/ssl.h>
 #include <openssl/err.h>
 #include <openssl/x509.h>
+#include <openssl/x509v3.h>
+#ifdef _WIN32
+#include <wincrypt.h>
+#endif
 // We link libsecp256k1 statically (without this the header assumes DLL import).
 // Both makefiles also pass -DSECP256K1_STATIC; the guard keeps that from
 // warning while leaving this file correct if built without the flag.
@@ -26,6 +30,7 @@
 
 #include "btfaddr.h"
 #include "btfchan.h"
+#include "proxy.h"
 
 using json = nlohmann::json;
 
@@ -127,6 +132,8 @@ vector<string> vBtfMeetingRelays = {
 bool fBtfRelayPinned = false;
 string strBtfActiveRelay;
 static CCriticalSection cs_activeRelay;
+static string strBtfOnionEndpoint;
+static CCriticalSection cs_onionEndpoint;
 
 // Only the rendezvous we actually registered at (BtfSetActiveRelay, called from
 // ThreadBtfAccept once registration succeeds). Empty until then, on purpose: it
@@ -144,10 +151,43 @@ string BtfActiveRelay()
 
 void BtfSetActiveRelay(const string& relay)
 {
+    // With /rvrelay set, the descriptor must never name anything but the pin.
+    // No caller can reach here with another relay today -- both registration
+    // paths draw their list from BtfAllRelays(), which returns the pin alone --
+    // but the descriptor is the one thing a miner obeys, so the invariant is
+    // enforced at the sink instead of being retrusted to every future caller.
+    if (fBtfRelayPinned &&
+        find(vBtfMeetingRelays.begin(), vBtfMeetingRelays.end(), relay) == vBtfMeetingRelays.end())
+    {
+        LogPrint("pool", "refusing to advertise meeting relay %s: /rvrelay pins %s\n",
+                 relay.c_str(),
+                 vBtfMeetingRelays.empty() ? "an empty list" : vBtfMeetingRelays[0].c_str());
+        return;
+    }
     CRITICAL_BLOCK(cs_activeRelay)
         strBtfActiveRelay = relay;
 }
 
+bool BtfSetLocalOnionEndpoint(const string& endpoint, string& errOut)
+{
+    string norm;
+    if (!btf::NormalizeOnionEndpoint(endpoint, norm))
+    {
+        errOut = "expected v3 onion endpoint HOST.onion:PORT";
+        return false;
+    }
+    CRITICAL_BLOCK(cs_onionEndpoint)
+        strBtfOnionEndpoint = norm;
+    return true;
+}
+
+string BtfLocalOnionEndpoint()
+{
+    CRITICAL_BLOCK(cs_onionEndpoint)
+        return strBtfOnionEndpoint;
+    return "";
+}
+
 // A relay this node advertises on Nostr for others to discover (/announcerelay).
 string strBtfAnnounceRelay;
 // Relays learned from other operators' Nostr announcements.
@@ -196,6 +236,18 @@ vector<string> BtfAllRelays()
     return all;
 }
 
+// Relays learned from Nostr, whether or not a pin is in force. Reporting only:
+// it exists so the pool can name what /rvrelay is excluding. Anything choosing
+// a relay to register or dial at must keep using BtfAllRelays().
+vector<string> BtfDiscoveredRelays()
+{
+    vector<string> out;
+    CRITICAL_BLOCK(cs_discoveredRelays)
+        foreach(const string& r, g_discoveredRelays)
+            out.push_back(r);
+    return out;
+}
+
 
 //
 // Utilities
@@ -387,10 +439,16 @@ std::string BtfLocalDescriptor()
     string meeting;
     CRITICAL_BLOCK(cs_activeRelay)
         meeting = strBtfActiveRelay;
+    string onion = BtfLocalOnionEndpoint();
     if (meeting.empty())
-        return "";
+    {
+        if (onion.empty())
+            return "";
+        meeting = "rendezvous-pending";
+    }
     return btf::SignDescriptor(g_nostrKey.ctx, g_nostrKey.seckey,
-                               g_nostrKey.EncPubHex(), meeting, (uint64_t)GetTime());
+                               g_nostrKey.EncPubHex(), meeting, (uint64_t)GetTime(),
+                               onion);
 }
 
 // The shared secp256k1 context, so net.cpp can verify descriptors that arrive
@@ -468,6 +526,41 @@ static bool BuildSignedEvent(CNostrKey& key, int kind, const json& tags,
 static const uint64 MAX_WS_FRAME   = 1 << 20;  // 1 MiB per frame
 static const uint64 MAX_WS_MESSAGE = 4 << 20;  // 4 MiB reassembled
 
+static int BtfConnectedNodeCount()
+{
+    int nNodes = 0;
+    CRITICAL_BLOCK(cs_vNodes)
+    {
+        nNodes = (int)vNodes.size();
+    }
+    return nNodes;
+}
+
+#ifdef _WIN32
+static bool BtfLoadWindowsRootCertificates(SSL_CTX* sslctx)
+{
+    HCERTSTORE hStore = CertOpenSystemStoreA(0, "ROOT");
+    if (!hStore)
+        return false;
+
+    bool fLoaded = false;
+    X509_STORE* x509store = SSL_CTX_get_cert_store(sslctx);
+    PCCERT_CONTEXT pCert = NULL;
+    while ((pCert = CertEnumCertificatesInStore(hStore, pCert)) != NULL)
+    {
+        const unsigned char* p = pCert->pbCertEncoded;
+        X509* x509 = d2i_X509(NULL, &p, pCert->cbCertEncoded);
+        if (!x509)
+            continue;
+        if (X509_STORE_add_cert(x509store, x509) == 1)
+            fLoaded = true;
+        X509_free(x509);
+    }
+    CertCloseStore(hStore, 0);
+    return fLoaded;
+}
+#endif
+
 class CWebSocket
 {
 public:
@@ -523,53 +616,8 @@ public:
         size_t colon = host.find(':');
         if (colon != string::npos) { port = atoi(host.substr(colon + 1).c_str()); host = host.substr(0, colon); }
 
-        // Resolve and connect (TCP). AF_UNSPEC so we get both A and AAAA
-        // records back and try them in the order the resolver prefers,
-        // rather than hard-failing whenever the IPv4 path to a relay is
-        // filtered/rate-limited (increasingly common for CDN-fronted
-        // relays) while a working IPv6 route exists right there in the
-        // same getaddrinfo() result.
-        struct addrinfo hints, *res = NULL, *rp = NULL;
-        memset(&hints, 0, sizeof(hints));
-        hints.ai_family = AF_UNSPEC;
-        hints.ai_socktype = SOCK_STREAM;
-        char portstr[16]; sprintf(portstr, "%d", port);
-        if (getaddrinfo(host.c_str(), portstr, &hints, &res) != 0 || !res)
-            return error("Nostr: getaddrinfo %s failed", host.c_str());
-
-        bool fConnected = false;
-        for (rp = res; rp != NULL; rp = rp->ai_next)
-        {
-            hSocket = BtfSocketTag(socket(rp->ai_family, rp->ai_socktype, rp->ai_protocol), SOCK_NOSTR);
-            if (hSocket == INVALID_SOCKET)
-                continue;
-
-            // Socket receive/send timeout: Windows takes a DWORD of
-            // milliseconds; POSIX takes a struct timeval.
-#ifdef _WIN32
-            DWORD tv = timeoutSec * 1000;
-            setsockopt(hSocket, SOL_SOCKET, SO_RCVTIMEO, (char*)&tv, sizeof(tv));
-            setsockopt(hSocket, SOL_SOCKET, SO_SNDTIMEO, (char*)&tv, sizeof(tv));
-#else
-            struct timeval tv;
-            tv.tv_sec = timeoutSec;
-            tv.tv_usec = 0;
-            setsockopt(hSocket, SOL_SOCKET, SO_RCVTIMEO, (char*)&tv, sizeof(tv));
-            setsockopt(hSocket, SOL_SOCKET, SO_SNDTIMEO, (char*)&tv, sizeof(tv));
-#endif
-
-            if (connect(hSocket, rp->ai_addr, (int)rp->ai_addrlen) == 0)
-            {
-                fConnected = true;
-                break;
-            }
-
-            BtfCloseSocket(hSocket);
-            hSocket = INVALID_SOCKET;
-        }
-        freeaddrinfo(res);
-
-        if (!fConnected)
+        hSocket = BtfConnectSocket(host, (unsigned short)port, SOCK_NOSTR, timeoutSec);
+        if (hSocket == INVALID_SOCKET)
             return error("Nostr: connect %s:%d failed", host.c_str(), port);
 
         // TLS
@@ -585,22 +633,35 @@ public:
             // so a MITM cannot forge them, but it could drop the rendezvous
             // registration (leaving the pool unreachable to miners) or answer
             // subscriptions with whatever it liked.
-            if (!SSL_CTX_set_default_verify_paths(sslctx))
-                return error("Nostr: no system CA store available, refusing %s", host.c_str());
             SSL_CTX_set_verify(sslctx, SSL_VERIFY_PEER, NULL);
+
+            // OpenSSL's default verify paths are usually empty on Windows, so
+            // the system ROOT store is loaded too -- without it verification
+            // fails closed there and every relay becomes unreachable.
+            bool fTrustLoaded = (SSL_CTX_set_default_verify_paths(sslctx) == 1);
+#ifdef _WIN32
+            fTrustLoaded = BtfLoadWindowsRootCertificates(sslctx) || fTrustLoaded;
+#endif
+            if (!fTrustLoaded)
+                return error("Nostr: failed to load TLS trust store");
+
+            // Floor the protocol version. Verification says who the peer is,
+            // not how weak a cipher suite we will agree to; without this a
+            // relay offering nothing better still gets TLS 1.0.
             SSL_CTX_set_min_proto_version(sslctx, TLS1_2_VERSION);
 
             ssl = SSL_new(sslctx);
             if (!ssl) return false;
             SSL_set_fd(ssl, (int)hSocket);
-            SSL_set_tlsext_host_name(ssl, host.c_str());  // SNI
+            if (SSL_set_tlsext_host_name(ssl, host.c_str()) != 1)  // SNI
+                return error("Nostr: failed to set TLS SNI for %s", host.c_str());
 
             // Verifying the chain is not enough on its own: without this the
             // relay could present any certificate a trusted CA ever issued,
             // for any name. SSL_set1_host binds the check to the host we asked
             // for.
-            if (!SSL_set1_host(ssl, host.c_str()))
-                return error("Nostr: cannot pin verification to %s", host.c_str());
+            if (SSL_set1_host(ssl, host.c_str()) != 1)
+                return error("Nostr: failed to set TLS hostname for %s", host.c_str());
 
             if (SSL_connect(ssl) != 1)
             {
@@ -846,17 +907,21 @@ static void PublishDescriptor(CWebSocket& ws, CNostrKey& key)
     // meeting_node is the rendezvous relay this node's hidden service
     // (ThreadBtfAccept in net.cpp) is registered at -- where clients dial us.
     string meeting_node = BtfActiveRelay();
+    string onion = BtfLocalOnionEndpoint();
     if (meeting_node.empty())
     {
-        // Not registered anywhere yet. Publishing now would advertise a meeting
-        // node we can't be reached at, and peers would waste dials on it. The
-        // ThreadNostrSeed loop republishes on every pass, so skipping costs
-        // nothing but the delay until ThreadBtfAccept registers.
-        LogPrint("nostr", "Nostr: skipping descriptor publish, no rendezvous registered yet\n");
-        return;
+        if (onion.empty())
+        {
+            // Not registered anywhere yet, and no direct onion endpoint exists.
+            // Publishing now would advertise a meeting node we can't be reached at.
+            LogPrint("nostr", "Nostr: skipping descriptor publish, no rendezvous registered yet\n");
+            return;
+        }
+        meeting_node = "rendezvous-pending";
     }
     string desc = btf::SignDescriptor(key.ctx, key.seckey, key.EncPubHex(),
-                                      meeting_node, (uint64_t)GetTime());
+                                      meeting_node, (uint64_t)GetTime(),
+                                      onion);
     if (desc.empty())
         return;
     json tags = json::array({ json::array({ "d", BTF_DESC_DTAG }) });
@@ -1062,7 +1127,8 @@ static void HandlePoolAnnouncement(const json& ev)
 // this socket for reuse, and only a completed exchange leaves it in a state
 // the next caller can trust.
 static bool ResolveDescriptor(CWebSocket& ws, void* ctx, const string& btfAddr,
-                              btf::Descriptor& out, bool& fExchangeOk)
+                              btf::Descriptor& out, bool& fExchangeOk,
+                              string* rawOut = NULL)
 {
     fExchangeOk = false;
     unsigned char pk[32];
@@ -1071,6 +1137,7 @@ static bool ResolveDescriptor(CWebSocket& ws, void* ctx, const string& btfAddr,
     json filter = json::object();
     filter["authors"] = json::array({ HexEncode(pk, 32) });
     filter["kinds"]   = json::array({ BTF_DESC_KIND });
+    filter["#d"]      = json::array({ BTF_DESC_DTAG });
     filter["limit"]   = 1;
     json req = json::array({ "REQ", "btf-resolve", filter });
     if (!ws.SendText(req.dump()))
@@ -1097,7 +1164,11 @@ static bool ResolveDescriptor(CWebSocket& ws, void* ctx, const string& btfAddr,
             const json& ev = j[2];
             if (!fFound && ev.contains("content") &&
                 btf::VerifyDescriptor(ctx, ev["content"].get<string>(), pk, out))
+            {
                 fFound = true;
+                if (rawOut)
+                    *rawOut = ev["content"].get<string>();
+            }
             // Deliberately keep reading to EOSE rather than returning here.
             // Returning early leaves the rest of the relay's answer queued on a
             // socket that goes straight back into the pool, and the next caller
@@ -1117,8 +1188,10 @@ static bool ResolveDescriptor(CWebSocket& ws, void* ctx, const string& btfAddr,
 // public discovery relays for the owner's self-certified descriptor. Used by
 // ConnectNodeBtf in net.cpp.
 bool BtfResolve(const std::string& btfAddr, std::string& meetingHostPort,
-                unsigned char enc_pub[32])
+                unsigned char enc_pub[32], std::string* onionHostPort)
 {
+    if (onionHostPort)
+        onionHostPort->clear();
     if (!EnsureNostrKey())
         return false;
     for (int i = 0; i < nNostrRelays && !fShutdown; i++)
@@ -1146,10 +1219,15 @@ bool BtfResolve(const std::string& btfAddr, std::string& meetingHostPort,
             }
             lease.fOk = fExchangeOk;
             if (d.meeting_node.empty() || d.meeting_node == "rendezvous-pending")
-                continue; // descriptor predates the owner's relay config
+            {
+                if (!onionHostPort || d.onion.empty())
+                    continue; // caller needs rendezvous, or descriptor has no direct path
+            }
             if (!HexDecode(d.enc, enc_pub, 32))
                 continue;
             meetingHostPort = d.meeting_node;
+            if (onionHostPort)
+                *onionHostPort = d.onion;
             return true;
         }
         CATCH_PRINT_EXCEPTION("BtfResolve")
@@ -1207,6 +1285,7 @@ bool BtfResolveMany(const std::vector<std::string>& btfAddrs,
             json filter = json::object();
             filter["authors"] = authors;
             filter["kinds"]   = json::array({ BTF_DESC_KIND });
+            filter["#d"]      = json::array({ BTF_DESC_DTAG });
             filter["limit"]   = (int)authors.size();
             json req = json::array({ "REQ", "btf-resolve-many", filter });
             if (!ws.SendText(req.dump()))
@@ -1237,12 +1316,15 @@ bool BtfResolveMany(const std::vector<std::string>& btfAddrs,
                     btf::Descriptor d;
                     if (!btf::VerifyDescriptor(g_nostrKey.ctx, ev["content"].get<string>(), pk, d))
                         continue;
-                    if (d.meeting_node.empty() || d.meeting_node == "rendezvous-pending")
+                    if ((d.meeting_node.empty() || d.meeting_node == "rendezvous-pending") &&
+                        d.onion.empty())
                         continue;
                     BtfResolvedPeer rp;
                     if (!HexDecode(d.enc, rp.enc_pub, 32))
                         continue;
                     rp.meetingHostPort = d.meeting_node;
+                    rp.onionHostPort = d.onion;
+                    rp.descriptor = ev["content"].get<string>();
                     out[ai->second] = rp;
                     pending.erase(ai->second);
                 }
@@ -1383,7 +1465,7 @@ static bool SeedFromRelay(CNostrKey& key, const string& relay)
                         else if (createdAt > it->second)  it->second = createdAt; // refresh
                     }
                     if (fNew && fDebug)
-                        LogPrint("nostr", "Nostr: discovered .btf peer %s\n", peerAddr.c_str());
+                        LogPrint("nostrdiscovery", "Nostr: discovered .btf peer %s\n", peerAddr.c_str());
                     if (++nPeers > 500) break;
                 }
                 else if (type == "EOSE")
@@ -1617,8 +1699,9 @@ static void ConnectDiscoveredBtfPeers()
     // plus a random sample, not one or the other.
     int64 now = GetTime();
     int nBudget = (int)BTF_DIALS_PER_PASS;
+    int nNodeCount = BtfConnectedNodeCount();
     {
-        int nRoom = (int)BTF_TARGET_CONN - (int)vNodes.size();
+        int nRoom = (int)BTF_TARGET_CONN - nNodeCount;
         if (nRoom < nBudget) nBudget = nRoom;
     }
     if (nBudget < 0) nBudget = 0;
@@ -1632,7 +1715,6 @@ static void ConnectDiscoveredBtfPeers()
         // Reliability slice: walk the tiered (good -> untried -> bad) order.
         for (const string& addr : peers)
         {
-            if ((int)vNodes.size() >= (int)BTF_TARGET_CONN) break;
             if ((int)candidates.size() >= nSortedSlots) break;
             map<string, int64>::iterator bi = g_btfPeerBackoff.find(addr);
             if (bi != g_btfPeerBackoff.end() && now < bi->second)
@@ -1657,7 +1739,7 @@ static void ConnectDiscoveredBtfPeers()
         int nWant = min(nRandomSlots, (int)pool.size());
         for (int i = 0; i < nWant; i++)
         {
-            if ((int)vNodes.size() + (int)candidates.size() >= (int)BTF_TARGET_CONN) break;
+            if (nNodeCount + (int)candidates.size() >= (int)BTF_TARGET_CONN) break;
             if ((int)candidates.size() >= nBudget) break;
             size_t j = i + (size_t)GetRand((uint64)(pool.size() - i));
             std::swap(pool[i], pool[j]);
@@ -1712,20 +1794,20 @@ static void ConnectDiscoveredBtfPeers()
     // not the shared Nostr relays, so there's no thundering-herd effect here.
     // Each thread writes its result back via shared state guarded by cs_btfPeerState.
     struct DialCtx { string addr; BtfResolvedPeer rp; };
-    vector<DialCtx*> ctxs;
     for (const string& addr : toDial)
     {
         DialCtx* ctx = new DialCtx{addr, resolved[addr]};
-        ctxs.push_back(ctx);
-        _beginthread([](void* arg) {
+        uintptr_t tid = _beginthread([](void* arg) {
             DialCtx* ctx = (DialCtx*)arg;
             string addr = ctx->addr;
             string meeting = ctx->rp.meetingHostPort;
+            string onion = ctx->rp.onionHostPort;
+            string desc = ctx->rp.descriptor;
             unsigned char enc_pub[32];
             memcpy(enc_pub, ctx->rp.enc_pub, 32);
             delete ctx;
 
-            CNode* pnode = ConnectNodeBtfResolved(addr, meeting, enc_pub);
+            CNode* pnode = ConnectNodeBtfResolved(addr, meeting, onion, enc_pub, desc);
             CRITICAL_BLOCK(cs_btfPeerState)
             {
                 if (pnode)
@@ -1750,6 +1832,21 @@ static void ConnectDiscoveredBtfPeers()
                 }
             }
         }, 0, ctx);
+        if (tid == (uintptr_t)-1)
+        {
+            LogPrint("nostr", "Nostr: failed to create .btf dial thread for %s\n", addr.c_str());
+            CRITICAL_BLOCK(cs_btfPeerState)
+            {
+                int n = ++g_btfPeerFails[addr];
+                int64 cap = (n >= BTF_CHRONIC_FAIL_THRESHOLD) ? BTF_BACKOFF_CAP_SECS_DEAD
+                                                               : BTF_BACKOFF_CAP_SECS;
+                int64 secs = 30;
+                for (int k = 1; k < n && secs < cap; k++) secs *= 2;
+                if (secs > cap) secs = cap;
+                g_btfPeerBackoff[addr] = GetTime() + secs;
+            }
+            delete ctx;
+        }
     }
 
     // Wait long enough for all parallel dials to finish (each has a 10s socket
@@ -1772,11 +1869,12 @@ void ThreadNostrSeed(void* parg)
     LogPrint("nostr", "Nostr: node pubkey = %s\n", key.PubKeyHex().c_str());
     LogPrint("nostr", "Nostr: node .btf address = %s\n", key.BtfAddress().c_str());
 
-    // The self-test below publishes a real descriptor, and PublishDescriptor now
-    // refuses to publish before ThreadBtfAccept has registered a rendezvous. Give
-    // registration a bounded head start so the test measures the publish/resolve
-    // chain instead of losing the race against it.
-    for (int i = 0; i < 60 && !fShutdown && BtfActiveRelay().empty(); i++)
+    // The self-test below publishes a real descriptor. Rendezvous-only nodes
+    // need ThreadBtfAccept to register first; Tor nodes can publish as soon as
+    // their signed onion endpoint exists, with rendezvous marked pending.
+    for (int i = 0; i < 60 && !fShutdown &&
+                    BtfActiveRelay().empty() &&
+                    BtfLocalOnionEndpoint().empty(); i++)
         Sleep(1000);
 
     // One-time self-test of the rendezvous: publish our descriptor to a relay,
@@ -1852,7 +1950,7 @@ void ThreadNostrSeed(void* parg)
 
         // Re-discover periodically. Sleep less aggressively when
         // we have no connections yet so we find peers faster on startup.
-        int nSleepSecs = vNodes.empty() ? 20 : 60;
+        int nSleepSecs = (BtfConnectedNodeCount() == 0) ? 20 : 60;
         for (int i = 0; i < nSleepSecs && !fShutdown; i++)
             Sleep(1000);
     }
diff --git a/src/nostr.h b/src/nostr.h
index 827b2f3..0dd919d 100644
--- a/src/nostr.h
+++ b/src/nostr.h
@@ -40,6 +40,13 @@ std::string BtfActiveRelay();
 // Record the relay this node just registered its service at (thread-safe).
 void BtfSetActiveRelay(const std::string& relay);
 
+// Optional Tor hidden-service endpoint for this node's normal P2P listener.
+// Set by /onionservice=HOST.onion:PORT. The endpoint is signed into this node's
+// .btf descriptor, so peers with -tor can dial it directly before falling back
+// to rendezvous relays.
+bool BtfSetLocalOnionEndpoint(const std::string& endpoint, std::string& errOut);
+std::string BtfLocalOnionEndpoint();
+
 // If set (via /announcerelay=host:port), this node announces that relay on
 // Nostr so other nodes discover it automatically -- no manual seed-list edit.
 extern std::string strBtfAnnounceRelay;
@@ -53,6 +60,9 @@ extern bool fBtfRelayPinned;
 bool LooksLikeRelay(const std::string& r);
 // Every relay to try: curated seeds + relays discovered from Nostr announcements.
 std::vector<std::string> BtfAllRelays();
+// Relays discovered from Nostr, ignoring the pin. For reporting what a pin
+// excludes -- never for choosing a relay to register or dial at.
+std::vector<std::string> BtfDiscoveredRelays();
 
 struct BtfPoolAnnouncement
 {
@@ -102,12 +112,15 @@ void* BtfSecpContext();
 // self-certified descriptor and return its meeting node ("host:port") and
 // x25519 public key for the end-to-end channel.
 bool BtfResolve(const std::string& btfAddr, std::string& meetingHostPort,
-                unsigned char enc_pub[32]);
+                unsigned char enc_pub[32],
+                std::string* onionHostPort = NULL);
 
 // Result of resolving one .btf address via BtfResolveMany.
 struct BtfResolvedPeer
 {
     std::string meetingHostPort;
+    std::string onionHostPort;
+    std::string descriptor;
     unsigned char enc_pub[32];
 };
 
diff --git a/src/proxy.cpp b/src/proxy.cpp
new file mode 100644
index 0000000..eed054c
--- /dev/null
+++ b/src/proxy.cpp
@@ -0,0 +1,422 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+
+#include "headers_core.h"
+#include "proxy.h"
+#include "sockcount.h"
+
+#include <errno.h>
+
+static CCriticalSection cs_socks5;
+static bool g_fSocks5Proxy = false;
+static bool g_fTorProxy = false;
+static std::string g_socks5Host;
+static unsigned short g_socks5Port = 0;
+static const char* DEFAULT_TOR_SOCKS5_PROXY = "127.0.0.1:9050";
+static const int TOR_CONNECT_TIMEOUT_SECS = 120;
+
+static void SetSocketTimeout(SOCKET s, int nTimeoutSecs)
+{
+    if (nTimeoutSecs <= 0)
+        return;
+#ifdef _WIN32
+    DWORD tv = (DWORD)nTimeoutSecs * 1000;
+    setsockopt(s, SOL_SOCKET, SO_RCVTIMEO, (const char*)&tv, sizeof(tv));
+    setsockopt(s, SOL_SOCKET, SO_SNDTIMEO, (const char*)&tv, sizeof(tv));
+#else
+    struct timeval tv;
+    tv.tv_sec = nTimeoutSecs;
+    tv.tv_usec = 0;
+    setsockopt(s, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
+    setsockopt(s, SOL_SOCKET, SO_SNDTIMEO, &tv, sizeof(tv));
+#endif
+}
+
+static bool ReadN(SOCKET s, void* buf, int n)
+{
+    char* p = (char*)buf;
+    int off = 0;
+    while (off < n)
+    {
+        int r = recv(s, p + off, n - off, 0);
+        if (r <= 0)
+            return false;
+        off += r;
+    }
+    return true;
+}
+
+static bool WriteN(SOCKET s, const void* buf, int n)
+{
+    const char* p = (const char*)buf;
+    int off = 0;
+    while (off < n)
+    {
+        int r = send(s, p + off, n - off, 0);
+        if (r <= 0)
+            return false;
+        off += r;
+    }
+    return true;
+}
+
+static bool ValidProxyHostChar(char c)
+{
+    return isalnum((unsigned char)c) || c == '.' || c == '-' || c == '_';
+}
+
+static bool ValidProxyIpv6HostChar(char c)
+{
+    return isxdigit((unsigned char)c) || c == ':' || c == '.';
+}
+
+static std::string LowerProxyHost(std::string host)
+{
+    if (!host.empty() && host[host.size() - 1] == '.')
+        host.erase(host.size() - 1);
+    for (size_t i = 0; i < host.size(); i++)
+        host[i] = (char)tolower((unsigned char)host[i]);
+    return host;
+}
+
+bool BtfIsTorOnionHost(const std::string& host)
+{
+    std::string lower = LowerProxyHost(host);
+    static const char* suffix = ".onion";
+    size_t suffixLen = strlen(suffix);
+    return lower.size() > suffixLen &&
+           lower.compare(lower.size() - suffixLen, suffixLen, suffix) == 0;
+}
+
+static bool ParsePort(const std::string& port, unsigned short& portOut,
+                      std::string& errOut)
+{
+    if (port.empty())
+    {
+        errOut = "port is empty";
+        return false;
+    }
+    for (size_t i = 0; i < port.size(); i++)
+    {
+        if (!isdigit((unsigned char)port[i]))
+        {
+            errOut = "port is not numeric";
+            return false;
+        }
+    }
+
+    errno = 0;
+    char* end = NULL;
+    long nPort = strtol(port.c_str(), &end, 10);
+    if (errno == ERANGE || end == NULL || *end != '\0' || nPort <= 0 || nPort > 65535)
+    {
+        errOut = "port is out of range";
+        return false;
+    }
+    portOut = (unsigned short)nPort;
+    return true;
+}
+
+bool BtfParseSocks5Proxy(const std::string& spec, std::string& hostOut,
+                         unsigned short& portOut, std::string& errOut)
+{
+    hostOut.clear();
+    portOut = 0;
+    errOut.clear();
+
+    std::string host;
+    std::string port;
+    bool fBracketedIpv6 = false;
+    if (!spec.empty() && spec[0] == '[')
+    {
+        size_t close = spec.find(']');
+        if (close == std::string::npos || close == 1 || close + 1 >= spec.size() || spec[close + 1] != ':')
+        {
+            errOut = "expected [IPv6]:PORT";
+            return false;
+        }
+        host = spec.substr(1, close - 1);
+        port = spec.substr(close + 2);
+        fBracketedIpv6 = true;
+    }
+    else
+    {
+        size_t colon = spec.rfind(':');
+        if (colon == std::string::npos || colon == 0 || colon + 1 >= spec.size())
+        {
+            errOut = "expected HOST:PORT";
+            return false;
+        }
+        host = spec.substr(0, colon);
+        port = spec.substr(colon + 1);
+        if (host.find(':') != std::string::npos)
+        {
+            errOut = "IPv6 proxy hosts must use [ADDR]:PORT";
+            return false;
+        }
+    }
+
+    if (host.size() > 255)
+    {
+        errOut = "host is too long";
+        return false;
+    }
+    if (fBracketedIpv6)
+    {
+        bool fHasColon = false;
+        for (size_t i = 0; i < host.size(); i++)
+        {
+            fHasColon = fHasColon || host[i] == ':';
+            if (!ValidProxyIpv6HostChar(host[i]))
+            {
+                errOut = "IPv6 proxy host contains unsupported characters";
+                return false;
+            }
+        }
+        if (!fHasColon)
+        {
+            errOut = "bracketed proxy host is not IPv6";
+            return false;
+        }
+    }
+    else
+    {
+        for (size_t i = 0; i < host.size(); i++)
+        {
+            if (!ValidProxyHostChar(host[i]))
+            {
+                errOut = "host contains unsupported characters";
+                return false;
+            }
+        }
+    }
+    if (!ParsePort(port, portOut, errOut))
+        return false;
+
+    hostOut = host;
+    return true;
+}
+
+static bool SetSocks5Proxy(const std::string& spec, bool fTorMode,
+                           std::string& errOut)
+{
+    std::string host;
+    unsigned short port = 0;
+    if (!BtfParseSocks5Proxy(spec, host, port, errOut))
+        return false;
+    CRITICAL_BLOCK(cs_socks5)
+    {
+        g_socks5Host = host;
+        g_socks5Port = port;
+        g_fSocks5Proxy = true;
+        g_fTorProxy = fTorMode;
+    }
+    return true;
+}
+
+bool BtfSetSocks5Proxy(const std::string& spec, std::string& errOut)
+{
+    return SetSocks5Proxy(spec, false, errOut);
+}
+
+bool BtfEnableTorProxy(const std::string& spec, std::string& errOut)
+{
+    return SetSocks5Proxy(spec.empty() ? DEFAULT_TOR_SOCKS5_PROXY : spec, true, errOut);
+}
+
+void BtfClearSocks5Proxy()
+{
+    CRITICAL_BLOCK(cs_socks5)
+    {
+        g_fSocks5Proxy = false;
+        g_fTorProxy = false;
+        g_socks5Host.clear();
+        g_socks5Port = 0;
+    }
+}
+
+bool BtfSocks5ProxyEnabled()
+{
+    CRITICAL_BLOCK(cs_socks5)
+        return g_fSocks5Proxy;
+    return false;
+}
+
+bool BtfTorProxyEnabled()
+{
+    CRITICAL_BLOCK(cs_socks5)
+        return g_fSocks5Proxy && g_fTorProxy;
+    return false;
+}
+
+std::string BtfSocks5ProxyName()
+{
+    CRITICAL_BLOCK(cs_socks5)
+    {
+        if (!g_fSocks5Proxy)
+            return "";
+        if (g_socks5Host.find(':') != std::string::npos)
+            return strprintf("[%s]:%u", g_socks5Host.c_str(), (unsigned)g_socks5Port);
+        return strprintf("%s:%u", g_socks5Host.c_str(), (unsigned)g_socks5Port);
+    }
+    return "";
+}
+
+static SOCKET ConnectDirect(const std::string& host, unsigned short port,
+                            int nSockSite, int nTimeoutSecs)
+{
+    struct addrinfo hints, *res = NULL, *rp = NULL;
+    memset(&hints, 0, sizeof(hints));
+    hints.ai_family = AF_UNSPEC;
+    hints.ai_socktype = SOCK_STREAM;
+    char portstr[16];
+    sprintf(portstr, "%u", (unsigned)port);
+    if (getaddrinfo(host.c_str(), portstr, &hints, &res) != 0 || !res)
+        return INVALID_SOCKET;
+
+    SOCKET s = INVALID_SOCKET;
+    for (rp = res; rp != NULL; rp = rp->ai_next)
+    {
+        s = BtfSocketTag(socket(rp->ai_family, rp->ai_socktype, rp->ai_protocol), nSockSite);
+        if (s == INVALID_SOCKET)
+            continue;
+        SetSocketTimeout(s, nTimeoutSecs);
+        if (connect(s, rp->ai_addr, (int)rp->ai_addrlen) == 0)
+            break;
+        BtfCloseSocket(s);
+        s = INVALID_SOCKET;
+    }
+    freeaddrinfo(res);
+    return s;
+}
+
+static bool Socks5Connect(SOCKET s, const std::string& destHost,
+                          unsigned short destPort)
+{
+    if (destHost.empty() || destHost.size() > 255)
+        return false;
+
+    unsigned char hello[3] = { 0x05, 0x01, 0x00 }; // SOCKS5, one method, no auth
+    if (!WriteN(s, hello, sizeof(hello)))
+    {
+        error("SOCKS5 hello write failed for %s:%u\n",
+              destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+    unsigned char choice[2] = { 0, 0 };
+    if (!ReadN(s, choice, sizeof(choice)))
+    {
+        error("SOCKS5 method selection read failed for %s:%u\n",
+              destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+    if (choice[0] != 0x05 || choice[1] != 0x00)
+    {
+        error("SOCKS5 proxy rejected no-auth method for %s:%u (version=0x%02x method=0x%02x)\n",
+              destHost.c_str(), (unsigned)destPort,
+              (unsigned)choice[0], (unsigned)choice[1]);
+        return false;
+    }
+
+    std::vector<unsigned char> req;
+    req.reserve(7 + destHost.size());
+    req.push_back(0x05); // version
+    req.push_back(0x01); // CONNECT
+    req.push_back(0x00); // reserved
+    req.push_back(0x03); // domain name; proxy resolves, avoiding local DNS leak
+    req.push_back((unsigned char)destHost.size());
+    req.insert(req.end(), destHost.begin(), destHost.end());
+    req.push_back((unsigned char)(destPort >> 8));
+    req.push_back((unsigned char)(destPort & 0xff));
+    if (!WriteN(s, &req[0], (int)req.size()))
+    {
+        error("SOCKS5 CONNECT request write failed for %s:%u\n",
+              destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+
+    unsigned char rep[4] = {0,0,0,0};
+    if (!ReadN(s, rep, sizeof(rep)))
+    {
+        error("SOCKS5 CONNECT reply read failed for %s:%u\n",
+              destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+    if (rep[0] != 0x05)
+    {
+        error("SOCKS5 CONNECT reply has invalid version 0x%02x for %s:%u\n",
+              (unsigned)rep[0], destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+    if (rep[1] != 0x00)
+    {
+        error("SOCKS5 CONNECT to %s:%u failed with reply 0x%02x\n",
+              destHost.c_str(), (unsigned)destPort, (unsigned)rep[1]);
+        return false;
+    }
+    int nAddr = 0;
+    if (rep[3] == 0x01) nAddr = 4;
+    else if (rep[3] == 0x04) nAddr = 16;
+    else if (rep[3] == 0x03)
+    {
+        unsigned char len = 0;
+        if (!ReadN(s, &len, 1))
+            return false;
+        nAddr = len;
+    }
+    else
+    {
+        error("SOCKS5 CONNECT reply has invalid address type 0x%02x for %s:%u\n",
+              (unsigned)rep[3], destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+
+    std::vector<unsigned char> discard(nAddr + 2);
+    if (!ReadN(s, &discard[0], (int)discard.size()))
+    {
+        error("SOCKS5 CONNECT bind address read failed for %s:%u\n",
+              destHost.c_str(), (unsigned)destPort);
+        return false;
+    }
+    return true;
+}
+
+SOCKET BtfConnectSocket(const std::string& destHost, unsigned short destPort,
+                        int nSockSite, int nTimeoutSecs)
+{
+    std::string proxyHost;
+    unsigned short proxyPort = 0;
+    bool fProxy = false;
+    bool fTorProxy = false;
+    CRITICAL_BLOCK(cs_socks5)
+    {
+        fProxy = g_fSocks5Proxy;
+        fTorProxy = g_fTorProxy;
+        proxyHost = g_socks5Host;
+        proxyPort = g_socks5Port;
+    }
+
+    if (!fProxy)
+    {
+        if (BtfIsTorOnionHost(destHost))
+        {
+            error("Refusing direct .onion connection to %s:%u; use /tor or /socks\n",
+                  destHost.c_str(), (unsigned)destPort);
+            return INVALID_SOCKET;
+        }
+        return ConnectDirect(destHost, destPort, nSockSite, nTimeoutSecs);
+    }
+
+    if (fTorProxy && nTimeoutSecs > 0 && nTimeoutSecs < TOR_CONNECT_TIMEOUT_SECS)
+        nTimeoutSecs = TOR_CONNECT_TIMEOUT_SECS;
+
+    SOCKET s = ConnectDirect(proxyHost, proxyPort, nSockSite, nTimeoutSecs);
+    if (s == INVALID_SOCKET)
+        return INVALID_SOCKET;
+    if (!Socks5Connect(s, destHost, destPort))
+    {
+        BtfCloseSocket(s);
+        return INVALID_SOCKET;
+    }
+    return s;
+}
diff --git a/src/proxy.h b/src/proxy.h
new file mode 100644
index 0000000..6429cf2
--- /dev/null
+++ b/src/proxy.h
@@ -0,0 +1,34 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// Optional SOCKS5 outbound proxy support. This is transport plumbing only:
+// no consensus, wallet, mining, or .btf identity data depends on it.
+
+#ifndef BITFLASH_PROXY_H
+#define BITFLASH_PROXY_H
+
+#ifdef _WIN32
+#ifndef WIN32_LEAN_AND_MEAN
+#define WIN32_LEAN_AND_MEAN 1
+#endif
+#include <winsock2.h>
+#else
+#include "compat.h"
+#endif
+
+#include <string>
+
+bool BtfParseSocks5Proxy(const std::string& spec, std::string& hostOut,
+                         unsigned short& portOut, std::string& errOut);
+bool BtfSetSocks5Proxy(const std::string& spec, std::string& errOut);
+bool BtfEnableTorProxy(const std::string& spec, std::string& errOut);
+void BtfClearSocks5Proxy();
+bool BtfSocks5ProxyEnabled();
+bool BtfTorProxyEnabled();
+bool BtfIsTorOnionHost(const std::string& host);
+std::string BtfSocks5ProxyName();
+
+SOCKET BtfConnectSocket(const std::string& destHost, unsigned short destPort,
+                        int nSockSite, int nTimeoutSecs);
+
+#endif
diff --git a/src/randomx_pow.cpp b/src/randomx_pow.cpp
index d617ba2..a509543 100644
--- a/src/randomx_pow.cpp
+++ b/src/randomx_pow.cpp
@@ -8,6 +8,7 @@
 #include <thread>
 #include <vector>
 #include <mutex>
+#include <system_error>
 
 // Fixed key (seed) that determines the RandomX cache/dataset. Keeping it
 // constant avoids per-epoch "reseed" logic; for the CPU+RAM fairness goal
@@ -19,40 +20,117 @@ static randomx_cache*  g_cache   = NULL;
 static randomx_dataset* g_dataset = NULL;
 static randomx_vm*     g_vmVerify = NULL;
 static CCriticalSection g_csVerify;
+static std::mutex      g_csInit;
 static bool            g_fInit    = false;
 static bool            g_fFast    = false;
 
+// RandomX reads a 256 MB cache, a 2 GB dataset and a 2 MB scratchpad per VM
+// at random, so most reads miss the TLB on 4 KB pages. 2 MB pages recover
+// roughly a tenth of the hash rate.
+//
+// The pool must be reserved first (vm.nr_hugepages), and RandomX returns NULL
+// instead of falling back, so each allocation below retries without the flag.
+bool fRandomXLargePages = true;   // cleared by -nolargepages
+static bool g_fLargeCache   = false;
+static bool g_fLargeDataset = false;
+static bool g_fLargeAny     = false;
+
+// How to reserve the large-page pool, for the hint printed when a large-page
+// allocation falls back to normal pages. The mechanism is OS-specific.
+static const char* LargePagesHint()
+{
+#ifdef _WIN32
+    return "enable the \"Lock pages in memory\" privilege and run elevated";
+#else
+    return "reserve them with: sysctl vm.nr_hugepages=1280";
+#endif
+}
+
+static randomx_flags WithLargePages(randomx_flags f)
+{
+    return (randomx_flags)(f | RANDOMX_FLAG_LARGE_PAGES);
+}
+
+// Ask for a cache in large pages, then plain pages. Sets fLargeOut to say
+// which one answered.
+static randomx_cache* AllocCache(randomx_flags flags, bool& fLargeOut)
+{
+    fLargeOut = false;
+    if (fRandomXLargePages)
+    {
+        randomx_cache* c = randomx_alloc_cache(WithLargePages(flags));
+        if (c)
+        {
+            fLargeOut = true;
+            return c;
+        }
+    }
+    return randomx_alloc_cache(flags);
+}
+
 
 bool RandomXInit()
 {
     if (g_fInit)
         return true;
 
+    std::lock_guard<std::mutex> lock(g_csInit);
+    if (g_fInit)
+        return true;
+
     // Detect the best flags for this CPU (JIT, hardware AES, Argon2).
     g_flags = randomx_get_flags();
 
-    g_cache = randomx_alloc_cache(g_flags);
+    g_cache = AllocCache(g_flags, g_fLargeCache);
     if (!g_cache)
     {
         // Try without JIT as a fallback
         g_flags = RANDOMX_FLAG_DEFAULT;
-        g_cache = randomx_alloc_cache(g_flags);
+        g_cache = AllocCache(g_flags, g_fLargeCache);
         if (!g_cache)
             return error("RandomX: failed to allocate cache (256 MB)");
     }
     randomx_init_cache(g_cache, RANDOMX_KEY, strlen(RANDOMX_KEY));
 
-    // Verification VM in light mode (cache only)
-    g_vmVerify = randomx_create_vm(g_flags, g_cache, NULL);
+    // Verification VM in light mode (cache only). The scratchpad is only 2 MB
+    // and this VM is created once, but it hashes every block the node ever
+    // validates, so it gets the same treatment.
+    bool fLargeVerify = false;
+    if (fRandomXLargePages)
+    {
+        g_vmVerify = randomx_create_vm(WithLargePages(g_flags), g_cache, NULL);
+        fLargeVerify = (g_vmVerify != NULL);
+    }
+    if (!g_vmVerify)
+        g_vmVerify = randomx_create_vm(g_flags, g_cache, NULL);
     if (!g_vmVerify)
         return error("RandomX: failed to create verification VM");
 
+    g_fLargeAny = g_fLargeCache || fLargeVerify;
     g_fInit = true;
-    printf("RandomX: initialized (cache 256 MB, flags=%d)\n", (int)g_flags);
+    printf("RandomX: initialized (cache 256 MB, flags=%d, large pages: %s)\n",
+           (int)g_flags, RandomXLargePagesStatus());
+    if (fRandomXLargePages && !g_fLargeCache)
+        printf("RandomX: large pages unavailable for the cache; %s "
+               "for about 10%% more hash rate\n", LargePagesHint());
     return true;
 }
 
 
+const char* RandomXLargePagesStatus()
+{
+    if (!fRandomXLargePages)
+        return "off (-nolargepages)";
+    if (g_fLargeCache && g_fLargeDataset)
+        return "cache + dataset";
+    if (g_fLargeCache)
+        return "cache only";
+    if (g_fLargeDataset)
+        return "dataset only";
+    return g_fLargeAny ? "scratchpad only" : "unavailable";
+}
+
+
 // One dataset, once, no matter how many miners ask for it.
 //
 // Every miner thread calls this at startup. The g_fFast guard below is only
@@ -82,8 +160,18 @@ bool RandomXInitDataset(int nThreads)
     if (g_fFast)
         return true;
 
-    randomx_flags fastFlags = (randomx_flags)(g_flags | RANDOMX_FLAG_FULL_MEM);
-    g_dataset = randomx_alloc_dataset(fastFlags);
+    // Only RANDOMX_FLAG_LARGE_PAGES means anything to randomx_alloc_dataset;
+    // the rest of g_flags belongs to the VMs that read it.
+    if (fRandomXLargePages)
+    {
+        g_dataset = randomx_alloc_dataset(WithLargePages(RANDOMX_FLAG_DEFAULT));
+        g_fLargeDataset = (g_dataset != NULL);
+        if (!g_dataset)
+            printf("RandomX: large pages unavailable for the 2 GB dataset; %s "
+                   "for about 10%% more hash rate\n", LargePagesHint());
+    }
+    if (!g_dataset)
+        g_dataset = randomx_alloc_dataset(RANDOMX_FLAG_DEFAULT);
     if (!g_dataset)
     {
         printf("RandomX: not enough memory for the 2 GB dataset, staying in light mode\n");
@@ -96,13 +184,28 @@ bool RandomXInitDataset(int nThreads)
 
     std::vector<std::thread> workers;
     unsigned long per = total / nThreads;
-    for (int i = 0; i < nThreads; i++)
+    try
+    {
+        for (int i = 0; i < nThreads; i++)
+        {
+            unsigned long start = i * per;
+            unsigned long count = (i == nThreads - 1) ? (total - start) : per;
+            workers.emplace_back([start, count]() {
+                randomx_init_dataset(g_dataset, g_cache, start, count);
+            });
+        }
+    }
+    catch (const std::system_error& e)
     {
-        unsigned long start = i * per;
-        unsigned long count = (i == nThreads - 1) ? (total - start) : per;
-        workers.emplace_back([start, count]() {
-            randomx_init_dataset(g_dataset, g_cache, start, count);
-        });
+        // Same refusal as the allocation failure above: light mode is slow
+        // but alive, std::terminate is neither. Join the workers that did
+        // start before releasing the dataset out from under them.
+        for (auto& w : workers) w.join();
+        randomx_release_dataset(g_dataset);
+        g_dataset = NULL;
+        printf("RandomX: cannot spawn dataset init threads (%s), staying in light mode\n",
+               e.what());
+        return false;
     }
     for (auto& w : workers) w.join();
 
@@ -137,13 +240,26 @@ void* RandomXCreateMinerVM()
 {
     if (!g_fInit && !RandomXInit())
         return NULL;
+
+    randomx_flags   flags   = g_flags;
+    randomx_cache*  cache   = g_cache;
+    randomx_dataset* dataset = NULL;
     if (g_fFast && g_dataset)
     {
-        randomx_flags fastFlags = (randomx_flags)(g_flags | RANDOMX_FLAG_FULL_MEM);
-        return randomx_create_vm(fastFlags, NULL, g_dataset);
+        flags   = (randomx_flags)(g_flags | RANDOMX_FLAG_FULL_MEM);
+        cache   = NULL;
+        dataset = g_dataset;
+    }
+
+    // Each thread gets its own 2 MB scratchpad, so the large-page pool can run
+    // dry partway through a fleet of miners. Threads that miss out still run.
+    if (fRandomXLargePages)
+    {
+        randomx_vm* vm = randomx_create_vm(WithLargePages(flags), cache, dataset);
+        if (vm)
+            return vm;
     }
-    // Light mode: own VM sharing the cache
-    return randomx_create_vm(g_flags, g_cache, NULL);
+    return randomx_create_vm(flags, cache, dataset);
 }
 
 
diff --git a/src/randomx_pow.h b/src/randomx_pow.h
index 0027571..355b708 100644
--- a/src/randomx_pow.h
+++ b/src/randomx_pow.h
@@ -41,4 +41,11 @@ uint256 RandomXHashWithVM(void* vm, const void* pHeader, size_t nSize);
 // True when the 2 GB dataset is ready (fast mode active).
 bool RandomXFastReady();
 
+// Ask for large (2 MB) pages for the cache, dataset and scratchpads. Set false
+// by -nolargepages. Must be set before the first RandomXInit().
+extern bool fRandomXLargePages;
+
+// Which allocations actually got large pages, for the status display.
+const char* RandomXLargePagesStatus();
+
 #endif
diff --git a/src/rc/bitcoin.ico b/src/rc/bitcoin.ico
index b768077..33323de 100644
--- a/src/rc/bitcoin.ico
+++ b/src/rc/bitcoin.ico
diff --git a/src/readme.txt b/src/readme.txt
index 6af1694..455884c 100644
--- a/src/readme.txt
+++ b/src/readme.txt
@@ -16,7 +16,7 @@ This product includes software developed by the OpenSSL Project.
 Differences from the original Bitcoin
 -------------------------------------
 - Own genesis block (22/Jul/2026 headline, independent chain)
-- Own magic bytes (0xbf 0x1a 0x5c 0xfd) and P2P port 8433
+- Own magic bytes (0xbf 0x20 0x5c 0xfd) and P2P port 8433
 - Addresses start with "B" (ADDRESSVERSION = 25)
 - Consensus fixes applied: value overflow (CVE-2010-5139), duplicate inputs,
   money range checks (MoneyRange)
@@ -41,21 +41,45 @@ The resulting executable is src/bitflash.exe.
 
 Command-line options (in addition to the original ones)
 -------------------------------------------------------
-  /port=N        listen on P2P port N (default 8433)
+  /testnet       use isolated test network genesis, datadir, port 18433, and message magic
+  /port=N        listen on P2P port N (default 8433; testnet default 18433)
+  /socks=HOST:PORT
+                 route outbound Nostr, .btf rendezvous, and direct onion peer
+                 dials through a SOCKS5 proxy, e.g. /socks=127.0.0.1:9050 for local Tor
+                 or /socks=[::1]:9050 for an IPv6 loopback proxy
+  /tor[=HOST:PORT]
+                 Tor mode for outbound Nostr, .btf rendezvous, and direct onion peer dials;
+                 defaults to the local Tor SOCKS5 proxy at 127.0.0.1:9050
+  /managedtor[=PATH]
+                 start Tor, create a v3 hidden service for this node, route outbound
+                 discovery through it, and advertise the generated onion endpoint
+                 Windows release packages that include tor/tor.exe start this mode
+                 automatically; use /nomanagedtor to force the legacy relay path
   /solomine      mine without requiring a connected peer (local testing)
   /operator      operator mode (run pool server)
   /participant=ADDR
                  participant mode; mine to pool .btf address ADDR
+  /stratumbridge=ADDR
+                 listen on 127.0.0.1:3333 and bridge external Stratum miners
+                 to pool .btf address ADDR
+  /stratumbridgeport=N
+                 local Stratum bridge port (default 3333)
   /poolname=NAME operator announcement pool name
   /poolfee=PCT   operator announcement fee percent (example: 0.75)
   /pooldashboard=URL
                  operator announcement dashboard URL
+  /poolstatusfile=PATH
+                 write pool status JSON for dashboards
+  /poolroundsfile=PATH
+                 write public pool round proofs JSON
   /connectbtf=ADDR
                  keep an outbound .btf connection to ADDR
   /rvrelay=HOST:PORT
                  override meeting relay list with one relay
   /announcerelay=HOST:PORT
                  announce this relay on Nostr for discovery
+  /onionservice=HOST.onion:PORT
+                 advertise this node's Tor hidden service in its signed .btf descriptor
 
 
 Roadmap
diff --git a/src/rpc.cpp b/src/rpc.cpp
index 03d1f44..3827cd5 100644
--- a/src/rpc.cpp
+++ b/src/rpc.cpp
@@ -31,10 +31,15 @@
 #include <netinet/in.h>
 #include <arpa/inet.h>
 #include <unistd.h>
+#include <fcntl.h>
+#include <dirent.h>
+#else
+#include <io.h>
 #endif
 
 #include <atomic>
 #include <mutex>
+#include <thread>
 #include <map>
 #include <set>
 #include <deque>
@@ -110,15 +115,28 @@ static uint256 ShareTargetFromDifficulty(double difficulty)
 {
     if (difficulty <= 0.0) difficulty = 1.0;
     static const uint256 diff1 = CBigNum(bnProofOfWorkLimit).getuint256();
+    // Representability floor. shareTarget = diff1 / difficulty, and diff1 is
+    // ~uint256(0) >> 12, i.e. a hair under 2^244 -- so the true target stops
+    // fitting in a uint256 once difficulty reaches 2^-12 (= 1/4096), and the
+    // fixed-point divide below breaks even earlier in a second way: the
+    // (uint64)(difficulty * 65536.0) divisor truncates to zero for any
+    // difficulty under 2^-16. Both thresholds sit far below VARDIFF_MIN
+    // (0.001), so live operation never comes near this, but a caller that
+    // bypasses vardiff (or a future VARDIFF_MIN) must not divide by zero or
+    // hand back getuint256()'s low-256-bit truncation of an oversized
+    // quotient -- a wrapped target is not merely wrong, it is arbitrarily
+    // HARDER than difficulty 1. At these difficulties every hash is meant to
+    // be a share, so the honest answer is the easiest representable target.
+    // (This replaces a dead branch that read `if (t < diff1 && difficulty <
+    // 1.0)`: t = diff1/difficulty, so difficulty < 1.0 implies t > diff1 and
+    // the two conditions could never both hold.)
+    if (difficulty < 1.0 / 4096.0) return ~uint256(0);
     // shareTarget = diff1 / difficulty
     CBigNum bn; bn.setuint256(diff1);
     // Multiply by 2^16 to keep precision, divide, shift back
     bn <<= 16;
     bn /= (uint64)(difficulty * 65536.0);
-    uint256 t = bn.getuint256();
-    // Cap at all-ones (maximum, easiest possible)
-    if (t < diff1 && difficulty < 1.0) t = ~uint256(0);
-    return t;
+    return bn.getuint256();
 }
 
 // Expected number of hashes to find one share at a given Stratum difficulty,
@@ -218,6 +236,29 @@ static bool RebuildJob()
         // From the pool, so the template's payout key is in wallet.dat before
         // any miner is handed work against it.
         vector<unsigned char> vchPubKey = GetKeyFromPool();
+        if (vchPubKey.empty()) {
+            // Empty means the wallet could not produce a key: encrypted and
+            // locked, or key generation itself failed. Serialised, an empty
+            // vector is a zero-length push, so the coinbase would become
+            // `<empty> OP_CHECKSIG` -- a script nobody can satisfy. Every
+            // block mined against such a job burns its whole subsidy, while
+            // QueuePayouts still records the full obligation and the miners
+            // are then paid out of coin that block never contributed.
+            // BitcoinMiner refuses to mine in this state; refuse to hand the
+            // pool's miners work in it too. printf and not LogPrint for the
+            // reason given above the deaf-node refusal, and throttled the
+            // same way -- the no-job watchdog retries every few seconds for
+            // as long as the condition lasts.
+            static int64 nLastSaidNoKey = 0;
+            if (GetTime() - nLastSaidNoKey > 60) {
+                nLastSaidNoKey = GetTime();
+                printf("RebuildJob: no wallet key available for the coinbase "
+                       "(wallet locked, or key generation failed -- the "
+                       "GetKeyFromPool line above says which) -- not issuing "
+                       "jobs\n");
+            }
+            return false;
+        }
         static std::atomic<uint32_t> sExtra{0};
         uint32_t extraNonce = ++sExtra;
 
@@ -236,35 +277,96 @@ static bool RebuildJob()
         CBlock block;
         block.vtx.push_back(txNew);
 
+        // Fill the block the same way BitcoinMiner() does, because this is the
+        // same job: a block that gets mined and submitted for real.
+        //
+        // It used to differ in two ways, and both were bugs.
+        //
+        // One pass over mapTransactions is not enough. That map is keyed by
+        // hash, so it has no dependency order, and a transaction spending the
+        // still-unconfirmed output of another (change from a recent send, most
+        // commonly) fails ConnectInputs whenever its parent happens to sit
+        // later in map order. A single pass then drops it -- and because map
+        // order does not change between rebuilds, every later rebuild drops it
+        // again at the same point. Deterministic exclusion, not bad luck: if
+        // pool operators mine most of the blocks, a transaction of that shape
+        // can stay unconfirmed for as long as its parent does.
+        //
+        // Diagnosis and fix both come from Vic-Nas, who found it in his fork
+        // of this code and described it exactly. The fork has since been
+        // deleted, so this carries it back rather than losing it.
+        int64 nFees = 0;
         {
             CTxDB txdb("r");
             CRITICAL_BLOCK(cs_mapTransactions)
             {
                 map<uint256, CTxIndex> pool;
-                unsigned int sz = 0;
-                for (auto& kv : mapTransactions) {
-                    CTransaction& tx = kv.second;
-                    if (tx.IsCoinBase() || !tx.IsFinal()) continue;
-                    int64 nFees = 0;
-                    map<uint256, CTxIndex> tmp(pool);
-                    if (!tx.ConnectInputs(txdb, tmp, CDiskTxPos(1,1,1), 0, nFees,
-                                          false, true, tx.GetMinFee(block.vtx.size() < 100)))
-                        continue;
-                    pool = tmp;
-                    block.vtx.push_back(tx);
-                    sz += ::GetSerializeSize(tx, SER_NETWORK);
-                    // Must stay under the consensus cap CheckBlock() enforces.
-                    // This is the pool's job builder, so a block over the cap
-                    // is not just one wasted solve -- it is every miner on the
-                    // pool working a template the network will reject. The
-                    // transaction is already pushed above, so this can overshoot
-                    // by one; half the cap leaves room for that.
-                    if (sz > MAX_BLOCK_SIZE / 2) break;
+                vector<char> vfAlreadyAdded(mapTransactions.size());
+                bool fFoundSomething = true;
+                // The cap is MAX_BLOCK_SIZE_GEN, not MAX_SIZE/2. MAX_SIZE is
+                // the 32 MB serialisation ceiling, so half of it is 16 MB --
+                // this builder would happily assemble a template that its own
+                // CheckBlock() rejects at the 1 MB consensus cap. This is the
+                // pool's job builder, so a block over the cap is not one
+                // wasted solve, it is every miner on the pool working a
+                // template the network will reject.
+                //
+                // The inner break used to bound the overshoot to one
+                // transaction per pass. One transaction is still too many:
+                // nothing caps how big a single transaction may be, so that
+                // bound was worth up to MAX_SIZE. Asking whether each one fits
+                // before appending it bounds the overshoot at zero instead.
+                //
+                // Seeded with the header, tx count and coinbase, because
+                // CheckBlock() weighs the whole serialized block.
+                unsigned int sz = ::GetSerializeSize(block, SER_DISK);
+                // And the sigop budget, which CheckBlock() enforces and this
+                // builder never counted against. Same counting function
+                // CheckBlock() sums, seeded from the coinbase because it sums
+                // over all of vtx.
+                unsigned int nSigOps = block.vtx[0].GetSigOpCount();
+                while (fFoundSomething && sz < MAX_BLOCK_SIZE_GEN)
+                {
+                    fFoundSomething = false;
+                    unsigned int n = 0;
+                    for (map<uint256, CTransaction>::iterator mi = mapTransactions.begin();
+                         mi != mapTransactions.end(); ++mi, ++n)
+                    {
+                        if (vfAlreadyAdded[n])
+                            continue;
+                        CTransaction& tx = (*mi).second;
+                        if (tx.IsCoinBase() || !tx.IsFinal()) continue;
+                        // Skip rather than stop: one transaction too big for
+                        // the room left does not mean the next is. Ordered
+                        // before ConnectInputs because ConnectInputs credits
+                        // nFees by reference on success, and a transaction we
+                        // then decline would leave the coinbase claiming a fee
+                        // this block does not collect.
+                        unsigned int nTxSize   = ::GetSerializeSize(tx, SER_NETWORK);
+                        unsigned int nTxSigOps = tx.GetSigOpCount();
+                        if (!BlockTemplateFits(sz, nSigOps, nTxSize, nTxSigOps))
+                            continue;
+                        map<uint256, CTxIndex> tmp(pool);
+                        if (!tx.ConnectInputs(txdb, tmp, CDiskTxPos(1,1,1), 0, nFees,
+                                              false, true, tx.GetMinFee(block.vtx.size() < 100)))
+                            continue;
+                        swap(pool, tmp);
+                        block.vtx.push_back(tx);
+                        sz      += nTxSize;
+                        nSigOps += nTxSigOps;
+                        vfAlreadyAdded[n] = true;
+                        fFoundSomething = true;
+                    }
                 }
             }
         }
 
-        block.vtx[0].vout[0].nValue = block.GetBlockValue(pindexPrev->nHeight + 1, 0);
+        // And the fees actually go to the coinbase now. nFees was declared
+        // inside the scan loop, so every transaction reset it and the total was
+        // thrown away, while this line passed a hardcoded 0. A pool operator
+        // collected fees into a block and paid none of them to itself. Solo
+        // mining has always passed nFees here; only this builder did not.
+        block.vtx[0].vout[0].nValue = block.GetBlockValue(pindexPrev->nHeight + 1, nFees);
         block.hashPrevBlock  = pindexPrev->GetBlockHash();
         block.hashMerkleRoot = block.BuildMerkleTree();
         block.nTime = max((unsigned int)(pindexPrev->GetMedianTimePast() + 1),
@@ -297,26 +399,406 @@ struct PendingPayout {
     // supposed to pay it: a 280-block reorg once left ~14.4k BTF of debt
     // owed against blocks that no longer existed, which then drained the
     // wallet paying fork-era miners out of real-chain coin.
+    //
+    // Upstream keys these on the string "block-<height>". That is the same
+    // bug this fork already paid for, and height keying additionally lets
+    // FindRecordedPoolPayout match the *previous* round's transaction after a
+    // reorg and silently skip a miner, so their `id` is deliberately dropped.
     int                          blockHeight = 0;
     // Must be explicitly zeroed: uint256's default constructor is empty
     // (uint256.h:514), so leaving this unassigned gives every ledger entry
     // loaded from an older file a garbage hash, which then matches no block
     // and gets voided as "orphaned". That mistake voided a live payout.
     uint256                      blockHash = 0;  // zero = entry predates hash keying
-    int                          matureAtHeight;
+    int                          matureAtHeight = 0;
     std::map<std::string, int64> amounts; // address -> satoshis
-    int                          retries = 0;    // exec-thread only: SendMoney attempts so far
-    int                          deferrals = 0;  // exec-thread only: waits for spendable coin
-    int64                        retryAfter = 0; // exec-thread only: unix time, 0 = ready now
+    // From upstream: which recipients already have a transaction. This is what
+    // lets an entry stay on disk until every address in `amounts` is paid,
+    // instead of being erased the moment the batch is handed off.
+    std::map<std::string, std::string> paidTxids; // address -> txid
+    // Retry and backoff state does NOT live here. It used to be declared here
+    // as well as on PayingRecord, and the copy on this side was never written:
+    // `retryAfter` was declared, serialised, loaded and tested at the flush
+    // gate, and the only assignment to it anywhere was `= 0`, so the gate could
+    // not fire. `retries` and `deferrals` were the same story. The real state
+    // is per (round, recipient) -- which is the granularity a payment can fail
+    // at -- and it lives on PayingRecord, which is now what persists it.
 };
 static std::vector<PendingPayout> gPendingPayouts;
+static std::mutex                 gPayoutLedgerMutex;
+// Bumped on every serialisation, under gPayoutLedgerMutex. See PublishVersioned.
+static uint64                     gPayoutLedgerSeq = 0;
+// Serialises writers of pending_payouts.json, and guards the sequence number
+// of the image currently on disk. Never taken while a data mutex is held.
+static std::mutex                 gPayoutLedgerFileMutex;
+static uint64                     gPayoutLedgerPublishedSeq = 0;
+
+struct PoolRoundProof {
+    std::string                  id;
+    int                          blockHeight;
+    int                          matureAtHeight;
+    int64                        createdAt;
+    std::string                  blockHash;
+    std::string                  coinbaseTxid;
+    std::string                  foundBy;
+    double                       feePercent;
+    uint64                       totalShares;
+    int64                        coinbaseValue;
+    int64                        subsidy;
+    int64                        minerReward;
+    int64                        operatorReward;
+    int                          skippedDust;
+    int64                        forfeitedBadAddress;
+    std::map<std::string, uint64> shares;
+    std::map<std::string, int64>  payouts;
+    std::map<std::string, std::string> paidTxids;
+    // Recipients the ledger has written off, and why. Without this the public
+    // round proof goes on advertising an address as owed with "txid": null
+    // forever, while the ledger has already dropped the obligation -- the two
+    // records of the same round permanently disagreeing, with the operator
+    // holding the money.
+    std::map<std::string, std::string> forfeited; // address -> reason
+
+    PoolRoundProof()
+        : blockHeight(0), matureAtHeight(0), createdAt(0), feePercent(0.0),
+          totalShares(0), coinbaseValue(0), subsidy(0), minerReward(0), operatorReward(0),
+          skippedDust(0), forfeitedBadAddress(0) {}
+};
+static std::vector<PoolRoundProof> gPoolRounds;
+static std::mutex                  gPoolRoundsMutex;
+static uint64                      gPoolRoundsSeq = 0; // guarded by gPoolRoundsMutex
+static std::mutex                  gPoolRoundsFileMutex;
+static uint64                      gPoolRoundsPublishedSeq = 0; // guarded by gPoolRoundsFileMutex
+static const size_t                MAX_POOL_ROUNDS = 200;
 
 static std::string PayoutFilePath()
 {
     return GetAppDir() + "/pending_payouts.json";
 }
 
-static void SavePendingPayouts()
+static std::string PoolRoundsFilePath()
+{
+    if (!strPoolRoundsFile.empty())
+        return strPoolRoundsFile;
+    return GetAppDir() + "/pool_rounds.json";
+}
+
+// ---------------------------------------------------------------------------
+// Atomic, ordered publication of the payout state files
+// ---------------------------------------------------------------------------
+//
+// Every one of these files is a full dump of an in-memory structure, written
+// tmp-then-rename so a crash cannot truncate it. Two things have to be true
+// for that to actually be safe, and only the first was:
+//
+//   1. the rename must be atomic (it is), and
+//   2. exactly one thread at a time may be writing the temp file, and a write
+//      must never publish an OLDER image over a newer one.
+//
+// (2) was broken for pending_payouts.json. The event loop wrote it with
+// gPayoutLedgerMutex held, the payout thread wrote it with the mutex
+// released, and nothing serialised the two: both opened the same
+// "<path>.tmp" with independent handles and both renamed it. The interleaved
+// file that lands is either a mixture of two images (LoadPendingPayouts then
+// throws mid-loop and comes up with a nearly empty ledger -- every obligation
+// not yet exploded, gone) or a whole newly-queued round silently overwritten
+// by an older snapshot that predates it.
+//
+// The fix is a per-file write mutex, held only across the I/O and never
+// across a data-structure mutex, plus a version on the snapshot. Serialising
+// happens under the data mutex and stamps a monotonically increasing sequence
+// number; publishing happens with the data mutex released and refuses any
+// blob whose sequence number is not newer than what is already on disk. So
+// writers can queue in any order and finish in any order -- the file only
+// ever moves forwards.
+//
+// The other half of the rule is that no thread waits for I/O while holding
+// gPayoutLedgerMutex, gPayoutExecMutex or gPoolRoundsMutex, which is the
+// contention the merge was right to remove from the event loop. That was
+// claimed here before it was true: pool_status.json is written by the same
+// WriteFileAtomic and RefreshStats held gPayoutLedgerMutex at function scope
+// across the call, so once the writes gained fsync() the event loop was doing
+// two of them every ten seconds with the payout thread's mutex held -- worse
+// than the buffered write the merge replaced. The status file now goes through
+// the same serialise-under-the-lock / publish-outside-it split as the ledgers,
+// and the rule holds for all four files. It is checked, not asserted: see the
+// "no payout mutex is held across a publish" section of the payout-ledger
+// self-test.
+
+// A serialised file image plus the version of the in-memory state it was
+// taken from.
+struct VersionedBlob {
+    std::string blob;
+    uint64      seq = 0;
+};
+
+// Push a file's contents out of the C library's buffer AND out of the kernel's
+// page cache, so the bytes exist on the device before anything points at them.
+static bool SyncFileHandle(FILE* f)
+{
+    if (fflush(f) != 0)
+        return false;
+#ifdef _WIN32
+    return _commit(_fileno(f)) == 0;
+#else
+    return fsync(fileno(f)) == 0;
+#endif
+}
+
+// Make the directory entry that rename() created durable too.
+//
+// A tmp+rename is only atomic with respect to a crash of the process. Against
+// a power cut or a hard VM reset the rename can reach the platter while the
+// data it points at has not, and the file that comes back is short or empty.
+// For pending_payouts.json that is not a corrupt file, it is a silent one:
+// LoadPendingPayouts catches the parse error, logs a single warning, and the
+// node comes up owing nobody anything.
+//
+// Best effort -- a filesystem that does not allow the directory to be opened
+// for this is not a reason to refuse to write the ledger.
+static void SyncDirectoryOf(const std::string& path)
+{
+#ifndef _WIN32
+    size_t slash = path.find_last_of('/');
+    std::string dir = (slash == std::string::npos) ? std::string(".")
+                                                   : path.substr(0, slash);
+    if (dir.empty())
+        dir = "/";
+    int fd = open(dir.c_str(), O_RDONLY);
+    if (fd < 0)
+        return;
+    fsync(fd);
+    close(fd);
+#endif
+}
+
+// Replace `path` with `data` atomically and durably. Caller must hold the
+// write mutex for `path`: the temp name is derived from the target, so two
+// threads in here at once for one path is precisely the race this exists to
+// prevent.
+//
+// Every failure removes the temp file before returning. It used to be left
+// where it fell, so a disk that filled up once left a short, valid-looking
+// "pending_payouts.json.tmp" next to the good ledger for as long as the node
+// ran. That file is a trap: it has the name of a half-finished save, and an
+// operator cleaning up after an incident is exactly the person who will move
+// it into place.
+//
+// Failures print unconditionally rather than through LogPrint(). These three
+// files are written under two different debug categories ("payout" for the
+// ledgers, "pool" for the status file), and a write failure is not a trace of
+// normal operation -- it is the file the operator is about to read not being
+// there. Gating it behind a category that had to be chosen before the failure
+// happened is how "could not replace pool_status.json" went missing.
+static bool WriteFileAtomic(const std::string& path, const std::string& data,
+                            const char* what)
+{
+    std::string tmp = path + ".tmp";
+    FILE* f = fopen(tmp.c_str(), "w");
+    if (!f) {
+        printf("[payout] WARNING: could not write %s (%s)\n",
+               tmp.c_str(), what);
+        return false;
+    }
+    if (!data.empty() && fwrite(data.c_str(), 1, data.size(), f) != data.size()) {
+        printf("[payout] WARNING: short write to %s (%s)\n",
+               tmp.c_str(), what);
+        fclose(f);
+        remove(tmp.c_str());
+        return false;
+    }
+    // Before the rename, not after: publishing a name that points at nothing
+    // is the failure this ordering exists to prevent. If the data cannot be
+    // made durable, do not rename -- the previous file is still intact and
+    // still correct, and the next write will try again.
+    if (!SyncFileHandle(f)) {
+        printf("[payout] WARNING: could not flush %s to disk (%s)"
+               " -- keeping the previous file\n", tmp.c_str(), what);
+        fclose(f);
+        remove(tmp.c_str());
+        return false;
+    }
+    // fclose() is where buffered data actually reaches the OS, so a failure
+    // here means the .tmp is short -- renaming it over the real file would
+    // destroy the good copy, which is exactly what these files exist to
+    // prevent.
+    if (fclose(f) != 0) {
+        printf("[payout] WARNING: could not close %s (%s)\n",
+               tmp.c_str(), what);
+        remove(tmp.c_str());
+        return false;
+    }
+#ifdef _WIN32
+    // rename() on Windows will not replace an existing file.
+    remove(path.c_str());
+#endif
+    if (rename(tmp.c_str(), path.c_str()) != 0) {
+        printf("[payout] WARNING: could not replace %s (%s)\n",
+               path.c_str(), what);
+        remove(tmp.c_str());
+        return false;
+    }
+    SyncDirectoryOf(path);
+    return true;
+}
+
+// Paths whose loader threw part-way through, and which must therefore never be
+// written again by this process.
+//
+// All three loaders push entries into the live structure INSIDE the try, so an
+// exception half way down a file leaves a PARTIAL ledger in memory -- the
+// entries before the bad one, and nothing after it. The first publish after
+// that then writes the partial state over the file, and the only record of
+// what was owed is gone. ReconcilePayouts publishes unconditionally at
+// startup, so "the first publish" is a few milliseconds later, before an
+// operator could possibly intervene. a8e2f58 named this failure mode in its
+// own commit message and then only fixed the write side.
+//
+// The file is renamed out of the way instead of being left in place, so the
+// evidence survives even if the operator restarts into the same fault, and so
+// a node that comes up owing nobody anything is visibly missing its ledger
+// rather than quietly appearing to have none.
+static std::set<std::string> gRefusedFiles;
+static std::mutex            gRefusedFilesMutex;
+
+static bool FileIsRefused(const std::string& path)
+{
+    std::lock_guard<std::mutex> lk(gRefusedFilesMutex);
+    return gRefusedFiles.count(path) > 0;
+}
+
+// Quarantine `path` and refuse to write it for the rest of the process.
+//
+// Prints unconditionally: an operator who has just lost a payout ledger must
+// be told at whatever log settings they were already running with, and the
+// name it was moved to is the only way back to the data.
+static void RefuseFileAfterLoadFailure(const std::string& path, const char* what,
+                                       const char* why)
+{
+    {
+        std::lock_guard<std::mutex> lk(gRefusedFilesMutex);
+        gRefusedFiles.insert(path);
+    }
+    std::string bad = strprintf("%s.bad.%lld", path.c_str(), (long long)GetTime());
+    bool moved = (rename(path.c_str(), bad.c_str()) == 0);
+    printf("[payout] ERROR: %s (%s) did not parse: %s\n"
+           "[payout] ERROR: what loaded before the error is a PARTIAL picture,"
+           " so this file will not be written again by this process --"
+           " restart once the cause is fixed\n"
+           "[payout] ERROR: the file %s\n",
+           path.c_str(), what, why,
+           moved ? strprintf("has been kept as %s", bad.c_str()).c_str()
+                 : "could NOT be renamed out of the way -- copy it now");
+}
+
+// Publish a versioned image of some in-memory state to `path`.
+//
+// `fileMutex` serialises writers of `path` and guards `publishedSeq`. A blob
+// older than what is already published is dropped: these files are whole-state
+// dumps, so a higher sequence number is by construction a later state of the
+// same structure and publishing it loses nothing. On a write failure
+// `publishedSeq` is deliberately left alone, so the next (newer) write still
+// gets a chance to land.
+static void PublishVersioned(const std::string& path, const VersionedBlob& v,
+                             std::mutex& fileMutex, uint64& publishedSeq,
+                             const char* what)
+{
+    // A default-constructed blob is not a snapshot of anything; it is a
+    // VersionedBlob nobody filled in. Today they are already dropped, because
+    // every serialiser stamps ++gSeq and so never produces 0, and 0 fails the
+    // seq <= publishedSeq test below -- but only for as long as publishedSeq
+    // starts at 0 and nobody writes `seq = gSeq++`. One character, and the
+    // ledger file becomes "[]". Say it out loud instead of relying on it.
+    if (!v.seq)
+        return;
+    // A file whose loader threw is not a file this process knows the contents
+    // of. Writing it would replace a full record of what was owed with
+    // whatever happened to parse before the error.
+    if (FileIsRefused(path))
+        return;
+    std::lock_guard<std::mutex> lk(fileMutex);
+    if (v.seq <= publishedSeq)
+        return;
+    if (!WriteFileAtomic(path, v.blob, what))
+        return;
+    publishedSeq = v.seq;
+}
+
+// Identity of a payout round. Used as the pool-round proof id and, more
+// importantly, as the `pool_payout_id` written into wallet transaction
+// metadata and matched by FindRecordedPoolPayout().
+//
+// Derived from the block HASH, not from its height alone. Upstream uses
+// "block-<height>", which names two different blocks identically across a
+// reorg -- and because this id is what the crash-recovery probe matches on, a
+// height-keyed id lets that probe find the *previous* round's transaction and
+// conclude a miner has already been paid when they have not. The height stays
+// in the string for readability only.
+//
+// A zero hash means the entry predates hash keying; those keep the old form so
+// anything already recorded against them still matches.
+static std::string PayoutIdForBlock(int blockHeight, const uint256& blockHash)
+{
+    if (blockHash == 0)
+        return strprintf("block-%d", blockHeight);
+    return strprintf("block-%d-%s", blockHeight,
+                     blockHash.ToString().substr(0, 16).c_str());
+}
+
+// Do these two references name the same payout round?
+//
+// The block hash alone does not decide it, and every ledger lookup used to
+// assume it did. Entries grandfathered in from a file written before payouts
+// were keyed by hash all carry hash 0, so under a hash-only comparison the
+// first zero-hash entry answers for every other one: RecordPayoutTxid writes
+// a txid against the wrong round (which is then erased as "fully paid" while
+// the real debt still stands), and ReconcilePayouts drops a live in-flight
+// record because a *different* zero-hash round happened to pay that address.
+//
+// A non-zero hash is unique and decides on its own -- that is the whole point
+// of keying on it. A zero hash falls back to the height, which
+// LoadPendingPayouts supplies for any entry that can name its own maturity.
+// Mixed hash-ness never matches: refusing to match is the safe direction for
+// every caller here, because each of them treats a match as "this debt is
+// already dealt with".
+static bool SamePayoutRound(int aHeight, const uint256& aHash,
+                            int bHeight, const uint256& bHash)
+{
+    if (aHash != bHash)
+        return false;
+    if (aHash != 0)
+        return true;
+    return aHeight == bHeight;
+}
+
+// An entry with neither a hash nor a height cannot be told apart from any
+// other entry in the same state, so nothing may be recorded against it: a
+// txid written to the wrong one reports a debt as settled that is still owed.
+// Such an entry is never paid and is logged instead -- refusing to act is the
+// safe failure, and no file this tree has ever written can produce one.
+static bool PayoutRoundIdentifiable(int height, const uint256& hash)
+{
+    return hash != 0 || height != 0;
+}
+
+static bool PayoutFullyPaid(const PendingPayout& pp)
+{
+    for (const auto& kv : pp.amounts)
+        if (pp.paidTxids.count(kv.first) == 0)
+            return false;
+    return true;
+}
+
+// Serialise the ledger and stamp it with the version it was taken at. Caller
+// must hold gPayoutLedgerMutex.
+//
+// Split from the file write so no thread holds the ledger mutex across the
+// I/O. Upstream writes the file inside the per-recipient loop with
+// gPayoutLedgerMutex held, while the event loop's FlushMaturePayouts blocks on
+// that same mutex -- one slow fsync per recipient, on the thread the miners'
+// I/O shares. The sequence number is what lets the write happen later, and
+// possibly out of order, without a stale image reaching the disk.
+static VersionedBlob SerializePendingPayoutsLocked()
 {
     nlohmann::json arr = nlohmann::json::array();
     for (const auto& pp : gPendingPayouts) {
@@ -324,21 +806,56 @@ static void SavePendingPayouts()
         obj["blockHeight"]    = pp.blockHeight;
         obj["blockHash"]      = pp.blockHash.ToString();
         obj["matureAtHeight"] = pp.matureAtHeight;
+        // No retryAfter: it was never written with anything but zero, and the
+        // retry clock that is actually used is on PayingRecord. Files that
+        // still carry the key load fine (it is ignored), and a build that
+        // expects it defaults an absent one to 0, which means "ready now" --
+        // the same answer it always got.
         nlohmann::json amounts = nlohmann::json::object();
         for (const auto& kv : pp.amounts)
             amounts[kv.first] = kv.second;
         obj["amounts"] = amounts;
+        nlohmann::json paid = nlohmann::json::object();
+        for (const auto& kv : pp.paidTxids)
+            paid[kv.first] = kv.second;
+        obj["paidTxids"] = paid;
         arr.push_back(obj);
     }
-    std::string path = PayoutFilePath();
-    FILE* f = fopen(path.c_str(), "w");
-    if (f) {
-        std::string s = arr.dump(2);
-        fwrite(s.c_str(), 1, s.size(), f);
-        fclose(f);
-    } else {
-        LogPrint("payout", "[payout] WARNING: could not write %s\n", path.c_str());
-    }
+    VersionedBlob v;
+    v.blob = arr.dump(2);
+    v.seq  = ++gPayoutLedgerSeq;
+    return v;
+}
+
+// Publish a ledger snapshot. Holds no data mutex; safe -- and intended -- to
+// call with gPayoutLedgerMutex released.
+static void PublishPendingPayouts(const VersionedBlob& v)
+{
+    PublishVersioned(PayoutFilePath(), v, gPayoutLedgerFileMutex,
+                     gPayoutLedgerPublishedSeq, "pending payout ledger");
+}
+
+// Parse a persisted block-hash field, refusing to guess. SetHex() reads
+// whatever hex prefix it finds and stops at the first character it does not
+// recognise, so a corrupt value does not fail to parse -- it parses as a
+// DIFFERENT hash. Both shapes of that are wrong in a dangerous direction: a
+// value with a hex-looking prefix ("deadbeef...") becomes a hash no block
+// ever had, which PayoutBlockStillOnChain reads as an orphaned block and
+// FlushMaturePayouts then VOIDS the debt; a value with no hex prefix at all
+// becomes 0, which is grandfathered past the orphan check on the strength
+// of garbage. A field that is not the 64-digit hex string ToString() wrote
+// is corruption, and corruption is a load failure like any other parse
+// error -- the file is quarantined, not read around.
+static uint256 ParsePayoutBlockHash(const std::string& str)
+{
+    if (str.size() != 64 ||
+        str.find_first_not_of("0123456789abcdefABCDEF") != std::string::npos)
+        throw std::runtime_error(
+            strprintf("blockHash \"%s\" is not a 64-digit hex string",
+                      str.c_str()));
+    uint256 h;
+    h.SetHex(str);
+    return h;
 }
 
 static void LoadPendingPayouts()
@@ -354,6 +871,7 @@ static void LoadPendingPayouts()
     fclose(f);
     try {
         nlohmann::json arr = nlohmann::json::parse(s);
+        std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
         for (const auto& obj : arr) {
             PendingPayout pp;
             pp.matureAtHeight = obj["matureAtHeight"].get<int>();
@@ -361,18 +879,33 @@ static void LoadPendingPayouts()
             // field. Leave blockHash zero and they are grandfathered past the
             // orphan check rather than voided on a guess.
             if (obj.contains("blockHash") && obj["blockHash"].is_string())
-                pp.blockHash.SetHex(obj["blockHash"].get<std::string>());
+                pp.blockHash =
+                    ParsePayoutBlockHash(obj["blockHash"].get<std::string>());
             if (obj.contains("blockHeight") && obj["blockHeight"].is_number())
                 pp.blockHeight = obj["blockHeight"].get<int>();
+            // Upstream's tolerance for an entry with no usable height, kept
+            // because it costs nothing and an entry that cannot name its block
+            // is worse than one derived from its maturity. COINBASE_MATURITY
+            // and not COINBASE_SPENDABLE_DEPTH: this reverses whatever the
+            // writer of *that* file used, and only files old enough to lack
+            // blockHeight are affected -- they were written when maturity was
+            // still COINBASE_MATURITY.
+            if (pp.blockHeight == 0 && pp.matureAtHeight > COINBASE_MATURITY)
+                pp.blockHeight = pp.matureAtHeight - COINBASE_MATURITY;
+            // "retryAfter" is deliberately not read. Files written by the
+            // merged build carry it, always as 0, and there is nowhere left to
+            // put it -- the retry clock is PayingRecord's.
             for (auto it = obj["amounts"].begin(); it != obj["amounts"].end(); ++it)
                 pp.amounts[it.key()] = it.value().get<int64>();
+            if (obj.contains("paidTxids") && obj["paidTxids"].is_object())
+                for (auto it = obj["paidTxids"].begin(); it != obj["paidTxids"].end(); ++it)
+                    pp.paidTxids[it.key()] = it.value().get<std::string>();
             gPendingPayouts.push_back(pp);
         }
         LogPrint("payout", "[payout] loaded %zu pending payout(s) from disk\n",
                  gPendingPayouts.size());
     } catch (const std::exception& e) {
-        LogPrint("payout", "[payout] WARNING: failed to parse %s: %s\n",
-                 path.c_str(), e.what());
+        RefuseFileAfterLoadFailure(path, "pending payout ledger", e.what());
     }
 }
 
@@ -388,6 +921,18 @@ static void LoadPendingPayouts()
 // and reconciling against the wallet on startup, is what makes a restart
 // survivable.
 struct PayingRecord {
+    // Identity of this SLOT, distinct from the identity of the payment it
+    // describes. ForgetPayment and ReschedulePayment used to find their record
+    // by comparing every field, which is only an identity while no two records
+    // can be equal -- and a restart used to produce byte-identical duplicates
+    // (see FlushMaturePayouts), so the first match absorbed every update and
+    // the second was never touched again.
+    //
+    // Process-local and deliberately not persisted: gPaying is rebuilt from
+    // disk at every start, so an id only ever has to name a slot within one
+    // run, and reading ids back would mean trusting a file to contain no
+    // duplicates. Assigned under gPayoutExecMutex from gPayingNextId.
+    uint64      id             = 0;
     int         blockHeight    = 0;
     uint256     blockHash      = 0; // zero = predates hash keying, see PendingPayout
     int         matureAtHeight = 0;
@@ -396,18 +941,66 @@ struct PayingRecord {
     int         retries    = 0;
     int         deferrals  = 0;
     int64       retryAfter = 0;
+    // Ask the wallet whether this payment already went out, once, before the
+    // first send attempt. Upstream asks on every attempt: FindRecordedPoolPayout
+    // is a linear scan of mapWallet under cs_mapWallet, per recipient, so with
+    // 2000 rotating payout addresses and a retry budget of 1440 that is a
+    // scan per address per minute for a day. The question it answers -- "did a
+    // previous process send this before it died?" -- can only change across a
+    // restart, and every restart re-sets this flag (ReconcilePayouts), so
+    // asking once per record is the whole of the answer.
+    //
+    // Not persisted: a record read back from disk is by definition a restart.
+    bool        fProbeWallet = true;
 };
 static std::vector<PayingRecord> gPaying; // guarded by gPayoutExecMutex
 static std::mutex                gPayoutExecMutex;
+static uint64                    gPayingNextId = 0; // guarded by gPayoutExecMutex
+static uint64                    gPayingSeq = 0; // guarded by gPayoutExecMutex
+static std::mutex                gPayingFileMutex;
+static uint64                    gPayingPublishedSeq = 0; // guarded by gPayingFileMutex
 static std::atomic<bool>         gPayoutThreadRunning{false};
 
+// Upstream's gPayoutExecQueue/gPayoutExecMutex/gPayoutThreadRunning are
+// declared above with gPaying: the in-flight list IS the exec queue in this
+// tree, at per-recipient rather than per-round granularity, so a second queue
+// would be a second answer to "who is owed money". Only the dedupe set is new.
+//
+// Ids of rounds currently exploded into gPaying, so a flush cannot queue the
+// same round twice. Guarded by gPayoutExecMutex. Seeded from the restored
+// in-flight list by ReconcilePayouts -- it is memory-only, and leaving it
+// empty at startup was half of why a restart duplicated everything in flight.
+static std::set<std::string>      gQueuedPayouts;
+
+// Is this exact payment already in flight? gPaying is keyed on
+// (round, address): the ledger holds one amount per address per round, so two
+// records for that pair are two standing orders to send the same money.
+// Caller must hold gPayoutExecMutex.
+static bool PaymentInFlightLocked(int blockHeight, const uint256& blockHash,
+                                  const std::string& address)
+{
+    for (const PayingRecord& e : gPaying)
+        if (e.address == address
+            && SamePayoutRound(e.blockHeight, e.blockHash, blockHeight, blockHash))
+            return true;
+    return false;
+}
+
 static std::string PayingFilePath()
 {
     return GetAppDir() + "/paying_payouts.json";
 }
 
-// Caller must hold gPayoutExecMutex.
-static void SavePayingLocked()
+// Serialise the in-flight list. Caller must hold gPayoutExecMutex.
+//
+// gPayoutExecMutex already serialises every writer of this file, so it never
+// had the interleaving race pending_payouts.json had. It is still split the
+// same way for a different reason: FlushMaturePayouts runs on the event loop
+// and holds gPayoutExecMutex, so writing (and, since this series, fsyncing)
+// the file under that mutex parks miner I/O behind the payout thread's disk.
+// The version stamp keeps the file monotonic now that the write is outside
+// the mutex that orders the writers.
+static VersionedBlob SerializePayingLocked()
 {
     nlohmann::json arr = nlohmann::json::array();
     for (const auto& r : gPaying) {
@@ -419,24 +1012,24 @@ static void SavePayingLocked()
         obj["amount"]         = r.amount;
         obj["retries"]        = r.retries;
         obj["deferrals"]      = r.deferrals;
+        // The live retry clock, which used not to be written at all: every
+        // restart handed every backing-off payment a retryAfter of 0 and put
+        // the whole set into the very next 500 ms batch, so a node restarted
+        // in a loop retried continuously instead of once a minute.
+        obj["retryAfter"]     = r.retryAfter;
         arr.push_back(obj);
     }
-    std::string path = PayingFilePath();
-    // Write to a temporary file and rename, so a crash mid-write cannot leave
-    // a truncated list of who is still owed money.
-    std::string tmp = path + ".tmp";
-    FILE* f = fopen(tmp.c_str(), "w");
-    if (!f) {
-        LogPrint("payout", "[payout] WARNING: could not write %s\n", tmp.c_str());
-        return;
-    }
-    std::string s = arr.dump(2);
-    fwrite(s.c_str(), 1, s.size(), f);
-    fflush(f);
-    fclose(f);
-    if (rename(tmp.c_str(), path.c_str()) != 0)
-        LogPrint("payout", "[payout] WARNING: could not rename %s -> %s\n",
-                 tmp.c_str(), path.c_str());
+    VersionedBlob v;
+    v.blob = arr.dump(2);
+    v.seq  = ++gPayingSeq;
+    return v;
+}
+
+// Publish an in-flight-list snapshot. Call with gPayoutExecMutex released.
+static void PublishPaying(const VersionedBlob& v)
+{
+    PublishVersioned(PayingFilePath(), v, gPayingFileMutex,
+                     gPayingPublishedSeq, "in-flight payment list");
 }
 
 static void LoadPaying()
@@ -452,26 +1045,209 @@ static void LoadPaying()
     fclose(f);
     try {
         nlohmann::json arr = nlohmann::json::parse(s);
+        // gPaying and gPayingNextId are both annotated as guarded by
+        // gPayoutExecMutex and this was mutating them without it. Safe today
+        // -- LoadPaying only runs at startup, before the payout thread is
+        // spawned -- but "safe because of where it is called from" is a fact
+        // about the caller, not about this function, and the annotation is
+        // what every other reader will trust. The mutex is uncontended here by
+        // construction, so taking it costs nothing.
+        std::lock_guard<std::mutex> lk(gPayoutExecMutex);
         for (const auto& obj : arr) {
             PayingRecord r;
             r.address        = obj["address"].get<std::string>();
             r.amount         = obj["amount"].get<int64>();
             r.matureAtHeight = obj["matureAtHeight"].get<int>();
             if (obj.contains("blockHash") && obj["blockHash"].is_string())
-                r.blockHash.SetHex(obj["blockHash"].get<std::string>());
+                r.blockHash =
+                    ParsePayoutBlockHash(obj["blockHash"].get<std::string>());
             if (obj.contains("blockHeight") && obj["blockHeight"].is_number())
                 r.blockHeight = obj["blockHeight"].get<int>();
             if (obj.contains("retries") && obj["retries"].is_number())
                 r.retries = obj["retries"].get<int>();
             if (obj.contains("deferrals") && obj["deferrals"].is_number())
                 r.deferrals = obj["deferrals"].get<int>();
+            // Absent in files written before this change; 0 means ready now,
+            // which is exactly the behaviour those files used to get.
+            if (obj.contains("retryAfter") && obj["retryAfter"].is_number())
+                r.retryAfter = obj["retryAfter"].get<int64>();
+            // Collapse duplicates as they are read. A build without the
+            // ReconcilePayouts seeding below wrote a second (and after another
+            // restart, a third) byte-identical record for every unpaid
+            // recipient, so a file written by one of those has to be cleaned
+            // up here or the pathology is inherited. The retry and deferral
+            // counts are merged upwards so collapsing does not hand the
+            // survivor a fresh budget.
+            PayingRecord* dup = NULL;
+            for (PayingRecord& e : gPaying)
+                if (e.address == r.address
+                    && SamePayoutRound(e.blockHeight, e.blockHash,
+                                       r.blockHeight, r.blockHash)) {
+                    dup = &e;
+                    break;
+                }
+            if (dup) {
+                dup->retries    = std::max(dup->retries, r.retries);
+                dup->deferrals  = std::max(dup->deferrals, r.deferrals);
+                dup->retryAfter = std::max(dup->retryAfter, r.retryAfter);
+                LogPrint("payout", "[payout] collapsing duplicate in-flight"
+                         " record for %s to %s -- one payment, one record\n",
+                         FormatMoney(r.amount).c_str(), r.address.c_str());
+                continue;
+            }
+            r.id = ++gPayingNextId;
             gPaying.push_back(r);
         }
         LogPrint("payout", "[payout] loaded %zu in-flight payment(s) from disk\n",
                  gPaying.size());
     } catch (const std::exception& e) {
-        LogPrint("payout", "[payout] WARNING: failed to parse %s: %s\n",
-                 path.c_str(), e.what());
+        RefuseFileAfterLoadFailure(path, "in-flight payment list", e.what());
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Pool round proofs (upstream cbdd06d). Disjoint from the in-flight ledger
+// above -- this is the operator's published record of how a round was split,
+// not an obligation to pay. Both sides added code at this offset; both are
+// kept.
+// ---------------------------------------------------------------------------
+static nlohmann::json PoolRoundToJson(const PoolRoundProof& r)
+{
+    nlohmann::json j;
+    j["id"] = r.id;
+    j["blockHeight"] = r.blockHeight;
+    j["matureAtHeight"] = r.matureAtHeight;
+    j["createdAt"] = r.createdAt;
+    j["blockHash"] = r.blockHash;
+    j["coinbaseTxid"] = r.coinbaseTxid;
+    j["foundBy"] = r.foundBy;
+    j["feePercent"] = r.feePercent;
+    j["totalShares"] = r.totalShares;
+    j["coinbaseValueSatoshis"] = r.coinbaseValue;
+    j["coinbaseValueBtf"] = FormatMoney(r.coinbaseValue);
+    j["subsidySatoshis"] = r.subsidy;
+    j["subsidyBtf"] = FormatMoney(r.subsidy);
+    j["minerRewardSatoshis"] = r.minerReward;
+    j["minerRewardBtf"] = FormatMoney(r.minerReward);
+    j["operatorRewardSatoshis"] = r.operatorReward;
+    j["operatorRewardBtf"] = FormatMoney(r.operatorReward);
+    j["skippedDust"] = r.skippedDust;
+    j["forfeitedBadAddressSatoshis"] = r.forfeitedBadAddress;
+    j["forfeitedBadAddressBtf"] = FormatMoney(r.forfeitedBadAddress);
+
+    j["shares"] = nlohmann::json::object();
+    for (const auto& kv : r.shares)
+        j["shares"][kv.first] = kv.second;
+
+    j["payouts"] = nlohmann::json::object();
+    for (const auto& kv : r.payouts) {
+        nlohmann::json p;
+        p["amountSatoshis"] = kv.second;
+        p["amountBtf"] = FormatMoney(kv.second);
+        std::map<std::string, std::string>::const_iterator tx = r.paidTxids.find(kv.first);
+        if (tx != r.paidTxids.end())
+            p["txid"] = tx->second;
+        else
+            p["txid"] = nullptr;
+        // Only emitted when it happened, so the common shape of the file is
+        // unchanged for anything already parsing it.
+        std::map<std::string, std::string>::const_iterator fo = r.forfeited.find(kv.first);
+        if (fo != r.forfeited.end()) {
+            p["forfeited"] = true;
+            p["forfeitReason"] = fo->second;
+        }
+        j["payouts"][kv.first] = p;
+    }
+    return j;
+}
+
+// Serialise the published round proofs. Caller must hold gPoolRoundsMutex.
+//
+// Like the in-flight list, gPoolRoundsMutex already serialises the writers
+// (RecordPoolRound on the event loop, MarkPoolRoundPaid on the payout thread),
+// so this file never had the interleaving race either -- but the event loop
+// should not be waiting on the payout thread's fsync to publish a round, so
+// the write moves outside the mutex on the same versioned terms.
+static VersionedBlob SerializePoolRoundsLocked()
+{
+    nlohmann::json root;
+    root["schema"] = "bitflash-pool-rounds-1";
+    root["updatedAt"] = GetTime();
+    root["rounds"] = nlohmann::json::array();
+    for (const PoolRoundProof& r : gPoolRounds)
+        root["rounds"].push_back(PoolRoundToJson(r));
+
+    VersionedBlob v;
+    v.blob = root.dump(2);
+    v.seq  = ++gPoolRoundsSeq;
+    return v;
+}
+
+// Publish a round-proof snapshot. Call with gPoolRoundsMutex released.
+static void PublishPoolRounds(const VersionedBlob& v)
+{
+    PublishVersioned(PoolRoundsFilePath(), v, gPoolRoundsFileMutex,
+                     gPoolRoundsPublishedSeq, "pool round proofs");
+}
+
+static void LoadPoolRounds()
+{
+    std::string path = PoolRoundsFilePath();
+    FILE* f = fopen(path.c_str(), "r");
+    if (!f) return;
+    fseek(f, 0, SEEK_END);
+    long sz = ftell(f);
+    fseek(f, 0, SEEK_SET);
+    std::string s(sz, '\0');
+    fread(&s[0], 1, sz, f);
+    fclose(f);
+
+    try {
+        nlohmann::json root = nlohmann::json::parse(s);
+        nlohmann::json arr = root.is_array() ? root : root["rounds"];
+        std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+        for (const auto& obj : arr) {
+            PoolRoundProof r;
+            if (obj.contains("id") && obj["id"].is_string()) r.id = obj["id"].get<std::string>();
+            if (obj.contains("blockHeight")) r.blockHeight = obj["blockHeight"].get<int>();
+            if (obj.contains("matureAtHeight")) r.matureAtHeight = obj["matureAtHeight"].get<int>();
+            if (obj.contains("createdAt")) r.createdAt = obj["createdAt"].get<int64>();
+            if (obj.contains("blockHash") && obj["blockHash"].is_string()) r.blockHash = obj["blockHash"].get<std::string>();
+            if (obj.contains("coinbaseTxid") && obj["coinbaseTxid"].is_string()) r.coinbaseTxid = obj["coinbaseTxid"].get<std::string>();
+            if (obj.contains("foundBy") && obj["foundBy"].is_string()) r.foundBy = obj["foundBy"].get<std::string>();
+            if (obj.contains("feePercent")) r.feePercent = obj["feePercent"].get<double>();
+            if (obj.contains("totalShares")) r.totalShares = obj["totalShares"].get<uint64>();
+            if (obj.contains("coinbaseValueSatoshis")) r.coinbaseValue = obj["coinbaseValueSatoshis"].get<int64>();
+            if (obj.contains("subsidySatoshis")) r.subsidy = obj["subsidySatoshis"].get<int64>();
+            if (obj.contains("minerRewardSatoshis")) r.minerReward = obj["minerRewardSatoshis"].get<int64>();
+            if (obj.contains("operatorRewardSatoshis")) r.operatorReward = obj["operatorRewardSatoshis"].get<int64>();
+            if (obj.contains("skippedDust")) r.skippedDust = obj["skippedDust"].get<int>();
+            if (obj.contains("forfeitedBadAddressSatoshis")) r.forfeitedBadAddress = obj["forfeitedBadAddressSatoshis"].get<int64>();
+            if (obj.contains("shares") && obj["shares"].is_object())
+                for (auto it = obj["shares"].begin(); it != obj["shares"].end(); ++it)
+                    r.shares[it.key()] = it.value().get<uint64>();
+            if (obj.contains("payouts") && obj["payouts"].is_object())
+                for (auto it = obj["payouts"].begin(); it != obj["payouts"].end(); ++it) {
+                    if (it.value().is_object()) {
+                        r.payouts[it.key()] = it.value().value("amountSatoshis", (int64)0);
+                        if (it.value().contains("txid") && it.value()["txid"].is_string())
+                            r.paidTxids[it.key()] = it.value()["txid"].get<std::string>();
+                        if (it.value().value("forfeited", false))
+                            r.forfeited[it.key()] =
+                                it.value().value("forfeitReason", std::string("unspecified"));
+                    } else if (it.value().is_number_integer()) {
+                        r.payouts[it.key()] = it.value().get<int64>();
+                    }
+                }
+            if (!r.id.empty())
+                gPoolRounds.push_back(r);
+        }
+        while (gPoolRounds.size() > MAX_POOL_ROUNDS)
+            gPoolRounds.erase(gPoolRounds.begin());
+        LogPrint("payout", "[payout] loaded %zu pool round proof(s) from disk\n",
+                 gPoolRounds.size());
+    } catch (const std::exception& e) {
+        RefuseFileAfterLoadFailure(path, "pool round proofs", e.what());
     }
 }
 
@@ -494,105 +1270,487 @@ static bool PayoutBlockStillOnChain(const uint256& blockHash)
     return false;
 }
 
-static std::string PayoutComment(int blockHeight)
+// The comment every pre-upgrade payout transaction carries, and therefore the
+// ONLY needle the legacy fallback in FindRecordedPoolPayout may search with.
+// This format is frozen: change it and every payment those builds made stops
+// matching, every one of those debts looks unpaid, and reconciliation pays
+// them all a second time.
+static std::string LegacyPayoutComment(int blockHeight)
 {
     return strprintf("Pool payout height %d", blockHeight);
 }
 
-// Did we already send this payment before dying? Looks for a wallet
-// transaction of ours carrying this payout's comment and paying exactly this
-// amount to this address.
+// The comment written on new sends. It names the funding block, because the
+// height alone cannot: a height that is won, lost to a reorg, and won again
+// yields two rounds whose height-only comments are identical -- and identical
+// amounts too, whenever the same miner held both rounds. The structured
+// pool_payout_* metadata already keys the payment by hash for the code; this
+// puts the same fact where an operator reading the wallet can see it, and
+// makes a new transaction unmatchable by the legacy needle even if the
+// structured keys are ever lost.
 //
-// Biased towards reporting "already paid" on any doubt: skipping a payment a
-// miner is owed is visible and recoverable from the log, while paying twice
-// is neither.
-static bool WalletAlreadyPaid(const PayingRecord& r)
+// A zero hash keeps the legacy form: those records predate hash keying, and
+// there is no hash to name.
+static std::string PayoutComment(int blockHeight, const uint256& blockHash)
 {
-    uint160 h160;
-    if (!AddressToHash160(r.address, h160))
-        return false;
-    CScript want;
-    want << OP_DUP << OP_HASH160 << h160 << OP_EQUALVERIFY << OP_CHECKSIG;
-    const std::string comment = PayoutComment(r.blockHeight);
+    if (blockHash == 0)
+        return LegacyPayoutComment(blockHeight);
+    return strprintf("Pool payout height %d block %s", blockHeight,
+                     blockHash.ToString().c_str());
+}
 
-    CRITICAL_BLOCK(cs_mapWallet)
+// Startup reconciliation.
+//
+// This used to be the crash-recovery mechanism: it scanned the wallet with
+// WalletAlreadyPaid() and then dropped ledger entries that had already been
+// exploded into in-flight records. Neither job is right any more.
+//
+// The ledger is now authoritative and an entry survives until every recipient
+// has a txid recorded against it (upstream cbdd06d), so dropping ledger
+// entries here would reintroduce exactly the loss this merge is adopting that
+// model to prevent. And the wallet scan is now FindRecordedPoolPayout(), done
+// once per record on its first attempt, which is the same question asked in
+// the one place that can act on the answer. Running both would be two
+// authorities for the same debt.
+//
+// What is left is the useful part: the in-flight list restored from disk may
+// contain records the ledger already shows as paid (we died between the send
+// and the in-flight file being rewritten). The ledger wins.
+//
+// And the part that was missing: gQueuedPayouts is memory-only, so it came up
+// empty while gPaying came up full. FlushMaturePayouts deduped against that
+// empty set and against the ledger's paidTxids, and against nothing else --
+// so a round that was exploded but not yet paid got a SECOND record per
+// unpaid recipient on the first flush after every restart, deterministically.
+// (Observed live: two byte-identical records for one (block, address).) The
+// surviving in-flight list is exactly the statement of which rounds are
+// already exploded, so it is what the set is rebuilt from.
+static void ReconcilePayouts()
+{
+    VersionedBlob payingSnap;
     {
-        for (std::map<uint256, CWalletTx>::iterator it = mapWallet.begin();
-             it != mapWallet.end(); ++it) {
-            CWalletTx& wtx = it->second;
-            // The comment is written only by the payout path, so its presence
-            // already identifies the transaction as one of ours.
-            std::map<std::string, std::string>::const_iterator ci =
-                wtx.mapValue.find("comment");
-            if (ci == wtx.mapValue.end() || ci->second != comment)
+        std::lock_guard<std::mutex> exec(gPayoutExecMutex);
+        std::lock_guard<std::mutex> ledger(gPayoutLedgerMutex);
+
+        size_t settled = 0;
+        int64  settledAmount = 0;
+        for (auto it = gPaying.begin(); it != gPaying.end(); ) {
+            bool paid = false;
+            for (const PendingPayout& pp : gPendingPayouts)
+                if (SamePayoutRound(pp.blockHeight, pp.blockHash,
+                                    it->blockHeight, it->blockHash)
+                    && pp.paidTxids.count(it->address)) {
+                    paid = true;
+                    break;
+                }
+            if (paid) {
+                settledAmount += it->amount;
+                settled++;
+                it = gPaying.erase(it);
+            } else {
+                // Every restored record gets one wallet probe before it is
+                // allowed to send: this is precisely the window where the
+                // wallet may hold a transaction the ledger has not recorded.
+                it->fProbeWallet = true;
+                ++it;
+            }
+        }
+        if (settled) {
+            LogPrint("payout", "[payout] %zu in-flight payment(s) totalling %s"
+                     " are already recorded paid in the ledger -- not"
+                     " resending\n",
+                     settled, FormatMoney(settledAmount).c_str());
+        }
+
+        // Rebuild the "already exploded" set from what survived. Without this
+        // the first flush after a restart re-explodes every round in flight.
+        gQueuedPayouts.clear();
+        for (const PayingRecord& r : gPaying)
+            gQueuedPayouts.insert(PayoutIdForBlock(r.blockHeight, r.blockHash));
+
+        payingSnap = SerializePayingLocked();
+
+        if (!gPaying.empty()) {
+            int64 owed = 0;
+            for (const auto& r : gPaying) owed += r.amount;
+            LogPrint("payout", "[payout] resuming %zu in-flight payment(s)"
+                     " totalling %s\n",
+                     gPaying.size(), FormatMoney(owed).c_str());
+        }
+    }
+    PublishPaying(payingSnap);
+}
+
+static void RecordPoolRound(const PoolRoundProof& round)
+{
+    VersionedBlob snap;
+    {
+        std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+        bool replaced = false;
+        for (PoolRoundProof& existing : gPoolRounds) {
+            if (existing.id == round.id) {
+                existing = round;
+                replaced = true;
+                break;
+            }
+        }
+        if (!replaced) {
+            gPoolRounds.push_back(round);
+            while (gPoolRounds.size() > MAX_POOL_ROUNDS)
+                gPoolRounds.erase(gPoolRounds.begin());
+        }
+        snap = SerializePoolRoundsLocked();
+    }
+    PublishPoolRounds(snap);
+}
+
+static void MarkPoolRoundPaid(const std::string& id,
+                              const std::string& address,
+                              const std::string& txid)
+{
+    VersionedBlob snap;
+    {
+        std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+        bool found = false;
+        for (PoolRoundProof& r : gPoolRounds) {
+            if (r.id != id)
                 continue;
-            foreach (const CTxOut& txout, wtx.vout)
-                if (txout.nValue == r.amount && txout.scriptPubKey == want)
-                    return true;
+            r.paidTxids[address] = txid;
+            found = true;
+            break;
+        }
+        if (!found)
+            return;
+        snap = SerializePoolRoundsLocked();
+    }
+    PublishPoolRounds(snap);
+}
+
+// Publish the fact that a recipient was written off, so the round proof and
+// the ledger agree. The ledger erases the amount (it is not owed any more and
+// must not be reported as sent); the proof keeps the amount visible and marks
+// it forfeited with a reason, because a miner who was promised a share is
+// entitled to see what happened to it.
+static void MarkPoolRoundForfeited(const std::string& id,
+                                   const std::string& address,
+                                   const std::string& reason)
+{
+    VersionedBlob snap;
+    {
+        std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+        bool found = false;
+        for (PoolRoundProof& r : gPoolRounds) {
+            if (r.id != id)
+                continue;
+            r.forfeited[address] = reason;
+            found = true;
+            break;
         }
+        if (!found)
+            return;
+        snap = SerializePoolRoundsLocked();
     }
+    PublishPoolRounds(snap);
+}
+
+// Does this round have a published round proof?
+//
+// Existence answers a temporal question the legacy fallback below needs:
+// which builds could have paid this round. RecordPoolRound writes the proof
+// when the round is created, and structured payout metadata (upstream
+// cbdd06d) is an ancestor of round proofs (upstream 83ba822) -- no build
+// able to write a proof has ever sent a payment that only a comment can
+// identify. A round with a proof therefore cannot have a comment-only
+// payment; one that matches it is another round's, colliding on the height.
+static bool PoolRoundHasProof(const std::string& id)
+{
+    std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+    for (const PoolRoundProof& r : gPoolRounds)
+        if (r.id == id)
+            return true;
     return false;
 }
 
-// Startup reconciliation. Drops in-flight records the wallet shows were
-// already sent, and drops ledger entries that were already exploded into
-// records (which happens if we died between writing the records and rewriting
-// the ledger -- both files then describe the same debt).
-static void ReconcilePayouts()
+// Which wallet transaction, if any, already paid this?
+//
+// Two kinds of evidence, in order of quality.
+//
+// Structured (pool_payout_id / pool_payout_address / pool_payout_amount,
+// plus pool_payout_block since this series) is upstream's, extended. The id
+// is derived from the block hash, but only from the FIRST sixteen hex digits
+// of it -- and proof-of-work concentrates zeros exactly there, so the id can
+// name two same-height rounds identically. New sends therefore record the
+// full hash as pool_payout_block, and a structured match must agree with it
+// wherever both sides have one; a transaction without the key was sent
+// before it existed, and for those the id is the best evidence there is.
+// Every transaction this build sends carries all four keys.
+//
+// But NO transaction this pool has ever sent carries it. Every payout in the
+// existing wallet has only a "comment". So on the first boot after this
+// upgrade -- precisely the boot where the binary is swapped after an unclean
+// shutdown with payments in flight -- a structured-only probe finds nothing
+// and every one of those recipients is paid a second time. The deleted
+// WalletAlreadyPaid() matched on what the payment WAS, and that evidence is
+// still there; it just has to be read.
+//
+// The legacy fallback is therefore restored, with three constraints that
+// together stop it answering for a round that is not this one:
+//
+//   1. it is only consulted when the structured lookup found nothing;
+//   2. it ignores any transaction carrying pool_payout_id. That key means this
+//      build wrote the transaction, and this build's transactions are
+//      adjudicated by the exact path -- so a NEW round's payment can never be
+//      offered as evidence for an old one. Only pre-upgrade transactions,
+//      which is exactly the population the fallback exists for, are eligible;
+//   3. `excluded` holds every txid already credited to some OTHER
+//      (round, address) pair -- from the ledger's paidTxids, which is durable,
+//      and from what this process has already claimed. One legacy transaction
+//      can therefore settle at most one debt, so N transactions can never
+//      satisfy more than N obligations;
+//
+//   4. it is not consulted at all for a round that has a round proof
+//      (fAllowLegacy, decided by the caller from PoolRoundHasProof). Proofs
+//      are written when a round is created, and only by builds whose every
+//      payment names its round exactly -- so a comment-only transaction
+//      cannot be a payment for such a round, only a same-height collision
+//      from an older one, and skipping the fallback cannot hide a real
+//      payment: the structured probe above already found any that exist.
+//
+// What is left unresolved by construction is a comment-only transaction and
+// a PROOFLESS round at the same height paying the same address the same
+// amount: two grandfathered zero-hash twins, or a twin pair from the builds
+// that keyed the ledger by hash before any metadata reached the wallet. The
+// comment carries only the height, so nothing ties the transaction to one
+// twin rather than the other. That needs a reorg.
+//
+// This used to say the losing twin's ledger entry is voided by the orphan
+// check before it can be paid. That is wrong: PayoutBlockStillOnChain()
+// returns true for a zero hash, and EVERY pre-upgrade entry has a zero hash,
+// so the orphan check is a no-op for exactly the population this fallback
+// serves.
+//
+// The outcome is still safe, by a different mechanism. SamePayoutRound()
+// treats two zero-hash entries at the same height as the SAME round, so the
+// pair is indistinguishable everywhere, not only here: FlushMaturePayouts
+// explodes one of them and skips the other as already queued,
+// PaymentInFlightLocked refuses a second record for that (round, address), and
+// RecordPayoutTxid settles against the first match. The pair therefore
+// presents as ONE debt and can be paid at most once -- which is the direction
+// that matters for a fallback whose failure mode is treating one payment as
+// proof of two.
+//
+// The cost of that mechanism, stated plainly: only one of a genuine
+// same-height pair would ever be paid. It takes a reorg AND both rounds
+// predating hash keying, and no file this tree has written since can produce
+// one, so it is a property of history rather than a live risk.
+//
+// Where the evidence genuinely runs out the fallback simply does not match,
+// and the payment is made -- paying a debt we cannot prove was settled is the
+// correct default for a pool.
+enum PayoutProbeResult {
+    PAYOUT_PROBE_NONE = 0,   // the wallet holds no record of this payment
+    PAYOUT_PROBE_STRUCTURED, // matched this build's pool_payout_* metadata
+    PAYOUT_PROBE_LEGACY      // matched a pre-upgrade comment and output
+};
+
+static PayoutProbeResult FindRecordedPoolPayout(const std::string& id,
+                                                int blockHeight,
+                                                const uint256& blockHash,
+                                                const std::string& address,
+                                                int64 amount,
+                                                bool fAllowLegacy,
+                                                const std::set<std::string>& excluded,
+                                                std::string& txidRet)
 {
-    std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+    // Built before cs_mapWallet is taken: an invalid address has no script to
+    // compare against, and the caller has already rejected those.
+    uint160 h160;
+    bool fHaveScript = AddressToHash160(address, h160);
+    CScript want;
+    if (fHaveScript)
+        want << OP_DUP << OP_HASH160 << h160 << OP_EQUALVERIFY << OP_CHECKSIG;
+    const std::string comment = LegacyPayoutComment(blockHeight);
+
+    // Candidate legacy matches, adjudicated after cs_mapWallet is released.
+    //
+    // The depth check cannot happen inside the scan: GetDepthInMainChain()
+    // reads mapBlockIndex and pindexBest, which belong to cs_main, and cs_main
+    // is taken BEFORE cs_mapWallet everywhere else in this tree
+    // (CreateTransaction, ConnectBlock). Taking it the other way round here
+    // would be a lock-order inversion in the payout thread. There is at most a
+    // handful of these: a candidate has to carry this exact height's comment
+    // and an output of exactly this amount to this address.
+    std::vector<uint256> legacyCandidates;
+
+    // One pass, not two: this scan runs under cs_mapWallet, which the whole
+    // node contends on, and the merge is already paying for it once per record.
+    CRITICAL_BLOCK(cs_mapWallet)
+    {
+        for (map<uint256, CWalletTx>::const_iterator it = mapWallet.begin();
+             it != mapWallet.end(); ++it)
+        {
+            const CWalletTx& wtx = it->second;
+            map<string, string>::const_iterator idIt = wtx.mapValue.find("pool_payout_id");
+            if (idIt != wtx.mapValue.end()) {
+                // Written by this build. Adjudicated exactly, and never
+                // offered to the fallback below.
+                if (idIt->second != id)
+                    continue;
+                map<string, string>::const_iterator addrIt = wtx.mapValue.find("pool_payout_address");
+                if (addrIt == wtx.mapValue.end() || addrIt->second != address)
+                    continue;
+                map<string, string>::const_iterator amtIt = wtx.mapValue.find("pool_payout_amount");
+                if (amtIt == wtx.mapValue.end() || amtIt->second != strprintf("%lld", amount))
+                    continue;
+                // The id alone cannot tell twin rounds at one height apart
+                // (see above); the full hash can, where the transaction
+                // recorded one. Where it did not, the id decides, as it
+                // always has -- refusing those transactions would make every
+                // payment sent before the key existed look unpaid and pay it
+                // again.
+                if (blockHash != 0) {
+                    map<string, string>::const_iterator blkIt =
+                        wtx.mapValue.find("pool_payout_block");
+                    if (blkIt != wtx.mapValue.end()
+                        && blkIt->second != blockHash.ToString())
+                        continue;   // a twin round's payment, not this round's
+                }
+                txidRet = wtx.GetHash().GetHex();
+                return PAYOUT_PROBE_STRUCTURED;
+            }
 
-    size_t settled = 0;
-    int64  settledAmount = 0;
-    for (auto it = gPaying.begin(); it != gPaying.end(); ) {
-        if (WalletAlreadyPaid(*it)) {
-            settledAmount += it->amount;
-            settled++;
-            it = gPaying.erase(it);
-        } else {
-            ++it;
+            if (!fAllowLegacy)
+                continue;   // comment-only evidence is inadmissible: rule 4
+            if (!fHaveScript)
+                continue;
+            // The comment is written only by the payout path, so its presence
+            // already identifies the transaction as one of ours.
+            map<string, string>::const_iterator ci = wtx.mapValue.find("comment");
+            if (ci == wtx.mapValue.end() || ci->second != comment)
+                continue;
+            if (excluded.count(wtx.GetHash().GetHex()))
+                continue;   // already credited to a different debt
+            foreach (const CTxOut& txout, wtx.vout)
+                if (txout.nValue == amount && txout.scriptPubKey == want) {
+                    legacyCandidates.push_back(it->first);
+                    break;
+                }
         }
     }
-    if (settled) {
-        LogPrint("payout", "[payout] %zu in-flight payment(s) totalling %s were"
-                 " already sent before the last shutdown -- not resending\n",
-                 settled, FormatMoney(settledAmount).c_str());
-        SavePayingLocked();
-    }
 
-    size_t dropped = 0;
-    for (auto it = gPendingPayouts.begin(); it != gPendingPayouts.end(); ) {
-        bool exploded = false;
-        for (const auto& r : gPaying)
-            if (r.matureAtHeight == it->matureAtHeight && r.blockHash == it->blockHash) {
-                exploded = true;
-                break;
+    // A legacy match must have CONFIRMED.
+    //
+    // The structured path does not need this and deliberately does not have
+    // it: this process sent that transaction moments ago, and a send that
+    // failed leaves nothing behind, because SendMoney calls
+    // RollbackTransactionSpent, which calls EraseFromWallet.
+    //
+    // The legacy path is the opposite case in every respect. Those
+    // transactions are days or weeks old, so whether they confirmed is a
+    // settled fact rather than an open question, and a pre-upgrade payout that
+    // never confirmed is evidence of NON-payment about to be read as payment.
+    // This chain has had a 280-block reorg (see FlushMaturePayouts): a payout
+    // invalidated by it is still sitting in mapWallet with its comment intact,
+    // and the first boot after this upgrade is exactly when it gets matched.
+    // The cost of being wrong here is a miner who is never paid and no record
+    // that they were owed.
+    CRITICAL_BLOCK(cs_main)
+    CRITICAL_BLOCK(cs_mapWallet)
+    {
+        for (const uint256& hash : legacyCandidates) {
+            map<uint256, CWalletTx>::const_iterator it = mapWallet.find(hash);
+            if (it == mapWallet.end())
+                continue;   // erased under us; it is not evidence of anything
+            int depth = it->second.GetDepthInMainChain();
+            if (depth < 1) {
+                // Loud: this is the difference between a miner having been
+                // paid and a miner about to be paid twice, decided on a fact
+                // that is easy to check and impossible to recover afterwards.
+                LogPrint("payout", "[payout] wallet tx %s carries the payout"
+                         " comment for height %d and an output of exactly %s to"
+                         " %s, but it is NOT in the main chain (depth %d) --"
+                         " refusing to read it as payment; this recipient will"
+                         " be paid\n",
+                         hash.GetHex().c_str(), blockHeight,
+                         FormatMoney(amount).c_str(), address.c_str(), depth);
+                continue;
             }
-        if (exploded) {
-            LogPrint("payout", "[payout] ledger entry for block %d is already"
-                     " in flight -- dropping the duplicate\n", it->blockHeight);
-            it = gPendingPayouts.erase(it);
-            dropped++;
-        } else {
-            ++it;
+            txidRet = hash.GetHex();
+            return PAYOUT_PROBE_LEGACY;
         }
     }
-    if (dropped) SavePendingPayouts();
+    return PAYOUT_PROBE_NONE;
+}
 
-    if (!gPaying.empty()) {
-        int64 owed = 0;
-        for (const auto& r : gPaying) owed += r.amount;
-        LogPrint("payout", "[payout] resuming %zu in-flight payment(s) totalling %s\n",
-                 gPaying.size(), FormatMoney(owed).c_str());
+// txid -> "<round id>|<address>", for payments this run has already credited
+// to a debt on legacy evidence. Stops one pre-upgrade transaction being read
+// as proof that two different obligations were met. The ledger's paidTxids
+// covers the same ground durably; this covers the window before the recovered
+// txid reaches the ledger, and the case where the ledger entry has already
+// been retired.
+static std::map<std::string, std::string> gLegacyClaimedTxids;
+static std::mutex                         gClaimedTxidMutex;
+
+// Every txid already spoken for by some payment OTHER than this one. Collected
+// before cs_mapWallet is taken: the ledger mutex must not be acquired under a
+// wallet lock.
+static void CollectForeignPayoutTxids(int blockHeight, const uint256& blockHash,
+                                      const std::string& address,
+                                      const std::string& claimKey,
+                                      std::set<std::string>& out)
+{
+    {
+        std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+        for (const PendingPayout& pp : gPendingPayouts) {
+            bool sameRound = SamePayoutRound(pp.blockHeight, pp.blockHash,
+                                             blockHeight, blockHash);
+            for (const auto& kv : pp.paidTxids)
+                if (!(sameRound && kv.first == address))
+                    out.insert(kv.second);
+        }
+    }
+    {
+        std::lock_guard<std::mutex> lk(gClaimedTxidMutex);
+        for (const auto& kv : gLegacyClaimedTxids)
+            if (kv.second != claimKey)
+                out.insert(kv.first);
     }
 }
 
+static void ClaimLegacyPayoutTxid(const std::string& txid, const std::string& claimKey)
+{
+    std::lock_guard<std::mutex> lk(gClaimedTxidMutex);
+    gLegacyClaimedTxids[txid] = claimKey;
+}
+
+// blockHash stays a uint256 and not upstream's display string: it is the key
+// this fork's payout ledger is built on, and a key that has been through
+// ToString() is a key that can be compared wrong. It is converted to text only
+// where the round proof needs text. The other three arguments are upstream's,
+// carried for the round-proof data.
 static void QueuePayouts(int blockHeight,
                          const uint256& blockHash,
+                         const std::string& coinbaseTxid,
+                         int64 coinbaseValue,
+                         const std::string& foundBy,
                          const std::map<std::string, uint64>& shareCount,
                          uint64 total)
 {
+    PoolRoundProof round;
+    round.id = PayoutIdForBlock(blockHeight, blockHash);
+    round.blockHeight = blockHeight;
+    round.matureAtHeight = blockHeight + COINBASE_SPENDABLE_DEPTH;
+    round.createdAt = GetTime();
+    round.blockHash = blockHash.ToString();
+    round.coinbaseTxid = coinbaseTxid;
+    round.coinbaseValue = coinbaseValue;
+    round.foundBy = foundBy;
+    round.feePercent = dPoolFeePercent;
+    round.totalShares = total;
+    round.shares = shareCount;
+
     if (total == 0) {
+        RecordPoolRound(round);
         LogPrint("payout", "[payout] block %d: zero shares recorded -- nothing to pay out\n",
                  blockHeight);
         return;
@@ -608,6 +1766,10 @@ static void QueuePayouts(int blockHeight,
     int64 nSubsidy = 50 * COIN;
     nSubsidy >>= (blockHeight / 210000); // halving schedule
     int64 minerReward = (int64)((double)nSubsidy * (1.0 - feeFrac));
+    int64 operatorCut = nSubsidy - minerReward;
+    round.subsidy = nSubsidy;
+    round.minerReward = minerReward;
+    round.operatorReward = operatorCut;
 
     PendingPayout pp;
     pp.blockHeight = blockHeight;
@@ -621,7 +1783,9 @@ static void QueuePayouts(int blockHeight,
     // alone on a private fork paying itself, so it says nothing about a pool
     // competing on the real chain. Waiting the extra 20 blocks makes each
     // payout funded by construction, and puts the maturity gate past the
-    // reorg depth that orphaned 280 blocks of obligations.
+    // reorg depth that orphaned 280 blocks of obligations. Upstream uses
+    // COINBASE_MATURITY here; this is a considered disagreement, not an
+    // oversight -- see the merge commit message.
     pp.matureAtHeight = blockHeight + COINBASE_SPENDABLE_DEPTH;
 
     int skipped = 0;
@@ -643,12 +1807,22 @@ static void QueuePayouts(int blockHeight,
             continue;
         }
         pp.amounts[kv.first] = amount;
+        round.payouts[kv.first] = amount;
     }
+    round.skippedDust = skipped;
+    round.forfeitedBadAddress = burned;
 
-    gPendingPayouts.push_back(pp);
-    SavePendingPayouts();
+    {
+        VersionedBlob snap;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            gPendingPayouts.push_back(pp);
+            snap = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(snap);
+    }
+    RecordPoolRound(round);
 
-    int64 operatorCut = nSubsidy - minerReward;
     LogPrint("payout",
              "[payout] block %d: subsidy %s BTF, miners get %s"
              " (fee %.2f%% = %s to operator),"
@@ -664,101 +1838,337 @@ static void QueuePayouts(int blockHeight,
                         : "");
 }
 
-// Called from event loop: move matured entries into the in-flight list (fast).
+// Called from the event loop: explode matured ledger entries into per-recipient
+// in-flight records (fast; no wallet or disk work beyond one small write).
+//
+// The ledger entry SURVIVES here. That is upstream's model and it is the
+// crash-safe one: this fork used to erase the entry as soon as its payments
+// were handed off, so a death in that window left the debt described by
+// nothing at all -- a container restart on 2026-07-30 silently dropped
+// ~1,156 BTF exactly that way. An entry is removed only once every recipient
+// in it has a txid recorded (PayoutFullyPaid), which the payout thread does.
 //
-// Ordering matters and is deliberate: the in-flight records are written and
-// fsync'd to their own file *before* the ledger entry is erased, so the debt
-// is always described by at least one of the two files. Dying in the window
-// where both describe it is handled at startup by ReconcilePayouts, which
-// drops the ledger entry it can see is already in flight.
+// gPaying is kept on top of that as the in-flight working set: it carries the
+// per-recipient retry/deferral state that a per-round `nextAttempt` cannot
+// express, and it is what the payout thread iterates. It is a cache of work
+// derived from the ledger, never an independent record of debt -- if it were
+// lost entirely the ledger would rebuild it on the next flush.
 static void FlushMaturePayouts()
 {
-    // Void obligations whose funding block lost a reorg. The coin that was
-    // meant to pay them does not exist, so paying anyway spends real-chain
-    // coin the pool owes to somebody else.
-    bool voided = false;
-    for (auto it = gPendingPayouts.begin(); it != gPendingPayouts.end(); ) {
-        if (PayoutBlockStillOnChain(it->blockHash)) { ++it; continue; }
-        int64 total = 0;
-        for (auto& kv : it->amounts) total += kv.second;
-        LogPrint("payout", "[payout] block %d (%s) was orphaned -- voiding %zu"
-                 " payment(s) totalling %s\n",
-                 it->blockHeight, it->blockHash.ToString().substr(0, 14).c_str(),
-                 it->amounts.size(), FormatMoney(total).c_str());
-        it = gPendingPayouts.erase(it);
-        voided = true;
-    }
-    if (voided) SavePendingPayouts();
-
-    std::vector<PendingPayout> ready;
-    for (auto it = gPendingPayouts.begin(); it != gPendingPayouts.end(); ) {
-        if (nBestHeight < it->matureAtHeight) { ++it; continue; }
-        LogPrint("payout", "[payout] block height %d matured -- queuing %zu payments\n",
-                 it->matureAtHeight, it->amounts.size());
-        ready.push_back(*it);   // copy first; erase after save
-        ++it;
-    }
-    if (!ready.empty()) {
-        // Record the individual payments first, and only then drop the ledger
-        // entries that produced them.
+    // Which funding blocks are still on the main chain? Asked with no payout
+    // lock held: PayoutBlockStillOnChain takes cs_main, and cs_main is held by
+    // ProcessBlock and SendMoney for long stretches. Holding the ledger mutex
+    // across it would let the event loop park the payout thread behind a chain
+    // lock it has no interest in. (It is not a deadlock either way -- nothing
+    // takes the ledger mutex while holding cs_main -- but it is exactly the
+    // kind of stall this merge is removing from the ledger path.)
+    std::vector<uint256> orphaned;
+    {
+        std::vector<uint256> hashes;
         {
-            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
-            for (const auto& pp : ready) {
-                for (const auto& kv : pp.amounts) {
-                    PayingRecord r;
-                    r.blockHeight    = pp.blockHeight;
-                    r.blockHash      = pp.blockHash;
-                    r.matureAtHeight = pp.matureAtHeight;
-                    r.address        = kv.first;
-                    r.amount         = kv.second;
-                    gPaying.push_back(r);
-                }
-            }
-            SavePayingLocked();
+            std::lock_guard<std::mutex> ledger(gPayoutLedgerMutex);
+            for (const PendingPayout& pp : gPendingPayouts)
+                hashes.push_back(pp.blockHash);
         }
+        for (const uint256& h : hashes)
+            if (!PayoutBlockStillOnChain(h))
+                orphaned.push_back(h);
+    }
+
+    std::vector<PendingPayout> ready;
+    VersionedBlob ledgerSnap;
+    {
+        std::lock_guard<std::mutex> ledger(gPayoutLedgerMutex);
+
+        // Void obligations whose funding block lost a reorg. The coin that was
+        // meant to pay them does not exist, so paying anyway spends real-chain
+        // coin the pool owes to somebody else.
+        bool voided = false;
         for (auto it = gPendingPayouts.begin(); it != gPendingPayouts.end(); ) {
-            if (nBestHeight >= it->matureAtHeight)
-                it = gPendingPayouts.erase(it);
-            else
+            if (std::find(orphaned.begin(), orphaned.end(), it->blockHash) == orphaned.end()) {
                 ++it;
+                continue;
+            }
+            int64 total = 0;
+            for (auto& kv : it->amounts) total += kv.second;
+            // Always: one line per voided entry, never a collapsed summary.
+            // A reorg voids these in a burst from this one source line.
+            LogPrintAlways("payout", "[payout] block %d (%s) was orphaned -- voiding %zu"
+                     " payment(s) totalling %s\n",
+                     it->blockHeight, it->blockHash.ToString().substr(0, 14).c_str(),
+                     it->amounts.size(), FormatMoney(total).c_str());
+            it = gPendingPayouts.erase(it);
+            voided = true;
+        }
+        if (voided) ledgerSnap = SerializePendingPayoutsLocked();
+
+        for (const PendingPayout& pp : gPendingPayouts) {
+            if (nBestHeight < pp.matureAtHeight)
+                continue;
+            if (PayoutFullyPaid(pp))
+                continue;
+            // An entry with neither a hash nor a height cannot be told apart
+            // from another in the same state, so a txid recorded against it
+            // could settle the wrong debt. Paying it is the unsafe move;
+            // leaving it standing and saying so is not.
+            if (!PayoutRoundIdentifiable(pp.blockHeight, pp.blockHash)) {
+                LogPrint("payout", "[payout] WARNING: ledger entry maturing at"
+                         " height %d names neither a block hash nor a height --"
+                         " refusing to pay %zu recipient(s) that cannot be told"
+                         " apart from another round's\n",
+                         pp.matureAtHeight, pp.amounts.size());
+                continue;
+            }
+            ready.push_back(pp);
         }
-        SavePendingPayouts();
     }
-}
+    // Outside the ledger mutex: publishing is I/O and the event loop is the
+    // one thread that must never wait on the payout thread's disk.
+    PublishPendingPayouts(ledgerSnap);
 
-// Identity of a payment, for finding its record again after SendMoney.
-// amounts is a map keyed by address, so (block, address) is already unique.
-static bool SamePayment(const PayingRecord& a, const PayingRecord& b)
-{
-    return a.matureAtHeight == b.matureAtHeight
-        && a.blockHash      == b.blockHash
-        && a.address        == b.address
-        && a.amount         == b.amount;
+    if (ready.empty())
+        return;
+
+    VersionedBlob payingSnap;
+    {
+        std::lock_guard<std::mutex> queue(gPayoutExecMutex);
+        size_t added = 0;
+        for (const PendingPayout& pp : ready) {
+            const std::string id = PayoutIdForBlock(pp.blockHeight, pp.blockHash);
+            if (gQueuedPayouts.count(id))
+                continue;   // already exploded into gPaying and still in flight
+            size_t n = 0;
+            for (const auto& kv : pp.amounts) {
+                // Upstream's per-recipient dedupe: a recipient already carrying
+                // a txid is done, even though the entry as a whole is not.
+                if (pp.paidTxids.count(kv.first))
+                    continue;
+                // The invariant, checked against the thing it is an invariant
+                // of: at most one in-flight record per (round, address). The
+                // round-level set above is an optimisation that can be wrong --
+                // it is memory only, it is rebuilt from gPaying at startup, and
+                // a stale `ready` snapshot can race a round finishing --
+                // whereas gPaying is the list being protected. A second record
+                // here is a second standing order to send the same money.
+                if (PaymentInFlightLocked(pp.blockHeight, pp.blockHash, kv.first))
+                    continue;
+                PayingRecord r;
+                r.id             = ++gPayingNextId;
+                r.blockHeight    = pp.blockHeight;
+                r.blockHash      = pp.blockHash;
+                r.matureAtHeight = pp.matureAtHeight;
+                r.address        = kv.first;
+                r.amount         = kv.second;
+                gPaying.push_back(r);
+                n++;
+            }
+            gQueuedPayouts.insert(id);
+            added += n;
+            LogPrint("payout", "[payout] block height %d matured -- queuing"
+                     " payout %s (%zu of %zu recipients still owed)\n",
+                     pp.matureAtHeight, id.c_str(), n, pp.amounts.size());
+        }
+        if (added) payingSnap = SerializePayingLocked();
+    }
+    PublishPaying(payingSnap);
 }
 
 // Settle a payment: it is either done or abandoned, either way it stops being
-// owed. Removing the record and rewriting the file is what makes the payment
-// not happen twice after a restart.
+// in flight. Note this only retires the working record -- whether the miner is
+// still OWED the money is the ledger's business, and the ledger is updated
+// separately by RecordPayoutTxid().
+//
+// Erases by record id, not by comparing fields. Value-matching was only an
+// identity for as long as no two records could be equal, and the restart bug
+// above produced records that were equal in every field: the first match then
+// absorbed every erase and every state update, and the second was never
+// touched again. The id names the slot the caller took its copy from, so the
+// update lands where it belongs whatever else is in the list.
 static void ForgetPayment(const PayingRecord& r)
 {
-    std::lock_guard<std::mutex> lk(gPayoutExecMutex);
-    for (auto it = gPaying.begin(); it != gPaying.end(); ++it)
-        if (SamePayment(*it, r)) { gPaying.erase(it); break; }
-    SavePayingLocked();
+    VersionedBlob snap;
+    {
+        std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+        for (auto it = gPaying.begin(); it != gPaying.end(); ++it)
+            if (it->id == r.id) { gPaying.erase(it); break; }
+
+        // When the last record for a round is gone the round is no longer in
+        // flight, so a later flush may explode it again if the ledger still
+        // shows recipients owed. That is the intended behaviour and it is now
+        // the only way a stalled payment ever leaves this list: a payment that
+        // keeps failing is retried forever rather than given up on, so its
+        // record stays here, and the flush that would re-explode it is stopped
+        // by PaymentInFlightLocked.
+        bool stillInFlight = false;
+        for (const auto& e : gPaying)
+            if (SamePayoutRound(e.blockHeight, e.blockHash,
+                                r.blockHeight, r.blockHash)) {
+                stillInFlight = true;
+                break;
+            }
+        if (!stillInFlight)
+            gQueuedPayouts.erase(PayoutIdForBlock(r.blockHeight, r.blockHash));
+
+        snap = SerializePayingLocked();
+    }
+    PublishPaying(snap);
 }
 
 // Persist an updated attempt count / backoff for a payment still owed.
 static void ReschedulePayment(const PayingRecord& r)
 {
-    std::lock_guard<std::mutex> lk(gPayoutExecMutex);
-    for (auto& e : gPaying)
-        if (SamePayment(e, r)) {
-            e.retries    = r.retries;
-            e.deferrals  = r.deferrals;
-            e.retryAfter = r.retryAfter;
+    VersionedBlob snap;
+    {
+        std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+        for (auto& e : gPaying)
+            if (e.id == r.id) {
+                e.retries      = r.retries;
+                e.deferrals    = r.deferrals;
+                e.retryAfter   = r.retryAfter;
+                // Carry the cleared probe flag back, or every retry re-scans
+                // the whole wallet -- the cost this merge is specifically
+                // removing.
+                e.fProbeWallet = r.fProbeWallet;
+                break;
+            }
+        snap = SerializePayingLocked();
+    }
+    PublishPaying(snap);
+}
+
+// Record that a recipient has been paid, in the ledger, which is the only
+// durable statement that the debt is settled.
+//
+// The file write happens with gPayoutLedgerMutex RELEASED. Upstream writes the
+// file inside the per-recipient loop with the mutex held, so every recipient
+// costs the event loop a full serialise+fsync it has to wait for in
+// FlushMaturePayouts. Ordering against the event loop's own writes is the
+// snapshot version's job, not the mutex's -- see PublishVersioned.
+static void RecordPayoutTxid(const PayingRecord& r, const std::string& txid)
+{
+    VersionedBlob blob;
+    bool complete = false;
+    {
+        std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+        for (auto it = gPendingPayouts.begin(); it != gPendingPayouts.end(); ++it) {
+            if (!SamePayoutRound(it->blockHeight, it->blockHash,
+                                 r.blockHeight, r.blockHash))
+                continue;
+            it->paidTxids[r.address] = txid;
+            if (PayoutFullyPaid(*it)) {
+                LogPrint("payout", "[payout] payout for block %d complete --"
+                         " removing from ledger\n", it->blockHeight);
+                gPendingPayouts.erase(it);
+                complete = true;
+            }
             break;
         }
-    SavePayingLocked();
+        blob = SerializePendingPayoutsLocked();
+    }
+    PublishPendingPayouts(blob);
+    // The round proof records a txid per address, so this is per recipient and
+    // not only on completion.
+    MarkPoolRoundPaid(PayoutIdForBlock(r.blockHeight, r.blockHash), r.address, txid);
+    if (complete)
+        LogPrint("payout", "[payout] block %d fully settled\n", r.blockHeight);
+}
+
+// Write a recipient off.
+//
+// Only ever called for a state that is DECIDABLE -- currently one: the ledger
+// names an address that is not a valid address, so no transaction paying it
+// can be constructed by this or any other build. It is not called, and must
+// not be, because a payment has failed some number of times. "The wallet said
+// no N times" is not a decidable state, it is a description of how long we
+// have been asking; a debt written off on the strength of it is a debt the
+// operator keeps, and the arithmetic that decided WHY the wallet said no was
+// wrong for a year (see PayoutThreadFn).
+//
+// The amount is removed from the entry rather than marked paid, so the money
+// is not reported as sent. Once nothing is left owed the entry retires. The
+// round proof is told separately, because dropping the obligation from the
+// ledger while pool_rounds.json goes on publishing the address as owed with
+// "txid": null leaves the pool's two records of the same round permanently
+// disagreeing.
+static void ForfeitPayoutRecipient(const PayingRecord& r, const std::string& reason)
+{
+    LogPrintAlways("payout", "[payout] writing off %s owed to %s for block %d: %s\n",
+             FormatMoney(r.amount).c_str(), r.address.c_str(), r.blockHeight,
+             reason.c_str());
+    VersionedBlob blob;
+    {
+        std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+        for (auto it = gPendingPayouts.begin(); it != gPendingPayouts.end(); ++it) {
+            if (!SamePayoutRound(it->blockHeight, it->blockHash,
+                                 r.blockHeight, r.blockHash))
+                continue;
+            it->amounts.erase(r.address);
+            // PayoutFullyPaid() returns true for an empty amounts map -- there
+            // is no recipient in it without a txid -- so the
+            // `amounts.empty()` disjunct that used to be here decided nothing.
+            if (PayoutFullyPaid(*it))
+                gPendingPayouts.erase(it);
+            break;
+        }
+        blob = SerializePendingPayoutsLocked();
+    }
+    PublishPendingPayouts(blob);
+    MarkPoolRoundForfeited(PayoutIdForBlock(r.blockHeight, r.blockHash),
+                           r.address, reason);
+}
+
+// What a failed send means for the payment's retry budget.
+//
+// A deferral is "the wallet's condition is temporarily wrong": wait, and do
+// not hold it against this payment. A fault is "the wallet is funded and
+// unlocked and still would not do it", which is worth logging loudly and
+// retrying with backoff.
+//
+// This used to be decided by re-reading GetBalance() after the failure and
+// comparing it against `amount + nTransactionFee + CENT`. Every term of that
+// was wrong:
+//
+//   * nTransactionFee is 0 in production. It is only ever assigned from the
+//     GUI preferences dialog (gui.cpp), which a headless pool node does not
+//     have, so the whole reserve was the CENT.
+//
+//   * The fee the reserve is for is GetMinFee(fDiscount=true), a STEP
+//     function of the serialised size: 0 below 10,000 bytes, and
+//     (1 + bytes/1000) * CENT at or above it -- so 11 * CENT at the step.
+//     There is no required-fee value between 1 and 11 CENT. A one-CENT
+//     reserve is therefore never the right number: below the step nothing
+//     needs reserving, and at the step it is short by a factor of eleven.
+//
+//   * A pool wallet close to broke selects many small inputs BECAUSE it is
+//     close to broke, and ~56 signed P2PKH inputs is 10 KB. The trigger and
+//     the failure are positively correlated: the guess is wrong precisely
+//     when the pool is nearly out of money.
+//
+// Concretely, with a balance of amount + 0.05: the pre-send gate passes,
+// CreateTransaction builds a >10 KB transaction, the fee becomes 0.11,
+// SelectCoins(amount + 0.11) fails, SendMoney returns false -- and the old
+// arithmetic said (amount + 0.05) < (amount + 0.01) is false, so "funded",
+// so a fault. The condition is stable, so it recurred every 60 s, and 1440 of
+// them erased the debt with the coin still in the operator's wallet.
+//
+// So stop guessing. The wallet is asked to say what it did, and this only
+// classifies the answer. WALLET_SEND_INSUFFICIENT_FUNDS is coin selection
+// failing to cover amount plus whatever fee that size of transaction
+// required, whatever that turned out to be -- no reserve to get wrong.
+enum PayoutFailureClass {
+    PAYOUT_FAILURE_DEFER = 0, // conditions are wrong; wait for them to change
+    PAYOUT_FAILURE_FAULT      // funded and unlocked, and it still would not go
+};
+
+static PayoutFailureClass ClassifyPayoutSendFailure(WalletSendResult result,
+                                                    bool fWalletLocked)
+{
+    // A locked wallet cannot sign. Nothing about this payment is wrong.
+    if (fWalletLocked)
+        return PAYOUT_FAILURE_DEFER;
+    if (result == WALLET_SEND_INSUFFICIENT_FUNDS)
+        return PAYOUT_FAILURE_DEFER;
+    return PAYOUT_FAILURE_FAULT;
 }
 
 // Payout execution thread: works through gPaying, calls SendMoney.
@@ -780,11 +2190,14 @@ static void PayoutThreadFn(void*)
         }
 
         for (PayingRecord r : batch) {
+            const std::string id = PayoutIdForBlock(r.blockHeight, r.blockHash);
+
             // Re-check here and not only at maturity: a payment can sit in this
             // list for hours across retries, and the reorg that kills its
-            // funding block can land at any point in that window.
+            // funding block can land at any point in that window. Upstream has
+            // no equivalent -- it decides once, when the entry matures.
             if (!PayoutBlockStillOnChain(r.blockHash)) {
-                LogPrint("payout", "[payout] block %d (%s) orphaned while queued"
+                LogPrintAlways("payout", "[payout] block %d (%s) orphaned while queued"
                          " -- dropping %s to %s\n",
                          r.blockHeight, r.blockHash.ToString().substr(0, 14).c_str(),
                          FormatMoney(r.amount).c_str(), r.address.c_str());
@@ -792,72 +2205,244 @@ static void PayoutThreadFn(void*)
                 continue;
             }
 
+            // Upstream's per-recipient dedupe, against the ledger rather than
+            // against the batch: if a txid is already recorded for this
+            // address, the money went out and nothing more is owed.
+            {
+                bool alreadyPaid = false;
+                {
+                    std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+                    for (const PendingPayout& pp : gPendingPayouts)
+                        if (SamePayoutRound(pp.blockHeight, pp.blockHash,
+                                            r.blockHeight, r.blockHash)
+                            && pp.paidTxids.count(r.address)) {
+                            alreadyPaid = true;
+                            break;
+                        }
+                }
+                if (alreadyPaid) {
+                    ForgetPayment(r);
+                    continue;
+                }
+            }
+
             uint160 h160;
             if (!AddressToHash160(r.address, h160)) {
-                // Should not happen -- bad addresses are filtered in QueuePayouts
-                LogPrint("payout", "[payout] SKIPPED bad address '%s'\n",
-                         r.address.c_str());
+                // Should not happen -- bad addresses are filtered in
+                // QueuePayouts. If one is here anyway it is decidable and
+                // permanent: there is no transaction that pays a string which
+                // is not an address, so retrying is not waiting for anything.
+                //
+                // This used to only ForgetPayment(), which drops the in-flight
+                // record and leaves the ledger entry claiming the debt and
+                // pool_rounds.json advertising the recipient as unpaid
+                // forever, with the next flush re-exploding it. Write it off
+                // properly and say why.
+                const std::string reason =
+                    strprintf("'%s' is not a valid address, so no transaction"
+                              " can pay it", r.address.c_str());
+                LogPrintAlways("payout", "[payout] SKIPPED bad address '%s' --"
+                         " %s owed for block %d cannot be paid\n",
+                         r.address.c_str(), FormatMoney(r.amount).c_str(),
+                         r.blockHeight);
+                ForfeitPayoutRecipient(r, reason);
                 ForgetPayment(r);
                 continue;
             }
             CScript sc;
             sc << OP_DUP << OP_HASH160 << h160 << OP_EQUALVERIFY << OP_CHECKSIG;
 
+            // Did a previous process send this and die before recording it?
+            // Only asked once per record -- see PayingRecord::fProbeWallet.
+            if (r.fProbeWallet) {
+                std::string recovered;
+                const std::string claimKey = id + "|" + r.address;
+                std::set<std::string> excluded;
+                CollectForeignPayoutTxids(r.blockHeight, r.blockHash, r.address,
+                                          claimKey, excluded);
+                // A round with a published proof was created by a build whose
+                // every payment names its round exactly, so only structured
+                // evidence can settle it -- a comment match would be another
+                // round's payment colliding on the height.
+                const bool fAllowLegacy = !PoolRoundHasProof(id);
+                r.fProbeWallet = false;
+                PayoutProbeResult probe = FindRecordedPoolPayout(
+                    id, r.blockHeight, r.blockHash, r.address, r.amount,
+                    fAllowLegacy, excluded, recovered);
+                if (probe != PAYOUT_PROBE_NONE) {
+                    if (probe == PAYOUT_PROBE_LEGACY) {
+                        // Loud on purpose: this is the upgrade path, where the
+                        // only evidence a payment went out is a comment written
+                        // by a binary that is no longer running.
+                        LogPrint("payout", "[payout] %s to %s was already paid by"
+                                 " a pre-upgrade build (wallet tx %s carries the"
+                                 " payout comment for height %d and an output of"
+                                 " exactly this amount, and no structured payout"
+                                 " metadata) -- not resending\n",
+                                 FormatMoney(r.amount).c_str(), r.address.c_str(),
+                                 recovered.c_str(), r.blockHeight);
+                        ClaimLegacyPayoutTxid(recovered, claimKey);
+                    } else {
+                        LogPrint("payout", "[payout] recovered recorded payout %s to %s"
+                                 " from wallet tx %s -- not resending\n",
+                                 FormatMoney(r.amount).c_str(), r.address.c_str(),
+                                 recovered.c_str());
+                    }
+                    RecordPayoutTxid(r, recovered);
+                    ForgetPayment(r);
+                    continue;
+                }
+            }
+
             // Waiting for coin to mature is not a failure, so it must not
             // consume the retry budget. Burning a retry every 60s means a
             // payment the pool fully intends to honour can hit GIVING UP
             // 24h later purely because the subsidy funding it had not
             // matured yet -- the miner is then silently never paid.
+            //
+            // The comparison includes the fee. It used to be against the
+            // amount alone, so a balance anywhere between amount and
+            // amount+fee sailed past this gate, failed in SendMoney, and was
+            // counted as a send FAILURE rather than a wait -- 1440 of those is
+            // 24 hours, and the recipient was erased with the money left in
+            // the operator's wallet and nothing on disk saying it was owed.
+            //
+            // nTransactionFee is the part of the fee that can be known before
+            // the transaction exists, and in production it is 0 -- it is only
+            // ever assigned from the GUI preferences dialog, which a pool node
+            // does not have -- so including it here changes nothing on this
+            // pool and is kept only because a GUI operator can set it. The
+            // rest is GetMinFee(), a function of the serialised size and
+            // therefore of how many inputs SelectCoins ends up picking, which
+            // cannot be predicted from here -- so this gate deliberately does
+            // NOT try to reserve it. Refusing to attempt a payment the wallet
+            // could actually have made would be its own way of not paying a
+            // miner. That residual is handled after the fact, by asking the
+            // wallet why it refused -- see ClassifyPayoutSendFailure.
             int64 nSpendable = GetBalance();
-            if (nSpendable < r.amount) {
+            if (nSpendable < r.amount + nTransactionFee) {
                 r.deferrals++;
                 r.retryAfter = GetTime() + 60;
                 // Hourly, not every minute: a dry pool would otherwise
                 // write one line per payment per minute forever.
                 if (r.deferrals == 1 || r.deferrals % 60 == 0)
                     LogPrint("payout", "[payout] deferring %s to %s -- only %s"
-                             " spendable (waiting %d min so far)\n",
+                             " spendable, need %s with fee (waiting %d min so far)\n",
                              FormatMoney(r.amount).c_str(), r.address.c_str(),
-                             FormatMoney(nSpendable).c_str(), r.deferrals);
+                             FormatMoney(nSpendable).c_str(),
+                             FormatMoney(r.amount + nTransactionFee).c_str(),
+                             r.deferrals);
                 ReschedulePayment(r);
                 continue;
             }
 
-            CWalletTx wtx;
-            wtx.mapValue["comment"] = PayoutComment(r.blockHeight);
+            // Likewise a locked wallet: it cannot sign, so every attempt fails
+            // for a reason that has nothing to do with this payment being
+            // payable. Left to the retry budget, an operator who locks the
+            // wallet overnight comes back to erased debts.
+            if (IsWalletLocked()) {
+                r.deferrals++;
+                r.retryAfter = GetTime() + 60;
+                if (r.deferrals == 1 || r.deferrals % 60 == 0)
+                    LogPrint("payout", "[payout] deferring %s to %s -- wallet is"
+                             " locked (waiting %d min so far)\n",
+                             FormatMoney(r.amount).c_str(), r.address.c_str(),
+                             r.deferrals);
+                ReschedulePayment(r);
+                continue;
+            }
 
-            if (SendMoney(sc, r.amount, wtx)) {
+            CWalletTx wtx;
+            wtx.mapValue["comment"] = PayoutComment(r.blockHeight, r.blockHash);
+            // Upstream's structured metadata. This is what makes the wallet
+            // probe above possible at all -- the old comment-only form could
+            // not distinguish two rounds paying the same address the same
+            // amount. Keyed by the hash-derived id, so a reorg cannot make one
+            // round's transaction answer for another's.
+            wtx.mapValue["pool_payout_id"]      = id;
+            wtx.mapValue["pool_payout_address"] = r.address;
+            wtx.mapValue["pool_payout_amount"]  = strprintf("%lld", r.amount);
+            // The full hash, not only the id's sixteen-digit prefix: the
+            // prefix of a proof-of-work hash is where the zeros live, and
+            // the probe needs to tell twin rounds at one height apart.
+            if (r.blockHash != 0)
+                wtx.mapValue["pool_payout_block"] = r.blockHash.ToString();
+
+            SendMoneyOutcome outcome;
+            if (SendMoney(sc, r.amount, wtx, outcome)) {
                 // The wallet holds the transaction before this returns, so a
-                // crash here is recoverable: ReconcilePayouts finds it by
-                // comment+address+amount and does not resend.
+                // crash between here and the ledger write is recoverable: the
+                // probe above finds it by id+address+amount and does not
+                // resend. Ledger first, in-flight record second -- the debt is
+                // described by at least one of them at every instant.
+                RecordPayoutTxid(r, wtx.GetHash().GetHex());
                 ForgetPayment(r);
-                LogPrint("payout", "[payout] paid %s to %s (tx %s)\n",
+                LogPrintAlways("payout", "[payout] paid %s to %s (tx %s)\n",
                          FormatMoney(r.amount).c_str(), r.address.c_str(),
                          wtx.GetHash().ToString().substr(0, 12).c_str());
-            } else if (r.retries < 1440) {
-                // Transient failures (reorg, locked wallet) must not silently
-                // burn the payment -- retry with backoff. Insufficient funds
-                // never lands here; it defers above.
-                r.retries++;
-                r.retryAfter = GetTime() + 60;
-                ReschedulePayment(r);
-                LogPrint("payout", "[payout] FAILED to pay %s to %s"
-                         " (%s spendable at the time) -- retry %d/1440 in 60s\n",
-                         FormatMoney(r.amount).c_str(), r.address.c_str(),
-                         FormatMoney(nSpendable).c_str(), r.retries);
             } else {
-                // Reaching here means 1440 attempts that were NOT
-                // insufficient-funds waits (those defer instead) against a
-                // block still on the main chain -- i.e. a real wallet fault,
-                // not a maturity or reorg question.
-                LogPrint("payout", "[payout] GIVING UP on %s to %s after %d"
-                         " retries -- block %d is still on-chain and %s was"
-                         " spendable, so this is a wallet fault, not maturity"
-                         " -- payment forfeited\n",
-                         FormatMoney(r.amount).c_str(), r.address.c_str(),
-                         r.retries, r.blockHeight,
-                         FormatMoney(nSpendable).c_str());
-                ForgetPayment(r);
+                // Why did it fail? The answer used to decide whether the
+                // payment eventually got erased, and it was decided by
+                // guessing from a balance snapshot -- see
+                // ClassifyPayoutSendFailure for the arithmetic and what it
+                // cost. The wallet now says what it did, and nothing here
+                // erases anything.
+                //
+                // The lock state is re-read rather than trusted from before
+                // the attempt: SendMoney takes cs_main and can block for a
+                // long time, so it may have moved underneath us. The funding
+                // answer does not need re-reading -- it is a statement about
+                // the attempt that was actually made.
+                bool fLocked = IsWalletLocked();
+                int64 nAfter = GetBalance();
+
+                if (ClassifyPayoutSendFailure(outcome.result, fLocked)
+                        == PAYOUT_FAILURE_DEFER) {
+                    // Conditions are temporarily wrong. Wait.
+                    r.deferrals++;
+                    r.retryAfter = GetTime() + 60;
+                    if (r.deferrals == 1 || r.deferrals % 60 == 0)
+                        LogPrint("payout", "[payout] deferring %s to %s -- send"
+                                 " failed with %s (%s spendable; the wallet"
+                                 " needed a fee of %s for a transaction this"
+                                 " size); waiting %d min so far\n",
+                                 FormatMoney(r.amount).c_str(), r.address.c_str(),
+                                 fLocked ? "the wallet locked" : "too little coin",
+                                 FormatMoney(nAfter).c_str(),
+                                 FormatMoney(outcome.nFeeRequired).c_str(),
+                                 r.deferrals);
+                    ReschedulePayment(r);
+                } else {
+                    // Funded, unlocked, block on the main chain, and the
+                    // wallet still would not build, sign or accept the
+                    // transaction. That is worth shouting about; it is not
+                    // grounds to keep the money.
+                    //
+                    // There is deliberately no give-up branch. It used to
+                    // forfeit the debt after 1440 of these, which is not a
+                    // decidable state -- it is a count of how long we have
+                    // been asking, and it was reached by misclassifying a
+                    // funding shortfall as a fault. A debt that is never
+                    // written off cannot be written off wrongly. The payment
+                    // stays in flight, keeps its ledger entry, keeps being
+                    // reported in pool_status.json as owed, and keeps
+                    // retrying once a minute until the operator or the wallet
+                    // makes it possible.
+                    r.retries++;
+                    r.retryAfter = GetTime() + 60;
+                    ReschedulePayment(r);
+                    // Every minute at first, then hourly: a fault that is not
+                    // going away must not turn the log into one line a minute
+                    // forever, and must not go quiet either.
+                    if (r.retries <= 5 || r.retries % 60 == 0)
+                        LogPrintAlways("payout", "[payout] FAILED to pay %s to %s"
+                                 " (%s spendable, wallet unlocked, block %d on"
+                                 " the main chain) -- attempt %d, retrying in"
+                                 " 60s; this debt stands until it is paid\n",
+                                 FormatMoney(r.amount).c_str(), r.address.c_str(),
+                                 FormatMoney(nAfter).c_str(), r.blockHeight,
+                                 r.retries);
+                }
             }
         }
 
@@ -881,6 +2466,7 @@ static StatsSnapshot                   gStats;
 static std::vector<PoolWorkerStatView> gWorkerStats;
 static std::vector<PendingPayoutView>  gPayoutViews;
 static std::mutex                      gStatsMutex;
+static int64                           gLastPoolStatusWrite = 0;
 
 void GetPoolOperatorStats(int& authorizedMiners, int& blocksFound, uint64& roundShares, double& totalHashRate)
 {
@@ -903,6 +2489,135 @@ void GetPendingPayouts(std::vector<PendingPayoutView>& out)
     out = gPayoutViews;
 }
 
+static std::string PoolStatusFilePath()
+{
+    if (!strPoolStatusFile.empty())
+        return strPoolStatusFile;
+    return GetAppDir() + "/pool_status.json";
+}
+
+// Serialise the operator status file. Caller must hold gStatsMutex (this reads
+// gStats / gWorkerStats / gPayoutViews); gPoolRoundsMutex is taken and
+// released inside.
+//
+// Split from the write for the same reason as the three ledgers, and for a
+// worse instance of the same problem. This used to be called from RefreshStats
+// with gPayoutLedgerMutex held at function scope, and once the ledger writes
+// gained fsync() that call became two fsyncs -- one on the file, one on its
+// directory -- performed by the event loop, the thread that owns every miner's
+// socket, with the mutex the payout thread needs in its hand. Measured on the
+// build host (ext4 on LVM on SSD): 3.78 ms per publish, every 10 seconds, and
+// unbounded on a shared virtual disk under load.
+//
+// Nothing here needs the ledger mutex at all: the pending-payout rows were
+// already copied into gPayoutViews under it, further up RefreshStats.
+static std::string SerializePoolStatusLocked()
+{
+    nlohmann::json j;
+    j["schema"] = "bitflash-pool-status-1";
+    j["network"] = "bitflash";
+    j["updatedAt"] = GetTime();
+
+    j["operator"] = {
+        {"name", strPoolName},
+        {"btfAddress", BtfLocalAddress()},
+        {"feePercent", dPoolFeePercent},
+        {"dashboardUrl", strPoolDashboardUrl},
+        {"roundsFile", "pool_rounds.json"}
+    };
+
+    j["node"] = {
+        {"height", nBestHeight},
+        {"poolRunning", (bool)gPoolRunning},
+        {"mode", nMineMode}
+    };
+
+    j["pool"] = {
+        {"authorizedMiners", gStats.authorizedMiners},
+        {"blocksFoundSession", gStats.blocksFound},
+        {"roundShares", gStats.roundShares},
+        {"hashRate", gStats.totalHashRate}
+    };
+
+    j["workers"] = nlohmann::json::array();
+    for (const PoolWorkerStatView& row : gWorkerStats) {
+        j["workers"].push_back({
+            {"address", row.address},
+            {"worker", row.worker},
+            {"totalShares", row.totalShares},
+            {"roundShares", row.roundShares},
+            {"lastSeen", row.lastSeen},
+            {"hashRate", row.hashRate}
+        });
+    }
+
+    j["pendingPayouts"] = nlohmann::json::array();
+    for (const PendingPayoutView& row : gPayoutViews) {
+        j["pendingPayouts"].push_back({
+            {"matureAtHeight", row.matureAtHeight},
+            {"recipients", row.recipients},
+            {"totalAmountSatoshis", row.totalAmount},
+            {"totalAmountBtf", FormatMoney(row.totalAmount)}
+        });
+    }
+
+    j["recentRounds"] = nlohmann::json::array();
+    {
+        std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+        size_t start = gPoolRounds.size() > 10 ? gPoolRounds.size() - 10 : 0;
+        for (size_t i = start; i < gPoolRounds.size(); i++) {
+            const PoolRoundProof& r = gPoolRounds[i];
+            // A forfeited recipient is not "unpaid and pending" -- the ledger
+            // has already dropped the obligation. Counting it as unpaid is
+            // what made the round proof and the ledger disagree for good.
+            int unpaid = 0;
+            int forfeited = 0;
+            for (const auto& kv : r.payouts) {
+                if (r.paidTxids.count(kv.first))
+                    continue;
+                if (r.forfeited.count(kv.first))
+                    forfeited++;
+                else
+                    unpaid++;
+            }
+            j["recentRounds"].push_back({
+                {"id", r.id},
+                {"blockHeight", r.blockHeight},
+                {"blockHash", r.blockHash},
+                {"coinbaseTxid", r.coinbaseTxid},
+                {"totalShares", r.totalShares},
+                {"payouts", (int)r.payouts.size()},
+                {"unpaidPayouts", unpaid},
+                {"forfeitedPayouts", forfeited},
+                {"coinbaseValueBtf", FormatMoney(r.coinbaseValue)},
+                {"minerRewardBtf", FormatMoney(r.minerReward)}
+            });
+        }
+    }
+
+    return j.dump(2);
+}
+
+// Publish the operator status file. Call with every payout mutex released.
+//
+// Still no version guard and no write mutex, deliberately, and the split does
+// not change the argument: RefreshStats remains the only caller of either
+// half, in production it runs only on the event loop, and it now calls this
+// after leaving the scope that serialised -- so the serialise and the write
+// stay strictly ordered on one thread and pool_status.json still has a single
+// writer by construction. It shares WriteFileAtomic so the durability rules
+// stay in one place.
+//
+// "In production" is doing real work in that sentence. The payout-ledger
+// self-test also calls RefreshStats, from one thread at a time and with the
+// pool not running, which is why it is still a single writer there too. A
+// second concurrent caller anywhere would invalidate this paragraph and want
+// the same versioned publish the ledgers use.
+static void PublishPoolStatus(const std::string& blob)
+{
+    WriteFileAtomic(PoolStatusFilePath(), blob, "pool status");
+}
+
 // ---------------------------------------------------------------------------
 // Miner state -- event loop thread only
 // ---------------------------------------------------------------------------
@@ -928,9 +2643,35 @@ static const double VARDIFF_MAX               = 1e12;
 static const int64  VARDIFF_STALL_SECS        = 45;  // 3x share target -- reacts faster without false-triggering on normal variance
 static const double VARDIFF_STALL_CUT         = 4.0; // divide difficulty by this much
 
+// #7: m->hashRate is an EWMA sampled only when a share arrives, so a miner
+// that stops hashing keeps its last estimate forever and RefreshStats sums
+// it into the announced pool total for as long as the connection sits open
+// -- the published pool hashrate ran several times over ground truth
+// because of exactly this. MinerReportedHashRate() below applies the
+// policy: a miner gets a grace of HASHRATE_IDLE_MISSES expected share
+// intervals (expected interval = expected hashes per share at its
+// difficulty, divided by the estimate itself) with no share, after which
+// the figure we report falls off with a half-life of one more such
+// interval. The interval is clamped to [HASHRATE_MIN_INTERVAL,
+// HASHRATE_MAX_INTERVAL] so a fast miner at the vardiff floor (expected
+// interval of milliseconds) is not punished for ordinary share-delivery
+// jitter, and a very slow miner's grace does not stretch past the point
+// where its estimate means anything. At the vardiff target of one share
+// per 15s that is a minute of grace, half the rate reported 75s in, and
+// nothing reported after about seventeen minutes of silence.
+static const double HASHRATE_IDLE_MISSES  = 4.0;    // grace, in expected share intervals
+static const double HASHRATE_MIN_INTERVAL = 1.0;    // seconds; floor for the expected interval
+static const double HASHRATE_MAX_INTERVAL = 3600.0; // seconds; ceiling for the expected interval
+// Half-lives past the grace beyond which we report a flat zero. 2^-64 of the
+// original estimate is not a number anyone needs, and stopping here keeps
+// pow() from walking down into the denormals for a miner that has been quiet
+// for hours.
+static const double HASHRATE_DECAY_CUTOFF = 64.0;
+
 struct Miner {
     btf_socket_t fd;
     bool         authorised    = false;
+    bool         subscribed    = false;  // completed mining.subscribe (#19 census)
     std::string  address;
     std::string  worker;
     std::string  readBuf;
@@ -954,11 +2695,80 @@ struct Miner {
     int64        lastShareTime  = 0;     // GetTime() of the previous accepted share
     double       hashRate       = 0.0;   // smoothed H/s estimate
 
+    // Replay guard for mining.submit (#8): nonces already credited on this
+    // connection for the job it is currently working. Keyed to the job id in
+    // seenNoncesJob and cleared by SendJob whenever that id changes, so a
+    // resubmission under a NEW job is never turned away, while a replayed
+    // (job_id, nonce) pair under the same job is refused before it can be
+    // credited twice into roundShareCount -- the figure the payout split
+    // divides by.
+    std::set<uint32_t> seenNonces;
+    std::string        seenNoncesJob;
+
     explicit Miner(btf_socket_t f)
         : fd(f), connectTime(GetTime()),
           extranonce2(gNextExtranonce2.fetch_add(1)) {}
 };
 
+// What we publish as a miner's H/s: the last EWMA sample, faded out if shares
+// have stopped arriving (#7, policy at HASHRATE_IDLE_MISSES).
+//
+// This reads m->hashRate and never writes it. That is the whole design. The
+// first attempt decayed the stored estimate in place from the event loop's
+// sweep, which put a running accumulator behind a figure that is only ever
+// displayed, and the accumulator misbehaved in two ways:
+//
+//   - `expected` was recomputed from the already-decayed estimate on every
+//     pass, so each decay raised `expected`, which raised `grace`, which is
+//     the very thing gating the next decay. `grace` simply chased `silent`
+//     upward and the reported rate settled into a 1/t crawl instead of the
+//     half-life curve the comment above promises -- 291x too high at ten
+//     half-lives past the grace. Issue #7 is about the pool over-reporting;
+//     that under-corrected it for hours.
+//   - Once `expected` reached HASHRATE_MAX_INTERVAL it could not rise any
+//     further, the feedback that had been gating each pass was gone, and the
+//     decay began compounding once a second against the total elapsed
+//     silence -- taking a miner from 0.4% of its baseline to 1e-11 of it in
+//     the next hundred seconds, four hours in, for no reason a reader of
+//     either the code or the announced number could see.
+//
+// Computing the value instead of accumulating it removes the failure mode
+// rather than tuning it: with no stored decay state there is nothing for a
+// tick rate, a missed pass or a duplicated pass to perturb, and the answer
+// depends only on how long the miner has actually been quiet. It also keeps
+// the fade out of the estimator -- the EWMA on the share path still blends
+// against the value it last computed, not against a faded copy of it, so a
+// miner that resumes recovers on exactly the curve it would have without any
+// of this.
+//
+// `now` is a parameter rather than a GetTime() call so that one refresh fades
+// every miner to the same instant, and so the policy is directly testable.
+static double MinerReportedHashRate(const Miner* m, int64 now)
+{
+    // Nothing sampled yet: a fresh connection, or one that has found a single
+    // share and so has no interval to have been timed over. Nothing to fade,
+    // and nothing to divide by below.
+    if (m->hashRate <= 0.0 || m->lastShareTime <= 0) return m->hashRate;
+
+    double expected = ExpectedHashesForDifficulty(m->difficulty) / m->hashRate;
+    // Written so that a NaN would land on the floor rather than sail through:
+    // the clamp is what guarantees `expected` is finite and strictly positive
+    // below, whatever the division produced.
+    if (!(expected > HASHRATE_MIN_INTERVAL)) expected = HASHRATE_MIN_INTERVAL;
+    if (expected > HASHRATE_MAX_INTERVAL)    expected = HASHRATE_MAX_INTERVAL;
+
+    double silent = (double)(now - m->lastShareTime);
+    double grace  = HASHRATE_IDLE_MISSES * expected;
+    // grace is at least HASHRATE_IDLE_MISSES seconds, so a clock that has
+    // stepped backwards gives a negative `silent`, takes this branch, and
+    // reports the sample unchanged. Nothing here can scale an estimate up.
+    if (!(silent > grace)) return m->hashRate;
+
+    double halflives = (silent - grace) / expected;
+    if (halflives >= HASHRATE_DECAY_CUTOFF) return 0.0;
+    return m->hashRate * pow(0.5, halflives);
+}
+
 static std::vector<Miner*> gMiners;
 
 struct FoundBlock { int height; int64 ts; std::string addr; };
@@ -1009,6 +2819,18 @@ static void LocalAcceptFn(void*)
                 break;
             continue;
         }
+        // #6: let the OS probe a peer that has gone silent, so a half-open
+        // session eventually errors out of recv and lands in the event
+        // loop's existing reap path instead of sitting in gMiners forever.
+        // This is a backstop, not the mechanism: the default cadence before
+        // the first probe is hours on most stacks, so the idle timeout in
+        // PoolEventLoop fires long before keepalive does. Miners arriving
+        // via a relay ride a loopback socket pair whose remote transport is
+        // the rendezvous socket owned by the tunnel pump threads; keepalive
+        // cannot reach across that, which is part of why the idle timeout
+        // exists.
+        int keepalive = 1;
+        setsockopt(c, SOL_SOCKET, SO_KEEPALIVE, (char*)&keepalive, sizeof(keepalive));
         LogPrint("pool", "[pool] miner arrived via loopback -- pushing to event loop\n");
         PushReady((btf_socket_t)c);
     }
@@ -1039,6 +2861,30 @@ static bool SendLine(btf_socket_t fd, const json& j)
 static const size_t MAX_STRATUM_LINE = 64 * 1024;
 static const size_t MAX_POOL_MINERS  = 1000;
 
+// #19 instrumentation: the "broadcast to N miner(s)" line counts connected
+// sockets, which says nothing about how many are actually mining. These split
+// the connection census into connected / subscribed / authorized / recently
+// active, so an operator can tell a real workforce from a pile of half-open
+// sessions at a glance.
+static const int64 POOL_CENSUS_SECS       = 60;  // how often to log the breakdown
+static const int64 POOL_ACTIVE_WINDOW     = 300; // a miner is "active" if it
+                                                 // authorized and was seen within
+                                                 // this window (one payout-rotate
+                                                 // cycle)
+static const int64 POOL_UNAUTH_GRACE_SECS = 60;  // a connection still not
+                                                 // authorized after this long is
+                                                 // idle, not merely starting up
+// #6: a Miner used to leave gMiners only when RecvLine reported a clean
+// disconnect. A half-open session (miner host died, NAT state expired,
+// cable pulled) sends no FIN and reports no error, so it sat in the table
+// forever -- authorize outpaced disconnect 2:1 on the live pool, and the
+// table grew toward MAX_POOL_MINERS, past which real miners are refused.
+// lastSeen is stamped on every complete line received; a miner that has
+// said nothing for this long is gone in every way that matters. Ten
+// minutes is far beyond the vardiff target (a share every 15s) and the
+// stall watchdog (45s), so no miner that is actually hashing comes close.
+static const int64 POOL_IDLE_TIMEOUT_SECS = 600;
+
 // Non-blocking recv: pull whatever bytes are available now into buf, then
 // return one complete line if one is ready. Three outcomes:
 //   true  -- line is filled; buf may still contain more lines
@@ -1122,6 +2968,17 @@ static json MakeNotifyParams(const StratumJob& job, const CBlock& b,
 static void SendJob(Miner* m, bool clean)
 {
     if (!gHaveJob) return;
+    // Every path that hands a miner a new job funnels through here, so this
+    // is the one place the replay guard needs to follow the job id: nonces
+    // credited under the previous job mean nothing under the new one. Keying
+    // the clear to the id (rather than clearing unconditionally) keeps a
+    // same-job re-notify -- the vardiff retarget and stall watchdog both
+    // re-send the CURRENT job -- from reopening the duplicate window it
+    // exists to close.
+    if (m->seenNoncesJob != gCurrentJob.jobId) {
+        m->seenNonces.clear();
+        m->seenNoncesJob = gCurrentJob.jobId;
+    }
     CBlock mb = BuildMinerBlock(gCurrentJob, m->extranonce2);
     // Use this miner's own shareTarget (set by vardiff) in the notify params.
     // The participant miner reads p[3] as its share target, and HandleLine
@@ -1147,6 +3004,65 @@ static void BroadcastJob(bool clean)
 }
 
 // ---------------------------------------------------------------------------
+// #19: connection census. "broadcast to N miner(s)" only counts authorized
+// sockets that got a job; it says nothing about the rest of the connection
+// table. This logs the full breakdown so an operator can tell a real workforce
+// apart from half-open / never-authorized / idle sessions, and flags when the
+// single select() loop is running out of room (issue #26).
+//
+// "Out of room" is not the same question on both platforms, and FD_SETSIZE
+// answers a different one on each. On POSIX it bounds the *value* of any
+// descriptor handed to FD_SET, so what matters is the highest fd we hold. On
+// Windows an fd_set is a counted array of SOCKET handles whose numeric values
+// are arbitrary, so what matters is how many we hold, not how large they are.
+// FD_SETSIZE comes from <sys/select.h> or winsock2.h; this file must not define
+// it, because redefining it after those headers changes nothing.
+// ---------------------------------------------------------------------------
+static void LogPoolConnectionCensus()
+{
+    int connected = 0, subscribed = 0, authorized = 0, active = 0, neverAuthIdle = 0;
+    int64 now = GetTime();
+#ifndef _WIN32
+    int maxfd = 0;
+#endif
+    for (Miner* m : gMiners) {
+        connected++;
+#ifndef _WIN32
+        if ((int)m->fd > maxfd) maxfd = (int)m->fd;
+#endif
+        if (m->subscribed) subscribed++;
+        if (m->authorised) {
+            authorized++;
+            if (m->lastSeen > 0 && now - m->lastSeen <= POOL_ACTIVE_WINDOW)
+                active++;
+        } else if (now - m->connectTime >= POOL_UNAUTH_GRACE_SECS) {
+            neverAuthIdle++; // past the grace period and still not authorized
+        }
+    }
+
+#ifndef _WIN32
+    int headroom = (int)FD_SETSIZE - maxfd;
+    LogPrint("pool", "[pool] census: connected=%d subscribed=%d authorized=%d"
+             " active(last %llds)=%d never-auth-idle=%d"
+             "  (cap=%zu, maxfd=%d, FD_SETSIZE=%d)\n",
+             connected, subscribed, authorized, (long long)POOL_ACTIVE_WINDOW,
+             active, neverAuthIdle, MAX_POOL_MINERS, maxfd, (int)FD_SETSIZE);
+#else
+    int headroom = (int)FD_SETSIZE - connected;
+    LogPrint("pool", "[pool] census: connected=%d subscribed=%d authorized=%d"
+             " active(last %llds)=%d never-auth-idle=%d"
+             "  (cap=%zu, FD_SETSIZE=%d sockets)\n",
+             connected, subscribed, authorized, (long long)POOL_ACTIVE_WINDOW,
+             active, neverAuthIdle, MAX_POOL_MINERS, (int)FD_SETSIZE);
+#endif
+    if (headroom <= 16)
+        LogPrint("pool", "[pool] WARNING: %d slots left before FD_SETSIZE=%d --"
+                 " the select() loop is about to walk into undefined behaviour"
+                 " (#26). Refuse new miners or rebuild with poll/epoll.\n",
+                 headroom, (int)FD_SETSIZE);
+}
+
+// ---------------------------------------------------------------------------
 // Stratum message handler -- called for each complete line from a miner
 // Returns false if the miner should be disconnected immediately.
 // ---------------------------------------------------------------------------
@@ -1214,6 +3130,7 @@ static bool HandleLine(Miner* m, const std::string& rawLine,
     // ------------------------------------------------------------------
     if (method == "mining.subscribe") {
         std::string sid = ToHex(&m->fd, 4);
+        m->subscribed = true;
         LogPrint("worker", "[worker->pool] subscribe from fd=%d sid=%s\n",
                  (int)m->fd, sid.c_str());
         reply(json::array({json::array({json::array({"mining.notify",sid})}),sid,4}));
@@ -1320,6 +3237,22 @@ static bool HandleLine(Miner* m, const std::string& rawLine,
         }
         unsigned int nNonce; memcpy(&nNonce, nb.data(), 4);
 
+        // Reject a replayed (job, nonce) before it costs a rebuild and a
+        // RandomX hash: nothing about the work below distinguishes a second
+        // submission of a valid share from the first, so without this check
+        // it passes every test and is credited again -- and roundShareCount
+        // is what the payout split divides by, so each replay multiplies the
+        // address's cut of the round. The set is per-connection and cleared
+        // by SendJob on every job change, so only a same-job repeat is
+        // refused.
+        if (m->seenNonces.count(nNonce)) {
+            LogPrint("worker", "[worker->pool] duplicate share from %s"
+                     " nonce=%u job=%s -- already credited, not counting again\n",
+                     m->address.c_str(), nNonce, submitJobId.c_str());
+            reply(false, "Duplicate share");
+            return true;
+        }
+
         // Rebuild this miner's exact block (unique merkle via extranonce2)
         CBlock b = BuildMinerBlock(gCurrentJob, m->extranonce2);
         b.nNonce = nNonce;
@@ -1347,6 +3280,7 @@ static bool HandleLine(Miner* m, const std::string& rawLine,
         m->roundShares++;
         m->totalShares++;
         m->vardiffShares++;
+        m->seenNonces.insert(nNonce); // replay guard: credit each nonce once per job
         int64 shareTime = GetTime();
         m->lastSeen = shareTime;
         roundShareCount[m->address]++;
@@ -1453,7 +3387,11 @@ static bool HandleLine(Miner* m, const std::string& rawLine,
             int foundHeight = gCurrentJob.height;
             // b is the block we submitted, untouched by ProcessBlock (which
             // took a copy), so its hash is what the payout must be keyed on.
-            QueuePayouts(foundHeight, b.GetHash(), roundShareCount, roundShareTotal);
+            // Passed as a uint256, not hex: the ledger key must stay a real
+            // hash. The remaining arguments are upstream's round-proof data.
+            QueuePayouts(foundHeight, b.GetHash(), b.vtx[0].GetHash().GetHex(),
+                         b.vtx[0].vout[0].nValue, m->address,
+                         roundShareCount, roundShareTotal);
             // Reset round shares
             roundShareCount.clear();
             roundShareTotal = 0;
@@ -1480,49 +3418,1892 @@ static bool HandleLine(Miner* m, const std::string& rawLine,
 }
 
 // ---------------------------------------------------------------------------
-// Stats refresh -- called every 2s from event loop
+// payout-ledger self-test
+//
+// Regression cover for the payout defects fixed in this series. Everything
+// here runs against a scratch data directory and an in-memory wallet map; it
+// never opens wallet.dat, never touches a real datadir, and never sends
+// anything.
 // ---------------------------------------------------------------------------
-static void RefreshStats(int blocksFoundThisSession, uint64 roundShareTotal)
+
+static bool PayoutTestReadFile(const std::string& path, std::string& out)
 {
-    std::lock_guard<std::mutex> lk(gStatsMutex);
+    FILE* f = fopen(path.c_str(), "r");
+    if (!f) return false;
+    fseek(f, 0, SEEK_END);
+    long sz = ftell(f);
+    fseek(f, 0, SEEK_SET);
+    out.assign((size_t)(sz > 0 ? sz : 0), '\0');
+    if (sz > 0 && fread(&out[0], 1, (size_t)sz, f) != (size_t)sz) {
+        fclose(f);
+        return false;
+    }
+    fclose(f);
+    return true;
+}
 
-    gStats.authorizedMiners = 0;
-    gStats.blocksFound      = blocksFoundThisSession;
-    gStats.roundShares      = roundShareTotal;
-    gStats.totalHashRate    = 0.0;
-    for (Miner* m : gMiners)
-        if (m->authorised) gStats.authorizedMiners++;
+// Delete the scratch data directory and everything in it. A sweep and not a
+// list of known names: LogPrint binds debug.log to whatever GetAppDir() is
+// when it first fires, so the test's own log lands in here too, and a
+// directory left behind in src/ after `make tests` is litter.
+static void PayoutTestRemoveDir(const std::string& dir)
+{
+#ifdef _WIN32
+    WIN32_FIND_DATAA findData;
+    HANDLE hFind = FindFirstFileA((dir + "\\*").c_str(), &findData);
+    if (hFind != INVALID_HANDLE_VALUE) {
+        do {
+            std::string name = findData.cFileName;
+            if (name == "." || name == "..") continue;
+            DeleteFileA((dir + "\\" + name).c_str());
+        } while (FindNextFileA(hFind, &findData));
+        FindClose(hFind);
+    }
+    RemoveDirectoryA(dir.c_str());
+#else
+    // One level of recursion, because CreateTransaction() opens a Berkeley DB
+    // environment and BDB puts its logs in a "database" subdirectory. Without
+    // this the scratch directory cannot be removed and the test leaves one
+    // behind on every run, which is what d5b3503 was for.
+    DIR* d = opendir(dir.c_str());
+    if (d) {
+        struct dirent* ent;
+        while ((ent = readdir(d)) != NULL) {
+            std::string name = ent->d_name;
+            if (name == "." || name == "..") continue;
+            const std::string path = dir + "/" + name;
+            if (unlink(path.c_str()) != 0)
+                PayoutTestRemoveDir(path);
+        }
+        closedir(d);
+    }
+    rmdir(dir.c_str());
+#endif
+}
 
-    gWorkerStats.clear();
-    for (Miner* m : gMiners) {
-        if (!m->authorised || m->lastSeen <= 0) continue;
-        PoolWorkerStatView v;
-        v.address     = m->address;
-        v.worker      = m->worker;
-        v.roundShares = m->roundShares;
-        v.totalShares = m->totalShares;
-        v.lastSeen    = m->lastSeen;
-        v.hashRate    = m->hashRate;
-        gWorkerStats.push_back(v);
-        gStats.totalHashRate += m->hashRate;
-    }
-    std::sort(gWorkerStats.begin(), gWorkerStats.end(),
-        [](const PoolWorkerStatView& a, const PoolWorkerStatView& b) {
-            return a.roundShares != b.roundShares ? a.roundShares > b.roundShares
-                                                  : a.lastSeen > b.lastSeen;
+static bool PayoutTestWriteFile(const std::string& path, const std::string& data)
+{
+    FILE* f = fopen(path.c_str(), "w");
+    if (!f) return false;
+    bool ok = data.empty() || fwrite(data.c_str(), 1, data.size(), f) == data.size();
+    return fclose(f) == 0 && ok;
+}
+
+// Wipe every piece of payout state this test touches, so each section starts
+// from the same place and a "restart" can be simulated by reloading from disk.
+static void PayoutTestResetState()
+{
+    {
+        std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+        gPendingPayouts.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+        gPaying.clear();
+        gQueuedPayouts.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+        gPoolRounds.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lk(gClaimedTxidMutex);
+        gLegacyClaimedTxids.clear();
+    }
+    {
+        // A quarantine is meant to last the life of the process; each section
+        // here is a fresh process as far as the code under test is concerned.
+        std::lock_guard<std::mutex> lk(gRefusedFilesMutex);
+        gRefusedFiles.clear();
+    }
+}
+
+// A BTF address whose hash160 is entirely under the test's control, so the
+// output script the probe compares against can be built without a wallet.
+static std::string PayoutTestAddress(unsigned char seed)
+{
+    uint160 h = 0;
+    for (int i = 0; i < 20; i++)
+        ((unsigned char*)&h)[i] = (unsigned char)(seed + i);
+    return Hash160ToAddress(h);
+}
+
+static CScript PayoutTestScriptFor(const std::string& address)
+{
+    uint160 h160;
+    CScript sc;
+    if (AddressToHash160(address, h160))
+        sc << OP_DUP << OP_HASH160 << h160 << OP_EQUALVERIFY << OP_CHECKSIG;
+    return sc;
+}
+
+// Block index entries fabricated by PayoutTestAddWalletTx, so they can be
+// freed and unhooked when the test finishes. gPayoutTestChainTip is the end of
+// that chain: blocks are linked onto it rather than each replacing the tip,
+// because IsInMainChain() is "pnext is set, or I am the tip".
+static std::vector<CBlockIndex*> gPayoutTestBlockIndexes;
+static CBlockIndex*              gPayoutTestChainTip = NULL;
+
+static void PayoutTestClearBlockIndex()
+{
+    CRITICAL_BLOCK(cs_main)
+    {
+        for (CBlockIndex* p : gPayoutTestBlockIndexes) {
+            for (std::map<uint256, CBlockIndex*>::iterator it = mapBlockIndex.begin();
+                 it != mapBlockIndex.end(); ) {
+                if (it->second == p) mapBlockIndex.erase(it++);
+                else ++it;
+            }
+            delete p;
+        }
+        gPayoutTestBlockIndexes.clear();
+        gPayoutTestChainTip = NULL;
+        pindexBest = NULL;
+    }
+}
+
+// Put a transaction in the wallet map that looks exactly like one this pool
+// sent. `nonce` only exists to keep the hashes distinct.
+//
+// fConfirmed decides what GetDepthInMainChain() will answer for it, which is
+// what the legacy probe now gates on. A confirmed one is given a block index
+// entry of its own: an empty merkle branch hashes to the transaction itself,
+// so a block whose merkle root IS that hash accepts it at index 0, and
+// pointing pindexBest at that block puts it in the main chain one deep. An
+// unconfirmed one keeps hashBlock 0, which is depth 0 -- the shape a payout
+// left behind by a reorg has.
+static std::string PayoutTestAddWalletTx(const std::string& comment,
+                                         const std::string& address,
+                                         int64 amount,
+                                         int nonce,
+                                         const std::string& structuredId,
+                                         bool fConfirmed = true,
+                                         const std::string& structuredBlock = "")
+{
+    CWalletTx wtx;
+    wtx.vin.resize(1);
+    wtx.vin[0].prevout.SetNull();
+    wtx.vin[0].scriptSig << nonce;
+    wtx.vout.resize(1);
+    wtx.vout[0].nValue = amount;
+    wtx.vout[0].scriptPubKey = PayoutTestScriptFor(address);
+    if (!comment.empty())
+        wtx.mapValue["comment"] = comment;
+    if (!structuredId.empty()) {
+        wtx.mapValue["pool_payout_id"]      = structuredId;
+        wtx.mapValue["pool_payout_address"] = address;
+        wtx.mapValue["pool_payout_amount"]  = strprintf("%lld", amount);
+        if (!structuredBlock.empty())
+            wtx.mapValue["pool_payout_block"] = structuredBlock;
+    }
+    uint256 hash = wtx.GetHash();
+    if (fConfirmed) {
+        // A block hash distinct from the transaction's own.
+        uint256 blockHash = hash;
+        ((unsigned char*)&blockHash)[0] ^= 0xff;
+        CRITICAL_BLOCK(cs_main)
+        {
+            CBlockIndex* pindex = new CBlockIndex();
+            pindex->hashMerkleRoot = hash;
+            // Linked onto the end of the fabricated chain rather than simply
+            // becoming the new tip: IsInMainChain() is "pnext is set, or I am
+            // the tip", so a second confirmed transaction would otherwise take
+            // the first one out of the chain again.
+            pindex->pprev   = gPayoutTestChainTip;
+            pindex->nHeight = gPayoutTestChainTip ? gPayoutTestChainTip->nHeight + 1 : 1;
+            if (gPayoutTestChainTip)
+                gPayoutTestChainTip->pnext = pindex;
+            gPayoutTestChainTip = pindex;
+            std::map<uint256, CBlockIndex*>::iterator mi =
+                mapBlockIndex.insert(std::make_pair(blockHash, pindex)).first;
+            pindex->phashBlock = &mi->first;
+            pindexBest = pindex;
+            gPayoutTestBlockIndexes.push_back(pindex);
+        }
+        wtx.hashBlock = blockHash;
+        wtx.nIndex    = 0;
+    }
+    CRITICAL_BLOCK(cs_mapWallet)
+        mapWallet[hash] = wtx;
+    return hash.GetHex();
+}
+
+// A real key, in the keystore, so a test wallet's outputs are IsMine() and can
+// actually be signed -- both are needed for CreateTransaction to build the
+// large transaction the fee schedule is being tested against. Inserted
+// straight into the key maps rather than through AddKey(), which would also
+// write it to a wallet.dat.
+static std::string PayoutTestAddSpendableKey()
+{
+    CKey key;
+    key.MakeNewKey();
+    std::vector<unsigned char> vchPubKey = key.GetPubKey();
+    CRITICAL_BLOCK(cs_mapKeys)
+    {
+        mapKeys[vchPubKey]                = key.GetPrivKey();
+        mapPubKeys[Hash160(vchPubKey)]    = vchPubKey;
+    }
+    return Hash160ToAddress(Hash160(vchPubKey));
+}
+
+// Give the wallet `n` spendable outputs of `each`, one transaction apiece --
+// which is the granularity SelectCoins works at, and therefore the number of
+// inputs the transaction spending them will carry.
+//
+// Deliberately not coinbases: a null prevout would make CWalletTx::GetCredit
+// return 0 until COINBASE_SPENDABLE_DEPTH, and there is no chain here.
+static void PayoutTestFundWallet(int n, int64 each, const std::string& address)
+{
+    const CScript sc = PayoutTestScriptFor(address);
+    CRITICAL_BLOCK(cs_mapWallet)
+    {
+        for (int i = 0; i < n; i++) {
+            CWalletTx wtx;
+            wtx.vin.resize(1);
+            wtx.vin[0].prevout.hash = (uint64)(i + 1);
+            wtx.vin[0].prevout.n    = 0;
+            wtx.vout.resize(1);
+            wtx.vout[0].nValue       = each;
+            wtx.vout[0].scriptPubKey = sc;
+            mapWallet[wtx.GetHash()] = wtx;
+        }
+    }
+}
+
+// Defined below with the event loop; the status-file publication test drives
+// it directly.
+static void RefreshStats(int blocksFoundThisSession, uint64 roundShareTotal);
+
+int RunPayoutLedgerSelfTest()
+{
+    int nFail = 0;
+    auto check = [&](bool ok, const char* msg) {
+        fprintf(stdout, "  %s   %s\n", ok ? "ok" : "FAIL", msg);
+        if (!ok) nFail++;
+    };
+
+    fprintf(stdout, "payout-ledger self-test\n");
+
+    const std::string savedDataDir = strSetDataDir;
+    const int savedBestHeight = nBestHeight;
+
+    // Scratch data directory in the current working directory. GetAppDir()
+    // follows strSetDataDir, so this is what PayoutFilePath() and
+    // PayingFilePath() resolve against for the rest of the test.
+#ifdef _WIN32
+    unsigned long pid = (unsigned long)GetCurrentProcessId();
+#else
+    unsigned long pid = (unsigned long)getpid();
+#endif
+    // Absolute, and the process moves into it.
+    //
+    // Both are needed by the CreateTransaction section: Berkeley DB resolves
+    // its log directory relative to the environment home, so a relative
+    // datadir makes dbenv.open() fail with DB_RUNRECOVERY; and BDB opens
+    // db.log relative to the working directory, which is src/ during `make
+    // tests`. Moving in puts it inside the scratch directory, where it dies
+    // with everything else.
+    std::string cwd = ".";
+    {
+#ifdef _WIN32
+        char buf[MAX_PATH];
+        if (GetCurrentDirectoryA(MAX_PATH, buf) > 0) cwd = buf;
+#else
+        char buf[4096];
+        if (getcwd(buf, sizeof(buf)) != NULL) cwd = buf;
+#endif
+    }
+    std::string dir = cwd + "/" +
+                      strprintf("payout_selftest_%d_%lu", (int)GetTime(), pid);
+#ifdef _WIN32
+    CreateDirectoryA(dir.c_str(), NULL);
+    SetCurrentDirectoryA(dir.c_str());
+#else
+    mkdir(dir.c_str(), 0700);
+    if (chdir(dir.c_str()) != 0) { /* stay put; the paths are absolute anyway */ }
+#endif
+    strSetDataDir = dir;
+    fprintf(stdout, "  scratch datadir: %s\n", dir.c_str());
+
+    const std::string ledgerPath = PayoutFilePath();
+    const std::string payingPath = PayingFilePath();
+    const std::string addrA = PayoutTestAddress(0x11);
+    const std::string addrB = PayoutTestAddress(0x55);
+
+    // -- 1. A restart must not duplicate an in-flight record -----------------
+    //
+    // The ledger entry is grandfathered (zero hash) on purpose: it keeps
+    // PayoutBlockStillOnChain out of the picture, which needs a block index,
+    // and it exercises the height fallback at the same time.
+    {
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+        remove(payingPath.c_str());
+
+        PendingPayout pp;
+        pp.blockHeight    = 4242;
+        pp.blockHash      = 0;
+        pp.matureAtHeight = 4242;
+        pp.amounts[addrA] = 10 * COIN;
+        pp.amounts[addrB] = 20 * COIN;
+        VersionedBlob snap;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            gPendingPayouts.push_back(pp);
+            snap = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(snap);
+
+        nBestHeight = 5000;
+        FlushMaturePayouts();
+        size_t afterFirstFlush = 0;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            afterFirstFlush = gPaying.size();
+        }
+        check(afterFirstFlush == 2,
+              "a matured round explodes into one record per unpaid recipient");
+
+        // Restart: drop everything in memory and come back from the files.
+        for (int restart = 1; restart <= 2; restart++) {
+            PayoutTestResetState();
+            LoadPendingPayouts();
+            LoadPaying();
+            ReconcilePayouts();
+
+            size_t queued = 0;
+            {
+                std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+                queued = gQueuedPayouts.size();
+            }
+            if (restart == 1)
+                check(queued == 1,
+                      "startup rebuilds the exploded-round set from the restored"
+                      " in-flight list");
+
+            FlushMaturePayouts();
+            size_t n = 0;
+            {
+                std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+                n = gPaying.size();
+            }
+            check(n == 2, restart == 1
+                  ? "a restart does not duplicate an in-flight record"
+                  : "a second restart does not duplicate one either");
+        }
+
+        // The other half of the guard: even with the round-level dedupe set
+        // deliberately emptied, the per-recipient check against gPaying must
+        // stop a second standing order for the same money.
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            gQueuedPayouts.clear();
+        }
+        FlushMaturePayouts();
+        size_t n = 0;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            n = gPaying.size();
+        }
+        check(n == 2,
+              "the flush refuses a second record for a (round, address) already"
+              " in flight even with the round set lost");
+    }
+
+    // -- 2. Duplicates already on disk are collapsed as they are read --------
+    {
+        PayoutTestResetState();
+        nlohmann::json arr = nlohmann::json::array();
+        for (int i = 0; i < 2; i++) {
+            nlohmann::json o;
+            o["blockHeight"]    = 4242;
+            o["blockHash"]      = uint256(0).ToString();
+            o["matureAtHeight"] = 4242;
+            o["address"]        = addrA;
+            o["amount"]         = (int64)(10 * COIN);
+            o["retries"]        = i == 0 ? 7 : 0;
+            o["deferrals"]      = i == 0 ? 0 : 3;
+            arr.push_back(o);
+        }
+        check(PayoutTestWriteFile(payingPath, arr.dump(2)),
+              "wrote a paying file containing the duplicate the old build made");
+        LoadPaying();
+        std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+        check(gPaying.size() == 1,
+              "loading collapses a duplicate in-flight record from disk");
+        check(gPaying.size() == 1 && gPaying[0].retries == 7 && gPaying[0].deferrals == 3,
+              "collapsing merges the attempt counts upwards, not resetting them");
+    }
+
+    // -- 3. State updates address a slot, not a value -----------------------
+    //
+    // Build the exact pathology the old code produced -- two records equal in
+    // every field -- and prove the update lands on the one asked for. Under
+    // value matching the first record absorbed everything and the second was
+    // untouchable.
+    {
+        PayoutTestResetState();
+        PayingRecord a;
+        a.blockHeight = 4242; a.blockHash = 0; a.matureAtHeight = 4242;
+        a.address = addrA; a.amount = 10 * COIN;
+        PayingRecord b = a;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            a.id = ++gPayingNextId;
+            b.id = ++gPayingNextId;
+            gPaying.push_back(a);
+            gPaying.push_back(b);
+        }
+        PayingRecord upd = b;
+        upd.retries = 5;
+        upd.retryAfter = 1234567;
+        ReschedulePayment(upd);
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            check(gPaying.size() == 2 &&
+                  gPaying[0].retries == 0 && gPaying[1].retries == 5,
+                  "rescheduling updates the record it was given, not the first"
+                  " one that looks like it");
+        }
+        ForgetPayment(a);
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            check(gPaying.size() == 1 && gPaying[0].id == b.id,
+                  "forgetting erases the record it was given, not the first"
+                  " one that looks like it");
+        }
+    }
+
+    // -- 4. retryAfter survives a restart ------------------------------------
+    {
+        PayoutTestResetState();
+        remove(payingPath.c_str());
+        PayingRecord r;
+        r.blockHeight = 77; r.blockHash = 0; r.matureAtHeight = 77;
+        r.address = addrA; r.amount = 3 * COIN;
+        r.retryAfter = 1700000000LL;
+        r.deferrals = 9;
+        VersionedBlob snap;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            r.id = ++gPayingNextId;
+            gPaying.push_back(r);
+            snap = SerializePayingLocked();
+        }
+        PublishPaying(snap);
+        PayoutTestResetState();
+        LoadPaying();
+        std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+        check(gPaying.size() == 1 && gPaying[0].retryAfter == 1700000000LL &&
+              gPaying[0].deferrals == 9,
+              "the retry clock that is actually used survives a restart");
+    }
+
+    // -- 5. The ledger file cannot be published from a stale snapshot --------
+    {
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+
+        PendingPayout one;
+        one.blockHeight = 100; one.blockHash = 0; one.matureAtHeight = 100;
+        one.amounts[addrA] = 1 * COIN;
+        VersionedBlob older, newer;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            gPendingPayouts.push_back(one);
+            older = SerializePendingPayoutsLocked();
+            PendingPayout two;
+            two.blockHeight = 200; two.blockHash = 0; two.matureAtHeight = 200;
+            two.amounts[addrB] = 2 * COIN;
+            gPendingPayouts.push_back(two);
+            newer = SerializePendingPayoutsLocked();
+        }
+        check(newer.seq > older.seq,
+              "a later serialisation carries a strictly higher version");
+
+        // The order the race produced: the payout thread's older image
+        // arriving after the event loop's newer one.
+        PublishPendingPayouts(newer);
+        PublishPendingPayouts(older);
+        std::string onDisk;
+        check(PayoutTestReadFile(ledgerPath, onDisk) && onDisk == newer.blob,
+              "an older snapshot cannot overwrite a newer published ledger");
+
+        // And the ordinary direction still works.
+        VersionedBlob newest;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            gPendingPayouts.clear();
+            newest = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(newest);
+        check(PayoutTestReadFile(ledgerPath, onDisk) && onDisk == newest.blob,
+              "a newer snapshot does replace the published ledger");
+    }
+
+    // -- 6. Concurrent publishers cannot interleave a file -------------------
+    //
+    // Two threads opening and renaming the same "<path>.tmp" over the same
+    // target was the original defect. This test was mutation-tested and did
+    // not catch it: with the file mutex removed the suite still went green 2
+    // runs in 5, and the "never leave it unparseable" assertion fired 0 times
+    // in 5. Two reasons, both fixed here.
+    //
+    // First, every image had the same structure and near enough the same
+    // length, so an interleaving of two of them was still valid JSON. The
+    // images now alternate between ONE entry and FIVE THOUSAND, so a write
+    // that lands on top of another leaves either a truncated array or a small
+    // image followed by the tail of a large one -- neither of which parses.
+    //
+    // Second, and worse, almost nothing was being written. Each thread walked
+    // a permutation of the images, and PublishVersioned drops any blob that is
+    // not newer than what is on disk, so only the record highs in each
+    // permutation ever reached the disk -- on the order of ten writes in
+    // total, four threads, no contention to speak of. Every publish here is
+    // stamped from a shared counter at the moment it is made, so every one of
+    // them is newer than the last and every one of them writes.
+    //
+    // And the file is watched while the writers run, not only inspected after
+    // they finish. "The published file is never observed unparseable" is the
+    // actual invariant -- rename(2) is atomic, so a reader can only ever see a
+    // completely written image -- and checking it once at the end samples the
+    // one moment when a torn file is least likely to still be there.
+    {
+        const std::string racePath = dir + "/publish_race_selftest.json";
+        std::mutex raceMutex;
+        uint64 racePublished = 0;
+
+        std::string tiny, huge;
+        {
+            nlohmann::json one = nlohmann::json::array();
+            nlohmann::json o;
+            o["image"]   = 0;
+            o["entry"]   = 0;
+            o["address"] = addrA;
+            o["amount"]  = (int64)COIN;
+            one.push_back(o);
+            tiny = one.dump(2);
+
+            nlohmann::json many = nlohmann::json::array();
+            for (int k = 0; k < 5000; k++) {
+                nlohmann::json e;
+                e["image"]   = 1;
+                e["entry"]   = k;
+                e["address"] = addrA;
+                e["amount"]  = (int64)(k + 1) * COIN;
+                many.push_back(e);
+            }
+            huge = many.dump(2);
+        }
+
+        const int kThreads   = 4;
+        const int kPerThread = 100;
+        const uint64 kTotal  = (uint64)kThreads * kPerThread;
+
+        std::atomic<uint64> nextSeq(0);
+        std::atomic<bool>   racing(true);
+        std::atomic<int>    tornReads(0);
+        std::atomic<int>    goodReads(0);
+
+        std::thread watcher([&]() {
+            bool seenOnce = false;
+            while (racing) {
+                std::string s;
+                if (!PayoutTestReadFile(racePath, s)) {
+                    // Only meaningful once the file exists at all.
+                    if (seenOnce) tornReads++;
+                    continue;
+                }
+                seenOnce = true;
+                try {
+                    if (nlohmann::json::parse(s).is_array()) goodReads++;
+                    else tornReads++;
+                } catch (...) {
+                    tornReads++;
+                }
+            }
         });
 
-    // gPendingPayouts is event-loop-only data (no lock needed here since
-    // RefreshStats is always called from the event loop thread).
-    gPayoutViews.clear();
-    for (const PendingPayout& pp : gPendingPayouts) {
-        PendingPayoutView pv;
-        pv.matureAtHeight = pp.matureAtHeight;
-        pv.recipients     = (int)pp.amounts.size();
-        pv.totalAmount    = 0;
-        for (auto& kv : pp.amounts) pv.totalAmount += kv.second;
-        gPayoutViews.push_back(pv);
+        std::vector<std::thread> threads;
+        for (int t = 0; t < kThreads; t++) {
+            threads.push_back(std::thread([&]() {
+                for (int i = 0; i < kPerThread; i++) {
+                    VersionedBlob v;
+                    v.seq  = ++nextSeq;
+                    v.blob = (v.seq & 1) ? tiny : huge;
+                    PublishVersioned(racePath, v, raceMutex, racePublished,
+                                     "publish race selftest");
+                }
+            }));
+        }
+        for (std::thread& th : threads)
+            th.join();
+        racing = false;
+        watcher.join();
+
+        check(goodReads > 0,
+              "the race test actually observed the file while it was being"
+              " written");
+        check(tornReads == 0,
+              "four threads publishing the same file never leave it"
+              " unparseable, at any instant while they are doing it");
+
+        // The highest sequence number issued is the one the file must settle
+        // on: PublishVersioned refuses anything older, so whichever order the
+        // writes complete in, that image is the last one that can land.
+        const std::string& expected = (kTotal & 1) ? tiny : huge;
+        std::string onDisk;
+        bool read = PayoutTestReadFile(racePath, onDisk);
+        check(read && onDisk == expected,
+              "the published file settles on the highest version, whatever the"
+              " completion order");
+        remove(racePath.c_str());
+        remove((racePath + ".tmp").c_str());
+    }
+
+    // -- 7. Grandfathered zero-hash rounds do not answer for each other ------
+    {
+        uint256 h1 = 0, h2 = 0;
+        h1.SetHex("00000000000000000000000000000000000000000000000000000000000000aa");
+        h2.SetHex("00000000000000000000000000000000000000000000000000000000000000bb");
+        check(!SamePayoutRound(100, 0, 200, 0),
+              "two zero-hash entries at different heights are different rounds");
+        check(SamePayoutRound(100, 0, 100, 0),
+              "two zero-hash entries at the same height are the same round");
+        check(SamePayoutRound(100, h1, 200, h1),
+              "a real hash identifies the round on its own");
+        check(!SamePayoutRound(100, h1, 100, h2),
+              "different hashes at one height are different rounds");
+        check(!SamePayoutRound(100, h1, 100, 0),
+              "a grandfathered entry never matches a hash-keyed one");
+        check(!PayoutRoundIdentifiable(0, 0) && PayoutRoundIdentifiable(0, h1) &&
+              PayoutRoundIdentifiable(7, 0),
+              "an entry with neither hash nor height is not adjudicable");
+
+        // What actually makes a grandfathered same-height pair safe, since the
+        // comment on FindRecordedPoolPayout used to claim it was the orphan
+        // check. It is not: the orphan check passes every zero-hash entry, and
+        // every pre-upgrade entry has a zero hash.
+        check(PayoutBlockStillOnChain(0),
+              "the orphan check passes every grandfathered entry, so it cannot"
+              " be what voids a losing twin");
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+        remove(payingPath.c_str());
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            PendingPayout twin;
+            twin.blockHeight = 300; twin.blockHash = 0; twin.matureAtHeight = 300;
+            twin.amounts[addrA] = 1 * COIN;
+            gPendingPayouts.push_back(twin);
+            gPendingPayouts.push_back(twin);   // the losing side of a reorg
+        }
+        nBestHeight = 5000;
+        FlushMaturePayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            check(gPaying.size() == 1,
+                  "two grandfathered rounds at one height are one round, so the"
+                  " pair presents as one debt and is paid at most once");
+        }
+
+        // End to end: recording a payment against one grandfathered round must
+        // not settle the other's debt.
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            PendingPayout first;
+            first.blockHeight = 100; first.blockHash = 0; first.matureAtHeight = 100;
+            first.amounts[addrA] = 1 * COIN;
+            PendingPayout second;
+            second.blockHeight = 200; second.blockHash = 0; second.matureAtHeight = 200;
+            second.amounts[addrA] = 1 * COIN;
+            gPendingPayouts.push_back(first);
+            gPendingPayouts.push_back(second);
+        }
+        PayingRecord r;
+        r.blockHeight = 200; r.blockHash = 0; r.matureAtHeight = 200;
+        r.address = addrA; r.amount = 1 * COIN;
+        RecordPayoutTxid(r, "txid-for-the-second-round");
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            // The second round was fully paid and retired; the first is
+            // untouched and still owed.
+            check(gPendingPayouts.size() == 1 &&
+                  gPendingPayouts[0].blockHeight == 100 &&
+                  gPendingPayouts[0].paidTxids.empty(),
+                  "a txid recorded against one zero-hash round leaves the other"
+                  " still owed");
+        }
+    }
+
+    // -- 8. A payment with only a legacy comment is recognised as paid -------
+    {
+        PayoutTestResetState();
+        const int    height = 8080;
+        const int64  amount = 7 * COIN;
+        const std::string id = PayoutIdForBlock(height, 0);
+        const std::string comment = LegacyPayoutComment(height);
+        std::set<std::string> none;
+        std::string found;
+        // No round proof exists for these rounds, so legacy evidence is
+        // admissible -- computed exactly as the payout thread computes it.
+        const bool fAllowLegacy = !PoolRoundHasProof(id);
+
+        check(FindRecordedPoolPayout(id, height, 0, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "an empty wallet is not evidence that anything was paid");
+
+        const std::string legacyTxid =
+            PayoutTestAddWalletTx(comment, addrA, amount, 1, "");
+        check(FindRecordedPoolPayout(id, height, 0, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_LEGACY && found == legacyTxid,
+              "a payment carrying only a pre-upgrade comment is recognised as"
+              " already paid");
+
+        check(FindRecordedPoolPayout(id, height, 0, addrB, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "the legacy match requires the output to pay THIS recipient");
+        check(FindRecordedPoolPayout(id, height, 0, addrA, amount + COIN, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "the legacy match requires the output to pay exactly this amount");
+        check(FindRecordedPoolPayout(id, height + 1, 0, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "the legacy match requires the comment for this block height");
+
+        std::set<std::string> spent;
+        spent.insert(legacyTxid);
+        check(FindRecordedPoolPayout(id, height, 0, addrA, amount, fAllowLegacy, spent, found)
+                  == PAYOUT_PROBE_NONE,
+              "one legacy transaction cannot settle a second debt");
+
+        // A transaction written by THIS build carries pool_payout_id, and must
+        // never be offered as legacy evidence for a different round -- that is
+        // exactly what the structured metadata exists to prevent.
+        const std::string otherId = PayoutIdForBlock(height, 0) + "-other";
+        PayoutTestAddWalletTx(comment, addrB, amount, 2, otherId);
+        check(FindRecordedPoolPayout(id, height, 0, addrB, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "another round's structured payment is not legacy evidence for"
+              " this one");
+
+        // The structured path still wins where it applies.
+        const std::string structuredTxid =
+            PayoutTestAddWalletTx(comment, addrB, amount, 3, id);
+        check(FindRecordedPoolPayout(id, height, 0, addrB, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_STRUCTURED && found == structuredTxid,
+              "structured payout metadata is matched in preference to a comment");
+
+        // A comment-matching transaction that never made it into the chain is
+        // evidence of NON-payment. This tree has seen a 280-block reorg; a
+        // pre-upgrade payout invalidated by one is still in mapWallet with its
+        // comment intact, and the first boot after the upgrade is exactly when
+        // it would be matched.
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+        const std::string addrC = PayoutTestAddress(0x33);
+        PayoutTestAddWalletTx(comment, addrC, amount, 4, "", false);
+        check(FindRecordedPoolPayout(id, height, 0, addrC, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "a pre-upgrade payout that never confirmed is not read as"
+              " payment");
+
+        // The same transaction, confirmed, is.
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        const std::string confirmedTxid =
+            PayoutTestAddWalletTx(comment, addrC, amount, 4, "", true);
+        check(FindRecordedPoolPayout(id, height, 0, addrC, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_LEGACY && found == confirmedTxid,
+              "the same payout, confirmed, is");
+
+        // And an unconfirmed one does not shadow a confirmed one that would
+        // have matched: the probe used to stop at the first comment match.
+        const std::string alsoConfirmed =
+            PayoutTestAddWalletTx(comment, addrC, amount, 6, "", true);
+        PayoutTestAddWalletTx(comment, addrC, amount, 5, "", false);
+        std::set<std::string> spentFirst;
+        spentFirst.insert(confirmedTxid);
+        check(FindRecordedPoolPayout(id, height, 0, addrC, amount, fAllowLegacy, spentFirst, found)
+                  == PAYOUT_PROBE_LEGACY && found == alsoConfirmed,
+              "an unconfirmed transaction does not hide a confirmed one behind"
+              " it");
+
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
     }
+
+    // -- 9. On-disk compatibility with the live production ledger ------------
+    {
+        PayoutTestResetState();
+        // Exactly the shape of the file on the pool node: amounts, blockHash,
+        // blockHeight, matureAtHeight, and nothing else.
+        const char* live =
+            "[{\"amounts\":{\"%s\":1234500000},"
+            "\"blockHash\":\"00000000000000000000000000000000000000000000000000000000000000cd\","
+            "\"blockHeight\":1000,"
+            "\"matureAtHeight\":1120}]";
+        check(PayoutTestWriteFile(ledgerPath, strprintf(live, addrA.c_str())),
+              "wrote a ledger file in the live production shape");
+        LoadPendingPayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            check(gPendingPayouts.size() == 1 &&
+                  gPendingPayouts[0].blockHeight == 1000 &&
+                  gPendingPayouts[0].matureAtHeight == 1120 &&
+                  gPendingPayouts[0].blockHash != 0 &&
+                  gPendingPayouts[0].amounts.size() == 1 &&
+                  gPendingPayouts[0].amounts[addrA] == 1234500000LL,
+                  "the live production pending_payouts.json still loads");
+        }
+
+        // And the shape the merged build writes, retryAfter included, which
+        // this build no longer writes but must still read past.
+        PayoutTestResetState();
+        const char* merged =
+            "[{\"amounts\":{\"%s\":100000000},"
+            "\"blockHash\":\"00000000000000000000000000000000000000000000000000000000000000ef\","
+            "\"blockHeight\":2000,\"matureAtHeight\":2120,\"retryAfter\":0,"
+            "\"paidTxids\":{\"%s\":\"abc123\"}}]";
+        check(PayoutTestWriteFile(ledgerPath,
+                                  strprintf(merged, addrA.c_str(), addrA.c_str())),
+              "wrote a ledger file in the merged build's shape");
+        LoadPendingPayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            check(gPendingPayouts.size() == 1 &&
+                  gPendingPayouts[0].blockHeight == 2000 &&
+                  gPendingPayouts[0].paidTxids.size() == 1 &&
+                  gPendingPayouts[0].paidTxids[addrA] == "abc123",
+                  "a ledger file carrying retryAfter and paidTxids still loads");
+        }
+
+        // A round trip through this build must not lose anything either.
+        VersionedBlob snap;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            snap = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(snap);
+        PayoutTestResetState();
+        LoadPendingPayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            check(gPendingPayouts.size() == 1 &&
+                  gPendingPayouts[0].blockHeight == 2000 &&
+                  gPendingPayouts[0].matureAtHeight == 2120 &&
+                  gPendingPayouts[0].paidTxids[addrA] == "abc123",
+                  "what this build writes, this build reads back unchanged");
+        }
+    }
+
+    // -- 10. A forfeit is published, not just dropped ------------------------
+    {
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+        const std::string roundsPath = dir + "/pool_rounds_selftest.json";
+        const std::string savedRoundsFile = strPoolRoundsFile;
+        strPoolRoundsFile = roundsPath;
+        remove(roundsPath.c_str());
+
+        const int height = 606;
+        PoolRoundProof round;
+        round.id = PayoutIdForBlock(height, 0);
+        round.blockHeight = height;
+        round.matureAtHeight = height;
+        round.payouts[addrA] = 5 * COIN;
+        round.payouts[addrB] = 6 * COIN;
+        RecordPoolRound(round);
+
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            PendingPayout pp;
+            pp.blockHeight = height; pp.blockHash = 0; pp.matureAtHeight = height;
+            pp.amounts[addrA] = 5 * COIN;
+            pp.amounts[addrB] = 6 * COIN;
+            gPendingPayouts.push_back(pp);
+        }
+
+        PayingRecord r;
+        r.blockHeight = height; r.blockHash = 0; r.matureAtHeight = height;
+        r.address = addrA; r.amount = 5 * COIN;
+        ForfeitPayoutRecipient(r, "selftest reason");
+
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            check(gPendingPayouts.size() == 1 &&
+                  gPendingPayouts[0].amounts.count(addrA) == 0 &&
+                  gPendingPayouts[0].amounts.count(addrB) == 1,
+                  "a forfeit removes only that recipient from the ledger entry");
+        }
+
+        std::string onDisk;
+        bool proofOk = false;
+        if (PayoutTestReadFile(roundsPath, onDisk)) {
+            try {
+                nlohmann::json root = nlohmann::json::parse(onDisk);
+                const nlohmann::json& p = root["rounds"][0]["payouts"];
+                proofOk = p[addrA].value("forfeited", false) &&
+                          p[addrA].value("forfeitReason", "") == "selftest reason" &&
+                          p[addrA]["txid"].is_null() &&
+                          !p[addrB].contains("forfeited");
+            } catch (...) {
+                proofOk = false;
+            }
+        }
+        check(proofOk,
+              "the published round proof records the forfeit instead of"
+              " advertising the address as still owed");
+
+        // And it survives a reload of the proof file.
+        {
+            std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+            gPoolRounds.clear();
+        }
+        LoadPoolRounds();
+        {
+            std::lock_guard<std::mutex> lk(gPoolRoundsMutex);
+            check(gPoolRounds.size() == 1 &&
+                  gPoolRounds[0].forfeited.count(addrA) == 1 &&
+                  gPoolRounds[0].forfeited[addrA] == "selftest reason",
+                  "the forfeit is read back from pool_rounds.json");
+        }
+
+        remove(roundsPath.c_str());
+        remove((roundsPath + ".tmp").c_str());
+        strPoolRoundsFile = savedRoundsFile;
+    }
+
+    // -- 11. A ledger that failed to load is never written back --------------
+    //
+    // The loaders push entries into the live vector inside the try, so an
+    // exception part way down a file leaves a PARTIAL ledger in memory: the
+    // entries before the bad one and nothing after it. Publishing that -- and
+    // ReconcilePayouts publishes unconditionally, milliseconds into startup --
+    // writes the partial state over the file and destroys the only record of
+    // what was owed.
+    {
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+
+        // Two entries, the second with a matureAtHeight that is not a number.
+        // The first loads; the second throws where it is read.
+        const std::string corrupt = strprintf(
+            "[{\"amounts\":{\"%s\":100000000},\"blockHash\":\"%s\","
+            "\"blockHeight\":10,\"matureAtHeight\":10},"
+            "{\"amounts\":{\"%s\":900000000},\"blockHash\":\"%s\","
+            "\"blockHeight\":20,\"matureAtHeight\":\"twenty\"}]",
+            addrA.c_str(), uint256(0).ToString().c_str(),
+            addrB.c_str(), uint256(0).ToString().c_str());
+        check(PayoutTestWriteFile(ledgerPath, corrupt),
+              "wrote a ledger whose second entry does not parse");
+
+        const int64 t0 = GetTime();
+        LoadPendingPayouts();
+        const int64 t1 = GetTime();
+
+        size_t loaded = 0;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            loaded = gPendingPayouts.size();
+        }
+        check(loaded == 1,
+              "a mid-file parse error does leave a partial ledger in memory --"
+              " which is the reason for everything below");
+
+        std::string gone;
+        check(!PayoutTestReadFile(ledgerPath, gone),
+              "the file that did not parse is moved out of the way");
+
+        // The rename stamps GetTime(); it was taken between t0 and t1.
+        std::string kept, keptPath;
+        for (int64 t = t0; t <= t1 && keptPath.empty(); t++) {
+            const std::string candidate =
+                strprintf("%s.bad.%lld", ledgerPath.c_str(), (long long)t);
+            if (PayoutTestReadFile(candidate, kept))
+                keptPath = candidate;
+        }
+        check(!keptPath.empty() && kept == corrupt,
+              "it is kept, byte for byte, as <path>.bad.<timestamp>");
+
+        // The publish that used to destroy it.
+        VersionedBlob partial;
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            partial = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(partial);
+        check(!PayoutTestReadFile(ledgerPath, gone),
+              "and the partial ledger is not published over it");
+
+        // The refusal is per path and lasts the process: a second attempt,
+        // with more state, is refused too.
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            PendingPayout pp;
+            pp.blockHeight = 30; pp.blockHash = 0; pp.matureAtHeight = 30;
+            pp.amounts[addrA] = 5 * COIN;
+            gPendingPayouts.push_back(pp);
+            partial = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(partial);
+        check(!PayoutTestReadFile(ledgerPath, gone),
+              "the refusal is not a one-shot -- the path stays unwritable");
+
+        if (!keptPath.empty())
+            remove(keptPath.c_str());
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+
+        // And a file that parses is not quarantined, so the ordinary path is
+        // still the ordinary path.
+        check(PayoutTestWriteFile(ledgerPath, "[]"),
+              "wrote a ledger that parses");
+        LoadPendingPayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            PendingPayout pp;
+            pp.blockHeight = 40; pp.blockHash = 0; pp.matureAtHeight = 40;
+            pp.amounts[addrA] = 2 * COIN;
+            gPendingPayouts.push_back(pp);
+            partial = SerializePendingPayoutsLocked();
+        }
+        PublishPendingPayouts(partial);
+        std::string written;
+        check(PayoutTestReadFile(ledgerPath, written) && written == partial.blob,
+              "a ledger that loaded cleanly is still published normally");
+    }
+
+    // -- 12. A send that failed for want of coin is not a fault --------------
+    //
+    // The defect this replaces: the classifier decided "was this a funding
+    // problem?" by re-reading GetBalance() and allowing amount +
+    // nTransactionFee + CENT. nTransactionFee is 0 on a headless node, and
+    // GetMinFee() is a step function -- 0 below 10,000 bytes, 11 * CENT at it
+    // -- so the allowance was either unnecessary or eleven times too small,
+    // and the ledger's own retry budget then wrote the debt off after 1440
+    // repeats of the same stable condition.
+    //
+    // This is tested against a real wallet and the real CreateTransaction, not
+    // against injected values: the honest question is not "does my enum
+    // switch work" but "does a wallet holding many small coins actually report
+    // the state I think it does". 60 outputs of 1 BTF give ~180 signed P2PKH
+    // bytes each, which is where the fee schedule steps. Nothing is committed
+    // or broadcast -- CreateTransaction only builds.
+    {
+        PayoutTestResetState();
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+
+        // CreateTransaction opens CTxDB("r"), which throws if blkindex.dat is
+        // not there. Create it in the scratch datadir first.
+        bool dbOk = true;
+        try {
+            CTxDB txdb("cr");
+        } catch (const std::exception&) {
+            dbOk = false;
+        }
+        check(dbOk, "a scratch block index exists for CreateTransaction to open");
+
+        const std::string walletAddr = PayoutTestAddSpendableKey();
+        const std::string payee      = PayoutTestAddress(0x77);
+        const CScript     payeeScript = PayoutTestScriptFor(payee);
+
+        // -- the >= 10 KB case: 60 small coins, balance = amount + 0.05 ------
+        PayoutTestFundWallet(60, 1 * COIN, walletAddr);
+        const int64 balance = GetBalance();
+        check(balance == 60 * COIN,
+              "the test wallet holds 60 separately spendable coins");
+
+        const int64 amount = balance - 5 * CENT;
+        // The pre-send gate in PayoutThreadFn passes: the balance covers the
+        // amount and the only fee that can be known in advance.
+        check(balance >= amount + nTransactionFee,
+              "the pre-send gate would let this payment through");
+
+        CWalletTx        wtx;
+        SendMoneyOutcome outcome;
+        int64            feeRequired = 0;
+        WalletSendResult result      = WALLET_SEND_OK;
+        bool             built       = true;
+        if (dbOk) {
+            try {
+                built = CreateTransaction(payeeScript, amount, wtx, feeRequired,
+                                          &result);
+            } catch (const std::exception&) {
+                built = true;   // report as a failure below
+            }
+        }
+        check(dbOk && !built,
+              "a wallet of many small coins cannot fund amount + the fee its"
+              " own size demands");
+        check(dbOk && result == WALLET_SEND_INSUFFICIENT_FUNDS,
+              "the wallet reports that as a funding shortfall, not as a"
+              " failure to build");
+        // GetMinFee(fDiscount) returns 0 below 10,000 bytes and
+        // (1 + bytes/1000) * CENT at or above, so a required fee of 11 CENT or
+        // more IS the statement that the transaction crossed 10 KB. Measured
+        // through the real serialiser rather than asserted.
+        check(dbOk && feeRequired >= 11 * CENT,
+              "the transaction it built crossed 10,000 bytes, so the fee"
+              " stepped from 0 to at least 11 CENT");
+
+        // The defect, stated as arithmetic. The old classifier asked whether
+        // the balance covered amount + nTransactionFee + CENT; it did, so it
+        // called a permanent funding shortfall a fault and started counting
+        // towards a write-off.
+        check(!(balance < amount + nTransactionFee + CENT),
+              "the reserve this replaces would have judged this send a fault");
+        check(balance < amount + feeRequired,
+              "while the fee actually required was more than the balance had");
+
+        outcome.result       = result;
+        outcome.nFeeRequired = feeRequired;
+        check(dbOk && ClassifyPayoutSendFailure(outcome.result, false)
+                          == PAYOUT_FAILURE_DEFER,
+              "a >= 10 KB send that ran out of coin is deferred, not counted"
+              " against the payment");
+
+        // -- the < 10 KB case: no reserve is needed at all -------------------
+        //
+        // The other half of the arithmetic. Below the step the required fee is
+        // 0, so a reserve of any size is a reason to refuse a payment the
+        // wallet could have made -- which is its own way of not paying a
+        // miner.
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestFundWallet(3, 1 * COIN, walletAddr);
+        const int64 smallAmount = 3 * COIN - 5 * CENT;
+        CWalletTx   smallTx;
+        int64       smallFee    = -1;
+        WalletSendResult smallResult = WALLET_SEND_FAILED;
+        bool        smallBuilt  = false;
+        if (dbOk) {
+            try {
+                smallBuilt = CreateTransaction(payeeScript, smallAmount, smallTx,
+                                               smallFee, &smallResult);
+            } catch (const std::exception&) {
+                smallBuilt = false;
+            }
+        }
+        check(dbOk && smallBuilt && smallResult == WALLET_SEND_OK,
+              "the same balance pays a small transaction with no headroom at"
+              " all");
+        check(dbOk && smallFee == 0,
+              "because below 10,000 bytes the required fee is zero");
+
+        // -- and the classification of every other answer --------------------
+        check(ClassifyPayoutSendFailure(WALLET_SEND_INSUFFICIENT_FUNDS, false)
+                  == PAYOUT_FAILURE_DEFER &&
+              ClassifyPayoutSendFailure(WALLET_SEND_INSUFFICIENT_FUNDS, true)
+                  == PAYOUT_FAILURE_DEFER &&
+              ClassifyPayoutSendFailure(WALLET_SEND_FAILED, true)
+                  == PAYOUT_FAILURE_DEFER,
+              "short of coin or unable to sign is always a deferral");
+        check(ClassifyPayoutSendFailure(WALLET_SEND_FAILED, false)
+                  == PAYOUT_FAILURE_FAULT,
+              "funded and unlocked and still refused is a fault");
+
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+    }
+
+    // -- 13. No payout mutex is held across the status-file write ------------
+    //
+    // RefreshStats runs on the event loop -- the thread that owns every
+    // miner's socket -- and used to hold gStatsMutex and gPayoutLedgerMutex at
+    // function scope across WriteFileAtomic. Once that write gained fsync() on
+    // the file and on its directory, publishing pool_status.json parked the
+    // payout thread behind two disk flushes every ten seconds.
+    //
+    // Timing assertions would be flaky, so this does not measure anything. It
+    // makes the write block for as long as the test likes: strPoolStatusFile
+    // points at a path whose ".tmp" is a FIFO, and open(2) for writing on a
+    // FIFO does not return until a reader arrives. While RefreshStats is
+    // parked in there, every mutex it must NOT be holding has to be
+    // acquirable. Against the previous code this test does not merely fail, it
+    // cannot pass: the writer is inside fopen() with both mutexes held and
+    // nothing will release them until the test lets the write finish.
+#ifndef _WIN32
+    {
+        PayoutTestResetState();
+        const std::string statusPath = dir + "/pool_status_selftest.json";
+        const std::string statusTmp  = statusPath + ".tmp";
+        const std::string savedStatusFile = strPoolStatusFile;
+        const int64       savedLastWrite  = gLastPoolStatusWrite;
+        remove(statusPath.c_str());
+        remove(statusTmp.c_str());
+        strPoolStatusFile    = statusPath;
+        gLastPoolStatusWrite = 0;   // due a publish on the next refresh
+
+        // Give the status file something to report, so the ledger mutex is
+        // genuinely taken on the way through rather than skipped over.
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            PendingPayout pp;
+            pp.blockHeight = 909; pp.blockHash = 0; pp.matureAtHeight = 909;
+            pp.amounts[addrA] = 3 * COIN;
+            gPendingPayouts.push_back(pp);
+        }
+
+        bool fifoOk = (mkfifo(statusTmp.c_str(), 0600) == 0);
+        check(fifoOk, "a FIFO stands in for the status file's temp file, so the"
+                      " write can be held open");
+        if (fifoOk) {
+            std::atomic<bool> done(false);
+            std::thread writer([&done]() {
+                RefreshStats(0, 0);
+                done = true;
+            });
+
+            // Settle: the work before the write is a handful of vector
+            // operations, so anything past this point is inside fopen(). The
+            // !done check below is what actually proves it -- with no reader
+            // there is no other way for this thread to still be running.
+            Sleep(500);
+            bool blocked = !done;
+            bool gotLedger = false, gotStats = false, gotExec = false,
+                 gotRounds = false;
+            for (int i = 0; i < 1000 && blocked; i++) {
+                if (!gotLedger && gPayoutLedgerMutex.try_lock()) {
+                    gotLedger = true; gPayoutLedgerMutex.unlock();
+                }
+                if (!gotStats && gStatsMutex.try_lock()) {
+                    gotStats = true; gStatsMutex.unlock();
+                }
+                if (!gotExec && gPayoutExecMutex.try_lock()) {
+                    gotExec = true; gPayoutExecMutex.unlock();
+                }
+                if (!gotRounds && gPoolRoundsMutex.try_lock()) {
+                    gotRounds = true; gPoolRoundsMutex.unlock();
+                }
+                if (gotLedger && gotStats && gotExec && gotRounds)
+                    break;
+                Sleep(2);
+            }
+
+            check(blocked,
+                  "the status-file write is held open for the duration of this"
+                  " test");
+            check(!blocked || gotLedger,
+                  "gPayoutLedgerMutex is free while pool_status.json is being"
+                  " written");
+            check(!blocked || (gotExec && gotRounds),
+                  "gPayoutExecMutex and gPoolRoundsMutex are free while"
+                  " pool_status.json is being written");
+            check(!blocked || gotStats,
+                  "gStatsMutex is free while pool_status.json is being written");
+
+            // Let the write finish. Drain to EOF rather than closing early:
+            // the writer is still filling the pipe and a closed read end would
+            // deliver it SIGPIPE.
+            std::thread reader([&statusTmp]() {
+                FILE* rf = fopen(statusTmp.c_str(), "r");
+                if (!rf) return;
+                char buf[4096];
+                while (fread(buf, 1, sizeof(buf), rf) > 0) { }
+                fclose(rf);
+            });
+            writer.join();
+            reader.join();
+        }
+        remove(statusTmp.c_str());
+
+        // And the ordinary path still produces the file it always did.
+        gLastPoolStatusWrite = 0;
+        RefreshStats(0, 0);
+        std::string onDisk;
+        bool statusOk = false;
+        if (PayoutTestReadFile(statusPath, onDisk)) {
+            try {
+                nlohmann::json j = nlohmann::json::parse(onDisk);
+                statusOk = j.value("schema", "") == "bitflash-pool-status-1" &&
+                           j["pendingPayouts"].is_array() &&
+                           j["pendingPayouts"].size() == 1 &&
+                           j["pendingPayouts"][0].value("matureAtHeight", 0) == 909 &&
+                           j["pendingPayouts"][0].value("totalAmountSatoshis",
+                                                        (int64)0) == 3 * COIN;
+            } catch (...) {
+                statusOk = false;
+            }
+        }
+        check(statusOk,
+              "splitting the serialise from the write leaves pool_status.json"
+              " saying the same thing");
+
+        remove(statusPath.c_str());
+        remove((statusPath + ".tmp").c_str());
+        strPoolStatusFile    = savedStatusFile;
+        gLastPoolStatusWrite = savedLastWrite;
+    }
+#endif
+
+    // -- 14. The payout comment names the funding block ----------------------
+    //
+    // Same height, two hashes: the shape a reorg leaves when the pool wins a
+    // height, loses the block, and wins the height again. The legacy needle is
+    // frozen at the pre-upgrade format, so pre-upgrade payments keep matching;
+    // a new-format comment never matches it, so a new send can never be read
+    // as a pre-upgrade payment for a twin round.
+    {
+        PayoutTestResetState();
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+
+        const int   height = 9090;
+        const int64 amount = 3 * COIN;
+        uint256 hashA = 0, hashB = 0;
+        hashA.SetHex("00000000000000000000000000000000000000000000000000000000000000aa");
+        hashB.SetHex("00000000000000000000000000000000000000000000000000000000000000bb");
+
+        check(LegacyPayoutComment(height) ==
+                  strprintf("Pool payout height %d", height),
+              "the legacy needle is frozen at the format pre-upgrade builds"
+              " wrote");
+        check(PayoutComment(height, 0) == LegacyPayoutComment(height),
+              "a grandfathered zero-hash record still writes the legacy form");
+        check(PayoutComment(height, hashA) ==
+                  strprintf("Pool payout height %d block %s", height,
+                            hashA.ToString().c_str()),
+              "a hash-keyed record's comment names its funding block");
+        check(PayoutComment(height, hashA) != PayoutComment(height, hashB),
+              "twin rounds at one height carry distinguishable comments");
+
+        // A transaction wearing the NEW comment format and -- hypothetically
+        // -- no structured metadata must not be matched by the legacy needle:
+        // the fallback exists for pre-upgrade transactions, and the new format
+        // proves this is not one.
+        const std::string idA = PayoutIdForBlock(height, hashA);
+        const std::string idB = PayoutIdForBlock(height, hashB);
+        std::set<std::string> none;
+        std::string found;
+        // Neither twin has a round proof here (section 15 covers the gate),
+        // and their ids collide, so one answer serves both.
+        const bool fAllowLegacy = !PoolRoundHasProof(idA);
+        PayoutTestAddWalletTx(PayoutComment(height, hashA), addrA, amount, 1, "");
+        check(FindRecordedPoolPayout(idB, height, hashB, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "a new-format comment is never legacy evidence for a twin round");
+        check(FindRecordedPoolPayout(idA, height, hashA, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "nor a match channel for its own round -- structured metadata is");
+
+        // Round A's own payment, sent by this build, is found by its
+        // structured id.
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+        const std::string paidA =
+            PayoutTestAddWalletTx(PayoutComment(height, hashA), addrA, amount,
+                                  2, idA);
+        check(FindRecordedPoolPayout(idA, height, hashA, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_STRUCTURED && found == paidA,
+              "the winning twin's own payment is found by its structured id");
+
+        // The id is derived from the FIRST sixteen hex digits of the hash --
+        // the end proof-of-work fills with zeros -- so twin hashes that agree
+        // there collide in id, and a payment carrying no pool_payout_block
+        // answers for either twin. That is the accepted trade for payments
+        // sent before the key existed, pinned here so it stays a decision.
+        check(idA == idB,
+              "twin hashes differing only past the sixteenth hex digit collide"
+              " in id -- the reason the full hash must decide");
+        check(FindRecordedPoolPayout(idB, height, hashB, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_STRUCTURED,
+              "a payment without the block key answers for a colliding twin --"
+              " the accepted residual for pre-key transactions");
+
+        // With the full hash recorded -- as every send now records it -- the
+        // twins are told apart and the re-won height is paid.
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+        const std::string keyedA =
+            PayoutTestAddWalletTx(PayoutComment(height, hashA), addrA, amount,
+                                  3, idA, true, hashA.ToString());
+        check(FindRecordedPoolPayout(idA, height, hashA, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_STRUCTURED && found == keyedA,
+              "a payment carrying the full block hash settles its own round");
+        check(FindRecordedPoolPayout(idB, height, hashB, addrA, amount, fAllowLegacy, none, found)
+                  == PAYOUT_PROBE_NONE,
+              "and is no evidence for the twin, so the re-won height is paid");
+
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+    }
+
+    // -- 15. A proof-bearing round rejects comment-only evidence -------------
+    //
+    // The surviving half of the same-height collision: a pre-upgrade
+    // transaction carries only "Pool payout height H", so if H is won again
+    // after a reorg, it matches the new round's (height, address, amount)
+    // exactly and would settle a debt it never paid. The new round has a
+    // round proof -- written at creation, and only by builds whose payments
+    // all name their round -- so for it, comment-only evidence is
+    // inadmissible and the miner is paid. A round without a proof keeps
+    // today's bias: the evidence is admissible and doubt resolves to
+    // "already paid".
+    {
+        PayoutTestResetState();
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+        const std::string roundsPath = dir + "/pool_rounds_gate_selftest.json";
+        const std::string savedRoundsFile = strPoolRoundsFile;
+        strPoolRoundsFile = roundsPath;
+        remove(roundsPath.c_str());
+
+        const int   height = 7171;
+        const int64 amount = 4 * COIN;
+        uint256 hashB = 0;
+        hashB.SetHex("00000000000000000000000000000000000000000000000000000000000000cc");
+        const std::string idB = PayoutIdForBlock(height, hashB);
+        std::set<std::string> none;
+        std::string found;
+
+        // The colliding pre-upgrade payment: confirmed, comment-only, same
+        // height, same address, same amount -- the strongest wrong evidence
+        // there is.
+        PayoutTestAddWalletTx(LegacyPayoutComment(height), addrA, amount, 1, "");
+
+        check(!PoolRoundHasProof(idB),
+              "a round with no recorded proof does not claim one");
+        check(FindRecordedPoolPayout(idB, height, hashB, addrA, amount,
+                                     !PoolRoundHasProof(idB), none, found)
+                  == PAYOUT_PROBE_LEGACY,
+              "without a proof the doubt is genuine and still resolves to"
+              " already-paid");
+
+        PoolRoundProof round;
+        round.id = idB;
+        round.blockHeight = height;
+        round.matureAtHeight = height + COINBASE_SPENDABLE_DEPTH;
+        round.payouts[addrA] = amount;
+        RecordPoolRound(round);
+        check(PoolRoundHasProof(idB),
+              "recording the round proof marks the round as this lineage's");
+        check(FindRecordedPoolPayout(idB, height, hashB, addrA, amount,
+                                     !PoolRoundHasProof(idB), none, found)
+                  == PAYOUT_PROBE_NONE,
+              "with a proof, a same-height comment-only transaction is not"
+              " evidence, and the re-won height is paid");
+
+        // Structured evidence still is: the round's own payment, recovered.
+        const std::string paidB =
+            PayoutTestAddWalletTx(PayoutComment(height, hashB), addrA, amount,
+                                  2, idB, true, hashB.ToString());
+        check(FindRecordedPoolPayout(idB, height, hashB, addrA, amount,
+                                     !PoolRoundHasProof(idB), none, found)
+                  == PAYOUT_PROBE_STRUCTURED && found == paidB,
+              "the gate does not blind the probe to the round's own structured"
+              " payment");
+
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        PayoutTestClearBlockIndex();
+        remove(roundsPath.c_str());
+        remove((roundsPath + ".tmp").c_str());
+        strPoolRoundsFile = savedRoundsFile;
+    }
+
+    // -- 16. A malformed block hash is corruption, not a hash ----------------
+    //
+    // SetHex() parses whatever hex prefix it finds and stops, so a corrupt
+    // blockHash did not fail to load -- it loaded as a DIFFERENT hash.
+    // "deadbeef..." became 0xdeadbeef, a hash no block ever had, which the
+    // orphan check reads as an orphaned block and the next flush VOIDS the
+    // debt; a value with no hex prefix became 0, which is grandfathered past
+    // the orphan check instead. Either way a corrupt file silently changed
+    // what the pool owed. It is a load failure now, handled like every other
+    // parse error: quarantine, and never rewrite.
+    {
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+        remove(payingPath.c_str());
+
+        const std::string badLedger = strprintf(
+            "[{\"amounts\":{\"%s\":100000000},"
+            "\"blockHash\":\"deadbeef oops, not a hash\","
+            "\"blockHeight\":10,\"matureAtHeight\":10}]", addrA.c_str());
+        check(PayoutTestWriteFile(ledgerPath, badLedger),
+              "wrote a ledger whose blockHash is not a 64-digit hex string");
+        LoadPendingPayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            check(gPendingPayouts.empty(),
+                  "no entry is loaded with a guessed hash");
+        }
+        std::string gone;
+        check(!PayoutTestReadFile(ledgerPath, gone),
+              "the ledger with the corrupt hash is quarantined");
+
+        const std::string badPaying = strprintf(
+            "[{\"address\":\"%s\",\"amount\":100000000,"
+            "\"blockHash\":\"00000000cafe\",\"blockHeight\":10,"
+            "\"matureAtHeight\":10}]", addrA.c_str());
+        check(PayoutTestWriteFile(payingPath, badPaying),
+              "wrote an in-flight list whose blockHash is truncated");
+        LoadPaying();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutExecMutex);
+            check(gPaying.empty(),
+                  "no in-flight record is loaded with a guessed hash");
+        }
+        check(!PayoutTestReadFile(payingPath, gone),
+              "the in-flight list with the corrupt hash is quarantined");
+
+        // The two spellings every real file uses still load: the 64-digit
+        // hash of a keyed round, and the 64 zeros this build writes for a
+        // grandfathered entry.
+        PayoutTestResetState();
+        remove(ledgerPath.c_str());
+        const std::string goodLedger = strprintf(
+            "[{\"amounts\":{\"%s\":100000000},"
+            "\"blockHash\":\"00000000000000000000000000000000000000000000000000000000000000cd\","
+            "\"blockHeight\":10,\"matureAtHeight\":10},"
+            "{\"amounts\":{\"%s\":200000000},"
+            "\"blockHash\":\"%s\","
+            "\"blockHeight\":20,\"matureAtHeight\":20}]",
+            addrA.c_str(), addrB.c_str(), uint256(0).ToString().c_str());
+        check(PayoutTestWriteFile(ledgerPath, goodLedger),
+              "wrote a ledger in both real hash spellings");
+        LoadPendingPayouts();
+        {
+            std::lock_guard<std::mutex> lk(gPayoutLedgerMutex);
+            check(gPendingPayouts.size() == 2 &&
+                  gPendingPayouts[0].blockHash != 0 &&
+                  gPendingPayouts[1].blockHash == 0,
+                  "a real hash and a serialised zero hash both still load");
+        }
+        remove(ledgerPath.c_str());
+    }
+
+    // -- clean up ------------------------------------------------------------
+    PayoutTestResetState();
+    CRITICAL_BLOCK(cs_mapWallet)
+        mapWallet.clear();
+    PayoutTestClearBlockIndex();
+    // Out of the scratch directory before removing it, and out of the key maps
+    // too: the keys this test generated are process-local, but leaving them in
+    // the keystore would let a later test think a script was its own.
+    CRITICAL_BLOCK(cs_mapKeys)
+    {
+        mapKeys.clear();
+        mapPubKeys.clear();
+    }
+#ifdef _WIN32
+    SetCurrentDirectoryA(cwd.c_str());
+#else
+    if (chdir(cwd.c_str()) != 0) { /* nothing useful to do about it */ }
+#endif
+    PayoutTestRemoveDir(dir);
+    strSetDataDir = savedDataDir;
+    nBestHeight = savedBestHeight;
+
+    fprintf(stdout, "%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+            nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+int RunPoolStratumSelfTest()
+{
+    int nFail = 0;
+    auto check = [&](bool ok, const char* msg) {
+        fprintf(stdout, "  %s   %s\n", ok ? "ok" : "FAIL", msg);
+        if (!ok) nFail++;
+    };
+
+    fprintf(stdout, "pool-stratum self-test\n");
+
+    StratumJob savedJob = gCurrentJob;
+    bool savedHaveJob = gHaveJob;
+
+    CTransaction coinbase;
+    coinbase.vin.resize(1);
+    coinbase.vin[0].prevout.SetNull();
+    coinbase.vin[0].scriptSig << 1 << (CBigNum)1;
+    coinbase.vout.resize(1);
+    coinbase.vout[0].nValue = 50 * COIN;
+
+    CBlock block;
+    block.vtx.push_back(coinbase);
+    block.nVersion = 1;
+    block.nBits = 0x1f0fffff;
+    block.nTime = 1;
+    block.nNonce = 1;
+    block.hashMerkleRoot = block.BuildMerkleTree();
+
+    gCurrentJob.jobId = "selftest";
+    gCurrentJob.block = block;
+    gCurrentJob.target = 0; // accepted share, not a block candidate
+    gCurrentJob.height = 1;
+    gHaveJob = true;
+
+    Miner miner(INVALID_SOCKET);
+    miner.authorised = true;
+    miner.address = "selftest-address";
+    miner.worker = "worker";
+    miner.shareTarget = ~uint256(0); // every RandomX hash is a valid share
+    miner.difficulty = 0.001;
+    miner.vardiffWindowStart = GetTime();
+
+    std::map<std::string, uint64> roundShareCount;
+    uint64 roundShareTotal = 0;
+    int blocksFound = 0;
+
+    uint256 targetFromNotify;
+    CBlock minerBlock = BuildMinerBlock(gCurrentJob, miner.extranonce2);
+    json params = MakeNotifyParams(gCurrentJob, minerBlock, miner.shareTarget, true);
+    std::vector<unsigned char> targetBytes = FromHex(params[3].get<std::string>());
+    if (targetBytes.size() == 32)
+        memcpy(&targetFromNotify, &targetBytes[0], 32);
+    check(targetFromNotify == miner.shareTarget,
+          "mining.notify exposes the same share target the pool validates");
+
+    json submit = {
+        {"id", 7},
+        {"method", "mining.submit"},
+        {"params", json::array({miner.address, "selftest", ToHex(&minerBlock.nNonce, 4)})}
+    };
+    HandleLine(&miner, submit.dump(), roundShareCount, roundShareTotal, blocksFound);
+
+    check(roundShareTotal == 1, "fake low-difficulty share increments the round total");
+    check(roundShareCount[miner.address] == 1, "fake share is credited to the submitting address");
+    check(miner.sessionShares == 1 && miner.roundShares == 1 && miner.totalShares == 1,
+          "miner share counters advance together");
+    check(blocksFound == 0, "share below block target is not counted as a found block");
+
+    json stale = {
+        {"id", 8},
+        {"method", "mining.submit"},
+        {"params", json::array({miner.address, "stale", ToHex(&minerBlock.nNonce, 4)})}
+    };
+    HandleLine(&miner, stale.dump(), roundShareCount, roundShareTotal, blocksFound);
+    check(roundShareTotal == 1, "stale submit does not increment shares");
+
+    std::vector<PoolRoundProof> savedRounds = gPoolRounds;
+    std::string savedRoundsFile = strPoolRoundsFile;
+    std::string proofPath = "pool_rounds_selftest.json";
+    remove(proofPath.c_str());
+    remove((proofPath + ".tmp").c_str());
+    gPoolRounds.clear();
+    strPoolRoundsFile = proofPath;
+
+    PoolRoundProof proof;
+    proof.id = "selftest-round";
+    proof.blockHeight = 42;
+    proof.matureAtHeight = 42 + COINBASE_MATURITY;
+    proof.createdAt = GetTime();
+    proof.blockHash = block.GetHash().GetHex();
+    proof.coinbaseTxid = coinbase.GetHash().GetHex();
+    proof.foundBy = miner.address;
+    proof.feePercent = 1.25;
+    proof.totalShares = 3;
+    proof.coinbaseValue = 50 * COIN;
+    proof.subsidy = 50 * COIN;
+    proof.minerReward = 49 * COIN;
+    proof.operatorReward = 1 * COIN;
+    proof.shares[miner.address] = 3;
+    proof.payouts[miner.address] = 49 * COIN;
+    RecordPoolRound(proof);
+    MarkPoolRoundPaid(proof.id, miner.address, "selftest-txid");
+
+    bool proofOk = false;
+    FILE* pf = fopen(proofPath.c_str(), "r");
+    if (pf) {
+        fseek(pf, 0, SEEK_END);
+        long sz = ftell(pf);
+        fseek(pf, 0, SEEK_SET);
+        std::string s(sz, '\0');
+        fread(&s[0], 1, sz, pf);
+        fclose(pf);
+        try {
+            json root = json::parse(s);
+            proofOk =
+                root.value("schema", "") == "bitflash-pool-rounds-1" &&
+                root["rounds"].is_array() &&
+                root["rounds"].size() == 1 &&
+                root["rounds"][0].value("id", "") == proof.id &&
+                root["rounds"][0]["shares"].value(miner.address, (uint64)0) == 3 &&
+                root["rounds"][0]["payouts"][miner.address].value("txid", "") == "selftest-txid";
+        } catch (...) {
+            proofOk = false;
+        }
+    }
+    check(proofOk, "pool round proof ledger is written and paid txid is recorded");
+
+    remove(proofPath.c_str());
+    remove((proofPath + ".tmp").c_str());
+    strPoolRoundsFile = savedRoundsFile;
+    gPoolRounds = savedRounds;
+
+    // -- hashrate decay (#7) --------------------------------------------------
+    // The first version of this decayed m->hashRate in place from the event
+    // loop's sweep, which made the reported figure a function of how the loop
+    // happened to run rather than of how long the miner had been quiet. These
+    // pin the properties that fixes: sampling changes nothing, and the answer
+    // depends only on elapsed silence.
+    {
+        // A miner exactly on the vardiff target: 4096 hashes per share at
+        // difficulty 1.0, one share per 15s, so 4096/15 H/s. Its expected
+        // interval is 15s and its grace is 60s.
+        const double base = 4096.0 / 15.0;
+        const int64  t0   = 1766000000; // any plausible non-zero wall clock
+        Miner decayed(INVALID_SOCKET);
+        decayed.difficulty    = 1.0;
+        decayed.hashRate      = base;
+        decayed.lastShareTime = t0;
+
+        check(MinerReportedHashRate(&decayed, t0 + 60) == base,
+              "hashrate decay: a miner inside its grace period reports its full estimate");
+
+        // Sampling must not consume the estimate. Twenty passes is one second
+        // of the event loop's old sweep; a thousand is nearly a minute of it.
+        double once = MinerReportedHashRate(&decayed, t0 + 61);
+        bool idempotent = (decayed.hashRate == base);
+        for (int i = 0; i < 1000 && idempotent; i++)
+            idempotent = (MinerReportedHashRate(&decayed, t0 + 61) == once) &&
+                         (decayed.hashRate == base);
+        check(idempotent,
+              "hashrate decay: repeated sampling returns one value and leaves the estimate alone");
+
+        // One second past a 60s grace is 1/15th of a half-life: ~4.5% off, not
+        // the estimate gone. A miner at the vardiff target overshoots its grace
+        // roughly 1.8% of the time (e^-4) purely by share-timing variance, and
+        // must not be zeroed for it.
+        check(once > 0.94 * base && once < 0.96 * base,
+              "hashrate decay: one second past grace costs a few percent, not the estimate");
+        double three = MinerReportedHashRate(&decayed, t0 + 63);
+        check(three > 0.86 * base && three < 0.88 * base,
+              "hashrate decay: three seconds past grace costs ~13%");
+
+        // One half-life past the grace is exactly half.
+        double half = MinerReportedHashRate(&decayed, t0 + 75);
+        check(half > 0.499 * base && half < 0.501 * base,
+              "hashrate decay: one expected interval past grace halves the estimate");
+
+        // A miner that has genuinely stopped ends up reported as nothing --
+        // the whole point of #7. The old in-place version could not get here:
+        // its decay fed back into its own grace and settled into a 1/t crawl.
+        check(MinerReportedHashRate(&decayed, t0 + 3600) == 0.0,
+              "hashrate decay: a miner silent for an hour is reported as zero");
+
+        // A clock that steps backwards must never inflate what we announce.
+        check(MinerReportedHashRate(&decayed, t0 - 3600) == base,
+              "hashrate decay: a backwards clock reports the estimate unchanged, never higher");
+
+        // Fresh connection, and a connection with one share and so no interval
+        // to have timed: both must report nothing rather than divide by zero.
+        Miner fresh(INVALID_SOCKET);
+        check(MinerReportedHashRate(&fresh, t0) == 0.0,
+              "hashrate decay: a miner that never submitted a share reports zero");
+        Miner single(INVALID_SOCKET);
+        single.lastShareTime = t0;
+        check(MinerReportedHashRate(&single, t0 + 86400) == 0.0,
+              "hashrate decay: a miner with no rate sample yet reports zero");
+
+        // Nothing in the swept range may produce a NaN, an infinity, a negative
+        // rate, or a rate above the estimate it started from.
+        bool finite = true;
+        for (int64 s = -100; s < 200000 && finite; s += 37) {
+            double v = MinerReportedHashRate(&decayed, t0 + s);
+            finite = !std::isnan(v) && !std::isinf(v) && v >= 0.0 && v <= base;
+        }
+        check(finite,
+              "hashrate decay: stays finite, non-negative and non-amplifying across a long silence");
+    }
+
+    gCurrentJob = savedJob;
+    gHaveJob = savedHaveJob;
+
+    fprintf(stdout, "%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+            nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+// ---------------------------------------------------------------------------
+// Stats refresh -- called every 2s from event loop
+// ---------------------------------------------------------------------------
+static void RefreshStats(int blocksFoundThisSession, uint64 roundShareTotal)
+{
+    std::string statusBlob;
+    bool        fPublish = false;
+    {
+        std::lock_guard<std::mutex> lk(gStatsMutex);
+
+        gStats.authorizedMiners = 0;
+        gStats.blocksFound      = blocksFoundThisSession;
+        gStats.roundShares      = roundShareTotal;
+        gStats.totalHashRate    = 0.0;
+        for (Miner* m : gMiners)
+            if (m->authorised) gStats.authorizedMiners++;
+
+        gWorkerStats.clear();
+        // One timestamp for the whole sweep (#7): every miner is faded to the
+        // same instant, so the per-worker rows and the total they are summed
+        // into describe one moment rather than a smear across the loop.
+        int64 nowStats = GetTime();
+        for (Miner* m : gMiners) {
+            if (!m->authorised || m->lastSeen <= 0) continue;
+            PoolWorkerStatView v;
+            v.address     = m->address;
+            v.worker      = m->worker;
+            v.roundShares = m->roundShares;
+            v.totalShares = m->totalShares;
+            v.lastSeen    = m->lastSeen;
+            // Not m->hashRate: a miner that has stopped submitting shares must
+            // not keep contributing its last sample to the announced total.
+            v.hashRate    = MinerReportedHashRate(m, nowStats);
+            gWorkerStats.push_back(v);
+            gStats.totalHashRate += v.hashRate;
+        }
+        std::sort(gWorkerStats.begin(), gWorkerStats.end(),
+            [](const PoolWorkerStatView& a, const PoolWorkerStatView& b) {
+                return a.roundShares != b.roundShares ? a.roundShares > b.roundShares
+                                                      : a.lastSeen > b.lastSeen;
+            });
+
+        // Scoped, not held to the end of the function. At function scope this
+        // lock covered the status-file write below, so the event loop did two
+        // fsyncs holding the mutex the payout thread takes to record that a
+        // miner has been paid.
+        gPayoutViews.clear();
+        {
+            std::lock_guard<std::mutex> ledger(gPayoutLedgerMutex);
+            for (const PendingPayout& pp : gPendingPayouts) {
+                PendingPayoutView pv;
+                pv.matureAtHeight = pp.matureAtHeight;
+                pv.recipients     = 0;
+                pv.totalAmount    = 0;
+                for (auto& kv : pp.amounts) {
+                    if (pp.paidTxids.count(kv.first))
+                        continue;
+                    pv.recipients++;
+                    pv.totalAmount += kv.second;
+                }
+                if (pv.recipients > 0)
+                    gPayoutViews.push_back(pv);
+            }
+        }
+
+        int64 now = GetTime();
+        if (now - gLastPoolStatusWrite >= 10) {
+            statusBlob = SerializePoolStatusLocked();
+            gLastPoolStatusWrite = now;
+            fPublish = true;
+        }
+    }
+    // Every payout mutex is released here, and gStatsMutex with them. This is
+    // where the two fsyncs happen, and no other thread is waiting behind them.
+    if (fPublish)
+        PublishPoolStatus(statusBlob);
 }
 
 // ---------------------------------------------------------------------------
@@ -1533,6 +5314,7 @@ static void PoolEventLoop()
     int   lastHeight            = -1;
     int64 lastRefresh           = GetTime();
     int64 lastStatsRefresh      = 0;
+    int64 lastCensus            = 0;   // #19 connection census throttle
     int   blocksFoundThisSession = 0;
     int64 noJobSince            = 0;   // 0 = have a job
     bool  warnedNoJob           = false;
@@ -1561,6 +5343,31 @@ static void PoolEventLoop()
                     sock_close(fd);
                     continue;
                 }
+                // #26: select() + FD_SET goes undefined once we exceed what an
+                // fd_set can carry, and MAX_POOL_MINERS (1000) alone does not
+                // prevent it -- a Miner is only removed on clean disconnect, so
+                // half-open zombies accumulate and the OS can hand out fds past
+                // the limit long before the count reaches 1000. Refuse rather
+                // than corrupt the fd_set. Which limit applies is platform
+                // specific: POSIX bounds the descriptor value, Windows the
+                // number of SOCKET handles an fd_set can hold.
+#ifndef _WIN32
+                if ((int)fd >= (int)FD_SETSIZE) {
+                    LogPrint("worker", "[pool] refusing miner fd=%d -- at/over"
+                             " FD_SETSIZE=%d, select() would be undefined (#26)\n",
+                             (int)fd, (int)FD_SETSIZE);
+                    sock_close(fd);
+                    continue;
+                }
+#else
+                if (gMiners.size() >= (size_t)FD_SETSIZE) {
+                    LogPrint("worker", "[pool] refusing miner -- %zu sockets held,"
+                             " an fd_set carries at most FD_SETSIZE=%d (#26)\n",
+                             gMiners.size(), (int)FD_SETSIZE);
+                    sock_close(fd);
+                    continue;
+                }
+#endif
                 gMiners.push_back(new Miner(fd));
                 LogPrint("worker", "[pool] miner fd=%d entered event loop"
                          " -- awaiting subscribe/authorize\n", (int)fd);
@@ -1688,6 +5495,35 @@ static void PoolEventLoop()
             }
         }
 
+        // 3.6. Idle reap (#6). Mirror the clean-disconnect path exactly --
+        // log, close, erase from gMiners via std::find, delete -- just with
+        // a different reason. Shares the miner already earned stay in
+        // roundShareCount, exactly as they do when a miner cleanly
+        // disconnects mid-round. connectTime stands in for lastSeen on a
+        // connection that never completed a line. Erasing inside the loop
+        // above would invalidate the iteration, so collect then reap.
+        {
+            int64 now = GetTime();
+            std::vector<Miner*> idle;
+            for (Miner* m : gMiners) {
+                int64 last = (m->lastSeen > 0) ? m->lastSeen : m->connectTime;
+                if (now - last > POOL_IDLE_TIMEOUT_SECS)
+                    idle.push_back(m);
+            }
+            for (Miner* m : idle) {
+                LogPrint("worker", "[pool] dropping idle miner %s -- nothing"
+                         " received in over %llds (session shares: %llu,"
+                         " round shares: %llu)\n",
+                         m->worker.empty() ? "(never authorized)" : m->worker.c_str(),
+                         (long long)POOL_IDLE_TIMEOUT_SECS,
+                         (unsigned long long)m->sessionShares,
+                         (unsigned long long)m->roundShares);
+                sock_close(m->fd);
+                gMiners.erase(std::find(gMiners.begin(), gMiners.end(), m));
+                delete m;
+            }
+        }
+
         // 4. Select over miner sockets
         if (!gMiners.empty()) {
             fd_set fds; FD_ZERO(&fds);
@@ -1710,6 +5546,11 @@ static void PoolEventLoop()
                     // terminate the whole node -- not just the pool. Every
                     // line arrives from an unauthenticated socket.
                     while (RecvLine(m->fd, m->readBuf, line, disc)) {
+                        // Any complete line is proof of life (#6): authorize
+                        // and valid shares already stamp lastSeen themselves,
+                        // but a miner that only ever subscribes (or sends
+                        // unrecognised methods) must count as alive too.
+                        m->lastSeen = GetTime();
                         try {
                             HandleLine(m, line, roundShareCount,
                                        roundShareTotal, blocksFoundThisSession);
@@ -1750,6 +5591,14 @@ static void PoolEventLoop()
             RefreshStats(blocksFoundThisSession, roundShareTotal);
             lastStatsRefresh = GetTime();
         }
+
+        // 6. #19: log the connection census periodically. Cheap (one pass over
+        // gMiners) and it is the single number an operator reads to judge pool
+        // health, so it should not be an overstatement.
+        if (GetTime() - lastCensus >= POOL_CENSUS_SECS) {
+            LogPoolConnectionCensus();
+            lastCensus = GetTime();
+        }
     }
 
     for (Miner* m : gMiners) { sock_close(m->fd); delete m; }
@@ -1778,13 +5627,19 @@ static void AcceptOneFn(void* arg)
     std::string host = relay.substr(0, colon);
     int         port = atoi(relay.substr(colon + 1).c_str());
 
-    LogPrint("pool", "[pool] accept thread started for relay %s\n", relay.c_str());
+    LogPrint("pool", "[pool] accept thread started for relay %s%s\n", relay.c_str(),
+             fBtfRelayPinned ? " (/rvrelay pin)" : "");
+
+    // Registration health for this relay. A pin has no fallback, so a pin that
+    // never registers means the pool is simply unreachable -- and that has to
+    // be loud. The 2026-07-30 incident went unnoticed because this loop logged
+    // failures at one flat line and success not at all, so "which relay is this
+    // pool actually registered at" could not be answered from the log.
+    int   nConsecFail     = 0;
+    int64 nFirstFail      = 0;
+    bool  fEverRegistered = false;
 
     while (!fShutdown && gPoolRunning) {
-        // Advertise this relay as the pool's meeting node BEFORE registering,
-        // so that miners which resolve our descriptor find a relay where the
-        // pool (not the node's peer-accept) holds the registration.
-        BtfSetActiveRelay(relay);
         // Returns as soon as the relay lists us -- registered, not yet paired.
         btf::RvSocket rv = btf::RvServiceRegister(host.c_str(), (unsigned short)port, pk);
 
@@ -1793,12 +5648,36 @@ static void AcceptOneFn(void* arg)
             break;
         }
         if (rv == btf::RV_INVALID) {
-            LogPrint("pool", "[pool] relay %s: RvServiceRegister failed"
-                     " -- backing off 30s before retry\n", relay.c_str());
+            nConsecFail++;
+            if (nFirstFail == 0) nFirstFail = GetTime();
+            LogPrint("pool", "[pool] relay %s: registration failed (attempt %d,"
+                     " failing for %llds) -- backing off 30s before retry\n",
+                     relay.c_str(), nConsecFail, (long long)(GetTime() - nFirstFail));
+            if (fBtfRelayPinned && (nConsecFail == 3 || nConsecFail % 10 == 0))
+                LogPrint("pool", "[pool] WARNING: pinned relay %s refused registration"
+                         " %d times running (%llds); /rvrelay leaves no fallback, so"
+                         " miners cannot reach this pool%s\n",
+                         relay.c_str(), nConsecFail, (long long)(GetTime() - nFirstFail),
+                         fEverRegistered ? "" : " -- it has never registered once");
             for (int i = 0; i < 30 && !fShutdown && gPoolRunning; i++) Sleep(1000);
             continue;
         }
 
+        // Advertise THIS relay only now. Setting it before the call published a
+        // meeting node we were not yet listed at, so a miner resolving the
+        // descriptor inside that window burned its dial on a relay holding no
+        // registration for us. net.cpp's peer-accept has always ordered it this
+        // way round; the pool had not.
+        BtfSetActiveRelay(relay);
+        if (!fEverRegistered || nConsecFail > 0)
+            LogPrint("pool", "[pool] registered at relay %s%s%s -- advertising it as"
+                     " the pool's meeting node\n", relay.c_str(),
+                     fBtfRelayPinned ? " (/rvrelay pin)" : "",
+                     nConsecFail > 0 ? ", recovered" : "");
+        fEverRegistered = true;
+        nConsecFail     = 0;
+        nFirstFail      = 0;
+
         // Block for a miner to actually arrive. RvServiceRegister used to do
         // this itself and returned with the relay's 0x01 pairing byte already
         // consumed; it no longer does. Without waiting here, BtfServiceWrap
@@ -1853,9 +5732,21 @@ static void AcceptLoopFn(void*)
     LogPrint("pool", "[pool] .btf identity ready after %ds\n", waitSecs * 2);
 
     std::set<std::string> spawned; // relays we've already started a thread for
+    std::set<std::string> skipped; // discovered relays the pin excluded, logged once each
 
     while (!fShutdown && gPoolRunning) {
+        // BtfAllRelays() already honours the pin: with /rvrelay set it returns
+        // vBtfMeetingRelays alone, so no thread is ever spawned for a
+        // discovered relay. Name the ones it drops -- a pool registering at a
+        // stranger's relay is exactly the thing that should not be silent.
         vector<string> relays = BtfAllRelays();
+        if (fBtfRelayPinned) {
+            for (const string& r : BtfDiscoveredRelays())
+                if (std::find(relays.begin(), relays.end(), r) == relays.end() &&
+                    skipped.insert(r).second)
+                    LogPrint("pool", "[pool] not registering at discovered relay %s"
+                             " -- /rvrelay pins the relay list\n", r.c_str());
+        }
         if (relays.empty()) {
             LogPrint("pool", "[pool] no relays available -- miners cannot connect yet\n");
         } else {
@@ -1871,8 +5762,9 @@ static void AcceptLoopFn(void*)
                              relay.c_str());
                 } else {
                     spawned.insert(relay);
-                    LogPrint("pool", "[pool] accept thread spawned for relay %s"
-                             " (%zu total)\n", relay.c_str(), spawned.size());
+                    LogPrint("pool", "[pool] accept thread spawned for relay %s%s"
+                             " (%zu total)\n", relay.c_str(),
+                             fBtfRelayPinned ? " (/rvrelay pin)" : "", spawned.size());
                 }
             }
         }
@@ -1901,16 +5793,24 @@ void ThreadRPCServer(void*)
     }
 
     LoadPendingPayouts();
+    LoadPoolRounds();
     LoadPaying();
     // Must run before the payout thread starts, so nothing is resent that the
-    // wallet already shows as sent, and nothing is owed twice because we died
-    // between recording the payments and rewriting the ledger.
+    // ledger already shows as sent, and every restored in-flight record is
+    // armed for its one wallet probe before it is allowed to send.
     ReconcilePayouts();
 
-    _beginthread(AcceptLoopFn, 0, NULL);
-    _beginthread(LocalAcceptFn, 0, NULL);
-    _beginthread(ThreadBtfPoolAnnouncer, 0, NULL);
-    _beginthread(PayoutThreadFn, 0, NULL);
+    // _beginthread cannot throw (it reports -1), but an unchecked failure
+    // leaves the pool running deaf: nobody accepts, announces, or pays, and
+    // nothing in the log says why.
+    if (_beginthread(AcceptLoopFn, 0, NULL) == (uintptr_t)-1)
+        LogPrint("pool", "[pool] FATAL: accept loop thread failed to spawn -- miners cannot connect\n");
+    if (_beginthread(LocalAcceptFn, 0, NULL) == (uintptr_t)-1)
+        LogPrint("pool", "[pool] local accept thread failed to spawn\n");
+    if (_beginthread(ThreadBtfPoolAnnouncer, 0, NULL) == (uintptr_t)-1)
+        LogPrint("pool", "[pool] announcer thread failed to spawn -- pool will not be advertised\n");
+    if (_beginthread(PayoutThreadFn, 0, NULL) == (uintptr_t)-1)
+        LogPrint("pool", "[pool] FATAL: payout thread failed to spawn -- no one gets paid\n");
 
     PoolEventLoop(); // blocks until gPoolRunning = false or fShutdown
 
diff --git a/src/selftest.cpp b/src/selftest.cpp
index ff0289b..357d532 100644
--- a/src/selftest.cpp
+++ b/src/selftest.cpp
@@ -6,9 +6,20 @@
 // and against a temporary data directory.
 
 #include "headers_core.h"
+#include "btfaddr.h"
 #include "bip32.h"
+#include "proxy.h"
 #include "selftest.h"
+#ifndef _WIN32
+#include <sys/wait.h>   // WIFEXITED/WEXITSTATUS for the child-process helper
+#endif
+#include "sockcount.h"
+#include "tor.h"
 #include "walletcmd.h"
+#include "wallet_sqlite.h"
+
+extern int RunPoolStratumSelfTest();
+extern int RunPayoutLedgerSelfTest();
 
 // Test results go to the terminal, not to debug.log.
 //
@@ -28,6 +39,7 @@
 #undef printf
 
 #include <mutex>
+#include <cerrno>
 #include <stdexcept>
 #include <thread>
 
@@ -55,6 +67,11 @@ static std::string HexStrLocal(const std::vector<unsigned char>& v)
     return out;
 }
 
+static vector<unsigned char> DataStreamBytes(const CDataStream& ss)
+{
+    return vector<unsigned char>(ss.begin(), ss.end());
+}
+
 static bool MakeTempDir(std::string& out)
 {
 #ifdef _WIN32
@@ -348,17 +365,17 @@ static int RunWalletHDSelfTest()
         nFail += Check(HaveHDSeed(), "the wallet reports having a seed") ? 0 : 1;
         nFail += Check(nHDKeySchema == HD_SCHEMA_BIP44,
                        "a new recovery phrase records the BIP44 HD schema") ? 0 : 1;
-        nFail += Check(nHDCoinType == HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL,
-                       "a new recovery phrase records the provisional BIP44 coin type") ? 0 : 1;
+        nFail += Check(nHDCoinType == HD_BIP44_COIN_TYPE_BITFLASH,
+                       "a new recovery phrase records the SLIP-0044 BIP44 coin type") ? 0 : 1;
         nFail += Check(nHDReceiveNext == 1 && nHDChangeNext == 0,
                        "BIP44 receive/change counters reserve the default receive key") ? 0 : 1;
-        std::vector<unsigned int> vBIP44Path = HDBIP44Path(HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL,
+        std::vector<unsigned int> vBIP44Path = HDBIP44Path(HD_BIP44_COIN_TYPE_BITFLASH,
                                                            HD_BIP44_ACCOUNT,
                                                            HD_BIP44_CHAIN_RECEIVE,
                                                            0);
         nFail += Check(vBIP44Path.size() == 5 &&
                        vBIP44Path[0] == (HD_BIP44_PURPOSE | bitflash::BIP32_HARDENED) &&
-                       vBIP44Path[1] == (HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL | bitflash::BIP32_HARDENED) &&
+                       vBIP44Path[1] == (HD_BIP44_COIN_TYPE_BITFLASH | bitflash::BIP32_HARDENED) &&
                        vBIP44Path[2] == (HD_BIP44_ACCOUNT | bitflash::BIP32_HARDENED) &&
                        vBIP44Path[3] == HD_BIP44_CHAIN_RECEIVE &&
                        vBIP44Path[4] == 0,
@@ -380,7 +397,7 @@ static int RunWalletHDSelfTest()
         hdParent.chainCode = vchHDChainCode;
         bitflash::BIP32PrivateNode hdBIP44ReceiveChild;
         if (!bitflash::BIP32DerivePath(hdParent,
-                                       HDBIP44Path(HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL,
+                                       HDBIP44Path(HD_BIP44_COIN_TYPE_BITFLASH,
                                                    HD_BIP44_ACCOUNT,
                                                    HD_BIP44_CHAIN_RECEIVE,
                                                    0),
@@ -568,7 +585,7 @@ static int RunWalletHDSelfTest()
         nFail += Check(audit.fHaveSeed, "the recovery audit reports the phrase") ? 0 : 1;
         nFail += Check(audit.nSchema == HD_SCHEMA_BIP44,
                        "the recovery audit reports the derivation schema") ? 0 : 1;
-        nFail += Check(audit.nCoinType == HD_BIP44_COIN_TYPE_BITFLASH_PROVISIONAL,
+        nFail += Check(audit.nCoinType == HD_BIP44_COIN_TYPE_BITFLASH,
                        "the recovery audit reports the BIP44 coin type") ? 0 : 1;
         nFail += Check(audit.nReceiveNext == nHDReceiveNext && audit.nChangeNext == 1,
                        "the recovery audit reports receive/change counters") ? 0 : 1;
@@ -582,6 +599,34 @@ static int RunWalletHDSelfTest()
                        "the recovery audit finds wallet.dat-only immature mining rewards") ? 0 : 1;
         nFail += Check(audit.nLegacyImmatureTx == 1,
                        "the recovery audit counts wallet.dat-only immature mining rewards") ? 0 : 1;
+
+        CKey keyLegacyHD11;
+        nSchemaForLegacyAudit = nHDKeySchema;
+        nHDKeySchema = HD_SCHEMA_LEGACY;
+        if (!DeriveHDKey(11, keyLegacyHD11, strError))
+            throw std::runtime_error("legacy compatibility index 11 derivation failed: " + strError);
+        nHDKeySchema = nSchemaForLegacyAudit;
+        if (!AddKey(keyLegacyHD11))
+            throw std::runtime_error("could not store the legacy compatibility index 11 key");
+
+        std::map<unsigned int, std::vector<unsigned char> > mapLegacyProbe;
+        mapLegacyProbe[0] = keyAuditLegacyHD.GetPubKey();
+        mapLegacyProbe[11] = keyLegacyHD11.GetPubKey();
+
+        CWalletTx wtxLegacyHD11;
+        wtxLegacyHD11.vout.push_back(CTxOut(19 * COIN, CScript() << keyLegacyHD11.GetPubKey() << OP_CHECKSIG));
+        CRITICAL_BLOCK(cs_mapWallet)
+        {
+            mapWallet.clear();
+            mapWallet[wtxLegacyHD11.GetHash()] = wtxLegacyHD11;
+        }
+        nFail += Check(WalletLastUsedPubKeyIndexNext(mapLegacyProbe) == 12,
+                       "restore collapses legacy hdnext to the last used compatibility index plus one") ? 0 : 1;
+
+        CRITICAL_BLOCK(cs_mapWallet)
+            mapWallet.clear();
+        nFail += Check(WalletLastUsedPubKeyIndexNext(mapLegacyProbe) == 0,
+                       "restore does not persist legacy hdnext at the scan depth when no compatibility key was used") ? 0 : 1;
     }
     catch (const std::exception& e)
     {
@@ -701,6 +746,1017 @@ static int RunWalletFormatSelfTest()
     return nFail == 0 ? 0 : 1;
 }
 
+static bool FileContainsText(const string& strPath, const string& strNeedle);
+static bool MakeDirLocal(const string& strPath);
+static int RunBitflashChild(const string& strExe,
+                            const vector<string>& vArgs,
+                            const string* pStdinFile,
+                            const string* pOutputFile);
+
+class CWalletStorageSanityRawDB : public CWalletDB
+{
+public:
+    CWalletStorageSanityRawDB(const char* pszMode="r+")
+        : CWalletDB(pszMode) { }
+
+    bool WriteUnknownRecord()
+    {
+        return Write(string("storage-sanity-unknown"), 1);
+    }
+
+    bool WriteMalformedKeyRecord()
+    {
+        if (!pdb)
+            return false;
+        unsigned char chKey = 0xff;
+        unsigned char chValue = 0x01;
+        Dbt datKey(&chKey, 1);
+        Dbt datValue(&chValue, 1);
+        return pdb->put(GetTxn(), &datKey, &datValue, 0) == 0;
+    }
+
+    bool MakePlainHDSeedIncomplete()
+    {
+        return Erase(string("hdchaincode"));
+    }
+
+    bool AddEncryptedMarkerToPlainWallet()
+    {
+        CWalletMasterKey kMasterKey;
+        kMasterKey.vchCryptedKey.resize(48);
+        for (size_t i = 0; i < kMasterKey.vchCryptedKey.size(); i++)
+            kMasterKey.vchCryptedKey[i] = (unsigned char)(0x80 + (i & 0x3f));
+        for (size_t i = 0; i < kMasterKey.vchSalt.size(); i++)
+            kMasterKey.vchSalt[i] = (unsigned char)(0x40 + i);
+        return WriteWalletMinVersion(WALLET_FORMAT_ENCRYPTED) &&
+               WriteMasterKey(1, kMasterKey);
+    }
+};
+
+static const char* SELFTEST_MUTATE_WALLET_MARKER =
+    ".bitflash-selftest-wallet-mutate-ok";
+static const char* SELFTEST_MUTATE_WALLET_MARKER_TEXT =
+    "bitflash destructive wallet storage self-test\n";
+
+static string SelfTestMutationMarkerPath()
+{
+    return GetAppDir() + "/" + SELFTEST_MUTATE_WALLET_MARKER;
+}
+
+static bool WriteSelfTestMutationMarker(const string& strDir)
+{
+    string strPath = strDir + "/" + SELFTEST_MUTATE_WALLET_MARKER;
+    FILE* pf = fopen(strPath.c_str(), "wb");
+    if (!pf)
+        return false;
+    bool fOk = fwrite(SELFTEST_MUTATE_WALLET_MARKER_TEXT, 1,
+                      strlen(SELFTEST_MUTATE_WALLET_MARKER_TEXT), pf) ==
+               strlen(SELFTEST_MUTATE_WALLET_MARKER_TEXT);
+    if (fclose(pf) != 0)
+        fOk = false;
+    return fOk;
+}
+
+int RunSelfTestMutateWallet(const std::string& name)
+{
+    if (!FileContainsText(SelfTestMutationMarkerPath(),
+                          SELFTEST_MUTATE_WALLET_MARKER_TEXT))
+    {
+        fprintf(stderr, "Refusing destructive wallet storage mutation outside "
+                        "a marked self-test datadir.\n");
+        return 1;
+    }
+
+    bool fOk = false;
+    try
+    {
+        CWalletStorageSanityRawDB walletdb;
+        if (name == "unknown-record")
+            fOk = walletdb.WriteUnknownRecord();
+        else if (name == "malformed-key")
+            fOk = walletdb.WriteMalformedKeyRecord();
+        else if (name == "incomplete-plain-hd")
+            fOk = walletdb.MakePlainHDSeedIncomplete();
+        else if (name == "encrypted-marker-with-plain-keys")
+            fOk = walletdb.AddEncryptedMarkerToPlainWallet();
+        else
+        {
+            fprintf(stderr, "Unknown wallet storage mutation '%s'\n", name.c_str());
+            return 1;
+        }
+    }
+    catch (const std::exception& e)
+    {
+        fprintf(stderr, "Cannot mutate wallet storage: %s\n", e.what());
+        return 1;
+    }
+    catch (...)
+    {
+        fprintf(stderr, "Cannot mutate wallet storage: unknown exception\n");
+        return 1;
+    }
+
+    DBFlush(true);
+    return fOk ? 0 : 1;
+}
+
+static int RunWalletStorageSanitySelfTest()
+{
+    fflush(stdout);
+    printf("wallet-storage-sanity self-test\n");
+
+    std::string tmp;
+    std::string cwd;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+    if (!GetCurrentDir(cwd))
+    {
+        printf("  FAIL could not read current directory\n");
+        RemoveTree(tmp);
+        return 1;
+    }
+
+    int nFail = 0;
+    printf("  temp root: %s\n", tmp.c_str());
+
+    try
+    {
+#ifdef _WIN32
+        string strExe = cwd + "\\bitflash.exe";
+#else
+        string strExe = cwd + "/bitflash-node";
+#endif
+
+        struct StorageScenario
+        {
+            const char* pszName;
+            const char* pszExpectedFailure;
+        };
+
+        StorageScenario scenarios[] = {
+            { "unknown-record", "wallet.dat contains unknown records" },
+            { "malformed-key", "wallet.dat contains malformed records" },
+            { "incomplete-plain-hd", "plain HD seed is incomplete" },
+            { "encrypted-marker-with-plain-keys",
+              "encrypted wallet still contains plain private key records" },
+        };
+
+        for (size_t i = 0; i < sizeof(scenarios)/sizeof(scenarios[0]); i++)
+        {
+            string strScenarioDir = tmp + "/" + scenarios[i].pszName;
+            nFail += Check(MakeDirLocal(strScenarioDir),
+                           "scenario datadir can be created") ? 0 : 1;
+
+            string strCreateOut = tmp + "/" + scenarios[i].pszName + "-create.txt";
+            vector<string> vCreateArgs;
+            vCreateArgs.push_back("-datadir=" + strScenarioDir);
+            vCreateArgs.push_back("-nomanagedtor");
+            vCreateArgs.push_back("-nogui");
+            vCreateArgs.push_back("-walletbackend=bdb");   // this suite is about wallet.dat
+            vCreateArgs.push_back("-newphrase");
+            int nCreateRet = RunBitflashChild(strExe, vCreateArgs, NULL, &strCreateOut);
+            nFail += Check(nCreateRet == 0 &&
+                           FileContainsText(strCreateOut, "Write these twelve words down"),
+                           "scenario phrase wallet can be created") ? 0 : 1;
+
+            if (i == 0)
+            {
+                string strBlockedOut = tmp + "/" + scenarios[i].pszName + "-blocked-mutate.txt";
+                vector<string> vBlockedArgs;
+                vBlockedArgs.push_back("-datadir=" + strScenarioDir);
+                vBlockedArgs.push_back("-nomanagedtor");
+                vBlockedArgs.push_back("-nogui");
+                vBlockedArgs.push_back("-selftestmutatewallet=" + string(scenarios[i].pszName));
+                int nBlockedRet = RunBitflashChild(strExe, vBlockedArgs, NULL, &strBlockedOut);
+                nFail += Check(nBlockedRet != 0 &&
+                               FileContainsText(strBlockedOut, "Refusing destructive wallet storage mutation"),
+                               "wallet mutation helper is blocked without marker") ? 0 : 1;
+            }
+
+            nFail += Check(WriteSelfTestMutationMarker(strScenarioDir),
+                           "scenario mutation marker can be written") ? 0 : 1;
+
+            string strMutateOut = tmp + "/" + scenarios[i].pszName + "-mutate.txt";
+            vector<string> vMutateArgs;
+            vMutateArgs.push_back("-datadir=" + strScenarioDir);
+            vMutateArgs.push_back("-nomanagedtor");
+            vMutateArgs.push_back("-nogui");
+            vMutateArgs.push_back("-selftestmutatewallet=" + string(scenarios[i].pszName));
+            int nMutateRet = RunBitflashChild(strExe, vMutateArgs, NULL, &strMutateOut);
+            nFail += Check(nMutateRet == 0, scenarios[i].pszName) ? 0 : 1;
+
+            string strCheckOut = tmp + "/" + scenarios[i].pszName + "-check.txt";
+            vector<string> vCheckArgs;
+            vCheckArgs.push_back("-datadir=" + strScenarioDir);
+            vCheckArgs.push_back("-nomanagedtor");
+            vCheckArgs.push_back("-nogui");
+            vCheckArgs.push_back("-walletstoragecheck");
+            int nCheckRet = RunBitflashChild(strExe, vCheckArgs, NULL, &strCheckOut);
+            nFail += Check(nCheckRet == 2 &&
+                           FileContainsText(strCheckOut, "storage sanity:            failed") &&
+                           FileContainsText(strCheckOut, scenarios[i].pszExpectedFailure),
+                           scenarios[i].pszExpectedFailure) ? 0 : 1;
+        }
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+static int RunDbEnvReopenSelfTest()
+{
+    fflush(stdout);
+    printf("db-env-reopen self-test\n");
+
+    std::string tmp;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+
+    int nFail = 0;
+    std::string strOldDataDir = strSetDataDir;
+    strSetDataDir = tmp;
+    printf("  temp datadir: %s\n", tmp.c_str());
+
+    try
+    {
+        for (int i = 0; i < 5; i++)
+        {
+            int64 nValue = 1000 + i;
+            {
+                CWalletDB walletdb("cr+");
+                nFail += Check(walletdb.WriteSetting("db-env-reopen-cycle", nValue),
+                               "wallet setting can be written before shutdown") ? 0 : 1;
+            }
+
+            DBFlush(true);
+
+            int64 nRead = 0;
+            {
+                CWalletDB walletdb("r");
+                nFail += Check(walletdb.ReadSetting("db-env-reopen-cycle", nRead),
+                               "wallet setting can be read after env reopen") ? 0 : 1;
+            }
+            nFail += Check(nRead == nValue,
+                           "reopened environment reads the last committed value") ? 0 : 1;
+
+            DBFlush(true);
+        }
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    DBFlush(true);
+    strSetDataDir = strOldDataDir;
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+static int RunWalletSQLiteSelfTest()
+{
+    fflush(stdout);
+    printf("wallet-sqlite self-test\n");
+
+    std::string tmp;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+
+    int nFail = 0;
+    string strPath = tmp + "/wallet.sqlite";
+    string strError;
+    string strOldRuntimeDataDir;
+    bool fRestoreRuntimeDataDir = false;
+
+    try
+    {
+        CDataStream ssKeySetting(SER_DISK);
+        ssKeySetting << make_pair(string("setting"), string("sqlite-roundtrip"));
+        CDataStream ssValueSetting(SER_DISK);
+        ssValueSetting << (int64)424242;
+
+        vector<unsigned char> vchPubKey;
+        vchPubKey.push_back(0x04);
+        for (int i = 0; i < 64; i++)
+            vchPubKey.push_back((unsigned char)i);
+        CDataStream ssKeyDefault(SER_DISK);
+        ssKeyDefault << string("defaultkey");
+        CDataStream ssValueDefault(SER_DISK);
+        ssValueDefault << vchPubKey;
+
+        {
+            CWalletDBSQLite db;
+            nFail += Check(db.Open(strPath, strError),
+                           "SQLite wallet opens and creates schema") ? 0 : 1;
+            nFail += Check(db.BeginTransaction(strError),
+                           "SQLite wallet begins a write transaction") ? 0 : 1;
+            nFail += Check(db.WriteRecord(DataStreamBytes(ssKeySetting),
+                                          DataStreamBytes(ssValueSetting),
+                                          strError),
+                           "SQLite wallet writes a serialized setting record") ? 0 : 1;
+            nFail += Check(db.WriteRecord(DataStreamBytes(ssKeyDefault),
+                                          DataStreamBytes(ssValueDefault),
+                                          strError),
+                           "SQLite wallet writes a serialized defaultkey record") ? 0 : 1;
+            nFail += Check(db.CommitTransaction(strError),
+                           "SQLite wallet commits a write transaction") ? 0 : 1;
+            int nCount = 0;
+            nFail += Check(db.CountRecords(nCount, strError) && nCount == 2,
+                           "SQLite wallet counts raw records") ? 0 : 1;
+        }
+
+        {
+            CWalletDBSQLite db;
+            nFail += Check(db.Open(strPath, strError),
+                           "SQLite wallet reopens") ? 0 : 1;
+            vector<unsigned char> vchRead;
+            nFail += Check(db.ReadRecord(DataStreamBytes(ssKeySetting),
+                                         vchRead,
+                                         strError),
+                           "SQLite wallet reads a serialized setting record") ? 0 : 1;
+            int64 nReadValue = 0;
+            CDataStream ssRead(vchRead, SER_DISK);
+            ssRead >> nReadValue;
+            nFail += Check(!ssRead.fail() && nReadValue == 424242,
+                           "SQLite wallet preserves serialized values byte-for-byte") ? 0 : 1;
+
+            vchRead.clear();
+            nFail += Check(db.ReadRecord(DataStreamBytes(ssKeyDefault),
+                                         vchRead,
+                                         strError),
+                           "SQLite wallet reads a serialized defaultkey record") ? 0 : 1;
+            vector<unsigned char> vchReadPubKey;
+            CDataStream ssReadDefault(vchRead, SER_DISK);
+            ssReadDefault >> vchReadPubKey;
+            nFail += Check(!ssReadDefault.fail() && vchReadPubKey == vchPubKey,
+                           "SQLite wallet preserves public key blobs") ? 0 : 1;
+        }
+
+        {
+            CWalletDBSQLite db;
+            nFail += Check(db.Open(strPath, strError),
+                           "SQLite wallet reopens for typed records") ? 0 : 1;
+
+            nFail += Check(db.WriteTypedRecord(make_pair(string("setting"),
+                                                         string("sqlite-typed")),
+                                               (int64)777, strError),
+                           "SQLite wallet writes a typed setting record") ? 0 : 1;
+
+            int64 nTypedRead = 0;
+            nFail += Check(db.ReadTypedRecord(make_pair(string("setting"),
+                                                        string("sqlite-typed")),
+                                              nTypedRead, strError) &&
+                           nTypedRead == 777,
+                           "SQLite wallet reads a typed setting record") ? 0 : 1;
+
+            nFail += Check(!db.WriteTypedRecord(make_pair(string("setting"),
+                                                          string("sqlite-typed")),
+                                                (int64)888, strError, false),
+                           "SQLite wallet refuses typed overwrite when asked") ? 0 : 1;
+
+            nTypedRead = 0;
+            nFail += Check(db.ReadTypedRecord(make_pair(string("setting"),
+                                                        string("sqlite-typed")),
+                                              nTypedRead, strError) &&
+                           nTypedRead == 777,
+                           "SQLite wallet preserves the old typed value after overwrite refusal") ? 0 : 1;
+
+            nFail += Check(db.EraseTypedRecord(make_pair(string("setting"),
+                                                         string("sqlite-typed")),
+                                               strError),
+                           "SQLite wallet erases a typed record") ? 0 : 1;
+
+            nTypedRead = 0;
+            nFail += Check(!db.ReadTypedRecord(make_pair(string("setting"),
+                                                         string("sqlite-typed")),
+                                               nTypedRead, strError),
+                           "SQLite wallet typed erase removes the record") ? 0 : 1;
+
+            nFail += Check(db.WriteTypedRecord(string("defaultkey"), vchPubKey,
+                                               strError),
+                           "SQLite wallet writes a typed defaultkey record") ? 0 : 1;
+
+            vector<unsigned char> vchTypedPubKey;
+            nFail += Check(db.ReadTypedRecord(string("defaultkey"), vchTypedPubKey,
+                                              strError) &&
+                           vchTypedPubKey == vchPubKey,
+                           "SQLite wallet reads a typed defaultkey record") ? 0 : 1;
+        }
+
+        {
+            string strRuntimePath = tmp + "/runtime-wallet.sqlite";
+            string strRuntimeDir = tmp + "/runtime-datadir";
+            nFail += Check(MakeDirLocal(strRuntimeDir),
+                           "SQLite runtime datadir can be created") ? 0 : 1;
+
+            {
+                CWalletDBSQLite db;
+                nFail += Check(db.Open(strRuntimePath, strError),
+                               "SQLite runtime wallet file can be created") ? 0 : 1;
+            }
+
+            string strOldDataDir = strSetDataDir;
+            strSetDataDir = strRuntimeDir;
+            strOldRuntimeDataDir = strOldDataDir;
+            fRestoreRuntimeDataDir = true;
+            bool fRuntimeOpened = WalletSQLiteRuntimeOpen(strRuntimePath, strError);
+            nFail += Check(fRuntimeOpened,
+                           "SQLite runtime wallet can be activated") ? 0 : 1;
+
+            if (fRuntimeOpened)
+            {
+                CKey key;
+                key.MakeNewKey();
+                vector<unsigned char> vchRuntimePubKey = key.GetPubKey();
+                CPrivKey vchRuntimePrivKey = key.GetPrivKey();
+                string strRuntimeAddress = PubKeyToAddress(vchRuntimePubKey);
+
+                nFail += Check(CWalletDB().WriteSetting("runtime-sqlite-setting",
+                                                        (int64)909090) &&
+                               CWalletDB().WriteDefaultKey(vchRuntimePubKey) &&
+                               CWalletDB().WriteKey(vchRuntimePubKey,
+                                                    vchRuntimePrivKey) &&
+                               CWalletDB().WriteName(strRuntimeAddress,
+                                                     "SQLite Runtime Address"),
+                               "CWalletDB writes route to active SQLite runtime") ? 0 : 1;
+
+                int64 nRuntimeSetting = 0;
+                vector<unsigned char> vchRuntimeDefaultKey;
+                CPrivKey vchRuntimeReadPrivKey;
+                string strRuntimeName;
+                nFail += Check(CWalletDB("r").ReadSetting("runtime-sqlite-setting",
+                                                          nRuntimeSetting) &&
+                               nRuntimeSetting == 909090 &&
+                               CWalletDB("r").ReadDefaultKey(vchRuntimeDefaultKey) &&
+                               vchRuntimeDefaultKey == vchRuntimePubKey &&
+                               CWalletDB("r").ReadKey(vchRuntimePubKey,
+                                                      vchRuntimeReadPrivKey) &&
+                               vchRuntimeReadPrivKey == vchRuntimePrivKey &&
+                               CWalletDB("r").ReadName(strRuntimeAddress,
+                                                       strRuntimeName) &&
+                               strRuntimeName == "SQLite Runtime Address",
+                               "CWalletDB reads route to active SQLite runtime") ? 0 : 1;
+
+                nFail += Check(CWalletDB().EraseName(strRuntimeAddress) &&
+                               !CWalletDB("r").ReadName(strRuntimeAddress,
+                                                        strRuntimeName),
+                               "CWalletDB erases route to active SQLite runtime") ? 0 : 1;
+
+                nFail += Check(!FileExists((strRuntimeDir + "/wallet.dat").c_str()),
+                               "active SQLite runtime does not create wallet.dat") ? 0 : 1;
+
+                // Transaction bracket: a rolled-back group leaves nothing, a
+                // committed group persists. This is the all-or-nothing that
+                // WriteHDMaster relies on so a half-written seed cannot survive
+                // a failure between its two records.
+                bool fTxnBegan = WalletSQLiteRuntimeBeginTxn();
+                bool fTxnWrote = fTxnBegan &&
+                    CWalletDB().WriteSetting("runtime-txn-rollback", (int64)111);
+                if (fTxnBegan)
+                    WalletSQLiteRuntimeRollbackTxn();
+                nFail += Check(fTxnBegan && fTxnWrote,
+                               "a SQLite runtime transaction opens and rolls back") ? 0 : 1;
+                int64 nRolledBack = 0;
+                nFail += Check(!CWalletDB("r").ReadSetting("runtime-txn-rollback",
+                                                           nRolledBack),
+                               "a rolled-back SQLite runtime write leaves no record") ? 0 : 1;
+
+                bool fCommitOk = WalletSQLiteRuntimeBeginTxn() &&
+                    CWalletDB().WriteSetting("runtime-txn-commit", (int64)222) &&
+                    WalletSQLiteRuntimeCommitTxn();
+                int64 nCommitted = 0;
+                nFail += Check(fCommitOk &&
+                               CWalletDB("r").ReadSetting("runtime-txn-commit",
+                                                          nCommitted) &&
+                               nCommitted == 222,
+                               "a committed SQLite runtime write persists") ? 0 : 1;
+
+                // WriteHDMaster brackets its two records in that transaction;
+                // both halves of the seed must land.
+                vector<unsigned char> vchTxnMaster(32, 0x5a);
+                vector<unsigned char> vchTxnChainCode(32, 0xa5);
+                vector<unsigned char> vchReadMaster, vchReadChainCode;
+                nFail += Check(CWalletDB().WriteHDMaster(vchTxnMaster, vchTxnChainCode) &&
+                               CWalletDB("r").ReadHDMaster(vchReadMaster, vchReadChainCode) &&
+                               vchReadMaster == vchTxnMaster &&
+                               vchReadChainCode == vchTxnChainCode,
+                               "WriteHDMaster commits both halves of the seed under SQLite") ? 0 : 1;
+
+                // Durability: close the backend (checkpoints the WAL), reopen
+                // the same file, and confirm what CWalletDB wrote is still
+                // there. This is the write-survives-a-restart property the real
+                // -walletbackend=sqlite node depends on.
+                WalletSQLiteRuntimeClose();
+                bool fReopened =
+                    WalletSQLiteRuntimeOpen(strRuntimePath, strError);
+                nFail += Check(fReopened,
+                               "SQLite runtime wallet reopens after close") ? 0 : 1;
+                if (fReopened)
+                {
+                    int64 nPersisted = 0;
+                    CPrivKey vchPersistedPrivKey;
+                    vector<unsigned char> vchPersistedDefaultKey;
+                    nFail += Check(CWalletDB("r").ReadSetting("runtime-sqlite-setting",
+                                                              nPersisted) &&
+                                   nPersisted == 909090 &&
+                                   CWalletDB("r").ReadDefaultKey(vchPersistedDefaultKey) &&
+                                   vchPersistedDefaultKey == vchRuntimePubKey &&
+                                   CWalletDB("r").ReadKey(vchRuntimePubKey,
+                                                          vchPersistedPrivKey) &&
+                                   vchPersistedPrivKey == vchRuntimePrivKey,
+                                   "SQLite runtime writes persist across a close and reopen") ? 0 : 1;
+                }
+            }
+
+            WalletSQLiteRuntimeClose();
+            strSetDataDir = strOldDataDir;
+            fRestoreRuntimeDataDir = false;
+        }
+    }
+    catch (const std::exception& e)
+    {
+        WalletSQLiteRuntimeClose();
+        if (fRestoreRuntimeDataDir)
+            strSetDataDir = strOldRuntimeDataDir;
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        WalletSQLiteRuntimeClose();
+        if (fRestoreRuntimeDataDir)
+            strSetDataDir = strOldRuntimeDataDir;
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+namespace {
+
+class CWalletRecordMapVisitor : public CWalletRecordVisitor
+{
+public:
+    std::map<vector<unsigned char>, vector<unsigned char> >& mapRecords;
+
+    explicit CWalletRecordMapVisitor(
+        std::map<vector<unsigned char>, vector<unsigned char> >& mapRecordsIn)
+        : mapRecords(mapRecordsIn) { }
+
+    bool VisitWalletRecord(const CDataStream& ssKey,
+                           const CDataStream& ssValue,
+                           string& strErrorRet)
+    {
+        vector<unsigned char> vchKey = DataStreamBytes(ssKey);
+        if (mapRecords.count(vchKey))
+        {
+            strErrorRet = "duplicate serialized wallet key";
+            return false;
+        }
+        mapRecords[vchKey] = DataStreamBytes(ssValue);
+        return true;
+    }
+};
+
+} // namespace
+
+static bool CreateSQLiteWalletWithEmptyKey(const string& strPath)
+{
+    sqlite3* pdb = NULL;
+    int ret = sqlite3_open_v2(strPath.c_str(), &pdb,
+                              SQLITE_OPEN_READWRITE |
+                              SQLITE_OPEN_CREATE |
+                              SQLITE_OPEN_FULLMUTEX,
+                              NULL);
+    if (ret != SQLITE_OK || !pdb)
+    {
+        if (pdb)
+            sqlite3_close(pdb);
+        return false;
+    }
+
+    char* pszErr = NULL;
+    bool fOk =
+        sqlite3_exec(pdb,
+                     "CREATE TABLE wallet_records ("
+                     "key BLOB PRIMARY KEY NOT NULL,"
+                     "value BLOB NOT NULL"
+                     ");",
+                     NULL, NULL, &pszErr) == SQLITE_OK &&
+        sqlite3_exec(pdb,
+                     "INSERT INTO wallet_records(key, value) "
+                     "VALUES(x'', x'01');",
+                     NULL, NULL, &pszErr) == SQLITE_OK;
+    if (pszErr)
+        sqlite3_free(pszErr);
+    sqlite3_close(pdb);
+    return fOk;
+}
+
+static bool CreateSQLiteWalletWithFutureMinVersion(const string& strPath)
+{
+    string strError;
+    CWalletDBSQLite db;
+    CDataStream ssKey(SER_DISK);
+    ssKey << string("walletminversion");
+    CDataStream ssValue(SER_DISK);
+    ssValue << (WALLET_FORMAT_SUPPORTED + 1);
+
+    if (!db.Open(strPath, strError))
+        return false;
+    if (!db.BeginTransaction(strError))
+        return false;
+    if (!db.WriteRecord(DataStreamBytes(ssKey), DataStreamBytes(ssValue), strError))
+        return false;
+    if (!db.CommitTransaction(strError))
+        return false;
+    if (!db.Checkpoint(strError))
+        return false;
+    return true;
+}
+
+static bool CreateTypedSQLiteWallet(const string& strPath)
+{
+    string strError;
+    CWalletDBSQLite db;
+    CKey key;
+    key.MakeNewKey();
+
+    vector<unsigned char> vchPubKey = key.GetPubKey();
+    CPrivKey vchPrivKey = key.GetPrivKey();
+    string strAddress = PubKeyToAddress(vchPubKey);
+
+    if (!db.Open(strPath, strError))
+        return false;
+    if (!db.BeginTransaction(strError))
+        return false;
+    if (!db.WriteTypedRecord(make_pair(string("key"), vchPubKey),
+                             vchPrivKey, strError, false))
+        return false;
+    if (!db.WriteTypedRecord(string("defaultkey"), vchPubKey, strError))
+        return false;
+    if (!db.WriteTypedRecord(make_pair(string("name"), strAddress),
+                             string("Typed SQLite Address"), strError))
+        return false;
+    if (!db.CommitTransaction(strError))
+        return false;
+    if (!db.Checkpoint(strError))
+        return false;
+    return true;
+}
+
+static int RunWalletSQLiteMigrationSelfTest()
+{
+    fflush(stdout);
+    printf("wallet-sqlite-migration self-test\n");
+
+    std::string tmp;
+    std::string cwd;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+    if (!GetCurrentDir(cwd))
+    {
+        printf("  FAIL could not read current directory\n");
+        RemoveTree(tmp);
+        return 1;
+    }
+
+    int nFail = 0;
+    printf("  temp root: %s\n", tmp.c_str());
+
+    try
+    {
+#ifdef _WIN32
+        string strExe = cwd + "\\bitflash.exe";
+#else
+        string strExe = cwd + "/bitflash-node";
+#endif
+        string strWalletDir = tmp + "/wallet";
+        nFail += Check(MakeDirLocal(strWalletDir),
+                       "temporary wallet directory can be created") ? 0 : 1;
+
+        string strCreateOut = tmp + "/create.txt";
+        vector<string> vCreateArgs;
+        vCreateArgs.push_back("-datadir=" + strWalletDir);
+        vCreateArgs.push_back("-nomanagedtor");
+        vCreateArgs.push_back("-nogui");
+        vCreateArgs.push_back("-walletbackend=bdb");   // migrate FROM a Berkeley DB wallet.dat
+        vCreateArgs.push_back("-newphrase");
+        int nCreateRet = RunBitflashChild(strExe, vCreateArgs, NULL, &strCreateOut);
+        nFail += Check(nCreateRet == 0 &&
+                       FileContainsText(strCreateOut, "Write these twelve words down"),
+                       "a phrase wallet can be created for SQLite export") ? 0 : 1;
+
+        string strSQLite = tmp + "/wallet.sqlite";
+        string strExportOut = tmp + "/sqlite-export.txt";
+        vector<string> vExportArgs;
+        vExportArgs.push_back("-datadir=" + strWalletDir);
+        vExportArgs.push_back("-nomanagedtor");
+        vExportArgs.push_back("-nogui");
+        vExportArgs.push_back("-walletsqliteexport=" + strSQLite);
+        int nExportRet = RunBitflashChild(strExe, vExportArgs, NULL, &strExportOut);
+        nFail += Check(nExportRet == 0 &&
+                       FileExists(strSQLite.c_str()) &&
+                       FileContainsText(strExportOut, "SQLite wallet export written"),
+                       "wallet.dat can be exported to SQLite") ? 0 : 1;
+
+        string strVerifyOut = tmp + "/sqlite-verify.txt";
+        vector<string> vVerifyArgs;
+        vVerifyArgs.push_back("-datadir=" + strWalletDir);
+        vVerifyArgs.push_back("-nomanagedtor");
+        vVerifyArgs.push_back("-nogui");
+        vVerifyArgs.push_back("-walletsqliteverify=" + strSQLite);
+        int nVerifyRet = RunBitflashChild(strExe, vVerifyArgs, NULL, &strVerifyOut);
+        nFail += Check(nVerifyRet == 0 &&
+                       FileContainsText(strVerifyOut, "verification:              ok"),
+                       "SQLite wallet export verifies against wallet.dat") ? 0 : 1;
+
+        string strLoadCheckOut = tmp + "/sqlite-loadcheck.txt";
+        vector<string> vLoadCheckArgs;
+        vLoadCheckArgs.push_back("-datadir=" + strWalletDir);
+        vLoadCheckArgs.push_back("-nomanagedtor");
+        vLoadCheckArgs.push_back("-nogui");
+        vLoadCheckArgs.push_back("-walletsqliteloadcheck=" + strSQLite);
+        int nLoadCheckRet =
+            RunBitflashChild(strExe, vLoadCheckArgs, NULL, &strLoadCheckOut);
+        nFail += Check(nLoadCheckRet == 0 &&
+                       FileContainsText(strLoadCheckOut,
+                                        "load check:                ok"),
+                       "SQLite wallet export passes the loader compatibility check") ? 0 : 1;
+
+        string strRuntimeOut = tmp + "/sqlite-runtime.txt";
+        vector<string> vRuntimeArgs;
+        vRuntimeArgs.push_back("-datadir=" + strWalletDir);
+        vRuntimeArgs.push_back("-nomanagedtor");
+        vRuntimeArgs.push_back("-nogui");
+        vRuntimeArgs.push_back("-walletsqlite=" + strSQLite);
+        int nRuntimeRet =
+            RunBitflashChild(strExe, vRuntimeArgs, NULL, &strRuntimeOut);
+        nFail += Check(nRuntimeRet == 0 &&
+                       FileContainsText(strRuntimeOut,
+                                        "SQLite wallet loaded: read-only staging backend"),
+                       "SQLite wallet export loads through the runtime startup path") ? 0 : 1;
+
+        string strTypedSQLite = tmp + "/typed-wallet.sqlite";
+        nFail += Check(CreateTypedSQLiteWallet(strTypedSQLite),
+                       "typed SQLite wallet can be created without Berkeley DB") ? 0 : 1;
+
+        string strTypedLoadCheckOut = tmp + "/sqlite-typed-loadcheck.txt";
+        vector<string> vTypedLoadCheckArgs;
+        vTypedLoadCheckArgs.push_back("-datadir=" + strWalletDir);
+        vTypedLoadCheckArgs.push_back("-nomanagedtor");
+        vTypedLoadCheckArgs.push_back("-nogui");
+        vTypedLoadCheckArgs.push_back("-walletsqliteloadcheck=" + strTypedSQLite);
+        int nTypedLoadCheckRet =
+            RunBitflashChild(strExe, vTypedLoadCheckArgs, NULL,
+                             &strTypedLoadCheckOut);
+        nFail += Check(nTypedLoadCheckRet == 0 &&
+                       FileContainsText(strTypedLoadCheckOut,
+                                        "load check:                ok"),
+                       "typed SQLite wallet passes the loader compatibility check") ? 0 : 1;
+
+        string strTypedRuntimeDir = tmp + "/typed-runtime-wallet";
+        nFail += Check(MakeDirLocal(strTypedRuntimeDir),
+                       "typed SQLite runtime directory can be created") ? 0 : 1;
+        string strTypedRuntimeOut = tmp + "/sqlite-typed-runtime.txt";
+        vector<string> vTypedRuntimeArgs;
+        vTypedRuntimeArgs.push_back("-datadir=" + strTypedRuntimeDir);
+        vTypedRuntimeArgs.push_back("-nomanagedtor");
+        vTypedRuntimeArgs.push_back("-nogui");
+        vTypedRuntimeArgs.push_back("-walletsqlite=" + strTypedSQLite);
+        int nTypedRuntimeRet =
+            RunBitflashChild(strExe, vTypedRuntimeArgs, NULL,
+                             &strTypedRuntimeOut);
+        nFail += Check(nTypedRuntimeRet == 0 &&
+                       FileContainsText(strTypedRuntimeOut,
+                                        "SQLite wallet loaded: read-only staging backend") &&
+                       !FileExists((strTypedRuntimeDir + "/wallet.dat").c_str()),
+                       "typed SQLite wallet loads through runtime without creating wallet.dat") ? 0 : 1;
+
+        string strRestoredDir = tmp + "/restored-wallet";
+        nFail += Check(MakeDirLocal(strRestoredDir),
+                       "restored wallet directory can be created") ? 0 : 1;
+        string strRestoreOut = tmp + "/sqlite-restore.txt";
+        vector<string> vRestoreArgs;
+        vRestoreArgs.push_back("-datadir=" + strRestoredDir);
+        vRestoreArgs.push_back("-nomanagedtor");
+        vRestoreArgs.push_back("-nogui");
+        vRestoreArgs.push_back("-walletsqliterestore=" + strSQLite);
+        int nRestoreRet = RunBitflashChild(strExe, vRestoreArgs, NULL, &strRestoreOut);
+        nFail += Check(nRestoreRet == 0 &&
+                       FileContainsText(strRestoreOut, "records restored:"),
+                       "SQLite wallet export restores into a fresh wallet.dat") ? 0 : 1;
+
+        string strVerifyRestoredOut = tmp + "/sqlite-verify-restored.txt";
+        vector<string> vVerifyRestoredArgs;
+        vVerifyRestoredArgs.push_back("-datadir=" + strRestoredDir);
+        vVerifyRestoredArgs.push_back("-nomanagedtor");
+        vVerifyRestoredArgs.push_back("-nogui");
+        vVerifyRestoredArgs.push_back("-walletsqliteverify=" + strSQLite);
+        int nVerifyRestoredRet =
+            RunBitflashChild(strExe, vVerifyRestoredArgs, NULL, &strVerifyRestoredOut);
+        nFail += Check(nVerifyRestoredRet == 0 &&
+                       FileContainsText(strVerifyRestoredOut,
+                                        "verification:              ok"),
+                       "restored wallet.dat verifies against the SQLite export") ? 0 : 1;
+
+        string strRestoreOverwriteOut = tmp + "/sqlite-restore-overwrite.txt";
+        int nRestoreOverwriteRet =
+            RunBitflashChild(strExe, vRestoreArgs, NULL, &strRestoreOverwriteOut);
+        nFail += Check(nRestoreOverwriteRet == 1 &&
+                       FileContainsText(strRestoreOverwriteOut,
+                                        "Refusing to overwrite existing wallet.dat"),
+                       "SQLite wallet restore refuses to overwrite wallet.dat") ? 0 : 1;
+
+        string strBadSQLite = tmp + "/bad-empty-key.sqlite";
+        nFail += Check(CreateSQLiteWalletWithEmptyKey(strBadSQLite),
+                       "bad SQLite export with an empty key can be created") ? 0 : 1;
+        string strBadRestoreDir = tmp + "/bad-restore-wallet";
+        nFail += Check(MakeDirLocal(strBadRestoreDir),
+                       "bad restore wallet directory can be created") ? 0 : 1;
+        string strBadRestoreOut = tmp + "/sqlite-restore-bad.txt";
+        vector<string> vBadRestoreArgs;
+        vBadRestoreArgs.push_back("-datadir=" + strBadRestoreDir);
+        vBadRestoreArgs.push_back("-nomanagedtor");
+        vBadRestoreArgs.push_back("-nogui");
+        vBadRestoreArgs.push_back("-walletsqliterestore=" + strBadSQLite);
+        int nBadRestoreRet =
+            RunBitflashChild(strExe, vBadRestoreArgs, NULL, &strBadRestoreOut);
+        nFail += Check(nBadRestoreRet == 1 &&
+                       FileContainsText(strBadRestoreOut,
+                                        "Cannot restore SQLite wallet export") &&
+                       !FileExists((strBadRestoreDir + "/wallet.dat").c_str()),
+                       "failed SQLite wallet restore removes incomplete wallet.dat") ? 0 : 1;
+
+        string strFutureSQLite = tmp + "/future-wallet.sqlite";
+        nFail += Check(CreateSQLiteWalletWithFutureMinVersion(strFutureSQLite),
+                       "SQLite export with a future wallet format can be created") ? 0 : 1;
+        string strFutureLoadCheckOut = tmp + "/sqlite-loadcheck-future.txt";
+        vector<string> vFutureLoadCheckArgs;
+        vFutureLoadCheckArgs.push_back("-datadir=" + strWalletDir);
+        vFutureLoadCheckArgs.push_back("-nomanagedtor");
+        vFutureLoadCheckArgs.push_back("-nogui");
+        vFutureLoadCheckArgs.push_back("-walletsqliteloadcheck=" + strFutureSQLite);
+        int nFutureLoadCheckRet =
+            RunBitflashChild(strExe, vFutureLoadCheckArgs, NULL,
+                             &strFutureLoadCheckOut);
+        nFail += Check(nFutureLoadCheckRet == 2 &&
+                       FileContainsText(strFutureLoadCheckOut,
+                                        "unsupported future wallet format") &&
+                       FileContainsText(strFutureLoadCheckOut,
+                                        "load check:                failed"),
+                       "SQLite wallet load check rejects future wallet formats") ? 0 : 1;
+
+        string strFutureRuntimeOut = tmp + "/sqlite-runtime-future.txt";
+        vector<string> vFutureRuntimeArgs;
+        vFutureRuntimeArgs.push_back("-datadir=" + strWalletDir);
+        vFutureRuntimeArgs.push_back("-nomanagedtor");
+        vFutureRuntimeArgs.push_back("-nogui");
+        vFutureRuntimeArgs.push_back("-walletsqlite=" + strFutureSQLite);
+        int nFutureRuntimeRet =
+            RunBitflashChild(strExe, vFutureRuntimeArgs, NULL,
+                             &strFutureRuntimeOut);
+        nFail += Check(nFutureRuntimeRet == 1 &&
+                       FileContainsText(strFutureRuntimeOut,
+                                        "Cannot open SQLite wallet export") &&
+                       FileContainsText(strFutureRuntimeOut,
+                                        "newer version of Bitflash"),
+                       "SQLite runtime startup rejects future wallet formats") ? 0 : 1;
+
+        string strOverwriteOut = tmp + "/sqlite-export-overwrite.txt";
+        int nOverwriteRet =
+            RunBitflashChild(strExe, vExportArgs, NULL, &strOverwriteOut);
+        nFail += Check(nOverwriteRet != 0 &&
+                       FileContainsText(strOverwriteOut,
+                                        "Refusing to overwrite existing SQLite wallet export"),
+                       "SQLite wallet export refuses to overwrite") ? 0 : 1;
+        remove((strSQLite + "-wal").c_str());
+        remove((strSQLite + "-shm").c_str());
+
+        std::map<vector<unsigned char>, vector<unsigned char> > mapBDB;
+        string strOldDataDir = strSetDataDir;
+        string strScanError;
+        strSetDataDir = strWalletDir;
+        CWalletRecordMapVisitor visitor(mapBDB);
+        bool fScanOk = ScanWalletRecords(visitor, strScanError);
+        DBFlush(true);
+        strSetDataDir = strOldDataDir;
+        nFail += Check(fScanOk && !mapBDB.empty(),
+                       "wallet.dat records can be scanned for comparison") ? 0 : 1;
+
+        CWalletDBSQLite db;
+        string strError;
+        nFail += Check(db.Open(strSQLite, strError),
+                       "exported SQLite wallet opens") ? 0 : 1;
+        int nSQLiteRecords = 0;
+        nFail += Check(db.CountRecords(nSQLiteRecords, strError) &&
+                       nSQLiteRecords == (int)mapBDB.size(),
+                       "SQLite export has the same record count as wallet.dat") ? 0 : 1;
+
+        bool fAllMatch = true;
+        for (std::map<vector<unsigned char>, vector<unsigned char> >::const_iterator it =
+                 mapBDB.begin(); it != mapBDB.end(); ++it)
+        {
+            vector<unsigned char> vchSQLiteValue;
+            if (!db.ReadRecord(it->first, vchSQLiteValue, strError) ||
+                vchSQLiteValue != it->second)
+            {
+                fAllMatch = false;
+                break;
+            }
+        }
+        nFail += Check(fAllMatch,
+                       "SQLite export preserves every wallet.dat key/value byte-for-byte") ? 0 : 1;
+
+        std::map<vector<unsigned char>, vector<unsigned char> > mapSQLite;
+        CWalletRecordMapVisitor sqliteVisitor(mapSQLite);
+        nFail += Check(db.ScanRecords(sqliteVisitor, strError) &&
+                       mapSQLite == mapBDB,
+                       "SQLite wallet scanner streams every exported record byte-for-byte") ? 0 : 1;
+
+        db.Close();
+        CWalletDBSQLite dbCorrupt;
+        vector<unsigned char> vchBadValue;
+        vchBadValue.push_back(0xba);
+        vchBadValue.push_back(0xad);
+        nFail += Check(!mapBDB.empty() &&
+                       dbCorrupt.Open(strSQLite, strError) &&
+                       dbCorrupt.BeginTransaction(strError) &&
+                       dbCorrupt.WriteRecord(mapBDB.begin()->first,
+                                             vchBadValue,
+                                             strError) &&
+                       dbCorrupt.CommitTransaction(strError) &&
+                       dbCorrupt.Checkpoint(strError),
+                       "SQLite export can be deliberately corrupted for verifier test") ? 0 : 1;
+        dbCorrupt.Close();
+
+        string strVerifyBadOut = tmp + "/sqlite-verify-bad.txt";
+        int nVerifyBadRet =
+            RunBitflashChild(strExe, vVerifyArgs, NULL, &strVerifyBadOut);
+        nFail += Check(nVerifyBadRet == 2 &&
+                       FileContainsText(strVerifyBadOut,
+                                        "record value mismatches:   1") &&
+                       FileContainsText(strVerifyBadOut,
+                                        "verification:              failed"),
+                       "SQLite wallet verifier detects a mismatched record value") ? 0 : 1;
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
 static void ClearWalletRuntimeForTest()
 {
     CRITICAL_BLOCK(cs_mapKeys)
@@ -891,6 +1947,90 @@ static bool WriteTextFile(const string& strPath, const string& strText)
     return fOk;
 }
 
+static bool MakeDirLocal(const string& strPath)
+{
+#ifdef _WIN32
+    return CreateDirectoryA(strPath.c_str(), NULL) || GetLastError() == ERROR_ALREADY_EXISTS;
+#else
+    return mkdir(strPath.c_str(), 0700) == 0 || errno == EEXIST;
+#endif
+}
+
+static bool CopyFileLocal(const string& strSrc, const string& strDst)
+{
+    FILE* in = fopen(strSrc.c_str(), "rb");
+    if (!in)
+        return false;
+    FILE* out = fopen(strDst.c_str(), "wb");
+    if (!out)
+    {
+        fclose(in);
+        return false;
+    }
+
+    bool fOk = true;
+    char buf[65536];
+    size_t n = 0;
+    while ((n = fread(buf, 1, sizeof(buf), in)) > 0)
+    {
+        if (fwrite(buf, 1, n, out) != n)
+        {
+            fOk = false;
+            break;
+        }
+    }
+    if (ferror(in))
+        fOk = false;
+    if (fclose(out) != 0)
+        fOk = false;
+    fclose(in);
+    return fOk;
+}
+
+static bool DirectoryHasFileWithPrefix(const string& strDir, const string& strPrefix)
+{
+#ifdef _WIN32
+    WIN32_FIND_DATAA findData;
+    string pattern = strDir + "\\*";
+    HANDLE hFind = FindFirstFileA(pattern.c_str(), &findData);
+    if (hFind == INVALID_HANDLE_VALUE)
+        return false;
+    bool fFound = false;
+    do
+    {
+        if (!(findData.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY))
+        {
+            string name = findData.cFileName;
+            if (name.compare(0, strPrefix.size(), strPrefix) == 0)
+            {
+                fFound = true;
+                break;
+            }
+        }
+    }
+    while (FindNextFileA(hFind, &findData));
+    FindClose(hFind);
+    return fFound;
+#else
+    DIR* dir = opendir(strDir.c_str());
+    if (!dir)
+        return false;
+    bool fFound = false;
+    struct dirent* ent;
+    while ((ent = readdir(dir)) != NULL)
+    {
+        string name = ent->d_name;
+        if (name.compare(0, strPrefix.size(), strPrefix) == 0)
+        {
+            fFound = true;
+            break;
+        }
+    }
+    closedir(dir);
+    return fFound;
+#endif
+}
+
 static string QuoteCommandArg(const string& str)
 {
     string out = "\"";
@@ -907,7 +2047,8 @@ static string QuoteCommandArg(const string& str)
 
 static int RunBitflashChild(const string& strExe,
                             const vector<string>& vArgs,
-                            const string* pStdinFile = NULL)
+                            const string* pStdinFile = NULL,
+                            const string* pOutputFile = NULL)
 {
 #ifdef _WIN32
     vector<char*> argv;
@@ -920,8 +2061,16 @@ static int RunBitflashChild(const string& strExe,
     int nOldErr = _dup(2);
     int nOldIn = _dup(0);
     int nNull = _open("NUL", _O_WRONLY);
+    int nOut = -1;
     int nIn = -1;
-    if (nNull >= 0)
+    if (pOutputFile)
+        nOut = _open(pOutputFile->c_str(), _O_WRONLY|_O_CREAT|_O_TRUNC|_O_BINARY, _S_IREAD|_S_IWRITE);
+    if (nOut >= 0)
+    {
+        _dup2(nOut, 1);
+        _dup2(nOut, 2);
+    }
+    else if (nNull >= 0)
     {
         _dup2(nNull, 1);
         _dup2(nNull, 2);
@@ -935,6 +2084,8 @@ static int RunBitflashChild(const string& strExe,
     int nRet = _spawnv(_P_WAIT, strExe.c_str(), &argv[0]);
     if (nIn >= 0)
         _close(nIn);
+    if (nOut >= 0)
+        _close(nOut);
     if (nNull >= 0)
         _close(nNull);
     if (nOldIn >= 0)
@@ -959,8 +2110,17 @@ static int RunBitflashChild(const string& strExe,
         strCmd += " " + QuoteCommandArg(vArgs[i]);
     if (pStdinFile)
         strCmd += " < " + QuoteCommandArg(*pStdinFile);
-    strCmd += " > /dev/null 2>&1";
-    return system(strCmd.c_str());
+    if (pOutputFile)
+        strCmd += " > " + QuoteCommandArg(*pOutputFile) + " 2>&1";
+    else
+        strCmd += " > /dev/null 2>&1";
+    // system() returns a wait status, not the exit code; unwrap it so callers
+    // see the same value the Windows _spawnv path returns (e.g. exit code 2 is
+    // 2, not 512). Without this every "== 2" assertion fails only on Linux.
+    int nSysRet = system(strCmd.c_str());
+    if (nSysRet != -1 && WIFEXITED(nSysRet))
+        return WEXITSTATUS(nSysRet);
+    return nSysRet;
 #endif
 }
 
@@ -1001,6 +2161,13 @@ static int RunWalletEncryptSelfTest()
         TopUpKeyPool();
 
         vector<unsigned char> vchDefaultPubKey = keyUser.GetPubKey();
+        CKey publicLabelKey;
+        publicLabelKey.MakeNewKey();
+        string strPublicLabelAddress = PubKeyToAddress(publicLabelKey.GetPubKey());
+        nFail += Check(CWalletDB().WriteName(strPublicLabelAddress, "rewrite-public-name") &&
+                       CWalletDB().WriteSetting("rewrite-public-setting", (int64)424242),
+                       "public wallet records can be written before encryption") ? 0 : 1;
+
         CPrivKey vchDefaultPrivKey;
         nFail += Check(GetWalletPrivKey(vchDefaultPubKey, vchDefaultPrivKey, strError),
                        "the default private key is readable before encryption") ? 0 : 1;
@@ -1028,16 +2195,31 @@ static int RunWalletEncryptSelfTest()
 #else
         string strExe = cwd + "/bitflash-node";
 #endif
+        string strStorageAudit = tmp + "/encrypted-storage-audit.txt";
         string strWrongDump = tmp + "/wrong-pass-dump.txt";
         string strRightDump = tmp + "/right-pass-dump.txt";
         string strLiteralDump = tmp + "/literal-pass-dump.txt";
         string strStdinDump = tmp + "/stdin-pass-dump.txt";
+        string strLockedAudit = tmp + "/locked-recovery-audit.txt";
+        string strUnlockedAudit = tmp + "/unlocked-recovery-audit.txt";
         string strWrongPassFile = tmp + "/wrong-pass.txt";
         string strRightPassFile = tmp + "/right-pass.txt";
         nFail += Check(WriteTextFile(strWrongPassFile, "wrong-passphrase\n") &&
                        WriteTextFile(strRightPassFile, "btf-test-passphrase\n"),
                        "passphrase files can be written for restarted commands") ? 0 : 1;
 
+        vector<string> vStorageAuditArgs;
+        vStorageAuditArgs.push_back("-datadir=" + tmp);
+        vStorageAuditArgs.push_back("-walletstorageaudit");
+        vStorageAuditArgs.push_back("-nogui");
+        int nStorageAuditRet = RunBitflashChild(strExe, vStorageAuditArgs, NULL, &strStorageAudit);
+        nFail += Check(nStorageAuditRet == 0 &&
+                       FileContainsText(strStorageAudit, "address book labels:       3"),
+                       "the encrypted rewrite keeps address-book records") ? 0 : 1;
+        nFail += Check(nStorageAuditRet == 0 &&
+                       FileContainsText(strStorageAudit, "settings:                  1"),
+                       "the encrypted rewrite keeps wallet setting records") ? 0 : 1;
+
         vector<string> vWrongArgs;
         vWrongArgs.push_back("-datadir=" + tmp);
         vWrongArgs.push_back("-walletpassphrase=@" + strWrongPassFile);
@@ -1047,6 +2229,17 @@ static int RunWalletEncryptSelfTest()
         nFail += Check(nWrongRet != 0 && !FileExists(strWrongDump.c_str()),
                        "a restarted wallet rejects the wrong-passphrase") ? 0 : 1;
 
+        vector<string> vLockedAuditArgs;
+        vLockedAuditArgs.push_back("-datadir=" + tmp);
+        vLockedAuditArgs.push_back("-recoveryaudit");
+        vLockedAuditArgs.push_back("-nogui");
+        int nLockedAuditRet = RunBitflashChild(strExe, vLockedAuditArgs, NULL, &strLockedAudit);
+        nFail += Check(nLockedAuditRet == 2 &&
+                       FileContainsText(strLockedAudit, "recovery phrase: encrypted, unlock wallet to audit") &&
+                       FileContainsText(strLockedAudit, "recovery coverage:            unavailable while wallet is locked") &&
+                       FileContainsText(strLockedAudit, "Unlock the wallet with /walletpassphrase"),
+                       "a locked encrypted wallet reports that phrase coverage needs unlock") ? 0 : 1;
+
         vector<string> vLiteralArgs;
         vLiteralArgs.push_back("-datadir=" + tmp);
         vLiteralArgs.push_back("-walletpassphrase=btf-test-passphrase");
@@ -1067,6 +2260,17 @@ static int RunWalletEncryptSelfTest()
         nFail += Check(FileContainsText(strRightDump, HexStrLocal(vchDefaultPrivBytes)),
                        "the restarted wallet can decrypt and dump the original key") ? 0 : 1;
 
+        vector<string> vUnlockedAuditArgs;
+        vUnlockedAuditArgs.push_back("-datadir=" + tmp);
+        vUnlockedAuditArgs.push_back("-walletpassphrase=@" + strRightPassFile);
+        vUnlockedAuditArgs.push_back("-recoveryaudit");
+        vUnlockedAuditArgs.push_back("-nogui");
+        int nUnlockedAuditRet = RunBitflashChild(strExe, vUnlockedAuditArgs, NULL, &strUnlockedAudit);
+        nFail += Check(nUnlockedAuditRet == 0 &&
+                       FileContainsText(strUnlockedAudit, "recovery phrase: present") &&
+                       !FileContainsText(strUnlockedAudit, "recovery phrase: not installed"),
+                       "an unlocked encrypted wallet audits the installed recovery phrase") ? 0 : 1;
+
         vector<string> vStdinArgs;
         vStdinArgs.push_back("-datadir=" + tmp);
         vStdinArgs.push_back("-walletpassphrase");
@@ -1097,6 +2301,737 @@ static int RunWalletEncryptSelfTest()
     return nFail == 0 ? 0 : 1;
 }
 
+// Encrypting a wallet while it runs on the SQLite backend. Unlike the Berkeley
+// DB encrypt test above, this drives the real command-line path end to end in
+// child processes: build a Berkeley DB wallet, export it to SQLite, then run
+// -walletbackend=sqlite -encryptwallet and prove the SQLite wallet came out
+// encrypted, unlockable, and with wallet.dat left untouched.
+static int RunWalletSQLiteEncryptSelfTest()
+{
+    fflush(stdout);
+    printf("wallet-sqlite-encrypt self-test\n");
+
+    std::string tmp;
+    std::string cwd;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+    if (!GetCurrentDir(cwd) || !SetCurrentDir(tmp))
+    {
+        printf("  FAIL could not move into the temporary data directory\n");
+        RemoveTree(tmp);
+        return 1;
+    }
+
+    int nFail = 0;
+    strSetDataDir = tmp;
+    printf("  temp datadir: %s\n", tmp.c_str());
+
+    try
+    {
+        // Build a normal Berkeley DB wallet with a recovery phrase, a key pool,
+        // and a couple of public records, then release it. Everything after this
+        // runs the real command-line paths in child processes.
+        if (!LoadWallet())
+            throw std::runtime_error("LoadWallet failed");
+
+        string strError;
+        const string strMnemonic =
+            "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
+        nFail += Check(SetHDSeedFromMnemonic(strMnemonic, strError),
+                       "a phrase can be installed before encryption") ? 0 : 1;
+        TopUpKeyPool();
+
+        vector<unsigned char> vchDefaultPubKey = keyUser.GetPubKey();
+        CKey publicLabelKey;
+        publicLabelKey.MakeNewKey();
+        string strPublicLabelAddress = PubKeyToAddress(publicLabelKey.GetPubKey());
+        nFail += Check(CWalletDB().WriteName(strPublicLabelAddress, "rewrite-public-name") &&
+                       CWalletDB().WriteSetting("rewrite-public-setting", (int64)424242),
+                       "public wallet records can be written before encryption") ? 0 : 1;
+
+        CPrivKey vchDefaultPrivKey;
+        nFail += Check(GetWalletPrivKey(vchDefaultPubKey, vchDefaultPrivKey, strError),
+                       "the default private key is readable before encryption") ? 0 : 1;
+        vector<unsigned char> vchDefaultPrivBytes(vchDefaultPrivKey.begin(), vchDefaultPrivKey.end());
+        vector<unsigned char> vchPlainHDMaster = vchHDMaster;
+        vector<unsigned char> vchPlainHDChainCode = vchHDChainCode;
+
+        // Release wallet.dat so a child process can read it for the export.
+        DBFlush(true);
+
+#ifdef _WIN32
+        string strExe = cwd + "\\bitflash.exe";
+#else
+        string strExe = cwd + "/bitflash-node";
+#endif
+        string strSQLitePath = tmp + "/wallet.sqlite";
+        string strWalletDatPath = tmp + "/wallet.dat";
+        string strRightPassFile = tmp + "/right-pass.txt";
+        string strWrongPassFile = tmp + "/wrong-pass.txt";
+        nFail += Check(WriteTextFile(strRightPassFile, "btf-test-passphrase\n") &&
+                       WriteTextFile(strWrongPassFile, "wrong-passphrase\n"),
+                       "passphrase files can be written for restarted commands") ? 0 : 1;
+
+        // Step 1: export the Berkeley DB wallet to SQLite.
+        vector<string> vExportArgs;
+        vExportArgs.push_back("-datadir=" + tmp);
+        vExportArgs.push_back("-walletsqliteexport=" + strSQLitePath);
+        vExportArgs.push_back("-nogui");
+        int nExportRet = RunBitflashChild(strExe, vExportArgs);
+        nFail += Check(nExportRet == 0 && FileExists(strSQLitePath.c_str()),
+                       "the wallet exports to a SQLite file") ? 0 : 1;
+        nFail += Check(FileContainsBytes(strSQLitePath, vchDefaultPrivBytes),
+                       "the exported SQLite wallet holds the plaintext key before encryption") ? 0 : 1;
+
+        // Step 2: encrypt through the real SQLite backend command path.
+        string strEncryptOut = tmp + "/sqlite-encrypt-out.txt";
+        vector<string> vEncryptArgs;
+        vEncryptArgs.push_back("-datadir=" + tmp);
+        vEncryptArgs.push_back("-walletbackend=sqlite");
+        vEncryptArgs.push_back("-encryptwallet=@" + strRightPassFile);
+        vEncryptArgs.push_back("-nogui");
+        int nEncryptRet = RunBitflashChild(strExe, vEncryptArgs, NULL, &strEncryptOut);
+        nFail += Check(nEncryptRet == 0,
+                       "the SQLite wallet can be encrypted through -walletbackend=sqlite") ? 0 : 1;
+        nFail += Check(FileContainsText(strEncryptOut, "Wallet backend: SQLite"),
+                       "encryption took the SQLite persistence path") ? 0 : 1;
+        nFail += Check(FileContainsText(strEncryptOut, "wallet.sqlite.before-encrypt"),
+                       "the plaintext SQLite wallet is preserved as an explicit backup") ? 0 : 1;
+
+        // The encrypted SQLite wallet must no longer hold the plaintext secrets.
+        nFail += Check(!FileContainsBytes(strSQLitePath, vchDefaultPrivBytes),
+                       "the encrypted SQLite wallet no longer contains the default private key bytes") ? 0 : 1;
+        nFail += Check(!FileContainsBytes(strSQLitePath, vchPlainHDMaster),
+                       "the encrypted SQLite wallet no longer contains the HD master key bytes") ? 0 : 1;
+        nFail += Check(!FileContainsBytes(strSQLitePath, vchPlainHDChainCode),
+                       "the encrypted SQLite wallet no longer contains the HD chain-code bytes") ? 0 : 1;
+
+        // The Berkeley DB wallet.dat is a separate file: the SQLite encrypt path
+        // must never touch it, so its plaintext key is still exactly there.
+        nFail += Check(FileContainsBytes(strWalletDatPath, vchDefaultPrivBytes),
+                       "the original Berkeley DB wallet.dat is left untouched by the SQLite encrypt") ? 0 : 1;
+
+        // Step 3: a locked encrypted SQLite wallet reports that phrase coverage
+        // needs an unlock, exactly as the Berkeley DB path does (exit code 2).
+        string strLockedAudit = tmp + "/locked-recovery-audit.txt";
+        vector<string> vLockedArgs;
+        vLockedArgs.push_back("-datadir=" + tmp);
+        vLockedArgs.push_back("-walletbackend=sqlite");
+        vLockedArgs.push_back("-recoveryaudit");
+        vLockedArgs.push_back("-nogui");
+        int nLockedRet = RunBitflashChild(strExe, vLockedArgs, NULL, &strLockedAudit);
+        nFail += Check(nLockedRet == 2 &&
+                       FileContainsText(strLockedAudit, "recovery phrase: encrypted, unlock wallet to audit"),
+                       "a locked encrypted SQLite wallet reports that phrase coverage needs unlock") ? 0 : 1;
+
+        // The wrong passphrase is rejected and reveals nothing.
+        string strWrongDump = tmp + "/wrong-dump.txt";
+        vector<string> vWrongArgs;
+        vWrongArgs.push_back("-datadir=" + tmp);
+        vWrongArgs.push_back("-walletbackend=sqlite");
+        vWrongArgs.push_back("-walletpassphrase=@" + strWrongPassFile);
+        vWrongArgs.push_back("-dumpwallet=" + strWrongDump);
+        vWrongArgs.push_back("-nogui");
+        int nWrongRet = RunBitflashChild(strExe, vWrongArgs);
+        nFail += Check(nWrongRet != 0 && !FileExists(strWrongDump.c_str()),
+                       "a restarted SQLite wallet rejects the wrong passphrase") ? 0 : 1;
+
+        // The right passphrase unlocks and can dump the original key.
+        string strRightDump = tmp + "/right-dump.txt";
+        vector<string> vRightArgs;
+        vRightArgs.push_back("-datadir=" + tmp);
+        vRightArgs.push_back("-walletbackend=sqlite");
+        vRightArgs.push_back("-walletpassphrase=@" + strRightPassFile);
+        vRightArgs.push_back("-dumpwallet=" + strRightDump);
+        vRightArgs.push_back("-nogui");
+        int nRightRet = RunBitflashChild(strExe, vRightArgs);
+        nFail += Check(nRightRet == 0 && FileExists(strRightDump.c_str()),
+                       "a restarted SQLite wallet unlocks with the right passphrase") ? 0 : 1;
+        nFail += Check(FileContainsText(strRightDump, HexStrLocal(vchDefaultPrivBytes)),
+                       "the unlocked SQLite wallet decrypts and dumps the original key") ? 0 : 1;
+
+        // The recovery phrase survives the encryption.
+        string strAudit = tmp + "/recovery-audit.txt";
+        vector<string> vAuditArgs;
+        vAuditArgs.push_back("-datadir=" + tmp);
+        vAuditArgs.push_back("-walletbackend=sqlite");
+        vAuditArgs.push_back("-walletpassphrase=@" + strRightPassFile);
+        vAuditArgs.push_back("-recoveryaudit");
+        vAuditArgs.push_back("-nogui");
+        int nAuditRet = RunBitflashChild(strExe, vAuditArgs, NULL, &strAudit);
+        nFail += Check(nAuditRet == 0 &&
+                       FileContainsText(strAudit, "recovery phrase: present"),
+                       "the encrypted SQLite wallet still has its recovery phrase") ? 0 : 1;
+
+        // One-shot storage commands honour -walletbackend. The SQLite wallet is
+        // encrypted; the wallet.dat beside it is still plaintext. Same datadir,
+        // opposite answers -> the flag routes the diagnostic to the right file.
+        string strSqliteAuditJson = tmp + "/sqlite-audit.json";
+        vector<string> vSqliteAuditArgs;
+        vSqliteAuditArgs.push_back("-datadir=" + tmp);
+        vSqliteAuditArgs.push_back("-walletbackend=sqlite");
+        vSqliteAuditArgs.push_back("-walletstorageauditjson=" + strSqliteAuditJson);
+        vSqliteAuditArgs.push_back("-nogui");
+        int nSqliteAuditRet = RunBitflashChild(strExe, vSqliteAuditArgs);
+        nFail += Check(nSqliteAuditRet == 0 &&
+                       FileContainsText(strSqliteAuditJson, "\"encrypted_hd_seed\": \"complete\"") &&
+                       FileContainsText(strSqliteAuditJson, "\"plain_hd_seed\": \"none\""),
+                       "-walletstorageaudit under SQLite reads the encrypted wallet.sqlite") ? 0 : 1;
+
+        string strBdbAuditJson = tmp + "/bdb-audit.json";
+        vector<string> vBdbAuditArgs;
+        vBdbAuditArgs.push_back("-datadir=" + tmp);
+        vBdbAuditArgs.push_back("-walletstorageauditjson=" + strBdbAuditJson);
+        vBdbAuditArgs.push_back("-nogui");
+        int nBdbAuditRet = RunBitflashChild(strExe, vBdbAuditArgs);
+        nFail += Check(nBdbAuditRet == 0 &&
+                       FileContainsText(strBdbAuditJson, "\"plain_hd_seed\": \"complete\"") &&
+                       FileContainsText(strBdbAuditJson, "\"encrypted_hd_seed\": \"none\""),
+                       "-walletstorageaudit without the flag still reads the plaintext wallet.dat") ? 0 : 1;
+
+        string strSqliteCheckOut = tmp + "/sqlite-check.txt";
+        vector<string> vSqliteCheckArgs;
+        vSqliteCheckArgs.push_back("-datadir=" + tmp);
+        vSqliteCheckArgs.push_back("-walletbackend=sqlite");
+        vSqliteCheckArgs.push_back("-walletstoragecheck");
+        vSqliteCheckArgs.push_back("-nogui");
+        int nSqliteCheckRet = RunBitflashChild(strExe, vSqliteCheckArgs, NULL, &strSqliteCheckOut);
+        nFail += Check(nSqliteCheckRet == 0,
+                       "-walletstoragecheck under SQLite passes on the encrypted wallet.sqlite") ? 0 : 1;
+
+        // Backup under SQLite copies wallet.sqlite, not the plaintext wallet.dat.
+        // The copy is a standalone SQLite wallet (loadcheck accepts it) and holds
+        // none of the plaintext key that wallet.dat still contains.
+        string strBackupDest = tmp + "/backup.sqlite";
+        vector<string> vBackupArgs;
+        vBackupArgs.push_back("-datadir=" + tmp);
+        vBackupArgs.push_back("-walletbackend=sqlite");
+        vBackupArgs.push_back("-backupwallet=" + strBackupDest);
+        vBackupArgs.push_back("-nogui");
+        int nBackupRet = RunBitflashChild(strExe, vBackupArgs);
+        nFail += Check(nBackupRet == 0 && FileExists(strBackupDest.c_str()),
+                       "-backupwallet under SQLite writes a backup file") ? 0 : 1;
+        nFail += Check(!FileContainsBytes(strBackupDest, vchDefaultPrivBytes),
+                       "the SQLite backup holds no plaintext key (it copied wallet.sqlite, not wallet.dat)") ? 0 : 1;
+
+        string strBackupLoadCheck = tmp + "/backup-loadcheck.txt";
+        vector<string> vLoadCheckArgs;
+        vLoadCheckArgs.push_back("-datadir=" + tmp);
+        vLoadCheckArgs.push_back("-walletsqliteloadcheck=" + strBackupDest);
+        vLoadCheckArgs.push_back("-nogui");
+        int nBackupLoadRet = RunBitflashChild(strExe, vLoadCheckArgs, NULL, &strBackupLoadCheck);
+        nFail += Check(nBackupLoadRet == 0,
+                       "the SQLite backup is a valid standalone SQLite wallet") ? 0 : 1;
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    DBFlush(true);
+    SetCurrentDir(cwd);
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+// Backend resolution when no -walletbackend flag is given: a fresh install
+// starts on SQLite (the new default), an existing wallet.dat stays on Berkeley
+// DB, the persistent marker overrides the default, and an explicit flag
+// overrides everything. Each scenario runs a real child process.
+static int RunWalletBackendDefaultSelfTest()
+{
+    fflush(stdout);
+    printf("wallet-backend-default self-test\n");
+
+    std::string tmp, cwd;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+    if (!GetCurrentDir(cwd) || !SetCurrentDir(tmp))
+    {
+        printf("  FAIL could not move into the temporary data directory\n");
+        RemoveTree(tmp);
+        return 1;
+    }
+
+    int nFail = 0;
+    strSetDataDir = tmp;
+    printf("  temp datadir: %s\n", tmp.c_str());
+
+#ifdef _WIN32
+    string strExe = cwd + "\\bitflash.exe";
+#else
+    string strExe = cwd + "/bitflash-node";
+#endif
+
+    try
+    {
+        // 1. Fresh datadir, no flag -> this fork refuses, where upstream creates.
+        //    An empty datadir on a headless node is far more often a mount or
+        //    backup fault than a first run, and creating a wallet also pins the
+        //    backend marker, after which restoring the real wallet is a no-op.
+        //    Nothing may be left behind: no wallet of either kind, no marker.
+        string d1 = tmp + "/fresh";
+        nFail += Check(MakeDirLocal(d1), "fresh scenario dir can be created") ? 0 : 1;
+        vector<string> a1;
+        a1.push_back("-datadir=" + d1);
+        a1.push_back("-nomanagedtor");
+        a1.push_back("-nogui");
+        a1.push_back("-newaddress");
+        int r0 = RunBitflashChild(strExe, a1);
+        nFail += Check(r0 != 0 &&
+                       !FileExists((d1 + "/wallet.sqlite").c_str()) &&
+                       !FileExists((d1 + "/wallet.dat").c_str()) &&
+                       !FileExists((d1 + "/wallet-backend").c_str()),
+                       "a flagless headless start refuses to create a wallet") ? 0 : 1;
+
+        // 1a. -createwallet says it was meant: new wallet.sqlite, marker
+        //     "sqlite", no wallet.dat.
+        vector<string> a1c = a1;
+        a1c.push_back("-createwallet");
+        int r1 = RunBitflashChild(strExe, a1c);
+        nFail += Check(r1 == 0 &&
+                       FileExists((d1 + "/wallet.sqlite").c_str()) &&
+                       !FileExists((d1 + "/wallet.dat").c_str()) &&
+                       FileContainsText(d1 + "/wallet-backend", "sqlite"),
+                       "-createwallet starts a fresh install on SQLite and records the marker") ? 0 : 1;
+
+        // 1b. Second run reuses it without the flag -- the refusal only guards
+        //     creation, so an existing wallet still starts flagless.
+        int r1b = RunBitflashChild(strExe, a1);
+        nFail += Check(r1b == 0 &&
+                       FileExists((d1 + "/wallet.sqlite").c_str()) &&
+                       !FileExists((d1 + "/wallet.dat").c_str()),
+                       "the recorded SQLite choice survives a flagless restart") ? 0 : 1;
+
+        // 2. Existing wallet.dat, no flag -> stays on Berkeley DB.
+        string d2 = tmp + "/existing-bdb";
+        nFail += Check(MakeDirLocal(d2), "existing-bdb scenario dir can be created") ? 0 : 1;
+        vector<string> a2c;
+        a2c.push_back("-datadir=" + d2);
+        a2c.push_back("-nomanagedtor");
+        a2c.push_back("-nogui");
+        a2c.push_back("-walletbackend=bdb");
+        a2c.push_back("-newphrase");
+        RunBitflashChild(strExe, a2c);
+        vector<string> a2;
+        a2.push_back("-datadir=" + d2);
+        a2.push_back("-nomanagedtor");
+        a2.push_back("-nogui");
+        a2.push_back("-newaddress");
+        int r2 = RunBitflashChild(strExe, a2);
+        nFail += Check(r2 == 0 &&
+                       FileExists((d2 + "/wallet.dat").c_str()) &&
+                       !FileExists((d2 + "/wallet.sqlite").c_str()),
+                       "an existing wallet.dat keeps a flagless start on Berkeley DB") ? 0 : 1;
+
+        // 3. Marker "bdb" forces Berkeley DB even on a fresh datadir.
+        string d3 = tmp + "/marker-bdb";
+        nFail += Check(MakeDirLocal(d3), "marker-bdb scenario dir can be created") ? 0 : 1;
+        nFail += Check(WriteTextFile(d3 + "/wallet-backend", "bdb\n"),
+                       "a bdb marker can be written") ? 0 : 1;
+        vector<string> a3;
+        a3.push_back("-datadir=" + d3);
+        a3.push_back("-nomanagedtor");
+        a3.push_back("-nogui");
+        a3.push_back("-newaddress");
+        int r3 = RunBitflashChild(strExe, a3);
+        nFail += Check(r3 == 0 &&
+                       FileExists((d3 + "/wallet.dat").c_str()) &&
+                       !FileExists((d3 + "/wallet.sqlite").c_str()),
+                       "a bdb marker forces Berkeley DB on a fresh datadir") ? 0 : 1;
+
+        // 4. Explicit -walletbackend=bdb on a fresh datadir -> wallet.dat.
+        string d4 = tmp + "/explicit-bdb";
+        nFail += Check(MakeDirLocal(d4), "explicit-bdb scenario dir can be created") ? 0 : 1;
+        vector<string> a4;
+        a4.push_back("-datadir=" + d4);
+        a4.push_back("-nomanagedtor");
+        a4.push_back("-nogui");
+        a4.push_back("-walletbackend=bdb");
+        a4.push_back("-newaddress");
+        int r4 = RunBitflashChild(strExe, a4);
+        nFail += Check(r4 == 0 &&
+                       FileExists((d4 + "/wallet.dat").c_str()) &&
+                       !FileExists((d4 + "/wallet.sqlite").c_str()),
+                       "an explicit -walletbackend=bdb creates wallet.dat on a fresh datadir") ? 0 : 1;
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    DBFlush(true);
+    SetCurrentDir(cwd);
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+// The wizard's conversion action, headless: build a Berkeley DB wallet, run
+// DoConvertWalletToSQLite() (what the GUI button calls), and prove it produced a
+// usable wallet.sqlite + backend marker while leaving wallet.dat untouched, then
+// that a flagless restart opens the converted SQLite wallet.
+static int RunWalletConvertSelfTest()
+{
+    fflush(stdout);
+    printf("wallet-convert self-test\n");
+
+    std::string tmp, cwd;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+    if (!GetCurrentDir(cwd) || !SetCurrentDir(tmp))
+    {
+        printf("  FAIL could not move into the temporary data directory\n");
+        RemoveTree(tmp);
+        return 1;
+    }
+
+    int nFail = 0;
+    strSetDataDir = tmp;
+    printf("  temp datadir: %s\n", tmp.c_str());
+
+#ifdef _WIN32
+    string strExe = cwd + "\\bitflash.exe";
+#else
+    string strExe = cwd + "/bitflash-node";
+#endif
+
+    try
+    {
+        if (!LoadWallet())
+            throw std::runtime_error("LoadWallet failed");
+
+        string strError;
+        nFail += Check(SetHDSeedFromMnemonic(
+                           "abandon abandon abandon abandon abandon abandon abandon "
+                           "abandon abandon abandon abandon about", strError),
+                       "a phrase can be installed before conversion") ? 0 : 1;
+        TopUpKeyPool();
+
+        vector<unsigned char> vchDefaultPubKey = keyUser.GetPubKey();
+        CPrivKey vchDefaultPrivKey;
+        nFail += Check(GetWalletPrivKey(vchDefaultPubKey, vchDefaultPrivKey, strError),
+                       "the default private key is readable before conversion") ? 0 : 1;
+        vector<unsigned char> vchDefaultPrivBytes(vchDefaultPrivKey.begin(),
+                                                  vchDefaultPrivKey.end());
+
+        // The conversion action the GUI button invokes.
+        int nCopied = 0;
+        string strConvertError;
+        bool fConverted = DoConvertWalletToSQLite(nCopied, strConvertError);
+        nFail += Check(fConverted && nCopied > 0,
+                       "DoConvertWalletToSQLite exports the wallet") ? 0 : 1;
+        nFail += Check(FileExists((tmp + "/wallet.sqlite").c_str()) &&
+                       FileContainsText(tmp + "/wallet-backend", "sqlite"),
+                       "conversion writes wallet.sqlite and records the sqlite marker") ? 0 : 1;
+        nFail += Check(FileContainsBytes(tmp + "/wallet.dat", vchDefaultPrivBytes),
+                       "wallet.dat is left untouched by the conversion") ? 0 : 1;
+
+        // Idempotence guard: a second conversion refuses rather than overwrite.
+        int nCopied2 = 0;
+        string strSecondError;
+        nFail += Check(!DoConvertWalletToSQLite(nCopied2, strSecondError),
+                       "a second conversion refuses to overwrite wallet.sqlite") ? 0 : 1;
+
+        DBFlush(true);
+
+        // A flagless restart now opens the converted SQLite wallet (the marker
+        // routes it) and finds the same recovery phrase.
+        string strAudit = tmp + "/converted-recovery-audit.txt";
+        vector<string> vAuditArgs;
+        vAuditArgs.push_back("-datadir=" + tmp);
+        vAuditArgs.push_back("-nomanagedtor");
+        vAuditArgs.push_back("-nogui");
+        vAuditArgs.push_back("-recoveryaudit");
+        int nAuditRet = RunBitflashChild(strExe, vAuditArgs, NULL, &strAudit);
+        nFail += Check(nAuditRet == 0 &&
+                       FileContainsText(strAudit, "recovery phrase: present"),
+                       "a flagless restart opens the converted SQLite wallet") ? 0 : 1;
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    DBFlush(true);
+    SetCurrentDir(cwd);
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+static int RunWalletPortabilitySelfTest()
+{
+    fflush(stdout);
+    printf("wallet-portability self-test\n");
+
+    std::string tmp;
+    std::string cwd;
+    if (!MakeTempDir(tmp))
+    {
+        printf("  FAIL could not create a temporary data directory\n");
+        return 1;
+    }
+    if (!GetCurrentDir(cwd))
+    {
+        printf("  FAIL could not read current directory\n");
+        RemoveTree(tmp);
+        return 1;
+    }
+
+    int nFail = 0;
+    printf("  temp root: %s\n", tmp.c_str());
+
+    try
+    {
+#ifdef _WIN32
+        string strExe = cwd + "\\bitflash.exe";
+#else
+        string strExe = cwd + "/bitflash-node";
+#endif
+        string strOriginal = tmp + "/original";
+        string strRawCopy = tmp + "/raw-copy";
+        string strBackupCopy = tmp + "/backup-copy";
+        nFail += Check(MakeDirLocal(strOriginal) &&
+                       MakeDirLocal(strRawCopy) &&
+                       MakeDirLocal(strBackupCopy),
+                       "temporary wallet directories can be created") ? 0 : 1;
+
+        string strCreateOut = tmp + "/create.txt";
+        vector<string> vCreateArgs;
+        vCreateArgs.push_back("-datadir=" + strOriginal);
+        vCreateArgs.push_back("-nomanagedtor");
+        vCreateArgs.push_back("-nogui");
+        vCreateArgs.push_back("-walletbackend=bdb");   // this suite is about wallet.dat portability
+        vCreateArgs.push_back("-newphrase");
+        int nCreateRet = RunBitflashChild(strExe, vCreateArgs, NULL, &strCreateOut);
+        nFail += Check(nCreateRet == 0 &&
+                       FileContainsText(strCreateOut, "Write these twelve words down"),
+                       "a phrase wallet can be created in a fresh datadir") ? 0 : 1;
+
+        string strOriginalAudit = tmp + "/original-audit.txt";
+        vector<string> vOriginalAuditArgs;
+        vOriginalAuditArgs.push_back("-datadir=" + strOriginal);
+        vOriginalAuditArgs.push_back("-nomanagedtor");
+        vOriginalAuditArgs.push_back("-nogui");
+        vOriginalAuditArgs.push_back("-recoveryaudit");
+        int nOriginalAuditRet = RunBitflashChild(strExe, vOriginalAuditArgs, NULL, &strOriginalAudit);
+        nFail += Check(nOriginalAuditRet == 0 &&
+                       FileContainsText(strOriginalAudit, "recovery phrase: present") &&
+                       FileContainsText(strOriginalAudit, "SLIP-0044 BITFLASH"),
+                       "the original wallet reports its recovery phrase") ? 0 : 1;
+
+        string strOriginalStorageAudit = tmp + "/original-storage-audit.txt";
+        vector<string> vOriginalStorageAuditArgs;
+        vOriginalStorageAuditArgs.push_back("-datadir=" + strOriginal);
+        vOriginalStorageAuditArgs.push_back("-nomanagedtor");
+        vOriginalStorageAuditArgs.push_back("-nogui");
+        vOriginalStorageAuditArgs.push_back("-walletstorageaudit");
+        int nOriginalStorageAuditRet =
+            RunBitflashChild(strExe, vOriginalStorageAuditArgs, NULL, &strOriginalStorageAudit);
+        nFail += Check(nOriginalStorageAuditRet == 0 &&
+                       FileContainsText(strOriginalStorageAudit, "Wallet storage audit") &&
+                       FileContainsText(strOriginalStorageAudit, "plain HD seed:             complete") &&
+                       FileContainsText(strOriginalStorageAudit, "encrypted HD seed:         none") &&
+                       FileContainsText(strOriginalStorageAudit, "malformed records:         0"),
+                       "the storage audit recognizes a plaintext phrase wallet") ? 0 : 1;
+
+        string strOriginalStorageCheck = tmp + "/original-storage-check.txt";
+        vector<string> vOriginalStorageCheckArgs;
+        vOriginalStorageCheckArgs.push_back("-datadir=" + strOriginal);
+        vOriginalStorageCheckArgs.push_back("-nomanagedtor");
+        vOriginalStorageCheckArgs.push_back("-nogui");
+        vOriginalStorageCheckArgs.push_back("-walletstoragecheck");
+        int nOriginalStorageCheckRet =
+            RunBitflashChild(strExe, vOriginalStorageCheckArgs, NULL, &strOriginalStorageCheck);
+        nFail += Check(nOriginalStorageCheckRet == 0 &&
+                       FileContainsText(strOriginalStorageCheck, "storage sanity:            ok") &&
+                       FileContainsText(strOriginalStorageCheck, "plain HD seed:             complete"),
+                       "the storage sanity check accepts a plaintext phrase wallet") ? 0 : 1;
+
+        string strOriginalStorageAuditJson = tmp + "/original-storage-audit.json";
+        vector<string> vOriginalStorageAuditJsonArgs;
+        vOriginalStorageAuditJsonArgs.push_back("-datadir=" + strOriginal);
+        vOriginalStorageAuditJsonArgs.push_back("-nomanagedtor");
+        vOriginalStorageAuditJsonArgs.push_back("-nogui");
+        vOriginalStorageAuditJsonArgs.push_back("-walletstorageauditjson=" +
+                                                strOriginalStorageAuditJson);
+        int nOriginalStorageAuditJsonRet =
+            RunBitflashChild(strExe, vOriginalStorageAuditJsonArgs);
+        nFail += Check(nOriginalStorageAuditJsonRet == 0 &&
+                       FileContainsText(strOriginalStorageAuditJson,
+                                        "\"format\": \"bitflash-wallet-storage-audit-v1\"") &&
+                       FileContainsText(strOriginalStorageAuditJson,
+                                        "\"plain_hd_seed\": \"complete\"") &&
+                       FileContainsText(strOriginalStorageAuditJson,
+                                        "\"encrypted_hd_seed\": \"none\""),
+                       "the storage audit can write plaintext-wallet JSON") ? 0 : 1;
+
+        string strPortableWallet = tmp + "/portable-wallet.dat";
+        string strBackupOut = tmp + "/backupwallet.txt";
+        vector<string> vBackupArgs;
+        vBackupArgs.push_back("-datadir=" + strOriginal);
+        vBackupArgs.push_back("-nomanagedtor");
+        vBackupArgs.push_back("-nogui");
+        vBackupArgs.push_back("-backupwallet=" + strPortableWallet);
+        int nBackupRet = RunBitflashChild(strExe, vBackupArgs, NULL, &strBackupOut);
+        nFail += Check(nBackupRet == 0 && FileExists(strPortableWallet.c_str()),
+                       "/backupwallet writes a portable wallet.dat") ? 0 : 1;
+
+        string strBackupOut2 = tmp + "/backupwallet-overwrite.txt";
+        int nBackupRet2 = RunBitflashChild(strExe, vBackupArgs, NULL, &strBackupOut2);
+        nFail += Check(nBackupRet2 == 0 && FileExists(strPortableWallet.c_str()) &&
+                       !DirectoryHasFileWithPrefix(tmp, "portable-wallet.dat.tmp.") &&
+                       !DirectoryHasFileWithPrefix(tmp, "portable-wallet.dat.old."),
+                       "/backupwallet replaces an existing backup without leaving temp files") ? 0 : 1;
+
+        nFail += Check(CopyFileLocal(strOriginal + "/wallet.dat",
+                                     strRawCopy + "/wallet.dat"),
+                       "a raw wallet.dat can be copied without database logs") ? 0 : 1;
+        string strRawAudit = tmp + "/raw-copy-audit.txt";
+        vector<string> vRawAuditArgs;
+        vRawAuditArgs.push_back("-datadir=" + strRawCopy);
+        vRawAuditArgs.push_back("-nomanagedtor");
+        vRawAuditArgs.push_back("-nogui");
+        vRawAuditArgs.push_back("-recoveryaudit");
+        int nRawAuditRet = RunBitflashChild(strExe, vRawAuditArgs, NULL, &strRawAudit);
+        nFail += Check(nRawAuditRet == 0 &&
+                       FileContainsText(strRawAudit, "recovery phrase: present") &&
+                       !FileContainsText(strRawAudit, "Cannot open wallet.dat"),
+                       "a raw wallet.dat copy opens in a new datadir") ? 0 : 1;
+
+        nFail += Check(CopyFileLocal(strPortableWallet,
+                                     strBackupCopy + "/wallet.dat"),
+                       "the portable backup can be installed as wallet.dat") ? 0 : 1;
+        string strBackupAudit = tmp + "/backup-copy-audit.txt";
+        vector<string> vBackupAuditArgs;
+        vBackupAuditArgs.push_back("-datadir=" + strBackupCopy);
+        vBackupAuditArgs.push_back("-nomanagedtor");
+        vBackupAuditArgs.push_back("-nogui");
+        vBackupAuditArgs.push_back("-recoveryaudit");
+        int nBackupAuditRet = RunBitflashChild(strExe, vBackupAuditArgs, NULL, &strBackupAudit);
+        nFail += Check(nBackupAuditRet == 0 &&
+                       FileContainsText(strBackupAudit, "recovery phrase: present") &&
+                       FileContainsText(strBackupAudit, "SLIP-0044 BITFLASH"),
+                       "a /backupwallet copy opens in a new datadir") ? 0 : 1;
+
+        string strPassFile = tmp + "/encrypt-pass.txt";
+        string strEncryptOut = tmp + "/encryptwallet.txt";
+        nFail += Check(WriteTextFile(strPassFile, "portable-test-passphrase\n"),
+                       "an encryption passphrase file can be written") ? 0 : 1;
+        vector<string> vEncryptArgs;
+        vEncryptArgs.push_back("-datadir=" + strOriginal);
+        vEncryptArgs.push_back("-nomanagedtor");
+        vEncryptArgs.push_back("-nogui");
+        vEncryptArgs.push_back("-encryptwallet=@" + strPassFile);
+        int nEncryptRet = RunBitflashChild(strExe, vEncryptArgs, NULL, &strEncryptOut);
+        nFail += Check(nEncryptRet == 0 &&
+                       !DirectoryHasFileWithPrefix(strOriginal + "/database", "log."),
+                       "the encryptwallet command purges Berkeley DB environment logs") ? 0 : 1;
+
+        string strEncryptedStorageAudit = tmp + "/encrypted-storage-audit.txt";
+        vector<string> vEncryptedStorageAuditArgs;
+        vEncryptedStorageAuditArgs.push_back("-datadir=" + strOriginal);
+        vEncryptedStorageAuditArgs.push_back("-nomanagedtor");
+        vEncryptedStorageAuditArgs.push_back("-nogui");
+        vEncryptedStorageAuditArgs.push_back("-walletstorageaudit");
+        int nEncryptedStorageAuditRet =
+            RunBitflashChild(strExe, vEncryptedStorageAuditArgs, NULL, &strEncryptedStorageAudit);
+        nFail += Check(nEncryptedStorageAuditRet == 0 &&
+                       FileContainsText(strEncryptedStorageAudit, "plain private keys:        0") &&
+                       FileContainsText(strEncryptedStorageAudit, "encrypted private keys:") &&
+                       FileContainsText(strEncryptedStorageAudit, "plain HD seed:             none") &&
+                       FileContainsText(strEncryptedStorageAudit, "encrypted HD seed:         complete") &&
+                       FileContainsText(strEncryptedStorageAudit, "wallet minimum version:    present") &&
+                       FileContainsText(strEncryptedStorageAudit, "malformed records:         0"),
+                       "the storage audit recognizes an encrypted wallet") ? 0 : 1;
+
+        string strEncryptedStorageCheck = tmp + "/encrypted-storage-check.txt";
+        vector<string> vEncryptedStorageCheckArgs;
+        vEncryptedStorageCheckArgs.push_back("-datadir=" + strOriginal);
+        vEncryptedStorageCheckArgs.push_back("-nomanagedtor");
+        vEncryptedStorageCheckArgs.push_back("-nogui");
+        vEncryptedStorageCheckArgs.push_back("-walletstoragecheck");
+        int nEncryptedStorageCheckRet =
+            RunBitflashChild(strExe, vEncryptedStorageCheckArgs, NULL, &strEncryptedStorageCheck);
+        nFail += Check(nEncryptedStorageCheckRet == 0 &&
+                       FileContainsText(strEncryptedStorageCheck, "storage sanity:            ok") &&
+                       FileContainsText(strEncryptedStorageCheck, "plain private keys:        0") &&
+                       FileContainsText(strEncryptedStorageCheck, "encrypted HD seed:         complete"),
+                       "the storage sanity check accepts an encrypted wallet") ? 0 : 1;
+
+        string strEncryptedStorageAuditJson = tmp + "/encrypted-storage-audit.json";
+        vector<string> vEncryptedStorageAuditJsonArgs;
+        vEncryptedStorageAuditJsonArgs.push_back("-datadir=" + strOriginal);
+        vEncryptedStorageAuditJsonArgs.push_back("-nomanagedtor");
+        vEncryptedStorageAuditJsonArgs.push_back("-nogui");
+        vEncryptedStorageAuditJsonArgs.push_back("-walletstorageauditjson=" +
+                                                 strEncryptedStorageAuditJson);
+        int nEncryptedStorageAuditJsonRet =
+            RunBitflashChild(strExe, vEncryptedStorageAuditJsonArgs);
+        nFail += Check(nEncryptedStorageAuditJsonRet == 0 &&
+                       FileContainsText(strEncryptedStorageAuditJson,
+                                        "\"plain_private_keys\": 0") &&
+                       FileContainsText(strEncryptedStorageAuditJson,
+                                        "\"plain_hd_seed\": \"none\"") &&
+                       FileContainsText(strEncryptedStorageAuditJson,
+                                        "\"encrypted_hd_seed\": \"complete\"") &&
+                       FileContainsText(strEncryptedStorageAuditJson,
+                                        "\"wallet_minimum_version\": \"present\""),
+                       "the storage audit can write encrypted-wallet JSON") ? 0 : 1;
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    RemoveTree(tmp);
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
 static int RunNetMessageSelfTest()
 {
     fflush(stdout);
@@ -1105,6 +3040,13 @@ static int RunNetMessageSelfTest()
     int nFail = 0;
     try
     {
+        // A peer that has not yet been kept waiting must not look like one that
+        // has been waiting since the epoch. This is the whole bug: the stall
+        // clock lives in CNode, so only the constructor can start it at zero.
+        CNode opened(INVALID_SOCKET, CAddress("127.0.0.1"));
+        nFail += Check(opened.nMsgWaitSince == 0 && opened.nMsgWaitSize == 0,
+                       "a new peer starts with its stall clock stopped") ? 0 : 1;
+
         CNode complete(INVALID_SOCKET, CAddress("127.0.0.1"));
         complete.nVersion = VERSION;
         complete.vRecv << CMessageHeader("ping", 0);
@@ -1119,20 +3061,38 @@ static int RunNetMessageSelfTest()
         nFail += Check(ProcessMessages(&partial), "an incomplete message returns cleanly") ? 0 : 1;
         nFail += Check(partial.vRecv.size() == nPartialBefore,
                        "an incomplete message keeps one header in the buffer") ? 0 : 1;
-        nFail += Check(partial.nIncompleteMessageStart != 0,
-                       "an incomplete message starts a timeout clock") ? 0 : 1;
+        nFail += Check(partial.nMsgWaitSince != 0,
+                       "an incomplete message starts the stall clock") ? 0 : 1;
+        nFail += Check(partial.nMsgWaitSize == 0,
+                       "the stall clock records how much payload had arrived") ? 0 : 1;
         nFail += Check(!partial.fDisconnect,
                        "a fresh incomplete message does not disconnect immediately") ? 0 : 1;
 
+        // Still arriving, just slowly: more payload is here than when the clock
+        // was started, so the clock restarts however old it was. Timing the
+        // wait instead of the stall would drop this peer.
+        CNode slow(INVALID_SOCKET, CAddress("127.0.0.1"));
+        slow.nVersion = VERSION;
+        slow.vRecv << CMessageHeader("block", 100);
+        slow.vRecv.insert(slow.vRecv.end(), 50, '\0');
+        slow.nMsgWaitSince = GetTime() - BTF_MSG_WAIT_MAX_SECS - 1;
+        slow.nMsgWaitSize = 10;
+        ProcessMessages(&slow);
+        nFail += Check(!slow.fDisconnect,
+                       "a peer still sending payload is not dropped") ? 0 : 1;
+        nFail += Check(slow.nMsgWaitSize == 50,
+                       "progress restarts the stall clock") ? 0 : 1;
+
+        // Nothing more has arrived since the clock started, and the clock is
+        // older than the limit.
         CNode stale(INVALID_SOCKET, CAddress("127.0.0.1"));
         stale.nVersion = VERSION;
         stale.vRecv << CMessageHeader("block", 100);
-        stale.nIncompleteMessageStart = GetTime() - BTF_INCOMPLETE_MESSAGE_TIMEOUT_SECS - 1;
-        stale.nIncompleteMessageSize = 100;
-        stale.strIncompleteMessageCommand = "block";
+        stale.nMsgWaitSince = GetTime() - BTF_MSG_WAIT_MAX_SECS - 1;
+        stale.nMsgWaitSize = 0;
         ProcessMessages(&stale);
         nFail += Check(stale.fDisconnect,
-                       "a stale incomplete message disconnects the peer") ? 0 : 1;
+                       "a stalled incomplete message disconnects the peer") ? 0 : 1;
 
         CNode oversized(INVALID_SOCKET, CAddress("127.0.0.1"));
         oversized.nVersion = VERSION;
@@ -1158,6 +3118,87 @@ static int RunNetMessageSelfTest()
     return nFail == 0 ? 0 : 1;
 }
 
+static int RunNetworkParamsSelfTest()
+{
+    fflush(stdout);
+    printf("network-params self-test\n");
+
+    int nFail = 0;
+    std::string strOldDataDir = strSetDataDir;
+    try
+    {
+        SelectChainParams(false);
+        nFail += Check(!IsTestNet(), "starts on mainnet after explicit selection") ? 0 : 1;
+        nFail += Check(ntohs(GetDefaultPort()) == MAINNET_PORT,
+                       "mainnet default P2P port is 8433") ? 0 : 1;
+        CAddress mainAddr("127.0.0.1");
+        nFail += Check(mainAddr.port == htons(MAINNET_PORT),
+                       "mainnet address parsing uses the mainnet default port") ? 0 : 1;
+        CMessageHeader mainHeader("ping", 0);
+        char mainMagic[4];
+        memcpy(mainMagic, mainHeader.pchMessageStart, sizeof(mainMagic));
+        uint256 mainGenesis = hashGenesisBlock;
+        uint256 mainMerkle = hashGenesisMerkleRoot;
+        unsigned int mainNonce = GENESIS_NONCE;
+
+        SelectChainParams(true);
+        nFail += Check(IsTestNet(), "testnet selection is sticky") ? 0 : 1;
+        nFail += Check(ntohs(GetDefaultPort()) == TESTNET_PORT,
+                       "testnet default P2P port is 18433") ? 0 : 1;
+        CAddress testAddr("127.0.0.1");
+        nFail += Check(testAddr.port == htons(TESTNET_PORT),
+                       "testnet address parsing uses the testnet default port") ? 0 : 1;
+        CMessageHeader testHeader("ping", 0);
+        nFail += Check(memcmp(mainMagic, testHeader.pchMessageStart, sizeof(mainMagic)) != 0,
+                       "testnet message magic differs from mainnet") ? 0 : 1;
+        nFail += Check(hashGenesisBlock != mainGenesis &&
+                       hashGenesisMerkleRoot != mainMerkle &&
+                       GENESIS_NONCE != mainNonce,
+                       "testnet genesis constants differ from mainnet") ? 0 : 1;
+        nFail += Check(hashGenesisBlock == uint256("0xa9d11c6d697bcb7aea0653bc088b12dcf9f44e732df205162cf085fd9d9963eb") &&
+                       hashGenesisMerkleRoot == uint256("0x510b293105e3ff85b8d4c3920e357f85d1a86bf199eb4e7d11f04f380030ec5c") &&
+                       GENESIS_NONCE == 3199,
+                       "testnet genesis constants are pinned") ? 0 : 1;
+
+        std::string tmp;
+        if (!MakeTempDir(tmp))
+        {
+            nFail += Check(false, "creates a temporary data directory") ? 0 : 1;
+        }
+        else
+        {
+            strSetDataDir = tmp;
+            SelectChainParams(false);
+            std::string mainDir = GetAppDir();
+            SelectChainParams(true);
+            std::string testDir = GetAppDir();
+            nFail += Check(mainDir == tmp,
+                           "mainnet uses the selected data directory") ? 0 : 1;
+            nFail += Check(testDir == tmp + "/testnet",
+                           "testnet stores data below a testnet subdirectory") ? 0 : 1;
+            RemoveTree(tmp);
+        }
+    }
+    catch (const std::exception& e)
+    {
+        printf("  FAIL exception: %s\n", e.what());
+        nFail++;
+    }
+    catch (...)
+    {
+        printf("  FAIL unknown exception\n");
+        nFail++;
+    }
+
+    strSetDataDir = strOldDataDir;
+    SelectChainParams(false);
+
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
 static CBlock MakeSizedConsensusBlock(size_t nScriptBytes)
 {
     CTransaction tx;
@@ -1175,6 +3216,74 @@ static CBlock MakeSizedConsensusBlock(size_t nScriptBytes)
     return block;
 }
 
+// A distinct transaction of a chosen weight and verification cost. nUnique
+// only keeps the txids apart, so a mempool built from these is not a pile of
+// duplicates a block could never carry anyway.
+static CTransaction MakeSizedTx(size_t nPadBytes, unsigned int nSigOps, int nUnique)
+{
+    CTransaction tx;
+    tx.vin.push_back(CTxIn(COutPoint(), CScript() << (int64)nUnique << 1));
+    tx.vout.push_back(CTxOut(0, CScript()));
+    for (unsigned int i = 0; i < nSigOps; i++)
+        tx.vout[0].scriptPubKey << OP_CHECKSIG;
+    tx.vout[0].scriptPubKey.insert(tx.vout[0].scriptPubKey.end(), nPadBytes, 0);
+    return tx;
+}
+
+static CBlock MakeCoinbaseOnlyTemplate()
+{
+    CTransaction txNew;
+    txNew.vin.resize(1);
+    txNew.vin[0].prevout.SetNull();
+    txNew.vin[0].scriptSig << 1 << 1 << 1;
+    txNew.vout.resize(1);
+    txNew.vout[0].scriptPubKey << OP_CHECKSIG;
+
+    CBlock block;
+    block.vtx.push_back(txNew);
+    block.nVersion = 1;
+    block.nTime = GetAdjustedTime();
+    block.nBits = bnProofOfWorkLimit.GetCompact();
+    block.nNonce = 0;
+    return block;
+}
+
+// The sum CheckBlock() takes, spelled the same way.
+static unsigned int BlockSigOpCount(const CBlock& block)
+{
+    unsigned int n = 0;
+    for (int i = 0; i < (int)block.vtx.size(); i++)
+        n += block.vtx[i].GetSigOpCount();
+    return n;
+}
+
+// Drive the selection rule the way both assemblers drive it: ask
+// BlockTemplateFits before appending, skip what does not fit, never stop early
+// on one that does not.
+//
+// This mirrors the loops in BitcoinMiner() and RebuildJob() rather than calling
+// them -- one needs a CTxDB, a wallet key and cs_main, the other is static in
+// rpc.cpp, so neither is reachable from here. What that leaves proven is the
+// rule the two of them share and the property it is meant to guarantee, which
+// is where the defect actually lived: the budget was right and the enforcement
+// was not.
+static void SelectIntoTemplate(CBlock& block, const vector<CTransaction>& vMempool)
+{
+    unsigned int nBlockSize   = ::GetSerializeSize(block, SER_DISK);
+    unsigned int nBlockSigOps = block.vtx[0].GetSigOpCount();
+    for (int i = 0; i < (int)vMempool.size(); i++)
+    {
+        const CTransaction& tx = vMempool[i];
+        unsigned int nTxSize   = ::GetSerializeSize(tx, SER_NETWORK);
+        unsigned int nTxSigOps = tx.GetSigOpCount();
+        if (!BlockTemplateFits(nBlockSize, nBlockSigOps, nTxSize, nTxSigOps))
+            continue;
+        block.vtx.push_back(tx);
+        nBlockSize   += nTxSize;
+        nBlockSigOps += nTxSigOps;
+    }
+}
+
 static int RunConsensusLimitsSelfTest()
 {
     fflush(stdout);
@@ -1198,6 +3307,95 @@ static int RunConsensusLimitsSelfTest()
                        "the test block sits between 1 MB and the old 32 MB cap") ? 0 : 1;
         nFail += Check(!oversized.CheckSizeLimits(),
                        "a block above 1 MB is outside the consensus size limit") ? 0 : 1;
+
+        // The other half of the cap. Everything above asks what validation
+        // refuses; nothing asked what assembly produces, which is why a miner
+        // that could overshoot the cap by an entire mempool went unnoticed.
+        nFail += Check(MAX_BLOCK_SIZE_GEN < MAX_BLOCK_SIZE,
+                       "the assembly budget stays under the consensus cap") ? 0 : 1;
+
+        // The rule itself, at its edges. The sigop comparison has to match
+        // CheckBlock(), which fails on `> MAX_BLOCK_SIGOPS` and so accepts a
+        // block sitting exactly on the limit.
+        nFail += Check(BlockTemplateFits(MAX_BLOCK_SIZE_GEN - 100, 0, 100, 0),
+                       "a transaction that exactly fills the size budget fits") ? 0 : 1;
+        nFail += Check(!BlockTemplateFits(MAX_BLOCK_SIZE_GEN - 100, 0, 101, 0),
+                       "one byte past the size budget does not fit") ? 0 : 1;
+        nFail += Check(BlockTemplateFits(0, 0, 0, MAX_BLOCK_SIGOPS),
+                       "sigops exactly on the limit fit, as CheckBlock() allows") ? 0 : 1;
+        nFail += Check(!BlockTemplateFits(0, 0, 0, MAX_BLOCK_SIGOPS + 1),
+                       "one sigop past the limit does not fit") ? 0 : 1;
+
+        // A mempool several times the consensus cap, in ordinary-sized
+        // transactions. The old miner tested its budget only on the outer
+        // loop, so a single pass appended all of this.
+        {
+            CBlock block = MakeCoinbaseOnlyTemplate();
+            vector<CTransaction> vMempool;
+            for (int i = 0; i < 300; i++)
+                vMempool.push_back(MakeSizedTx(10000, 1, i));
+            SelectIntoTemplate(block, vMempool);
+            block.hashMerkleRoot = block.BuildMerkleTree();
+
+            nFail += Check(block.vtx.size() > 1,
+                           "a full mempool still fills a template") ? 0 : 1;
+            nFail += Check(::GetSerializeSize(block, SER_DISK) <= MAX_BLOCK_SIZE_GEN,
+                           "a template built from a 3 MB mempool respects the budget") ? 0 : 1;
+            nFail += Check(block.CheckSizeLimits(),
+                           "that template is one CheckBlock() would accept on size") ? 0 : 1;
+        }
+
+        // One transaction too big for the budget. Nothing on the path into the
+        // mempool caps transaction size, so this is a transaction a peer can
+        // simply send. It must be skipped and the rest still taken -- skipped,
+        // not stopped on.
+        {
+            CBlock block = MakeCoinbaseOnlyTemplate();
+            vector<CTransaction> vMempool;
+            vMempool.push_back(MakeSizedTx(1500000, 1, 9999));
+            for (int i = 0; i < 10; i++)
+                vMempool.push_back(MakeSizedTx(1000, 1, i));
+
+            unsigned int nHugeSize = ::GetSerializeSize(vMempool[0], SER_NETWORK);
+            nFail += Check(nHugeSize > MAX_BLOCK_SIZE && nHugeSize <= MAX_SIZE,
+                           "the outsized transaction is one the mempool would hold") ? 0 : 1;
+
+            SelectIntoTemplate(block, vMempool);
+            block.hashMerkleRoot = block.BuildMerkleTree();
+
+            bool fTookHuge = false;
+            for (int i = 0; i < (int)block.vtx.size(); i++)
+                if (block.vtx[i].GetHash() == vMempool[0].GetHash())
+                    fTookHuge = true;
+
+            nFail += Check(!fTookHuge,
+                           "a transaction larger than the budget is left out") ? 0 : 1;
+            nFail += Check(block.vtx.size() == 11,
+                           "the ten that do fit are taken anyway") ? 0 : 1;
+            nFail += Check(block.CheckSizeLimits(),
+                           "one outsized transaction cannot invalidate a template") ? 0 : 1;
+        }
+
+        // Transactions that are cheap in bytes and expensive to verify. Size
+        // alone does not bound what a block costs, and CheckBlock() refuses on
+        // the count regardless of how small the block is.
+        {
+            CBlock block = MakeCoinbaseOnlyTemplate();
+            vector<CTransaction> vMempool;
+            for (int i = 0; i < 100; i++)
+                vMempool.push_back(MakeSizedTx(0, 1000, i));
+            SelectIntoTemplate(block, vMempool);
+            block.hashMerkleRoot = block.BuildMerkleTree();
+
+            nFail += Check(block.vtx.size() > 1,
+                           "sigop-heavy transactions are still selected") ? 0 : 1;
+            nFail += Check(BlockSigOpCount(block) <= MAX_BLOCK_SIGOPS,
+                           "selection stops at the sigop cap CheckBlock() enforces") ? 0 : 1;
+            nFail += Check(::GetSerializeSize(block, SER_DISK) < MAX_BLOCK_SIZE_GEN,
+                           "and stops on sigops while still well inside the size budget") ? 0 : 1;
+            nFail += Check(block.CheckSizeLimits(),
+                           "the sigop-bounded template is within the size limit too") ? 0 : 1;
+        }
     }
     catch (const std::exception& e)
     {
@@ -1216,6 +3414,357 @@ static int RunConsensusLimitsSelfTest()
     return nFail == 0 ? 0 : 1;
 }
 
+static int RunParseMoneySelfTest()
+{
+    printf("parse-money self-test\n");
+    int nFail = 0;
+    struct Case { const char* in; bool ok; int64 val; };
+    Case cases[] = {
+        {"0.5", true, 50000000LL},
+        {"1", true, 100000000LL},
+        {"1.23456789", true, 123456789LL},
+        {"0.00000001", true, 1LL},
+        {"10.00000000", true, 1000000000LL},
+        {"1,000", true, 100000000000LL},
+        {"1.5 ", true, 150000000LL},
+        {"0.123456789", false, 0LL},
+        {"1.2.3", false, 0LL},
+        {"abc", false, 0LL},
+        {"-1", false, 0LL},
+        {"1e5", false, 0LL},
+    };
+    for (size_t i = 0; i < sizeof(cases) / sizeof(cases[0]); i++)
+    {
+        int64 v = -1;
+        bool r = ParseMoney(cases[i].in, v);
+        bool pass = (r == cases[i].ok) && (!r || v == cases[i].val);
+        char desc[160];
+        snprintf(desc, sizeof(desc), "ParseMoney(\"%s\") %s and value matches",
+                 cases[i].in, cases[i].ok ? "accepts" : "rejects");
+        nFail += Check(pass, desc) ? 0 : 1;
+    }
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+static bool SelfTestReadN(SOCKET s, void* buf, int n)
+{
+    char* p = (char*)buf;
+    int off = 0;
+    while (off < n)
+    {
+        int r = recv(s, p + off, n - off, 0);
+        if (r <= 0)
+            return false;
+        off += r;
+    }
+    return true;
+}
+
+static bool SelfTestWriteN(SOCKET s, const void* buf, int n)
+{
+    const char* p = (const char*)buf;
+    int off = 0;
+    while (off < n)
+    {
+        int r = send(s, p + off, n - off, 0);
+        if (r <= 0)
+            return false;
+        off += r;
+    }
+    return true;
+}
+
+static void SelfTestSetSocketTimeout(SOCKET s, int nTimeoutSecs)
+{
+#ifdef _WIN32
+    DWORD tv = (DWORD)nTimeoutSecs * 1000;
+    setsockopt(s, SOL_SOCKET, SO_RCVTIMEO, (const char*)&tv, sizeof(tv));
+    setsockopt(s, SOL_SOCKET, SO_SNDTIMEO, (const char*)&tv, sizeof(tv));
+#else
+    struct timeval tv;
+    tv.tv_sec = nTimeoutSecs;
+    tv.tv_usec = 0;
+    setsockopt(s, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
+    setsockopt(s, SOL_SOCKET, SO_SNDTIMEO, &tv, sizeof(tv));
+#endif
+}
+
+#ifdef _WIN32
+struct SelfTestWinsock
+{
+    bool fStarted;
+    SelfTestWinsock() : fStarted(false)
+    {
+        WSADATA wsadata;
+        fStarted = (WSAStartup(MAKEWORD(2,2), &wsadata) == 0);
+    }
+    ~SelfTestWinsock()
+    {
+        if (fStarted)
+            WSACleanup();
+    }
+};
+#endif
+
+static bool RunSocks5HandshakeProbe(std::string& errOut)
+{
+    errOut.clear();
+#ifdef _WIN32
+    SelfTestWinsock winsock;
+    if (!winsock.fStarted)
+    {
+        errOut = "could not start Winsock";
+        return false;
+    }
+#endif
+
+    SOCKET listener = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    if (listener == INVALID_SOCKET)
+    {
+        errOut = "could not create listener";
+        return false;
+    }
+    SelfTestSetSocketTimeout(listener, 5);
+
+    struct sockaddr_in addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    addr.sin_port = 0;
+    if (bind(listener, (struct sockaddr*)&addr, sizeof(addr)) != 0 ||
+        listen(listener, 1) != 0)
+    {
+        closesocket(listener);
+        errOut = "could not bind/listen on loopback";
+        return false;
+    }
+
+#ifdef _WIN32
+    int addrLen = sizeof(addr);
+#else
+    socklen_t addrLen = sizeof(addr);
+#endif
+    if (getsockname(listener, (struct sockaddr*)&addr, &addrLen) != 0)
+    {
+        closesocket(listener);
+        errOut = "could not read listener port";
+        return false;
+    }
+    unsigned short proxyPort = ntohs(addr.sin_port);
+
+    bool fServerOk = false;
+    std::string serverErr;
+    std::string requestedHost;
+    unsigned short requestedPort = 0;
+    std::thread server([&]() {
+        SOCKET s = accept(listener, NULL, NULL);
+        if (s == INVALID_SOCKET)
+        {
+            serverErr = "accept failed";
+            return;
+        }
+        SelfTestSetSocketTimeout(s, 5);
+
+        unsigned char hello[3] = {0,0,0};
+        if (!SelfTestReadN(s, hello, sizeof(hello)) ||
+            hello[0] != 0x05 || hello[1] != 0x01 || hello[2] != 0x00)
+        {
+            serverErr = "bad SOCKS5 greeting";
+            closesocket(s);
+            return;
+        }
+        unsigned char choice[2] = {0x05, 0x00};
+        if (!SelfTestWriteN(s, choice, sizeof(choice)))
+        {
+            serverErr = "could not write method choice";
+            closesocket(s);
+            return;
+        }
+
+        unsigned char hdr[5] = {0,0,0,0,0};
+        if (!SelfTestReadN(s, hdr, sizeof(hdr)) ||
+            hdr[0] != 0x05 || hdr[1] != 0x01 || hdr[2] != 0x00 || hdr[3] != 0x03)
+        {
+            serverErr = "CONNECT did not use domain-name address type";
+            closesocket(s);
+            return;
+        }
+
+        unsigned char len = hdr[4];
+        std::vector<unsigned char> rest((size_t)len + 2);
+        if (!SelfTestReadN(s, &rest[0], (int)rest.size()))
+        {
+            serverErr = "could not read CONNECT target";
+            closesocket(s);
+            return;
+        }
+        requestedHost.assign((const char*)&rest[0], (size_t)len);
+        requestedPort = ((unsigned short)rest[len] << 8) | rest[len + 1];
+
+        unsigned char reply[10] = {0x05, 0x00, 0x00, 0x01, 0,0,0,0, 0,0};
+        if (!SelfTestWriteN(s, reply, sizeof(reply)))
+        {
+            serverErr = "could not write CONNECT reply";
+            closesocket(s);
+            return;
+        }
+        fServerOk = true;
+        closesocket(s);
+    });
+
+    std::string err;
+    BtfClearSocks5Proxy();
+    bool fClientOk = BtfSetSocks5Proxy(strprintf("127.0.0.1:%u", (unsigned)proxyPort), err);
+    SOCKET client = INVALID_SOCKET;
+    if (fClientOk)
+        client = BtfConnectSocket("relay.example", 443, SOCK_NOSTR, 5);
+    if (client != INVALID_SOCKET)
+        BtfCloseSocket(client);
+    BtfClearSocks5Proxy();
+    closesocket(listener);
+    server.join();
+
+    if (!fClientOk)
+        errOut = strprintf("could not enable proxy: %s", err.c_str());
+    else if (client == INVALID_SOCKET)
+        errOut = "client SOCKS5 connect failed";
+    else if (!fServerOk)
+        errOut = serverErr.empty() ? "mock server failed" : serverErr;
+    else if (requestedHost != "relay.example" || requestedPort != 443)
+        errOut = strprintf("unexpected CONNECT target %s:%u", requestedHost.c_str(), (unsigned)requestedPort);
+    else
+        return true;
+    return false;
+}
+
+static int RunSocks5ProxySelfTest()
+{
+    printf("socks5-proxy self-test\n");
+    int nFail = 0;
+    std::string host, err;
+    unsigned short port = 0;
+
+    nFail += Check(BtfParseSocks5Proxy("127.0.0.1:9050", host, port, err) &&
+                   host == "127.0.0.1" && port == 9050,
+                   "parses local Tor proxy endpoint") ? 0 : 1;
+    nFail += Check(BtfParseSocks5Proxy("localhost:9050", host, port, err) &&
+                   host == "localhost" && port == 9050,
+                   "parses hostname proxy endpoint") ? 0 : 1;
+    nFail += Check(BtfParseSocks5Proxy("[::1]:9050", host, port, err) &&
+                   host == "::1" && port == 9050,
+                   "parses bracketed IPv6 proxy endpoint") ? 0 : 1;
+    nFail += Check(!BtfParseSocks5Proxy("::1:9050", host, port, err),
+                   "rejects unbracketed IPv6 proxy endpoint") ? 0 : 1;
+    nFail += Check(!BtfParseSocks5Proxy("localhost", host, port, err),
+                   "rejects missing port") ? 0 : 1;
+    nFail += Check(!BtfParseSocks5Proxy("localhost:0", host, port, err),
+                   "rejects zero port") ? 0 : 1;
+    nFail += Check(!BtfParseSocks5Proxy("localhost:70000", host, port, err),
+                   "rejects out-of-range port") ? 0 : 1;
+    nFail += Check(!BtfParseSocks5Proxy("localhost:999999999999999999999999999999", host, port, err),
+                   "rejects overflowing port") ? 0 : 1;
+    nFail += Check(!BtfParseSocks5Proxy("user:pass@localhost:9050", host, port, err),
+                   "rejects unsupported authenticated proxy syntax") ? 0 : 1;
+    nFail += Check(BtfIsTorOnionHost("abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcd.onion") &&
+                   BtfIsTorOnionHost("Relay.Example.ONION.") &&
+                   !BtfIsTorOnionHost("relay.example") &&
+                   !BtfIsTorOnionHost(".onion"),
+                   "detects .onion hosts without accepting lookalikes") ? 0 : 1;
+    std::string onion;
+    nFail += Check(btf::NormalizeOnionEndpoint("ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCD.onion.:8433", onion) &&
+                   onion == "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcd.onion:8433",
+                   "normalizes v3 onion peer endpoint") ? 0 : 1;
+    nFail += Check(!btf::NormalizeOnionEndpoint("short.onion:8433", onion) &&
+                   !btf::NormalizeOnionEndpoint("abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcd.onion:0", onion) &&
+                   !btf::NormalizeOnionEndpoint("abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabc1.onion:8433", onion),
+                   "rejects malformed onion peer endpoints") ? 0 : 1;
+
+    BtfClearSocks5Proxy();
+    nFail += Check(!BtfSocks5ProxyEnabled(), "starts disabled after clear") ? 0 : 1;
+    nFail += Check(BtfSetSocks5Proxy("127.0.0.1:9050", err) &&
+                   BtfSocks5ProxyEnabled() &&
+                   BtfSocks5ProxyName() == "127.0.0.1:9050",
+                   "enables parsed SOCKS5 proxy") ? 0 : 1;
+    BtfClearSocks5Proxy();
+    nFail += Check(!BtfSocks5ProxyEnabled(), "clear disables proxy") ? 0 : 1;
+
+    nFail += Check(BtfSetSocks5Proxy("[::1]:9050", err) &&
+                   BtfSocks5ProxyEnabled() &&
+                   BtfSocks5ProxyName() == "[::1]:9050",
+                   "enables bracketed IPv6 proxy endpoint") ? 0 : 1;
+    BtfClearSocks5Proxy();
+
+    nFail += Check(BtfEnableTorProxy("", err) &&
+                   BtfSocks5ProxyEnabled() &&
+                   BtfTorProxyEnabled() &&
+                   BtfSocks5ProxyName() == "127.0.0.1:9050",
+                   "enables Tor mode on the default local SOCKS5 endpoint") ? 0 : 1;
+    BtfClearSocks5Proxy();
+
+    nFail += Check(BtfEnableTorProxy("[::1]:9050", err) &&
+                   BtfSocks5ProxyEnabled() &&
+                   BtfTorProxyEnabled() &&
+                   BtfSocks5ProxyName() == "[::1]:9050",
+                   "enables Tor mode on a custom IPv6 endpoint") ? 0 : 1;
+    BtfClearSocks5Proxy();
+
+    nFail += Check(BtfSetSocks5Proxy("127.0.0.1:9051", err) &&
+                   BtfSocks5ProxyEnabled() &&
+                   !BtfTorProxyEnabled(),
+                   "plain SOCKS5 mode is distinct from Tor mode") ? 0 : 1;
+    BtfClearSocks5Proxy();
+
+    std::string handshakeErr;
+    bool fHandshakeOk = RunSocks5HandshakeProbe(handshakeErr);
+    nFail += Check(fHandshakeOk, handshakeErr.empty() ?
+                   "completes SOCKS5 domain-name CONNECT handshake" :
+                   strprintf("completes SOCKS5 domain-name CONNECT handshake (%s)",
+                             handshakeErr.c_str()).c_str()) ? 0 : 1;
+
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
+static int RunManagedTorSelfTest()
+{
+    printf("managed-tor self-test\n");
+    int nFail = 0;
+
+    std::string torrc = BtfBuildManagedTorrcForTest("C:/Bitflash Managed Tor/data",
+                                                   "C:/Bitflash Managed Tor/onion-service",
+                                                   19050, 19051, 8433);
+    nFail += Check(torrc.find("DataDirectory \"C:/Bitflash Managed Tor/data\"") != std::string::npos,
+                   "quotes the Tor data directory") ? 0 : 1;
+    nFail += Check(torrc.find("SocksPort 127.0.0.1:19050") != std::string::npos,
+                   "binds SOCKS5 to localhost only") ? 0 : 1;
+    nFail += Check(torrc.find("ControlPort 127.0.0.1:19051") != std::string::npos &&
+                   torrc.find("CookieAuthentication 1") != std::string::npos,
+                   "binds an authenticated Tor control port to localhost only") ? 0 : 1;
+    nFail += Check(torrc.find("IsolateSOCKSAuth") != std::string::npos &&
+                   torrc.find("IsolateClientAddr") != std::string::npos &&
+                   torrc.find("IsolateDestAddr") != std::string::npos &&
+                   torrc.find("IsolateDestPort") != std::string::npos,
+                   "enables strict Tor stream isolation") ? 0 : 1;
+    nFail += Check(torrc.find("HiddenServiceDir \"C:/Bitflash Managed Tor/onion-service\"") != std::string::npos,
+                   "writes a hidden service directory") ? 0 : 1;
+    nFail += Check(torrc.find("HiddenServiceVersion 3") != std::string::npos,
+                   "requests a v3 onion service") ? 0 : 1;
+    nFail += Check(torrc.find("HiddenServicePort 8433 127.0.0.1:8433") != std::string::npos,
+                   "maps the onion service to the Bitflash P2P listener") ? 0 : 1;
+    nFail += Check(BtfManagedTorStatus() == "disabled",
+                   "managed Tor starts disabled") ? 0 : 1;
+
+    printf("%s (%d failure%s)\n", nFail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED",
+           nFail, nFail == 1 ? "" : "s");
+    fflush(stdout);
+    return nFail == 0 ? 0 : 1;
+}
+
 int RunSelfTest(const std::string& name)
 {
     AttachTerminal();
@@ -1226,16 +3775,44 @@ int RunSelfTest(const std::string& name)
         return RunWalletHDSelfTest();
     if (name == "wallet-format")
         return RunWalletFormatSelfTest();
+    if (name == "wallet-storage-sanity")
+        return RunWalletStorageSanitySelfTest();
+    if (name == "db-env-reopen")
+        return RunDbEnvReopenSelfTest();
+    if (name == "wallet-sqlite")
+        return RunWalletSQLiteSelfTest();
+    if (name == "wallet-sqlite-migration")
+        return RunWalletSQLiteMigrationSelfTest();
     if (name == "wallet-crypto")
         return RunWalletCryptoSelfTest();
     if (name == "wallet-encrypt")
         return RunWalletEncryptSelfTest();
+    if (name == "wallet-sqlite-encrypt")
+        return RunWalletSQLiteEncryptSelfTest();
+    if (name == "wallet-backend-default")
+        return RunWalletBackendDefaultSelfTest();
+    if (name == "wallet-convert")
+        return RunWalletConvertSelfTest();
+    if (name == "wallet-portability")
+        return RunWalletPortabilitySelfTest();
     if (name == "net-message")
         return RunNetMessageSelfTest();
+    if (name == "network-params")
+        return RunNetworkParamsSelfTest();
     if (name == "consensus-limits")
         return RunConsensusLimitsSelfTest();
+    if (name == "pool-stratum")
+        return RunPoolStratumSelfTest();
+    if (name == "payout-ledger")
+        return RunPayoutLedgerSelfTest();
+    if (name == "parse-money")
+        return RunParseMoneySelfTest();
+    if (name == "socks5-proxy")
+        return RunSocks5ProxySelfTest();
+    if (name == "managed-tor")
+        return RunManagedTorSelfTest();
 
     printf("Unknown self-test '%s'\n", name.c_str());
-    printf("Known self-tests: wallet-keypool, wallet-hd, wallet-format, wallet-crypto, wallet-encrypt, net-message, consensus-limits\n");
+    printf("Known self-tests: wallet-keypool, wallet-hd, wallet-format, wallet-storage-sanity, db-env-reopen, wallet-sqlite, wallet-sqlite-migration, wallet-crypto, wallet-encrypt, wallet-sqlite-encrypt, wallet-backend-default, wallet-convert, wallet-portability, net-message, network-params, consensus-limits, pool-stratum, payout-ledger, parse-money, socks5-proxy, managed-tor\n");
     return 1;
 }
diff --git a/src/selftest.h b/src/selftest.h
index d3699c6..0ffe232 100644
--- a/src/selftest.h
+++ b/src/selftest.h
@@ -7,5 +7,6 @@
 #include <string>
 
 int RunSelfTest(const std::string& name);
+int RunSelfTestMutateWallet(const std::string& name);
 
 #endif
diff --git a/src/sockcount.h b/src/sockcount.h
index 96b6efb..a63c6be 100644
--- a/src/sockcount.h
+++ b/src/sockcount.h
@@ -63,6 +63,8 @@ enum
     SOCK_PAIR_APP,    // loopback pair: the app end handed to CNode
     SOCK_PAIR_PUMP,   // loopback pair: the pump end
     SOCK_NOSTR,       // outbound to a Nostr relay
+    SOCK_ONION_PEER,  // direct outbound to a peer's Tor hidden service
+    SOCK_STRATUM_BRIDGE, // local Stratum bridge listener/miner sockets
     SOCK_SITES
 };
 
diff --git a/src/test_btfaddr.cpp b/src/test_btfaddr.cpp
index b40dcc1..9d33d63 100644
--- a/src/test_btfaddr.cpp
+++ b/src/test_btfaddr.cpp
@@ -86,6 +86,7 @@ int main()
     }
 
     const std::string ENC_HEX = "aabbccddeeff00112233445566778899aabbccddeeff00112233445566778899";
+    const std::string ONION = "abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcd.onion:8433";
 
     // helper: fresh keypair -> (seckey, xonly pubkey)
     auto newKey = [&](unsigned char sk[32], unsigned char pk[32]) {
@@ -108,6 +109,17 @@ int main()
         CHECK(!btf::VerifyDescriptor(ctx, d, pk2, bad), "different key rejected");
     }
 
+    printf("descriptor_signs_optional_onion_endpoint\n");
+    {
+        unsigned char sk[32], pk[32]; newKey(sk, pk);
+        std::string d = btf::SignDescriptor(ctx, sk, ENC_HEX, "meeting-node-abc", 1000, ONION);
+        CHECK(!d.empty(), "sign produced onion descriptor");
+        btf::Descriptor got;
+        CHECK(btf::VerifyDescriptor(ctx, d, pk, got), "onion descriptor verifies");
+        CHECK(got.meeting_node == "meeting-node-abc" && got.enc == ENC_HEX &&
+              got.created == 1000 && got.onion == ONION, "onion fields match");
+    }
+
     printf("descriptor_rejects_tampering\n");
     {
         unsigned char sk[32], pk[32]; newKey(sk, pk);
@@ -117,6 +129,27 @@ int main()
         CHECK(!btf::VerifyDescriptor(ctx, j.dump(), pk, o), "tampered meeting_node rejected");
         json j2 = json::parse(d); j2["enc"] = "00000000000000000000000000000000000000000000000000000000deadbeef";
         CHECK(!btf::VerifyDescriptor(ctx, j2.dump(), pk, o), "tampered enc rejected");
+
+        std::string d3 = btf::SignDescriptor(ctx, sk, ENC_HEX, "node-1", 5, ONION);
+        json j3 = json::parse(d3);
+        j3["onion"] = "bcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde.onion:8433";
+        CHECK(!btf::VerifyDescriptor(ctx, j3.dump(), pk, o),
+              "tampered onion rejects the descriptor");
+        json j4 = json::parse(d3);
+        j4["sig3"] = std::string(128, '0');
+        CHECK(!btf::VerifyDescriptor(ctx, j4.dump(), pk, o),
+              "bad onion signature rejects the descriptor");
+        json j5 = json::parse(d3);
+        j5.erase("sig3");
+        CHECK(!btf::VerifyDescriptor(ctx, j5.dump(), pk, o),
+              "unsigned onion rejects the descriptor");
+        // Removing both fields still verifies: the result is indistinguishable
+        // from a peer that never had an onion endpoint. That residual strip
+        // needs the onion bound into the primary sig, an upstream change.
+        json j6 = json::parse(d3);
+        j6.erase("onion"); j6.erase("sig3");
+        CHECK(btf::VerifyDescriptor(ctx, j6.dump(), pk, o) && o.onion.empty(),
+              "full strip indistinguishable from no-onion (documented residual)");
     }
 
     printf("full_resolve_chain_from_address\n");
diff --git a/src/test_compactblock.cpp b/src/test_compactblock.cpp
new file mode 100644
index 0000000..f4b5583
--- /dev/null
+++ b/src/test_compactblock.cpp
@@ -0,0 +1,133 @@
+// Standalone test of compactblock.cpp's core logic: build a compact block,
+// reconstruct it from a simulated mempool, including the missing-tx path.
+// Not wired into the P2P layer -- proves BuildCompactBlock/
+// TryReconstructBlock/FillMissingAndFinish are correct in isolation.
+
+#include "headers.h"
+#include "compactblock.h"
+#include <cstdio>
+#include <cassert>
+
+// main.cpp defines this; we're not linking main.cpp, so define it here.
+map<uint256, CTransaction> mapTransactions;
+string GetAppDir() { return "."; } // util.h's debug-log path helper needs this
+
+static int g_fail = 0;
+#define CHECK(cond, msg) do { \
+    if (cond) printf("  ok   %s\n", msg); \
+    else { printf("  FAIL %s\n", msg); g_fail++; } \
+} while (0)
+
+// Build a syntactically-valid-enough CTransaction that GetHash()s uniquely
+// per `nSeed` -- doesn't need to be consensus-valid, this test only
+// exercises short-ID computation and reconstruction, not script validation.
+static CTransaction MakeTx(int nSeed)
+{
+    CTransaction tx;
+    tx.nVersion = 1;
+    tx.nLockTime = nSeed; // cheapest way to make each tx's serialization (and hash) unique
+    return tx;
+}
+
+int main()
+{
+    // Build a block: coinbase + 20 regular transactions.
+    CBlock block;
+    block.nVersion = 1;
+    block.hashPrevBlock = uint256("0x00000000000000000000000000000000000000000000000000000000000abc");
+    block.nTime = 1234567890;
+    block.nBits = 0x1f0fffff;
+    block.nNonce = 42;
+    block.vtx.push_back(MakeTx(0)); // coinbase
+    for (int i = 1; i <= 20; i++)
+        block.vtx.push_back(MakeTx(i));
+    block.hashMerkleRoot = block.BuildMerkleTree();
+
+    printf("build_and_reconstruct_full_mempool\n");
+    {
+        CCmpctBlock cmpct;
+        CHECK(BuildCompactBlock(block, cmpct), "BuildCompactBlock succeeds");
+        CHECK(cmpct.vPrefilledIndex.size() == 1 && cmpct.vPrefilledIndex[0] == 0, "only the coinbase is prefilled");
+        CHECK(cmpct.vShortTxId.size() == 20, "one short ID per remaining tx");
+
+        // Simulate a peer with every transaction already in its mempool.
+        mapTransactions.clear();
+        for (size_t i = 1; i < block.vtx.size(); i++)
+            mapTransactions[block.vtx[i].GetHash()] = block.vtx[i];
+
+        CBlock rebuilt;
+        vector<unsigned int> vMissing;
+        CHECK(TryReconstructBlock(cmpct, rebuilt, vMissing), "fully reconstructs when mempool has everything");
+        CHECK(vMissing.empty(), "nothing reported missing");
+        CHECK(rebuilt.GetHash() == block.GetHash(), "reconstructed block hash matches original exactly");
+        CHECK(rebuilt.vtx.size() == block.vtx.size(), "same transaction count");
+        bool fAllMatch = true;
+        for (size_t i = 0; i < block.vtx.size(); i++)
+            if (rebuilt.vtx[i].GetHash() != block.vtx[i].GetHash()) fAllMatch = false;
+        CHECK(fAllMatch, "every transaction in the right position");
+    }
+
+    printf("partial_mempool_then_getblocktxn_completes_it\n");
+    {
+        CCmpctBlock cmpct;
+        BuildCompactBlock(block, cmpct);
+
+        // Simulate a peer missing 3 of the 20 non-coinbase transactions.
+        mapTransactions.clear();
+        vector<unsigned int> expectMissing;
+        for (size_t i = 1; i < block.vtx.size(); i++)
+        {
+            if (i == 5 || i == 12 || i == 19) { expectMissing.push_back((unsigned int)i); continue; }
+            mapTransactions[block.vtx[i].GetHash()] = block.vtx[i];
+        }
+
+        CBlock rebuilt;
+        vector<unsigned int> vMissing;
+        CHECK(!TryReconstructBlock(cmpct, rebuilt, vMissing), "reports incomplete when mempool is missing some tx");
+        CHECK(vMissing == expectMissing, "missing indices are exactly the ones not in mempool");
+
+        // Simulate the getblocktxn round trip: peer sends back the missing txs.
+        vector<CTransaction> vTxn;
+        foreach(unsigned int idx, vMissing)
+            vTxn.push_back(block.vtx[idx]);
+
+        CHECK(FillMissingAndFinish(rebuilt, vMissing, vTxn), "FillMissingAndFinish succeeds with matching response");
+        CHECK(rebuilt.GetHash() == block.GetHash(), "block hash matches after filling in the missing tx");
+    }
+
+    printf("mismatched_blocktxn_response_rejected\n");
+    {
+        CCmpctBlock cmpct;
+        BuildCompactBlock(block, cmpct);
+        mapTransactions.clear();
+        mapTransactions[block.vtx[1].GetHash()] = block.vtx[1]; // only one in mempool
+
+        CBlock rebuilt;
+        vector<unsigned int> vMissing;
+        TryReconstructBlock(cmpct, rebuilt, vMissing);
+        CHECK(vMissing.size() == 19, "19 missing when mempool has only 1 of 20");
+
+        vector<CTransaction> vWrongCount;
+        vWrongCount.push_back(block.vtx[2]); // way fewer than vMissing.size()
+        CHECK(!FillMissingAndFinish(rebuilt, vMissing, vWrongCount), "rejects a response with the wrong tx count");
+    }
+
+    printf("different_blocks_give_different_short_ids_for_same_tx\n");
+    {
+        // Same transaction, two different (simulated) blocks -- short IDs
+        // must differ, since they're keyed per-block (hashPrevBlock +
+        // fresh nonce each time), not just derived from the txid alone.
+        CTransaction tx = MakeTx(99);
+        uint256 prevA = uint256("0x1111111111111111111111111111111111111111111111111111111111111111");
+        uint256 prevB = uint256("0x2222222222222222222222222222222222222222222222222222222222222222");
+        uint64 id1 = ComputeShortTxId(prevA, 0xAAAABBBBCCCCDDDDULL, tx.GetHash());
+        uint64 id2 = ComputeShortTxId(prevB, 0xAAAABBBBCCCCDDDDULL, tx.GetHash());
+        uint64 id3 = ComputeShortTxId(prevA, 0x1111222233334444ULL, tx.GetHash());
+        CHECK(id1 != id2, "different hashPrevBlock -> different short ID");
+        CHECK(id1 != id3, "different nonce -> different short ID");
+        CHECK(id1 <= 0xFFFFFFFFFFFFULL, "short ID fits in 48 bits");
+    }
+
+    printf("\n%s (%d failures)\n", g_fail == 0 ? "ALL TESTS PASSED" : "TESTS FAILED", g_fail);
+    return g_fail == 0 ? 0 : 1;
+}
diff --git a/src/tor.cpp b/src/tor.cpp
new file mode 100644
index 0000000..fea6912
--- /dev/null
+++ b/src/tor.cpp
@@ -0,0 +1,892 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+
+#include "headers_core.h"
+#include "tor.h"
+#include "nostr.h"
+#include "proxy.h"
+
+#include <errno.h>
+
+#ifndef _WIN32
+#include <signal.h>
+#include <sys/wait.h>
+#endif
+
+static CCriticalSection cs_managedTor;
+static bool g_fManagedTor = false;
+static bool g_fManagedTorStopping = false;
+static unsigned short g_managedTorSocksPort = 0;
+static unsigned short g_managedTorControlPort = 0;
+static unsigned short g_managedTorP2PPort = 0;
+static std::string g_managedTorPath;
+static std::string g_managedTorDataDir;
+static std::string g_managedTorHiddenServiceDir;
+static std::string g_managedTorOnion;
+static std::string g_managedTorStatus;
+#ifdef _WIN32
+static PROCESS_INFORMATION g_managedTorProcess;
+#else
+static pid_t g_managedTorPid = -1;
+#endif
+
+static std::string PathJoin(const std::string& a, const std::string& b)
+{
+    if (a.empty())
+        return b;
+    char last = a[a.size() - 1];
+    if (last == '/' || last == '\\')
+        return a + b;
+    return a + "/" + b;
+}
+
+static std::string NormalizeTorrcPath(std::string path)
+{
+    for (size_t i = 0; i < path.size(); i++)
+        if (path[i] == '\\')
+            path[i] = '/';
+    return path;
+}
+
+static std::string QuoteTorrcPath(const std::string& path)
+{
+    std::string out = "\"";
+    for (size_t i = 0; i < path.size(); i++)
+    {
+        if (path[i] == '"' || path[i] == '\\')
+            out += '\\';
+        out += path[i];
+    }
+    out += "\"";
+    return out;
+}
+
+static std::string QuoteCommandArg(const std::string& arg)
+{
+    std::string out = "\"";
+    for (size_t i = 0; i < arg.size(); i++)
+    {
+        if (arg[i] == '"')
+            out += '\\';
+        out += arg[i];
+    }
+    out += "\"";
+    return out;
+}
+
+static bool EnsureDir(const std::string& path, std::string& errOut)
+{
+    if (path.empty())
+    {
+        errOut = "directory path is empty";
+        return false;
+    }
+#ifdef _WIN32
+    DWORD attr = GetFileAttributesA(path.c_str());
+    if (attr != INVALID_FILE_ATTRIBUTES)
+    {
+        if (attr & FILE_ATTRIBUTE_DIRECTORY)
+            return true;
+        errOut = strprintf("%s exists and is not a directory", path.c_str());
+        return false;
+    }
+    if (CreateDirectoryA(path.c_str(), NULL))
+        return true;
+    DWORD err = GetLastError();
+    if (err == ERROR_ALREADY_EXISTS)
+        return true;
+    errOut = strprintf("could not create %s (error %lu)", path.c_str(), (unsigned long)err);
+    return false;
+#else
+    struct stat st;
+    if (stat(path.c_str(), &st) == 0)
+    {
+        if (S_ISDIR(st.st_mode))
+        {
+            chmod(path.c_str(), 0700);
+            return true;
+        }
+        errOut = strprintf("%s exists and is not a directory", path.c_str());
+        return false;
+    }
+    if (mkdir(path.c_str(), 0700) == 0)
+        return true;
+    if (errno == EEXIST)
+    {
+        if (stat(path.c_str(), &st) == 0 && S_ISDIR(st.st_mode))
+        {
+            chmod(path.c_str(), 0700);
+            return true;
+        }
+    }
+    errOut = strprintf("could not create %s: %s", path.c_str(), strerror(errno));
+    return false;
+#endif
+}
+
+static bool WriteTextFile(const std::string& path, const std::string& data,
+                          std::string& errOut)
+{
+    std::string tmp = path + ".tmp";
+    FILE* f = fopen(tmp.c_str(), "wb");
+    if (!f)
+    {
+        errOut = strprintf("could not write %s", tmp.c_str());
+        return false;
+    }
+    bool ok = fwrite(data.data(), 1, data.size(), f) == data.size();
+    if (fclose(f) != 0)
+        ok = false;
+    if (!ok)
+    {
+        remove(tmp.c_str());
+        errOut = strprintf("could not finish writing %s", tmp.c_str());
+        return false;
+    }
+#ifdef _WIN32
+    if (!MoveFileExA(tmp.c_str(), path.c_str(), MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH))
+    {
+        remove(tmp.c_str());
+        errOut = strprintf("could not install %s atomically (error %lu)",
+                           path.c_str(), (unsigned long)GetLastError());
+        return false;
+    }
+#else
+    if (rename(tmp.c_str(), path.c_str()) != 0)
+    {
+        remove(tmp.c_str());
+        errOut = strprintf("could not install %s atomically: %s",
+                           path.c_str(), strerror(errno));
+        return false;
+    }
+#endif
+    return true;
+}
+
+static bool ReadBinaryFile(const std::string& path, std::vector<unsigned char>& data,
+                           std::string& errOut)
+{
+    data.clear();
+    FILE* f = fopen(path.c_str(), "rb");
+    if (!f)
+    {
+        errOut = strprintf("could not read %s", path.c_str());
+        return false;
+    }
+    unsigned char buf[256];
+    for (;;)
+    {
+        size_t n = fread(buf, 1, sizeof(buf), f);
+        if (n > 0)
+            data.insert(data.end(), buf, buf + n);
+        if (n < sizeof(buf))
+        {
+            if (ferror(f))
+            {
+                fclose(f);
+                errOut = strprintf("could not finish reading %s", path.c_str());
+                return false;
+            }
+            break;
+        }
+        if (data.size() > 1024)
+        {
+            fclose(f);
+            errOut = strprintf("%s is unexpectedly large", path.c_str());
+            return false;
+        }
+    }
+    fclose(f);
+    if (data.empty())
+    {
+        errOut = strprintf("%s is empty", path.c_str());
+        return false;
+    }
+    return true;
+}
+
+static void SetSocketTimeouts(SOCKET s, int millis)
+{
+#ifdef _WIN32
+    DWORD timeout = millis;
+    setsockopt(s, SOL_SOCKET, SO_RCVTIMEO, (const char*)&timeout, sizeof(timeout));
+    setsockopt(s, SOL_SOCKET, SO_SNDTIMEO, (const char*)&timeout, sizeof(timeout));
+#else
+    struct timeval tv;
+    tv.tv_sec = millis / 1000;
+    tv.tv_usec = (millis % 1000) * 1000;
+    setsockopt(s, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
+    setsockopt(s, SOL_SOCKET, SO_SNDTIMEO, &tv, sizeof(tv));
+#endif
+}
+
+static bool SendAll(SOCKET s, const std::string& data)
+{
+    const char* p = data.data();
+    int left = (int)data.size();
+    while (left > 0)
+    {
+        int n = send(s, p, left, 0);
+        if (n <= 0)
+            return false;
+        p += n;
+        left -= n;
+    }
+    return true;
+}
+
+static bool RecvControlLine(SOCKET s, std::string& line)
+{
+    line.clear();
+    while (line.size() < 4096)
+    {
+        char ch = 0;
+        int n = recv(s, &ch, 1, 0);
+        if (n <= 0)
+            return false;
+        if (ch == '\n')
+            return true;
+        if (ch != '\r')
+            line += ch;
+    }
+    return false;
+}
+
+static SOCKET ConnectLoopback(unsigned short port, std::string& errOut)
+{
+#ifdef _WIN32
+    WSADATA wsadata;
+    int ret = WSAStartup(MAKEWORD(2,2), &wsadata);
+    if (ret != NO_ERROR)
+    {
+        errOut = strprintf("could not start Winsock for Tor control shutdown (WSAStartup returned %d)", ret);
+        return INVALID_SOCKET;
+    }
+#endif
+    SOCKET s = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    if (s == INVALID_SOCKET)
+    {
+        errOut = "could not create Tor control socket";
+#ifdef _WIN32
+        WSACleanup();
+#endif
+        return INVALID_SOCKET;
+    }
+    SetSocketTimeouts(s, 3000);
+    struct sockaddr_in addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    addr.sin_port = htons(port);
+    if (connect(s, (struct sockaddr*)&addr, sizeof(addr)) != 0)
+    {
+        closesocket(s);
+        errOut = strprintf("could not connect to Tor control port 127.0.0.1:%u", (unsigned)port);
+#ifdef _WIN32
+        WSACleanup();
+#endif
+        return INVALID_SOCKET;
+    }
+    return s;
+}
+
+static void CloseLoopback(SOCKET s)
+{
+    if (s != INVALID_SOCKET)
+        closesocket(s);
+#ifdef _WIN32
+    WSACleanup();
+#endif
+}
+
+static bool ReadPositiveTorControlReply(SOCKET s, std::string& errOut)
+{
+    std::string line;
+    if (!RecvControlLine(s, line))
+    {
+        errOut = "Tor control port closed before replying";
+        return false;
+    }
+    if (line.size() >= 3 && line.substr(0, 3) == "250")
+        return true;
+    errOut = strprintf("Tor control command failed: %s", line.c_str());
+    return false;
+}
+
+static bool RequestManagedTorShutdown(std::string& errOut)
+{
+    std::string dataDir;
+    unsigned short controlPort = 0;
+    CRITICAL_BLOCK(cs_managedTor)
+    {
+        dataDir = g_managedTorDataDir;
+        controlPort = g_managedTorControlPort;
+    }
+    if (controlPort == 0 || dataDir.empty())
+    {
+        errOut = "Tor control port is not available";
+        return false;
+    }
+
+    std::vector<unsigned char> cookie;
+    if (!ReadBinaryFile(PathJoin(dataDir, "control_auth_cookie"), cookie, errOut))
+        return false;
+
+    SOCKET s = ConnectLoopback(controlPort, errOut);
+    if (s == INVALID_SOCKET)
+        return false;
+
+    bool ok = false;
+    std::string auth = "AUTHENTICATE " + HexStr(cookie.begin(), cookie.end(), false) + "\r\n";
+    if (!SendAll(s, auth) || !ReadPositiveTorControlReply(s, errOut))
+        goto done;
+
+    if (!SendAll(s, "SIGNAL SHUTDOWN\r\n"))
+    {
+        errOut = "could not send Tor shutdown signal";
+        goto done;
+    }
+
+    {
+        std::string reply;
+        if (RecvControlLine(s, reply) && !(reply.size() >= 3 && reply.substr(0, 3) == "250"))
+        {
+            errOut = strprintf("Tor rejected shutdown signal: %s", reply.c_str());
+            goto done;
+        }
+    }
+    ok = true;
+
+done:
+    CloseLoopback(s);
+    return ok;
+}
+
+static bool ReadOneLine(const std::string& path, std::string& out)
+{
+    out.clear();
+    FILE* f = fopen(path.c_str(), "rb");
+    if (!f)
+        return false;
+    char buf[256] = {0};
+    if (!fgets(buf, sizeof(buf), f))
+    {
+        fclose(f);
+        return false;
+    }
+    fclose(f);
+    out = buf;
+    while (!out.empty() && (out[out.size() - 1] == '\n' || out[out.size() - 1] == '\r' ||
+                           out[out.size() - 1] == ' ' || out[out.size() - 1] == '\t'))
+        out.erase(out.size() - 1);
+    return !out.empty();
+}
+
+static bool PickLocalPort(unsigned short& portOut, std::string& errOut)
+{
+    portOut = 0;
+    bool ok = false;
+#ifdef _WIN32
+    WSADATA wsadata;
+    int ret = WSAStartup(MAKEWORD(2,2), &wsadata);
+    if (ret != NO_ERROR)
+    {
+        errOut = strprintf("could not start Winsock for local port probe (WSAStartup returned %d)", ret);
+        return false;
+    }
+#endif
+    struct sockaddr_in addr;
+    socklen_t len = sizeof(addr);
+    SOCKET s = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
+    if (s == INVALID_SOCKET)
+    {
+        errOut = "could not create local port probe socket";
+        goto done;
+    }
+    memset(&addr, 0, sizeof(addr));
+    addr.sin_family = AF_INET;
+    addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    addr.sin_port = 0;
+    if (bind(s, (struct sockaddr*)&addr, sizeof(addr)) != 0)
+    {
+        errOut = "could not bind local port probe socket";
+        goto done;
+    }
+    if (getsockname(s, (struct sockaddr*)&addr, &len) != 0)
+    {
+        errOut = "could not read local port probe socket";
+        goto done;
+    }
+    portOut = ntohs(addr.sin_port);
+    if (portOut == 0)
+    {
+        errOut = "local port probe returned port zero";
+        goto done;
+    }
+    ok = true;
+done:
+    if (s != INVALID_SOCKET)
+        closesocket(s);
+#ifdef _WIN32
+    WSACleanup();
+#endif
+    return ok;
+}
+
+static std::string ExecutableDir()
+{
+#ifdef _WIN32
+    char path[MAX_PATH + 1] = {0};
+    DWORD n = GetModuleFileNameA(NULL, path, MAX_PATH);
+    if (n == 0 || n >= MAX_PATH)
+        return ".";
+    std::string s = path;
+    size_t slash = s.find_last_of("\\/");
+    if (slash == std::string::npos)
+        return ".";
+    return s.substr(0, slash);
+#else
+    char path[4096] = {0};
+    ssize_t n = readlink("/proc/self/exe", path, sizeof(path) - 1);
+    if (n <= 0)
+        return ".";
+    path[n] = 0;
+    std::string s = path;
+    size_t slash = s.find_last_of('/');
+    if (slash == std::string::npos)
+        return ".";
+    return s.substr(0, slash);
+#endif
+}
+
+static bool FileIsExecutableCandidate(const std::string& path)
+{
+#ifdef _WIN32
+    DWORD attr = GetFileAttributesA(path.c_str());
+    return attr != INVALID_FILE_ATTRIBUTES && !(attr & FILE_ATTRIBUTE_DIRECTORY);
+#else
+    return access(path.c_str(), X_OK) == 0;
+#endif
+}
+
+static std::string ResolveTorPath(const std::string& torPathOpt)
+{
+    if (!torPathOpt.empty())
+        return torPathOpt;
+
+    std::vector<std::string> candidates;
+    std::string exeDir = ExecutableDir();
+#ifdef _WIN32
+    candidates.push_back(PathJoin(exeDir, "tor/tor.exe"));
+    candidates.push_back(PathJoin(exeDir, "tor.exe"));
+    candidates.push_back("tor.exe");
+#else
+    candidates.push_back(PathJoin(exeDir, "tor/tor"));
+    candidates.push_back(PathJoin(exeDir, "tor"));
+    candidates.push_back("tor");
+#endif
+    for (size_t i = 0; i < candidates.size(); i++)
+    {
+        if (candidates[i].find('/') == std::string::npos &&
+            candidates[i].find('\\') == std::string::npos)
+            return candidates[i]; // Let the OS search PATH.
+        if (FileIsExecutableCandidate(candidates[i]))
+            return candidates[i];
+    }
+#ifdef _WIN32
+    return "tor.exe";
+#else
+    return "tor";
+#endif
+}
+
+bool BtfBundledTorPath(std::string& torPathOut)
+{
+    torPathOut.clear();
+    std::string exeDir = ExecutableDir();
+#ifdef _WIN32
+    std::string path = PathJoin(exeDir, "tor/tor.exe");
+#else
+    std::string path = PathJoin(exeDir, "tor/tor");
+#endif
+    if (!FileIsExecutableCandidate(path))
+        return false;
+    torPathOut = path;
+    return true;
+}
+
+std::string BtfBuildManagedTorrcForTest(const std::string& dataDir,
+                                        const std::string& hiddenServiceDir,
+                                        unsigned short socksPort,
+                                        unsigned short controlPort,
+                                        unsigned short p2pPort)
+{
+    std::string torData = NormalizeTorrcPath(dataDir);
+    std::string hsDir = NormalizeTorrcPath(hiddenServiceDir);
+    std::string s;
+    s += "# Generated by Bitflash. Edit only while Bitflash is not managing Tor.\n";
+    s += "DataDirectory " + QuoteTorrcPath(torData) + "\n";
+    s += strprintf("SocksPort 127.0.0.1:%u IsolateSOCKSAuth IsolateClientAddr IsolateDestAddr IsolateDestPort\n",
+                   (unsigned)socksPort);
+    s += strprintf("ControlPort 127.0.0.1:%u\n", (unsigned)controlPort);
+    s += "CookieAuthentication 1\n";
+    s += "HiddenServiceDir " + QuoteTorrcPath(hsDir) + "\n";
+    s += "HiddenServiceVersion 3\n";
+    s += strprintf("HiddenServicePort %u 127.0.0.1:%u\n",
+                   (unsigned)p2pPort, (unsigned)p2pPort);
+    return s;
+}
+
+static bool StartTorProcess(const std::string& torPath, const std::string& torrcPath,
+                            std::string& errOut)
+{
+#ifdef _WIN32
+    memset(&g_managedTorProcess, 0, sizeof(g_managedTorProcess));
+    STARTUPINFOA si;
+    memset(&si, 0, sizeof(si));
+    si.cb = sizeof(si);
+    std::string cmd = QuoteCommandArg(torPath) + " -f " + QuoteCommandArg(torrcPath);
+    std::vector<char> mutableCmd(cmd.begin(), cmd.end());
+    mutableCmd.push_back(0);
+    if (!CreateProcessA(NULL, &mutableCmd[0], NULL, NULL, FALSE, CREATE_NO_WINDOW,
+                        NULL, NULL, &si, &g_managedTorProcess))
+    {
+        errOut = strprintf("could not start Tor process %s (error %lu)",
+                           torPath.c_str(), (unsigned long)GetLastError());
+        return false;
+    }
+    return true;
+#else
+    g_managedTorPid = fork();
+    if (g_managedTorPid < 0)
+    {
+        errOut = strprintf("could not fork Tor process: %s", strerror(errno));
+        return false;
+    }
+    if (g_managedTorPid == 0)
+    {
+        execlp(torPath.c_str(), torPath.c_str(), "-f", torrcPath.c_str(), (char*)NULL);
+        _exit(127);
+    }
+    return true;
+#endif
+}
+
+static bool ManagedTorProcessAlive(bool& fExited, int& nExitCode)
+{
+    fExited = false;
+    nExitCode = 0;
+#ifdef _WIN32
+    HANDLE hProcess = NULL;
+    CRITICAL_BLOCK(cs_managedTor)
+        hProcess = g_managedTorProcess.hProcess;
+    if (!hProcess)
+        return false;
+    DWORD code = 0;
+    if (!GetExitCodeProcess(hProcess, &code))
+        return false;
+    if (code != STILL_ACTIVE)
+    {
+        fExited = true;
+        nExitCode = (int)code;
+        return false;
+    }
+    return true;
+#else
+    pid_t pid = -1;
+    CRITICAL_BLOCK(cs_managedTor)
+        pid = g_managedTorPid;
+    if (pid <= 0)
+        return false;
+    int status = 0;
+    pid_t r = waitpid(pid, &status, WNOHANG);
+    if (r == 0)
+        return true;
+    if (r == pid)
+    {
+        fExited = true;
+        if (WIFEXITED(status))
+            nExitCode = WEXITSTATUS(status);
+        else if (WIFSIGNALED(status))
+            nExitCode = 128 + WTERMSIG(status);
+        CRITICAL_BLOCK(cs_managedTor)
+            if (g_managedTorPid == pid)
+                g_managedTorPid = -1;
+    }
+    return false;
+#endif
+}
+
+static bool ValidateManagedTorStartup(std::string& errOut)
+{
+    Sleep(500);
+    bool fExited = false;
+    int nExitCode = 0;
+    if (ManagedTorProcessAlive(fExited, nExitCode))
+        return true;
+    if (fExited)
+        errOut = strprintf("Tor exited during startup with code %d", nExitCode);
+    else
+        errOut = "Tor process is not running after startup";
+    return false;
+}
+
+static void MarkManagedTorDead(int nExitCode)
+{
+    BtfStopManagedTor();
+    CRITICAL_BLOCK(cs_managedTor)
+        g_managedTorStatus = strprintf("stopped unexpectedly, Tor exit code %d", nExitCode);
+}
+
+static void ThreadManagedTorWatchdog(void*)
+{
+    for (;;)
+    {
+        Sleep(5000);
+        CRITICAL_BLOCK(cs_managedTor)
+        {
+            if (!g_fManagedTor || g_fManagedTorStopping || fShutdown)
+                return;
+        }
+
+        bool fExited = false;
+        int nExitCode = 0;
+        if (!ManagedTorProcessAlive(fExited, nExitCode))
+        {
+            if (fExited)
+                MarkManagedTorDead(nExitCode);
+            else
+            {
+                BtfStopManagedTor();
+                CRITICAL_BLOCK(cs_managedTor)
+                    g_managedTorStatus = "stopped unexpectedly, Tor process handle is gone";
+            }
+            return;
+        }
+    }
+}
+
+static void ThreadManagedTorHostname(void*)
+{
+    std::string hostnamePath;
+    unsigned short p2pPort = 0;
+    CRITICAL_BLOCK(cs_managedTor)
+    {
+        hostnamePath = PathJoin(g_managedTorHiddenServiceDir, "hostname");
+        p2pPort = g_managedTorP2PPort;
+    }
+
+    for (int i = 0; i < 90 && !fShutdown; i++)
+    {
+        std::string onion;
+        if (ReadOneLine(hostnamePath, onion))
+        {
+            std::string endpoint = strprintf("%s:%u", onion.c_str(), (unsigned)p2pPort);
+            std::string err;
+            if (BtfSetLocalOnionEndpoint(endpoint, err))
+            {
+                CRITICAL_BLOCK(cs_managedTor)
+                {
+                    g_managedTorOnion = BtfLocalOnionEndpoint();
+                    g_managedTorStatus = strprintf("running, SOCKS5 127.0.0.1:%u, onion %s",
+                                                   (unsigned)g_managedTorSocksPort,
+                                                   g_managedTorOnion.c_str());
+                }
+                printf("Managed Tor hidden service ready: %s\n", BtfLocalOnionEndpoint().c_str());
+                return;
+            }
+            CRITICAL_BLOCK(cs_managedTor)
+                g_managedTorStatus = strprintf("running, but generated onion endpoint was rejected: %s",
+                                               err.c_str());
+            return;
+        }
+        Sleep(1000);
+    }
+
+    BtfStopManagedTor();
+    CRITICAL_BLOCK(cs_managedTor)
+        g_managedTorStatus = "failed: Tor did not create a hidden service hostname within 90s";
+}
+
+bool BtfStartManagedTor(const std::string& torPathOpt, std::string& errOut)
+{
+    CRITICAL_BLOCK(cs_managedTor)
+    {
+        if (g_fManagedTor)
+        {
+            errOut = "managed Tor is already running";
+            return false;
+        }
+    }
+
+    std::string root = PathJoin(GetAppDir(), "managed-tor");
+    std::string dataDir = PathJoin(root, "data");
+    std::string hsDir = PathJoin(root, "onion-service");
+    std::string torrcPath = PathJoin(root, "torrc");
+    if (!EnsureDir(root, errOut) || !EnsureDir(dataDir, errOut) || !EnsureDir(hsDir, errOut))
+        return false;
+
+    unsigned short socksPort = 0;
+    if (!PickLocalPort(socksPort, errOut))
+        return false;
+    unsigned short controlPort = 0;
+    if (!PickLocalPort(controlPort, errOut))
+        return false;
+
+    unsigned short p2pPort = ntohs(nListenPort);
+    std::string torrc = BtfBuildManagedTorrcForTest(dataDir, hsDir, socksPort,
+                                                   controlPort, p2pPort);
+    if (!WriteTextFile(torrcPath, torrc, errOut))
+        return false;
+
+    std::string torPath = ResolveTorPath(torPathOpt);
+    {
+        CRITICAL_BLOCK(cs_managedTor)
+        {
+            g_fManagedTor = true;
+            g_fManagedTorStopping = false;
+            g_managedTorPath = torPath;
+            g_managedTorDataDir = dataDir;
+            g_managedTorHiddenServiceDir = hsDir;
+            g_managedTorSocksPort = socksPort;
+            g_managedTorControlPort = controlPort;
+            g_managedTorP2PPort = p2pPort;
+            g_managedTorOnion.clear();
+            g_managedTorStatus = strprintf("starting %s, SOCKS5 127.0.0.1:%u",
+                                           torPath.c_str(), (unsigned)socksPort);
+        }
+    }
+
+    if (!StartTorProcess(torPath, torrcPath, errOut))
+    {
+        CRITICAL_BLOCK(cs_managedTor)
+        {
+            g_fManagedTor = false;
+            g_managedTorStatus = strprintf("failed: %s", errOut.c_str());
+        }
+        return false;
+    }
+    if (!ValidateManagedTorStartup(errOut))
+    {
+        BtfStopManagedTor();
+        CRITICAL_BLOCK(cs_managedTor)
+            g_managedTorStatus = strprintf("failed: %s", errOut.c_str());
+        return false;
+    }
+
+    std::string proxyErr;
+    if (!BtfEnableTorProxy(strprintf("127.0.0.1:%u", (unsigned)socksPort), proxyErr))
+    {
+        BtfStopManagedTor();
+        errOut = strprintf("could not enable managed Tor SOCKS5 proxy: %s", proxyErr.c_str());
+        return false;
+    }
+
+    if (_beginthread(ThreadManagedTorHostname, 0, NULL) == (uintptr_t)-1)
+    {
+        BtfStopManagedTor();
+        errOut = "could not start managed Tor hostname watcher";
+        return false;
+    }
+    if (_beginthread(ThreadManagedTorWatchdog, 0, NULL) == (uintptr_t)-1)
+    {
+        BtfStopManagedTor();
+        errOut = "could not start managed Tor watchdog";
+        return false;
+    }
+
+    return true;
+}
+
+void BtfStopManagedTor()
+{
+    bool fWasRunning = false;
+    CRITICAL_BLOCK(cs_managedTor)
+    {
+        fWasRunning = g_fManagedTor;
+        if (!fWasRunning)
+            return;
+        g_fManagedTorStopping = true;
+        g_fManagedTor = false;
+        g_managedTorStatus = "stopping";
+    }
+#ifdef _WIN32
+    if (g_managedTorProcess.hProcess)
+    {
+        std::string shutdownErr;
+        bool fGraceful = RequestManagedTorShutdown(shutdownErr);
+        DWORD waitResult = WaitForSingleObject(g_managedTorProcess.hProcess,
+                                               fGraceful ? 10000 : 1000);
+        if (waitResult != WAIT_OBJECT_0)
+        {
+            TerminateProcess(g_managedTorProcess.hProcess, 0);
+            WaitForSingleObject(g_managedTorProcess.hProcess, 5000);
+        }
+        CloseHandle(g_managedTorProcess.hProcess);
+        CloseHandle(g_managedTorProcess.hThread);
+        memset(&g_managedTorProcess, 0, sizeof(g_managedTorProcess));
+    }
+#else
+    // Snapshot the pid under the lock. The watchdog's ManagedTorProcessAlive
+    // reaps the same child concurrently and resets g_managedTorPid under
+    // cs_managedTor; reading the global unlocked here could leave us waiting
+    // on ECHILD and then SIGKILLing a recycled PID.
+    pid_t pid = -1;
+    CRITICAL_BLOCK(cs_managedTor)
+        pid = g_managedTorPid;
+    if (pid > 0)
+    {
+        std::string shutdownErr;
+        if (!RequestManagedTorShutdown(shutdownErr))
+            kill(pid, SIGTERM);
+        bool fExited = false;
+        for (int i = 0; i < 100; i++)
+        {
+            int status = 0;
+            pid_t r = waitpid(pid, &status, WNOHANG);
+            // ECHILD means the watchdog already reaped it -- that is exit,
+            // not a reason to signal anything.
+            if (r == pid || (r == -1 && errno == ECHILD))
+            {
+                fExited = true;
+                break;
+            }
+            Sleep(100);
+        }
+        if (!fExited)
+        {
+            kill(pid, SIGKILL);
+            waitpid(pid, NULL, 0);
+        }
+        CRITICAL_BLOCK(cs_managedTor)
+            if (g_managedTorPid == pid)
+                g_managedTorPid = -1;
+    }
+#endif
+    CRITICAL_BLOCK(cs_managedTor)
+    {
+        g_managedTorStatus = "stopped";
+        g_managedTorOnion.clear();
+        g_managedTorSocksPort = 0;
+        g_managedTorControlPort = 0;
+        g_managedTorP2PPort = 0;
+    }
+}
+
+bool BtfManagedTorEnabled()
+{
+    CRITICAL_BLOCK(cs_managedTor)
+        return g_fManagedTor;
+    return false;
+}
+
+std::string BtfManagedTorStatus()
+{
+    CRITICAL_BLOCK(cs_managedTor)
+    {
+        if (!g_fManagedTor && g_managedTorStatus.empty())
+            return "disabled";
+        return g_managedTorStatus;
+    }
+    return "disabled";
+}
diff --git a/src/tor.h b/src/tor.h
new file mode 100644
index 0000000..cfb87a5
--- /dev/null
+++ b/src/tor.h
@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+//
+// Managed Tor process support. This is transport bootstrapping only: it does
+// not touch consensus, wallet keys, mining, or the .btf identity.
+
+#ifndef BITFLASH_TOR_H
+#define BITFLASH_TOR_H
+
+#include <string>
+
+bool BtfStartManagedTor(const std::string& torPathOpt, std::string& errOut);
+void BtfStopManagedTor();
+bool BtfManagedTorEnabled();
+std::string BtfManagedTorStatus();
+bool BtfBundledTorPath(std::string& torPathOut);
+
+std::string BtfBuildManagedTorrcForTest(const std::string& dataDir,
+                                        const std::string& hiddenServiceDir,
+                                        unsigned short socksPort,
+                                        unsigned short controlPort,
+                                        unsigned short p2pPort);
+
+#endif
diff --git a/src/util.cpp b/src/util.cpp
index d52ca88..ab29178 100644
--- a/src/util.cpp
+++ b/src/util.cpp
@@ -7,6 +7,12 @@
 
 
 bool fDebug = false;
+bool fDebugRelay = false;
+
+// In-process cap for debug.log, in bytes. Default matches the 1G trigger of
+// the shipped logrotate policy so a long-running node stays bounded even
+// without it; -maxdebugfilesize=N (MB) tunes it, 0 disables.
+int64 nMaxDebugFileSize = 1024 * 1024 * (int64)1024;
 
 // ---------------------------------------------------------------------------
 // Categorized, burst-collapsing logging -- see the LogPrint doc comment in
@@ -26,10 +32,22 @@ static bool LogCategoryDefaultOn(const char* category)
            strcmp(category, "payout") == 0;
 }
 
+// Categories so noisy they drown out everything else even under -debug:
+// per-message send traces, wallet relay rebroadcasts, raw CBlock dumps and
+// per-address discovery lines made up ~90% of a 13-hour production capture
+// (issue #35). They need /debugrelay, not merely /debug.
+static bool LogCategoryVerboseOnly(const char* category)
+{
+    return strcmp(category, "relay")          == 0 ||
+           strcmp(category, "nostrdiscovery") == 0;
+}
+
 bool LogAcceptsCategory(const char* category)
 {
     if (LogCategoryDefaultOn(category))
         return true;
+    if (LogCategoryVerboseOnly(category))
+        return fDebugRelay;
     return fDebug;
 }
 
@@ -47,6 +65,61 @@ struct LogDedupState {
 static std::map<std::string, LogDedupState> g_logDedup;
 static CCriticalSection cs_logDedup;
 
+// A pending "(N similar)" summary, lifted out of the table while the lock is
+// held and written after it is released.
+struct LogDedupFlush {
+    std::string category;
+    int         suppressed;
+    int64       elapsed;      // how long the window that counted them ran
+    std::string lastMsg;
+};
+
+static int64 g_logDedupLastSweep = 0;
+
+static void EmitDedupSummary(const LogDedupFlush& f)
+{
+    OutputDebugStringF("[%s] (%d similar in %llds, last: %s)\n",
+                       f.category.c_str(), f.suppressed,
+                       (long long)f.elapsed, f.lastMsg.c_str());
+}
+
+// A window is otherwise only closed out when its own call site fires again, so
+// a burst that simply stops -- 100 ledger entries voided in one pass and then
+// silence -- leaves its count sitting in the table and the summary is never
+// written at all. That is how 99 of 100 voids went unreported, with no "(N
+// similar)" line to say anything was missing (issue #3). Sweep every expired
+// window instead, so a finished burst is summarised as soon as anything at all
+// is logged.
+//
+// Expired entries are erased rather than reopened: the window is over, so there
+// is no state left worth keeping, and the next call from that site then takes
+// the "first time" path and prints directly -- exactly what the rollover branch
+// below would have done. It also stops the table growing without bound.
+//
+// Caller holds cs_logDedup; the summaries are written after it is released.
+static void SweepExpiredWindowsLocked(int64 now, std::vector<LogDedupFlush>& out)
+{
+    for (std::map<std::string, LogDedupState>::iterator it = g_logDedup.begin();
+         it != g_logDedup.end(); )
+    {
+        if (now - it->second.windowStart < DEDUP_WINDOW_SECS)
+        {
+            ++it;
+            continue;
+        }
+        if (it->second.suppressed > 0)
+        {
+            LogDedupFlush f;
+            f.category   = it->first.substr(0, it->first.find('|'));
+            f.suppressed = it->second.suppressed;
+            f.elapsed    = now - it->second.windowStart;
+            f.lastMsg    = it->second.lastMsg;
+            out.push_back(f);
+        }
+        g_logDedup.erase(it++);
+    }
+}
+
 void LogPrintDedup(const char* category, const char* file, int line, const std::string& msgIn)
 {
     // Call sites follow the existing printf() convention of ending their
@@ -61,11 +134,19 @@ void LogPrintDedup(const char* category, const char* file, int line, const std::
 
     int64 now = GetTime();
     bool  fEmitNow = false;
-    int   suppressedToFlush = 0;
-    std::string flushedMsg;
+    std::vector<LogDedupFlush> flushes;
 
     CRITICAL_BLOCK(cs_logDedup)
     {
+        // At most once a second. The table holds one entry per call site that
+        // has fired in the last few seconds, so the walk is short, but it must
+        // not run once per line of a burst.
+        if (now != g_logDedupLastSweep)
+        {
+            g_logDedupLastSweep = now;
+            SweepExpiredWindowsLocked(now, flushes);
+        }
+
         std::map<std::string, LogDedupState>::iterator it = g_logDedup.find(key);
         if (it == g_logDedup.end())
         {
@@ -76,10 +157,18 @@ void LogPrintDedup(const char* category, const char* file, int line, const std::
         }
         else if (now - it->second.windowStart >= DEDUP_WINDOW_SECS)
         {
-            // Window rolled over: flush what was suppressed during it (if
-            // anything), then start a new window with this call printed.
-            suppressedToFlush = it->second.suppressed;
-            flushedMsg = it->second.lastMsg;
+            // Window rolled over within the same second as the last sweep:
+            // flush what was suppressed during it (if anything), then start a
+            // new window with this call printed.
+            if (it->second.suppressed > 0)
+            {
+                LogDedupFlush f;
+                f.category   = category;
+                f.suppressed = it->second.suppressed;
+                f.elapsed    = now - it->second.windowStart;
+                f.lastMsg    = it->second.lastMsg;
+                flushes.push_back(f);
+            }
             it->second.windowStart = now;
             it->second.suppressed  = 0;
             it->second.lastMsg     = msg;
@@ -94,13 +183,23 @@ void LogPrintDedup(const char* category, const char* file, int line, const std::
         }
     }
 
-    if (suppressedToFlush > 0)
-        OutputDebugStringF("[%s] (%d similar in %llds, last: %s)\n",
-                            category, suppressedToFlush, (long long)DEDUP_WINDOW_SECS, flushedMsg.c_str());
+    for (size_t i = 0; i < flushes.size(); i++)
+        EmitDedupSummary(flushes[i]);
     if (fEmitNow)
         OutputDebugStringF("[%s] %s\n", category, msg.c_str());
 }
 
+// LogPrintAlways() -- see the doc comment in util.h. No window, no counting,
+// no table entry: every call writes its own line.
+void LogPrintNoCollapse(const char* category, const std::string& msgIn)
+{
+    std::string msg = msgIn;
+    while (!msg.empty() && (msg.back() == '\n' || msg.back() == '\r'))
+        msg.pop_back();
+
+    OutputDebugStringF("[%s] %s\n", category, msg.c_str());
+}
+
 
 
 
@@ -337,7 +436,7 @@ string FormatMoney(int64 n, bool fPlus)
 bool ParseMoney(const char* pszIn, int64& nRet)
 {
     string strWhole;
-    int64 nCents = 0;
+    int64 nUnits = 0;                 // fractional part, scaled to COIN (8 decimals)
     const char* p = pszIn;
     while (isspace(*p))
         p++;
@@ -348,12 +447,16 @@ bool ParseMoney(const char* pszIn, int64& nRet)
         if (*p == '.')
         {
             p++;
-            if (!isdigit(p[0]) || !isdigit(p[1]))
-                return false;
-            nCents = atoi64(p);
-            if (nCents < 0 || nCents > 99)
+            int64 nMult = COIN / 10;  // weight of the first decimal digit
+            while (isdigit(*p) && nMult > 0)
+            {
+                nUnits += nMult * (*p - '0');
+                nMult /= 10;
+                p++;
+            }
+            // reject more than 8 fractional digits rather than silently truncate
+            if (isdigit(*p))
                 return false;
-            p += 2;
             break;
         }
         if (isspace(*p))
@@ -365,13 +468,12 @@ bool ParseMoney(const char* pszIn, int64& nRet)
     for (; *p; p++)
         if (!isspace(*p))
             return false;
-    if (strWhole.size() > 17)
+    if (strWhole.size() > 10)         // 10 whole digits * COIN stays within int64
         return false;
     int64 nWhole = atoi64(strWhole);
-    int64 nValue = nWhole * 100 + nCents;
-    if (nValue / 100 != nWhole)
+    int64 nValue = nWhole * COIN + nUnits;
+    if (nValue < 0 || (nValue - nUnits) / COIN != nWhole)
         return false;
-    nValue *= CENT;
     nRet = nValue;
     return true;
 }
@@ -394,13 +496,37 @@ bool FileExists(const char* psz)
 #endif
 }
 
-int GetFilesize(FILE* file)
+#ifndef _WIN32
+// If off_t is 32 bits wide, ftello() truncates exactly like the int this
+// function used to return. Fail the build rather than ship the silent
+// version of the bug (32-bit hosts need -D_FILE_OFFSET_BITS=64).
+static_assert(sizeof(off_t) >= 8, "GetFilesize needs a 64-bit off_t");
+#endif
+
+// Returns the file's size in bytes, or -1 if it cannot be determined.
+//
+// This used to hold ftell()'s long in an int, so a file of 2 GiB or more came
+// back negative. Its only caller is the debug.log roll in util.h, which skips
+// the roll on a negative size -- i.e. rotation switched itself off for good at
+// exactly the size the roll exists to prevent, and any cap of 2048 MB or more
+// could never be exceeded at all. Both failures were silent.
+int64 GetFilesize(FILE* file)
 {
-    int nSavePos = ftell(file);
-    int nFilesize = -1;
-    if (fseek(file, 0, SEEK_END) == 0)
-        nFilesize = ftell(file);
-    fseek(file, nSavePos, SEEK_SET);
+#ifdef _WIN32
+    __int64 nSavePos = _ftelli64(file);
+    int64 nFilesize = -1;
+    if (nSavePos >= 0 && _fseeki64(file, 0, SEEK_END) == 0)
+        nFilesize = _ftelli64(file);
+    if (nSavePos >= 0)
+        _fseeki64(file, nSavePos, SEEK_SET);
+#else
+    off_t nSavePos = ftello(file);
+    int64 nFilesize = -1;
+    if (nSavePos >= 0 && fseeko(file, 0, SEEK_END) == 0)
+        nFilesize = ftello(file);
+    if (nSavePos >= 0)
+        fseeko(file, nSavePos, SEEK_SET);
+#endif
     return nFilesize;
 }
 
diff --git a/src/util.h b/src/util.h
index d72518b..dfe7511 100644
--- a/src/util.h
+++ b/src/util.h
@@ -87,6 +87,15 @@ inline T& REF(const T& val)
 
 extern bool fDebug;
 
+// /debugrelay: the per-message firehose ("relay" and "nostrdiscovery"
+// categories) that even -debug keeps off. See LogAcceptsCategory().
+extern bool fDebugRelay;
+
+// debug.log is rolled to debug.log.old once it grows past this many bytes
+// (set from -maxdebugfilesize, in MB; 0 disables the check). See the roll
+// site in OutputDebugStringF() below.
+extern int64 nMaxDebugFileSize;
+
 // ---------------------------------------------------------------------------
 // Categorized, burst-collapsing logging
 //
@@ -106,15 +115,29 @@ extern bool fDebug;
 //   2. Burst collapse: repeated LogPrint() calls from the *same source line*
 //      only emit one line per DEDUP_WINDOW_SECS; if more calls land inside
 //      that window they're counted instead of reprinted, and the count is
-//      flushed as a single "(xN similar in Ws)" line the moment the window
-//      rolls over. A loop discovering 500 peers by address now produces a
-//      small, bounded number of lines instead of 500 -- log growth is capped
-//      by elapsed time, not by how many similar events happen to fire.
+//      flushed as a single "(xN similar in Ws)" line once the window expires
+//      -- whether or not that call site ever fires again. A loop discovering
+//      500 peers by address now produces a small, bounded number of lines
+//      instead of 500 -- log growth is capped by elapsed time, not by how
+//      many similar events happen to fire.
+//
+// Use LogPrintAlways() instead for anything that reports an irreversible
+// change to money: an obligation voided, a payment sent, a payment that
+// failed. One line standing in for an unknown number of identical events is
+// a tidy report of peer chatter and a false report of a ledger. A reorg
+// voiding 100 entries hits one source line 100 times inside one window;
+// under LogPrint() that read as a single block losing a single 49.49 BTF
+// payment, while 4,950 BTF of obligations were actually destroyed, and the
+// discrepancy was only found by counting entries in pending_payouts.json
+// (issue #3). Bounded log growth is not worth that ambiguity here.
 // ---------------------------------------------------------------------------
 bool LogAcceptsCategory(const char* category);
 void LogPrintDedup(const char* category, const char* file, int line, const std::string& msg);
+void LogPrintNoCollapse(const char* category, const std::string& msg);
 #define LogPrint(category, ...) \
     do { if (LogAcceptsCategory(category)) LogPrintDedup((category), __FILE__, __LINE__, strprintf(__VA_ARGS__)); } while (0)
+#define LogPrintAlways(category, ...) \
+    do { if (LogAcceptsCategory(category)) LogPrintNoCollapse((category), strprintf(__VA_ARGS__)); } while (0)
 
 // Every format string in this project goes through one of the four functions
 // below -- `printf` itself is remapped to OutputDebugStringF just above, and
@@ -145,7 +168,7 @@ void ParseString(const string& str, char c, vector<string>& v);
 string FormatMoney(int64 n, bool fPlus=false);
 bool ParseMoney(const char* pszIn, int64& nRet);
 bool FileExists(const char* psz);
-int GetFilesize(FILE* file);
+int64 GetFilesize(FILE* file);
 uint64 GetRand(uint64 nMax);
 int64 GetTime();
 int64 GetAdjustedTime();
@@ -199,7 +222,7 @@ protected:
 public:
     char* pszFile;
     int nLine;
-    explicit CCriticalSection() { InitializeCriticalSection(&cs); }
+    explicit CCriticalSection() : pszFile(NULL), nLine(0) { InitializeCriticalSection(&cs); }
     ~CCriticalSection() { DeleteCriticalSection(&cs); }
     void Enter() { EnterCriticalSection(&cs); }
     void Leave() { LeaveCriticalSection(&cs); }
@@ -390,7 +413,65 @@ inline int OutputDebugStringF(const char* pszFormat, ...)
             else
                 strDebugFile = "debug.log";
         }
+        // Latched by a failed rename in the roll below, which cannot be
+        // retried usefully and must not be retried endlessly.
+        static bool fRollDisabled = false;
         FILE* fileout = fopen(strDebugFile.c_str(), "a");
+        if (fileout && nMaxDebugFileSize > 0 && !fRollDisabled)
+        {
+            // Roll an overgrown debug.log before adding to it. Nothing in the
+            // tree shrinks this file once the process is running (there is no
+            // ShrinkDebugFile, and even Bitcoin's only ran at startup), so a
+            // node that stays up for months grows the log without bound --
+            // production hit ~2 GiB. The file is opened and closed per line,
+            // so a rename is safe here: the next line simply reopens the
+            // path. One generation is kept as debug.log.old; logrotate
+            // (contrib/logrotate/) handles anything longer-term.
+            int64 nSize = GetFilesize(fileout);
+            if (nSize >= 0 && nSize > nMaxDebugFileSize)
+            {
+                fclose(fileout);
+                string strOldFile = strDebugFile + ".old";
+                remove(strOldFile.c_str()); // rename() won't clobber on Windows
+                bool fRolled = (rename(strDebugFile.c_str(), strOldFile.c_str()) == 0);
+                int nRenameErrno = errno; // before fopen() can overwrite it
+                fileout = fopen(strDebugFile.c_str(), "a");
+                if (fRolled)
+                {
+                    if (fileout)
+                        fprintf(fileout,
+                            "debug.log grew past %lld MB; previous contents moved to debug.log.old (-maxdebugfilesize)\n",
+                            (long long)(nMaxDebugFileSize / 1024 / 1024));
+                }
+                else if (nRenameErrno == ENOENT)
+                {
+                    // The file went away between the size check and the
+                    // rename, so an external rotator (logrotate) got there
+                    // first. Nothing left to roll and nothing wrong: the
+                    // fopen above has already recreated it. Latching on this
+                    // would let a benign race with logrotate switch the cap
+                    // off for the rest of the run.
+                }
+                else
+                {
+                    // The file is still over the cap, so this branch would be
+                    // reached again on the next line and every line after it.
+                    // Unlatched, the complaint about failing to roll becomes
+                    // the runaway growth the roll exists to prevent. Say it
+                    // once and stop trying -- on stderr too, because whatever
+                    // blocked the rename (read-only mount, permissions, EXDEV
+                    // across a bind mount) may equally block the log write.
+                    fRollDisabled = true;
+                    fprintf(stderr,
+                        "cannot roll %s (rename to .old failed: %s); -maxdebugfilesize disabled for this run\n",
+                        strDebugFile.c_str(), strerror(nRenameErrno));
+                    if (fileout)
+                        fprintf(fileout,
+                            "cannot roll debug.log (rename to .old failed: %s); -maxdebugfilesize disabled for this run\n",
+                            strerror(nRenameErrno));
+                }
+            }
+        }
         if (fileout)
         {
             va_list arg_ptr;
diff --git a/src/wallet_sqlite.cpp b/src/wallet_sqlite.cpp
new file mode 100644
index 0000000..f4b4b37
--- /dev/null
+++ b/src/wallet_sqlite.cpp
@@ -0,0 +1,374 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+
+#include "headers.h"
+#include "wallet_sqlite.h"
+
+static void SetSQLiteError(sqlite3* pdb, const string& strContext,
+                           string& strError)
+{
+    if (pdb)
+        strError = strContext + ": " + sqlite3_errmsg(pdb);
+    else
+        strError = strContext;
+}
+
+CWalletDBSQLite::CWalletDBSQLite() : pdb(NULL)
+{
+}
+
+CWalletDBSQLite::~CWalletDBSQLite()
+{
+    Close();
+}
+
+bool CWalletDBSQLite::Open(const string& strPath, string& strError)
+{
+    Close();
+
+    int ret = sqlite3_open_v2(strPath.c_str(), &pdb,
+                              SQLITE_OPEN_READWRITE |
+                              SQLITE_OPEN_CREATE |
+                              SQLITE_OPEN_FULLMUTEX,
+                              NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot open SQLite wallet", strError);
+        Close();
+        return false;
+    }
+
+    sqlite3_busy_timeout(pdb, 5000);
+
+    if (!Exec("PRAGMA journal_mode=WAL;", strError))
+    {
+        Close();
+        return false;
+    }
+    if (!Exec("PRAGMA synchronous=FULL;", strError))
+    {
+        Close();
+        return false;
+    }
+    if (!InitSchema(strError))
+    {
+        Close();
+        return false;
+    }
+    return true;
+}
+
+bool CWalletDBSQLite::OpenReadOnly(const string& strPath, string& strError)
+{
+    Close();
+
+    int ret = sqlite3_open_v2(strPath.c_str(), &pdb,
+                              SQLITE_OPEN_READONLY |
+                              SQLITE_OPEN_FULLMUTEX,
+                              NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot open SQLite wallet read-only", strError);
+        Close();
+        return false;
+    }
+
+    sqlite3_busy_timeout(pdb, 5000);
+    return true;
+}
+
+void CWalletDBSQLite::Close()
+{
+    if (pdb)
+    {
+        sqlite3_close(pdb);
+        pdb = NULL;
+    }
+}
+
+bool CWalletDBSQLite::BeginTransaction(string& strError)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    return Exec("BEGIN IMMEDIATE;", strError);
+}
+
+bool CWalletDBSQLite::CommitTransaction(string& strError)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    return Exec("COMMIT;", strError);
+}
+
+bool CWalletDBSQLite::RollbackTransaction(string& strError)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    return Exec("ROLLBACK;", strError);
+}
+
+bool CWalletDBSQLite::Checkpoint(string& strError)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    return Exec("PRAGMA wal_checkpoint(TRUNCATE);", strError);
+}
+
+bool CWalletDBSQLite::Exec(const char* pszSql, string& strError)
+{
+    char* pszErr = NULL;
+    int ret = sqlite3_exec(pdb, pszSql, NULL, NULL, &pszErr);
+    if (ret != SQLITE_OK)
+    {
+        if (pszErr)
+        {
+            strError = pszErr;
+            sqlite3_free(pszErr);
+        }
+        else
+            SetSQLiteError(pdb, "SQLite exec failed", strError);
+        return false;
+    }
+    return true;
+}
+
+bool CWalletDBSQLite::InitSchema(string& strError)
+{
+    return Exec("CREATE TABLE IF NOT EXISTS wallet_records ("
+                "key BLOB PRIMARY KEY NOT NULL,"
+                "value BLOB NOT NULL"
+                ");",
+                strError) &&
+           Exec("PRAGMA user_version=1;", strError);
+}
+
+bool CWalletDBSQLite::WriteRecord(const vector<unsigned char>& vchKey,
+                                  const vector<unsigned char>& vchValue,
+                                  string& strError,
+                                  bool fOverwrite)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    if (vchKey.empty())
+    {
+        strError = "SQLite wallet record key is empty";
+        return false;
+    }
+
+    sqlite3_stmt* stmt = NULL;
+    const char* pszSql = fOverwrite
+        ? "INSERT OR REPLACE INTO wallet_records(key, value) VALUES(?, ?);"
+        : "INSERT INTO wallet_records(key, value) VALUES(?, ?);";
+    int ret = sqlite3_prepare_v2(pdb, pszSql, -1, &stmt, NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot prepare SQLite wallet write", strError);
+        return false;
+    }
+
+    ret = sqlite3_bind_blob(stmt, 1, &vchKey[0], (int)vchKey.size(),
+                            SQLITE_TRANSIENT);
+    if (ret == SQLITE_OK)
+        ret = sqlite3_bind_blob(stmt, 2,
+                                vchValue.empty() ? NULL : &vchValue[0],
+                                (int)vchValue.size(),
+                                SQLITE_TRANSIENT);
+    if (ret == SQLITE_OK)
+        ret = sqlite3_step(stmt);
+
+    bool fOk = (ret == SQLITE_DONE);
+    if (!fOk)
+        SetSQLiteError(pdb, "cannot write SQLite wallet record", strError);
+    sqlite3_finalize(stmt);
+    return fOk;
+}
+
+bool CWalletDBSQLite::ReadRecord(const vector<unsigned char>& vchKey,
+                                 vector<unsigned char>& vchValueRet,
+                                 string& strError)
+{
+    vchValueRet.clear();
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    if (vchKey.empty())
+    {
+        strError = "SQLite wallet record key is empty";
+        return false;
+    }
+
+    sqlite3_stmt* stmt = NULL;
+    const char* pszSql = "SELECT value FROM wallet_records WHERE key = ?;";
+    int ret = sqlite3_prepare_v2(pdb, pszSql, -1, &stmt, NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot prepare SQLite wallet read", strError);
+        return false;
+    }
+
+    ret = sqlite3_bind_blob(stmt, 1, &vchKey[0], (int)vchKey.size(),
+                            SQLITE_TRANSIENT);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot bind SQLite wallet key", strError);
+        sqlite3_finalize(stmt);
+        return false;
+    }
+
+    ret = sqlite3_step(stmt);
+    if (ret == SQLITE_ROW)
+    {
+        const unsigned char* pch =
+            (const unsigned char*)sqlite3_column_blob(stmt, 0);
+        int nBytes = sqlite3_column_bytes(stmt, 0);
+        if (nBytes > 0 && pch)
+            vchValueRet.assign(pch, pch + nBytes);
+        sqlite3_finalize(stmt);
+        return true;
+    }
+
+    if (ret == SQLITE_DONE)
+        strError = "SQLite wallet record not found";
+    else
+        SetSQLiteError(pdb, "cannot read SQLite wallet record", strError);
+    sqlite3_finalize(stmt);
+    return false;
+}
+
+bool CWalletDBSQLite::EraseRecord(const vector<unsigned char>& vchKey,
+                                  string& strError)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+    if (vchKey.empty())
+    {
+        strError = "SQLite wallet record key is empty";
+        return false;
+    }
+
+    sqlite3_stmt* stmt = NULL;
+    const char* pszSql = "DELETE FROM wallet_records WHERE key = ?;";
+    int ret = sqlite3_prepare_v2(pdb, pszSql, -1, &stmt, NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot prepare SQLite wallet erase", strError);
+        return false;
+    }
+
+    ret = sqlite3_bind_blob(stmt, 1, &vchKey[0], (int)vchKey.size(),
+                            SQLITE_TRANSIENT);
+    if (ret == SQLITE_OK)
+        ret = sqlite3_step(stmt);
+
+    bool fOk = (ret == SQLITE_DONE);
+    if (!fOk)
+        SetSQLiteError(pdb, "cannot erase SQLite wallet record", strError);
+    sqlite3_finalize(stmt);
+    return fOk;
+}
+
+bool CWalletDBSQLite::ScanRecords(CWalletRecordVisitor& visitor,
+                                  string& strError)
+{
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+
+    sqlite3_stmt* stmt = NULL;
+    const char* pszSql = "SELECT key, value FROM wallet_records ORDER BY rowid;";
+    int ret = sqlite3_prepare_v2(pdb, pszSql, -1, &stmt, NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot prepare SQLite wallet scan", strError);
+        return false;
+    }
+
+    while ((ret = sqlite3_step(stmt)) == SQLITE_ROW)
+    {
+        const unsigned char* pchKey =
+            (const unsigned char*)sqlite3_column_blob(stmt, 0);
+        int nKeyBytes = sqlite3_column_bytes(stmt, 0);
+        const unsigned char* pchValue =
+            (const unsigned char*)sqlite3_column_blob(stmt, 1);
+        int nValueBytes = sqlite3_column_bytes(stmt, 1);
+
+        vector<unsigned char> vchKey;
+        vector<unsigned char> vchValue;
+        if (nKeyBytes > 0 && pchKey)
+            vchKey.assign(pchKey, pchKey + nKeyBytes);
+        if (nValueBytes > 0 && pchValue)
+            vchValue.assign(pchValue, pchValue + nValueBytes);
+
+        CDataStream ssKey(vchKey, SER_DISK);
+        CDataStream ssValue(vchValue, SER_DISK);
+        if (!visitor.VisitWalletRecord(ssKey, ssValue, strError))
+        {
+            sqlite3_finalize(stmt);
+            return false;
+        }
+    }
+
+    if (ret != SQLITE_DONE)
+    {
+        SetSQLiteError(pdb, "cannot scan SQLite wallet records", strError);
+        sqlite3_finalize(stmt);
+        return false;
+    }
+
+    sqlite3_finalize(stmt);
+    return true;
+}
+
+bool CWalletDBSQLite::CountRecords(int& nRecordsRet, string& strError)
+{
+    nRecordsRet = 0;
+    if (!pdb)
+    {
+        strError = "SQLite wallet is not open";
+        return false;
+    }
+
+    sqlite3_stmt* stmt = NULL;
+    int ret = sqlite3_prepare_v2(pdb,
+                                 "SELECT COUNT(*) FROM wallet_records;",
+                                 -1, &stmt, NULL);
+    if (ret != SQLITE_OK)
+    {
+        SetSQLiteError(pdb, "cannot prepare SQLite wallet count", strError);
+        return false;
+    }
+
+    ret = sqlite3_step(stmt);
+    if (ret != SQLITE_ROW)
+    {
+        SetSQLiteError(pdb, "cannot count SQLite wallet records", strError);
+        sqlite3_finalize(stmt);
+        return false;
+    }
+
+    nRecordsRet = sqlite3_column_int(stmt, 0);
+    sqlite3_finalize(stmt);
+    return true;
+}
diff --git a/src/wallet_sqlite.h b/src/wallet_sqlite.h
new file mode 100644
index 0000000..d27e13a
--- /dev/null
+++ b/src/wallet_sqlite.h
@@ -0,0 +1,120 @@
+// Copyright (c) 2026 Bitflash developers
+// Distributed under the MIT/X11 software license.
+
+#ifndef BITFLASH_WALLET_SQLITE_H
+#define BITFLASH_WALLET_SQLITE_H
+
+#include <sqlite3.h>
+
+class CWalletRecordVisitor;
+
+class CWalletDBSQLite
+{
+public:
+    CWalletDBSQLite();
+    ~CWalletDBSQLite();
+
+    bool Open(const string& strPath, string& strError);
+    bool OpenReadOnly(const string& strPath, string& strError);
+    void Close();
+
+    bool BeginTransaction(string& strError);
+    bool CommitTransaction(string& strError);
+    bool RollbackTransaction(string& strError);
+    bool Checkpoint(string& strError);
+
+    bool WriteRecord(const vector<unsigned char>& vchKey,
+                     const vector<unsigned char>& vchValue,
+                     string& strError,
+                     bool fOverwrite=true);
+    bool ReadRecord(const vector<unsigned char>& vchKey,
+                    vector<unsigned char>& vchValueRet,
+                    string& strError);
+    bool EraseRecord(const vector<unsigned char>& vchKey,
+                     string& strError);
+    bool ScanRecords(CWalletRecordVisitor& visitor, string& strError);
+    bool CountRecords(int& nRecordsRet, string& strError);
+
+    template<typename K, typename T>
+    bool WriteTypedRecord(const K& key, const T& value, string& strError,
+                          bool fOverwrite=true)
+    {
+        CDataStream ssKey(SER_DISK);
+        ssKey.reserve(1000);
+        ssKey << key;
+
+        CDataStream ssValue(SER_DISK);
+        ssValue.reserve(10000);
+        ssValue << value;
+
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+        vector<unsigned char> vchValue(ssValue.begin(), ssValue.end());
+        bool fOk = WriteRecord(vchKey, vchValue, strError, fOverwrite);
+
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!vchValue.empty())
+            memset(&vchValue[0], 0, vchValue.size());
+        if (!ssKey.empty())
+            memset(&ssKey[0], 0, ssKey.size());
+        if (!ssValue.empty())
+            memset(&ssValue[0], 0, ssValue.size());
+        return fOk;
+    }
+
+    template<typename K, typename T>
+    bool ReadTypedRecord(const K& key, T& valueRet, string& strError)
+    {
+        CDataStream ssKey(SER_DISK);
+        ssKey.reserve(1000);
+        ssKey << key;
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+
+        vector<unsigned char> vchValue;
+        bool fOk = ReadRecord(vchKey, vchValue, strError);
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!ssKey.empty())
+            memset(&ssKey[0], 0, ssKey.size());
+        if (!fOk)
+            return false;
+
+        CDataStream ssValue(vchValue, SER_DISK);
+        ssValue >> valueRet;
+        bool fReadOk = !ssValue.fail();
+        if (!vchValue.empty())
+            memset(&vchValue[0], 0, vchValue.size());
+        if (!ssValue.empty())
+            memset(&ssValue[0], 0, ssValue.size());
+        if (!fReadOk)
+            strError = "SQLite wallet record could not be deserialized";
+        return fReadOk;
+    }
+
+    template<typename K>
+    bool EraseTypedRecord(const K& key, string& strError)
+    {
+        CDataStream ssKey(SER_DISK);
+        ssKey.reserve(1000);
+        ssKey << key;
+        vector<unsigned char> vchKey(ssKey.begin(), ssKey.end());
+
+        bool fOk = EraseRecord(vchKey, strError);
+        if (!vchKey.empty())
+            memset(&vchKey[0], 0, vchKey.size());
+        if (!ssKey.empty())
+            memset(&ssKey[0], 0, ssKey.size());
+        return fOk;
+    }
+
+private:
+    sqlite3* pdb;
+
+    bool Exec(const char* pszSql, string& strError);
+    bool InitSchema(string& strError);
+
+    CWalletDBSQLite(const CWalletDBSQLite&);
+    void operator=(const CWalletDBSQLite&);
+};
+
+#endif
diff --git a/src/walletcmd.cpp b/src/walletcmd.cpp
index 06f35a5..f59fc0c 100644
--- a/src/walletcmd.cpp
+++ b/src/walletcmd.cpp
@@ -12,6 +12,7 @@
 #include "headers_core.h"
 #include "bip32.h"
 #include "walletcmd.h"
+#include "wallet_sqlite.h"
 
 #undef printf
 
@@ -54,6 +55,37 @@ bool RestoreScanReachedDepth(int nSchema,
     return nLegacyNext >= nDepth;
 }
 
+unsigned int WalletLastUsedPubKeyIndexNext(
+    const std::map<unsigned int, std::vector<unsigned char> >& mapPubKeysByIndex)
+{
+    std::map<std::vector<unsigned char>, unsigned int> mapIndexByPubKey;
+    for (std::map<unsigned int, std::vector<unsigned char> >::const_iterator it =
+             mapPubKeysByIndex.begin();
+         it != mapPubKeysByIndex.end(); ++it)
+        mapIndexByPubKey[it->second] = it->first;
+
+    unsigned int nNext = 0;
+    CRITICAL_BLOCK(cs_mapWallet)
+    {
+        for (map<uint256, CWalletTx>::iterator it = mapWallet.begin();
+             it != mapWallet.end(); ++it)
+        {
+            CWalletTx& wtx = (*it).second;
+            for (int i = 0; i < (int)wtx.vout.size(); i++)
+            {
+                vector<unsigned char> vchPubKey;
+                if (!ExtractPubKey(wtx.vout[i].scriptPubKey, false, vchPubKey))
+                    continue;
+                std::map<std::vector<unsigned char>, unsigned int>::const_iterator mi =
+                    mapIndexByPubKey.find(vchPubKey);
+                if (mi != mapIndexByPubKey.end() && mi->second + 1 > nNext)
+                    nNext = mi->second + 1;
+            }
+        }
+    }
+    return nNext;
+}
+
 int CmdNewPhrase()
 {
     AttachTerminal();
@@ -132,7 +164,10 @@ bool RestoreFromPhrase(const std::string& strMnemonic,
     // Derive forward in batches, scanning after each, until a whole batch turns
     // up nothing. Every derived key is written to the wallet before the scan,
     // because the scan asks the wallet what belongs to it.
-    int nTotalDerived = nHDKeySchema == HD_SCHEMA_BIP44
+    const bool fRestoreBIP44 = nHDKeySchema == HD_SCHEMA_BIP44;
+    unsigned int nLegacyScanNext = nHDNext;
+    std::map<unsigned int, vector<unsigned char> > mapLegacyScanPubKeys;
+    int nTotalDerived = fRestoreBIP44
         ? (int)(nHDReceiveNext + nHDChangeNext)
         : (int)nHDNext;
     int nStopDepth = max(nMinDepth, RESTORE_MIN_SCAN);
@@ -151,7 +186,7 @@ bool RestoreFromPhrase(const std::string& strMnemonic,
             nWalletBefore = mapWallet.size();
 
         std::string strDeriveError;
-        if (nHDKeySchema == HD_SCHEMA_BIP44)
+        if (fRestoreBIP44)
         {
             for (int i = 0; i < RESTORE_BATCH; i++)
             {
@@ -182,15 +217,15 @@ bool RestoreFromPhrase(const std::string& strMnemonic,
             for (int i = 0; i < RESTORE_BATCH; i++)
             {
                 CKey key;
-                if (!DeriveHDKey(nHDNext, key, strDeriveError))
+                if (!DeriveHDKey(nLegacyScanNext, key, strDeriveError))
                     break;
                 if (!AddKey(key))
                     break;
-                nHDNext++;
+                mapLegacyScanPubKeys[nLegacyScanNext] = key.GetPubKey();
+                nLegacyScanNext++;
                 nTotalDerived++;
             }
             nHDKeySchema = nSavedSchema;
-            CWalletDB().WriteHDNext(nHDNext);
         }
         else
         {
@@ -209,6 +244,22 @@ bool RestoreFromPhrase(const std::string& strMnemonic,
 
         ScanForWalletTransactions(pindexGenesisBlock);
 
+        if (fRestoreBIP44)
+        {
+            // The legacy branch is scanned only for compatibility with phrases
+            // created before BIP44. Persist the last used legacy index + 1, not
+            // the lookahead depth. Otherwise a restore with no legacy hits can
+            // leave hdnext at RESTORE_MAX and make future compatibility scans
+            // look exhausted even though no legacy key was ever used.
+            unsigned int nLegacyUsedNext =
+                WalletLastUsedPubKeyIndexNext(mapLegacyScanPubKeys);
+            if (nLegacyUsedNext != nHDNext)
+            {
+                nHDNext = nLegacyUsedNext;
+                CWalletDB().WriteHDNext(nHDNext);
+            }
+        }
+
         size_t nWalletAfter = 0;
         CRITICAL_BLOCK(cs_mapWallet)
             nWalletAfter = mapWallet.size();
@@ -239,7 +290,7 @@ bool RestoreFromPhrase(const std::string& strMnemonic,
             RestoreScanReachedDepth(nHDKeySchema,
                                     nHDReceiveNext,
                                     nHDChangeNext,
-                                    nHDNext,
+                                    fRestoreBIP44 ? nLegacyScanNext : nHDNext,
                                     nStopDepth))
             break;
     }
@@ -350,11 +401,16 @@ int CmdRecoveryAudit()
     int64 nImmatureTotal = audit.nRecoverableImmatureCredit + audit.nLegacyImmatureCredit;
 
     printf("Wallet recovery audit\n");
-    printf("  recovery phrase: %s\n", audit.fHaveSeed ? "present" : "not installed");
+    if (audit.fHaveSeed)
+        printf("  recovery phrase: present\n");
+    else if (audit.fSeedEncryptedLocked)
+        printf("  recovery phrase: encrypted, unlock wallet to audit\n");
+    else
+        printf("  recovery phrase: not installed\n");
     if (audit.fHaveSeed)
     {
         printf("  derivation schema: %s\n", HDKeySchemaName(audit.nSchema).c_str());
-        printf("  BIP44 coin type: %u (provisional BITFLASH)\n", audit.nCoinType);
+        printf("  BIP44 coin type: %u (SLIP-0044 BITFLASH)\n", audit.nCoinType);
         printf("  derived keys known to this wallet: %u\n", audit.nDerivedKnown);
         printf("  receive/change counters: %u/%u\n",
                audit.nReceiveNext, audit.nChangeNext);
@@ -362,15 +418,24 @@ int CmdRecoveryAudit()
     if (!audit.fDeriveComplete)
         printf("  derivation warning: %s\n", audit.strDeriveError.c_str());
     printf("  total spendable balance:      %s BTF\n", FormatMoney(nTotal).c_str());
+    if (audit.fSeedEncryptedLocked)
+    {
+        printf("  recovery coverage:            unavailable while wallet is locked\n");
+        printf("  immature mining rewards:      %s BTF\n", FormatMoney(nImmatureTotal).c_str());
+        printf("\n");
+        printf("Unlock the wallet with /walletpassphrase or /walletpassphrase=@FILE to audit phrase coverage.\n");
+        fflush(stdout);
+        return 2;
+    }
     printf("  covered by recovery phrase:   %s BTF (%d transaction(s))\n",
            FormatMoney(audit.nRecoverableCredit).c_str(), audit.nRecoverableTx);
-    printf("  wallet.dat-only balance:      %s BTF (%d transaction(s))\n",
+    printf("  not phrase-backed balance:    %s BTF (%d transaction(s))\n",
            FormatMoney(audit.nLegacyCredit).c_str(), audit.nLegacyTx);
     printf("  immature mining rewards:      %s BTF\n", FormatMoney(nImmatureTotal).c_str());
     printf("    phrase-backed immature:     %s BTF (%d transaction(s))\n",
            FormatMoney(audit.nRecoverableImmatureCredit).c_str(),
            audit.nRecoverableImmatureTx);
-    printf("    wallet.dat-only immature:   %s BTF (%d transaction(s))\n",
+    printf("    not phrase-backed immature: %s BTF (%d transaction(s))\n",
            FormatMoney(audit.nLegacyImmatureCredit).c_str(),
            audit.nLegacyImmatureTx);
 
@@ -392,7 +457,7 @@ int CmdRecoveryAudit()
     {
         printf("\n");
         printf("Warning: some coins are on keys the phrase does not reproduce.\n");
-        printf("Keep wallet.dat backups until that balance has been moved to a phrase-backed address.\n");
+        printf("Keep a file backup of this wallet until that balance has been moved to a phrase-backed address.\n");
         fflush(stdout);
         return 2;
     }
@@ -406,10 +471,952 @@ int CmdRecoveryAudit()
     return 0;
 }
 
+struct WalletStorageAuditCounts
+{
+    unsigned int nTotal = 0;
+    unsigned int nMalformed = 0;
+    unsigned int nUnknown = 0;
+    unsigned int nVersion = 0;
+    unsigned int nNames = 0;
+    unsigned int nTransactions = 0;
+    unsigned int nPlainKeys = 0;
+    unsigned int nEncryptedKeys = 0;
+    unsigned int nMasterKeys = 0;
+    unsigned int nDefaultKey = 0;
+    unsigned int nPlainHDMaster = 0;
+    unsigned int nPlainHDChainCode = 0;
+    unsigned int nCryptedHDMaster = 0;
+    unsigned int nCryptedHDChainCode = 0;
+    unsigned int nWalletMinVersion = 0;
+    unsigned int nPool = 0;
+    unsigned int nSettings = 0;
+    unsigned int nHDNext = 0;
+    unsigned int nHDSchema = 0;
+    unsigned int nHDCoinType = 0;
+    unsigned int nHDReceiveNext = 0;
+    unsigned int nHDChangeNext = 0;
+};
+
+static std::string HDSeedStorageState(unsigned int nMaster, unsigned int nChain)
+{
+    if (nMaster == 0 && nChain == 0)
+        return "none";
+    if (nMaster > 0 && nChain > 0)
+        return "complete";
+    return "incomplete";
+}
+
+static void CountWalletStorageType(const std::string& strType,
+                                   WalletStorageAuditCounts& c)
+{
+    if (strType == "version")
+        c.nVersion++;
+    else if (strType == "name")
+        c.nNames++;
+    else if (strType == "tx")
+        c.nTransactions++;
+    else if (strType == "key")
+        c.nPlainKeys++;
+    else if (strType == "ckey")
+        c.nEncryptedKeys++;
+    else if (strType == "mkey")
+        c.nMasterKeys++;
+    else if (strType == "defaultkey")
+        c.nDefaultKey++;
+    else if (strType == "hdmaster")
+        c.nPlainHDMaster++;
+    else if (strType == "hdchaincode")
+        c.nPlainHDChainCode++;
+    else if (strType == "cryptedhdmaster")
+        c.nCryptedHDMaster++;
+    else if (strType == "cryptedhdchaincode")
+        c.nCryptedHDChainCode++;
+    else if (strType == "walletminversion")
+        c.nWalletMinVersion++;
+    else if (strType == "pool")
+        c.nPool++;
+    else if (strType == "setting")
+        c.nSettings++;
+    else if (strType == "hdnext")
+        c.nHDNext++;
+    else if (strType == "hdschema")
+        c.nHDSchema++;
+    else if (strType == "hdcointype")
+        c.nHDCoinType++;
+    else if (strType == "hdreceivenext")
+        c.nHDReceiveNext++;
+    else if (strType == "hdchangenext")
+        c.nHDChangeNext++;
+    else
+        c.nUnknown++;
+}
+
+static bool ReadWalletStorageCounts(WalletStorageAuditCounts& counts,
+                                    std::string& strError)
+{
+    class CWalletStorageCountVisitor : public CWalletRecordVisitor
+    {
+    public:
+        WalletStorageAuditCounts& counts;
+
+        explicit CWalletStorageCountVisitor(WalletStorageAuditCounts& countsIn)
+            : counts(countsIn) { }
+
+        bool VisitWalletRecord(const CDataStream& ssKeyIn,
+                               const CDataStream& ssValue,
+                               std::string& strErrorRet)
+        {
+            (void)ssValue;
+            (void)strErrorRet;
+            counts.nTotal++;
+            try
+            {
+                CDataStream ssKey = ssKeyIn;
+                std::string strType;
+                ssKey >> strType;
+                if (ssKey.fail())
+                {
+                    counts.nMalformed++;
+                    return true;
+                }
+                CountWalletStorageType(strType, counts);
+            }
+            catch (...)
+            {
+                counts.nMalformed++;
+            }
+            return true;
+        }
+    };
+
+    CWalletStorageCountVisitor visitor(counts);
+    return ScanWalletRecords(visitor, strError);
+}
+
+static std::string WalletStorageAuditJson(const WalletStorageAuditCounts& counts)
+{
+    std::string strJson;
+    strJson += "{\n";
+    strJson += "  \"format\": \"bitflash-wallet-storage-audit-v1\",\n";
+    strJson += strprintf("  \"records_total\": %u,\n", counts.nTotal);
+    strJson += strprintf("  \"malformed_records\": %u,\n", counts.nMalformed);
+    strJson += strprintf("  \"unknown_records\": %u,\n", counts.nUnknown);
+    strJson += strprintf("  \"plain_private_keys\": %u,\n", counts.nPlainKeys);
+    strJson += strprintf("  \"encrypted_private_keys\": %u,\n", counts.nEncryptedKeys);
+    strJson += strprintf("  \"encryption_master_keys\": %u,\n", counts.nMasterKeys);
+    strJson += strprintf("  \"default_public_key\": \"%s\",\n",
+                          counts.nDefaultKey ? "present" : "none");
+    strJson += strprintf("  \"plain_hd_seed\": \"%s\",\n",
+                          HDSeedStorageState(counts.nPlainHDMaster,
+                                             counts.nPlainHDChainCode).c_str());
+    strJson += strprintf("  \"encrypted_hd_seed\": \"%s\",\n",
+                          HDSeedStorageState(counts.nCryptedHDMaster,
+                                             counts.nCryptedHDChainCode).c_str());
+    strJson += strprintf("  \"wallet_minimum_version\": \"%s\",\n",
+                          counts.nWalletMinVersion ? "present" : "none");
+    strJson += strprintf("  \"keypool_entries\": %u,\n", counts.nPool);
+    strJson += strprintf("  \"wallet_transactions\": %u,\n", counts.nTransactions);
+    strJson += strprintf("  \"address_book_labels\": %u,\n", counts.nNames);
+    strJson += strprintf("  \"settings\": %u,\n", counts.nSettings);
+    strJson += strprintf("  \"hd_metadata_records\": %u,\n",
+                          counts.nHDNext + counts.nHDSchema + counts.nHDCoinType +
+                          counts.nHDReceiveNext + counts.nHDChangeNext);
+    strJson += strprintf("  \"database_version_records\": %u\n", counts.nVersion);
+    strJson += "}\n";
+    return strJson;
+}
+
+static bool WriteAuditTextFile(const std::string& strPath,
+                               const std::string& strText,
+                               std::string& strError)
+{
+    FILE* pf = fopen(strPath.c_str(), "wb");
+    if (!pf)
+    {
+        strError = "cannot open output file";
+        return false;
+    }
+    size_t nWritten = fwrite(strText.data(), 1, strText.size(), pf);
+    bool fCloseOk = fclose(pf) == 0;
+    if (nWritten != strText.size() || !fCloseOk)
+    {
+        strError = "could not write the complete output file";
+        return false;
+    }
+    return true;
+}
+
+static void AddWalletStorageFailure(std::vector<std::string>& vFailures,
+                                    const std::string& strFailure)
+{
+    vFailures.push_back(strFailure);
+}
+
+static void BuildWalletStorageSanityFailures(const WalletStorageAuditCounts& counts,
+                                             std::vector<std::string>& vFailures)
+{
+    bool fPlainHD = counts.nPlainHDMaster > 0 || counts.nPlainHDChainCode > 0;
+    bool fCryptedHD = counts.nCryptedHDMaster > 0 || counts.nCryptedHDChainCode > 0;
+    bool fEncryptedRecords = counts.nEncryptedKeys > 0 ||
+                             counts.nMasterKeys > 0 ||
+                             fCryptedHD;
+
+    if (counts.nMalformed > 0)
+        AddWalletStorageFailure(vFailures, "wallet.dat contains malformed records");
+    if (counts.nUnknown > 0)
+        AddWalletStorageFailure(vFailures, "wallet.dat contains unknown records");
+    if ((counts.nPlainHDMaster > 0) != (counts.nPlainHDChainCode > 0))
+        AddWalletStorageFailure(vFailures, "plain HD seed is incomplete");
+    if ((counts.nCryptedHDMaster > 0) != (counts.nCryptedHDChainCode > 0))
+        AddWalletStorageFailure(vFailures, "encrypted HD seed is incomplete");
+    if (fPlainHD && fCryptedHD)
+        AddWalletStorageFailure(vFailures, "wallet.dat contains both plain and encrypted HD seed records");
+    if (counts.nDefaultKey > 1)
+        AddWalletStorageFailure(vFailures, "wallet.dat contains more than one default public key record");
+    if (counts.nWalletMinVersion > 1)
+        AddWalletStorageFailure(vFailures, "wallet.dat contains more than one minimum-version record");
+
+    if (fEncryptedRecords)
+    {
+        if (counts.nPlainKeys > 0)
+            AddWalletStorageFailure(vFailures, "encrypted wallet still contains plain private key records");
+        if (fPlainHD)
+            AddWalletStorageFailure(vFailures, "encrypted wallet still contains plain HD seed records");
+        if (counts.nMasterKeys == 0)
+            AddWalletStorageFailure(vFailures, "encrypted wallet has no encryption master key record");
+        if (counts.nWalletMinVersion == 0)
+            AddWalletStorageFailure(vFailures, "encrypted wallet has no minimum-version record");
+    }
+}
+
+int CmdWalletStorageCheck()
+{
+    AttachTerminal();
+
+    WalletStorageAuditCounts counts;
+    std::string strError;
+    if (!ReadWalletStorageCounts(counts, strError))
+    {
+        fprintf(stderr, "Cannot check wallet storage: %s\n", strError.c_str());
+        return 1;
+    }
+
+    std::vector<std::string> vFailures;
+    BuildWalletStorageSanityFailures(counts, vFailures);
+
+    printf("Wallet storage sanity check\n");
+    printf("  records total:             %u\n", counts.nTotal);
+    printf("  encrypted records:         %s\n",
+           (counts.nEncryptedKeys || counts.nMasterKeys ||
+            counts.nCryptedHDMaster || counts.nCryptedHDChainCode) ? "yes" : "no");
+    printf("  plain private keys:        %u\n", counts.nPlainKeys);
+    printf("  encrypted private keys:    %u\n", counts.nEncryptedKeys);
+    printf("  plain HD seed:             %s\n",
+           HDSeedStorageState(counts.nPlainHDMaster,
+                              counts.nPlainHDChainCode).c_str());
+    printf("  encrypted HD seed:         %s\n",
+           HDSeedStorageState(counts.nCryptedHDMaster,
+                              counts.nCryptedHDChainCode).c_str());
+    if (vFailures.empty())
+    {
+        printf("  storage sanity:            ok\n");
+        fflush(stdout);
+        return 0;
+    }
+
+    printf("  storage sanity:            failed\n");
+    for (std::vector<std::string>::const_iterator it = vFailures.begin();
+         it != vFailures.end(); ++it)
+        printf("  failure:                   %s\n", it->c_str());
+    fflush(stdout);
+    return 2;
+}
+
+int CmdWalletStorageAudit(const std::string& strJsonOut)
+{
+    AttachTerminal();
+
+    WalletStorageAuditCounts counts;
+    std::string strError;
+    if (!ReadWalletStorageCounts(counts, strError))
+    {
+        fprintf(stderr, "Cannot audit wallet storage: %s\n", strError.c_str());
+        return 1;
+    }
+
+    if (!strJsonOut.empty())
+    {
+        std::string strWriteError;
+        if (!WriteAuditTextFile(strJsonOut,
+                                WalletStorageAuditJson(counts),
+                                strWriteError))
+        {
+            fprintf(stderr, "Cannot write wallet storage audit JSON: %s\n",
+                    strWriteError.c_str());
+            return 1;
+        }
+        printf("Wallet storage audit written to %s\n", strJsonOut.c_str());
+        fflush(stdout);
+        return counts.nMalformed > 0 ? 2 : 0;
+    }
+
+    printf("Wallet storage audit\n");
+    printf("  records total:             %u\n", counts.nTotal);
+    printf("  malformed records:         %u\n", counts.nMalformed);
+    printf("  unknown records:           %u\n", counts.nUnknown);
+    printf("  plain private keys:        %u\n", counts.nPlainKeys);
+    printf("  encrypted private keys:    %u\n", counts.nEncryptedKeys);
+    printf("  encryption master keys:    %u\n", counts.nMasterKeys);
+    printf("  default public key:        %s\n", counts.nDefaultKey ? "present" : "none");
+    printf("  plain HD seed:             %s\n",
+           HDSeedStorageState(counts.nPlainHDMaster,
+                              counts.nPlainHDChainCode).c_str());
+    printf("  encrypted HD seed:         %s\n",
+           HDSeedStorageState(counts.nCryptedHDMaster,
+                              counts.nCryptedHDChainCode).c_str());
+    printf("  wallet minimum version:    %s\n",
+           counts.nWalletMinVersion ? "present" : "none");
+    printf("  keypool entries:           %u\n", counts.nPool);
+    printf("  wallet transactions:       %u\n", counts.nTransactions);
+    printf("  address book labels:       %u\n", counts.nNames);
+    printf("  settings:                  %u\n", counts.nSettings);
+    printf("  HD metadata records:       %u\n",
+           counts.nHDNext + counts.nHDSchema + counts.nHDCoinType +
+           counts.nHDReceiveNext + counts.nHDChangeNext);
+    printf("  database version records:  %u\n", counts.nVersion);
+    fflush(stdout);
+
+    if (counts.nMalformed > 0)
+        return 2;
+    return 0;
+}
+
+static vector<unsigned char> DataStreamBytesLocal(const CDataStream& ss)
+{
+    return vector<unsigned char>(ss.begin(), ss.end());
+}
+
+namespace {
+
+static void RemoveSQLiteExportFiles(const string& strPath)
+{
+    remove(strPath.c_str());
+    remove((strPath + "-wal").c_str());
+    remove((strPath + "-shm").c_str());
+}
+
+static void RemoveFailedRestoreWallet(const string& strWalletPath)
+{
+    DBFlush(true);
+    remove(strWalletPath.c_str());
+}
+
+class CWalletSQLiteExportVisitor : public CWalletRecordVisitor
+{
+public:
+    CWalletDBSQLite& db;
+    int& nCopied;
+
+    CWalletSQLiteExportVisitor(CWalletDBSQLite& dbIn, int& nCopiedIn)
+        : db(dbIn), nCopied(nCopiedIn) { }
+
+    bool VisitWalletRecord(const CDataStream& ssKey,
+                           const CDataStream& ssValue,
+                           string& strErrorRet)
+    {
+        if (!db.WriteRecord(DataStreamBytesLocal(ssKey),
+                            DataStreamBytesLocal(ssValue),
+                            strErrorRet))
+            return false;
+        nCopied++;
+        return true;
+    }
+};
+
+class CWalletRecordMapVisitor : public CWalletRecordVisitor
+{
+public:
+    std::map<vector<unsigned char>, vector<unsigned char> >& mapRecords;
+
+    explicit CWalletRecordMapVisitor(
+        std::map<vector<unsigned char>, vector<unsigned char> >& mapRecordsIn)
+        : mapRecords(mapRecordsIn) { }
+
+    bool VisitWalletRecord(const CDataStream& ssKey,
+                           const CDataStream& ssValue,
+                           string& strErrorRet)
+    {
+        vector<unsigned char> vchKey = DataStreamBytesLocal(ssKey);
+        if (mapRecords.count(vchKey))
+        {
+            strErrorRet = "duplicate serialized wallet key";
+            return false;
+        }
+        mapRecords[vchKey] = DataStreamBytesLocal(ssValue);
+        return true;
+    }
+};
+
+class CWalletRawRestoreDB : public CWalletDB
+{
+public:
+    CWalletRawRestoreDB(const char* pszMode="cr+", bool fTxn=true)
+        : CWalletDB(pszMode, fTxn) { }
+
+    bool WriteRaw(CDataStream ssKey, CDataStream ssValue)
+    {
+        if (!pdb || ssKey.empty())
+            return false;
+
+        Dbt datKey((void*)&ssKey[0], ssKey.size());
+        Dbt datValue(ssValue.empty() ? NULL : (void*)&ssValue[0],
+                     ssValue.size());
+        int ret = pdb->put(GetTxn(), &datKey, &datValue, 0);
+
+        memset(datKey.get_data(), 0, datKey.get_size());
+        if (datValue.get_data())
+            memset(datValue.get_data(), 0, datValue.get_size());
+        return ret == 0;
+    }
+};
+
+class CWalletSQLiteRestoreVisitor : public CWalletRecordVisitor
+{
+public:
+    CWalletRawRestoreDB& db;
+    int& nCopied;
+
+    CWalletSQLiteRestoreVisitor(CWalletRawRestoreDB& dbIn, int& nCopiedIn)
+        : db(dbIn), nCopied(nCopiedIn) { }
+
+    bool VisitWalletRecord(const CDataStream& ssKey,
+                           const CDataStream& ssValue,
+                           string& strErrorRet)
+    {
+        if (!db.WriteRaw(ssKey, ssValue))
+        {
+            strErrorRet = "could not write raw wallet record";
+            return false;
+        }
+        nCopied++;
+        return true;
+    }
+};
+
+class CWalletSQLiteLoadCheckVisitor : public CWalletRecordVisitor
+{
+public:
+    int nRecords;
+    int nUnknown;
+    string strFailure;
+
+    CWalletSQLiteLoadCheckVisitor() : nRecords(0), nUnknown(0) { }
+
+    bool Fail(const string& strMessage, string& strErrorRet)
+    {
+        strFailure = strMessage;
+        strErrorRet = strMessage;
+        return false;
+    }
+
+    bool VisitWalletRecord(const CDataStream& ssKeyIn,
+                           const CDataStream& ssValueIn,
+                           string& strErrorRet)
+    {
+        nRecords++;
+        try
+        {
+            CDataStream ssKey = ssKeyIn;
+            CDataStream ssValue = ssValueIn;
+            string strType;
+            ssKey >> strType;
+            if (ssKey.fail())
+                return Fail("malformed wallet record key", strErrorRet);
+
+            if (strType == "name")
+            {
+                string strAddress;
+                string strName;
+                ssKey >> strAddress;
+                ssValue >> strName;
+            }
+            else if (strType == "tx")
+            {
+                uint256 hash;
+                CWalletTx wtx;
+                ssKey >> hash;
+                ssValue >> wtx;
+            }
+            else if (strType == "key")
+            {
+                vector<unsigned char> vchPubKey;
+                CPrivKey vchPrivKey;
+                ssKey >> vchPubKey;
+                ssValue >> vchPrivKey;
+            }
+            else if (strType == "mkey")
+            {
+                unsigned int nID = 0;
+                CWalletMasterKey kMasterKey;
+                ssKey >> nID;
+                ssValue >> kMasterKey;
+            }
+            else if (strType == "ckey")
+            {
+                vector<unsigned char> vchPubKey;
+                vector<unsigned char> vchCryptedSecret;
+                ssKey >> vchPubKey;
+                ssValue >> vchCryptedSecret;
+            }
+            else if (strType == "defaultkey" ||
+                     strType == "hdmaster" ||
+                     strType == "hdchaincode" ||
+                     strType == "cryptedhdmaster" ||
+                     strType == "cryptedhdchaincode")
+            {
+                vector<unsigned char> vch;
+                ssValue >> vch;
+            }
+            else if (strType == "hdnext" ||
+                     strType == "hdreceivenext" ||
+                     strType == "hdchangenext" ||
+                     strType == "hdcointype")
+            {
+                unsigned int nValue = 0;
+                ssValue >> nValue;
+            }
+            else if (strType == "hdschema")
+            {
+                int nSchema = 0;
+                ssValue >> nSchema;
+                if (!ssValue.fail() &&
+                    nSchema != HD_SCHEMA_NONE &&
+                    nSchema != HD_SCHEMA_LEGACY &&
+                    nSchema != HD_SCHEMA_BIP44)
+                    return Fail("unsupported deterministic wallet schema",
+                                strErrorRet);
+            }
+            else if (strType == "walletminversion")
+            {
+                int nMinVersion = 0;
+                ssValue >> nMinVersion;
+                if (!ssValue.fail() && nMinVersion > WALLET_FORMAT_SUPPORTED)
+                    return Fail("unsupported future wallet format", strErrorRet);
+            }
+            else if (strType == "pool")
+            {
+                int64 nIndex = 0;
+                vector<unsigned char> vchPubKey;
+                ssKey >> nIndex;
+                ssValue >> vchPubKey;
+            }
+            else if (strType == "setting")
+            {
+                string strKey;
+                ssKey >> strKey;
+                if (strKey == "nTransactionFee")
+                {
+                    int64 nValue = 0;
+                    ssValue >> nValue;
+                }
+                else if (strKey == "addrIncoming")
+                {
+                    CAddress addr;
+                    ssValue >> addr;
+                }
+                else if (strKey == "nMineMode")
+                {
+                    int nValue = 0;
+                    ssValue >> nValue;
+                }
+                else if (strKey == "fGenerateBitcoins")
+                {
+                    int fValue = 0;
+                    ssValue >> fValue;
+                }
+                else if (strKey == "strParticipantPool")
+                {
+                    string strValue;
+                    ssValue >> strValue;
+                }
+            }
+            else if (strType == "version")
+            {
+                int nVersion = 0;
+                ssValue >> nVersion;
+            }
+            else
+            {
+                nUnknown++;
+            }
+
+            if (ssKey.fail())
+                return Fail("malformed wallet record key", strErrorRet);
+            if (ssValue.fail())
+                return Fail("malformed wallet record value", strErrorRet);
+        }
+        catch (const std::exception& e)
+        {
+            return Fail(strprintf("wallet record parse exception: %s", e.what()),
+                        strErrorRet);
+        }
+        catch (...)
+        {
+            return Fail("wallet record parse exception", strErrorRet);
+        }
+        return true;
+    }
+};
+
+} // namespace
+
+// Export the currently-loaded wallet to a SQLite file. Shared by the
+// -walletsqliteexport command and the GUI conversion wizard: opens the
+// destination, copies every record inside one transaction, checkpoints, and
+// verifies the stored count matches. Returns false with strErrorRet set on any
+// failure and leaves no partial file behind; the source wallet is only read.
+bool ExportActiveWalletToSQLite(const std::string& strDest, int& nCopiedRet,
+                                std::string& strErrorRet)
+{
+    nCopiedRet = 0;
+    if (strDest.empty())
+    {
+        strErrorRet = "no SQLite export path was given";
+        return false;
+    }
+    if (FileExists(strDest.c_str()))
+    {
+        strErrorRet = strprintf("refusing to overwrite existing file: %s", strDest.c_str());
+        return false;
+    }
+
+    CWalletDBSQLite db;
+    if (!db.Open(strDest, strErrorRet))
+    {
+        RemoveSQLiteExportFiles(strDest);
+        return false;
+    }
+    if (!db.BeginTransaction(strErrorRet))
+    {
+        db.Close();
+        RemoveSQLiteExportFiles(strDest);
+        return false;
+    }
+
+    CWalletSQLiteExportVisitor visitor(db, nCopiedRet);
+    if (!ScanWalletRecords(visitor, strErrorRet))
+    {
+        string strRollbackError;
+        db.RollbackTransaction(strRollbackError);
+        db.Close();
+        RemoveSQLiteExportFiles(strDest);
+        return false;
+    }
+    if (!db.CommitTransaction(strErrorRet) || !db.Checkpoint(strErrorRet))
+    {
+        db.Close();
+        RemoveSQLiteExportFiles(strDest);
+        return false;
+    }
+
+    int nCount = 0;
+    if (!db.CountRecords(nCount, strErrorRet))
+    {
+        db.Close();
+        RemoveSQLiteExportFiles(strDest);
+        return false;
+    }
+    if (nCount != nCopiedRet)
+    {
+        strErrorRet = strprintf("export count mismatch: copied %d, stored %d",
+                                nCopiedRet, nCount);
+        db.Close();
+        RemoveSQLiteExportFiles(strDest);
+        return false;
+    }
+    db.Close();
+    return true;
+}
+
+// Convert the running Berkeley DB wallet to SQLite for the GUI wizard: export
+// wallet.dat to <datadir>/wallet.sqlite, then record the backend marker so the
+// next start opens SQLite. wallet.dat is never modified -- it stays as the
+// fallback. Refuses if already on SQLite or if a wallet.sqlite already exists.
+bool DoConvertWalletToSQLite(int& nCopiedRet, std::string& strErrorRet)
+{
+    nCopiedRet = 0;
+    if (WalletSQLiteRuntimeActive())
+    {
+        strErrorRet = "this wallet is already on the SQLite backend";
+        return false;
+    }
+    string strDest = GetAppDir() + "/wallet.sqlite";
+    if (FileExists(strDest.c_str()))
+    {
+        strErrorRet = strprintf("a SQLite wallet already exists at %s", strDest.c_str());
+        return false;
+    }
+    if (!ExportActiveWalletToSQLite(strDest, nCopiedRet, strErrorRet))
+        return false;
+    if (!WriteWalletBackendMarker("sqlite"))
+    {
+        strErrorRet = "the wallet was exported but the backend choice could not be saved";
+        return false;
+    }
+    return true;
+}
+
+int CmdWalletSQLiteExport(const std::string& strDest)
+{
+    AttachTerminal();
+
+    // Keep the command's own specific messages for the two conditions the
+    // shared helper folds into a generic error, so scripts and the tests that
+    // read this output see the same wording as before.
+    if (strDest.empty())
+    {
+        fprintf(stderr, "Missing SQLite wallet export path.\n");
+        return 1;
+    }
+    if (FileExists(strDest.c_str()))
+    {
+        fprintf(stderr, "Refusing to overwrite existing SQLite wallet export: %s\n",
+                strDest.c_str());
+        return 1;
+    }
+
+    int nCopied = 0;
+    string strError;
+    if (!ExportActiveWalletToSQLite(strDest, nCopied, strError))
+    {
+        fprintf(stderr, "Cannot export wallet to SQLite: %s\n", strError.c_str());
+        return 1;
+    }
+
+    printf("SQLite wallet export written to %s\n", strDest.c_str());
+    printf("  records copied:            %d\n", nCopied);
+    fflush(stdout);
+    return 0;
+}
+
+int CmdWalletSQLiteVerify(const std::string& strPath)
+{
+    AttachTerminal();
+
+    if (strPath.empty())
+    {
+        fprintf(stderr, "Missing SQLite wallet export path.\n");
+        return 1;
+    }
+    if (!FileExists(strPath.c_str()))
+    {
+        fprintf(stderr, "SQLite wallet export does not exist: %s\n",
+                strPath.c_str());
+        return 1;
+    }
+
+    std::map<vector<unsigned char>, vector<unsigned char> > mapBDB;
+    std::map<vector<unsigned char>, vector<unsigned char> > mapSQLite;
+    string strError;
+
+    CWalletRecordMapVisitor bdbVisitor(mapBDB);
+    if (!ScanWalletRecords(bdbVisitor, strError))
+    {
+        fprintf(stderr, "Cannot scan wallet.dat records: %s\n", strError.c_str());
+        return 1;
+    }
+
+    CWalletDBSQLite db;
+    if (!db.Open(strPath, strError))
+    {
+        fprintf(stderr, "Cannot open SQLite wallet export: %s\n", strError.c_str());
+        return 1;
+    }
+    CWalletRecordMapVisitor sqliteVisitor(mapSQLite);
+    if (!db.ScanRecords(sqliteVisitor, strError))
+    {
+        fprintf(stderr, "Cannot scan SQLite wallet export: %s\n", strError.c_str());
+        return 1;
+    }
+
+    int nMissing = 0;
+    int nMismatched = 0;
+    for (std::map<vector<unsigned char>, vector<unsigned char> >::const_iterator it =
+             mapBDB.begin(); it != mapBDB.end(); ++it)
+    {
+        std::map<vector<unsigned char>, vector<unsigned char> >::const_iterator sit =
+            mapSQLite.find(it->first);
+        if (sit == mapSQLite.end())
+            nMissing++;
+        else if (sit->second != it->second)
+            nMismatched++;
+    }
+
+    int nExtra = 0;
+    for (std::map<vector<unsigned char>, vector<unsigned char> >::const_iterator it =
+             mapSQLite.begin(); it != mapSQLite.end(); ++it)
+    {
+        if (!mapBDB.count(it->first))
+            nExtra++;
+    }
+
+    printf("SQLite wallet export verification\n");
+    printf("  wallet.dat records:        %u\n", (unsigned int)mapBDB.size());
+    printf("  SQLite records:            %u\n", (unsigned int)mapSQLite.size());
+    printf("  missing records:           %d\n", nMissing);
+    printf("  extra records:             %d\n", nExtra);
+    printf("  record value mismatches:   %d\n", nMismatched);
+    if (nMissing == 0 && nExtra == 0 && nMismatched == 0)
+    {
+        printf("  verification:              ok\n");
+        fflush(stdout);
+        return 0;
+    }
+
+    printf("  verification:              failed\n");
+    fflush(stdout);
+    return 2;
+}
+
+int CmdWalletSQLiteRestore(const std::string& strPath)
+{
+    AttachTerminal();
+
+    if (strPath.empty())
+    {
+        fprintf(stderr, "Missing SQLite wallet export path.\n");
+        return 1;
+    }
+    if (!FileExists(strPath.c_str()))
+    {
+        fprintf(stderr, "SQLite wallet export does not exist: %s\n",
+                strPath.c_str());
+        return 1;
+    }
+
+    string strWalletPath = GetAppDir() + "/wallet.dat";
+    if (FileExists(strWalletPath.c_str()))
+    {
+        fprintf(stderr, "Refusing to overwrite existing wallet.dat: %s\n",
+                strWalletPath.c_str());
+        return 1;
+    }
+
+    string strError;
+    CWalletDBSQLite sqlite;
+    if (!sqlite.Open(strPath, strError))
+    {
+        fprintf(stderr, "Cannot open SQLite wallet export: %s\n", strError.c_str());
+        return 1;
+    }
+
+    int nSQLiteRecords = 0;
+    if (!sqlite.CountRecords(nSQLiteRecords, strError))
+    {
+        fprintf(stderr, "Cannot count SQLite wallet export records: %s\n",
+                strError.c_str());
+        return 1;
+    }
+    if (nSQLiteRecords <= 0)
+    {
+        fprintf(stderr, "SQLite wallet export contains no records.\n");
+        return 2;
+    }
+
+    CWalletRawRestoreDB bdb("cr+", true);
+    if (!bdb.TxnBegin())
+    {
+        fprintf(stderr, "Cannot begin Berkeley DB restore transaction.\n");
+        return 1;
+    }
+
+    int nCopied = 0;
+    CWalletSQLiteRestoreVisitor visitor(bdb, nCopied);
+    if (!sqlite.ScanRecords(visitor, strError))
+    {
+        bdb.TxnAbort();
+        bdb.Close();
+        RemoveFailedRestoreWallet(strWalletPath);
+        fprintf(stderr, "Cannot restore SQLite wallet export: %s\n",
+                strError.c_str());
+        return 1;
+    }
+    if (nCopied != nSQLiteRecords)
+    {
+        bdb.TxnAbort();
+        bdb.Close();
+        RemoveFailedRestoreWallet(strWalletPath);
+        fprintf(stderr, "SQLite wallet restore copied %d records, expected %d.\n",
+                nCopied, nSQLiteRecords);
+        return 2;
+    }
+    if (!bdb.TxnCommit())
+    {
+        bdb.Close();
+        RemoveFailedRestoreWallet(strWalletPath);
+        fprintf(stderr, "Cannot commit Berkeley DB restore transaction.\n");
+        return 1;
+    }
+
+    printf("SQLite wallet export restored to wallet.dat\n");
+    printf("  records restored:          %d\n", nCopied);
+    fflush(stdout);
+    return 0;
+}
+
+int CmdWalletSQLiteLoadCheck(const std::string& strPath)
+{
+    AttachTerminal();
+
+    if (strPath.empty())
+    {
+        fprintf(stderr, "Missing SQLite wallet export path.\n");
+        return 1;
+    }
+    if (!FileExists(strPath.c_str()))
+    {
+        fprintf(stderr, "SQLite wallet export does not exist: %s\n",
+                strPath.c_str());
+        return 1;
+    }
+
+    string strError;
+    CWalletDBSQLite sqlite;
+    if (!sqlite.Open(strPath, strError))
+    {
+        fprintf(stderr, "Cannot open SQLite wallet export: %s\n", strError.c_str());
+        return 1;
+    }
+
+    CWalletSQLiteLoadCheckVisitor visitor;
+    if (!sqlite.ScanRecords(visitor, strError))
+    {
+        printf("SQLite wallet load check\n");
+        printf("  records checked:           %d\n", visitor.nRecords);
+        printf("  unknown records:           %d\n", visitor.nUnknown);
+        printf("  load check:                failed\n");
+        printf("  failure:                   %s\n", strError.c_str());
+        fflush(stdout);
+        return 2;
+    }
+
+    printf("SQLite wallet load check\n");
+    printf("  records checked:           %d\n", visitor.nRecords);
+    printf("  unknown records:           %d\n", visitor.nUnknown);
+    printf("  load check:                ok\n");
+    fflush(stdout);
+    return 0;
+}
+
 int CmdEncryptWallet(const std::string& strPassphrase)
 {
     AttachTerminal();
 
+    // Capture the backend now: under SQLite, EncryptWallet() closes the runtime
+    // store to swap the file, so WalletSQLiteRuntimeActive() reads false by the
+    // time we would decide whether to purge Berkeley DB logs below.
+    bool fSQLiteBackend = WalletSQLiteRuntimeActive();
+
     string strBackup;
     string strError;
     if (!EncryptWallet(strPassphrase, strBackup, strError))
@@ -420,6 +1427,8 @@ int CmdEncryptWallet(const std::string& strPassphrase)
     }
 
     printf("Wallet encrypted.\n");
+    if (fSQLiteBackend)
+        printf("Wallet backend: SQLite (wallet.sqlite).\n");
     printf("The old unencrypted wallet was moved to:\n");
     printf("  %s\n", strBackup.c_str());
     printf("That backup still contains private keys in plain text. Move it offline or\n");
@@ -432,7 +1441,13 @@ int CmdEncryptWallet(const std::string& strPassphrase)
     // them. Closing the environment and dropping the logs is the last step of
     // encrypting, not an optimisation -- our own backup advice is to copy the
     // whole directory, and following it otherwise carries the keys along.
-    PurgeDbEnvironmentLogs();
+    //
+    // The SQLite backend has no Berkeley DB environment behind the wallet, and
+    // EncryptWallet() already closed and swapped the SQLite store; there is
+    // nothing to purge, and calling into the environment here would only open
+    // one needlessly.
+    if (!fSQLiteBackend)
+        PurgeDbEnvironmentLogs();
     return 0;
 }
 
diff --git a/src/walletcmd.h b/src/walletcmd.h
index 04d3fb7..7013d44 100644
--- a/src/walletcmd.h
+++ b/src/walletcmd.h
@@ -7,7 +7,9 @@
 #ifndef BITFLASH_WALLETCMD_H
 #define BITFLASH_WALLETCMD_H
 
+#include <map>
 #include <string>
+#include <vector>
 
 // Create a phrase for a wallet that does not have one, install the seed, and
 // show the words once. Refuses if a phrase already exists. Returns 0 on success.
@@ -41,6 +43,13 @@ bool RestoreScanReachedDepth(int nSchema,
                              unsigned int nLegacyNext,
                              int nStopDepth);
 
+// Given the pubkeys derived while scanning a compatibility branch, return the
+// next index after the highest one that actually appears in wallet
+// transactions. The scan depth can be much larger than this; hdnext must record
+// use, not how far a restore looked ahead.
+unsigned int WalletLastUsedPubKeyIndexNext(
+    const std::map<unsigned int, std::vector<unsigned char> >& mapPubKeysByIndex);
+
 // Take the next address from the key pool and print it. With a recovery phrase
 // installed the address is derived, so the phrase can bring back whatever is
 // paid to it.
@@ -53,6 +62,40 @@ int CmdShowDerived(int nCount);
 // by the installed recovery phrase or still depends on wallet.dat-only keys.
 int CmdRecoveryAudit();
 
+// Diagnostic: count wallet.dat record types without printing keys,
+// addresses, transaction ids, labels, or other wallet values.
+int CmdWalletStorageAudit(const std::string& strJsonOut = "");
+
+// Diagnostic: fail closed when wallet.dat contains an internally inconsistent
+// or migration-unsafe mix of storage records.
+int CmdWalletStorageCheck();
+
+// Copy every raw wallet.dat record into a SQLite key/value store, preserving
+// serialized bytes. A migration/scripting tool; it does not change which backend
+// the runtime wallet opens.
+int CmdWalletSQLiteExport(const std::string& strDest);
+
+// Export the currently-loaded wallet to a SQLite file (shared by the command
+// above and the GUI wizard). Returns false with an error on any failure.
+bool ExportActiveWalletToSQLite(const std::string& strDest, int& nCopiedRet,
+                                std::string& strErrorRet);
+
+// Convert the running Berkeley DB wallet to SQLite and record the backend
+// marker so the next start opens it. wallet.dat is left untouched as fallback.
+bool DoConvertWalletToSQLite(int& nCopiedRet, std::string& strErrorRet);
+
+// Diagnostic/migration staging: compare a SQLite wallet export with the current
+// wallet.dat raw records. Prints counts only, never record keys or values.
+int CmdWalletSQLiteVerify(const std::string& strPath);
+
+// Diagnostic/migration staging: rebuild wallet.dat from a SQLite export in an
+// empty data directory. Refuses to overwrite an existing wallet.dat.
+int CmdWalletSQLiteRestore(const std::string& strPath);
+
+// Diagnostic/migration staging: parse a SQLite wallet export as the runtime
+// wallet loader would. Prints counts only, never record keys or values.
+int CmdWalletSQLiteLoadCheck(const std::string& strPath);
+
 // Rewrite wallet.dat so private keys and the HD seed are encrypted with the
 // given passphrase. Returns 0 on success and exits without starting the node.
 int CmdEncryptWallet(const std::string& strPassphrase);
diff --git a/tests/fixtures/chain-tools/explorer-blocks.json b/tests/fixtures/chain-tools/explorer-blocks.json
new file mode 100644
index 0000000..795d6e4
--- /dev/null
+++ b/tests/fixtures/chain-tools/explorer-blocks.json
@@ -0,0 +1 @@
+{"blocks":[{"cbAddr":"BDnXDAAvEameyQk12FrtvBiPBp9MsfRmUA","cbValue":5000000000,"hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","height":2,"nTx":2,"size":331,"time":1753315440},{"cbAddr":"B61KYnjpfXHN2w2e1nR869HneK4P1Gz4va","cbValue":5000000000,"hash":"17bdb455d41592adbff4aa97b7fca2091fef69600e67306baca829ab5a588b30","height":1,"nTx":2,"size":331,"time":1753315320},{"cbAddr":"BDU4zj6apurZ7YWNxsndaTt75PMgzvwbN4","cbValue":5000000000,"hash":"5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169","height":0,"nTx":1,"size":278,"time":1753315200}],"count":3,"network":"bitflash","tipHeight":2}
diff --git a/tests/fixtures/chain-tools/fair-launch-report.json b/tests/fixtures/chain-tools/fair-launch-report.json
new file mode 100644
index 0000000..d35f30b
--- /dev/null
+++ b/tests/fixtures/chain-tools/fair-launch-report.json
@@ -0,0 +1 @@
+{"attestation_payload_sha256":"bf192bdbbb84c69d15bb68cf133abd474d0e1021600febc68e9f1a9de844b2af","chain":{"coin":100000000,"message_start_hex":"bf205cfd","name":"Bitflash","ticker":"BTF"},"checks":{"computed_merkle_matches_header":true,"genesis_has_single_transaction":true,"genesis_hash_matches_source":true,"genesis_merkle_matches_source":true,"genesis_supply_is_50_btf":true,"genesis_transaction_is_coinbase":true},"coinbase_outputs":[{"block_hash":"5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169","coinbase_txid":"1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325","height":0,"outputs":[{"script_pub_key_hex":"4104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac","value_btf":"50.00000000","value_satoshis":5000000000}],"value_btf":"50.00000000","value_satoshis":5000000000},{"block_hash":"17bdb455d41592adbff4aa97b7fca2091fef69600e67306baca829ab5a588b30","coinbase_txid":"d6967c16013f1da136183f962aefd2f15e59b6836043f8ef49aadb92f38dca05","height":1,"outputs":[{"script_pub_key_hex":"76a914111111111111111111111111111111111111111188ac","value_btf":"50.00000000","value_satoshis":5000000000}],"value_btf":"50.00000000","value_satoshis":5000000000},{"block_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","coinbase_txid":"d55af2c80e8b70a9ae8f362a8aac5448e7925267c7f737d1fa0d227fd472a657","height":2,"outputs":[{"script_pub_key_hex":"76a914666666666666666666666666666666666666666688ac","value_btf":"50.00000000","value_satoshis":5000000000}],"value_btf":"50.00000000","value_satoshis":5000000000}],"deterministic":true,"external_timestamping":{"instructions":["Save the canonical JSON report.","Run: ots stamp bitflash-fair-launch-report.json","Later verify with: ots verify bitflash-fair-launch-report.json.ots"],"recommended":"OpenTimestamps","status":"not_embedded"},"genesis":{"bits":"0x1f0fffff","coinbase_txid":"1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325","computed_merkle_root":"1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325","hash":"5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169","merkle_root":"1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325","nonce":3141,"outputs":[{"script_pub_key_hex":"4104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac","value_btf":"50.00000000","value_satoshis":5000000000}],"time":1753315200,"time_utc":"2025-07-24T00:00:00Z","tx_count":1},"scanned":{"block_count":3,"first_height":0,"last_height":2,"non_coinbase_transactions":2,"total_coinbase_btf":"150.00000000","total_coinbase_satoshis":15000000000},"schema":"bitflash-fair-launch-report-1","source_constants":{"genesis_bits":"0x1f0fffff","genesis_hash":"5bd7cb255d814e48cebcdfb72da4dc87b34bd774227f8ceb546c5640f4bdc169","genesis_merkle_root":"1a45b4482532abb29b10e234d3f13132230525a339ecea91658ffa675a5b1325","genesis_message":"Bitflash 24/Jul/2026 Fair launch: one CPU one vote, no premine","genesis_nonce":3141,"genesis_time":1753315200,"genesis_time_utc":"2025-07-24T00:00:00Z"},"source_mode":"local-block-files","verdict":"FAIR_LAUNCH_BASELINE_VERIFIED"}
diff --git a/tests/fixtures/chain-tools/utxo-proof-verification.json b/tests/fixtures/chain-tools/utxo-proof-verification.json
new file mode 100644
index 0000000..a40c673
--- /dev/null
+++ b/tests/fixtures/chain-tools/utxo-proof-verification.json
@@ -0,0 +1 @@
+{"checks":{"leaf_hash_matches_target":true,"root_matches":true,"schema_is_supported":true},"commitment":{"computed_root":"6e49b47ffccb178b62402235343ae7c55ec4a03effe19debb8c057e8ffc5b3c0","expected_root":"6e49b47ffccb178b62402235343ae7c55ec4a03effe19debb8c057e8ffc5b3c0","leaf_hash":"da964462812e40c918d6349baa57aee1dc838416eca44ccd31b782f0d1542d7b","path_length":3},"deterministic":true,"failures":[],"schema":"bitflash-utxo-proof-verification-1","target":{"created_height":2,"outpoint":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a:1","value_btf":"17.50000000","value_satoshis":1750000000},"verdict":"UTXO_PROOF_VERIFIED"}
diff --git a/tests/fixtures/chain-tools/utxo-proof.json b/tests/fixtures/chain-tools/utxo-proof.json
new file mode 100644
index 0000000..154c45b
--- /dev/null
+++ b/tests/fixtures/chain-tools/utxo-proof.json
@@ -0,0 +1 @@
+{"chain":{"coin":100000000,"message_start_hex":"bf205cfd","name":"Bitflash","ticker":"BTF"},"commitment":{"algorithm":"sorted-outpoint-merkle-sha256","leaf_count":5,"leaf_domain":"BTFUTXO1","node_domain":"BTFNODE1","root":"6e49b47ffccb178b62402235343ae7c55ec4a03effe19debb8c057e8ffc5b3c0"},"deterministic":true,"proof":[{"duplicated":false,"hash":"7a4f4f13aaf91f8b6b32d1fb22feaa3d0398782504915e9c156e60fdeca1255d","level":0,"side":"left"},{"duplicated":false,"hash":"5f91d5ba472b7d6ab96e9ce99d689896dad3c264d3abbce4c77f257687608943","level":1,"side":"right"},{"duplicated":false,"hash":"f041ba6a82fbc6759f0632f412dd8aab971ac1317358d6f204af3e57da4d12de","level":2,"side":"right"}],"scanned":{"first_height":0,"last_height":2,"main_chain_block_count":3,"raw_block_count":3,"side_blocks_ignored":0,"tip_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","tip_time":1753315440,"tip_time_utc":"2025-07-24T00:04:00Z"},"schema":"bitflash-utxo-inclusion-proof-1","target":{"leaf_hash":"da964462812e40c918d6349baa57aee1dc838416eca44ccd31b782f0d1542d7b","leaf_index":1,"outpoint":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a:1","txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","utxo":{"coinbase":false,"created_block_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","created_height":2,"created_txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","script_pub_key_hex":"76a914555555555555555555555555555555555555555588ac","txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","value_btf":"17.50000000","value_satoshis":1750000000,"vout":1},"vout":1},"verdict":"UTXO_INCLUSION_PROOF_CREATED","warnings":{"legacy_duplicate_output_overwrites":0}}
diff --git a/tests/fixtures/chain-tools/utxo-report.json b/tests/fixtures/chain-tools/utxo-report.json
new file mode 100644
index 0000000..c6e98ee
--- /dev/null
+++ b/tests/fixtures/chain-tools/utxo-report.json
@@ -0,0 +1 @@
+{"chain":{"coin":100000000,"message_start_hex":"bf205cfd","name":"Bitflash","ticker":"BTF"},"checks":{"all_scanned_merkle_roots_match":true,"genesis_hash_matches_source":true,"genesis_merkle_matches_source":true,"no_missing_spends":true},"commitment":{"algorithm":"sorted-outpoint-merkle-sha256","leaf_domain":"BTFUTXO1","node_domain":"BTFNODE1","root":"6e49b47ffccb178b62402235343ae7c55ec4a03effe19debb8c057e8ffc5b3c0"},"deterministic":true,"scanned":{"first_height":0,"last_height":2,"main_chain_block_count":3,"raw_block_count":3,"side_blocks_ignored":0,"tip_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","tip_time":1753315440,"tip_time_utc":"2025-07-24T00:04:00Z"},"schema":"bitflash-utxo-set-commitment-1","stats":{"coinbase_minus_unspent_btf":"1.50000000","coinbase_minus_unspent_satoshis":150000000,"duplicate_outputs":[],"missing_spends":[],"normal_transactions":2,"spent_outputs":8000000000,"total_coinbase_btf":"150.00000000","total_coinbase_satoshis":15000000000,"total_fees_btf":"1.50000000","total_fees_satoshis":150000000,"total_unspent_btf":"148.50000000","total_unspent_satoshis":14850000000,"utxo_count":5},"utxos":{"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a:0":{"coinbase":false,"created_block_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","created_height":2,"created_txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","script_pub_key_hex":"76a914444444444444444444444444444444444444444488ac","txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","value_btf":"12.00000000","value_satoshis":1200000000,"vout":0},"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a:1":{"coinbase":false,"created_block_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","created_height":2,"created_txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","script_pub_key_hex":"76a914555555555555555555555555555555555555555588ac","txid":"218609b2969dc0b6ae1c378ae255bbed863902987df4c943200e3c291b0e4c2a","value_btf":"17.50000000","value_satoshis":1750000000,"vout":1},"24bddfded9e22c2f98d9369e9ac00a4eccc8dcf05a2d1b9e12d94fd9f62ababc:1":{"coinbase":false,"created_block_hash":"17bdb455d41592adbff4aa97b7fca2091fef69600e67306baca829ab5a588b30","created_height":1,"created_txid":"24bddfded9e22c2f98d9369e9ac00a4eccc8dcf05a2d1b9e12d94fd9f62ababc","script_pub_key_hex":"76a914333333333333333333333333333333333333333388ac","txid":"24bddfded9e22c2f98d9369e9ac00a4eccc8dcf05a2d1b9e12d94fd9f62ababc","value_btf":"19.00000000","value_satoshis":1900000000,"vout":1},"d55af2c80e8b70a9ae8f362a8aac5448e7925267c7f737d1fa0d227fd472a657:0":{"coinbase":true,"created_block_hash":"7c0e819cec25ebe29452049f1b35479526ba679bc2c1b00407417109384dea76","created_height":2,"created_txid":"d55af2c80e8b70a9ae8f362a8aac5448e7925267c7f737d1fa0d227fd472a657","script_pub_key_hex":"76a914666666666666666666666666666666666666666688ac","txid":"d55af2c80e8b70a9ae8f362a8aac5448e7925267c7f737d1fa0d227fd472a657","value_btf":"50.00000000","value_satoshis":5000000000,"vout":0},"d6967c16013f1da136183f962aefd2f15e59b6836043f8ef49aadb92f38dca05:0":{"coinbase":true,"created_block_hash":"17bdb455d41592adbff4aa97b7fca2091fef69600e67306baca829ab5a588b30","created_height":1,"created_txid":"d6967c16013f1da136183f962aefd2f15e59b6836043f8ef49aadb92f38dca05","script_pub_key_hex":"76a914111111111111111111111111111111111111111188ac","txid":"d6967c16013f1da136183f962aefd2f15e59b6836043f8ef49aadb92f38dca05","value_btf":"50.00000000","value_satoshis":5000000000,"vout":0}},"verdict":"UTXO_COMMITMENT_VERIFIED","warnings":{"legacy_duplicate_output_overwrites":0}}
diff --git a/tests/scripts/test_bitflash_tools.py b/tests/scripts/test_bitflash_tools.py
new file mode 100644
index 0000000..3b4c846
--- /dev/null
+++ b/tests/scripts/test_bitflash_tools.py
@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Regression tests for deterministic Bitflash Python tooling."""
+
+import json
+import os
+import struct
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPTS = ROOT / "scripts"
+FIXTURES = ROOT / "tests" / "fixtures" / "chain-tools"
+sys.path.insert(0, str(SCRIPTS))
+
+import bitflash_chain as chain  # noqa: E402
+
+
+def run(args, **kwargs):
+    env = dict(os.environ)
+    env["PYTHONIOENCODING"] = "utf-8"
+    return subprocess.run(
+        [sys.executable] + [str(a) for a in args],
+        cwd=str(ROOT),
+        env=env,
+        check=True,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        **kwargs
+    )
+
+
+def write_block_file(path, blocks):
+    with Path(path).open("wb") as f:
+        f.write(b"noise")
+        f.write(chain.MAGIC)
+        f.write(struct.pack("<I", chain.MAX_BLOCK_PAYLOAD + 1))
+        f.write(b"still-noise")
+        for block in blocks:
+            payload = chain.ser_block(block)
+            f.write(chain.MAGIC)
+            f.write(struct.pack("<I", len(payload)))
+            f.write(payload)
+
+
+def p2pkh_script(byte):
+    return "76a914%s88ac" % (bytes([byte]) * 20).hex()
+
+
+def make_tx(vin, vout):
+    tx = {
+        "version": 1,
+        "vin": vin,
+        "vout": vout,
+        "lock_time": 0,
+    }
+    tx["txid"] = chain.hash_hex(chain.ser_tx(tx))
+    return tx
+
+
+def make_coinbase(label, script_byte, value=50 * chain.COIN):
+    return make_tx(
+        [{
+            "prevout_hash": "0" * 64,
+            "prevout_n": 0xFFFFFFFF,
+            "script_sig_hex": label.encode("ascii").hex(),
+            "sequence": 0xFFFFFFFF,
+        }],
+        [{
+            "value_satoshis": value,
+            "value_btf": chain.format_money(value),
+            "script_pub_key_hex": p2pkh_script(script_byte),
+        }],
+    )
+
+
+def make_spend(prev_txid, prev_n, outputs, label):
+    return make_tx(
+        [{
+            "prevout_hash": prev_txid,
+            "prevout_n": prev_n,
+            "script_sig_hex": label.encode("ascii").hex(),
+            "sequence": 0xFFFFFFFF,
+        }],
+        [{
+            "value_satoshis": value,
+            "value_btf": chain.format_money(value),
+            "script_pub_key_hex": p2pkh_script(script_byte),
+        } for value, script_byte in outputs],
+    )
+
+
+def make_block(prev_hash, txs, ntime, nonce):
+    merkle = chain.merkle_root([tx["txid"] for tx in txs])
+    header = (
+        struct.pack("<i", 1)
+        + bytes.fromhex(prev_hash)[::-1]
+        + bytes.fromhex(merkle)[::-1]
+        + struct.pack("<III", ntime, chain.GENESIS_BITS, nonce)
+    )
+    block = {
+        "hash": chain.hash_hex(header),
+        "version": 1,
+        "previous_hash": prev_hash,
+        "merkle_root": merkle,
+        "computed_merkle_root": merkle,
+        "time": ntime,
+        "time_utc": chain.utc(ntime),
+        "bits": "0x%08x" % chain.GENESIS_BITS,
+        "nonce": nonce,
+        "tx_count": len(txs),
+        "transactions": txs,
+        "source_file": "synthetic",
+        "source_offset": 0,
+        "size": 80 + len(chain.ser_compact_size(len(txs))) + sum(len(chain.ser_tx(tx)) for tx in txs),
+    }
+    return block
+
+
+def fixture_chain():
+    genesis = chain.reconstructed_genesis()
+    spend1 = make_spend(
+        chain.GENESIS_MERKLE,
+        0,
+        [(30 * chain.COIN, 0x22), (19 * chain.COIN, 0x33)],
+        "spend genesis with 1 BTF fee",
+    )
+    block1 = make_block(
+        genesis["hash"],
+        [make_coinbase("fixture coinbase 1", 0x11), spend1],
+        chain.GENESIS_TIME + 120,
+        4001,
+    )
+    spend2 = make_spend(
+        spend1["txid"],
+        0,
+        [(12 * chain.COIN, 0x44), (17 * chain.COIN + 50_000_000, 0x55)],
+        "split spend with 0.5 BTF fee",
+    )
+    block2 = make_block(
+        block1["hash"],
+        [make_coinbase("fixture coinbase 2", 0x66), spend2],
+        chain.GENESIS_TIME + 240,
+        4002,
+    )
+    return [genesis, block1, block2], {
+        "genesis_outpoint": "%s:0" % chain.GENESIS_MERKLE,
+        "first_spend_txid": spend1["txid"],
+        "proof_outpoint": "%s:1" % spend2["txid"],
+    }
+
+
+def compare_golden(name, actual, update):
+    path = FIXTURES / name
+    if update:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(actual)
+        return
+    # The tools promise canonical LF-terminated JSON. On Windows checkouts a
+    # fixture may still appear as CRLF in the working tree; normalize only line
+    # endings so content, field order and compact serialization still drift-test.
+    expected = path.read_bytes().replace(b"\r\n", b"\n")
+    if actual.replace(b"\r\n", b"\n") != expected:
+        raise AssertionError("golden mismatch: %s" % name)
+
+
+def assert_true(cond, msg):
+    if not cond:
+        raise AssertionError(msg)
+
+
+def run_genesis_smoke():
+    genesis = chain.reconstructed_genesis()
+    outpoint = "%s:0" % chain.GENESIS_MERKLE
+
+    with tempfile.TemporaryDirectory(prefix="bitflash-tool-tests-") as tmp:
+        tmp = Path(tmp)
+        datadir = tmp / "datadir"
+        datadir.mkdir()
+        blk1 = datadir / "blk0001.dat"
+        blk2 = datadir / "blk0002.dat"
+        write_block_file(blk1, [genesis])
+        blk2.write_bytes(b"")
+
+        fair = run([SCRIPTS / "verify-fair-launch.py", "--datadir", datadir,
+                    "--max-blocks", "1", "--json"]).stdout
+        fair_report = json.loads(fair)
+        assert_true(fair_report["verdict"] == "FAIR_LAUNCH_BASELINE_VERIFIED",
+                    "fair launch verifier failed synthetic genesis")
+
+        utxo = run([SCRIPTS / "verify-utxo-set.py", "--datadir", datadir,
+                    "--json"]).stdout
+        utxo_report = json.loads(utxo)
+        assert_true(utxo_report["verdict"] == "UTXO_COMMITMENT_VERIFIED",
+                    "UTXO verifier failed synthetic genesis")
+
+        proof_path = tmp / "proof.json"
+        run([SCRIPTS / "prove-utxo.py", outpoint, "--datadir", datadir,
+             "--out", proof_path, "--json"])
+        proof_check = run([SCRIPTS / "verify-utxo-proof.py", proof_path,
+                           "--root", utxo_report["commitment"]["root"], "--json"]).stdout
+        proof_report = json.loads(proof_check)
+        assert_true(proof_report["verdict"] == "UTXO_PROOF_VERIFIED",
+                    "UTXO proof verifier rejected synthetic proof")
+
+        explorer_dir = tmp / "explorer"
+        run([SCRIPTS / "build-explorer.py", blk1, blk2, explorer_dir])
+        blocks = json.loads((explorer_dir / "blocks.json").read_text(encoding="ascii"))
+        assert_true(blocks["tipHeight"] == 0 and blocks["count"] == 1,
+                    "explorer did not build the synthetic chain")
+        index_html = (explorer_dir / "index.html").read_text(encoding="utf-8")
+        assert_true("innerHTML" not in index_html, "explorer viewer still uses innerHTML")
+
+        try:
+            chain.apply_blocks([genesis, genesis], strict_duplicates=True)
+        except chain.ParseError:
+            pass
+        else:
+            raise AssertionError("strict duplicate output mode did not fail")
+
+
+def run_golden_fixture(update):
+    blocks, meta = fixture_chain()
+
+    with tempfile.TemporaryDirectory(prefix="bitflash-tool-golden-") as tmp:
+        tmp = Path(tmp)
+        datadir = tmp / "datadir"
+        datadir.mkdir()
+        blk1 = datadir / "blk0001.dat"
+        blk2 = datadir / "blk0002.dat"
+        write_block_file(blk1, blocks[:2])
+        write_block_file(blk2, blocks[2:])
+
+        fair = run([SCRIPTS / "verify-fair-launch.py", "--datadir", datadir,
+                    "--max-blocks", "3", "--json"]).stdout.encode("ascii")
+        compare_golden("fair-launch-report.json", fair, update)
+        fair_report = json.loads(fair)
+        assert_true(fair_report["scanned"]["non_coinbase_transactions"] == 2,
+                    "fair-launch fixture did not count normal transactions")
+
+        utxo = run([SCRIPTS / "verify-utxo-set.py", "--datadir", datadir,
+                    "--include-utxos", "--strict-duplicates", "--json"]).stdout.encode("ascii")
+        compare_golden("utxo-report.json", utxo, update)
+        utxo_report = json.loads(utxo)
+        assert_true(utxo_report["stats"]["normal_transactions"] == 2,
+                    "UTXO fixture did not apply normal transactions")
+        assert_true(utxo_report["stats"]["total_fees_btf"] == "1.50000000",
+                    "UTXO fixture fee total changed")
+        assert_true(meta["genesis_outpoint"] not in utxo_report["utxos"],
+                    "spent genesis output still appears in the UTXO map")
+
+        proof_path = tmp / "fixture-proof.json"
+        proof = run([SCRIPTS / "prove-utxo.py", meta["proof_outpoint"],
+                     "--datadir", datadir, "--strict-duplicates",
+                     "--out", proof_path, "--json"]).stdout.encode("ascii")
+        compare_golden("utxo-proof.json", proof, update)
+
+        proof_check = run([SCRIPTS / "verify-utxo-proof.py", proof_path,
+                           "--root", utxo_report["commitment"]["root"], "--json"]).stdout.encode("ascii")
+        compare_golden("utxo-proof-verification.json", proof_check, update)
+        proof_report = json.loads(proof_check)
+        assert_true(proof_report["verdict"] == "UTXO_PROOF_VERIFIED",
+                    "fixture UTXO proof did not verify")
+
+        explorer_dir = tmp / "explorer"
+        run([SCRIPTS / "build-explorer.py", blk1, blk2, explorer_dir])
+        compare_golden("explorer-blocks.json",
+                       (explorer_dir / "blocks.json").read_bytes(), update)
+        detail = json.loads((explorer_dir / "block" / "1.json").read_text(encoding="ascii"))
+        assert_true(len(detail["txs"]) == 2,
+                    "explorer fixture block did not include the normal transaction")
+
+
+def main():
+    update = "--update-goldens" in sys.argv[1:]
+    run_genesis_smoke()
+    run_golden_fixture(update)
+    print("Bitflash script tool regressions passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())