How Iroh Manages Data Synchronization: CRDT Replication Over QUIC

Iroh manages data synchronization through a peer-to-peer CRDT-style replication protocol that operates over QUIC connections, utilizing document-level stores with content-addressed blobs and gossip-based peer discovery to propagate changes efficiently across NATs and firewalls without central coordination.

The n0-computer/iroh repository implements a sophisticated data synchronization layer in its core iroh crate. This system enables distributed applications to maintain consistent mutable key-value stores across peers using conflict-free replicated data types (CRDTs) and efficient content hashing.

The iroh-sync Engine Architecture

At the heart of Iroh's synchronization capabilities lies the iroh-sync engine, which implements a peer-to-peer replication protocol. The engine coordinates document-level stores where each document represents a mutable key-value collection backed by content-addressed blob storage.

Document Stores and CRDT Semantics

Each document in Iroh functions as a mutable key-value store backed by the iroh-blobs content-addressed storage system. When changes occur, the sync engine records them as entries containing the author's public key, a monotonically increasing name-stamp, and a timestamp. This structure ensures that concurrent modifications converge correctly without requiring centralized consensus.

The document store implementation resides in iroh/src/sync/mod.rs, where the engine manages the replication state machine and coordinates with the underlying storage layer.

Content-Addressed Blob Propagation

Iroh leverages content addressing for all synchronized data. When a peer learns about new blob hashes through the sync protocol, it requests missing blobs from peers that already hold them. The sync engine tracks content hashes per document and iterates over them efficiently to stream data to remote peers.

This approach ensures bandwidth-efficient synchronization, as peers only transfer data they don't already possess, deduplicated by hash.

Peer Discovery and Gossip Protocol

The synchronization layer relies on a lightweight gossip subsystem to advertise document availability and negotiate sync sessions. This eliminates the need for static peer configurations or centralized registries.

Peer Data and Neighbor Events

According to the CHANGELOG.md evolution of the protocol, the gossip layer propagates two critical data structures: peer data (the set of peers aware of a specific document) and neighbor events that drive the sync engine's state machine. These mechanisms enable dynamic peer discovery and efficient sync session initiation.

The gossip protocol implementation integrates with the sync actor in iroh/src/sync/mod.rs, processing incoming peer announcements and triggering appropriate sync actions.

Content-Hash Tracking

The sync engine maintains efficient iterators over content hashes for each document store. As documented in the changelog improvements, these iterators allow the engine to quickly determine which hashes need synchronization when establishing connections with new peers, minimizing handshake overhead.

Connection Management and Network Traversal

Iroh's data synchronization operates over QUIC connections established by the core Iroh endpoint, with sophisticated handling for network obstacles like NATs and firewalls.

QUIC Hole-Punching and Relay Fallback

Connections initially attempt direct QUIC hole-punching between peers. When direct connections fail, Iroh automatically falls back to the public relay network, using the same mechanism as standard QUIC traffic. This fallback is handled in iroh/src/endpoint/bind.rs and iroh/src/address_lookup/pkarr.rs, which manages public-relay address lookup.

Once a QUIC connection is established, the sync actor attaches immediately to the channel, allowing the sync protocol to begin without additional handshake delays.

Sync Actor Lifecycle

The synchronization lifecycle is managed by dedicated sync actors. As implemented in the core sync module, these actors start when a document opens and shut down cleanly when the Iroh node exits. The system automatically prunes inactive replicas and supports read-only replicas that don't require pulling full blob history, optimizing resource usage for large documents.

Implementation in the Source Code

The data synchronization system spans several key files in the n0-computer/iroh repository:

• iroh/src/sync/mod.rs: Contains the core SyncEngine implementation, gossip handling, and document store coordination
• iroh/src/endpoint/quic.rs: Manages QUIC connection handling that underpins all peer-to-peer sync traffic
• iroh/src/endpoint/bind.rs: Handles endpoint creation and hole-punching logic for NAT traversal
• iroh/src/address_lookup/pkarr.rs: Implements public-relay address lookup for fallback connectivity

Practical Example: Setting Up Document Synchronization

The following example demonstrates how to initialize the sync engine using the public API from the iroh crate:

use iroh::sync::{self, SyncEngine};
use iroh::doc::Document;
use iroh::endpoint::Endpoint;
use std::sync::Arc;

// 1. Create a QUIC endpoint that will be used for all connections.
let endpoint = Endpoint::bind().await?;

// 2. Open (or create) a document that we want to keep in sync.
let doc = Document::open("my-doc").await?;

// 3. Build the sync engine – it automatically discovers peers via gossip.
let sync = SyncEngine::builder()
    .endpoint(endpoint.clone())
    .document(doc.clone())
    .build()
    .await?;

// 4. Start the sync engine (runs in the background).
let sync_handle = sync.spawn();

// 5. Write a value to the document; the sync engine will propagate it.
doc.put("hello", b"world").await?;

// 6. Later we can shut down the engine cleanly.
sync_handle.shutdown().await?;

This workflow illustrates the three essential steps: endpoint creation, document opening, and sync engine instantiation. Once running, the engine automatically propagates changes to peers that have announced interest in the same document identifier.

Summary

• Iroh implements CRDT-based data synchronization through the iroh-sync engine, enabling conflict-free concurrent edits across distributed peers.
• Document-level stores use content-addressed blobs (iroh-blobs) with entries containing author keys and timestamps to ensure consistency.
• Gossip-based discovery propagates peer data and neighbor events, eliminating the need for centralized coordination servers.
• Network resilience is achieved through QUIC hole-punching with automatic relay fallback, managed in iroh/src/endpoint/bind.rs.
• Resource efficiency comes from content-hash deduplication, incremental sync, and support for read-only replicas without full history.

Frequently Asked Questions

How does Iroh handle conflicts during data synchronization?

Iroh uses CRDT (Conflict-free Replicated Data Type) semantics where each entry includes the author's public key, a monotonically increasing name-stamp, and a timestamp. When peers synchronize, these metadata fields ensure that concurrent modifications converge deterministically without requiring locks or centralized conflict resolution.

What happens if two peers cannot establish a direct connection?

If direct QUIC hole-punching fails, Iroh automatically falls back to the public relay network. The iroh/src/endpoint/bind.rs and iroh/src/address_lookup/pkarr.rs modules handle this fallback by looking up relay addresses and tunneling traffic through the relay infrastructure while maintaining the same sync protocol semantics.

Can I synchronize only specific parts of a document without downloading the entire history?

Yes. Iroh supports read-only replicas that can be created without pulling the full blob history. The sync engine in iroh/src/sync/mod.rs tracks content hashes per document and allows peers to request only specific blobs they need, while inactive replicas are automatically pruned to conserve resources.

How does the sync engine know which peers to contact for a specific document?

The engine uses a gossip-based discovery layer that propagates peer data—sets of peers known to hold specific documents. When a document is opened, the sync actor listens for gossip announcements about that document identifier and initiates sync sessions with discovered peers over existing QUIC connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}