private broadcast: clarify claims, mark as experimental #36309

instagibbs commented at 6:48 PM on September 21, 2026: member

Some of the claims were too strong, so I reframed these in terms of risk reduction, hopefully making user expectations more aligned with what's done
As a newer feature, it probably should have been marked experimental already, as the interface is likely to change in the future as it matures

DrahtBot added the label Private Broadcast on Sep 21, 2026

DrahtBot commented at 6:48 PM on September 21, 2026: contributor

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

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/36309.

Reviews

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

Type	Reviewers
ACK	andrewtoth, mzumsande, davidgumberg, optout21, vasild, sedited
Concept ACK	darosior
Stale ACK	l0rinc, w0xlt

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

instagibbs force-pushed on Sep 21, 2026

DrahtBot added the label CI failed on Sep 21, 2026

l0rinc commented at 6:58 PM on September 21, 2026: contributor

ACK b8aafb31f749d47e533802b79e7a8b86f143401b

Privacy is a spectrum, and we should expect to find new attack vectors. We should have marked the feature as experimental from the start, that would have avoided the confusion caused by the v2-to-v1 fallback issue.

in doc/release-notes-36309.md:2 in b8aafb31f7 outdated

   0 | @@ -0,0 +1,8 @@
   1 | +P2P and network changes
   2 | +-----------------------

sedited commented at 7:05 PM on September 21, 2026:

This is for a backport to 32.x, and we already opened the wiki for consolidating the release notes, so I don't think it makes sense to merge this with this note. However I would keep this here for now to make it easier to people to comment on, but remove it before it gets merged.

instagibbs force-pushed on Sep 21, 2026

DrahtBot removed the label CI failed on Sep 21, 2026

l0rinc commented at 9:29 PM on September 21, 2026: contributor

reACK b8aafb31f749d47e533802b79e7a8b86f143401b

darosior commented at 9:36 PM on September 21, 2026: member

Concept ACK on documenting and marking as experimental. The help texts look good to me.

andrewtoth commented at 11:45 PM on September 21, 2026: contributor

Concept ACK

in src/rpc/mempool.cpp:94 in 15976bda76

  92 | +        "\nIf -privatebroadcast is enabled, then the transaction will be sent via\n"
  93 |          "dedicated, short-lived connections to Tor or I2P peers or IPv4/IPv6 peers\n"
  94 | -        "via the Tor network. This conceals the transaction's origin. The transaction\n"
  95 | -        "will only enter the local mempool when it is received back from the network.\n"
  96 | +        "via the Tor network. This provides best-effort privacy: your IP address may\n"
  97 | +        "still be exposed, and transactions may still be linked to each other or to your node.\n"

vasild commented at 1:53 PM on September 22, 2026:

All looks good except this repeated

your IP address may still be exposed, and transactions may still be linked to each other or to your node

It makes it sound as if this is by design. What about:

This provides best-effort privacy to conceal the transaction's origin. Bugs may cause your IP address to be exposed, and transactions to be linked to each other or to your node.

instagibbs commented at 2:02 PM on September 22, 2026:

I think a design document is helpful to elaborate on what we're promising technically, but for user-facing docs underpromising and overdelivering should be our goal imo.

It might not even be our bugs, but timing analysis, bugs in Tor/i2p, etc.

Keeping as is for now

andrewtoth commented at 2:43 PM on September 22, 2026:

I don't think we need a design document to tell us that the goal is to conceal the transaction's origin. I think the wording here makes it ambiguous about what the goal is. If it fails to do the stated goal that is a bug, in our code or otherwise. The "best-effort" phrasing makes that clear IMO. I don't think we need to remove the description of the goal that we are making a best-effort to achieve. That will only confuse users about the purpose of this feature.

yancyribbens commented at 4:11 PM on September 22, 2026:

I agree that saying your IP may be leaked seems overkill. It seems enough to just say that this is tunneling over tor and not make any claims or assertions beyond that.

If -privatebroadcast is enabled, then the transaction will be sent via dedicated, short-lived connections to Tor or I2P peers or IPv4/IPv6 peers via the Tor network to provides best-effort privacy.

Note that private broadcast is experimental and may change in future releases. Submission does not itself add the transaction to the local mempool; normal mempool acceptance and relay apply when it is received back from the network. The private broadcast queue is bounded: when it is full, this RPC fails and the transaction is not scheduled, until an existing one completes or is aborted. Use getprivatebroadcastinfo to inspect the queue and abortprivatebroadcast to abort.

instagibbs commented at 4:40 PM on September 22, 2026:

letting "best effort" do more heavy lifting

doc: scope claims about private broadcast feature

