Skip to content


idk requested to merge eyedeekay/ccs-proposals:monero-i2p-samv3 into master

This project redesigns and modernizes I2P support in Monero. It updates the GUI and docs to make I2P usage easy for users. By abandoning i2p-zero and encouraging users to install I2P themselves, Monero will be set up for flexible long-term I2P support with very little maintenance burden.

The GUI part of this project overlaps with the I2P GUI bounty but we do not recommend doing the I2P router bundling/management task referenced in that bounty.

Amount assumes that the 22.2 XMR bounty is claimed simultaneously, for 150 XMR total.



  • Redesign I2P support to use SAM version 3.1 ("SAMv3")
  • Provide GUI interface to enable and configure I2P support
  • Provide GUI indication of external router status up/down
  • Add sane default I2P configuration and a way to modify the default
  • Abandon i2p-zero
  • Abandon goal of bundling a router or managing an external i2p router
  • Support external Java I2P or i2pd router
  • Support both I2P-only and "mixed" network configurations
  • Rewrite documentation on how to install Java I2P or i2pd router and set it up to work with Monero


  • Bundling a router with Monero
  • Management/control of external router. The user will be responsible for installing/starting/stopping the router.
  • Connections via I2P outproxy to clearnet
  • Any mods or support of i2p-zero

Key Benefits:

  • Provide first-class I2P support for Monero

What do we mean by first-class support?

I2P provides a network layer for obfuscating metadata about connections, "anonymizing" the connection to observers. It does this by providing cryptographic addresses, "Destinations," to "applications" on a garlic-routed overlay network. This means that you have a "pseudonym" in the form of the destination which your peers use to communicate with you. The last application is usually a "Proxy" of some sort, such as a SOCKS proxy in the case of Monero right now. This last last application receives messages and distributes them to proxies applications.

What's wrong with SOCKS?

Most applications can be "proxied" over I2P to make them compatible with I2P. This can lead to a "Shared Identity" problem, where all applications who share the same SOCKS proxy also share the same return "destination" address. An attacker can run multiple applications and "collude" to discern whether they are operating on the same destination, leaking information about what is going on. In the case of "chatty" peer-to-peer applications that depend on frequently syncing information from peers, this can often be done in a mostly passive way. SOCKS lends itself to this type of misconfiguration.

How does SAMv3 fix it.

SAMv3 resolves the issue by providing a proxy which allows the application to configure it's own I2P connection.

  • SAMv3 provides far-end ID ("destination") for incoming connections; keys are generated as part of the handshake/connection setup process and can be stored or not as the application demands.
  • SAMv3 puts the application in control of the crypto keys and allows both permanent and transient destinations
  • SAMv3 allows the application to configure the tunnels rather than relying on external i2p-zero setup scripts; all tunnel options are available via SAM
  • Tunnel configuration may be changed by the application later, rather than one-shot by a setup script; this allows an application to "throw away" a pseudonym.

What's wrong with I2PTunnel?

Hidden Services Manager, a.k.a. I2PTunnel is a generic suite of proxies which are designed for adapting standard applications to I2P. It supports several kinds of proxies, including "standard" proxies which are similar to forwarding and reverse proxies, specialized HTTP and SOCKS proxies. However, each of these tunnels always has different destination keys. For an application like Monero which must accept incoming and outgoing connections, this means that it must generate manage 2 sets of destination keys. Hidden Services Manager is also a "manual" process, it is vaguely "scriptable" but the flexibility is quite limited when compared to SAMv3.

  • SAMv3 allows both incoming and outgoing connections; no need for two sets of tunnels like with i2p-zero; cuts resource usage in half and simplifies your network by using the same ID ("destination") for incoming and outgoing connections
  • Brings tunnel configuration options up to current cryptographic standards and recommendations; improves performance and allows upgrading the keys by the application

Lesser Benefits:

What's wrong with i2p-zero?

i2p-zero is an interesting project in many ways, but it's utility as an I2P router is severely compromised by it's elaborate and error-prone build process. i2p-zero is essentially a custom launcher and a buildsystem for the I2P router. The launcher itself is very simple, however the buildsystem is designed in such a way that it requires considerable expertise to maintain properly. It depends on obscure processes in order to successfully generate a minified runtime image for Java I2P a'la jpackage without the need for a Windows host. It does this by manually(and carefully) using jlink on an existing Windows-compatible image.

  • Remove dependency on unmaintained i2p-zero

  • External router allows users to keep it up-to-date with standard upgrade mechanisms

  • Much simpler than bundling a router or maintaining an external router fork

  • External unmanaged router is the same architecture adopted by bitcoin and libtorrent

  • SAMv3 is the standard API to interface with I2P routers

  • SAMv3 is supported by both Java I2P and i2pd

  • SAMv3 is used by bitcoin and libtorrent

  • Proven implementation in bitcoin with thousands of users

  • Numerous SAMv3 libraries are available, or code could be adapted from bitcoin or libtorrent (license permitting)

  • SAMv3 is fairly simple and is somewhat similar to SOCKS

Task Overview:

  • Become more familiar with I2P. Study the SAMv3 documentation. Run bitcoin with i2pd and/or Java I2P; become familiar with diagnostics in I2P router console
  • Experiment with SAMv3 via telnet to manually build tunnels and make connections to gain experience
  • Research available SAMv3 libraries and code; confirm license compatibility; select library or code to adapt, or decide to write from scratch
  • Maintain presence on I2P IRC for rapid answers to questions, informal progress reports, etc.
  • Decide whether to support permanent or transient destinations or both
  • Decide whether to use SAMv3 ACCEPT or FORWARD for incoming connections (probably ACCEPT)
  • Code SAM
  • Code GUI
  • Confirm best default configuration after consultation with I2P experts; ensure compliance with I2P guildelines
  • Test with both i2pd and Java I2P
  • Test Monero reaction to external router start/stop/restart
  • Add configuration to GUI
  • Implement any unit tests required by Monero code guidelines
  • Rewrite documentation; possibly adapt from bitcoin docs; ensure compliance with I2P guidelines
  • Docs to include user instructions for 1) New install of i2pd or Java I2P; 2) Migration from i2p-zero; 3) migration of existing (non-i2p-zero) i2pd or Java I2P install
  • Announce and recruit beta testers
  • Verify and update seed node list
  • Pass any Monero code review guidelines required for merging
  • PR, merge, include in Monero release
  • Announce and encourage Monero users to install and enable I2P


  • Datagrams (UDP) not required
  • I2P ports not required
  • SAM v3.2 or v3.3 not required


  • Android?


TBD, presumably somebody in the Monero dev community. I2P devs and community will provide consultation and support as necessary, without compensation, but should not be relied on for any coding or testing.

Estimated effort:

2-6 months depending on coder's experience For reference, the main bitcoin i2p code is about 500 lines (no GUI)

Expiration: 2024-12-31

Merge request reports