iroh-gossip Reference Documentation
This directory contains a deep-dive reference on how the iroh-gossip crate works, based on source code analysis of the repository at /workspace/iroh-gossip.
Documents
| # | File | Topic |
|---|---|---|
| 01 | Overview & Architecture | Crate structure, module organization, design principles, features, dependencies |
| 02 | HyParView Membership | Swarm membership protocol: active/passive views, join procedure, shuffle mechanism, failure recovery, PeerData |
| 03 | PlumTree Broadcast | Epidemic broadcast trees: eager/lazy push, Graft/IHave/Prune, tree optimization, message deduplication, cache management |
| 04 | State & Topic Coordination | Multi-topic state management, topic lifecycle, event routing between HyParView and PlumTree |
| 05 | Net Actor & Networking | Actor model, event loop, connection management, Dialer, wire protocol, address lookup, topic state in the net layer |
| 06 | API & Data Flow | Public API types, subscription model, event/command flow, channel architecture, configuration defaults |
| 07 | Utilities & Wire Format | IndexSet, TimerMap, TimeBoundCache, serialization, PeerData/AddrInfo, Dialer internals |
| 08 | Testing & Metrics | Test infrastructure, simulation, key test patterns, metrics, references |
Quick Reference
Version
iroh-gossip v0.97.0
ALPN
/iroh-gossip/1
Core Protocols
- HyParView: Hybrid partial view membership (active view = 5, passive view = 30 by default)
- PlumTree: Epidemic broadcast trees (eager + lazy push with Graft/IHave optimization)
Key Abstractions
- TopicId: 32-byte identifier for a topic/swarm
- PeerIdentity: Generic trait (instantiated as
PublicKeyin the net layer) - PeerData: Opaque bytes exchanged on join (carries
AddrInfoin net layer) - IO trait: Interface for protocol output events (pure state machine, no IO)
Wire Format
- Postcard (serde) encoding over QUIC unidirectional streams
- Length-prefixed frames (u32 length + postcard payload)
- Stream header with TopicId
- Max message size: 4096 bytes (configurable, minimum 512)