Merge upstream v1.2.19 into the fork

Merges upstream tag v1.2.19 (9e39a50) into merge/upstream-1.2.18 (991853f).
Unlike the 1.2.15->1.2.18 replay, bc3de30 is a true ancestor of our branch via
a9b4f89, so this is an ordinary three-way merge with merge-base bc3de30.

Delta: 36 files, +3265/-163, the Tor onion transport (managed Tor, signed
direct onion endpoints, onion-only dial mode) and the nHDNext restore fix.
src/main.cpp, main.h, script.cpp/h and db.cpp/h are byte-identical between the
two tags, and the poll() socket loop carries no diff hunks, so the merge is
consensus-neutral and the soak-tested socket paths are unchanged. relay/ is
untouched; the payout ledger (rpc.cpp) is untouched.

7 conflict blocks in 6 files, resolved as follows.

Makefile -- VERSION. Ours: stays 1.2.19+sec with the naming comment updated,
so artifacts from this tree cannot be mistaken for the upstream release.

src/Makefile, src/makefile.mingw -- HEADERS list. Ours (no market.h) plus
their tor.h. NODE_OBJS auto-merged correctly: no market.o, tor.o present.

src/selftest.cpp -- known-tests list. Union: payout-ledger (ours) and
managed-tor (theirs).

src/main_gui.cpp -- one block. Our /dumpaddresses kept; their
BtfStopManagedTor() on the StartNode failure path taken. The /rvrelay pin,
/noannounce and the marketplace removal auto-merged and were verified intact.

src/nostr.cpp -- two blocks in ResolveDescriptor. Signature takes both
out-params (our fExchangeOk, their rawOut). The body keeps our
drain-to-EOSE read -- returning early poisons the pooled socket for the next
caller -- and adds their rawOut capture. Our TLS 1.2 floor
(SSL_CTX_set_min_proto_version) is untouched by this merge; upstream 1.2.19
still has no floor of its own.

Upstream's release commit also added four build logs and a compiled Python
cache (build-1219.log, build-17.log, build-appimage.log, build-node.log,
scripts/__pycache__/bitflash_chain.cpython-313.pyc). Removed here; they are
build output, not source.

31 files changed, 2417 insertions, 165 deletions

diff --git a/Makefile b/Makefile
index 4fdab39..9f97b73 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,7 @@
 #
 #   make linux    build Bitflash-*-x86_64.AppImage
 #   make windows  build Bitflash-*-windows.zip (from MSYS2 UCRT64)
+#   make windows-tor build Bitflash-*-windows-with-tor.zip
 #   make tests    build and run standalone unit tests
 #   make checksums create SHA256SUMS for release assets
 #   make verify-release TAG=v1.2.13
@@ -10,10 +11,10 @@
 ROOT    := $(shell pwd)
 NPROC   := $(shell nproc 2>/dev/null || echo 2)
 SUDO    := $(shell [ "$$(id -u)" = "0" ] && echo "" || echo "sudo")
-# Not "1.2.18". This tree is upstream v1.2.18 plus 24 commits of our own and a
-# hand-merged payout ledger, so a binary built here must not be mistakable for
+# Not "1.2.19". This tree is upstream v1.2.19 plus our own hardening commits and
+# a hand-merged payout ledger, so a binary built here must not be mistakable for
 # the upstream release of that number -- it names every release artifact.
-VERSION := 1.2.18+sec
+VERSION := 1.2.19+sec
 
 # ---- Pinned third-party sources -------------------------------------------
 #
@@ -239,6 +240,9 @@ windows: deps-windows
         @zip -r Bitflash-$(VERSION)-windows.zip Bitflash-$(VERSION)-windows/
         @echo "Built: Bitflash-$(VERSION)-windows.zip"
 
+windows-tor: windows
+        ./scripts/package-windows-tor.sh
+
 # ---- Clean ----------------------------------------------------------------
 
 clean:
@@ -265,6 +269,6 @@ sign-checksums:
 verify-release:
         ./scripts/verify-release.sh $(if $(TAG),$(TAG),latest)
 
-.PHONY: linux windows clean appimage \
+.PHONY: linux windows windows-tor clean appimage \
         tests fuzz-net-message-smoke fuzz-script-smoke checksums sign-checksums verify-release \
         deps-linux deps-windows deps-apt deps-secp256k1 deps-randomx
diff --git a/README.md b/README.md
index ef4f39b..1782bc3 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ Bitflash keeps Satoshi's original consensus rules and replaces two things:
 
 **RandomX proof of work.** Memory-hard algorithm used by Monero. A laptop competes equally with a server. ASICs and GPUs have no advantage.
 
-**Anonymous addressing.** Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes reach each other through encrypted rendezvous tunnels, so no port forwarding is needed and a node behind CGNAT works normally.
+**Anonymous addressing.** Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes reach each other through encrypted rendezvous tunnels by default, and can advertise a signed direct `.onion` endpoint for Tor peers.
 
 No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute blocks.
 
@@ -30,14 +30,17 @@ No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute bl
 
 Worth being precise, because the difference matters if you are relying on it.
 
-**A peer you reach over `.btf` does not learn your IP.** All outbound connections go through a rendezvous tunnel; there is no IP-based peer dialling left in the node. The relay forwards encrypted bytes and cannot read or alter them.
+**A peer you reach over `.btf` does not learn your IP.** Outbound peer discovery uses rendezvous tunnels by default. If both sides use Tor and the peer advertises a signed `.onion` endpoint, the node connects directly to that hidden service instead. In both cases the peer does not see your clearnet IP.
 
-**The rendezvous relay does see your IP.** It has to — it is the thing your TCP connection terminates on. Relays are run by volunteers, so treat that as a party who knows you are on the network.
+**The rendezvous relay sees your IP unless you use Tor.** It has to — it is the thing your TCP connection terminates on. With `-tor`, the relay sees Tor instead. With a signed direct `.onion` peer endpoint, the relay is not on that connection path at all.
 
 **The node still listens on 8433.** Nothing dials by IP any more, but the listener is still there, so anyone who already knows your address and can reach that port may connect directly. If that matters to you, firewall it.
 
 This is unlinkability between peers, not anonymity against a network observer.
-For Tor routing, start the node with `-tor`; see [Tor mode](docs/tor.md).
+For Tor routing and direct onion peer endpoints, start the node with `-tor`;
+see [Tor mode](docs/tor.md).
+For a plain SOCKS5 proxy without Tor-specific defaults, use
+`-socks=HOST:PORT`.
 
 ---
 
@@ -49,6 +52,8 @@ configuration — it connects automatically and starts syncing.
 **Linux:** make the `.AppImage` executable and run it.
 
 **Windows:** extract the `-windows.zip` and run `Bitflash.exe`.
+If you want managed Tor without a separate Tor install, use the
+`-windows-with-tor.zip` package and start Bitflash with `-managedtor`.
 
 Every release ships a `SHA256SUMS` covering the assets. Verifying takes a second
 and is worth doing:
@@ -74,6 +79,14 @@ scripts/verify-release.sh latest
 See [release verification](docs/release-verification.md) for the full release
 audit flow and the maintainer signing step.
 
+Public mirrors should make the latest checksum files available both under the
+versioned release directory and at the release root:
+
+```text
+https://releases.bitflash.network/v1.2.19/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS        # alias to latest
+```
+
 Bitflash also ships a deterministic UTXO-set commitment tool:
 
 ```bash
@@ -113,6 +126,12 @@ python3 scripts/build-explorer.py --datadir ~/.bitflash ./explorer-out
 python3 scripts/build-explorer.py ~/.bitflash/blk0001.dat ~/.bitflash/blk0002.dat ./explorer-out
 ```
 
