Skip to content

Add Iroh P2P transport for private remote connectivity - #1311

Open
rueckwaerts wants to merge 13 commits into
romanz:masterfrom
rueckwaerts:iroh-transport-clean
Open

Add Iroh P2P transport for private remote connectivity#1311
rueckwaerts wants to merge 13 commits into
romanz:masterfrom
rueckwaerts:iroh-transport-clean

Conversation

@rueckwaerts

Copy link
Copy Markdown

Summary

Adds an optional Iroh QUIC P2P transport to electrs, allowing wallet software to connect directly to a home node from anywhere in the world — without TCP port forwarding, Tor, or VPN.

The user only needs to know the server's Iroh Node ID (a 64-char hex string). NAT traversal is handled automatically.

Motivation

Users running electrs at home (Start9, Umbrel, RaspiBlitz, bare metal) currently have no good option for remote access:

  • Open router ports — security risk, not always possible
  • Tor — slow, complex setup, not reliable on mobile
  • VPN — requires a VPS or complex router config

This is a real barrier for anyone who wants to use their own node from outside their home network.

Iroh solves this cleanly: the relay is only used for the initial handshake (NAT traversal). Once connected, traffic flows peer-to-peer, end-to-end encrypted via QUIC/TLS. The relay never sees payload content.

Notably, Fedimint — a well-known Bitcoin privacy project — uses Iroh for exactly this reason: P2P connectivity between guardians without infrastructure overhead. This validates Iroh as a production-ready choice for Bitcoin-related software.

Changes

  • src/iroh_listener.rs — new Iroh listener (accepts incoming QUIC connections, pipes to existing recv_loop)
  • src/server.rspub fn recv_loop (no logic change, visibility only)
  • src/lib.rsiroh_listener module included behind iroh feature flag
  • Cargo.toml — optional iroh feature: cargo build --release --features iroh

Configuration

Secret key path defaults to ~/.electrs/iroh_secret_key.bin, configurable via:

--iroh-secret-key-path <PATH>

The Node ID is printed to logs on startup — no file write required.

ALPN

b"electrs/electrum/0"

Testing

Tested end-to-end from outside home network, against electrs on Start9:

  • Sparrow Wallet → Iroh relay → electrs: Connected to electrs/0.11.1 on protocol version 1.4 ✓
  • Electrum → Iroh relay → electrs ✓

Client-side bridge: https://github.com/rueckwaerts/iroh-electrum-bridge
Sparrow integration PR: sparrowwallet/sparrow#2021
Electrum integration PR: spesmilo/electrum#10695

Feature Flag

Iroh support is fully opt-in and does not affect existing builds:

cargo build --release                          # unchanged
cargo build --release --features iroh          # with Iroh support

@rueckwaerts rueckwaerts changed the title Add Iroh P2P transport for private remote connectivityIroh transport clean Add Iroh P2P transport for private remote connectivity Jun 15, 2026
@romanz romanz added the iroh label Jun 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants