doc: add basic I2P documentation #22250

pull vasild wants to merge 2 commits into bitcoin:master from vasild:i2p_doc changing 2 files +75 −2
  1. vasild commented at 12:14 pm on June 15, 2021: member
    Add basic I2P documentation to help users to start using I2P and Bitcoin Core.
  3. fanquake added the label Docs on Jun 15, 2021
  5. jonatack commented at 12:21 pm on June 15, 2021: member

    Concept ACK!

    Can be merged after FF but is needed before release.

  6. fanquake commented at 12:24 pm on June 15, 2021: member

    Can be merged after FF

    Why after feature freeze? I can’t see why this couldn’t be merged at any time.

  7. jonatack commented at 12:37 pm on June 15, 2021: member
    That it’s ok if it isn’t merged today.
  8. MarcoFalke commented at 12:57 pm on June 15, 2021: member
    Missing a link to the new doc from the main file doc/Readme.md?
  9. theStack commented at 1:26 pm on June 15, 2021: member
    Concept ACK
  10. ghost commented at 2:43 pm on June 15, 2021: none

    Concept ACK

    nit: Docs mention i2p ‘router’ is required, this can be confusing for some users. I had to use i2pd (C++) instead of i2prouter (Java) last time I tried i2p in Bitcoin Core.

    Related comments:

    #20685 (comment)

    #20685 (comment)

    #20685 (comment)

    Will test again today on POP!_OS.

  11. ghost commented at 8:54 pm on June 15, 2021: none

    Tried on POP!_OS and had no issues except last step:

    1. Install i2pd using instructions mentioned for Ubuntu: https://i2pd.readthedocs.io/en/latest/user-guide/install/

    2. Run: sudo systemctl start i2pd.service

    3. Confirm if running: ss -nlt

      0State   Recv-Q   Send-Q     Local Address:Port      Peer Address:Port  Process  
1
2LISTEN  0        4096           127.0.0.1:7656           0.0.0.0:*

    4. bitcoin.conf:

      0testnet=1
1i2psam=127.0.0.1:7656
2i2pacceptincoming=1
3debug=i2p

    5. Run bitcoind

    6. Check debug.log:

      02021-06-15T20:36:16Z i2paccept thread start
12021-06-15T20:36:16Z I2P: Creating SAM session with 127.0.0.1:7656
2
32021-06-15T20:36:56Z I2P: SAM session created: session id=3e0f35228b, my address=bmwyyuzyqdc5dcx27s4baltbu6zw7rbqfl2nmclt45i7ng3ul4pa.b32.i2p:18333
42021-06-15T20:36:56Z AddLocal(bmwyyuzyqdc5dcx27s4baltbu6zw7rbqfl2nmclt45i7ng3ul4pa.b32.i2p:18333,4)

    7. Confirm i2p_private_key was created:

      0~/.bitcoin/testnet3$ ls
1
2anchors.dat  chainstate         i2p_private_key  settings.json
3banlist.dat  debug.log          mempool.dat      wallets
4blocks       fee_estimates.dat  peers.dat

    8. bitcoin-cli -netinfo returns i2p address but no column for i2p peers

      0Bitcoin Core v21.99.0-eb63b1db2c4d testnet - 70016/Satoshi:21.99.0/
1
2        ipv4    ipv6   onion   total   block
3in         0       0       0       0
4out       10       0       0      10       2
5total     10       0       0      10
6
7Local addresses
8bmwyyuzyqdc5dcx27s4baltbu6zw7rbqfl2nmclt45i7ng3ul4pa.b32.i2p     port  18333    score      4
  12. jonatack commented at 9:07 pm on June 15, 2021: member
    -netinfo displays an I2P column if you have any I2P connections; addnode any of the I2P addresses in contrib/seeds/nodes_main.txt and you will see the connection in -netinfo.
  13. in doc/i2p.md:1 in 2f689c9bfe outdated 
    0@@ -0,0 +1,64 @@
1+# I2P SUPPORT IN BITCOIN
    laanwj commented at 2:50 pm on June 17, 2021:
    No need to use full-caps here. We don’t use this in other documents, and besides, the idea of a high-level formatting language like markdown is to leave it up to the rendering engine how different styles are shown.
    vasild commented at 2:28 pm on June 18, 2021:

    I actually lowercased that before reading your comment! Also changed BITCOIN to Bitcoin Core, since this doc is specific to Bitcoin Core.

    It was a copy-paste-modify from doc/tor.md which uses uppercase.

  14. in doc/i2p.md:72 in 2f689c9bfe outdated 
    59+or the RPC `getpeerinfo` (e.g. `bitcoin-cli getpeerinfo`).
