Overview

Relevant source files

• docs/metrics.md
• docs/stellar-core_example.cfg
• src/bucket/test/BucketTestUtils.cpp
• src/bucket/test/BucketTestUtils.h
• src/herder/Herder.cpp
• src/herder/Herder.h
• src/herder/HerderImpl.cpp
• src/herder/HerderImpl.h
• src/herder/TransactionQueue.cpp
• src/herder/TransactionQueue.h
• src/herder/test/HerderTests.cpp
• src/herder/test/TestTxSetUtils.cpp
• src/herder/test/TestTxSetUtils.h
• src/herder/test/TransactionQueueTests.cpp
• src/herder/test/TxSetTests.cpp
• src/ledger/LedgerManager.h
• src/ledger/LedgerManagerImpl.cpp
• src/ledger/LedgerManagerImpl.h
• src/main/Application.cpp
• src/main/Application.h
• src/main/ApplicationImpl.cpp
• src/main/ApplicationImpl.h
• src/main/CommandHandler.cpp
• src/main/CommandHandler.h
• src/main/Config.cpp
• src/main/Config.h
• src/overlay/OverlayMetrics.cpp
• src/overlay/OverlayMetrics.h
• src/test/test.cpp
• src/test/test.h

Purpose and Scope

This document provides a high-level introduction to stellar-core, the reference implementation of the Stellar network protocol. It covers the major architectural components, their relationships, and how they map to code entities within the codebase. This page serves as an entry point for understanding stellar-core's design before diving into specific subsystems.

For detailed information about specific subsystems, see:

• Core application lifecycle and configuration: Core Application
• Consensus protocol implementation: Consensus System
• Network communication: Peer-to-Peer Networking
• State management: Ledger Management
• Transaction processing: Transaction Processing
• Smart contract execution: Soroban Smart Contracts

Sources: src/main/ApplicationImpl.cpp1-100 src/main/Config.h1-80 docs/stellar-core_example.cfg1-120

What is Stellar-Core

Stellar-core is a replicated state machine that maintains a distributed ledger through the Stellar Consensus Protocol (SCP). Each instance of stellar-core:

• Participates in consensus to agree on transaction sets
• Applies validated transactions to update ledger state
• Maintains ledger history in bucket lists and SQL databases
• Communicates with peer nodes over TCP
• Publishes ledger snapshots to history archives
• Executes Soroban smart contracts

The codebase is organized around a main Application class that coordinates several manager subsystems, each responsible for a distinct concern.

Sources: src/main/ApplicationImpl.cpp86-209 src/main/Application.h1-50

Major Subsystems

The architecture follows a layered design where ApplicationImpl acts as the central coordinator, instantiating and managing lifecycle for all major subsystems. Each subsystem exposes an interface and interacts with others through well-defined boundaries.

Sources: src/main/ApplicationImpl.cpp241-344 src/main/ApplicationImpl.h1-100

Core Components

ApplicationImpl

ApplicationImpl is the root object that owns and coordinates all subsystems. It manages:

• Configuration: Loaded from TOML via Config class
• Threading: Main thread plus worker, overlay, eviction, and apply threads
• I/O Context: Separate asio::io_context instances for different thread types
• Component Lifecycle: Initialization, startup, graceful shutdown

Key members include mVirtualClock for event scheduling, mDatabase for SQL persistence, mBucketManager for state snapshots, mHerder for consensus, mLedgerManager for state transitions, and mOverlayManager for networking.

Sources: src/main/ApplicationImpl.cpp86-209 src/main/ApplicationImpl.h24-100

Config

The Config class holds all configuration parameters loaded from stellar-core.cfg. Major configuration categories:

Category	Key Settings	Description
Network	NETWORK_PASSPHRASE, NODE_SEED	Network identity and node keypair
Consensus	QUORUM_SET, VALIDATORS	SCP quorum configuration
Networking	PEER_PORT, TARGET_PEER_CONNECTIONS	P2P overlay settings
Database	DATABASE	PostgreSQL or SQLite connection string
Storage	BUCKET_DIR_PATH, ENTRY_CACHE_SIZE	Bucket storage and caching
HTTP	HTTP_PORT, HTTP_QUERY_PORT	Command and query endpoints
Protocol	LEDGER_PROTOCOL_VERSION	Protocol version to use

Sources: src/main/Config.h72-400 src/main/Config.cpp125-374 docs/stellar-core_example.cfg1-300

HerderImpl

HerderImpl orchestrates the Stellar Consensus Protocol. It:

• Maintains a TransactionQueue for pending transactions
• Drives the SCP state machine via HerderSCPDriver
• Manages PendingEnvelopes to track SCP messages
• Coordinates with LedgerManager when consensus externalizes values
• Handles transaction flooding and demand across the network

The Herder state machine transitions between HERDER_BOOTING_STATE, HERDER_SYNCING_STATE, and HERDER_TRACKING_NETWORK_STATE based on sync status.

Sources: src/herder/HerderImpl.cpp89-117 src/herder/HerderImpl.h37-100

LedgerManagerImpl

LedgerManagerImpl manages ledger state and coordinates ledger close. Core responsibilities:

• Applies transaction sets to advance ledger state
• Manages ApplyState which encapsulates in-memory Soroban state and module cache
• Coordinates parallel Soroban transaction execution
• Commits state changes to BucketManager and Database
• Publishes LedgerCloseMeta for downstream consumers
• Maintains mLastClosedLedgerState with bucket snapshots

