Ledger Subsystem — Technical Summary

Overview

The ledger subsystem is the core of stellar-core's state management. It orchestrates ledger closing (applying transaction sets to produce new ledger states), manages the "last closed ledger" (LCL) state, provides a transactional in-memory layer (LedgerTxn) for reading/writing ledger entries during transaction processing, maintains in-memory Soroban contract state, manages Soroban network configuration, and produces ledger close metadata for downstream consumers (e.g., Horizon).

The subsystem has a two-thread architecture: a main thread handles consensus and publishes state, while a apply thread executes transactions and commits state. The invariant LCL <= A <= Q <= H tracks ledger progress across these threads (H=heard, Q=queued, A=applying, LCL=last closed).

Key Files

• LedgerManager.h / LedgerManagerImpl.h / LedgerManagerImpl.cpp — Abstract interface and implementation for ledger lifecycle: applying, closing, state management, parallel apply orchestration.
• LedgerTxn.h / LedgerTxnImpl.h / LedgerTxn.cpp — Nestable in-memory transactional layer over the database for ledger entries; core data mutation path.
• LedgerTxnEntry.h / .cpp — Handle types (LedgerTxnEntry, ConstLedgerTxnEntry) for accessing active entries in a LedgerTxn.
• LedgerTxnHeader.h / .cpp — Handle type for accessing the LedgerHeader within a LedgerTxn.
• LedgerTxnOfferSQL.cpp — SQL-specific bulk operations for offer entries (upsert/delete) used by LedgerTxnRoot.
• InternalLedgerEntry.h / .cpp — Extended ledger entry types (InternalLedgerEntry, InternalLedgerKey) that wrap XDR LedgerEntry/LedgerKey with additional internal-only types (sponsorship tracking, max-seq-num-to-apply).
• NetworkConfig.h / .cpp — SorobanNetworkConfig: reads/writes all Soroban-related configuration from ledger entries, provides fee and resource limit accessors.
• InMemorySorobanState.h / .cpp — InMemorySorobanState: in-memory cache of all live Soroban contract data, code, and TTL entries for fast lookups during transaction execution.
• LedgerStateSnapshot.h / .cpp — Unified read-only snapshot interfaces (LedgerSnapshot, CompleteConstLedgerState) abstracting over SQL and BucketList backends.