Merge pull request 'net: add optional SOCKS5 outbound proxy' (#27) from socks5-proxy into main

10 files changed, 656 insertions, 55 deletions

diff --git a/src/Makefile b/src/Makefile
index 00a8182..511fe79 100644
--- a/src/Makefile
+++ b/src/Makefile
@@ -30,7 +30,7 @@ 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)
@@ -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 market.h \
-          selftest.h walletcmd.h compat.h sockcount.h font_roboto.h
+          selftest.h walletcmd.h compat.h sockcount.h proxy.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/market.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/proxy.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o
 
@@ -193,5 +193,6 @@ tests: test_bip32 bitflash-node
         ./bitflash-node -selftest=consensus-limits
         ./bitflash-node -selftest=pool-stratum
         ./bitflash-node -selftest=parse-money
+        ./bitflash-node -selftest=socks5-proxy
 
 .PHONY: tests fuzz-net-message-smoke fuzz-script-smoke
diff --git a/src/btfrv.cpp b/src/btfrv.cpp
index 6ac3280..d4f079f 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).
@@ -92,6 +95,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_INET;
@@ -119,6 +127,7 @@ static SOCKET ConnectTo(const char* host, unsigned short port)
         CLOSESOCK(s); freeaddrinfo(res); return INVALID_SOCKET;
     }
     freeaddrinfo(res);
+#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.
diff --git a/src/main_gui.cpp b/src/main_gui.cpp
index b036ac9..90a6050 100644
--- a/src/main_gui.cpp
+++ b/src/main_gui.cpp
@@ -1,6 +1,7 @@
 // Bitflash entry point -- starts node threads then runs GUI (or headless).
 
 #include "headers_core.h"
+#include "proxy.h"
 #include "selftest.h"
 #include "walletcmd.h"
 #include <thread>          // hardware_concurrency, to sanity-check /genproclimit
@@ -110,7 +111,8 @@ static void PrintUsage()
     printf("  /debug\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-crypto, wallet-encrypt,\n");
+    printf("            net-message, consensus-limits, pool-stratum, parse-money, or socks5-proxy\n");
     printf("\n");
     printf("Mining mode:\n");
     printf("  /operator\n");
@@ -135,6 +137,7 @@ static void PrintUsage()
     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("  /btfseed=ADDRESS:ENCHEX    (extra bootstrap peer, repeatable)\n");
     printf("\n");
     printf("Wallet:\n");
@@ -282,6 +285,17 @@ static void ParseStartupArguments(int argc, char* argv[])
     if (!announceRelay.empty())
         strBtfAnnounceRelay = announceRelay;
 
+    string socksProxy = argval2(argc, argv, "/socks", "-socks");
+    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());
+    }
+
     // /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++)
diff --git a/src/makefile.mingw b/src/makefile.mingw
index b946e50..28e925c 100644
--- a/src/makefile.mingw
+++ b/src/makefile.mingw
@@ -21,7 +21,7 @@ WARNFLAGS = -Wformat -Werror=format \
 # 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 \
+           -DSECP256K1_STATIC -DBITFLASH_NODE_BUILD \
            -I$(DEPS)/include -I$(RANDOMX)/src \
            -I$(DEPS)/include/nlohmann \
            -IC:/msys64/ucrt64/include \
@@ -42,7 +42,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/market.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/proxy.o
 
 GUI_OBJS = obj/gui.o obj/main_gui.o obj/bitflash_res.o
 
@@ -56,7 +56,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 market.h \
-          selftest.h walletcmd.h sockcount.h compat.h font_roboto.h
+          selftest.h walletcmd.h sockcount.h proxy.h compat.h font_roboto.h
 
 all: bitflash.exe
 
@@ -117,3 +117,4 @@ tests: test_bip32.exe bitflash.exe
         ./bitflash.exe -selftest=net-message
         ./bitflash.exe -selftest=consensus-limits
         ./bitflash.exe -selftest=pool-stratum
+        ./bitflash.exe -selftest=socks5-proxy
diff --git a/src/net.cpp b/src/net.cpp
index b9bb95d..fe9964e 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -17,6 +17,7 @@
 #include <openssl/rand.h>
 #include "btfaddr.h"
 #include "btftunnel.h"
+#include "proxy.h"
 
 void ThreadReconnectCachedBtfPeers(void* parg);
 void ThreadMessageHandler2(void* parg);
