doc: Add privacy.md consolidating network privacy recommendations #35858

pablomartin4btc commented at 3:49 AM on August 1, 2026: member

Creates doc/privacy.md as a single home for Bitcoin Core's privacy tools for transaction broadcasting and network connectivity.

Commit 1: Move the "Privacy recommendations" sections from doc/tor.md and doc/i2p.md into privacy.md, replacing them with pointers. The two files contained the same multi-network unlinkability warning duplicated verbatim; this consolidation removes the duplication. No content changes.
Commit 2: Add a "Transaction broadcasting privacy" section documenting -privatebroadcast, its prerequisites (Tor or I2P), current scope (sendrawtransaction only, with a link to the tracking issue for planned wallet-level support), and the related RPCs (getprivatebroadcastinfo, abortprivatebroadcast).

doc: Extract network privacy recommendations into doc/privacy.md

Move the "Privacy recommendations" sections from doc/tor.md and
doc/i2p.md into a new doc/privacy.md, replacing them with pointers.
The two files contained overlapping advice (the multi-network
unlinkability warning was duplicated verbatim); consolidating them
removes the duplication and gives privacy guidance a single home.

No behaviour changes; this is a pure documentation refactor.

886189e83d

doc: Document -privatebroadcast option in doc/privacy.md

Add a "Transaction broadcasting privacy" section explaining how
-privatebroadcast works, its prerequisites (Tor or I2P), current scope
(sendrawtransaction only, with a link to the tracking issue for
planned wallet-level support), and the two related RPCs
(getprivatebroadcastinfo, abortprivatebroadcast).

Update the pointers in doc/tor.md and doc/i2p.md to mention private
transaction broadcasting.

1b07681dfe

DrahtBot added the label Docs on Aug 1, 2026

DrahtBot commented at 3:49 AM on August 1, 2026: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

External sites

Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/35858
Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/35858.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/35858#author-ralph

Reviews

See the guideline and AI policy for information on the review process.

Type	Reviewers
ACK	vasild
Concept ACK	jonatack

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.

Conflicts

No conflicts as of last run.

pablomartin4btc renamed this:
~~doc: Add privacy.md consolidating network privacy recommendations and documenting -privatebroadcast~~
doc: Add privacy.md consolidating network privacy recommendations
on Aug 1, 2026

pablomartin4btc commented at 9:11 PM on August 28, 2026: member

Gently pinging @ismaelsadeeq and @vasild — this follows up on the new privacy.md consolidation suggested during review of #29415, and covers the -privatebroadcast feature from that PR. Happy to adjust scope or wording based on your feedback.

in doc/privacy.md:56 in 1b07681dfe

  51 | +this configuration (i.e. bridge nodes) increase the cost and complexity of
  52 | +launching eclipse and partition attacks. However, under certain conditions, an
  53 | +adversary that can connect to your node on multiple networks may be able to
  54 | +correlate those identities by observing shared runtime characteristics. It is
  55 | +not recommended to expose your node over multiple networks if you require
  56 | +unlinkability across those identities.

jonatack commented at 9:38 PM on August 28, 2026:

under certain conditions...may be able to correlate those identities

IIRC this came from a study of nodes running over both IPv4 and Tor. As I pointed out in the PR that added this note, people running their node over Tor are probably much more likely to use I2P as a second network than clearnet (I can go into why if needed). However, that review and other suggestions from me were ignored.

It would thus be more helpful to describe (a) what those "certain conditions" are, and (b) clarify the more frequently used case of Tor + I2P

As-is, (and it isn't your fault), I think this note is incomplete (and perhaps misleading).

pablomartin4btc commented at 3:07 AM on August 29, 2026:

Ok, I see that the thread you are referring to is this one. I agree that we could expand a bit on those circumstances and the risks that would be involved. I'll investigate a bit and see if I can come up with something else to add that I hope could help. Thanks!

jonatack commented at 9:38 PM on August 28, 2026: member

Concept ACK

sedited requested review from andrewtoth on Oct 13, 2026

sedited requested review from vasild on Oct 13, 2026

pablomartin4btc marked this as a draft on Oct 29, 2026

pablomartin4btc commented at 6:24 PM on October 29, 2026: member

Drafted due to a new approach defined in #36608, perhaps would be better to close this.

in doc/privacy.md:6 in 1b07681dfe

   0 | @@ -0,0 +1,72 @@
   1 | +# Privacy in Bitcoin Core
   2 | +
   3 | +## Transaction broadcasting privacy
   4 | +
   5 | +By default, when Bitcoin Core submits a transaction to the network it announces
   6 | +it to all connected peers. This allows any peer to correlate the transaction

vasild commented at 1:26 PM on November 4, 2026:

It is not "any" peer. That is, a single node being a recipient just sees an incoming transaction and they cannot tell if this is the originator or somebody relaying it. Maybe reword to something like:

This allows ~any peer~ an actor with many connections to many nodes to correlate...

in doc/privacy.md:15 in 1b07681dfe

  10 | +
  11 | +Transactions submitted via the `sendrawtransaction` RPC can be broadcast
  12 | +privately through a short-lived Tor or I2P connection, without putting them
  13 | +in the local mempool first. The transaction reaches the wider network only
  14 | +once a recipient relays it, which prevents linking the submission to the
  15 | +node's IP address.

vasild commented at 1:33 PM on November 4, 2026:

node's identify.

Even if a node runs only on Tor+I2P and thus has concealed their IP address, it still has some identity which is protected by -privatebroadcast.

in doc/privacy.md:34 in 1b07681dfe

  29 | +
  30 | +**Scope:** Only `sendrawtransaction` is affected. Wallet RPCs (`sendtoaddress`,
  31 | +`send`, `sendmany`, `sendall`, etc.) broadcast transactions through the standard method
  32 | +regardless of this setting. Wallet-level private broadcast is not yet supported;
  33 | +see the [private broadcast tracking issue](https://github.com/bitcoin/bitcoin/issues/34476)
  34 | +for planned extensions.

vasild commented at 1:35 PM on November 4, 2026:

regardless of this setting. Wallet-level private broadcast is not yet supported.

I closed the issue: #34476 (comment)

vasild approved

vasild commented at 1:39 PM on November 4, 2026: contributor

ACK 1b07681dfebffe4e31dd92042c5ba8493a5cf9b7

<details> <summary>Show Signature</summary>

vasild's public key is on openpgp.org

</details>

DrahtBot requested review from jonatack on Nov 4, 2026

in doc/privacy.md:13 in 1b07681dfe

   8 | +
   9 | +### Private broadcast (`-privatebroadcast`)
  10 | +
  11 | +Transactions submitted via the `sendrawtransaction` RPC can be broadcast
  12 | +privately through a short-lived Tor or I2P connection, without putting them
  13 | +in the local mempool first. The transaction reaches the wider network only

instagibbs commented at 6:14 PM on November 4, 2026:

The core of the claim is that our node is meant to act the same as any other, that we will not tell our peers about the tx until we hear about it over p2p. We don't know if it reaches the "wider network", as the recipient may be an adversary. We just don't want our node to act differently than any other node.