# I2P support in Bitcoin Core It is possible to run Bitcoin Core as an [I2P (Invisible Internet Project)](https://en.wikipedia.org/wiki/I2P) service and connect to such services. This [glossary](https://geti2p.net/en/about/glossary) may be useful to get started with I2P terminology. ## Run Bitcoin Core with an I2P router (proxy) A running I2P router (proxy) is required with the [SAM](https://geti2p.net/en/docs/api/samv3) application bridge enabled. The following routers are recommended for use with Bitcoin Core: - [i2prouter (I2P Router)](https://geti2p.net), the official implementation in Java. The SAM bridge is not enabled by default; it must be started manually, or configured to start automatically, in the Clients page in the router console (`http://127.0.0.1:7657/configclients`) or in the `clients.config` file. - [i2pd (I2P Daemon)](https://github.com/PurpleI2P/i2pd) ([documentation](https://i2pd.readthedocs.io/en/latest)), a lighter alternative in C++. It enables the SAM bridge by default. Note the IP address and port the SAM proxy is listening to; usually, it is `127.0.0.1:7656`. Once an I2P router with SAM enabled is up and running, use the following Bitcoin Core configuration options: ``` -i2psam= I2P SAM proxy to reach I2P peers and accept I2P connections (default: none) -i2pacceptincoming Whether to accept inbound I2P connections (default: 1). Ignored if -i2psam is not set. Listening for inbound I2P connections is done through the SAM proxy, not by binding to a local address and port. ``` In a typical situation, this suffices: ``` bitcoind -i2psam=127.0.0.1:7656 ``` ## Additional configuration options related to I2P ``` -debug=i2p ``` Set the `debug=i2p` config logging option to see additional information in the debug log about your I2P configuration and connections. Run `bitcoin-cli help logging` for more information. ``` -onlynet=i2p ``` Make automatic outbound connections only to I2P addresses. Inbound and manual connections are not affected by this option. It can be specified multiple times to allow multiple networks, e.g. onlynet=onion, onlynet=i2p. I2P support was added to Bitcoin Core in version 22.0 and there may be fewer I2P peers than Tor or IP ones. Therefore, using I2P alone without other networks may make a node more susceptible to [Sybil attacks](https://en.bitcoin.it/wiki/Weaknesses#Sybil_attack). You can use `bitcoin-cli -addrinfo` to see the number of I2P addresses known to your node. Another consideration with `onlynet=i2p` is that the initial blocks download phase when syncing up a new node can be very slow. This phase can be sped up by using other networks, for instance `onlynet=onion`, at the same time. In general, a node can be run with both onion and I2P hidden services (or any/all of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if one of the networks has issues. ## Persistent vs transient I2P addresses The first time Bitcoin Core connects to the I2P router, it automatically generates a persistent I2P address and its corresponding private key by default or if `-i2pacceptincoming=1` is set. The private key is saved in a file named `i2p_private_key` in the Bitcoin Core data directory. The persistent I2P address is used for making outbound connections and accepting inbound connections. In the I2P network, the receiver of an inbound connection sees the address of the initiator. This is unlike the Tor network, where the recipient does not know who is connecting to it. If your node is configured by setting `-i2pacceptincoming=0` to not accept inbound I2P connections, then it will use a random transient I2P address for itself on each outbound connection to make it harder to discriminate, fingerprint or analyze it based on its I2P address. I2P addresses are designed to be long-lived. Waiting for tunnels to be built for every peer connection adds delay to connection setup time. Therefore, I2P listening should only be turned off if really needed. ## Fetching I2P-related information from Bitcoin Core There are several ways to see your I2P address in Bitcoin Core if accepting incoming I2P connections (`-i2pacceptincoming`): - in the "Local addresses" output of CLI `-netinfo` - in the "localaddresses" output of RPC `getnetworkinfo` - in the debug log (grep for `AddLocal`; the I2P address ends in `.b32.i2p`) To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4` or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`). You can use the `getnodeaddresses` RPC to fetch a number of I2P peers known to your node; run `bitcoin-cli help getnodeaddresses` for details. ## Compatibility Bitcoin Core uses the [SAM v3.1](https://geti2p.net/en/docs/api/samv3) protocol to connect to the I2P network. Any I2P router that supports it can be used. ## Ports in I2P and Bitcoin Core One particularity of SAM v3.1 is that it does not support ports, unlike newer versions of SAM (v3.2 and up) that do support them and default the port numbers to 0. From the point of view of peers that use newer versions of SAM or other protocols that support ports, a SAM v3.1 peer is connecting to them on port 0, from source port 0. To allow future upgrades to newer versions of SAM, Bitcoin Core sets its listening port to 0 when listening for incoming I2P connections and advertises its own I2P address with port 0. Furthermore, it will not attempt to connect to I2P addresses with a non-zero port number because with SAM v3.1 the destination port (`TO_PORT`) is always set to 0 and is not in the control of Bitcoin Core. ## Bandwidth By default, your node shares bandwidth and transit tunnels with the I2P network in order to increase your anonymity with cover traffic, help the I2P router used by your node integrate optimally with the network, and give back to the network. It's important that the nodes of a popular application like Bitcoin contribute as much to the I2P network as they consume. It is possible, though strongly discouraged, to change your I2P router configuration to limit the amount of I2P traffic relayed by your node. With `i2pd`, this can be done by adjusting the `bandwidth`, `share` and `transittunnels` options in your `i2pd.conf` file. For example, to limit total I2P traffic to 256KB/s and share 50% of this limit for a maximum of 20 transit tunnels: ``` bandwidth = 256 share = 50 [limits] transittunnels = 20 ``` Similar bandwidth configuration options for the Java I2P router can be found in `http://127.0.0.1:7657/config` under the "Bandwidth" tab. Before doing this, please see the "Participating Traffic Considerations" section in [Embedding I2P in your Application](https://geti2p.net/en/docs/applications/embedding). In most cases, the default router settings should work fine. ## Bundling I2P in a Bitcoin application Please see the "General Guidance for Developers" section in https://geti2p.net/en/docs/api/samv3 if you are developing a downstream application that may be bundling I2P with Bitcoin.