+The generated explorer is static and self-contained: `index.html`,
+`style.css`, `explorer.js`, `blocks.json`, `block/*.json`, and `logo.png`. It is
+safe to host behind a strict policy such as `default-src 'none'; img-src 'self';
+style-src 'self'; script-src 'self'; connect-src 'self'; base-uri 'none';
+form-action 'none'`.
+
 **Keep your node current.** Consensus rules have changed since the first
 releases — 1.2.1 fixed a bug that let anyone spend anyone's coins, and 1.2.2
 added a per-block signature-operation cap. A node on an older build will accept
@@ -265,6 +284,7 @@ default both are created in the data directory; use `-poolstatusfile=PATH` and
 `-poolroundsfile=PATH` to write them somewhere a dashboard or web sync can read.
 The files are informational only: nodes still discover pools through Nostr and
 `.btf`, not through any web domain.
+See [public pool directory](docs/pool-directory.md) for the website/API shape.
 
 **Participant** — mine to someone else's pool. Enter or select the pool's `.btf` address and enable Start Mining.
 
@@ -319,8 +339,10 @@ Other options worth knowing:
 ```bash
 -datadir=PATH    # wallet and chain data elsewhere
 -port=N          # P2P listen port, default 8433
--socks=HOST:PORT # SOCKS5 for outbound Nostr and .btf rendezvous dials
+-socks=HOST:PORT # SOCKS5 for outbound Nostr, .btf relay, and onion peer dials
 -tor[=HOST:PORT] # Tor mode; default local Tor SOCKS5 proxy is 127.0.0.1:9050
+-managedtor[=PATH] # start Tor, create a hidden service, advertise its onion
+-onionservice=HOST.onion:PORT # advertise this node's Tor hidden service
 -debug           # verbose log; without it debug.log is nearly silent
 -help            # full list
 ```
@@ -329,15 +351,23 @@ Other options worth knowing:
 needed — the data directory takes an exclusive lock, so a second node pointed at
 the same one will refuse to start.
 
-`-socks=127.0.0.1:9050` routes outbound Nostr discovery and `.btf` rendezvous
-dials through a local SOCKS5 proxy such as Tor. When it is set, the node skips
+`-socks=127.0.0.1:9050` routes outbound Nostr discovery, `.btf` rendezvous
+dials, and direct `.onion` peer dials through a local SOCKS5 proxy such as Tor.
+When it is set, the node skips
 plain HTTP external-IP probes instead of leaking a direct request outside the
 proxy. IPv6 proxy endpoints use brackets, for example `-socks=[::1]:9050`.
 
 `-tor` is a privacy shorthand for the usual local Tor SOCKS5 listener at
-`127.0.0.1:9050`. It routes outbound Nostr discovery and `.btf` rendezvous
-dials through Tor, refuses direct `.onion` resolution, and keeps external-IP
-probes disabled. Use `-tor=HOST:PORT` when Tor listens somewhere else.
+`127.0.0.1:9050`. It routes outbound Nostr discovery, `.btf` rendezvous dials,
+and signed direct `.onion` peer dials through Tor, and keeps external-IP probes
+disabled. Use `-tor=HOST:PORT` when Tor listens somewhere else.
+
+`-managedtor[=PATH]` starts a Tor process for this node, writes a local `torrc`,
+creates a v3 hidden service for port `8433`, routes outbound discovery through
+that Tor instance, and signs the generated `.onion:8433` endpoint into the
+node's `.btf` descriptor. Without `PATH`, Bitflash looks for `tor/tor.exe`,
+`tor.exe`, or `tor` beside the binary and then on `PATH`. The hidden-service key
+is stored under the Bitflash data directory in `managed-tor/onion-service/`.
 
 ### When something looks wrong
 
@@ -424,6 +454,19 @@ make windows
 ```
 Installs deps via pacman, produces `Bitflash-*-windows.zip`.
 
+To build the Windows package that also carries the Tor Expert Bundle:
+
+```bash
+make windows-tor
+```
+
+That produces `Bitflash-*-windows-with-tor.zip`. The release script downloads
+the Tor Expert Bundle from the official Tor archive, verifies its pinned SHA256,
+optionally verifies the Tor Project GPG signature when `gpg` is available, and
+places `tor/tor.exe` beside `Bitflash.exe` so `-managedtor` works without a
+separate Tor install. For release builds, use `TOR_VERIFY_GPG=required make
+windows-tor` to require the extra signature check.
+
 ---
 
 ## At a glance
diff --git a/docs/mining-calculator.md b/docs/mining-calculator.md
index 352eea1..e6cb61b 100644
--- a/docs/mining-calculator.md
+++ b/docs/mining-calculator.md
@@ -84,3 +84,25 @@ The script is intentionally standalone so the same math can later back a
 website widget or status dashboard. Until a public price exists, a website
 calculator should keep price as a manual field and label fiat profit as
 speculative.
+
+## Website Fields
+
+A public calculator should ask for:
+
+- miner hashrate and unit;
+- power draw in watts;
+- electricity price per kWh;
+- pool fee percent;
+- optional BTF price;
+- either current Bitflash difficulty or current network hashrate.
+
+The output should separate:
+
+- estimated BTF per day;
+- estimated gross fiat revenue, if a manual price was provided;
+- electricity cost;
+- net profit/loss;
+- the difficulty/hashrate assumptions used.
+
+Never present the fiat number as a market quote unless it comes from a real
+public market. Before that exists, label it as a manual scenario.
diff --git a/docs/pool-directory.md b/docs/pool-directory.md
index 76269b9..ff0640a 100644
--- a/docs/pool-directory.md
+++ b/docs/pool-directory.md
@@ -26,6 +26,10 @@ The generated output contains:
 - `index.html`: human-readable ranking page.
 - `pools.json`: machine-readable API for `api.bitflash.network/pools.json`.
 
+The website is a convenience layer, not a consensus or discovery dependency.
+Nodes discover pools through Nostr descriptors and `.btf`; a missing website
+must not stop mining or pool operation.
+
 When a source is an HTTP(S) `pool_status.json`, the directory links to a
 `pool_rounds.json` proof file next to it. That file records the block height,
 block hash, coinbase txid, coinbase value, pool fee, total shares, per-address
@@ -41,3 +45,17 @@ Ranking order is intentionally simple:
 
 An entry is considered online when the source says the pool is running and its
 status file is no more than 120 seconds old.
+
+## Recommended Hostnames
+
+Use:
+
+```text
+pool.bitflash.network        human-readable pool directory
+api.bitflash.network/pools.json
+status.bitflash.network      relay/node health, not pool ranking
+docs.bitflash.network        operator setup guide
+```
+
+The GUI may use the API as a shortcut for humans, but it should keep the
+existing decentralized pool discovery path as the source of truth.
diff --git a/docs/release-verification.md b/docs/release-verification.md
index 32de74f..b8eaf5e 100644
--- a/docs/release-verification.md
+++ b/docs/release-verification.md
@@ -34,6 +34,16 @@ From a shell with `curl` or `wget`, `sha256sum` and `gpg`:
 scripts/verify-release.sh latest
 ```
 
