Architecture

System diagram

Role	Operated by	Participates in CDN?
Node (pure cache)	Independent node operator	Yes — stakes, gossips, probes, delivers
Node (origin-backed)	Content provider or node operator with storage	Yes — same protocol, plus a private origin backend
Client	End-user or application	Pays for bytes; subscribes to gossip but does not publish
App server	Content provider	No — external; rides the same QUIC transport but does not gossip, probe, or stake
Watchtower	Independent watchtower operator	Semi-participant — monitors channel disputes on behalf of nodes

See Participants for a deeper breakdown per role.

Client bootstrap — client generates an iroh key, queries the on-chain registry, seeds a peer table, and subscribes to regional + global gossip topics (bootstrap).
Discovery — client asks its known peers cdn/probe/v1 for a blob hash. On miss, any peer performs a cdn/dht/v1 FIND_VALUE to locate holders (content discovery).
Selection — returned candidates are scored by rate_per_mb × rtt_ms × (1 / max(reputation, 0.1)²) — lower is better (network).
Payment channel open — client opens a payment channel in an allowlisted ERC-20 with the selected node on-chain (payments).
Streaming + vouchers — node streams via cdn/client/v1; client signs EIP-712 vouchers per configurable cadence (default 1 MB) (payments).
Cache-miss fan-out — if the node doesn’t have the blob, it performs its own probe/pull from another peer via cdn/client/v1 (paid). Every byte delivered in the network is paid (wire protocol).
Channel close — either party initiates settlement on-chain. Watchtowers (watchtower) monitor for stale closes during the dispute window.

No external origin URL exists — content enters the network through origin-backed nodes whose backends are hidden.
A node cannot earn without delivering verifiable bytes — BLAKE3 hash mismatch voids payment.
A node cannot join the mesh without staking — StakingRegistry enforces stake >= minStake before accepting a registerNode call.
A node cannot register a NodeId it does not control — ed25519 signature verification prevents squatting.
Safety bounds on all governable parameters are hardcoded — governance cannot set fees to 100% or stake to zero.
A node cannot serve a blacklisted hash after the compliance window — doing so is slashable.

Search & indexers — dedicated indexer nodes subscribe to gossip and build a searchable metadata index, exposing cdn/search/v1. Staked and slashable for fabricated results.
KV-CRDT content catalogs — iroh-docs namespaces replicate hash → metadata entries across nodes for smarter prefetching, complementing the DHT.
Parallel streaming from multiple nodes — the protocol already supports it; not prioritized.