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/30951.

Reviews

See the guideline for information on the review process.

If your review is incorrectly listed, please copy-paste <!--meta-tag:bot-skip--> into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #29418 (rpc: provide per message stats for global traffic via new RPC 'getnetmsgstats' by vasild)

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

LLM Linter (✨ experimental)

Possible typos and grammar issues:

• Peers can still connect to you, observers can identify Bitcoin activity from connection attempts on the default port (8333) or from analysing Bitcoin network traffic patterns. -> Peers can still connect to you. Observers can identify Bitcoin activity from connection attempts on the default port (8333) or from analysing Bitcoin network traffic patterns. [The original is a comma splice that should be two sentences (or use a semicolon) to be grammatically correct and clear.]

• IPV4/IPV6 -> IPv4/IPv6 [Standard capitalization is "IPv4"/"IPv6"; "IPV4"/"IPV6" is atypical and looks like a typographic error in documentation.]

Possible places where named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

• node0.addnode("15.61.23.23:1234", "onetry", True) in test/functional/p2p_v2_encrypted.py
• node0.addnode("8.8.8.8:1234", "onetry", False) in test/functional/p2p_v2_encrypted.py
• node0.addnode(addr, "onetry", False) in test/functional/p2p_v2_encrypted.py

^2025-12-12

In #29618 and here, I don't see the motivation to forbid v1 connections. In other words, what is the purpose of this?

In addition to the concerns expressed in #29618, there is one more - if V2-only is widespread, it may be hard to eclipse V2-only node, but then it becomes easy to eclipse a V1 node which has a problem of finding peers to connect to, so an attacker starts a lot of nodes that do accept V1 connections.

I see possible downsides and 0 benefit of a v2only option.

Concept ACK

In #29618 and here, I don't see the motivation to forbid v1 connections.

Well, to gain the benefits of BIP324. For example if you are concerned about someone inspecting the traffic to your node it really doesn't matter how many BIP324 peers you have if you have just one unencrypted connection. You could also run tor-only in this case, but that has its own disadvantages and -onlynet=onion shares the exact same downside that if everyone did it, the network would split. If some, but not all nodes who are running only on privacy networks would be willing to also have clearnet peers with this option, that would be a good thing in my opinion.

if V2-only is widespread

that would be a problem, but -onlynet, -blocksonly etc. have that exact same problem. I see this as an option you would only choose if you actually need it because you are concerned about unencrypted traffic.

You could also run tor-only in this case, but that has its own disadvantages and -onlynet=onion shares the exact same downside that if everyone did it, the network would split.

Our docs address this to an extent here and here. As those docs point out, -onlynet only affects outbound connections (not inbound and manual ones), and we suggest that it be used with multiple networks. My blog goes further into it here and here.

If some, but not all nodes who are running only on privacy networks would be willing to also have clearnet peers with this option, that would be a good thing in my opinion.

Agree. My node, for instance, runs over tor/i2p/cjdns and makes manual connections to trusted clearnet peers.

if V2-only is widespread, it may be hard to eclipse V2-only node, but then it becomes easy to eclipse a V1 node which has a problem of finding peers to connect to, so an attacker starts a lot of nodes that do accept V1 connections.

Agree. With this change, clearnet node operators may need to accept v2, whether they wish to or not. We generally try to avoid forcing users to do things. I suppose my concept ack on this would depend on that tradeoff.

For example if you are concerned about someone inspecting the traffic to your node it really doesn't matter how many BIP324 peers you have if you have just one unencrypted connection.

True. Lets dive a bit deeper - what are the reasons to be concerned about somebody inspecting the traffic to my node?

True. Lets dive a bit deeper - what are the reasons to be concerned about somebody inspecting the traffic to my node?

Some thoughts off the top my head:

• You don't want others (e.g. network admins, internet providers, etc.) to know that you are running a bitcoin node at all. Maybe it's not allowed in your network / country etc., maybe for other reasons such as personal security.
• Transaction privacy

In both of these cases, if you accept inbounds they could just connect to you as an alternative (but they would need to have a suspicion, whereas detection of bitcoin-related network data could be automated). So another alternative would be to only disallow v1 connections for outbound peers. In that case, if you don't want any v1 connections at all you'd have to run with -nolisten.

what are the reasons to be concerned about somebody inspecting the traffic to my node?

• You don't want others (e.g. network admins, internet providers, etc.) to know that you are running a bitcoin node at all. Maybe it's not allowed in your network / country etc., maybe for other reasons such as personal security.

