# syndica/sig architecture

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

- Interactive diagram: https://gitdiagram.com/syndica/sig
- Repository: https://github.com/syndica/sig

## Overview

##### Project type and purpose
- Sig is a full-featured Solana validator client written in Zig. It implements all of Solana’s core services: peer gossip, block/​shred propagation, consensus, ledger storage, account database, BPF runtime, RPC endpoints, metrics, and CLI tooling to run a validator node.

##### File structure
- Top-level directories:
- src/ – all Zig modules subdivided by functionality (gossip, shred_network, ledger, accountsdb, runtime, rpc, vm, transaction_sender, etc.)
- data/ – genesis and test data
- metrics/ – Prometheus, Grafana, Loki configurations
- docs/, scripts/, ci/ – tooling, build & deploy automation
- Key configuration files: build.zig (build script), zls.build.json (LSP config)
- Patterns: modular service layers (gossip vs shred_network vs consensus vs ledger vs runtime), pluggable VM programs under runtime/program

##### README for additional insights
- Confirms Sig is a “validator client” implementing node services in Zig
- Mentions CLI (cmd.zig), library entrypoint (sig.zig)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    subgraph "External Clients"
        Clients["Clients (Wallets, Explorers)"]:::external
    end
    subgraph "External Network"
        Peers["Peer Validators"]:::external
    end
    subgraph "Monitoring Stack"
        Prometheus["Prometheus"]:::metrics
        Grafana["Grafana"]:::metrics
        Prometheus --> Grafana
    end

    %% Initialization
    subgraph "Initialization"
        Cmd["cmd.zig"]:::api
        click Cmd "https://github.com/syndica/sig/blob/main/src/cmd.zig"
        Config["config.zig"]:::api
        click Config "https://github.com/syndica/sig/blob/main/src/config.zig"
        CLI["cli.zig"]:::api
        click CLI "https://github.com/syndica/sig/blob/main/src/cli.zig"
        Entrypoint["sig.zig"]:::api
        click Entrypoint "https://github.com/syndica/sig/blob/main/src/sig.zig"
    end

    %% Networking Services
    subgraph "Networking Services"
        Gossip["Gossip Service"]:::network
        click Gossip "https://github.com/syndica/sig/blob/main/src/gossip/service.zig"
        click Gossip "https://github.com/syndica/sig/tree/main/src/gossip/"
        ShredNet["Shred Network Service"]:::network
        click ShredNet "https://github.com/syndica/sig/blob/main/src/shred_network/service.zig"
        click ShredNet "https://github.com/syndica/sig/tree/main/src/shred_network/"
        TxSender["Transaction Sender"]:::network
        click TxSender "https://github.com/syndica/sig/blob/main/src/transaction_sender/service.zig"
        click TxSender "https://github.com/syndica/sig/tree/main/src/transaction_sender/"
        RPCServer["RPC Server"]:::api
        click RPCServer "https://github.com/syndica/sig/blob/main/src/rpc/server/server.zig"
        click RPCServer "https://github.com/syndica/sig/tree/main/src/rpc/server/"
        HTTPClient["HTTP Client"]:::api
        click HTTPClient "https://github.com/syndica/sig/blob/main/src/rpc/http.zig"
        click HTTPClient "https://github.com/syndica/sig/blob/main/src/rpc/client.zig"
    end

    %% Consensus
    subgraph "Consensus"
        ForkChoice["fork_choice.zig"]:::core
        click ForkChoice "https://github.com/syndica/sig/blob/main/src/consensus/fork_choice.zig"
        LibConsensus["lib.zig"]:::core
        click LibConsensus "https://github.com/syndica/sig/blob/main/src/consensus/lib.zig"
    end

    %% Storage
    subgraph "Storage"
        Blockstore["blockstore.zig"]:::storage
        click Blockstore "https://github.com/syndica/sig/blob/main/src/ledger/blockstore.zig"
        click Blockstore "https://github.com/syndica/sig/tree/main/src/ledger/"
        RocksDB["rocksdb.zig"]:::storage
        click RocksDB "https://github.com/syndica/sig/blob/main/src/ledger/database/rocksdb.zig"
        AccountsDB["db.zig"]:::storage
        click AccountsDB "https://github.com/syndica/sig/blob/main/src/accountsdb/db.zig"
        click AccountsDB "https://github.com/syndica/sig/tree/main/src/accountsdb/"
    end

    %% Execution
    subgraph "Execution"
        Runtime["executor.zig"]:::execution
        click Runtime "https://github.com/syndica/sig/blob/main/src/runtime/executor.zig"
        click Runtime "https://github.com/syndica/sig/tree/main/src/runtime/"
        BPFPrograms["BPF Programs"]:::execution
        click BPFPrograms "https://github.com/syndica/sig/tree/main/src/runtime/program/bpf/"
        VMCore["interpreter.zig"]:::execution
        click VMCore "https://github.com/syndica/sig/blob/main/src/vm/interpreter.zig"
        click VMCore "https://github.com/syndica/sig/blob/main/src/vm/lib.zig"
    end

    %% Utilities
    subgraph "Auxiliary Modules"
        Utils["service.zig"]:::utility
        click Utils "https://github.com/syndica/sig/blob/main/src/utils/service.zig"
        click Utils "https://github.com/syndica/sig/tree/main/src/utils/"
        SyncPrims["thread_pool.zig"]:::utility
        click SyncPrims "https://github.com/syndica/sig/blob/main/src/sync/thread_pool.zig"
        click SyncPrims "https://github.com/syndica/sig/tree/main/src/sync/"
        Bincode["bincode"]:::utility
        click Bincode "https://github.com/syndica/sig/tree/main/src/bincode/"
        Bloom["bloom"]:::utility
        click Bloom "https://github.com/syndica/sig/tree/main/src/bloom/"
        Crypto["lib.zig"]:::utility
        click Crypto "https://github.com/syndica/sig/blob/main/src/crypto/lib.zig"
        click Crypto "https://github.com/syndica/sig/tree/main/src/crypto/"
    end

    %% Metrics
    subgraph "Metrics & Observability"
        PromExp["Prometheus Exporter"]:::metrics
        click PromExp "https://github.com/syndica/sig/blob/main/src/prometheus/http.zig"
        click PromExp "https://github.com/syndica/sig/tree/main/src/prometheus/"
        GrafDash["Grafana Dashboards"]:::metrics
        click GrafDash "https://github.com/syndica/sig/tree/main/metrics/grafana/dashboards/"
        PromConfig["prometheus.yml"]:::metrics
        click PromConfig "https://github.com/syndica/sig/blob/main/metrics/prometheus/prometheus.yml"
    end

    %% Connections
    Clients -->|"RPC JSON"| RPCServer
    Clients -->|"Submit Tx RPC"| RPCServer
    RPCServer -->|"Query Blocks"| Blockstore
    RPCServer -->|"Account Lookups"| AccountsDB
    RPCServer -->|"Forward Tx"| TxSender

    Config --> Cmd
    Config --> CLI
    Config --> Entrypoint
    Entrypoint --> Gossip
    Entrypoint --> ShredNet
    Entrypoint --> ForkChoice
    Entrypoint --> Blockstore
    Entrypoint --> Runtime
    Entrypoint --> PromExp

    Peers <-->|"Gossip Protocol"| Gossip
    Peers <-->|"Shred UDP"| ShredNet
    Gossip -->|"Cluster Info/Votes"| ForkChoice
    ShredNet -->|"Incoming Shreds"| ForkChoice

    ForkChoice -->|"New Blocks"| Blockstore
    Blockstore -->|"Update State"| AccountsDB

    TxSender -->|"Gossip Tx"| Gossip
    ForkChoice -->|"Execute Transactions"| Runtime
    Runtime -->|"Load BPF"| BPFPrograms
    BPFPrograms --> VMCore
    VMCore -->|"State Updates"| AccountsDB
    VMCore -->|"Block Writes"| Blockstore

    %% Metrics flows
    Gossip --> PromExp
    ShredNet --> PromExp
    TxSender --> PromExp
    RPCServer --> PromExp
    ForkChoice --> PromExp
    Blockstore --> PromExp
    AccountsDB --> PromExp
    Runtime --> PromExp
    VMCore --> PromExp
    PromExp --> Prometheus

    %% Styles
    classDef network fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef storage fill:#DFFFE0,stroke:#000,stroke-width:1px
    classDef execution fill:#FFE8B0,stroke:#000,stroke-width:1px
    classDef api fill:#E8D0FF,stroke:#000,stroke-width:1px
    classDef utility fill:#F0F0F0,stroke:#000,stroke-width:1px
    classDef metrics fill:#FFD0D0,stroke:#000,stroke-width:1px
    classDef core fill:#FFF0D0,stroke:#000,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
