living-web-sync-iroh

A sync module for the Living Web that implements the GraphSyncModule interface from Spec 03, using Iroh for QUIC-native P2P transport with NAT traversal.

Overview

This is the more capable of two sync module implementations (the other being living-web-sync-websocket which uses a WebSocket relay). Key advantages:

• NAT traversal — Iroh punches through NATs for direct peer-to-peer connections
• Peer discovery — Gossip-based discovery, no centralized relay needed
• Direct connections — After discovery, data flows peer-to-peer (relay only for initial handshake)
• Connection migration — QUIC handles network changes (WiFi → cellular) without dropping

Architecture

Two build targets with a transport abstraction layer:

Target	Transport	Discovery	Use case
WASM (wasm32-unknown-unknown)	WebTransport API	Relay-assisted topic rooms	Browser polyfill
Native	iroh-net QUIC	iroh-gossip	Chromium browser process, server

The GraphSyncModule interface is identical across both targets — they are interchangeable with living-web-sync-websocket.

WASM Compatibility

Iroh's Rust crates (iroh, iroh-net) depend on tokio, socket2, and native networking — they don't compile to wasm32-unknown-unknown. The WASM build uses the browser's WebTransport API as the QUIC transport, connecting to an Iroh relay/bridge server that handles the actual Iroh networking.

Content Addressing

The WASM binary hash is used in graph URIs, ensuring the exact sync logic is verifiable:

living://<graph-hash>?sync=iroh&module=sha256:<wasm-hash>

Build

# WASM build (for browser polyfill)
wasm-pack build --target web --release

# Native build (for Chromium browser process)
cargo build --release

# Run tests
cargo test

GraphSyncModule Interface

IrohSyncModule::new()
    .init(config_json)
    .connect(graph_uri, local_did)
    .commit(diff_json) -> revision
    .request_sync(from_revision)
    .peers() -> JSON
    .online_peers() -> JSON
    .send_signal(remote_did, payload)
    .validate(diff_json, author) -> JSON
    .current_revision() -> Option<String>
    .disconnect()
    .shutdown()

OR-Set CRDT

Uses an add-wins Observed-Remove Set for conflict-free graph synchronization. The CRDT implementation is transport-independent and identical to the WebSocket module.

License

MIT