The manager transitions between LM_BOOTING_STATE, LM_SYNCED_STATE, and LM_CATCHING_UP_STATE.

Sources: src/ledger/LedgerManagerImpl.cpp333-405 src/ledger/LedgerManagerImpl.h58-150

OverlayManager and TCPPeer

The overlay network manages peer-to-peer connections:

• OverlayManager maintains authenticated and pending peer lists
• TCPPeer handles individual TCP connections with authentication flow
• FlowControl implements backpressure and capacity management
• Messages are flooded or pulled based on message type and flow control state

Connection establishment follows: TCP connect → HELLO exchange → AUTH verification → authenticated state.

Sources: src/overlay/Peer.cpp134-158 src/overlay/TCPPeer.cpp34-110 src/overlay/Peer.h67-130

BucketManager

BucketManager maintains two bucket lists as Merkle trees:

• Live BucketList: Current ledger state (11 levels)
• Hot Archive BucketList: Evicted/expired state (11 levels)

Buckets are immutable, content-addressed .xdr.gz files. The bucket list structure enables efficient state snapshots and catchup. Each ledger close adds entries to level 0, with periodic merges into higher levels following an exponential schedule.

Sources: src/bucket/BucketManager.h1-100 src/ledger/LedgerManagerImpl.cpp470-487

Key Code Entities

This diagram traces the critical path from startup through consensus to state commitment, using actual function names from the codebase.

Sources: src/main/main.cpp1-50 src/main/ApplicationImpl.cpp240-345 src/herder/HerderImpl.cpp236-502 src/ledger/LedgerManagerImpl.cpp505-750

Transaction Lifecycle (High Level)

A transaction flows through multiple stages from submission to finalization:

1. Submission: Received via HTTP or overlay network
2. Queue Validation: TransactionQueue::tryAdd() validates basic requirements
3. SCP Nomination: Herder nominates transaction set for consensus
4. Consensus: Network agrees on transaction set hash via SCP ballot protocol
5. Externalization: Herder::valueExternalized() triggered when consensus reached
6. Application: LedgerManager::closeLedger() applies transactions
   • Classic transactions: Sequential application
   • Soroban transactions: Parallel execution across stages
7. State Commitment: Changes written to bucket list and database
8. Meta Publishing: LedgerCloseMeta emitted to stream

For detailed transaction processing, see Transaction Flow End-to-End.

Sources: src/herder/HerderImpl.cpp596-660 src/herder/TransactionQueue.cpp1-100 src/ledger/LedgerManagerImpl.cpp800-1200

Threading Architecture

Thread types are tracked in ApplicationImpl::mThreadTypes map. The main thread handles coordination and must not block. CPU-intensive or I/O-bound work is posted to appropriate thread pools. Thread safety is maintained through message passing and careful phase management during ledger close.

Sources: src/main/ApplicationImpl.cpp167-207 src/main/ApplicationImpl.h90-130 src/ledger/LedgerManagerImpl.h90-150

Configuration and Startup

Stellar-core initialization sequence:

1. Parse Config: Load stellar-core.cfg via Config::load()
2. Initialize Application: Construct ApplicationImpl with config
3. Create Subsystems: Initialize database, bucket manager, overlay, herder, ledger manager
4. Load State:
   • New network: LedgerManager::startNewLedger() creates genesis
   • Existing network: LedgerManager::loadLastKnownLedger() restores from DB
5. Start Threads: Spawn worker, eviction, overlay, and apply threads
6. Join Network: Connect to peers, participate in consensus
7. HTTP Server: Start command and query HTTP endpoints

The config file format is TOML with sections for database, networking, consensus, and operational settings.

Sources: src/main/main.cpp1-100 src/main/ApplicationImpl.cpp240-345 src/main/Config.cpp830-876 src/ledger/LedgerManagerImpl.cpp408-502 docs/stellar-core_example.cfg1-120

State Management Architecture

Stellar-core maintains ledger state across multiple layers:

Layer	Component	Purpose
In-Memory	InMemorySorobanState	Hot cache for contract data and code
Module Cache	SharedModuleCache	Compiled WASM modules per protocol
Transaction	LedgerTxn	Transactional snapshot isolation layer
Entry Cache	LedgerTxnRoot	LRU cache of ledger entries
Bucket List	BucketManager	Merkle tree snapshots (Live + Hot Archive)
SQL Database	Database	Persistent storage (PostgreSQL/SQLite)

Reads flow from top to bottom: check cache → check bucket list → query database. Writes accumulate in LedgerTxn and flush to bucket list and database on commit.

Sources: src/ledger/LedgerManagerImpl.h117-240 src/ledger/LedgerTxn.cpp1-100 src/bucket/BucketManager.h1-100

Next Steps

After understanding this overview, dive into specific subsystems:

• Application internals: Application Lifecycle, Multi-Threading Architecture
• Consensus details: Herder State Machine, SCP Message Processing
• Network protocol: Overlay Manager and Peer Management, Flow Control
• State management: Ledger Close Pipeline, Bucket List Architecture
• Transaction handling: Transaction Framework, Parallel Transaction Application
• Smart contracts: InvokeHostFunction Execution, Resource Metering