How solana-labs/solana works
1. Purpose and scope
Archived reference implementation of the Solana validator and its surrounding Rust workspace. It implements a high-throughput, proof-of-stake blockchain node, client/CLI tooling, SDKs, built-in on-chain programs, local testing, and operational deployment utilities. The active successor is Agave, per README.md.
2. Primary entry points
• Validator process: validator/src/main.rs, with node bootstrap and operator CLI in validator/src/bootstrap.rs and validator/src/cli.rs.
• Local single-node validator: validator/src/bin/solana-test-validator.rs.
• User-facing command-line client: cli/src/main.rs, with command dispatch in cli/src/cli.rs.
• Genesis creation and ledger inspection: genesis/src/main.rs, ledger-tool/src/main.rs.
• Workspace composition and crate dependency boundaries: Cargo.toml.
3. Validator orchestration and network ingress
The validator composes transaction processing (TPU), validation/replay (TVU), gossip, RPC, persistence, and background services. Core lifecycle and service wiring reside in core/src/validator.rs; TPU and TVU pipelines are represented by core/src/tpu.rs and core/src/tvu.rs.
Inbound client transactions enter fetch/signature-verification/banking stages. core/src/fetch_stage.rs, core/src/sigverify_stage.rs, and core/src/banking_stage.rs form the principal execution ingress. Banking includes account-lock-aware, priority-based scheduling under core/src/banking_stage/transaction_scheduler/prio_graph_scheduler.rs.
Networking is split from consensus/execution: packet and QUIC/UDP transport are in streamer/src/lib.rs and streamer/src/quic.rs; cluster membership and CRDS gossip are in gossip/src/cluster_info.rs and gossip/src/gossip_service.rs.
4. Execution, state, and built-in programs
The runtime executes sanitized transactions against a Bank, applying fees, account changes, program invocation, and commitment state. Key boundaries are runtime/src/bank.rs, svm/src/transaction_processor.rs, and program-runtime/src/invoke_context.rs.
Persistent account state is owned by AccountsDB, which separates account caches, indexes, append-vector storage, hash verification, and snapshot-oriented persistence: accounts-db/src/accounts_db.rs, accounts-db/src/accounts_index.rs, and accounts-db/src/append_vec.rs.
Native programs define protocol-level instruction semantics, including system transfers, staking, voting, loaders, and address lookup tables: programs/system/src/system_processor.rs, programs/stake/src/lib.rs, and programs/bpf_loader/src/lib.rs. SBF program execution is an explicit sandbox boundary through loader syscalls and serialization.
5. Ledger, consensus, and block propagation
Ledger storage persists shreds, slot metadata, and blockstore state, then reconstructs/consumes blocks: ledger/src/blockstore.rs, ledger/src/blockstore_processor.rs, and ledger/src/shred.rs.
Proof of History services produce and record slot timing/entries via poh/src/poh_service.rs and poh/src/poh_recorder.rs. Leader output is shredded and propagated through Turbine broadcast/retransmission: turbine/src/broadcast_stage.rs and turbine/src/retransmit_stage.rs.
Replay validates ledger data into bank forks; consensus selects forks and tracks votes/tower state: core/src/replay_stage.rs, core/src/consensus.rs, and core/src/consensus/heaviest_subtree_fork_choice.rs. Repair services recover missing ledger data from peers under core/src/repair/repair_service.rs.
6. External-facing APIs and clients
RPC exposes account, transaction, subscription, health, and cluster views over the validator’s bank/ledger state: rpc/src/rpc_service.rs, rpc/src/rpc.rs, and rpc/src/rpc_pubsub_service.rs. Client libraries provide HTTP RPC plus direct TPU submission over QUIC/UDP: rpc-client/src/rpc_client.rs, client/src/tpu_client.rs, and client/src/nonblocking/quic_client.rs.
The public SDK defines transactions, messages, accounts, keys, signatures, and protocol data types shared across clients and nodes: sdk/src/lib.rs, sdk/src/transaction/mod.rs, and sdk/program/src/lib.rs.
7. Operations and infrastructure
Material runtime dependencies include Rust, native TLS/OpenSSL and protobuf tooling, optional GPU/performance libraries, disk-backed account and ledger storage, UDP/QUIC networking, and RocksDB-backed ledger components. Optional integrations include Google Cloud Bigtable archival access/upload through storage-bigtable/src/bigtable.rs and ledger/src/bigtable_upload.rs.
Metrics instrumentation is centralized in metrics/src/lib.rs; dashboards/scripts target InfluxDB and Grafana in metrics/scripts/start.sh. Cluster provisioning and remote-node operations support AWS, Azure, GCE, and colocation via net/net.sh and provider scripts under net/scripts/.
Main entry points: validator.rs Validator orchestration · blockstore.rs Blockstore · bank.rs Bank and SVM · quic.rs QUIC/UDP transport
Components 22
Entry points
- Rust workspace · Defines crate composition and dependency boundaries.
Cargo.toml - Validator bootstrap
validator/src/main.rs - Local test validator
validator/src/bin/solana-test-validator.rs - User CLI
cli/src/main.rs - Genesis and ledger tools
genesis/src/main.rs
Validator pipelines
- Validator orchestration · Wires TPU, TVU, gossip, RPC, persistence, and background services.
core/src/validator.rs - TPU transaction pipeline
core/src/tpu.rs - Banking scheduler · Account-lock-aware priority scheduling and banking.
core/src/banking_stage/transaction_scheduler/prio_graph_scheduler.rs - TVU validation pipeline
core/src/tvu.rs - CRDS gossip
gossip/src/gossip_service.rs - QUIC/UDP transport
streamer/src/quic.rs
Execution and state
- Bank and SVM · Applies transaction effects, fees, invocation, and commitment state.
runtime/src/bank.rs - Program invocation · Invocation context forms the SBF/native program boundary.
program-runtime/src/invoke_context.rs - AccountsDB · Caches, indexes, append-vector storage, hashes, and snapshots.
accounts-db/src/accounts_db.rs - Built-in programs · System, stake, vote, loader, and lookup-table semantics.
programs/system/src/system_processor.rs
Ledger and consensus
- Blockstore · Stores shreds, slot metadata, and reconstructed blocks.
ledger/src/blockstore.rs - PoH and Turbine · Records slot entries, shreds leader output, and retransmits it.
poh/src/poh_service.rs - Replay and consensus · Replays ledger into bank forks and selects voting/tower state.
core/src/replay_stage.rs
APIs and operations
- RPC and PubSub · Exposes account, transaction, subscription, health, and cluster views.
rpc/src/rpc_service.rs - SDK and clients · Shared protocol types plus HTTP RPC and direct TPU submission.
sdk/src/lib.rs - Metrics and deployment · Metrics plus multi-provider cluster provisioning scripts.
metrics/src/lib.rs - Bigtable archival
storage-bigtable/src/bigtable.rs
Connections 29
- Rust workspace → Validator bootstrap: builds
- Rust workspace → User CLI: builds
- Validator bootstrap → Validator orchestration: boots
- Local test validator → Validator orchestration: local node
- User CLI → SDK and clients: uses
- SDK and clients → RPC and PubSub: HTTP RPC
- SDK and clients → QUIC/UDP transport: direct TPU
- Validator orchestration → TPU transaction pipeline: runs
- Validator orchestration → TVU validation pipeline: runs
- Validator orchestration → CRDS gossip: runs
- Validator orchestration → RPC and PubSub: serves
- QUIC/UDP transport → TPU transaction pipeline: client packets
- TPU transaction pipeline → Banking scheduler: verified transactions
- Banking scheduler → Bank and SVM: executes
- Bank and SVM → Program invocation: invokes programs
- Program invocation → Built-in programs: native instructions
- Bank and SVM → AccountsDB: reads and writes accounts
- Banking scheduler → PoH and Turbine: leader entries
- PoH and Turbine → Blockstore: shreds and slots
- PoH and Turbine → QUIC/UDP transport: Turbine propagation
- QUIC/UDP transport → Blockstore: received shreds
- Blockstore → TVU validation pipeline: ledger data
- TVU validation pipeline → Replay and consensus: validated replay
- Replay and consensus → Bank and SVM: bank forks
- RPC and PubSub → Bank and SVM: state queries
- RPC and PubSub → Blockstore: ledger queries
- Blockstore → Bigtable archival: optional archival upload
- Validator orchestration → Metrics and deployment: instrumentation
- Genesis and ledger tools → Blockstore: creates and inspects