18 files changed, 1518 insertions, 87 deletions

diff --git a/src/Makefile b/src/Makefile
index 89ba559..b068376 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -53,7 +53,7 @@ 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 proxy.h font_roboto.h
+          selftest.h walletcmd.h compat.h sockcount.h proxy.h tor.h font_roboto.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
@@ -61,7 +61,7 @@ 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/proxy.o
+            obj/selftest.o obj/bip32.o obj/walletcmd.o obj/proxy.o obj/tor.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o
 
@@ -195,5 +195,6 @@ tests: test_bip32 bitflash-node
         ./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/btfaddr.cpp b/src/btfaddr.cpp
index 6edcc91..ce2ac86 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,35 @@ 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"))
+        {
+            if (v["onion"].is_string() && v.contains("sig3") && v["sig3"].is_string())
+            {
+                std::string onionNorm;
+                std::string onionRaw = v["onion"].get<std::string>();
+                if (NormalizeOnionEndpoint(onionRaw, onionNorm) && onionNorm == onionRaw)
+                {
+                    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) &&
+                        secp256k1_schnorrsig_verify(ctx, sig3, digest3, 32, &xpub))
+                        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/main_gui.cpp b/src/main_gui.cpp
index e941522..e8dacd3 100644
--- a/src/main_gui.cpp
+++ b/src/main_gui.cpp
@@ -1,8 +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
@@ -112,7 +114,7 @@ static void PrintUsage()
     printf("  /gen\n");
     printf("  /nogui or /daemon\n");
     printf("  /selftest=wallet-keypool, wallet-hd, wallet-format, wallet-crypto, wallet-encrypt,\n");
-    printf("            net-message, consensus-limits, pool-stratum, parse-money, or socks5-proxy\n");
+    printf("            net-message, consensus-limits, pool-stratum, parse-money, socks5-proxy, or managed-tor\n");
     printf("\n");
     printf("Mining mode:\n");
     printf("  /operator\n");
@@ -137,11 +139,15 @@ static void PrintUsage()
     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("  /socks=HOST:PORT           (SOCKS5 proxy for outbound Nostr and .btf relay dials)\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("  /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");
@@ -295,6 +301,7 @@ static void ParseStartupArguments(int argc, char* argv[])
     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())
@@ -315,14 +322,67 @@ 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");
-    if (fTorMode)
+    string socksProxy = argval2(argc, argv, "/socks", "-socks");
+    string bundledTorPath;
+    bool fAutoManagedTor = !fManagedTor && !fNoManagedTor && !fTorMode &&
+                            socksProxy.empty() && 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)
     {
-        string socksProxy = argval2(argc, argv, "/socks", "-socks");
         if (!socksProxy.empty())
             fprintf(stderr, "Warning: /tor takes precedence over /socks=%s\n",
                     socksProxy.c_str());
@@ -337,7 +397,6 @@ static void ParseStartupArguments(int argc, char* argv[])
     }
     else
     {
-        string socksProxy = argval2(argc, argv, "/socks", "-socks");
         if (!socksProxy.empty())
         {
             string err;
@@ -348,6 +407,8 @@ static void ParseStartupArguments(int argc, char* argv[])
                         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.
@@ -368,22 +429,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.
@@ -760,7 +805,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;
@@ -793,6 +843,7 @@ int main(int argc, char* argv[])
         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
@@ -812,6 +863,7 @@ int main(int argc, char* argv[])
     int ret = RunGUI(argc, argv);
     fShutdown = true;
     StopNode();
+    BtfStopManagedTor();
     DBFlush(true);
     return ret;
 #endif
diff --git a/src/makefile.mingw b/src/makefile.mingw
index 8b49cac..0ba1d76 100644
--- a/src/makefile.mingw
+++ b/src/makefile.mingw
@@ -37,7 +37,7 @@ 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/proxy.o
+            obj/selftest.o obj/bip32.o obj/walletcmd.o obj/proxy.o obj/tor.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o obj/bitflash_res.o
 
@@ -51,7 +51,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 proxy.h compat.h font_roboto.h
+          selftest.h walletcmd.h sockcount.h proxy.h tor.h compat.h font_roboto.h
 
 all: bitflash.exe
 
@@ -113,3 +113,4 @@ tests: test_bip32.exe bitflash.exe
         ./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 bb39122..35baf21 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -17,9 +17,12 @@
 #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);
@@ -62,6 +65,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;
@@ -170,7 +175,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", "stratum bridge"
+    "nostr relay", "direct onion peer", "stratum bridge"
 };
 
 static string SockAccountingText()
@@ -263,15 +268,21 @@ 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();
@@ -294,6 +305,23 @@ string GetDiagnosticsText()
     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",
@@ -544,6 +572,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
@@ -602,6 +631,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())
@@ -625,7 +656,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)
     {
@@ -633,11 +665,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;
             }
@@ -645,6 +681,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;
@@ -659,6 +696,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())
@@ -747,7 +786,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());
@@ -785,7 +824,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
@@ -876,14 +915,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);
@@ -893,16 +955,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;
@@ -922,7 +1022,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);
@@ -952,9 +1052,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)
@@ -962,7 +1063,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
@@ -971,7 +1072,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))
@@ -981,7 +1083,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
@@ -1936,6 +2038,11 @@ bool StartNode(string& strError)
     // IP address, and port for the socket that is being bound
     int nRetryLimit = 15;
     struct sockaddr_in sockaddr = addrLocalHost.GetSockAddr();
+    // Keep addrLocalHost as this node's advertised address, but listen on all
+    // local interfaces. Managed Tor forwards hidden-service traffic to
+    // 127.0.0.1:<port>, and binding only to the LAN address made that onion
+    // endpoint unreachable even though the P2P listener was running.
+    sockaddr.sin_addr.s_addr = INADDR_ANY;
     if (bind(hListenSocket, (struct sockaddr*)&sockaddr, sizeof(sockaddr)) == SOCKET_ERROR)
     {
         int nErr = WSAGetLastError();
diff --git a/src/net.h b/src/net.h
index 653a015..9f3c7e4 100644
--- a/src/net.h
+++ b/src/net.h
@@ -26,10 +26,12 @@ enum
 bool GetMyExternalIP(unsigned int& ipRet);
 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;
diff --git a/src/nostr.cpp b/src/nostr.cpp
index 32cea18..e2d839c 100644
--- a/src/nostr.cpp
+++ b/src/nostr.cpp
@@ -132,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
@@ -153,6 +155,26 @@ void BtfSetActiveRelay(const string& relay)
         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.
@@ -392,10 +414,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
@@ -854,17 +882,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 }) });
@@ -1070,7 +1102,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];
@@ -1106,7 +1139,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
@@ -1126,8 +1163,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++)
@@ -1155,10 +1194,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")
@@ -1247,12 +1291,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);
                 }
@@ -1729,11 +1776,13 @@ static void ConnectDiscoveredBtfPeers()
             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)
@@ -1795,11 +1844,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,
diff --git a/src/nostr.h b/src/nostr.h
index 827b2f3..6dbbe26 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;
@@ -102,12 +109,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
index 7d30911..eed054c 100644
--- a/src/proxy.cpp
+++ b/src/proxy.cpp
@@ -13,6 +13,7 @@ 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)
 {
@@ -297,10 +298,25 @@ static bool Socks5Connect(SOCKET s, const std::string& destHost,
 
     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)) || choice[0] != 0x05 || choice[1] != 0x00)
+    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());
@@ -313,11 +329,25 @@ static bool Socks5Connect(SOCKET s, const std::string& destHost,
     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)) || rep[0] != 0x05)
+    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",
@@ -335,10 +365,20 @@ static bool Socks5Connect(SOCKET s, const std::string& destHost,
         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);
-    return ReadN(s, &discard[0], (int)discard.size());
+    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,
@@ -347,9 +387,11 @@ SOCKET BtfConnectSocket(const std::string& destHost, unsigned short destPort,
     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;
     }
