Adds a section to doc/tor.md warning against running -onlynet=onion. Covers eclipse attack risk, Tor centralization, on-chain privacy misconceptions, and documents the dnsseed/dns gotchas for anyone who proceeds anyway.
Reworked based on feedback from luke-jr and pinheadmz. Originally started as a how-to guide after hitting the undocumented dnsseed incompatibility on a Pi 5 setup.
Documentation only, no code changes.
The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.
See the guideline for information on the review process.
| Type | Reviewers |
|---|---|
| Concept ACK | aandia |
If your review is incorrectly listed, please copy-paste <!–meta-tag:bot-skip–> into the comment that the bot should ignore.
Tor is a centralised network, so Tor-only usage should be discouraged.
You should probably also note that Tor does not make actual Bitcoin usage much more private (ie, on-chain)
Add a new section documenting how to configure and operate a
Tor-only Bitcoin Core node. This covers:
- Minimal bitcoin.conf for onlynet=onion
- The dnsseed/dns incompatibility with onlynet (which causes a
hard exit with a non-obvious error message)
- Peer discovery mechanisms when DNS seeding is unavailable
- How to verify onion address advertisement
These are common pain points encountered when setting up a
privacy-focused Tor-only node, particularly on resource-constrained
hardware like ARM64 single-board computers.
Concept ACK
Reads as a clear, practical guide for running a Tor-only node with -onlynet=onion, and the added notes around Tor’s limitations help set the right expectations .
Two small suggestions:
** It might help to briefly frame earlier when a Tor-only setup is preferable vs. a bridge node, to make the trade-offs clear before the config section.
** For the getnetworkinfo verification step, explicitly mentioning the expected fields (localaddresses, reachable: true for onion only) could make it more concrete for first-time users.
248+directory authorities. Running `-onlynet=onion` makes your node entirely
249+dependent on Tor's availability and integrity. If Tor is unavailable, your
250+node will be unable to connect to any peers. For most users, running a node
251+that is reachable on both clearnet and Tor (a "bridge" node) is preferable, as
252+it strengthens the Bitcoin network's resistance to partitioning while still
253+allowing Tor connections (see Section 5).
Not just this but since onion identities are free, it is trivial to eclipse a node with such a configuration:
https://bitcoin.stackexchange.com/q/116146/3667
For this reason I doubt you will get any support for this PR unless the warning is bright red and repeated often. In fact, a better PR might be to discourage “only Tor” entirely.
- Add "When to use Tor-only vs. a bridge node" subsection before config
- Make getnetworkinfo verification step more concrete with expected fields
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Reframe Section 4 from a how-to guide into warnings against Tor-only
operation, based on reviewer feedback about eclipse attack risk and
Tor centralization.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
271+
272+If you still choose to use `-onlynet=onion`, be aware of the following:
273+
274+- **DNS incompatibility:** You must set `-dnsseed=0` and `-dns=0`. DNS
275+ resolution requires IPv4 or IPv6, so `-dnsseed=1` with `-onlynet=onion`
276+ will cause Bitcoin Core to exit with:
This seems like the main motivation for this PR, but the entire point of -onlynet=onion is that you don’t make a dns query on accident. The error message already tells you what to do. The other points you raise are also questionable to an extent.
NACK.
Closing as an LLM generated “AI agent” patch. Please note that contributors are required to fully understand their authored code themselves.
If you wish to contribute in the future, please focus on creating high-quality, original content that demonstrates a clear understanding of the project’s requirements and goals. Also, see the contributing guidelines.