SAM v3 (“Simple Anonymous Messaging”) is the current stable, router agnostic API that allows external applications to communicate with the I2P network without embedding the router itself. It provides unified access to streams, datagrams, and raw messages, and remains the canonical bridge layer for non-Java software.
1. Overview and Purpose
SAM v3 enables developers to build I2P aware software in any language using a lightweight TCP/UDP protocol. It abstracts router internals, exposing a minimal set of commands over TCP (7656) and UDP (7655). Both Java I2P and i2pd implement subsets of the SAM v3 specification, though i2pd still lacks most 3.2 and 3.3 extensions as of 2025.
2. Version History
| Version | Introduced | Key Features |
|---|---|---|
| 3.0 | 0.7.3 (May 2009) | Streams + Datagrams; binary destinations; `SESSION CREATE STYLE=` parameter. |
| 3.1 | 0.9.14 (Jul 2014) | Signature type negotiation via `SIGNATURE_TYPE`; improved `DEST GENERATE`. |
| 3.2 | 0.9.24 (Jan 2016) | Per session encryption + tunnel options; `STREAM CONNECT ID` support. |
| 3.3 | 0.9.25 (Mar 2016) | PRIMARY / SUBSESSION architecture; multiplexing; improved datagrams. |
Naming Note
- Java I2P uses
PRIMARY/SUBSESSION. - i2pd and I2P+ continue to use legacy
MASTER/SUBSESSIONterminology for backward compatibility.
3. Core Workflow
Version Negotiation
HELLO VERSION MIN=3.1 MAX=3.3
HELLO REPLY RESULT=OK VERSION=3.3
Destination Creation
DEST GENERATE SIGNATURE_TYPE=7
SIGNATURE_TYPE=7→ Ed25519 (EdDSA SHA512). Strongly recommended since I2P 0.9.15.
Session Creation
SESSION CREATE STYLE=STREAM DESTINATION=NAME OPTION=i2cp.leaseSetEncType=4,0 OPTION=inbound.quantity=3 OPTION=outbound.quantity=3
i2cp.leaseSetEncType=4,0→4is X25519 (ECIES X25519 AEAD Ratchet) and0is ElGamal fallback for compatibility.- Explicit tunnel quantities for consistency: Java I2P default 2, i2pd default 5.
Protocol Operations
STREAM CONNECT ID=1 DESTINATION=b32address.i2p
STREAM SEND ID=1 SIZE=128
STREAM CLOSE ID=1
Core message types include: STREAM CONNECT, STREAM ACCEPT, STREAM FORWARD, DATAGRAM SEND, RAW SEND, NAMING LOOKUP, DEST LOOKUP, PING, QUIT.
Graceful Shutdown
QUIT
4. Implementation Differences (Java I2P vs i2pd)
| Feature | Java I2P 2.10.0 | i2pd 2.58.0 (Sept 2025) |
|---|---|---|
| SAM enabled by default | ❌ Requires manual enable in router console | ✅ Enabled via `enabled=true` in `i2pd.conf` |
| Default ports | TCP 7656 / UDP 7655 | Same |
| AUTH / USER / PASSWORD | ✓ Supported | ✗ Not implemented |
| PING / PONG keepalive | ✓ Supported | ✗ Not implemented |
| QUIT / STOP / EXIT commands | ✓ Supported | ✗ Not implemented |
| FROM_PORT / TO_PORT / PROTOCOL | ✓ Supported | ✗ Not implemented |
| PRIMARY/SUBSESSION support | ✓ (since 0.9.47) | ✗ Absent |
| SESSION ADD / REMOVE | ✓ Supported | ✗ Not implemented |
| Datagram2 / Datagram3 support | ✓ (since 2.9.0) | ✗ Not implemented |
| SSL/TLS | Optional | ✗ None |
| Default tunnel quantities | Inbound/outbound=2 | Inbound/outbound=5 |
Recommendation: Always specify tunnel quantities explicitly to ensure cross router consistency.
5. Supported Libraries (2025 Snapshot)
| Library | Language | SAM Support | Maintenance Status (2025) |
|---|---|---|---|
| libsam3 | C | 3.1 | Maintained by I2P Project (eyedeekay) |
| i2psam | C++ | 3.1 | Minimal updates since 2019 |
| sam3 | Go | 3.3 | Active; migrated from `eyedeekay/sam3` |
| onramp | Go | 3.3 | Actively maintained (2025) |
| i2plib | Python | 3.1 | Modern async replacement for `i2p.socket` |
| i2p.socket | Python | 3.2 | Abandoned (last release 2017) |
| Py2p | Python | 3.3 | Unverified/inactive |
| i2p-rs | Rust | 3.1 | Experimental; unstable API |
| @diva.exchange/i2p-sam | TypeScript / JS | 3.3 | Most actively maintained (2024–2025) |
| I2PSharp | C# | 3.3 | Functional; light maintenance |
6. Upcoming and New Features (2024–2025)
| Feature | Status | Introduced |
|---|---|---|
| NAMING LOOKUP `OPTIONS=true` | ✓ Supported | 2.8.0 |
| Datagram2 / Datagram3 formats | ✓ (Java only) | 2.9.0 |
| Post-quantum hybrid crypto (ML KEM) | Optional | 2.10.0 |
| Java 17+ runtime requirement | Planned | 2.11.0 |
| I2P over Tor blocking | Active | 2.6.0 |
| Improved floodfill selection | Active | 2.8.0+ |
7. Security and Configuration Notes
- Bind SAM to
127.0.0.1only. - For persistent services, use PRIMARY sessions with static keys.
- Use
HELLO VERSIONto test for feature support. - Use
PINGorNAMING LOOKUPto verify router liveness. - Avoid unauthenticated remote SAM connections (no TLS in i2pd).
8. References and Specifications
- SAM v3 Specification
- SAM v2 (Legacy)
- Streaming Specification
- Datagrams
- Documentation Hub
- i2pd Documentation
9. Summary
SAM v3 remains the recommended bridge protocol for all non Java I2P applications. It offers stability, cross language bindings, and consistent performance across router types.
When developing with SAM:
- Use Ed25519 signatures and X25519 encryption.
- Verify feature support dynamically via
HELLO VERSION. - Design for compatibility, especially when supporting both Java I2P and i2pd routers.