alknet/docs/research/references/iroh/iroh-gossip/README.md

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 PublicKey in the net layer)
• PeerData: Opaque bytes exchanged on join (carries AddrInfo in 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)