From 9052b79ef6656e15c0cf6e21b442f8f656f1b399 Mon Sep 17 00:00:00 2001 From: Krystie Date: Sat, 27 Jun 2026 16:33:23 -0700 Subject: [PATCH] docs: I2P-EMBEDDED-ARCHITECTURE.md --- I2P-EMBEDDED-ARCHITECTURE.md | 237 +++++++++++++++++++++++++++++++++++ 1 file changed, 237 insertions(+) create mode 100644 I2P-EMBEDDED-ARCHITECTURE.md diff --git a/I2P-EMBEDDED-ARCHITECTURE.md b/I2P-EMBEDDED-ARCHITECTURE.md new file mode 100644 index 0000000..90a1cde --- /dev/null +++ b/I2P-EMBEDDED-ARCHITECTURE.md @@ -0,0 +1,237 @@ +# I2P Embedded Architecture (Level 3) + +**Date:** 2026-06-27 +**Status:** ✅ IMPLEMENTED & WORKING + +--- + +## What This Is + +Triangles now runs **two embedded anonymity networks simultaneously**: + +1. **Tor** — Every node is a .onion hidden service (existing, unchanged) +2. **I2P** — Every node is a .b32.i2p destination (new) + +Both routers run **in-process** as static libraries. No external dependencies, no separate daemons to install. + +### What I2P Adds Over Tor-Only + +| Property | Tor | I2P | +|----------|-----|-----| +| Routing | Onion (3-hop circuits) | Garlic (variable-hop tunnels) | +| Directory | Centralized authorities | Distributed floodfills | +| Service discovery | Hidden service descriptors | Network database (KadDHT) | +| Designed for | Exit to clearnet | Peer-to-peer services | +| Peer correlation resistance | Moderate | Strong (ephemeral tunnels) | + +I2P was designed from the ground up for **peer-to-peer anonymous services** — exactly what a cryptocurrency P2P network needs. Tor's hidden services work, but Tor is optimized for anonymous web browsing (exit traffic). I2P's garlic routing, distributed network database, and short-lived tunnels make it inherently better suited for P2P mesh communication. + +--- + +## Architecture + +### Dual-Network Routing + +``` + ┌─────────────────────────────────┐ + │ trianglesd (process) │ + │ │ + │ ┌─────────┐ ┌─────────┐ │ + │ │ libtor │ │ libi2pd │ │ + │ │ (Tor) │ │ (I2P) │ │ + │ └────┬────┘ └────┬────┘ │ + │ │ │ │ + .onion peers ─────┼───────┘ │ │ + │ SOCKS 19099 │ │ + │ │ │ + .b32.i2p peers ───┼──────────────────────┘ │ + │ SOCKS 19100 │ + └─────────────────────────────────┘ +``` + +### Traffic Flow + +| Destination | Route | Proxy | +|-------------|-------|-------| +| `*.onion` | Tor SOCKS5 → Tor circuit → hidden service | 127.0.0.1:19099 | +| `*.b32.i2p` | I2P SOCKS5 → I2P tunnel → destination | 127.0.0.1:19100 | +| Clearnet (IPv4/IPv6) | **BLOCKED** | — | + +The routing decision happens in `ConnectSocketByName()` (netbase.cpp): +- `.b32.i2p` suffix → I2P SOCKS proxy (NET_I2P) +- Everything else → Tor name proxy (SetNameProxy) + +--- + +## Implementation + +### Files Added + +``` +src/i2p/ +├── i2pd-src/ # PurpleI2P/i2pd git submodule +├── i2p_embedded.h # CI2PEmbedded class declaration +├── i2p_embedded.cpp # Embedded router start/stop logic +├── i2pseed.h # Hardcoded .b32.i2p seed nodes +└── build-libi2pd.sh # Static library build script +``` + +### Files Modified + +| File | Change | +|------|--------| +| `CMakeLists.txt` | `USE_I2P_EMBEDDED` option + config summary | +| `src/CMakeLists.txt` | I2P source, includes, library linking | +| `src/init.cpp` | I2P startup (after Tor), shutdown, CLI flags | +| `src/net.cpp` | Allow `.b32.i2p` in `ConnectNode()` and seed parser | +| `src/netbase.cpp` | I2P SOCKS routing, fixed `.b32.i2p` address parsing | + +### CI2PEmbedded Class + +Singleton pattern (mirrors `CTorEmbedded`): + +```cpp +class CI2PEmbedded { + bool Start(int socksPort, int samPort, int serverPort); + void Stop(); + bool IsRunning() const; + std::string GetSocksProxy() const; // "127.0.0.1:19100" + std::string GetI2PAddress() const; // .b32.i2p destination +}; +``` + +### Startup Sequence (init.cpp) + +``` +1. StartEmbeddedTor() → Tor SOCKS on 19099 +2. TOR-NATIVE MODE → all traffic forced through Tor +3. StartEmbeddedI2P() → i2pd SOCKS on 19100 +4. I2P-NATIVE MODE → .b32.i2p routed through i2pd +5. Dual-network anonymity → Tor + I2P co-equal +``` + +If I2P fails to start, the daemon continues in Tor-only mode (non-fatal). + +### How i2pd Integrates + +i2pd provides a C++ API (`libi2pd/api.h`) for in-process embedding: + +```cpp +i2p::api::InitI2P(argc, argv, "triangles-i2pd"); +i2p::api::StartI2P(logStream); +i2p::client::context.Start(); // SAM, SOCKS, tunnels +``` + +The auto-generated `i2pd.conf` enables: +- SOCKS proxy on 19100 (for outbound .b32.i2p) +- SAM bridge on 7656 (for future SAM v3 protocol) +- Server tunnel in `tunnels.conf` (I2P hidden service) + +The `tunnels.conf` is written before `Start()`: +```ini +[triangles-p2p] +type = server +host = 127.0.0.1 +port = +keys = triangles-p2p-keys.dat +inbound.length = 3 +outbound.length = 3 +``` + +This creates a persistent `.b32.i2p` destination that survives restarts. + +--- + +## Build Instructions + +### Prerequisites + +Same as existing Tor build + Boost (already required). + +### Build with I2P + +```bash +# 1. Initialize the i2pd submodule +git submodule update --init --recursive src/i2p/i2pd-src + +# 2. Build i2pd static libraries +cd src/i2p && bash build-libi2pd.sh + +# 3. Configure and build Triangles +mkdir build && cd build +cmake -G Ninja -DUSE_I2P_EMBEDDED=ON .. +ninja trianglesd +``` + +### Build without I2P (Tor-only, existing behavior) + +```bash +cmake -G Ninja .. # USE_I2P_EMBEDDED defaults to OFF +ninja trianglesd +``` + +--- + +## CLI Flags + +| Flag | Default | Description | +|------|---------|-------------| +| `-i2p` | `1` | Enable embedded I2P router | +| `-i2psocks=` | `19100` | I2P SOCKS proxy port | +| `-i2psam=` | `7656` | I2P SAM bridge port | +| `-i2phsport=` | P2P port | I2P server tunnel forward port | + +--- + +## Testing Verification + +### Expected Startup Output + +``` +Embedded I2P: starting i2pd router... +Embedded I2P: server tunnel configured on port 24112 +... +Clients: New private keys file .../triangles-p2p-keys.dat for .b32.i2p created +Clients: 1 I2P server tunnels created +Embedded I2P: SOCKS proxy at 127.0.0.1:19100, SAM at 127.0.0.1:7656 +... +I2P-NATIVE MODE: I2P router running + SOCKS proxy at 127.0.0.1:19100 for .b32.i2p connections + Dual-network anonymity: Tor (.onion) + I2P (.b32.i2p) +``` + +--- + +## Seed Node Deployment + +To deploy an I2P seed node: + +1. Build with `-DUSE_I2P_EMBEDDED=ON` +2. Start the daemon — it auto-generates a `.b32.i2p` destination +3. Read the address from the log: `grep "b32.i2p" debug.log` +4. Add the address to `src/i2p/i2pseed.h` +5. Add the address to `seeds.cryptographic-triangles.org/i2p-seeds.txt` + +The destination keys persist in `/i2p_data/triangles-p2p-keys.dat`. + +--- + +## Comparison to Other Projects + +| Project | Tor | I2P | Embedded | Dual-Network | +|---------|-----|-----|----------|-------------| +| **Triangles** | ✅ Embedded | ✅ Embedded | Both in-process | ✅ | +| Bitcoin Core | Optional | Optional (SAM) | No | No | +| Monero | Optional | No | No | No | +| Kovri (Monero I2P) | N/A | Planned | Planned | No | + +Triangles is the only cryptocurrency with **both** Tor and I2P embedded as in-process routers. + +--- + +## Future Work + +- **I2P seed nodes:** Deploy stable .b32.i2p seeds (parallel to onion seeds) +- **SAM v3 direct:** Use SAM bridge for native I2P streaming (bypass SOCKS overhead) +- **I2P address in RPC:** Expose `.b32.i2p` address via `getnetworkinfo` +- **Cross-network bridging:** Allow Tor nodes to discover I2P peers and vice versa