Overlay Subsystem — Technical Summary

Overview

The overlay subsystem implements stellar-core's peer-to-peer network layer. It manages TCP connections to other nodes, authenticates peers via ECDH+HMAC, floods broadcast messages (transactions, SCP messages) across the network, fetches missing data (tx sets, quorum sets) via anycast requests, and performs network surveys. The subsystem supports optional background thread processing for I/O-heavy operations (reads/writes on TCP sockets) to keep the main thread responsive.

Key Files

• OverlayManager.h / OverlayManagerImpl.h/.cpp — Central manager; owns peer lists, Floodgate, TxDemandsManager, SurveyManager, PeerManager, PeerAuth, PeerDoor.
• Peer.h / Peer.cpp — Abstract base class for a connected peer; handles message dispatch, HMAC auth, flow control, pull-mode adverts.
• TCPPeer.h / TCPPeer.cpp — Concrete Peer subclass; async TCP read/write via Asio, framing with RFC5531 record marking.
• FlowControl.h / FlowControl.cpp — Per-peer flow control for flood traffic; outbound queuing with priority and load shedding.
• FlowControlCapacity.h / FlowControlCapacity.cpp — Tracks message-count and byte-count capacity for reading/writing flood data.
• Floodgate.h / Floodgate.cpp — Tracks which peers have seen which broadcast messages; ensures each message is sent/received at most once per peer.
• ItemFetcher.h / ItemFetcher.cpp — Manages anycast fetch requests for tx sets and quorum sets via Tracker instances.
• Tracker.h / Tracker.cpp — Tracks a single fetch request; tries peers sequentially with timeout-based retries.
• TxAdverts.h / TxAdverts.cpp — Per-peer incoming/outgoing transaction hash advertisement queues (pull mode).
• TxDemandsManager.h / TxDemandsManager.cpp — Global transaction demand scheduling; issues FLOOD_DEMAND messages based on received adverts.
• PeerManager.h / PeerManager.cpp — Persists peer records (address, type, failure count, next-attempt time) in the database.