Merge bitcoin/bitcoin#22250: doc: add basic I2P documentation

78cdab1ad2e85176784e4e1230622f42acd20149 doc: sort entries in doc/README.md#Miscellaneous alphabetically (Vasil Dimov)
cad487bcfa829b7e20a0aafcb9a21eb55d5d1528 doc: add basic I2P documentation (Vasil Dimov)

Pull request description:

  Add basic I2P documentation to help users to start using I2P and Bitcoin Core.

ACKs for top commit:
  jonatack:
    ACK 78cdab1ad2e85176784e4e1230622f42acd20149
  laanwj:
    ACK 78cdab1ad2e85176784e4e1230622f42acd20149

Tree-SHA512: 71cffc9419338a21cb9e811ee9463d6d09eef1a2a73190f766523bc1642a1f58984d5b2ab13da9b6560387ac9f431aace8bc7ae9b776585ecd3e3c1ff6af8e8d

2 files changed, 75 insertions, 2 deletions

diff --git a/doc/README.md b/doc/README.md
index c629c2ccfa..45e7983038 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -76,12 +76,13 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th
 - [bitcoin.conf Configuration File](bitcoin-conf.md)
 - [Files](files.md)
 - [Fuzz-testing](fuzzing.md)
+- [I2P Support](i2p.md)
+- [Init Scripts (systemd/upstart/openrc)](init.md)
+- [PSBT support](psbt.md)
 - [Reduce Memory](reduce-memory.md)
 - [Reduce Traffic](reduce-traffic.md)
 - [Tor Support](tor.md)
-- [Init Scripts (systemd/upstart/openrc)](init.md)
 - [ZMQ](zmq.md)
-- [PSBT support](psbt.md)
 
 License
 ---------------------
diff --git a/doc/i2p.md b/doc/i2p.md
new file mode 100644
index 0000000000..8b4607208a
--- /dev/null
+++ b/doc/i2p.md
@@ -0,0 +1,72 @@
+# 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) with [SAM](https://geti2p.net/en/docs/api/samv3)
+enabled is required (there is an [official one](https://geti2p.net) and
+[a few alternatives](https://en.wikipedia.org/wiki/I2P#Routers)). Notice the IP
+address and port the SAM proxy is listening to; usually, it is
+`127.0.0.1:7656`. Once it is up and running with SAM enabled, use the following
+Bitcoin Core options:
+
+```
+-i2psam=<ip:port>
+     I2P SAM proxy to reach I2P peers and accept I2P connections (default:
+     none)
+
+-i2pacceptincoming
+     If set and -i2psam is also set then incoming I2P connections are
+     accepted via the SAM proxy. If this is not set but -i2psam is set
+     then only outgoing connections will be made to the I2P network.
+     Ignored if -i2psam is not set. Listening for incoming I2P
+     connections is done through the SAM proxy, not by binding to a
+     local address and port (default: 1)
+```
+
+In a typical situation, this suffices:
+
+```
+bitcoind -i2psam=127.0.0.1:7656
+```
+
+The first time Bitcoin Core connects to the I2P router, its I2P address (and
+corresponding private key) will be automatically generated and saved in a file
+named `i2p_private_key` in the Bitcoin Core data directory.
+
+## Additional configuration options related to I2P
+
+You may set the `debug=i2p` config logging option to have additional
+information in the debug log about your I2P configuration and connections. Run
+`bitcoin-cli help logging` for more information.
+
+It is possible to restrict outgoing connections in the usual way with
+`onlynet=i2p`. I2P support was added to Bitcoin Core in version 22.0 (mid 2021)
+and there may be fewer I2P peers than Tor or IP ones. Therefore, using
+`onlynet=i2p` alone (without other `onlynet=`) may make a node more susceptible
+to [Sybil attacks](https://en.bitcoin.it/wiki/Weaknesses#Sybil_attack). Use
+`bitcoin-cli -addrinfo` to see the number of I2P addresses known to your node.
+
+## I2P related information in Bitcoin Core
+
+There are several ways to see your I2P address in Bitcoin Core:
+- in the debug log (grep for `AddLocal`, the I2P address ends in `.b32.i2p`)
+- in the output of the `getnetworkinfo` RPC in the "localaddresses" section
+- in the output of `bitcoin-cli -netinfo` peer connections dashboard
+
+To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4`
+or the `getpeerinfo` RPC (e.g. `bitcoin-cli getpeerinfo`).
+
+To see which I2P addresses your node knows, use the `getnodeaddresses 0 i2p`
+RPC.
+
+## 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.