This is what is worrying me - V2-only will not hide the fact that I am running a bitcoin node, but may give the false impression that it does. This is dangerous. My node will connect to publicly known bitcoin nodes and the mere fact that I have a TCP connection to an addr:port, where it is known that a bitcoin node is running, is already revealing enough. No need to inspect the traffic itself.

Another possible misunderstanding is that V2-only makes the traffic impossible to spy. I can imagine a blatant MITM, which is detectable because the session keys would differ, should somebody bother to check them. Once I detect this, whom am I going to complain to? My oppressive gov/ISP/whatever, same one that is doing the spying? Or the ISP can outright redirect my connections to addr:port to their spy node at spyaddr:port (I think I am talking to addr, but addr does not even have a connection from me). The point is that the traffic is spyable. Then, what is it so much that I want to keep away from spies? The data being transferred is all public, except if we are talking about me broadcasting my own transactions, there you go:

• Transaction privacy

V2-only may give the false impression that it breaks the link between transaction origin and IP address / geolocation. Even with unspyable p2p encryption, I may have a connection to a spy bitcoin node which then sees my traffic. Like you said "it really doesn't matter how many BIP324 peers you have if you have just one unencrypted connection" I think this is the same as "it does not matter even if all your connections are encrypted, if you have just one (encrypted) connection to a spy node".

@vasild V2 only doesn't protect against active attacks like the ones you've mentioned which require resources from the other party to run a node to spy the traffic.

V2 only protects against a cheaper attack vectors possible because of passive inspection of network traffic flowing through different medium. They don't need the other party to run a node to spy.

True. Lets dive a bit deeper - what are the reasons to be concerned about somebody inspecting the traffic to my node?

Some thoughts off the top my head:

• You don't want others (e.g. network admins, internet providers, etc.) to know that you are running a bitcoin node at all. Maybe it's not allowed in your network / country etc., maybe for other reasons such as personal security.
• Transaction privacy

Yes, for the same reason as wanting to encrypt network traffic in the first place and this just offers a stronger guarantee when running a node with v2 support that unencrypted clearnet bitcoin traffic is not being collected and sold by other parties. Deep packet inspection, keyword filtering are cheaper for ISPs/firewalls to pull off and v2 only would protect against this.

A V2-only option will:

• not hide the fact that one runs bitcoin node (that is true regardless of encryption) and
• not stop even moderately motivated actor from spying for transaction origin (either by opening a P2P connection to the target or bricking V2 encryption or outright redirecting connections to their node)

but it will give the false impression that it does those two things. Further, it will make it more difficult for old nodes to find peers to connect to.

Concept NACK because of that.

Concept ACK

This option seems useful for users that want to:

• prevent passive spying on their connections
• increase the cost of tampering with the data exchanged on their connections
• increase the cost of detecting that they run a bitcoin node

Currently 59.71% of network supports v2

Have you checked how diverse these ~60% of v2 supporting nodes are? An extreme example: if they are all on running on AWS then I don't think we should add the option at this time.

increase the cost of detecting that they run a bitcoin node

How? Given that the spy does not need to inspect the traffic at all:

My node will connect to publicly known bitcoin nodes and the mere fact that I have a TCP connection to an addr:port, where it is known that a bitcoin node is running, is already revealing enough.

@vasild That assumes the attacker has sufficient monitoring infrastructure in place to maintain an accurate list of Bitcoin P2P ip:ports. That's obviously not impossible, but it is a significantly larger effort than stateless packet inspection looking for the string "\xf9\xbe\xb4\xd9version\x00\x00\x00\x00\x00".

And yes, very little in BIP324 protects against an attacker deliberately targetting specific individuals - its goal is increasing costs for large-scale monitoring. From that perspective I agree there is a risk for a false sense of security when introducing options like these, but I think it's a stretch to say that that makes it pointless. I can very well imagine this makes it possible to run a node at all for some users.

However, as I pointed out in the linked issue, I am somewhat concerned about a potential future where it becomes harder for other/older software to connect to the network if large swaths move to be v2-only. Because of that, I wonder if it isn't better to make this only apply to outbound connections, and advise people who want more private operation to not listen for inbound connections.

However, as I pointed out in the linked issue, I am somewhat concerned about a potential future where it becomes harder for other/older software to connect to the network if large swaths move to be v2-only. Because of that, I wonder if it isn't better to make this only apply to outbound connections, and advise people who want more private operation to not listen for inbound connections.

Yes. I may be potentially concept/approach ack here if this proposal adopts the suggestion above / in #29618 (comment) or #29618 (comment). (Along with perhaps additional user documentation for node runners, maybe in the relevant config option helps and/or in /doc.)