@@ -365,6 +407,9 @@ SOCKET BtfConnectSocket(const std::string& destHost, unsigned short destPort,
         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;
diff --git a/src/readme.txt b/src/readme.txt
index 794fe20..752be66 100644
--- a/src/readme.txt
+++ b/src/readme.txt
@@ -43,12 +43,17 @@ Command-line options (in addition to the original ones)
 -------------------------------------------------------
   /port=N        listen on P2P port N (default 8433)
   /socks=HOST:PORT
-                 route outbound Nostr and .btf rendezvous dials through a
-                 SOCKS5 proxy, e.g. /socks=127.0.0.1:9050 for local Tor
+                 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 and .btf rendezvous dials;
+                 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
@@ -72,6 +77,8 @@ Command-line options (in addition to the original ones)
                  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/selftest.cpp b/src/selftest.cpp
index 034e1f7..9f7106f 100644
--- a/src/selftest.cpp
+++ b/src/selftest.cpp
@@ -6,10 +6,12 @@
 // and against a temporary data directory.
 
 #include "headers_core.h"
+#include "btfaddr.h"
 #include "bip32.h"
 #include "proxy.h"
 #include "selftest.h"
 #include "sockcount.h"
+#include "tor.h"
 #include "walletcmd.h"
 
 extern int RunPoolStratumSelfTest();
@@ -587,6 +589,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)
     {
@@ -1505,6 +1535,14 @@ static int RunSocks5ProxySelfTest()
                    !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;
@@ -1554,6 +1592,41 @@ static int RunSocks5ProxySelfTest()
     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();
@@ -1580,8 +1653,10 @@ int RunSelfTest(const std::string& name)
         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, pool-stratum, payout-ledger, parse-money, socks5-proxy\n");
+    printf("Known self-tests: wallet-keypool, wallet-hd, wallet-format, wallet-crypto, wallet-encrypt, net-message, consensus-limits, pool-stratum, payout-ledger, parse-money, socks5-proxy, managed-tor\n");
     return 1;
 }
diff --git a/src/sockcount.h b/src/sockcount.h
index 5147f55..a63c6be 100644
--- a/src/sockcount.h
+++ b/src/sockcount.h
@@ -63,6 +63,7 @@ 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..8de426e 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,16 @@ 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) && o.onion.empty(),
+              "tampered onion ignored rather than trusted");
+        json j4 = json::parse(d3);
+        j4["sig3"] = std::string(128, '0');
+        CHECK(btf::VerifyDescriptor(ctx, j4.dump(), pk, o) && o.onion.empty(),
+              "bad onion signature ignored rather than trusted");
     }
 
     printf("full_resolve_chain_from_address\n");
diff --git a/src/tor.cpp b/src/tor.cpp
new file mode 100644
index 0000000..20b4577
--- /dev/null
+++ b/src/tor.cpp
@@ -0,0 +1,881 @@
+// 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
+    if (g_managedTorPid > 0)
+    {
+        std::string shutdownErr;
+        if (!RequestManagedTorShutdown(shutdownErr))
+            kill(g_managedTorPid, SIGTERM);
+        bool fExited = false;
+        for (int i = 0; i < 100; i++)
+        {
+            int status = 0;
+            pid_t r = waitpid(g_managedTorPid, &status, WNOHANG);
+            if (r == g_managedTorPid)
+            {
+                fExited = true;
+                break;
+            }
+            Sleep(100);
+        }
+        if (!fExited)
+        {
+            kill(g_managedTorPid, SIGKILL);
+            waitpid(g_managedTorPid, NULL, 0);
+        }
+        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/walletcmd.cpp b/src/walletcmd.cpp
index 0ea2251..e8ac4bf 100644
--- a/src/walletcmd.cpp
+++ b/src/walletcmd.cpp
@@ -54,6 +54,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 +163,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 +185,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 +216,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 +243,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 +289,7 @@ bool RestoreFromPhrase(const std::string& strMnemonic,
             RestoreScanReachedDepth(nHDKeySchema,
                                     nHDReceiveNext,
                                     nHDChangeNext,
-                                    nHDNext,
+                                    fRestoreBIP44 ? nLegacyScanNext : nHDNext,
                                     nStopDepth))
             break;
     }
diff --git a/src/walletcmd.h b/src/walletcmd.h
index 04d3fb7..007b8b5 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.