Porting I2P from Java to Python

The Invisible Internet Project has been running for over twenty years. Its Java implementation is one of the most battle-tested privacy systems in existence. This is the story of porting it to Python — and why.

Why Port I2P?

Ethereum validators are broadcasting their home IP addresses to anyone who asks. Researchers proved it — four nodes, 72 hours, 15% of all validators deanonymized. The fix is I2P: give nodes private addresses that can't be traced back to physical locations.

But integrating I2P into Ethereum clients means those clients need an I2P stack. The Java implementation is excellent — but Ethereum clients are written in Go, Rust, C#, and Python. Asking each team to embed a JVM is a non-starter.

A native Python implementation unlocks I2P for the entire Python ecosystem: not just Ethereum, but any application that needs anonymous networking. Libraries, services, CLI tools — all in a language that 70% of developers already know.

The Original I2P Team

This port exists because of the people who built I2P in the first place.

jrandom designed the original architecture and wrote much of the initial codebase. zzz has been the project's backbone for over a decade — maintaining the router, reviewing patches, keeping the network running through every challenge. str4d contributed critical cryptographic work and protocol improvements.

The I2P community has maintained this infrastructure for twenty years. They did it without venture funding, without a token sale, without hype cycles. The Java I2P core — i2p.jar, router.jar, SAM, streaming — is released into the public domain. That's an extraordinary gift. Every line of this Python port exists because they wrote the specification and the reference implementation first.

We owe them everything. This is a port built on their shoulders.

dollspace-gay

dollspace-gay's contributions to the I2P ecosystem deserve specific recognition. Their work on I2P tooling, community engagement, and documentation has helped make I2P more accessible to developers who aren't steeped in the project's two-decade history. The kind of bridge-building work that makes ecosystems thrive.

Claude

Let's be direct about this: significant portions of i2p-python were generated by Claude, Anthropic's AI assistant. Not as a novelty. As a core contributor.

Claude wrote crypto implementations that pass byte-identical parity tests against Java reference vectors. It generated security audits that found real timing-attack vulnerabilities and nonce overflow bugs. It produced 3,240+ tests. It built the cross-platform packaging infrastructure — deb, rpm, Windows exe — from scratch.

The collaboration model was human direction + AI implementation. A human decided what to build and why. Claude figured out how and did the work. This is what made a port of this scale feasible for a small team — the kind of project that would normally require a dozen engineers and a year of work.

The bimo.studio System

i2p-python wasn't built by hand in a text editor. It was built by bimo.studio — an autonomous development platform that orchestrates the entire software delivery lifecycle.

At the center is Chainlink, a VDD (Verification-Driven Development) pipeline that enforces a strict progression: specification, tests, implementation, gates. No code ships without passing automated verification. No tier advances without its prerequisites proven.

The I2P port was organized into 20 tiers of dependencies — from foundational utilities (Tier 0) through crypto primitives (Tiers 1-5), data structures (Tiers 6-9), transports (Tiers 12-14), up to the full router (Tier 17). Each tier's packages had to pass parity tests against the Java reference before the next tier could begin.

PolyPort: The Polyglot Engine

PolyPort is the porting subsystem that made the Java-to-Python translation tractable. It's a general-purpose tool — not specific to I2P or to Java/Python — designed to port any codebase between any language pair.

The Java I2P source was ingested into a pgvector semantic database: 40,340 code chunks from 1,920 files across 179 packages. PolyPort queries this database to find the relevant Java source for each Python module being implemented, generates test vectors from the Java reference, scaffolds the Python package structure, and orchestrates the TDD cycle.

This isn't a transpiler. It doesn't do line-by-line translation. It understands the intent of the Java code and produces idiomatic Python that achieves the same result — verified by byte-identical parity tests.

By The Numbers

Every crypto primitive — AES-256-CBC, ChaCha20-Poly1305, Ed25519, X25519, ElGamal, DSA, HKDF, HMAC-SHA256, SipHash, ML-KEM (post-quantum) — passes parity tests against Java reference vectors. The NTCP2 transport completes Noise XK handshakes with live Java I2P peers. The SAM v3 bridge implements the full session/stream/datagram protocol.

What's Next

Ethereum ENR integration. An EIP draft proposes adding an "i2p" key to Ethereum Node Records — 32 bytes that replace your cleartext IP with an I2P destination hash. i2p-python provides the stack that makes this work.

Live network testing. Extended participation on the I2P network to validate tunnel building, relay performance, and interoperability at scale.

Performance benchmarking. Profiling against the Java implementation to identify and close performance gaps in the Python port.

Post-quantum readiness. ML-KEM (Kyber) is already implemented. As the I2P protocol evolves its post-quantum migration, this implementation will track it.

Credits