+The public release host should expose latest-file aliases for convenience:
+
+```text
+https://releases.bitflash.network/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS.asc
+```
+
+Those aliases must point at the current versioned directory. They do not replace
+signature verification; they only make the common manual path shorter.
+
 For a specific release:
 
 ```bash
@@ -71,6 +81,14 @@ Publish, alongside the assets, `SHA256SUMS` and `SHA256SUMS.asc`, and update
 is ever rotated, announce the new fingerprint clearly and update the embedded
 key in `verify-release.sh`.
 
+For Windows releases with managed Tor built in, run `make windows-tor`. It
+creates `Bitflash-*-windows-with-tor.zip` by downloading the Tor Expert Bundle,
+checking the pinned SHA256 in `scripts/package-windows-tor.sh`, optionally
+verifying the Tor Project `.asc` signature, and placing `tor/tor.exe` next to
+`Bitflash.exe`. For release builds, run `TOR_VERIFY_GPG=required make
+windows-tor` so the signature check is mandatory. Include that zip in
+`SHA256SUMS` like any other release asset.
+
 ## Why this matters
 
 `SHA256SUMS` alone protects against a broken download, but not against someone
diff --git a/docs/rendezvous.md b/docs/rendezvous.md
index ac8e598..68b5df3 100644
--- a/docs/rendezvous.md
+++ b/docs/rendezvous.md
@@ -18,11 +18,16 @@ A connection to a `.btf` service has three layers:
 1. **Discovery (Nostr).** The service publishes a signed descriptor as a Nostr
    event. A caller fetches it by the service public key and verifies the
    signature. The descriptor says which rendezvous relay the service is waiting
-   at and which encryption key to use.
+   at, which encryption key to use, and optionally which Tor hidden service can
+   be dialed directly.
 2. **Rendezvous (TCP).** Caller and service both connect out to the same relay
    and are paired by public key. Neither needs an inbound port or a public IP.
    After pairing the relay is a blind byte pipe.
-3. **Encrypted channel (X25519 + XChaCha20-Poly1305).** Over the paired pipe the
+3. **Direct onion fallback bypass.** If the descriptor carries a valid signed
+   `.onion:port` endpoint and the caller is running with Tor mode, the caller
+   tries that endpoint before using rendezvous. This removes the rendezvous
+   relay from the data path for peers that choose to run hidden services.
+4. **Encrypted channel (X25519 + XChaCha20-Poly1305).** Over the paired pipe the
    caller and service run an ephemeral to static handshake and then exchange
    authenticated frames. The relay sees only ciphertext.
 
@@ -107,6 +112,8 @@ The default rendezvous port is `8434`.
 The descriptor is a JSON object, signed with the identity key over a domain
 separated digest of its own fields.
 
+Legacy descriptor:
+
 ```json
 {
   "v": 2,
@@ -118,7 +125,22 @@ separated digest of its own fields.
 }
 ```
 
-The signed digest is:
+Onion-capable descriptor:
+
+```json
+{
+  "v": 3,
+  "pubkey": "<hex 32-byte x-only identity key>",
+  "enc": "<hex 32-byte X25519 public key>",
+  "meeting_node": "host:port",
+  "onion": "<56-char-v3-name>.onion:8433",
+  "created": <unix seconds>,
+  "sig": "<legacy v2 signature>",
+  "sig3": "<signature over the onion-capable digest>"
+}
+```
+
+The legacy signed digest is:
 
 ```
 digest = SHA256( ".btf-descriptor-v2"
@@ -128,17 +150,37 @@ digest = SHA256( ".btf-descriptor-v2"
                || created        (8 bytes, big endian) )
 ```
 
-The signature is a deterministic BIP340 Schnorr signature (no auxiliary
-randomness) over `digest` by the identity key.
+`sig` is kept on v3 descriptors so old nodes can still resolve and dial through
+the rendezvous relay. The onion-capable digest is:
+
+```
+digest3 = SHA256( ".btf-descriptor-v3-onion"
+                || pubkey[32]
+                || enc            (raw bytes of the string)
+                || meeting_node   (raw bytes of the string)
+                || onion          (raw bytes of the normalized string)
+                || created        (8 bytes, big endian) )
+```
+
+`sig` and `sig3` are deterministic BIP340 Schnorr signatures (no auxiliary
+randomness) over their respective digests by the identity key.
 
 **Verification** (untrusted input, must never throw): parse the JSON, require all
 fields with the right types, confirm `pubkey` equals the address being resolved,
 recompute the digest, and verify the Schnorr signature. Any failure rejects the
 descriptor.
 
+If `onion` is present, readers accept it only when it is a normalized v3 onion
+endpoint and `sig3` verifies. A bad or tampered onion field is ignored; the v2
+descriptor can still be used for rendezvous fallback if `sig` verifies.
+
 `created` lets a reader prefer the freshest descriptor when more than one is
-seen. A node only publishes a descriptor once it has actually registered at a
-`meeting_node`, so it never advertises a relay it cannot be reached at.
+seen. A node without a direct onion endpoint only publishes a descriptor once it
+has actually registered at a `meeting_node`, so it never advertises a relay it
+cannot be reached at. A node with a direct onion endpoint may publish before
+rendezvous registration using `meeting_node = "rendezvous-pending"`; Tor peers
+can still dial the signed onion endpoint, and rendezvous becomes fallback once
+registration succeeds.
 
 ## 6. Rendezvous transport
 
@@ -243,8 +285,9 @@ tunnel.
   not published anywhere.
 - **Forward secrecy.** The caller's per connection ephemeral key means a later
   compromise of the service encryption key does not decrypt past sessions.
-- **IP privacy.** Neither side needs a public IP or an inbound port. The observable
-  network fact is that each side has a TCP connection to a relay.
+- **IP privacy.** Neither side needs a public IP or an inbound port for
+  rendezvous. With a signed `.onion` endpoint, the reachable side exposes only a
+  Tor hidden service and the relay is not in the peer connection path.
 
 ## 10. Threat model and limitations
 
@@ -265,6 +308,11 @@ tunnel.
   unreachable, discovery stalls until one is reachable again. Relay TLS is
   verified, which closes a man in the middle path on discovery, but availability
   still rests on the relay set.
+- **Direct onion needs Tor.** With `-managedtor`, Bitflash starts a Tor process,
+  writes a local hidden-service config, and advertises the generated onion
+  endpoint. With `-onionservice`, an operator can still run Tor manually and
+  provide the endpoint. In both cases Tor owns the hidden-service private key and
+  uptime.
 
 ## 11. Wire reference
 
@@ -273,9 +321,9 @@ tunnel.
 | `.btf` Base32 alphabet | `abcdefghijklmnopqrstuvwxyz234567`, no padding |
 | Address payload | `pubkey[32] || checksum[2]`, 55 Base32 chars |
 | Address checksum | `SHA256(".btf-checksum-v1" || pubkey)[0..2]` |
-| Descriptor domain sep | `.btf-descriptor-v2` |
-| Descriptor version | `2` |
-| Descriptor signature | BIP340 Schnorr, deterministic (no aux rand) |
+| Descriptor domain sep | `.btf-descriptor-v2`; optional onion sep `.btf-descriptor-v3-onion` |
+| Descriptor version | `2`; `3` when a signed onion endpoint is present |
+| Descriptor signature | BIP340 Schnorr, deterministic (no aux rand), v3 keeps `sig` plus `sig3` |
 | Nostr descriptor event | kind `38501`, `d = btf-descriptor-2` |
 | Nostr relay event | kind `38502`, `d = btf-relay-2` |
 | Nostr pool event | kind `38503`, `d = btf-pool-2` |
diff --git a/docs/site.md b/docs/site.md
new file mode 100644
index 0000000..9526a61
--- /dev/null
+++ b/docs/site.md
@@ -0,0 +1,115 @@
+# Public Site Contract
+
+The public Bitflash sites are generated from this repository. If a deployed
+page and the source disagree, the deployed page is stale.
+
+## Canonical Navigation
+
+Every public page should use the same top navigation:
+
+| label | target |
+|---|---|
+| home | `https://bitflash.network/` |
+| code | `https://git.bitflash.network/bitflash/bitflash` |
+| docs | `https://docs.bitflash.network/` |
+| downloads | `https://releases.bitflash.network/` |
+| explorer | `https://explorer.bitflash.network/` |
+| status | `https://status.bitflash.network/` |
+
+The `code` link intentionally points at the repository, not the Forgejo
+instance root. A visitor choosing "code" wants the source tree.
+
+## Documentation Pages To Publish
+
+The docs index should expose these source files:
+
+| page | source | why it matters |
+|---|---|---|
+| Manual | `README.md` | run, mine, recover, operate |
+| Key derivation and address format | `docs/derivation.md` | independent wallet recovery |
+| Release verification | `docs/release-verification.md` | pinned signing-key flow |
+| Dependencies | `docs/dependencies.md` | pinned secp256k1/RandomX supply chain |
+| Rendezvous and .btf addressing | `docs/rendezvous.md` | network design and caveats |
+| Tor mode | `docs/tor.md` | `-tor`, `-socks`, onion relay operation |
+| Fair launch verifier | `docs/fair-launch.md` | no-premine launch audit |
+| UTXO set commitment | `docs/utxo-commitment.md` | deterministic supply/root audit |
+| UTXO inclusion proofs | `docs/utxo-proofs.md` | proof for one unspent output |
+| Mining calculator | `docs/mining-calculator.md` | local WhatToMine-style estimates |
+| Public pool directory | `docs/pool-directory.md` | `pool_status.json`, `pools.json`, ranking |
+
+## Release Mirror Aliases
+
+Each release remains under its versioned directory:
+
+```text
+https://releases.bitflash.network/v1.2.19/SHA256SUMS
+https://releases.bitflash.network/v1.2.19/SHA256SUMS.asc
+```
+
+The release root should also alias the latest files:
+
+```text
+https://releases.bitflash.network/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS.asc
+https://releases.bitflash.network/Bitflash-latest-windows.zip
+https://releases.bitflash.network/Bitflash-latest-x86_64.AppImage
+https://releases.bitflash.network/bitflash-node-latest-x86_64
+```
+
+The aliases are convenience only. Verification must still require the pinned
+release key documented in `docs/release-verification.md`.
+
+## Static Explorer
+
+`scripts/build-explorer.py` writes a static explorer with no backend:
+
+```text
+index.html
+style.css
+explorer.js
+logo.png
+blocks.json
+block/<height>.json
+```
+
+Serve it with a strict content policy:
+
+```text
+default-src 'none';
+img-src 'self';
+style-src 'self';
+script-src 'self';
+connect-src 'self';
+base-uri 'none';
+form-action 'none';
+frame-ancestors 'none';
+```
+
+The viewer must never use `innerHTML` for chain data. A malicious transaction
+must be rendered as text, not interpreted as markup.
+
+## Cache Policy
+
+Recommended defaults:
+
+| path | cache |
+|---|---|
+| HTML pages | `public, max-age=0, must-revalidate` |
+| `status.json` | `no-store` |
+| `blocks.json`, `block/*.json` | `public, max-age=0, must-revalidate` |
+| release assets | `public, max-age=14400, must-revalidate` |
+| `SHA256SUMS`, signatures, keys | `public, max-age=0, must-revalidate` |
+
+## Security Headers
+
+Recommended for all static pages:
+
+```text
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+Referrer-Policy: no-referrer
+Permissions-Policy: interest-cohort=(), geolocation=(), camera=(), microphone=()
+```
+
+Forgejo has its own application headers and should not blindly inherit the
+static-site CSP.
diff --git a/docs/tor.md b/docs/tor.md
index 087c822..0016f8b 100644
--- a/docs/tor.md
+++ b/docs/tor.md
@@ -25,15 +25,106 @@ bitflash -tor=127.0.0.1:9150
 bitflash -tor=[::1]:9050
 ```
 
+For a SOCKS5 proxy that is not Tor, use `-socks` directly:
+
+```bash
+bitflash -socks=127.0.0.1:9050
+bitflash -socks=[::1]:9050
+```
+
+If both `-tor` and `-socks` are present, Tor mode wins and the node prints a
+warning. That keeps a command line with `-tor` from silently becoming a custom
+proxy route.
+
+## Managed Tor mode
+
+`-managedtor` starts a Tor process for this node, writes a local `torrc`, creates
+a v3 hidden service for the normal Bitflash P2P listener, routes outbound
+discovery through that Tor instance, and signs the generated `.onion:8433`
+endpoint into the node's `.btf` descriptor.
+
+```bash
+bitflash -managedtor
+```
+
+Without a value, Bitflash looks for Tor in this order:
+
+1. `tor/tor.exe` or `tor/tor` beside the Bitflash binary;
+2. `tor.exe` or `tor` beside the Bitflash binary;
+3. `tor.exe` or `tor` on `PATH`.
+
+Windows releases can also be built as `Bitflash-*-windows-with-tor.zip`. That
+package includes the official Tor Expert Bundle under `tor/`, so the first path
+above exists immediately after extraction and `bitflash -managedtor` needs no
+separate Tor install.
+
+The bundled-Tor package is created by:
+
+```bash
+make windows-tor
+```
+
+The packaging script verifies a pinned SHA256 for the downloaded Tor Expert
+Bundle before copying it into the release directory. When `gpg` is available it
+also verifies the matching `.asc` signature against the pinned Tor Browser
+Developers signing-key fingerprint. Release builds should use
+`TOR_VERIFY_GPG=required make windows-tor` to make that second check mandatory.
+The Tor binary is bundled; the runtime data directory, hidden-service key, and
+control cookie are still created under the user's Bitflash data directory.
+
+To point at a specific Tor executable:
+
+```bash
+bitflash -managedtor=/opt/tor/bin/tor
+bitflash -managedtor=C:\Tor Browser\Browser\TorBrowser\Tor\tor.exe
+```
+
+Managed Tor writes its state under the Bitflash data directory:
+
+```text
+managed-tor/
+  torrc
+  data/
+  onion-service/
+```
+
+The private key for the onion address lives in `managed-tor/onion-service/`.
+Back up that directory if you want the same onion address after moving the node.
+Delete it only if you intentionally want a fresh onion endpoint.
+
+`-managedtor` takes precedence over `-tor` and `-socks`, because it must choose
+the local SOCKS port it starts. Diagnostics report the current managed Tor
+state, including the SOCKS port and onion endpoint once Tor has generated it.
+
 When Tor mode is enabled:
 
 - outbound Nostr relay dials use Tor;
 - outbound `.btf` rendezvous relay dials use Tor;
+- outbound direct peer dials prefer signed `.onion` endpoints when a peer
+  advertises one;
 - destination names are sent to Tor as SOCKS5 domain-name CONNECT requests, so
   the local DNS resolver does not see them;
 - direct `.onion` dials are refused unless a SOCKS5/Tor proxy is enabled;
 - plain HTTP external-IP probes are skipped.
 
+Tor mode affects outbound discovery and relay dials. It does not encrypt
+`wallet.dat`, hide mining rewards on-chain, or change the `.btf` identity. A
+relay still sees the TCP client that connected to it; with Tor mode that client
+is the Tor exit or onion circuit endpoint instead of the user's direct IP.
+
+## What to test
+
+Use the public status page only as a rough health check. To prove the local node
+is using Tor/SOCKS, test from the node machine:
+
+```bash
+bitflash -tor -debug
+```
+
+Then confirm in `debug.log` that Nostr and rendezvous dials report the proxy
+path. A DNS leak test should show no local resolver lookup for relay hostnames:
+the SOCKS5 request uses the domain-name form and asks the proxy to resolve it.
+
 ## Onion rendezvous relay
 
 An operator can expose a Bitflash rendezvous relay as a Tor hidden service. The
@@ -69,16 +160,72 @@ bitflash -operator -tor \
   -announcerelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
 ```
 
-## Full-node hidden service
+## Manual direct full-node hidden service
 
-The legacy P2P listener still binds to port `8433`. You can expose it through
-Tor manually:
+Managed Tor is the preferred path for ordinary nodes. Operators can still expose
+the P2P listener through a separately managed Tor service:
 
 ```text
 HiddenServiceDir /var/lib/tor/bitflash-node/
 HiddenServicePort 8433 127.0.0.1:8433
 ```
 
-Current automatic peer discovery is `.btf`/rendezvous based, not onion-address
-gossip. Treat direct full-node onion access as an operator/admin tool unless a
-future release adds first-class onion peer advertisements.
+After restarting Tor, read the generated onion name:
+
+```bash
+sudo cat /var/lib/tor/bitflash-node/hostname
+```
+
+Then start Bitflash with Tor outbound enabled and advertise that hidden service:
+
+```bash
+bitflash -tor \
+  -onionservice=exampleexampleexampleexampleexampleexampleexampleexample.onion:8433
+```
+
+That onion endpoint is signed into this node's self-certifying `.btf`
+descriptor. New peers that resolve the descriptor and also run with `-tor` try
+the `.onion:8433` P2P connection first. If it fails, they fall back to the
+ordinary encrypted rendezvous path. Older nodes ignore the onion field and still
+use the rendezvous relay because the descriptor keeps the legacy signature too.
+
+If the node has `-onionservice` but has not registered at any rendezvous relay
+yet, it can still publish an onion-capable descriptor with
+`meeting_node = rendezvous-pending`. Tor-capable peers can dial the hidden
+service directly from that descriptor. Rendezvous becomes a fallback, not a
+precondition for being discoverable.
+
+This means rendezvous relays stop being the only way to reach a node that has
+published a hidden service. They remain useful bootstrap/fallback infrastructure,
+but an already-discovered onion-capable peer can be reached directly over Tor.
+
+Tor owns the private key under `HiddenServiceDir`; back it up if you want the
+onion name to stay stable.
+
+## Release smoke test
+
+After building a Windows binary with managed Tor support, run the two-node smoke
+test before cutting a release:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\smoke-managed-tor-onion.ps1 `
+  -Bitflash .\src\bitflash.exe `
+  -Tor C:\path\to\tor.exe
+```
+
+The script creates two temporary datadirs, starts node A with `-managedtor`,
+waits for it to publish its `.btf` identity and generated `.onion` endpoint,
+then starts node B with its own `-managedtor`, `-oniononly`, and
+`-connectbtf=<node-a>`. It passes only when node B logs that it connected to
+node A `via direct onion`; rendezvous fallback cannot satisfy the test.
+
+By default the script waits 120 seconds after node A's descriptor self-resolves
+before it starts node B. Tor can create the local `hostname` before the hidden
+service descriptor is visible enough for client circuits, and early dials often
+fail with SOCKS5 reply `0x01`. Override this with `-OnionWarmupSec N` when
+testing a slow or already-warmed Tor environment.
+
+This test still uses Nostr for descriptor discovery, because that is how nodes
+learn each other's signed `.btf` descriptors. It does not require a Bitflash
+rendezvous relay to carry the P2P connection: once the descriptor includes the
+signed onion endpoint, the actual node connection goes directly through Tor.
diff --git a/scripts/build-explorer.py b/scripts/build-explorer.py
index 97a7f4e..dbb8e17 100755
--- a/scripts/build-explorer.py
+++ b/scripts/build-explorer.py
@@ -4,6 +4,7 @@
 import argparse
 import hashlib
 import json
+import shutil
 import sys
 from pathlib import Path
 
@@ -148,6 +149,11 @@ def build_explorer(raw_blocks, out_dir):
         encoding="ascii",
     )
     (out / "index.html").write_text(INDEX_HTML, encoding="utf-8")
+    (out / "style.css").write_text(STYLE_CSS, encoding="utf-8")
+    (out / "explorer.js").write_text(EXPLORER_JS, encoding="utf-8")
+    logo = Path(__file__).resolve().parents[1] / "docs" / "logo.png"
+    if logo.exists():
+        shutil.copyfile(logo, out / "logo.png")
     return len(blocks), len(blocks) - 1
 
 
@@ -167,43 +173,26 @@ INDEX_HTML = r"""<!doctype html>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Bitflash Block Explorer</title>
-<style>
-  :root { color-scheme: light dark; --bg:#fff; --fg:#111; --mut:#666; --line:#e2e2e2; --card:#fafafa; --acc:#2b6cb0; }
-  @media (prefers-color-scheme: dark){ :root{ --bg:#0e0f11; --fg:#e6e6e6; --mut:#9aa0a6; --line:#26282c; --card:#16181b; --acc:#63b3ed; } }
-  * { box-sizing: border-box; }
-  body { font: 15px/1.5 system-ui, sans-serif; margin:0; background:var(--bg); color:var(--fg); }
-  header { padding:20px 24px; border-bottom:1px solid var(--line); display:flex; gap:16px; align-items:baseline; flex-wrap:wrap; }
-  h1 { font-size:18px; margin:0; }
-  h2 { font-size:16px; }
-  .mut { color:var(--mut); }
-  .wrap { padding:16px 24px; max-width:1100px; margin:0 auto; }
-  input { width:100%; max-width:420px; padding:9px 12px; border:1px solid var(--line); border-radius:8px; background:var(--card); color:var(--fg); font-size:14px; }
-  table { width:100%; border-collapse:collapse; margin-top:12px; }
-  th,td { text-align:left; padding:9px 10px; border-bottom:1px solid var(--line); font-variant-numeric:tabular-nums; }
-  th { font-size:12px; text-transform:uppercase; letter-spacing:.05em; color:var(--mut); }
-  tr.blk { cursor:pointer; }
-  tr.blk:hover td { background:var(--card); }
-  code { font-size:12px; word-break:break-all; }
-  .scroll { overflow-x:auto; }
-  .card { border:1px solid var(--line); border-radius:10px; background:var(--card); padding:14px 16px; margin-top:12px; }
-  .kv { display:grid; grid-template-columns:150px 1fr; gap:4px 12px; font-size:13px; }
-  .kv div:nth-child(odd){ color:var(--mut); }
-  .tx { border-top:1px solid var(--line); padding:10px 0; }
-  .io { display:grid; grid-template-columns:1fr 1fr; gap:16px; }
-  @media (max-width:640px){ .io{ grid-template-columns:1fr; } .kv{ grid-template-columns:110px 1fr; } }
-  .pill { display:inline-block; font-size:11px; padding:1px 7px; border-radius:99px; border:1px solid var(--line); color:var(--mut); }
-  button.link { background:none; border:none; color:var(--acc); cursor:pointer; font:inherit; padding:0; }
-  .note { color:var(--mut); font-size:13px; max-width:820px; }
-</style>
+<meta name="description" content="Read-only Bitflash block explorer generated from local blk*.dat files.">
+<link rel="icon" href="logo.png" type="image/png">
+<link rel="stylesheet" href="style.css">
+<script src="explorer.js" defer></script>
 </head>
 <body>
-<header>
-  <h1>Bitflash Block Explorer</h1>
-  <span class="mut" id="tip"></span>
-  <span style="flex:1"></span>
-  <button class="link" id="home" style="display:none">back to blocks</button>
+<header class="topbar">
+  <a class="brand" href="https://bitflash.network/"><img src="logo.png" width="22" height="22" alt="">Bitflash</a>
+  <nav aria-label="Bitflash sites">
+    <a href="https://bitflash.network/">home</a>
+    <a href="https://git.bitflash.network/bitflash/bitflash">code</a>
+    <a href="https://docs.bitflash.network/">docs</a>
+    <a href="https://releases.bitflash.network/">downloads</a>
+    <a href="https://explorer.bitflash.network/" aria-current="page">explorer</a>
+    <a href="https://status.bitflash.network/">status</a>
+  </nav>
+  <span class="meta" id="tip"></span>
 </header>
 <div class="wrap">
+  <h1>Block explorer <button class="link" id="home" hidden>back to blocks</button></h1>
   <p class="note">Read-only view of the main chain: blocks, their transactions, and the coinbase payout. There is no mempool and no per-address history here.</p>
   <div id="listview">
     <input id="q" placeholder="Search by height or block hash">
@@ -213,9 +202,63 @@ INDEX_HTML = r"""<!doctype html>
     </table></div>
     <p class="mut" id="more"></p>
   </div>
-  <div id="detail" style="display:none"></div>
+  <div id="detail" hidden></div>
 </div>
-<script>
+</body>
+</html>
+"""
+
+
+STYLE_CSS = r""":root{
+  color-scheme: light dark;
+  --bg:#fff; --bg-2:#f6f6f6; --fg:#111; --dim:#6b6b6b; --line:#d7d7d7; --line-hard:#111;
+  --accent:#0b7a34; --accent-2:#12a047; --bar:3rem;
+  --mono: ui-monospace,"Cascadia Mono","Segoe UI Mono",Consolas,"DejaVu Sans Mono","Liberation Mono","Courier New",monospace;
+}
+@media (prefers-color-scheme: dark){:root{
+  --bg:#000; --bg-2:#0b0b0b; --fg:#dcdcdc; --dim:#8a8a8a; --line:#242424; --line-hard:#4a4a4a;
+  --accent:#2ee06a; --accent-2:#6bff9f;
+}}
+*{box-sizing:border-box;}
+html,body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 var(--mono);-webkit-text-size-adjust:100%;}
+a{color:var(--accent);}
+.topbar{display:flex;align-items:center;gap:1rem;flex-wrap:wrap;min-height:var(--bar);
+        padding:.5rem clamp(.9rem,2.5vw,3rem);border-bottom:1px solid var(--line);position:sticky;top:0;background:var(--bg);z-index:5;}
+.brand{display:flex;align-items:center;gap:.6rem;text-decoration:none;color:var(--fg);font-weight:bold;}
+.brand img{width:22px;height:22px;display:block;}
+.topbar nav{display:flex;flex-wrap:wrap;gap:.15rem 1.4rem;font-size:.86rem;}
+.topbar nav a{text-decoration:none;color:var(--dim);}
+.topbar nav a::before{content:"/";color:var(--line-hard);margin-right:.3rem;}
+.topbar nav a:hover{color:var(--fg);text-decoration:underline;}
+.topbar nav a[aria-current="page"]{color:var(--accent);font-weight:bold;}
+.topbar nav a[aria-current="page"]::before{color:var(--accent);}
+.topbar .meta{margin-left:auto;font-size:.76rem;color:var(--dim);letter-spacing:.06em;}
+.wrap{padding:1.4rem clamp(.9rem,2.5vw,3rem) 4rem;}
+h1{font-size:1rem;margin:0 0 .3rem;letter-spacing:.02em;}
+h2{font-size:.95rem;margin:1.2rem 0 .4rem;}
+.mut{color:var(--dim);}
+.note{color:var(--dim);font-size:.82rem;max-width:60rem;margin:.2rem 0 1rem;}
+input{width:100%;max-width:28rem;padding:.5rem .7rem;border:1px solid var(--line);background:var(--bg-2);color:var(--fg);font:inherit;font-size:.86rem;}
+input:focus{outline:none;border-color:var(--accent);}
+.scroll{overflow-x:auto;}
+table{width:100%;border-collapse:collapse;margin-top:.8rem;font-size:.86rem;}
+th,td{text-align:left;padding:.5rem .6rem;border-bottom:1px solid var(--line);font-variant-numeric:tabular-nums;}
+th{font-size:.72rem;text-transform:uppercase;letter-spacing:.1em;color:var(--dim);font-weight:normal;}
+tr.blk{cursor:pointer;}
+tr.blk:hover td{background:var(--bg-2);}
+code{font-size:.8rem;word-break:break-all;color:var(--fg);}
+.card{border:1px solid var(--line);background:var(--bg-2);padding:.9rem 1rem;margin-top:.8rem;}
+.kv{display:grid;grid-template-columns:11rem 1fr;gap:.25rem .8rem;font-size:.82rem;}
+.kv div:nth-child(odd){color:var(--dim);}
+.tx{border-top:1px solid var(--line);padding:.7rem 0;}
+.io{display:grid;grid-template-columns:1fr 1fr;gap:1rem;}
+@media (max-width:640px){.io{grid-template-columns:1fr;}.kv{grid-template-columns:7rem 1fr;}.topbar .meta{margin-left:0;width:100%;}}
+.pill{display:inline-block;font-size:.68rem;padding:.05rem .5rem;border:1px solid var(--line);color:var(--dim);text-transform:uppercase;letter-spacing:.05em;}
+button.link{background:none;border:none;color:var(--accent);cursor:pointer;font:inherit;padding:0;text-decoration:underline;}
+"""
+
+
+EXPLORER_JS = r"""
 var SUM = [], SHOWN = 200;
 function btf(sat){ return (sat/1e8).toFixed(8).replace(/0+$/,'').replace(/\.$/,'')+" BTF"; }
 function ts(t){ return new Date(t*1000).toISOString().replace('T',' ').replace('.000Z',' UTC'); }
@@ -310,25 +353,22 @@ function openBlock(h){
       }));
       append(tx, head, io); append(detail, tx);
     });
-    document.getElementById('listview').style.display='none';
-    detail.style.display='block';
-    document.getElementById('home').style.display='inline';
+    document.getElementById('listview').hidden = true;
+    detail.hidden = false;
+    document.getElementById('home').hidden = false;
     window.scrollTo(0,0);
   });
 }
 document.getElementById('home').onclick=function(){
-  document.getElementById('detail').style.display='none';
-  document.getElementById('listview').style.display='block';
-  this.style.display='none';
+  document.getElementById('detail').hidden = true;
+  document.getElementById('listview').hidden = false;
+  this.hidden = true;
 };
 document.getElementById('q').oninput=function(){ renderList(this.value); };
 fetch('blocks.json').then(function(r){return r.json();}).then(function(d){
   SUM=d.blocks; document.getElementById('tip').textContent='tip height '+d.tipHeight+' - '+d.count+' blocks';
   renderList('');
 });
-</script>
-</body>
-</html>
 """
 
 
diff --git a/scripts/make-release-checksums.sh b/scripts/make-release-checksums.sh
index 5b29e2d..9c4f45a 100755
--- a/scripts/make-release-checksums.sh
+++ b/scripts/make-release-checksums.sh
@@ -10,6 +10,7 @@ Usage: scripts/make-release-checksums.sh [--sign] [--local-user KEYID]
 
 Creates SHA256SUMS for release assets in the current directory:
   Bitflash-*-windows.zip
+  Bitflash-*-windows-with-tor.zip
   Bitflash-*-x86_64.AppImage
   bitflash-node-*-x86_64
 
@@ -44,6 +45,7 @@ fi
 assets=()
 for pattern in \
   "Bitflash-*-windows.zip" \
+  "Bitflash-*-windows-with-tor.zip" \
   "Bitflash-*-x86_64.AppImage" \
   "bitflash-node-*-x86_64"
 do
diff --git a/scripts/package-windows-tor.sh b/scripts/package-windows-tor.sh
new file mode 100755
index 0000000..c8cca3b
--- /dev/null
+++ b/scripts/package-windows-tor.sh
@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="${VERSION:-$(sed -n 's/^VERSION[[:space:]]*:= *//p' "$ROOT/Makefile" | head -1)}"
+
+TOR_VERSION="${TOR_VERSION:-15.0.19}"
+TOR_ARCHIVE_NAME="tor-expert-bundle-windows-x86_64-${TOR_VERSION}.tar.gz"
+TOR_URL="${TOR_URL:-https://archive.torproject.org/tor-package-archive/torbrowser/${TOR_VERSION}/${TOR_ARCHIVE_NAME}}"
+TOR_SHA256="${TOR_SHA256:-6AC067402C7B4A3DC37887ED3754B3914B67FDC220C966190683E9CCF91ABF0F}"
+TOR_ASC_URL="${TOR_ASC_URL:-${TOR_URL}.asc}"
+TOR_SIGNING_KEY_FINGERPRINT="${TOR_SIGNING_KEY_FINGERPRINT:-EF6E286DDA85EA2A4BA7DE684E2C6E8793298290}"
+TOR_VERIFY_GPG="${TOR_VERIFY_GPG:-auto}"
+
+BUNDLE_DIR="${BUNDLE_DIR:-$ROOT/Bitflash-${VERSION}-windows}"
+OUT_ZIP="${OUT_ZIP:-$ROOT/Bitflash-${VERSION}-windows-with-tor.zip}"
+CACHE_DIR="${CACHE_DIR:-$ROOT/.cache}"
+ARCHIVE="${TOR_ARCHIVE:-$CACHE_DIR/$TOR_ARCHIVE_NAME}"
+ASC_FILE="${TOR_ASC:-$ARCHIVE.asc}"
+
+usage() {
+  cat <<EOF
+Usage: scripts/package-windows-tor.sh
+
+Creates Bitflash-${VERSION}-windows-with-tor.zip from an existing
+Bitflash-${VERSION}-windows/ release directory.
+
+Environment overrides:
+  VERSION       Bitflash release version, default read from Makefile
+  TOR_VERSION   Tor Expert Bundle version, default ${TOR_VERSION}
+  TOR_URL       Download URL, default official Tor archive URL
+  TOR_ASC_URL   Signature URL, default TOR_URL.asc
+  TOR_SHA256    Expected archive SHA256
+  TOR_ARCHIVE   Use an existing archive instead of downloading
+  TOR_ASC       Use an existing detached signature
+  TOR_VERIFY_GPG auto, required, or off; default auto
+  BUNDLE_DIR    Existing unpacked Windows release directory
+  OUT_ZIP       Output zip path
+EOF
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+need() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "missing required command: $1" >&2
+    exit 1
+  }
+}
+
+need sha256sum
+need tar
+need zip
+
+download() {
+  local url="$1"
+  local out="$2"
+  if command -v curl >/dev/null 2>&1; then
+    curl -L --fail --output "$out" "$url"
+  elif command -v wget >/dev/null 2>&1; then
+    wget -O "$out" "$url"
+  else
+    echo "missing required command: curl or wget" >&2
+    exit 1
+  fi
+}
+
+if [ ! -d "$BUNDLE_DIR" ]; then
+  echo "missing Windows release directory: $BUNDLE_DIR" >&2
+  echo "run 'make windows' first, or set BUNDLE_DIR" >&2
+  exit 1
+fi
+if [ ! -f "$BUNDLE_DIR/Bitflash.exe" ]; then
+  echo "missing Bitflash.exe in $BUNDLE_DIR" >&2
+  exit 1
+fi
+BUNDLE_PARENT="$(cd "$(dirname "$BUNDLE_DIR")" && pwd)"
+BUNDLE_NAME="$(basename "$BUNDLE_DIR")"
+OUT_PARENT="$(mkdir -p "$(dirname "$OUT_ZIP")" && cd "$(dirname "$OUT_ZIP")" && pwd)"
+OUT_NAME="$(basename "$OUT_ZIP")"
+OUT_ZIP_ABS="$OUT_PARENT/$OUT_NAME"
+
+mkdir -p "$CACHE_DIR"
+if [ ! -f "$ARCHIVE" ]; then
+  download "$TOR_URL" "$ARCHIVE"
+fi
+
+got="$(sha256sum "$ARCHIVE" | awk '{print tolower($1)}')"
+want="$(printf '%s' "$TOR_SHA256" | tr 'A-F' 'a-f')"
+if [ "$got" != "$want" ]; then
+  echo "Tor archive SHA256 mismatch" >&2
+  echo "  expected: $want" >&2
+  echo "       got: $got" >&2
+  exit 1
+fi
+
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/bitflash-tor-package.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT
+
+case "$TOR_VERIFY_GPG" in
+  auto|required|off) ;;
+  *) echo "TOR_VERIFY_GPG must be auto, required, or off" >&2; exit 2 ;;
+esac
+
+if [ "$TOR_VERIFY_GPG" != "off" ]; then
+  if command -v gpg >/dev/null 2>&1; then
+    if [ ! -f "$ASC_FILE" ]; then
+      download "$TOR_ASC_URL" "$ASC_FILE"
+    fi
+    gnupg_home="$tmp/gnupg"
+    mkdir -p "$gnupg_home"
+    chmod 0700 "$gnupg_home"
+    gpg --homedir "$gnupg_home" --batch --auto-key-locate nodefault,wkd,keyserver \
+      --locate-keys torbrowser@torproject.org >/dev/null 2>&1 || {
+        if [ "$TOR_VERIFY_GPG" = "required" ]; then
+          echo "could not import Tor Browser Developers signing key" >&2
+          exit 1
+        fi
+        echo "WARNING: skipped Tor GPG signature verification; signing key import failed" >&2
+      }
+    if gpg --homedir "$gnupg_home" --batch --with-colons --fingerprint "$TOR_SIGNING_KEY_FINGERPRINT" \
+        2>/dev/null | grep -q "^fpr:::::::::${TOR_SIGNING_KEY_FINGERPRINT}:"; then
+      gpg --homedir "$gnupg_home" --batch --verify "$ASC_FILE" "$ARCHIVE" >/dev/null 2>&1 || {
+        echo "Tor archive GPG signature verification failed" >&2
+        exit 1
+      }
+      echo "Tor archive GPG signature verified against ${TOR_SIGNING_KEY_FINGERPRINT}"
+    elif [ "$TOR_VERIFY_GPG" = "required" ]; then
+      echo "Tor signing key fingerprint mismatch" >&2
+      exit 1
+    else
+      echo "WARNING: skipped Tor GPG signature verification; signing key fingerprint was not available" >&2
+    fi
+  elif [ "$TOR_VERIFY_GPG" = "required" ]; then
+    echo "missing required command for TOR_VERIFY_GPG=required: gpg" >&2
+    exit 1
+  else
+    echo "WARNING: gpg not found; relying on pinned SHA256 only" >&2
+  fi
+fi
+
+mkdir -p "$tmp/extract"
+tar -xzf "$ARCHIVE" -C "$tmp/extract"
+
+if [ ! -f "$tmp/extract/tor/tor.exe" ]; then
+  echo "Tor archive did not contain tor/tor.exe" >&2
+  exit 1
+fi
+
+rm -rf "$BUNDLE_DIR/tor"
+mkdir -p "$BUNDLE_DIR/tor"
+cp -R "$tmp/extract/tor/." "$BUNDLE_DIR/tor/"
+if [ -d "$tmp/extract/docs" ]; then
+  mkdir -p "$BUNDLE_DIR/tor/docs"
+  cp -R "$tmp/extract/docs/." "$BUNDLE_DIR/tor/docs/"
+fi
+if [ -d "$tmp/extract/data" ]; then
+  mkdir -p "$BUNDLE_DIR/tor/data-defaults"
+  cp -R "$tmp/extract/data/." "$BUNDLE_DIR/tor/data-defaults/"
+fi
+
+cat > "$BUNDLE_DIR/TOR-EXPERT-BUNDLE.txt" <<EOF
+Bitflash managed Tor bundle
+
+This Windows package includes the Tor Expert Bundle so -managedtor can start
+Tor without requiring a separate Tor install.
+
+Tor Expert Bundle: ${TOR_VERSION}
+Archive URL: ${TOR_URL}
+Archive SHA256: ${TOR_SHA256}
+
+Bitflash uses tor/tor.exe from this package. Runtime state, hidden-service keys,
+and control authentication cookies are written under the user's Bitflash data
+directory, not inside this release directory.
+EOF
+
+rm -f "$OUT_ZIP_ABS"
+(
+  cd "$BUNDLE_PARENT"
+  zip -qr "$OUT_ZIP_ABS" "$BUNDLE_NAME"
+)
+
+echo "Bundled Tor Expert Bundle ${TOR_VERSION}"
+echo "Built: $OUT_ZIP_ABS"
diff --git a/scripts/smoke-managed-tor-onion.ps1 b/scripts/smoke-managed-tor-onion.ps1
new file mode 100644
index 0000000..70658c7
--- /dev/null
+++ b/scripts/smoke-managed-tor-onion.ps1
@@ -0,0 +1,174 @@
+param(
+    [string]$Bitflash,
+    [string]$Tor,
+    [string]$WorkDir,
+    [int]$TimeoutSec = 600,
+    [int]$OnionWarmupSec = 120
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-RepoRoot {
+    $scriptDir = Split-Path -Parent $PSCommandPath
+    return (Resolve-Path (Join-Path $scriptDir "..")).Path
+}
+
+function Get-FreeTcpPort {
+    $listener = [Net.Sockets.TcpListener]::new([Net.IPAddress]::Loopback, 0)
+    $listener.Start()
+    try {
+        return ([Net.IPEndPoint]$listener.LocalEndpoint).Port
+    }
+    finally {
+        $listener.Stop()
+    }
+}
+
+function Wait-RegexInFile {
+    param(
+        [string]$Path,
+        [string]$Pattern,
+        [datetime]$Deadline,
+        [string]$Label
+    )
+
+    while ((Get-Date) -lt $Deadline) {
+        if (Test-Path $Path) {
+            $text = Get-Content -Raw -ErrorAction SilentlyContinue $Path
+            if ($null -ne $text) {
+                $m = [regex]::Match($text, $Pattern)
+                if ($m.Success) {
+                    return $m
+                }
+            }
+        }
+        Start-Sleep -Milliseconds 500
+    }
+    throw "timed out waiting for $Label"
+}
+
+function Stop-TestProcesses {
+    param(
+        [System.Diagnostics.Process[]]$Processes,
+        [string[]]$DataDirKeys
+    )
+
+    foreach ($p in $Processes) {
+        try {
+            $p.Refresh()
+            if (!$p.HasExited) {
+                Stop-Process -Id $p.Id -Force
+            }
+        }
+        catch {}
+    }
+
+    foreach ($key in $DataDirKeys) {
+        if ([string]::IsNullOrWhiteSpace($key)) {
+            continue
+        }
+        try {
+            Get-CimInstance Win32_Process -Filter "name = 'tor.exe'" |
+                Where-Object { $_.CommandLine -like "*$key*" } |
+                ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
+        }
+        catch {}
+    }
+}
+
+$repo = Resolve-RepoRoot
+if ([string]::IsNullOrWhiteSpace($Bitflash)) {
+    $Bitflash = Join-Path $repo "src\bitflash.exe"
+}
+if ([string]::IsNullOrWhiteSpace($Tor)) {
+    $candidates = @(
+        (Join-Path $repo "src\tor\tor.exe"),
+        (Join-Path $repo "Bitflash-$(Select-String -Path (Join-Path $repo 'Makefile') -Pattern '^VERSION[ ]*:=' | ForEach-Object { ($_.Line -split ':=')[1].Trim() })-windows\tor\tor.exe")
+    )
+    foreach ($candidate in $candidates) {
+        if (Test-Path $candidate) {
+            $Tor = $candidate
+            break
+        }
+    }
+}
+if ([string]::IsNullOrWhiteSpace($WorkDir)) {
+    $WorkDir = Join-Path $env:TEMP ("bitflash-managed-tor-two-node-" + (Get-Date -Format "yyyyMMddHHmmss"))
+}
+
+if (!(Test-Path $Bitflash)) {
+    throw "Bitflash binary not found: $Bitflash"
+}
+if (!(Test-Path $Tor)) {
+    throw "Tor binary not found. Pass -Tor or build the Windows-with-Tor package."
+}
+
+New-Item -ItemType Directory -Force -Path $WorkDir | Out-Null
+$dataA = Join-Path $WorkDir "node-a"
+$dataB = Join-Path $WorkDir "node-b"
+New-Item -ItemType Directory -Force -Path $dataA | Out-Null
+New-Item -ItemType Directory -Force -Path $dataB | Out-Null
+
+$portA = Get-FreeTcpPort
+$portB = Get-FreeTcpPort
+$deadline = (Get-Date).AddSeconds($TimeoutSec)
+$oldPath = $env:PATH
+$env:PATH = "C:\msys64\ucrt64\bin;C:\msys64\usr\bin;" + $env:PATH
+
+$procA = $null
+$procB = $null
+$dataKeys = @((Split-Path $WorkDir -Leaf))
+
+try {
+    $argsA = @(
+        "-datadir=$dataA",
+        "-port=$portA",
+        "-managedtor=$Tor",
+        "-nogui",
+        "-debug",
+        "-checkblocks=0"
+    )
+    $procA = Start-Process -FilePath $Bitflash -ArgumentList $argsA -WorkingDirectory (Split-Path $Bitflash -Parent) -PassThru -WindowStyle Hidden
+    $logA = Join-Path $dataA "debug.log"
+
+    $btfMatch = Wait-RegexInFile -Path $logA -Pattern "Nostr: node \.btf address = ([a-z2-7]+\.btf)" -Deadline $deadline -Label "node A .btf address"
+    $btfA = $btfMatch.Groups[1].Value
+
+    $onionMatch = Wait-RegexInFile -Path $logA -Pattern "Managed Tor hidden service ready: ([a-z2-7]{56}\.onion:\d+)" -Deadline $deadline -Label "node A managed onion"
+    $onionA = $onionMatch.Groups[1].Value
+
+    Wait-RegexInFile -Path $logA -Pattern "Nostr: \.btf self-resolve OK via .*" -Deadline $deadline -Label "node A descriptor self-resolve" | Out-Null
+    if ($OnionWarmupSec -gt 0) {
+        Write-Host "Waiting $OnionWarmupSec second(s) for Tor hidden-service descriptor propagation"
+        Start-Sleep -Seconds $OnionWarmupSec
+    }
+
+    $argsB = @(
+        "-datadir=$dataB",
+        "-port=$portB",
+        "-managedtor=$Tor",
+        "-oniononly",
+        "-connectbtf=$btfA",
+        "-nogui",
+        "-debug",
+        "-checkblocks=0"
+    )
+    $procB = Start-Process -FilePath $Bitflash -ArgumentList $argsB -WorkingDirectory (Split-Path $Bitflash -Parent) -PassThru -WindowStyle Hidden
+    $logB = Join-Path $dataB "debug.log"
+
+    Wait-RegexInFile -Path $logB -Pattern ("connected " + [regex]::Escape($btfA) + " via direct onion ") -Deadline $deadline -Label "node B direct onion connection to node A" | Out-Null
+
+    Write-Host "Managed Tor two-node onion smoke test passed"
+    Write-Host "  node A .btf:   $btfA"
+    Write-Host "  node A onion:  $onionA"
+    Write-Host "  node A port:   $portA"
+    Write-Host "  node B port:   $portB"
+    Write-Host "  work dir:      $WorkDir"
+}
+finally {
+    $env:PATH = $oldPath
+    $procs = @()
+    if ($null -ne $procA) { $procs += $procA }
+    if ($null -ne $procB) { $procs += $procB }
+    Stop-TestProcesses -Processes $procs -DataDirKeys $dataKeys
+}
diff --git a/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.
diff --git a/tests/scripts/test_bitflash_tools.py b/tests/scripts/test_bitflash_tools.py
index 4b18d1e..3b4c846 100644
--- a/tests/scripts/test_bitflash_tools.py
+++ b/tests/scripts/test_bitflash_tools.py
@@ -159,8 +159,11 @@ def compare_golden(name, actual, update):
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_bytes(actual)
         return
-    expected = path.read_bytes()
-    if actual != expected:
+    # The tools promise canonical LF-terminated JSON. On Windows checkouts a
+    # fixture may still appear as CRLF in the working tree; normalize only line
+    # endings so content, field order and compact serialization still drift-test.
+    expected = path.read_bytes().replace(b"\r\n", b"\n")
+    if actual.replace(b"\r\n", b"\n") != expected:
         raise AssertionError("golden mismatch: %s" % name)