# solana-labs/solana architecture

> Architecture diagram of the GitHub repository solana-labs/solana, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solana-labs/solana
- Repository: https://github.com/solana-labs/solana

## Overview

#### 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: [`core/src/validator.rs`](https://github.com/solana-labs/solana/blob/master/core/src/validator.rs) (Validator orchestration), [`ledger/src/blockstore.rs`](https://github.com/solana-labs/solana/blob/master/ledger/src/blockstore.rs) (Blockstore), [`runtime/src/bank.rs`](https://github.com/solana-labs/solana/blob/master/runtime/src/bank.rs) (Bank and SVM), [`streamer/src/quic.rs`](https://github.com/solana-labs/solana/blob/master/streamer/src/quic.rs) (QUIC/UDP transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_workspace["Rust workspace<br/>[Cargo.toml]"]
  node_validator_cli["Validator bootstrap<br/>validator entry<br/>[main.rs]"]
  node_test_validator["Local test validator<br/>validator entry"]
  node_cli["User CLI<br/>client entry<br/>[main.rs]"]
  node_genesis_ledger_tools["Genesis and ledger tools<br/>operator tools<br/>[main.rs]"]
end

subgraph group_validator["Validator pipelines"]
  node_validator_core["Validator orchestration<br/>node lifecycle<br/>[validator.rs]"]
  node_tpu["TPU transaction pipeline<br/>ingress pipeline<br/>[tpu.rs]"]
  node_banking["Banking scheduler<br/>execution stage"]
  node_tvu["TVU validation pipeline<br/>replay pipeline<br/>[tvu.rs]"]
  node_gossip["CRDS gossip<br/>cluster membership<br/>[gossip_service.rs]"]
  node_transport["QUIC/UDP transport<br/>network transport<br/>[quic.rs]"]
end

subgraph group_execution["Execution and state"]
  node_bank_svm["Bank and SVM<br/>transaction execution<br/>[bank.rs]"]
  node_program_runtime["Program invocation<br/>sandbox runtime<br/>[invoke_context.rs]"]
  node_accounts_db[("AccountsDB<br/>account persistence<br/>[accounts_db.rs]")]
  node_native_programs["Built-in programs<br/>protocol programs"]
end

subgraph group_ledger["Ledger and consensus"]
  node_blockstore[("Blockstore<br/>ledger persistence<br/>[blockstore.rs]")]
  node_poh_turbine["PoH and Turbine<br/>leader propagation<br/>[poh_service.rs]"]
  node_replay_consensus["Replay and consensus<br/>fork choice<br/>[replay_stage.rs]"]
end

subgraph group_api["APIs and operations"]
  node_rpc["RPC and PubSub<br/>validator API<br/>[rpc_service.rs]"]
  node_sdk_clients["SDK and clients<br/>client libraries<br/>[lib.rs]"]
  node_metrics_ops["Metrics and deployment<br/>operations<br/>[lib.rs]"]
  node_bigtable[("Bigtable archival<br/>optional storage<br/>[bigtable.rs]")]
end

node_workspace -->|"builds"| node_validator_cli
node_workspace -->|"builds"| node_cli
node_validator_cli -->|"boots"| node_validator_core
node_test_validator -->|"local node"| node_validator_core
node_cli -->|"uses"| node_sdk_clients
node_sdk_clients -->|"HTTP RPC"| node_rpc
node_sdk_clients -->|"direct TPU"| node_transport
node_validator_core -->|"runs"| node_tpu
node_validator_core -->|"runs"| node_tvu
node_validator_core -->|"runs"| node_gossip
node_validator_core -->|"serves"| node_rpc
node_transport -->|"client packets"| node_tpu
node_tpu -->|"verified transactions"| node_banking
node_banking -->|"executes"| node_bank_svm
node_bank_svm -->|"invokes programs"| node_program_runtime
node_program_runtime -->|"native instructions"| node_native_programs
node_bank_svm -->|"reads and writes accounts"| node_accounts_db
node_banking -->|"leader entries"| node_poh_turbine
node_poh_turbine -->|"shreds and slots"| node_blockstore
node_poh_turbine -->|"Turbine propagation"| node_transport
node_transport -->|"received shreds"| node_blockstore
node_blockstore -->|"ledger data"| node_tvu
node_tvu -->|"validated replay"| node_replay_consensus
node_replay_consensus -->|"bank forks"| node_bank_svm
node_rpc -->|"state queries"| node_bank_svm
node_rpc -->|"ledger queries"| node_blockstore
node_blockstore -.->|"optional archival upload"| node_bigtable
node_validator_core -->|"instrumentation"| node_metrics_ops
node_genesis_ledger_tools -->|"creates and inspects"| node_blockstore