Reframe in terms of risk reduction rather than absolutes

2630d8e6c9

private broadcast: mark feature as experimental f413729983

instagibbs force-pushed on Sep 22, 2026

l0rinc commented at 5:05 PM on September 22, 2026: contributor

reACK 7ffe9b7846904858ab5055bf117b36e342fad9fd

DrahtBot requested review from andrewtoth on Sep 22, 2026

DrahtBot requested review from darosior on Sep 22, 2026

w0xlt commented at 5:22 PM on September 22, 2026: contributor

ACK 7ffe9b7846904858ab5055bf117b36e342fad9fd

andrewtoth approved

andrewtoth commented at 6:05 PM on September 22, 2026: contributor

ACK f41372998377ab8310476f0c03294e69cc3222e8

Not marking the feature as experimental and using absolute language about the privacy benefits was an oversight. It is good that we are correcting it now.

I also approve of the release notes language, but I ACK'd the second commit since I believe we want to drop that one before merging.

DrahtBot requested review from andrewtoth on Sep 22, 2026

mzumsande commented at 6:20 PM on September 22, 2026: contributor

ACK f41372998377ab8310476f0c03294e69cc3222e8

DrahtBot requested review from mzumsande on Sep 22, 2026

davidgumberg commented at 11:11 PM on September 22, 2026: contributor

ACK https://github.com/bitcoin/bitcoin/commit/f41372998377ab8310476f0c03294e69cc3222e8

DrahtBot requested review from davidgumberg on Sep 22, 2026

in doc/release-notes-36309.md:5 in 7ffe9b7846

   0 | @@ -0,0 +1,7 @@
   1 | +P2P and network changes
   2 | +-----------------------
   3 | +
   4 | +- The `-privatebroadcast` feature is now marked experimental and may change in future
   5 | +  releases. It provides best-effort privacy for concealing transaction origin. The 31.0

optout21 commented at 6:35 AM on September 23, 2026:

7ffe9b7 doc: add release note for private broadcast update:

"It provides best-effort privacy for concealing transaction origin." This sentence sounds awkward and unclear to me.

Suggestion(s): "It improves transaction sender privacy by best-effort concealment of the originator node."

Other options: "It provides best-effort privacy for submitted transactions by concealing their origin." "It provides best-effort transaction privacy by concealing the origin." "It provides best-effort privacy by concealing transaction origin."

in doc/release-notes-36309.md:6 in 7ffe9b7846

   0 | @@ -0,0 +1,7 @@
   1 | +P2P and network changes
   2 | +-----------------------
   3 | +
   4 | +- The `-privatebroadcast` feature is now marked experimental and may change in future
   5 | +  releases. It provides best-effort privacy for concealing transaction origin. The 31.0
   6 | +  release notes overstated these privacy guarantees. This documentation correction

optout21 commented at 6:50 AM on September 23, 2026:

7ffe9b7 doc: add release note for private broadcast update:

"The 31.0 release notes overstated these privacy guarantees." Factually true, and I agree, though I find the formulation a bit harsh. I would prefer something like "Previous release notes (31.0) included some overly bold statements on the privacy guarantees."

Even better would be to make it more specific, and state the overstated claim. "Previous release notes (31.0) stated that the originator IP address will be never known -- while this is one of the main goals of private broadcast, this feature alone cannot fully guarantee it."

instagibbs commented at 1:22 PM on September 23, 2026:

I also think the other claims of unlinkability are too strong. It's better to be less specific and more cautious.

sedited commented at 1:30 PM on September 23, 2026:

I tend to agree with with optout, buts lets hammer that out on the release notes wiki and get the rest of the changes merged in the meantime.

optout21 commented at 6:53 AM on September 23, 2026: contributor

ACK f41372998377ab8310476f0c03294e69cc3222e8

I agree. For the release note, I also agree conceptually, but I have some comments regarding wording. I ack the 2nd commit, but happy to re-ack as fit.

DrahtBot requested review from optout21 on Sep 23, 2026

vasild approved

vasild commented at 8:15 AM on September 23, 2026: contributor

ACK f41372998377ab8310476f0c03294e69cc3222e8

The ACK is on the second commit. I guess the 3rd one will be dropped.

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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

ACK f41372998377ab8310476f0c03294e69cc3222e8

