Last updated: 21 August 2023
Using Alternative P2P Networks with your Bitcoin Core Node (and more)

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. Two good blog posts that describe I2P and how it compares to Tor are:

I2P support was merged into Bitcoin Core v22 in PR 20685 and the documentation is here.

What is CJDNS?

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 PR 25355, 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 recommended.)

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 Tor, i.e. -onlynet=onion with no other onlynet options set.

  • 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 cumulative chainwork.

    This can be alleviated by making manual connections to trusted peers using the addnode configuration option or RPC, 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 -asmap configuration option — due to the cost of obtaining IPs in many networks.)

  • Network Partitioning: If a sufficiently large proportion of Tor nodes uses -onlynet=onion without 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.


Getting Started

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:

In many cases, getting started with I2P could be as quick as:
  • 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.conf configuration file (on Linux it is usually located in the ~/.bitcoin/ directory, and on macOS in ~/Library/Application\ Support/Bitcoin):
    i2psam=127.0.0.1:7656
    debug=i2p (to turn on I2P logging in the debug log)
  • Restart your node with Bitcoin Core version 22 and up.

To bootstrap your node's peer connections, if you need peers running I2P, CJDNS or Tor to manually connect to (using the addnode configuration option or RPC), you can find some in the Bitcoin Core source code file contrib/seeds/nodes_main_manual.txt.

There aren't many Bitcoin nodes running CJDNS yet, so here are some CJDNS peers you can manually connect your node to:

  • fc32:17ea:e415:c3bf:9808:149d:b5a2:c9aa
  • fcc7:be49:ccd1:dc91:3125:f0da:457d:8ce
  • fc70:704d:b268:cdbf:d622:ea9f:db12:859e

Further reading:

  • BIP 155 (addr v2) that was required for Tor v3, I2P and CJDNS support


Troubleshooting your I2P service

Some steps to try if your node isn't seeing I2P peer connections, or if the debug log is showing connection errors (please also refer to the I2P documentation in Bitcoin Core):

  • Restart your I2P router
  • Upgrade your I2P router regularly to the latest version; this can mitigate some connection issues
  • Verify the settings in your bitcoin.conf file and in your I2P router's configuration file
  • Consider changing your router to i2pd (docs) or to i2prouter


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

Info about the watch command:
  • watch is built into Linux as the watch(1) command
  • with macOS, watch can be installed using brew, i.e. $ brew install watch
  • adjust the --interval (in seconds) and --no-title arguments 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.