# jito-foundation/jito-solana architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, distributed blockchain node implementation: Jito’s fork of the Solana validator.
- It encompasses the core validator engine (networking, consensus, transaction pipeline, ledger storage, runtime), plus CLI tools, client libraries, programs, benchmarks, and integration with external services (Bigtable, metrics, etc.).

##### File structure
- Top-level crates capture the major logical areas:
– validator/cli/clients (e.g. “cli”, “rpc-client”, “tpu-client”, “banks-client”)
– networking (e.g. “gossip”, “turbine”, “streamer”, “quic-client”, “udp-client”)
– transaction pipeline & consensus (“core”, “runtime”, “banking-stage”, “consensus”, “poh”, “replay-stage”, “snapshot-packager-service”)
– storage (“ledger”, “accounts-db”, “blockstore”, “storage-bigtable”)
– runtime/program execution (“program-runtime”, “bpf_loader”, “program-test”, “runtime-plugin”)
– tooling, benchmarks, CI/CD, docs, and scripts.
- Patterns: stage-based pipeline in “core” (“fetch-stage” → “sigverify-stage” → “banking-stage” → “replay-stage” → “snapshot”), actor-style services, and CRDT gossip (CRDS) for cluster state.

##### README for additional insights
- Confirms purpose: “Jito’s fork of the Solana validator.”
- Describes build/test workflow, but leaves detailed architecture to code and docs/architecture.md.

##### Detail and essential elements
- Every stage in the transaction processing pipeline
- Interactions between consensus & pipeline & storage
- Don’t omit the RPC/API layer or external services
- Important patterns (CRDT, actor model, async)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/API Layer
    subgraph "Client/API Layer"
        direction TB
        CLI["CLI Tooling"]:::api
        RPCsvc["RPC Service & PubSub"]:::api
        RPCclient["RPC Client Library"]:::api
        BanksClient["Banks Client"]:::api
        BanksServer["Banks Server (gRPC)"]:::api
        ThinClient["Thin Client Utilities"]:::api
        PubSubClient["PubSub Client"]:::api
        TPUClientLegacy["TPU Client (legacy)"]:::api
        TPUClientNext["TPU Client (next-gen)"]:::api
    end

    %% Validator Core
    subgraph "Validator Core"
        direction TB

        subgraph "Networking" 
            direction TB
            Gossip["Gossip"]:::networking
            Turbine["Turbine Broadcast"]:::networking
            Streamer["Streamer (packet relay)"]:::networking
            QUIC["QUIC TPU Client"]:::networking
            UDP["UDP TPU Client"]:::networking
        end

        subgraph "Processing Pipeline"
            direction TB
            Fetch["Fetch Stage"]:::processing
            SigVerify["SigVerify Stage"]:::processing
            Banking["Banking Stage"]:::processing
            Replay["Replay Stage"]:::processing
            SnapshotPkg["Snapshot Packager Service"]:::processing
        end

        subgraph "Consensus & Voting"
            direction TB
            ConsensusMods["Consensus Modules"]:::processing
            VoteSim["Vote Simulator"]:::processing
            VotingSvc["Voting Service"]:::processing
        end

        subgraph "Ledger & State Storage"
            direction TB
            Blockstore["Blockstore (ledger)"]:::storage
            AccountsDB["Accounts DB"]:::storage
        end

        subgraph "Runtime & BPF Execution"
            direction TB
            ProgRuntime["Program Runtime"]:::processing
            BFPLoader["BPF Loader"]:::processing
            RuntimePlugins["Runtime Plugins"]:::processing
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Bigtable["Bigtable Storage Integration"]:::external
        Metrics["Metrics Collection & Dashboards"]:::external
    end

    %% Client to Core
    CLI -->|uses RPC| RPCsvc
    RPCclient -->|calls RPC| RPCsvc
    BanksClient -->|calls Banks gRPC| BanksServer
    ThinClient -->|sends transactions| TPUClientLegacy
    PubSubClient -->|subscribes| RPCsvc
    TPUClientLegacy -->|submits TX| Gossip
    TPUClientNext -->|submits TX| Gossip

    RPCsvc -->|serves API| Gossip
    BanksServer -->|serves to| Gossip

    %% Networking to Pipeline
    Gossip -->|dispatch packets| Fetch
    Turbine -->|broadcast shreds| Gossip
    Streamer -->|relay packets| Fetch
    QUIC -->|ingest TX| Fetch
    UDP -->|ingest TX| Fetch

    %% Pipeline flow
    Fetch -->|fetched| SigVerify
    SigVerify -->|verified| Banking
    Banking -->|processed| Replay
    Replay -->|replayed| SnapshotPkg

    %% Banking interactions
    Banking -->|write| Blockstore
    Banking -->|write| AccountsDB

    %% Runtime execution
    Banking -->|invoke| ProgRuntime
    ProgRuntime -->|load program| BFPLoader
    ProgRuntime -->|plugins| RuntimePlugins

    %% Consensus interactions
    Replay -->|block proposals| ConsensusMods
    ConsensusMods -->|simulate votes| VoteSim
    VoteSim -->|trigger votes| VotingSvc
    VotingSvc -->|publish votes| Gossip

    %% Snapshot integration
    SnapshotPkg -->|store snapshots| Blockstore

    %% External services
    Blockstore -->|archive| Bigtable
    AccountsDB -->|sync| Bigtable
    Metrics -->|collect from| Gossip
    Metrics -->|collect from| Banking
    Metrics -->|collect from| ConsensusMods

    %% Click events
    click Gossip "https://github.com/jito-foundation/jito-solana/tree/master/gossip/"
    click Turbine "https://github.com/jito-foundation/jito-solana/tree/master/turbine/src"
    click Streamer "https://github.com/jito-foundation/jito-solana/tree/master/streamer/src"
    click QUIC "https://github.com/jito-foundation/jito-solana/tree/master/quic-client/src"
    click UDP "https://github.com/jito-foundation/jito-solana/tree/master/udp-client/src"
    click Fetch "https://github.com/jito-foundation/jito-solana/blob/master/core/src/fetch_stage.rs"
    click SigVerify "https://github.com/jito-foundation/jito-solana/blob/master/core/src/sigverify_stage.rs"
    click Banking "https://github.com/jito-foundation/jito-solana/blob/master/core/src/banking_stage.rs"
    click Banking "https://github.com/jito-foundation/jito-solana/tree/master/core/src/banking_stage/"
    click Replay "https://github.com/jito-foundation/jito-solana/blob/master/core/src/replay_stage.rs"
    click SnapshotPkg "https://github.com/jito-foundation/jito-solana/blob/master/core/src/snapshot_packager_service.rs"
    click SnapshotPkg "https://github.com/jito-foundation/jito-solana/tree/master/core/src/snapshot_packager_service/"
    click ConsensusMods "https://github.com/jito-foundation/jito-solana/tree/master/core/src/consensus/"
    click VoteSim "https://github.com/jito-foundation/jito-solana/blob/master/core/src/vote_simulator.rs"
    click VotingSvc "https://github.com/jito-foundation/jito-solana/blob/master/core/src/voting_service.rs"
    click Blockstore "https://github.com/jito-foundation/jito-solana/tree/master/ledger/src"
    click AccountsDB "https://github.com/jito-foundation/jito-solana/tree/master/accounts-db/src"
    click ProgRuntime "https://github.com/jito-foundation/jito-solana/tree/master/program-runtime/src"
    click BFPLoader "https://github.com/jito-foundation/jito-solana/tree/master/programs/bpf_loader/src"
    click RuntimePlugins "https://github.com/jito-foundation/jito-solana/tree/master/runtime-plugin/src"
    click CLI "https://github.com/jito-foundation/jito-solana/tree/master/cli/src"
    click RPCsvc "https://github.com/jito-foundation/jito-solana/tree/master/rpc/src"
    click RPCclient "https://github.com/jito-foundation/jito-solana/tree/master/rpc-client/src"
    click BanksClient "https://github.com/jito-foundation/jito-solana/tree/master/banks-client/src"
    click BanksServer "https://github.com/jito-foundation/jito-solana/tree/master/banks-server/src"
    click ThinClient "https://github.com/jito-foundation/jito-solana/tree/master/client/src"
    click ThinClient "https://github.com/jito-foundation/jito-solana/tree/master/thin-client/src"
    click PubSubClient "https://github.com/jito-foundation/jito-solana/tree/master/pubsub-client/src"
    click TPUClientLegacy "https://github.com/jito-foundation/jito-solana/tree/master/tpu-client/src"
    click TPUClientNext "https://github.com/jito-foundation/jito-solana/tree/master/tpu-client-next/src"
    click Bigtable "https://github.com/jito-foundation/jito-solana/tree/master/storage-bigtable/src"
    click Metrics "https://github.com/jito-foundation/jito-solana/tree/master/metrics/src"

    %% Styles
    classDef networking fill:#D6EAF8,stroke:#2980B9;
    classDef processing fill:#D5F5E3,stroke:#27AE60;
    classDef storage fill:#FDEBD0,stroke:#D68910;
    classDef api fill:#E8DAEF,stroke:#8E44AD;
    classDef external fill:#E5E8E8,stroke:#566573;
```