click node_workspace "https://github.com/solana-labs/solana/blob/master/Cargo.toml"
click node_validator_cli "https://github.com/solana-labs/solana/blob/master/validator/src/main.rs"
click node_test_validator "https://github.com/solana-labs/solana/blob/master/validator/src/bin/solana-test-validator.rs"
click node_cli "https://github.com/solana-labs/solana/blob/master/cli/src/main.rs"
click node_genesis_ledger_tools "https://github.com/solana-labs/solana/blob/master/genesis/src/main.rs"
click node_validator_core "https://github.com/solana-labs/solana/blob/master/core/src/validator.rs"
click node_tpu "https://github.com/solana-labs/solana/blob/master/core/src/tpu.rs"
click node_banking "https://github.com/solana-labs/solana/blob/master/core/src/banking_stage/transaction_scheduler/prio_graph_scheduler.rs"
click node_tvu "https://github.com/solana-labs/solana/blob/master/core/src/tvu.rs"
click node_gossip "https://github.com/solana-labs/solana/blob/master/gossip/src/gossip_service.rs"
click node_transport "https://github.com/solana-labs/solana/blob/master/streamer/src/quic.rs"
click node_bank_svm "https://github.com/solana-labs/solana/blob/master/runtime/src/bank.rs"
click node_program_runtime "https://github.com/solana-labs/solana/blob/master/program-runtime/src/invoke_context.rs"
click node_accounts_db "https://github.com/solana-labs/solana/blob/master/accounts-db/src/accounts_db.rs"
click node_native_programs "https://github.com/solana-labs/solana/blob/master/programs/system/src/system_processor.rs"
click node_blockstore "https://github.com/solana-labs/solana/blob/master/ledger/src/blockstore.rs"
click node_poh_turbine "https://github.com/solana-labs/solana/blob/master/poh/src/poh_service.rs"
click node_replay_consensus "https://github.com/solana-labs/solana/blob/master/core/src/replay_stage.rs"
click node_rpc "https://github.com/solana-labs/solana/blob/master/rpc/src/rpc_service.rs"
click node_sdk_clients "https://github.com/solana-labs/solana/blob/master/sdk/src/lib.rs"
click node_metrics_ops "https://github.com/solana-labs/solana/blob/master/metrics/src/lib.rs"
click node_bigtable "https://github.com/solana-labs/solana/blob/master/storage-bigtable/src/bigtable.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workspace,node_validator_cli,node_test_validator,node_cli,node_genesis_ledger_tools toneBlue
class node_validator_core,node_tpu,node_banking,node_tvu,node_gossip,node_transport toneAmber
class node_bank_svm,node_program_runtime,node_accounts_db,node_native_programs toneMint
class node_blockstore,node_poh_turbine,node_replay_consensus toneRose
class node_rpc,node_sdk_clients,node_metrics_ops,node_bigtable toneIndigo
```

## Components

### Entry points

- [Rust workspace](https://github.com/solana-labs/solana/blob/master/Cargo.toml): workspace · Defines crate composition and dependency boundaries. · `Cargo.toml`
- [Validator bootstrap](https://github.com/solana-labs/solana/blob/master/validator/src/main.rs): validator entry · `validator/src/main.rs`
- [Local test validator](https://github.com/solana-labs/solana/blob/master/validator/src/bin/solana-test-validator.rs): validator entry · `validator/src/bin/solana-test-validator.rs`
- [User CLI](https://github.com/solana-labs/solana/blob/master/cli/src/main.rs): client entry · `cli/src/main.rs`
- [Genesis and ledger tools](https://github.com/solana-labs/solana/blob/master/genesis/src/main.rs): operator tools · `genesis/src/main.rs`

### Validator pipelines

- [Validator orchestration](https://github.com/solana-labs/solana/blob/master/core/src/validator.rs): node lifecycle · Wires TPU, TVU, gossip, RPC, persistence, and background services. · `core/src/validator.rs`
- [TPU transaction pipeline](https://github.com/solana-labs/solana/blob/master/core/src/tpu.rs): ingress pipeline · `core/src/tpu.rs`
- [Banking scheduler](https://github.com/solana-labs/solana/blob/master/core/src/banking_stage/transaction_scheduler/prio_graph_scheduler.rs): execution stage · Account-lock-aware priority scheduling and banking. · `core/src/banking_stage/transaction_scheduler/prio_graph_scheduler.rs`
- [TVU validation pipeline](https://github.com/solana-labs/solana/blob/master/core/src/tvu.rs): replay pipeline · `core/src/tvu.rs`
- [CRDS gossip](https://github.com/solana-labs/solana/blob/master/gossip/src/gossip_service.rs): cluster membership · `gossip/src/gossip_service.rs`
- [QUIC/UDP transport](https://github.com/solana-labs/solana/blob/master/streamer/src/quic.rs): network transport · `streamer/src/quic.rs`

### Execution and state

- [Bank and SVM](https://github.com/solana-labs/solana/blob/master/runtime/src/bank.rs): transaction execution · Applies transaction effects, fees, invocation, and commitment state. · `runtime/src/bank.rs`
- [Program invocation](https://github.com/solana-labs/solana/blob/master/program-runtime/src/invoke_context.rs): sandbox runtime · Invocation context forms the SBF/native program boundary. · `program-runtime/src/invoke_context.rs`
- [AccountsDB](https://github.com/solana-labs/solana/blob/master/accounts-db/src/accounts_db.rs): account persistence · Caches, indexes, append-vector storage, hashes, and snapshots. · `accounts-db/src/accounts_db.rs`
- [Built-in programs](https://github.com/solana-labs/solana/blob/master/programs/system/src/system_processor.rs): protocol programs · System, stake, vote, loader, and lookup-table semantics. · `programs/system/src/system_processor.rs`

### Ledger and consensus

- [Blockstore](https://github.com/solana-labs/solana/blob/master/ledger/src/blockstore.rs): ledger persistence · Stores shreds, slot metadata, and reconstructed blocks. · `ledger/src/blockstore.rs`
- [PoH and Turbine](https://github.com/solana-labs/solana/blob/master/poh/src/poh_service.rs): leader propagation · Records slot entries, shreds leader output, and retransmits it. · `poh/src/poh_service.rs`
- [Replay and consensus](https://github.com/solana-labs/solana/blob/master/core/src/replay_stage.rs): fork choice · Replays ledger into bank forks and selects voting/tower state. · `core/src/replay_stage.rs`

### APIs and operations

- [RPC and PubSub](https://github.com/solana-labs/solana/blob/master/rpc/src/rpc_service.rs): validator API · Exposes account, transaction, subscription, health, and cluster views. · `rpc/src/rpc_service.rs`
- [SDK and clients](https://github.com/solana-labs/solana/blob/master/sdk/src/lib.rs): client libraries · Shared protocol types plus HTTP RPC and direct TPU submission. · `sdk/src/lib.rs`
- [Metrics and deployment](https://github.com/solana-labs/solana/blob/master/metrics/src/lib.rs): operations · Metrics plus multi-provider cluster provisioning scripts. · `metrics/src/lib.rs`
- [Bigtable archival](https://github.com/solana-labs/solana/blob/master/storage-bigtable/src/bigtable.rs): optional storage · `storage-bigtable/src/bigtable.rs`

## Connections

- 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
