1# I2P support in Bitcoin Core
2
3It is possible to run Bitcoin Core as an
4[I2P (Invisible Internet Project)](https://en.wikipedia.org/wiki/I2P)
5service and connect to such services.
6
7This [glossary](https://i2p.net/en/docs/overview/glossary) may be useful to get
8started with I2P terminology.
9
10## Run Bitcoin Core with an I2P router (proxy)
11
12A running I2P router (proxy) is required with the [SAM](https://i2p.net/en/docs/api/samv3)
13application bridge enabled. The following routers are recommended for use with Bitcoin Core:
14
15- [i2prouter (I2P Router)](https://i2p.net), the official implementation in
16  Java. The SAM bridge is not enabled by default; it must be started manually,
17  or configured to start automatically, in the Clients page in the
18  router console (`http://127.0.0.1:7657/configclients`) or in the `clients.config` file.
19- [i2pd (I2P Daemon)](https://github.com/PurpleI2P/i2pd)
20  ([documentation](https://docs.i2pd.website/en/latest)), a lighter
21  alternative in C++. It enables the SAM bridge by default.
22
23Note the IP address and port the SAM proxy is listening to; usually, it is
24`127.0.0.1:7656`.
25
26Once an I2P router with SAM enabled is up and running, use the following Bitcoin
27Core configuration options:
28
29```
30-i2psam=<ip:port>
31     I2P SAM proxy to reach I2P peers and accept I2P connections (default:
32     none)
33
34-i2pacceptincoming
35     Whether to accept inbound I2P connections (default: 1). Ignored if
36     -i2psam is not set. Listening for inbound I2P connections is
37     done through the SAM proxy, not by binding to a local address and
38     port.
39```
40
41In a typical situation, this suffices:
42
43```
44bitcoind -i2psam=127.0.0.1:7656
45```
46
47## Additional configuration options related to I2P
48
49```
50-debug=i2p
51```
52
53Set the `debug=i2p` config logging option to see additional information in the
54debug log about your I2P configuration and connections. Run `bitcoin-cli help
55logging` for more information.
56
57```
58-onlynet=i2p
59```
60
61Make automatic outbound connections only to I2P addresses. Inbound and manual
62connections are not affected by this option. It can be specified multiple times
63to allow multiple networks, e.g. onlynet=onion, onlynet=i2p.
64
65I2P support was added to Bitcoin Core in version 22.0 and there may be fewer I2P
66peers than Tor or IP ones. Therefore, using I2P alone without other networks may
67make a node more susceptible to [Sybil
68attacks](https://en.bitcoin.it/wiki/Weaknesses#Sybil_attack). You can use
69`bitcoin-cli -addrinfo` to see the number of I2P addresses known to your node.
70
71Another consideration with `onlynet=i2p` is that the initial blocks download
72phase when syncing up a new node can be very slow. This phase can be sped up by
73using other networks, for instance `onlynet=onion`, at the same time.
74
75In general, a node can be run with both onion and I2P hidden services (or
76any/all of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if
77one of the networks has issues.
78
79## Persistent vs transient I2P addresses
80
81The first time Bitcoin Core connects to the I2P router, it automatically
82generates a persistent I2P address and its corresponding private key by default,
83unless `-i2pacceptincoming=0` is set.  The private key is saved in a file named
84`i2p_private_key` in the Bitcoin Core data directory.  The persistent I2P
85address is used for making outbound connections and accepting inbound
86connections.
87
88In the I2P network, the receiver of an inbound connection sees the address of
89the initiator. This is unlike the Tor network, where the recipient does not
90know who is connecting to it.
91
92If your node is configured by setting `-i2pacceptincoming=0` to not accept
93inbound I2P connections, then it will use a random transient I2P address for
94itself on each outbound connection to make it harder to discriminate,
95fingerprint or analyze it based on its I2P address.
96
97I2P addresses are designed to be long-lived.  Waiting for tunnels to be built
98for every peer connection adds delay to connection setup time.  Therefore, I2P
99listening should only be turned off if really needed.
100
101## Fetching I2P-related information from Bitcoin Core
102
103There are several ways to see your I2P address in Bitcoin Core if accepting
104incoming I2P connections (`-i2pacceptincoming`):
105- in the "Local addresses" output of CLI `-netinfo`
106- in the "localaddresses" output of RPC `getnetworkinfo`
107- in the debug log (grep for `AddLocal`; the I2P address ends in `.b32.i2p`)
108
109To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4`
110or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`).
111
112You can use the `getnodeaddresses` RPC to fetch a number of I2P peers known to your node; run `bitcoin-cli help getnodeaddresses` for details.
113
114## Compatibility
115
116Bitcoin Core uses the [SAM v3.1](https://i2p.net/en/docs/api/samv3) protocol
117to connect to the I2P network. Any I2P router that supports it can be used.
118
119## Ports in I2P and Bitcoin Core
120
121One particularity of SAM v3.1 is that it does not support ports,
122unlike newer versions of SAM (v3.2 and up) that do support them and default the
123port numbers to 0. From the point of view of peers that use newer versions of
124SAM or other protocols that support ports, a SAM v3.1 peer is connecting to them
125on port 0, from source port 0.
126
127To allow future upgrades to newer versions of SAM, Bitcoin Core sets its
128listening port to 0 when listening for incoming I2P connections and advertises
129its own I2P address with port 0. Furthermore, it will not attempt to connect to
130I2P addresses with a non-zero port number because with SAM v3.1 the destination
131port (`TO_PORT`) is always set to 0 and is not in the control of Bitcoin Core.
132
133## Bandwidth
134
135By default, your node shares bandwidth and transit tunnels with the I2P network
136in order to increase your anonymity with cover traffic, help the I2P router used
137by your node integrate optimally with the network, and give back to the network.
138It's important that the nodes of a popular application like Bitcoin contribute
139as much to the I2P network as they consume.
140
141It is possible, though strongly discouraged, to change your I2P router
142configuration to limit the amount of I2P traffic relayed by your node.
143
144With `i2pd`, this can be done by adjusting the `bandwidth`, `share` and
145`transittunnels` options in your `i2pd.conf` file. For example, to limit total
146I2P traffic to 256KB/s and share 50% of this limit for a maximum of 20 transit
147tunnels:
148
149```
150bandwidth = 256
151share = 50
152
153[limits]
154transittunnels = 20
155```
156
157Similar bandwidth configuration options for the Java I2P router can be found in
158`http://127.0.0.1:7657/config` under the "Bandwidth" tab.
159
160Before doing this, please see the "Participating Traffic Considerations" section
161in [Embedding I2P in your Application](https://i2p.net/en/docs/applications/embedding).
162
163In most cases, the default router settings should work fine.
164
165## Bundling I2P in a Bitcoin application
166
167Please see the "General Guidance for Developers" section in https://i2p.net/en/docs/api/samv3
168if you are developing a downstream application that may be bundling I2P with Bitcoin.
169
170## Privacy recommendations
171
172- Operating a node that listens on multiple networks (e.g. IPv4 and I2P) can help
173  strengthen the Bitcoin network, as nodes in this configuration (i.e. bridge nodes) increase
174  the cost and complexity of launching eclipse and partition attacks. However, under certain
175  conditions, an adversary that can connect to your node on multiple networks may be
176  able to correlate those identities by observing shared runtime characteristics. It
177  is not recommended to expose your node over multiple networks if you require
178  unlinkability across those identities.
179