# firedancer-io/firedancer architecture

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

- Interactive diagram: https://gitdiagram.com/firedancer-io/firedancer
- Repository: https://github.com/firedancer-io/firedancer

## Overview

##### Overall Project Understanding
- Recognize that Firedancer is a validator client for Solana. Its purpose is to process blocks quickly, securely, and with minimal trusted code.
- That there are two validator “flavors” that share common high-performance components but have differing implementations (Frankendancer, which is a hybrid using Agave code for consensus/execution, and a fully “from-scratch” Firedancer for other components).

##### Major Architectural Domains and Components from the File Structure
- Command-Line and Operator Tools: Directories like src/app/fdctl, src/app/fddbg, src/app/fddev, src/app/ledger, and src/app/rpcserver indicate separate front-end applications for configuration, debugging, development, ledger operations, and RPC interface.
- Cryptographic and Low-Level Primitives: The “ballet” directory has multiple subdirectories (such as aes, base58, blake3, ed25519, etc.) that contain implementations of cryptographic primitives, encoding/decoding, and performance-critical algorithms.
- Core Validator Pipelines: Other modules – “choreo”, “disco”, “flamenco”, “tango”, “wiredancer” – appear to be distinct layers or “dancers” that collaborate in the overall pipeline. For example:
– “flamenco” deals with block capture, genesis, gossip, log collection, runtime systems (the block production and execution pipeline).
– “disco”, “discof” and “discoh” represent networking and lower-level communication functions such as handling netlink, archiver, and data packaging.
– “tango” comprises modules for caching, IPC, and network interface abstractions.
– “wiredancer” contains both C and RTL (hardware description language) implementations for interfacing with FPGAs or specialized logic (like the “f1” platform) for fast packet processing.
- Plugins and Bundles: The “plugin” folder (e.g. plugin/bundle) illustrates mechanisms for bundling and protocol definitions (using protobufs) which may be used to extend or interface with external systems.
- Utilities and Shared Components: The “util” directory (with subdirectories for allocators, text processing, template data structures, logging, etc.) provides common libraries shared across the system.

##### Capturing Essential Architectural Elements
- Aim to break down the entire system into as many discernible components as possible using the file tree. Each directory (or grouping from similar directories) represents a module of functionality.
- On the two separate validator implementations by optionally indicating a branching within the execution path – one for Frankendancer (hybrid with Agave) and one for Firedancer.

##### Practical Steps for the Principal Software Engineer

– The external API/control via CLI/RPC,
– The high-speed networking and consensus engine,
– The block production and ledger execution pipeline,
– The foundational libraries for cryptography and utilities.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Firedancer Validator"
        %% Control Plane / Operator Tools
        subgraph "Control Plane"
            fdctl["fdctl"]:::control
            fddbg["fddbg"]:::control
            fddev["fddev"]:::control
            ledger["ledger"]:::control
            rpcserver["rpcserver"]:::control
        end

        %% Networking, Consensus & Data Flow
        subgraph "Networking & Consensus"
            disco["disco"]:::networking
            discof["discof"]:::networking
            discoh["discoh"]:::networking
        end

        %% Block Production & Execution Pipeline
        subgraph "Block Production & Execution"
            choreo["choreo"]:::execution
            flamenco["flamenco"]:::execution
            Frankendancer["Frankendancer"]:::execution
            Firedancer["Firedancer"]:::execution
        end

        %% Cryptographic and Low-Level Primitives
        subgraph "Cryptographic Primitives"
            ballet["ballet"]:::crypto
        end

        %% Extension & Plugin Layer
        subgraph "Extension & Plugin Layer"
            pluginBundle["plugin/bundle"]:::plugin
        end

        %% Shared Utility and System Libraries
        subgraph "Shared Utilities"
            util["util"]:::utility
            tango["tango"]:::utility
        end

        %% Specialized Hardware and Performance Layers
        subgraph "Specialized Hardware"
            wiredancer["wiredancer"]:::hardware
        end

        %% Additional Frameworks / Experimentation
        subgraph "Additional Frameworks"
            funk["funk"]:::framework
            funkier["funkier"]:::framework
            groove["groove"]:::framework
            waltz["waltz"]:::framework
        end
    end

    %% Connections between components
    rpcserver -->|"config"| choreo
    disco -->|"netflow"| choreo
    ballet -->|"crypto"| disco
    ballet -->|"crypto"| choreo
    wiredancer -->|"hw"| disco
    tango -->|"net"| disco
    pluginBundle -->|"extensions"| fdctl
    funk -->|"assist"| flamenco
    groove -->|"data"| flamenco
    waltz -->|"highperf"| discof
    funkier -->|"assist"| discoh

    %% Execution branching to validator flavors
    choreo -->|"branch"| Frankendancer
    choreo -->|"branch"| Firedancer
    flamenco -->|"branch"| Frankendancer
    flamenco -->|"branch"| Firedancer

    %% Shared utility supporting control plane
    util -->|"logging"| rpcserver

    %% Style definitions
    classDef control fill:#FFCCCC,stroke:#990000,stroke-width:2px;
    classDef networking fill:#CCFFFF,stroke:#006699,stroke-width:2px;
    classDef execution fill:#CCFFCC,stroke:#009900,stroke-width:2px;
    classDef crypto fill:#FFFFCC,stroke:#999900,stroke-width:2px;
    classDef plugin fill:#FFCCFF,stroke:#990099,stroke-width:2px;
    classDef utility fill:#CCE5FF,stroke:#003366,stroke-width:2px;
    classDef hardware fill:#FFEECC,stroke:#CC6600,stroke-width:2px;
    classDef framework fill:#E5CCFF,stroke:#660099,stroke-width:2px;

    %% Click Events
    click fdctl "https://github.com/firedancer-io/firedancer/tree/main/src/app/fdctl"
    click fddbg "https://github.com/firedancer-io/firedancer/tree/main/src/app/fddbg"
    click fddev "https://github.com/firedancer-io/firedancer/tree/main/src/app/fddev"
    click ledger "https://github.com/firedancer-io/firedancer/tree/main/src/app/ledger"
    click rpcserver "https://github.com/firedancer-io/firedancer/tree/main/src/app/rpcserver"
    click ballet "https://github.com/firedancer-io/firedancer/tree/main/src/ballet"
    click choreo "https://github.com/firedancer-io/firedancer/tree/main/src/choreo"
    click flamenco "https://github.com/firedancer-io/firedancer/tree/main/src/flamenco"
    click disco "https://github.com/firedancer-io/firedancer/tree/main/src/disco"
    click discof "https://github.com/firedancer-io/firedancer/tree/main/src/discof"
    click discoh "https://github.com/firedancer-io/firedancer/tree/main/src/discoh"
    click pluginBundle "https://github.com/firedancer-io/firedancer/tree/main/plugin/bundle"
    click util "https://github.com/firedancer-io/firedancer/tree/main/src/util"
    click tango "https://github.com/firedancer-io/firedancer/tree/main/src/tango"
    click wiredancer "https://github.com/firedancer-io/firedancer/tree/main/src/wiredancer"
    click funk "https://github.com/firedancer-io/firedancer/tree/main/src/funk"
    click funkier "https://github.com/firedancer-io/firedancer/tree/main/src/funkier"
    click groove "https://github.com/firedancer-io/firedancer/tree/main/src/groove"
    click waltz "https://github.com/firedancer-io/firedancer/tree/main/src/waltz"
```
