Merge branch 'chore/main-catchup-2026-08-26' into 'main'HEADmain

Bring main onto the line this project actually ships (incl. the 1.2.23 compactblock port)

Closes #6, #7, #8, #11, #35, #34, #29, #28, #27, and #16

See merge request !16

44 files changed, 14922 insertions, 889 deletions

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);