@@ -361,6 +362,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[] = {
diff --git a/src/nostr.cpp b/src/nostr.cpp
index 9bc538f..d286767 100644
--- a/src/nostr.cpp
+++ b/src/nostr.cpp
@@ -29,6 +29,7 @@
 
 #include "btfaddr.h"
 #include "btfchan.h"
+#include "proxy.h"
 
 using json = nlohmann::json;
 
@@ -540,53 +541,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
diff --git a/src/proxy.cpp b/src/proxy.cpp
new file mode 100644
index 0000000..d7dc324
--- /dev/null
+++ b/src/proxy.cpp
@@ -0,0 +1,329 @@
+// 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 std::string g_socks5Host;
+static unsigned short g_socks5Port = 0;
+
+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 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;
+}
+
+bool BtfSetSocks5Proxy(const std::string& spec, 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;
+    }
+    return true;
+}
+
+void BtfClearSocks5Proxy()
+{
+    CRITICAL_BLOCK(cs_socks5)
+    {
+        g_fSocks5Proxy = false;
+        g_socks5Host.clear();
+        g_socks5Port = 0;
+    }
+}
+
+bool BtfSocks5ProxyEnabled()
+{
+    CRITICAL_BLOCK(cs_socks5)
+        return g_fSocks5Proxy;
+    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)))
+        return false;
+    unsigned char choice[2] = { 0, 0 };
+    if (!ReadN(s, choice, sizeof(choice)) || choice[0] != 0x05 || choice[1] != 0x00)
+        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()))
+        return false;
+
+    unsigned char rep[4] = {0,0,0,0};
+    if (!ReadN(s, rep, sizeof(rep)) || rep[0] != 0x05)
+        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
+        return false;
+
+    std::vector<unsigned char> discard(nAddr + 2);
+    return ReadN(s, &discard[0], (int)discard.size());
+}
+
+SOCKET BtfConnectSocket(const std::string& destHost, unsigned short destPort,
+                        int nSockSite, int nTimeoutSecs)
+{
+    std::string proxyHost;
+    unsigned short proxyPort = 0;
+    bool fProxy = false;
+    CRITICAL_BLOCK(cs_socks5)
+    {
+        fProxy = g_fSocks5Proxy;
+        proxyHost = g_socks5Host;
+        proxyPort = g_socks5Port;
+    }
+
+    if (!fProxy)
+        return ConnectDirect(destHost, destPort, nSockSite, nTimeoutSecs);
+
+    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..b5e69c8
--- /dev/null
+++ b/src/proxy.h
@@ -0,0 +1,31 @@
+// 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);
+void BtfClearSocks5Proxy();
+bool BtfSocks5ProxyEnabled();
+std::string BtfSocks5ProxyName();
+
+SOCKET BtfConnectSocket(const std::string& destHost, unsigned short destPort,
+                        int nSockSite, int nTimeoutSecs);
+
+#endif
diff --git a/src/readme.txt b/src/readme.txt
index b8b89c1..1fa77df 100644
--- a/src/readme.txt
+++ b/src/readme.txt
@@ -42,6 +42,10 @@ 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)
+  /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
+                 or /socks=[::1]:9050 for an IPv6 loopback proxy
   /solomine      mine without requiring a connected peer (local testing)
   /operator      operator mode (run pool server)
   /participant=ADDR
diff --git a/src/selftest.cpp b/src/selftest.cpp
index dcb9192..aa4e528 100644
--- a/src/selftest.cpp
+++ b/src/selftest.cpp
@@ -7,7 +7,9 @@
 
 #include "headers_core.h"
 #include "bip32.h"
+#include "proxy.h"
 #include "selftest.h"
+#include "sockcount.h"
 #include "walletcmd.h"
 
 extern int RunPoolStratumSelfTest();
@@ -1253,6 +1255,254 @@ static int RunParseMoneySelfTest()
     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;
+
+    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();
+
+    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;
+}
+
 int RunSelfTest(const std::string& name)
 {
     AttachTerminal();
@@ -1275,8 +1525,10 @@ int RunSelfTest(const std::string& name)
         return RunPoolStratumSelfTest();
     if (name == "parse-money")
         return RunParseMoneySelfTest();
+    if (name == "socks5-proxy")
+        return RunSocks5ProxySelfTest();
 
     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\n");
+    printf("Known self-tests: wallet-keypool, wallet-hd, wallet-format, wallet-crypto, wallet-encrypt, net-message, consensus-limits, pool-stratum, parse-money, socks5-proxy\n");
     return 1;
 }