The ACK is on the second commit. I guess the 3rd one [will be dropped](https://github.com/bitcoin/bitcoin/pull/36309#discussion_r4065457880).
-----BEGIN PGP SIGNATURE-----

iQRPBAEBCAA5FiEE5k2NRWFNsHVF2czBVN8G9ktVy78FAmqzinYbFIAAAAAABAAO
bWFudTIsMi41KzEuMTIsMiwzAAoJEFTfBvZLVcu/QQIgAKj6FuCiY4jznVV7Qnpu
2btGuQOtTPorPdwfXsFZ1VRmtAgIP4QcmkUslY+ts0I2mPuM7+Hi4hera9pcFl5k
+7uQ1MIqxclg33DhXlZblaR7MAaT5eQwG0g08DCSlmN9KGUyX8rhXm0tDpA6KkDm
QRRqK0sofPNVdvh8glclOGeWT3Sl3l26zPtlS2YfpJ/kK2axpDYAq2cBDtR5qIsl
dnkdjicnTs/vanKja+KJw+Wrw8YZ8h9JluIzYmg//98gc+WaojS4o/E9mAEKeQ6m
MAykJiuRvyPpG9CzFU+w/SURSC27rhXht5PpnOSMDzZOxPeI/Q9eQptB4YVHICRf
3ds0Nx3tSlIRLr2WM6gGIuLz0w2Oq6VNCOIzQQEi6zN2g7J3wqMvLD/fCbroM7U6
HPiBE4XgBW0BBcwhGkIrOkrj5iOgXfiyo0luzJAo6zq0E8W38svooxPxU42WbnOr
vGx656rWDKQUlI7T33wl1XuNOhwBguG8Wm+eKaL1hkI70ocUPr8BmjlIGCR/VdKL
/mx4n6Zf6JhCKypcC8lKH5UqvwhFtrN7q8zB9L6Gx5ouKQZ3SP66IYhMYrzRrCtw
P8I5GtXFlX9yk/3tsZrcJdwprUD+pQMSF0noOJXCdzzEx1cwBvaKs2PhE/uKxkBL
clg4OSxeTIePyhkNz9EdpjtjOmXglq0uIFLIG6mm0VtTqGRhd471CpRV0d/8zShm
vpRl4dOIoS6xafzM2L+hICR6sOjP0dllRPMBl0AI57oJT4fxDwb1ElQXJ4tjCo+d
A2q2Sd8BY48TLz4quqUJcds6uqDAIMRg7zGJAZnASmoY3ZogcTtyZ6I+I0X67Dz5
EZmcV5gKT84MpFAItNxEqgoeD4P4zD0r+zQLciTLQHtggdePG62nkyqyn53u6ck2
Xt7C6O6POnKxXKLHskX0sr5Zw6BDFKH12bpF8IXgqUaE6WcSZ5NP1l+bBY4Epa6p
73qM6CeIGRiEDpd5PBkVwRf5G2LvysnvQKrjqOjySMmmodKRDQeQ0gzSI0KEyZtM
DDhZFXyMPi85zqDdsMX7+PKPWN1T5eNHgeVQE0z18YmPZSUFN5zGprODiSXlYNVp
0N2vS0Cmt2jDmZSIZcsGvJJDYig2ZFCxnTfNwkC8Mo36h1HSH765Un3NOBDqBUEz
UhRmUlnzugKN0kJovbOCRNUBH0nUoJSHyKBGLZcO4uAWkDXOSAgBpdfgAL4DJe64
PtgJpTcQpoTP4hbG+R/7coFIs0MmKJ9SxbW3hFeUBKYencvW7vhCgCRhDzDLbia5
bWTcAT2UCa0UuiXhbygIP1aV3ZKOrUXUNkatxCLRZ7BWzr3pCak4qZLgsxb8sIhP
Las=
=x9o6
-----END PGP SIGNATURE-----

vasild's public key is on openpgp.org

</details>

DrahtBot requested review from vasild on Sep 23, 2026

instagibbs force-pushed on Sep 23, 2026

DrahtBot requested review from w0xlt on Sep 23, 2026

DrahtBot requested review from l0rinc on Sep 23, 2026

sedited added the label Needs Backport (31.x) on Sep 23, 2026

sedited added the label Needs Backport (32.x) on Sep 23, 2026

sedited approved

sedited commented at 2:31 PM on September 23, 2026: contributor

ACK f41372998377ab8310476f0c03294e69cc3222e8

sedited merged this on Sep 23, 2026

sedited closed this on Sep 23, 2026

fanquake removed the label Needs Backport (32.x) on Sep 23, 2026

fanquake commented at 4:04 PM on September 23, 2026: member

Backported to 32.x in #36300.

fanquake referenced this in commit bfc87b96ef on Sep 23, 2026

fanquake referenced this in commit fa11293ddc on Sep 23, 2026

fanquake removed the label Needs Backport (31.x) on Sep 23, 2026

fanquake commented at 4:14 PM on September 23, 2026: member

Backported to 31.x in #36319.