A mutation testing report for this PR is available at: https://brunoerg.xyz/mutation-core-front

Concept ACK. I think deployment of v2-capable nodes is sufficient that it's reasonable to offer an outbound-v2-only option.

Concept ACK

A year later, adoption is now almost at ~70% according to https://21.ninja/reachable-nodes/node-service-share/ - could update the OP with that info.

Concept ACK. i was critical of this in the past, but i'm more convinced that it makes some sense now, and believe it outweighs the implementation/maintenance cost of such a feature.

I re-assessed this carefully.

It seems ok to me to have v2only with the following properties:

• Can only be enabled if not listening, like suggested above. Otherwise we have to either:
  • accept v1 incoming which defeats the purpose of this because then we will have cleartext connections or
  • deny v1 incoming (only allow v2 incoming) which is a problem if this is widely adopted because then old nodes that do not support v2 will have a hard time finding peers to connect to and will be subject to eclipse from an attacker who runs many v1-accepting nodes.

avoids easy detection that you're running a bitcoin node by stateless packet connection.

The node is still making outbound connections to addresses on the internet to port 8333!

• So it would be good to make it very obvious to the user that this option will not hide the fact that they are running a Bitcoin node.

• Also, it would be good to make it very obvious that this option only marginally if at all improves own transactions' privacy. Why? It improves it in the following case: if a node has only cleartext v1 connections, then their ISP can monitor all traffic that goes in and out of the node. So the ISP can know when the node sends their own transactions because it never received those transactions from others before sending them. Thus the node must be the originator. However, if there is at least one encrypted connection, then the ISP cannot know whether the transaction originated from the node or whether the node is just relaying a transaction it received over the encrypted connection. So this option helps to avoid the case of having only cleartext v1 connections with a passive spy that is only inspecting traffic. Then the option might be -avoid-having-all-connections-as-v1 If the spy ISP is willing to redirect outgoing connections to their spyish nodes, then v2only does not help.

From the issue that prompted this:

I asked for this because of a friend in a country where they are having issues, very real issues and they did not want to doxx themselves

I still think that this is misguided and can get people into "very real issues" if such an option gives the impression that it:

1. Hides the fact that you run a bitcoin node. It does not at all because you will still connect to others at port 8333, and that is the easiest way to detect bitcoin traffic, no need for spy nodes or inspecting the traffic contents.

2. Hides you as originator of your own transactions from your ISP. A little bit it does, but not much as commented in details above. I think that all-v2-connections is the same as at-least-one-v2-connection for concealing the transaction origin.

Anyway, if it is made clear that a v2only option does not achieve 1. or 2., then I guess it is fine. V2 adoption has increased and there are enough knowledgeable people commenting here, so with this post I would like to withdraw my "Concept NACK" and leave it in your capable hands.

Concept 0

Thank you all for the very helpful feedback on this! and sorry for getting late with the update.

I've pushed an update addressing all the review comments except @mzumsande's conceptual concern about whether
v2onlyclearnet should accept v2 inbounds as well so that the network doesn't face a shortage of listening capacity in the worst case scenario where a huge fraction of network turns it on.

Quick summary of the update:

• More description in help text to highlight that -v2onlyclearnet doesn't hide the fact that you're running a bitcoin node. (thanks @vasild!)
• -v2onlyclearnet, -listen arg interaction which errors if we use -v2onlyclearnet on a listening node (thanks @ajtowns!)
• naming consistency in functions/variables to use "v2 only" language instead of mixing it with potentially confusing "disable v1" language also. Ex: s/DisableV10nClearnet/RequiresV2ForOutbound (thanks @fjahr!)
• introduced DEFAULT_DISABLE_V1CONN_CLEARNET=false (thanks @laanwj!)

regarding #30951 (review):

I still don't find the reason for tying it to -listen=0 instead of also disallowing v1 inbounds compelling. Yes, if everyone disabled v1 incoming peers that could lead to v1 nodes being eclipsed. But with the suggested approach, if too many nodes just disabled incoming connections entirely to be able to use the option, that wouldn't be any better, because now every node would have trouble finding peers / risk being eclipsed.

I assumed people who didn't want network traffic to be spyed on are already people who didn't accept (possibly spy) connections from others (people running private nodes) and didn't think of the impact on the listening slots in the network. This doesn't necessarily need to be the case though. -v2onlyclearnet being used with listen=0 would also need -listenonion=0, so we'd also be turning off tor/i2p inbounds.

However this feels like lots of users setting listen=0 problem, and we're showing someone a reason for setting listen=0 + making that future slightly more probable. Will need to think more about this and curious about other people's thoughts on #30951 (review) as well.