docs: I2P-EMBEDDED-ARCHITECTURE.md
This commit is contained in:
Krystie
@@ -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 = <P2P_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=<port>` | `19100` | I2P SOCKS proxy port |
|
||||
| `-i2psam=<port>` | `7656` | I2P SAM bridge port |
|
||||
| `-i2phsport=<port>` | 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>.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 `<datadir>/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
|
||||
Reference in New Issue
Block a user