Catchup Subsystem — Technical Summary

The catchup subsystem in stellar-core is responsible for synchronizing a node's local ledger state with the rest of the network when it falls behind. It downloads historical data (ledger headers, transactions, and bucket snapshots) from history archives, verifies integrity, and applies the data to bring the node up to date.

All files reside in src/catchup/.

Key Classes and Data Structures

CatchupConfiguration

File: CatchupConfiguration.h/.cpp

Immutable configuration describing a catchup request. Parameterized by:

• toLedger — destination ledger number (or CURRENT = 0 to resolve at runtime from the archive).
• count — number of ledgers to replay before the destination. 0 = minimal (buckets only), UINT32_MAX = complete history.
• Mode — one of OFFLINE_BASIC, OFFLINE_COMPLETE, or ONLINE.