How firedancer-io/firedancer works
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.