History Subsystem Technical Summary

Overview

The history subsystem is responsible for storing and retrieving historical records in long-term public archives. It handles two forms of data:

1. Buckets from the BucketList — checkpoints of full ledger state.
2. History blocks — sequential logs of ledger headers, transactions, and transaction results.

Checkpoints occur every 64 ledgers (or 8 when ARTIFICIALLY_ACCELERATE_TIME_FOR_TESTING is set). A checkpoint is identified by the last ledger in its range. The first checkpoint covers ledgers [1, 63]; subsequent ones cover [K*64, (K+1)*64 - 1]. Archives are served over HTTP with the root state at .well-known/stellar-history.json. Per-checkpoint files use 3-level hex directory prefixes (e.g., ledger/12/34/56/ledger-0x12345677.xdr.gz).

Key Classes and Data Structures

HistoryManager (abstract base, HistoryManager.h)

Abstract interface for the history subsystem. Provides: