Summary — Adopting Bitcoin, San Salvador, November 2022
We'll discuss why and how to easily use alternative peer-to-peer networks (I2P, CJDNS) with your Bitcoin Core node for improved network connectivity and robustness — and more good stuff.
What is I2P?
I2P (the Invisible Internet Project) is an anonymizing network, offering a simple layer that identity-sensitive applications can use to securely communicate. All data is wrapped with several layers of encryption, and the network is both distributed and dynamic, with no trusted parties. I2P uses garlic routing, bundling and encryption. See here for more about its threat model. A good blog post that describes I2P and how it compares to Tor is here.
I2P support was merged into Bitcoin Core v22 in PR 20685 and the documentation is here.
What is CJDNS?
is an IPv6 overlay network that uses public-key cryptography
for address allocation and a distributed hash table for routing.
It builds an end-to-end encrypted mesh network over the
fc00::/8 address space (reserved IPv6 range) with a
friend-of-a-friend network topology. It is like a distributed,
shared VPN with multiple entry points where every participant
can reach any other participant.
CJDNS support was merged into Bitcoin Core v23 in PR 23077 and the documentation is here.
I2P and CJDNS commonalities
Compared to IPv4/IPv6, both I2P and CJDNS provide end-to-end encryption and may help protect nodes from traffic analysis and filtering.
Used with Tor, the I2P and CJDNS networks are complementary, less-centralized options that can enhance network redundancy and robustness for both your node and the Bitcoin network.
Unlike Tor, I2P and CJDNS connections have a source address — you can be certain that the peer that connects to you from a given address possesses the private key corresponding to that address. This quality can be used to whitelist friend nodes. It is a stronger guarantee than IP addresses (which can be spoofed by your ISP, for instance).
Why use multiple Bitcoin peer-to-peer networks?
Using multiple networks provides potentially better decentralization, network robustness and censorship resistance, e.g. I2P or CJDNS may be operational when Tor is not or has degraded operation, while not degrading privacy or facilitating fingerprinting compared to running Tor alone.
Each network has different characteristics. For instance, Tor is widely used but centralized due to its hardcoded directory servers / consensus nodes that store the identity of nodes on the network, which can lead to problems (consensus node attacks, denial of service attacks, censorship, etc). At the time of this writing, various forms of DoS have been ongoing for nearly half a year now — see https://status.torproject.org/issues.
I2P can be fairly slow in latency (similar to Tor), and unlike
Tor, connections have a source address. However, starting with
24.0 containing the merge of
Bitcoin Core automatically generates a new transient
address for every outbound I2P peer connection when I2P
listening is turned off, i.e. when your node doesn't accept
inbound I2P connections by using the configuration option
-i2pacceptincoming=0. (Note that turning off
listening is neither the default behavior nor necessarily
CJDNS is generally quite fast but does not hide the sender and the recipient from intermediate routers; it was designed to be used with a friend-of-a-friend topology. It builds an overlay network which traverses NAT (Network Address Translation), exposing all ports of every node to every other node within the network. Those who are used to relying on NAT to protect their devices may find this troublesome.
Overall, it is good to have options and redundancy. I've found both I2P and CJDNS work very well for my nodes alongside Tor, and they generally are the first peer connections that I see on node startup.
A question that sometimes comes up is whether running your node over multiple networks means that it will gossip to all of the networks you have set up. The answer is (generally) yes, depending on your configuration. For example, most full nodes are configured to relay new transactions to all of their peers unless they’ve already received an advertisement about the transaction from that peer.
Considerations with running Tor only
There are security considerations with running a node only over
-onlynet=onion with no other onlynet
Sybil/Eclipse attacks: If you only make random Tor
connections, you're much more vulnerable to Sybil attacks. As
Tor addresses may be created at no cost, an attacker can
potentially flood the network with many Tor nodes and take all
of your node's outbound connection slots. If all of your
connections are controlled by a Sybil attacker, they can
prevent you from seeing confirmed transactions and, with more
difficulty, even trick your node into falsely reporting a
transaction as confirmed on the blockchain with the most
This can be alleviated by making manual
-addnodeconnections to trusted peers, as a connection to a single honest peer is enough to thwart an attempted eclipse attack. (It can also be alleviated with IPv4/IPv6 connections — particularly when using the
-asmapconfiguration option — due to the cost of obtaining IPs in many networks.)
Network Partitioning: If a sufficiently large proportion of
Tor nodes uses
-onlynet=onionwithout setting other onlynet options, it could become difficult for onion nodes to communicate with clearnet, I2P, and CJDNS nodes, preventing the Tor network from seeing recent transactions and blocks.
The same is even more true for nodes running only I2P or CJDNS. It is essential that some nodes access multiple networks, and with the currently small identity set of Bitcoin nodes that run I2P or CJDNS it is a good idea for a node to run these as one of several networks. Initial Block Download (IBD) will be much faster as well.
Bitcoin Core Listening Port
Historically, the network listening port on mainnet has been 8333; Bitcoin Core had a strong preference for only connecting to nodes on clearnet that listen on that port.
Since Bitcoin Core 23.0, that preference was removed with the merge of PR 23542, because connections over clearnet involving port 8333 make it easy to detect, analyze, block or divert Bitcoin P2P traffic before the connection is even established (at TCP SYN time). Your Bitcoin Core node may now use any port, so consider using a different one over clearnet, and/or running it behind a VPN to encrypt your node's traffic.
Running your Bitcoin Core node over I2P and CJDNS is surprisingly quick and easy. Here is the Bitcoin Core documentation for running your node with:
Install i2pd (I2P daemon) on the command line:
apt install i2pd && systemctl enable i2pd.service && systemctl start i2pd.service(Linux), or
brew install i2pd && brew services start i2pd(macOS)
Add these options to your
bitcoin.confconfiguration file (on Linux it is usually located in the
~/.bitcoin/directory, and on macOS in
debug=i2p(to turn on I2P logging in the debug log)
- Restart your node with Bitcoin Core version 22 and up.
- BIP 155 (addr v2) that was required for Tor v3, I2P and CJDNS support
Monitoring your Bitcoin Core node from the command line
I generally have the following 3 command line windows open:
- 1 window for the debug log
1 window with a live CLI -getinfo dashboard:
$ watch --no-title --interval 10 ./src/bitcoin-cli -rpcwait -getinfo
1 window with a live CLI -netinfo (network connections) dashboard:
$ watch --no-title --interval 4 ./src/bitcoin-cli -rpcwait -netinfo 4
Run the following for -netinfo help:
$ ./src/bitcoin-cli -netinfo help
To see the number of peers your node knows by network type:
$ ./src/bitcoin-cli -rpcwait -addrinfo
watchis built into Linux as the watch(1) command
watchcan be installed using brew, i.e.
$ brew install watch
--interval(in seconds) and
--no-titlearguments as you prefer
Credit to Vasil Dimov and Robert Spigler, as well as to the I2P and CJDNS online documentation and the Bitcoin Optech topics resource, for parts of the text above.
Thanks to Vasil Dimov for giving feedback on this article and for his amazing work over the years on these areas of Bitcoin Core.
Jon has been contributing to Bitcoin Core development since early 2019 with decentralization, censorship resistance, robustness, and privacy being his highest priorities. He helps onboard new contributors through mentoring and with his writing at https://jonatack.github.io/articles.