i2p.md
1 # I2P support in Bitcoin Core 2 3 It is possible to run Bitcoin Core as an 4 [I2P (Invisible Internet Project)](https://en.wikipedia.org/wiki/I2P) 5 service and connect to such services. 6 7 This [glossary](https://geti2p.net/en/about/glossary) may be useful to get 8 started with I2P terminology. 9 10 ## Run Bitcoin Core with an I2P router (proxy) 11 12 A running I2P router (proxy) is required with the [SAM](https://geti2p.net/en/docs/api/samv3) 13 application bridge enabled. The following routers are recommended for use with Bitcoin Core: 14 15 - [i2prouter (I2P Router)](https://geti2p.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://i2pd.readthedocs.io/en/latest)), a lighter 21 alternative in C++. It enables the SAM bridge by default. 22 23 Note the IP address and port the SAM proxy is listening to; usually, it is 24 `127.0.0.1:7656`. 25 26 Once an I2P router with SAM enabled is up and running, use the following Bitcoin 27 Core 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 41 In a typical situation, this suffices: 42 43 ``` 44 bitcoind -i2psam=127.0.0.1:7656 45 ``` 46 47 ## Additional configuration options related to I2P 48 49 ``` 50 -debug=i2p 51 ``` 52 53 Set the `debug=i2p` config logging option to see additional information in the 54 debug log about your I2P configuration and connections. Run `bitcoin-cli help 55 logging` for more information. 56 57 ``` 58 -onlynet=i2p 59 ``` 60 61 Make automatic outbound connections only to I2P addresses. Inbound and manual 62 connections are not affected by this option. It can be specified multiple times 63 to allow multiple networks, e.g. onlynet=onion, onlynet=i2p. 64 65 I2P support was added to Bitcoin Core in version 22.0 and there may be fewer I2P 66 peers than Tor or IP ones. Therefore, using I2P alone without other networks may 67 make a node more susceptible to [Sybil 68 attacks](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 71 Another consideration with `onlynet=i2p` is that the initial blocks download 72 phase when syncing up a new node can be very slow. This phase can be sped up by 73 using other networks, for instance `onlynet=onion`, at the same time. 74 75 In general, a node can be run with both onion and I2P hidden services (or 76 any/all of IPv4/IPv6/onion/I2P/CJDNS), which can provide a potential fallback if 77 one of the networks has issues. 78 79 ## Persistent vs transient I2P addresses 80 81 The first time Bitcoin Core connects to the I2P router, it automatically 82 generates a persistent I2P address and its corresponding private key by default, 83 unless `-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 85 address is used for making outbound connections and accepting inbound 86 connections. 87 88 In the I2P network, the receiver of an inbound connection sees the address of 89 the initiator. This is unlike the Tor network, where the recipient does not 90 know who is connecting to it. 91 92 If your node is configured by setting `-i2pacceptincoming=0` to not accept 93 inbound I2P connections, then it will use a random transient I2P address for 94 itself on each outbound connection to make it harder to discriminate, 95 fingerprint or analyze it based on its I2P address. 96 97 I2P addresses are designed to be long-lived. Waiting for tunnels to be built 98 for every peer connection adds delay to connection setup time. Therefore, I2P 99 listening should only be turned off if really needed. 100 101 ## Fetching I2P-related information from Bitcoin Core 102 103 There are several ways to see your I2P address in Bitcoin Core if accepting 104 incoming 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 109 To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4` 110 or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`). 111 112 You 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 116 Bitcoin Core uses the [SAM v3.1](https://geti2p.net/en/docs/api/samv3) protocol 117 to connect to the I2P network. Any I2P router that supports it can be used. 118 119 ## Ports in I2P and Bitcoin Core 120 121 One particularity of SAM v3.1 is that it does not support ports, 122 unlike newer versions of SAM (v3.2 and up) that do support them and default the 123 port numbers to 0. From the point of view of peers that use newer versions of 124 SAM or other protocols that support ports, a SAM v3.1 peer is connecting to them 125 on port 0, from source port 0. 126 127 To allow future upgrades to newer versions of SAM, Bitcoin Core sets its 128 listening port to 0 when listening for incoming I2P connections and advertises 129 its own I2P address with port 0. Furthermore, it will not attempt to connect to 130 I2P addresses with a non-zero port number because with SAM v3.1 the destination 131 port (`TO_PORT`) is always set to 0 and is not in the control of Bitcoin Core. 132 133 ## Bandwidth 134 135 By default, your node shares bandwidth and transit tunnels with the I2P network 136 in order to increase your anonymity with cover traffic, help the I2P router used 137 by your node integrate optimally with the network, and give back to the network. 138 It's important that the nodes of a popular application like Bitcoin contribute 139 as much to the I2P network as they consume. 140 141 It is possible, though strongly discouraged, to change your I2P router 142 configuration to limit the amount of I2P traffic relayed by your node. 143 144 With `i2pd`, this can be done by adjusting the `bandwidth`, `share` and 145 `transittunnels` options in your `i2pd.conf` file. For example, to limit total 146 I2P traffic to 256KB/s and share 50% of this limit for a maximum of 20 transit 147 tunnels: 148 149 ``` 150 bandwidth = 256 151 share = 50 152 153 [limits] 154 transittunnels = 20 155 ``` 156 157 Similar 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 160 Before doing this, please see the "Participating Traffic Considerations" section 161 in [Embedding I2P in your Application](https://geti2p.net/en/docs/applications/embedding). 162 163 In most cases, the default router settings should work fine. 164 165 ## Bundling I2P in a Bitcoin application 166 167 Please see the "General Guidance for Developers" section in https://geti2p.net/en/docs/api/samv3 168 if 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.