60+
61+## Compatibility
62+
63+Bitcoin Core uses the [SAM v3.1](https://geti2p.net/en/docs/api/samv3) protocol
64+to connect to the I2P network. Any I2P router that supports it can be used.
    laanwj commented at 2:52 pm on June 17, 2021:
    Please add a link to this document in doc/README.md (the best place is likely where tor.md is mentioned) so that people can find it more easily.
    vasild commented at 2:28 pm on June 18, 2021:
    Done.
  15. laanwj added this to the milestone 22.0 on Jun 17, 2021
  16. in doc/i2p.md:36 in 2f689c9bfe outdated 
    31+```
32+bitcoind -i2psam=127.0.0.1:7656
33+```
34+
35+The first time Bitcoin Core connects to the I2P router its I2P address (and
36+its corresponding private key) will be automatically generated and saved in a
    jonatack commented at 9:09 am on June 18, 2021:
    • s/router/router,/
    • s/and its/and/
    vasild commented at 2:29 pm on June 18, 2021:
    Done.
  17. in doc/i2p.md:64 in 2f689c9bfe outdated 
    54+- in the debug log (grep for `AddLocal`, the I2P address ends in `.b32.i2p`)
55+- in the output of RPC `getnetworkinfo` in the "localaddresses" section
56+- in the output of the CLI `-netinfo` peer connections dashboard
57+
58+To see to which I2P peers your node is connected, use `bitcoin-cli -netinfo 4`
59+or the RPC `getpeerinfo` (e.g. `bitcoin-cli getpeerinfo`).
    jonatack commented at 9:12 am on June 18, 2021:
    Maybe mention that you can see which I2P addresses your node knows with RPC getnodeaddresses 0 i2p and (maybe, not sure) that there are I2P seed nodes to bootstrap your I2P connections in /contrib/seeds/nodes_main.txt
    vasild commented at 2:33 pm on June 18, 2021:

    Added getnodeaddresses 0 i2p, but not the seeds mention.

    Actually, we use the seeds to fill addrman / establish a connection if we don’t have any. But as far as I am aware we do this regardless of the network. Should we do that per-network? I.e. make sure we establish at least one connection to Tor if the user has bothered to setup a Tor proxy, using the seeds if necessary? Same for I2P.

    jonatack commented at 3:24 pm on June 18, 2021:
    This seems like a good idea. IRC discussion: https://www.erisian.com.au/bitcoin-core-dev/log-2021-06-18.html#l-289
    jonatack commented at 3:27 pm on June 18, 2021:
    The few times I talked people through testing an I2P service, each time they needed an I2P address to connect to or wouldn’t see one. @prayank23’s review is another good example :+1:
    vasild commented at 2:10 pm on June 21, 2021:

    “(N being either I2P or Tor). If N is configured, make sure we have at least one connection to N (either inbound or outbound). If nobody connects to us, then try to open a connection to a peer from N (using either the seeds or addresses received via gossip)”.

    This will help I2P now / 22.0. But it is too late for 22.0.

    For 23.0 it may not be necessary for I2P if it gains traction quickly. I am not sure if Tor needs it at all.

    jonatack commented at 2:15 pm on June 21, 2021:
    If demonstrated to be an issue, it may (possibly) not be too late.
  18. in doc/i2p.md:3 in 2f689c9bfe outdated 
    0@@ -0,0 +1,64 @@
1+# I2P SUPPORT IN BITCOIN
2+
3+It is possible to use Bitcoin Core to accept and make connections from/to other
    jonatack commented at 9:15 am on June 18, 2021: 
    0It is possible to use Bitcoin Core to accept and make connections to/from other
    vasild commented at 2:34 pm on June 18, 2021:
    Since the wording is “accept from” and “connect to” and since “accept” comes before “connect”, I put “from” before “to”. Reworded in a different way now.
  19. jonatack commented at 9:18 am on June 18, 2021: member
    ACK, modulo the comments. I was wondering if we should warn that i2pd needs to be a version more recent than 2.33.0 due to the issues Suhas experienced with it, but mentioning i2pd can be done in a follow-up, if desired.
  20. laanwj commented at 12:12 pm on June 18, 2021: member

    I was wondering if we should warn that i2pd needs to be a version more recent than 2.33.0 due to the issues Suhas experienced with it, but mentioning i2pd can be done in a follow-up

    Was about to comment this as well, but I guess we cannot really recommend any version of i2pd at this point at all due to known crash issues? In any case, I agree it can be done later if at all.

  21. ghost commented at 12:18 pm on June 18, 2021: none
    I have nothing more to add in review apart from my comments above. Would be helpful if someone could answer this question on SE: https://bitcoin.stackexchange.com/questions/107060/tor-and-i2p-tradeoffs-in-bitcoin-core
  22. vasild force-pushed on Jun 18, 2021
  23. vasild commented at 2:25 pm on June 18, 2021: member
    2f689c9bfe...28fb34a275: address suggestions
  24. vasild force-pushed on Jun 18, 2021
  25. vasild commented at 2:27 pm on June 18, 2021: member

    28fb34a275...e498c9292a: remove redundant word

    Render: https://github.com/bitcoin/bitcoin/blob/e498c9292af233c33616dcee2fe749ecb85fa186/doc/i2p.md

  26. vasild commented at 2:36 pm on June 18, 2021: member
    @prayank23, I added a link to the I2P glossary https://geti2p.net/en/about/glossary, I think “I2P router” in general means an I2P proxy not the specific implementation in Java.
  27. in doc/i2p.md:13 in e498c9292a outdated 
     8+started with I2P terminology.
 9+
10+## Run Bitcoin Core with an I2P router (proxy)
11+
12+A running I2P router (proxy) with [SAM](https://geti2p.net/en/docs/api/samv3)
13+enabled is required (there is an [official one](https://geti2p.net) and
    unknown commented at 2:54 pm on June 18, 2021:
    This official link has one ‘download’ button, it will open https://geti2p.net/en/download which has options for different OS. If you try installing i2p for Ubuntu from here it won’t work. Others also look like .jar files
  28. in doc/i2p.md:7 in e498c9292a outdated 
    0@@ -0,0 +1,71 @@
1+# I2P support in Bitcoin Core
2+
3+It is possible to use Bitcoin Core to accept connections from and make
4+connections to other Bitcoin nodes through the
5+[I2P network](https://en.wikipedia.org/wiki/I2P).
6+
7+[I2P glossary](https://geti2p.net/en/about/glossary) may be useful to get
    jonatack commented at 2:56 pm on June 18, 2021: 
    0This [glossary](https://geti2p.net/en/about/glossary) may be useful to get

    or

    “The…with terminology.”

    vasild commented at 9:50 am on June 21, 2021:
    Done.
  29. in doc/i2p.md:15 in e498c9292a outdated 
    10+## Run Bitcoin Core with an I2P router (proxy)
11+
12+A running I2P router (proxy) with [SAM](https://geti2p.net/en/docs/api/samv3)
13+enabled is required (there is an [official one](https://geti2p.net) and
14+[a few alternatives](https://en.wikipedia.org/wiki/I2P#Routers)). Notice the IP
15+address and port the SAM proxy is listening to. Usually that is
    jonatack commented at 2:58 pm on June 18, 2021: 
    0address and port the SAM proxy is listening to; usually, it is
    vasild commented at 9:51 am on June 21, 2021:
    Done.
  30. in doc/i2p.md:17 in e498c9292a outdated 
    12+A running I2P router (proxy) with [SAM](https://geti2p.net/en/docs/api/samv3)
13+enabled is required (there is an [official one](https://geti2p.net) and
14+[a few alternatives](https://en.wikipedia.org/wiki/I2P#Routers)). Notice the IP
15+address and port the SAM proxy is listening to. Usually that is
16+`127.0.0.1:7656`. Once it is up and running with SAM enabled, the following
17+Bitcoin Core options can be used to engage with it:
    jonatack commented at 2:58 pm on June 18, 2021:
    maybe s/engage with/configure/
    vasild commented at 9:51 am on June 21, 2021:
    Reworded in another way.
  31. in doc/i2p.md:46 in e498c9292a outdated 
    41+named `i2p_private_key` in the Bitcoin Core data directory.
42+
43+## Additional configuration options related to I2P
44+
45+You may set the `-debug=i2p` config logging option to have additional
46+information in the debug log about your I2P configuration and connections.
    jonatack commented at 2:59 pm on June 18, 2021:
    Perhaps add “Run bitcoin-cli help logging for more information.” (Have received many questions from users and devs about this.)
    vasild commented at 9:51 am on June 21, 2021:
    Done.
  32. in doc/i2p.md:53 in e498c9292a outdated 
    48+It is possible to restrict outgoing connections in the usual way with
49+`-onlynet=i2p`. Notice that, I2P support being new (as of 2021), there are not
50+as many I2P peers as Tor or IP ones. So using `-onlynet=i2p` may make a node
51+more susceptible to
52+[Sybil attack](https://en.bitcoin.it/wiki/Weaknesses#Sybil_attack). Use CLI
53+`-addrinfo` to see the number of I2P addresses known to your node.
    jonatack commented at 3:01 pm on June 18, 2021:
    maybe “Run bitcoin-cli -addrinfo to see…”
    vasild commented at 9:51 am on June 21, 2021:
    Done.
  33. in doc/i2p.md:52 in e498c9292a outdated 
    46+information in the debug log about your I2P configuration and connections.
47+
48+It is possible to restrict outgoing connections in the usual way with
49+`-onlynet=i2p`. Notice that, I2P support being new (as of 2021), there are not
50+as many I2P peers as Tor or IP ones. So using `-onlynet=i2p` may make a node
51+more susceptible to
    jonatack commented at 3:04 pm on June 18, 2021:
    • A propos “Notice that…” and “So using…”, maybe something like:

    “I2P support was added to Bitcoin Core in version 22.0 and there may be fewer I2P peers than Tor ones. Therefore, using…”

    • s/attack/attacks/
    vasild commented at 9:52 am on June 21, 2021:
    Changed to “attacks”, but left it as is otherwise.
    jonatack commented at 2:19 pm on June 21, 2021:
    Definitely no need to use my suggestion, but if helpful, it’s incorrect/not really great to begin a sentence with “So using”… and “Notice that” isn’t great either (and, like “note that,” it is unneeded and can be omitted).
    vasild commented at 2:54 pm on June 21, 2021:

    Actually mentioning this was Gleb’s idea. Poking him here to ensure that I conveyed it correctly.

    cc @naumenkogs

    jarolrod commented at 10:59 pm on June 21, 2021:

    Not a major nit, but @jonatacks suggestion is grammatically correct compared to the current sentence.

    Iterating on top of jons suggestion

    0I2P support was added to Bitcoin Core in version 22.0 and there may be fewer I2P peers than on the Tor or IP networks. Therefore, using...
    vasild commented at 10:16 am on June 23, 2021:
    Reworded. “Gramattik”, what is that?
  34. jonatack commented at 3:08 pm on June 18, 2021: member

    ACK with a few more comments :)

    Edit: I wonder if the first sentence from doc/tor.md would be clearer: “It is possible to run Bitcoin Core as an I2P (Invisible Internet Project) service and connect to such services.”

  35. vasild force-pushed on Jun 21, 2021
  36. vasild commented at 9:50 am on June 21, 2021: member
    e498c9292a...afe5c3e70a: address suggestions and remove leading - from config options since - is used only on the command line and not in bitcoin.conf and it may be confused with an option to bitcoin-cli (instead of bitcoind).
  37. vasild commented at 9:54 am on June 21, 2021: member

    I wonder if the first sentence from doc/tor.md would be clearer: “It is possible to run Bitcoin Core as an I2P (Invisible Internet Project) service and connect to such services.”

    Yes. The previous “to connect to other bitcoin nodes through I2P” may be interpreted as to connect to other non-I2P nodes (e.g. IPv4).

  38. in doc/i2p.md:63 in afe5c3e70a outdated 
    58+There are several ways to see your I2P address in Bitcoin Core:
59+- in the debug log (grep for `AddLocal`, the I2P address ends in `.b32.i2p`)
60+- in the output of RPC `getnetworkinfo` in the "localaddresses" section
61+- in the output of `bitcoin-cli -netinfo` peer connections dashboard
62+
63+To see to which I2P peers your node is connected, use `bitcoin-cli -netinfo 4`
    jonatack commented at 3:20 pm on June 21, 2021: 
    0To see which I2P peers your node is connected to, use `bitcoin-cli -netinfo 4`

    and omit “the” in the following line or “the getpeerinfo RPC”

    vasild commented at 10:19 am on June 23, 2021:
    Done.
  39. in doc/i2p.md:66 in afe5c3e70a outdated 
    61+- in the output of `bitcoin-cli -netinfo` peer connections dashboard
62+
63+To see to which I2P peers your node is connected, use `bitcoin-cli -netinfo 4`
64+or the RPC `getpeerinfo` (e.g. `bitcoin-cli getpeerinfo`).
65+
66+To see which I2P addresses your node knows, use the RPC
    jonatack commented at 3:23 pm on June 21, 2021: 
    0To see which I2P addresses your node knows, run RPC
    vasild commented at 10:20 am on June 23, 2021:
    No
    jonatack commented at 11:07 am on June 23, 2021:
    “run” because getnodeaddresses 0 i2p is not just the name of an RPC but a call with specific arguments. But definitely a pico-nit.
  40. in doc/README.md:82 in afe5c3e70a outdated 
    78@@ -79,6 +79,7 @@ The Bitcoin repo's [root README](/README.md) contains relevant information on th
79 - [Reduce Memory](reduce-memory.md)
80 - [Reduce Traffic](reduce-traffic.md)
81 - [Tor Support](tor.md)
82+- [I2P Support](i2p.md)
    jonatack commented at 3:25 pm on June 21, 2021:
    nit, sort (these are listed in alphabetical order, the “init scripts” and “psbt” entries could optionally be moved, too)
    jarolrod commented at 10:37 pm on June 21, 2021:

    agree on sorting I2P Support

    Sorting Init Scripts and the PSBT entries can be left for a followup

    vasild commented at 10:20 am on June 23, 2021:
    Sorted.
  41. in doc/i2p.md:7 in afe5c3e70a outdated 
    0@@ -0,0 +1,72 @@
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 [I2P glossary](https://geti2p.net/en/about/glossary) may be useful to get
    jonatack commented at 3:27 pm on June 21, 2021: 
    0This [glossary](https://geti2p.net/en/about/glossary) may be useful to get

    (“I2P” already used in this sentence to describe the terminology)

    jarolrod commented at 10:38 pm on June 21, 2021:
    agree this could just be glossary
    vasild commented at 10:21 am on June 23, 2021:
    Done.
  42. jonatack commented at 3:30 pm on June 21, 2021: member

    ACK

    There are a few fixups but nothing that can’t be done in a follow-up before -final. Personally, I was procrastinating on writing this doc out of bikeshed avoidance, so just noting a few things here and happy to open a follow-up.

  43. doc: add basic I2P documentation cad487bcfa
  44. doc: sort entries in doc/README.md#Miscellaneous alphabetically 78cdab1ad2
  45. vasild force-pushed on Jun 23, 2021
  46. vasild commented at 10:24 am on June 23, 2021: member

    afe5c3e70a...78cdab1ad2: address suggestions

    For the next time: maybe a wiki is more appropriate, where everybody can edit and only open a PR once settled/finalized.

  47. jonatack commented at 11:08 am on June 23, 2021: member

    ACK 78cdab1ad2e85176784e4e1230622f42acd20149

    Thanks for updating. It may be a good idea to mention the ports (0 or ignored) I2P specificity to users here once it’s settled.

  48. laanwj commented at 11:38 am on June 24, 2021: member

    ACK 78cdab1ad2e85176784e4e1230622f42acd20149

    For the next time: maybe a wiki is more appropriate, where everybody can edit and only open a PR once settled/finalized.

    Yes, I don’t think this is a bad idea for new documentation. I’d be uncomfortable with using a wiki as main documentation source, but during the editing phase it can be less friction.

  49. laanwj merged this on Jun 24, 2021
  50. laanwj closed this on Jun 24, 2021
  51. michaelfolkson commented at 11:43 am on June 24, 2021: contributor

    For the next time: maybe a wiki is more appropriate, where everybody can edit and only open a PR once settled/finalized.

    Neat idea. Better than a StackExchange post if it is intended to go directly into Core docs and as @laanwj says less friction during editing phase than opening a PR with a first draft.

  52. vasild deleted the branch on Jun 24, 2021
  53. vasild commented at 12:33 pm on June 24, 2021: member
    Indeed. Just the initial/draft phase.
  54. sidhujag referenced this in commit 379d21746c on Jun 24, 2021
  55. PastaPastaPasta referenced this in commit bec40bed09 on Jun 27, 2021
  56. PastaPastaPasta referenced this in commit 59658f72d8 on Jun 28, 2021
  57. PastaPastaPasta referenced this in commit 58bed68b4e on Jun 29, 2021
  58. PastaPastaPasta referenced this in commit 944f9eaafd on Jul 1, 2021
  59. PastaPastaPasta referenced this in commit 7db7cfd117 on Jul 1, 2021
  60. PastaPastaPasta referenced this in commit 31fadf08f7 on Jul 15, 2021
  61. PastaPastaPasta referenced this in commit a20e445a5a on Jul 15, 2021
  62. Fabcien referenced this in commit 24433c09e9 on Feb 15, 2022
  63. gwillen referenced this in commit a1f89ca048 on Jun 1, 2022
  64. DrahtBot locked this on Aug 16, 2022


vasild jonatack fanquake MarcoFalke theStack ghost laanwj jarolrod michaelfolkson

Labels
Docs

Milestone
22.0

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2024-07-03 10:13 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me