DOCSEARCHbyAlgolia
Submit Docs

Firedancer Documentation

repository·main·Indexed 23 days ago

https://github.com/firedancer-io/firedancer

Firedancer is a high-performance, independent validator client for the Solana network, featuring a restrictive sandbox architecture for low latency and high security. Documentation covers the Agave Cluster Management Tool CLI, build environments using GCC containers, cross-compilation toolchains, CodeQL static analysis, and the Offline Replay continuous validation harness.

Tokens
125.9K
Snippets
182
Records
647
Agent score
81%

What's inside Firedancer

  2. Overview of the Firedancer SVM Program Cache

    main

    The Program Cache is a fixed-size, fork-aware, and thread-concurrent cache used to store the results of SVM program loading and validation.

    Why it is used

    Loading and validating a program from its sBPF ELF can take up to a millisecond. The cache stores these validated programs to avoid this latency on subsequent executions. Even programs that fail to load are cached.

    User Roles

    • Transaction Executor Threads (execle, execrp tiles): These threads read from the cache, fill it on demand when a miss occurs, and lazily evict old records when the cache is out of space.
    • Replay Thread (replay tile): This thread performs background garbage collection of old records.

  3. Overview of Offline Replay

    main

    Offline Replay is a continuous validation harness that compares Firedancer's runtime against real Solana cluster history (mainnet, testnet, or devnet). It polls a Solana ledger archive bucket hourly, replays new ledgers using firedancer-dev backtest, and validates Firedancer's bank hashes against canonical Agave hashes.

    If a mismatch or crash occurs, the system:

    1. Uploads a minimized reproduction ledger to gs://firedancer-ci-resources/.
    2. Posts notifications to Slack.
    3. Resumes replaying past the problematic slot.

    It gives up after more than 5 mismatches or 5 failures on a single ledger.

  4. Use fd_resolv for sandboxed DNS resolution

    main

    The fd_resolv module provides a Linux userland DNS resolver designed for servers operating on a WAN. It is specifically engineered to facilitate sandboxing via seccomp and landlock by strictly documenting and limiting syscalls and file system accesses.

    Note that this module is not optimized for performance; it is a modified version of the getaddrinfo implementation from musl libc intended for security and sandboxing compliance rather than high-throughput resolution.

  5. Cryptographic algorithms implemented in Firedancer

    main
    Firedancer implements a wide range of cryptographic algorithms for various protocol needs, including authenticated encryption, hashing, elliptic curve operations, and signature schemes. These implementations range from hand-written SIMD-optimized versions to wrappers around formally verified libraries like s2n-bignum and blst.

  6. Use the `firedancer` CLI to manage running validators

    main

    The firedancer binary provides a command-line interface to manage and interact with running validator instances. Commands are categorized into two types:

    1. Versioned Commands: set-identity, get-identity, and add-authorized-voter work across different releases and attach to running validators.
    2. Diagnostic Commands: Commands like monitor, watch, and metrics read the validator's memory directly and must be run from the same binary that the validator is running.

    To target a specific validator when multiple are running on a host, use the --name <name> flag. Alternatively, you can provide a --config <path> to a TOML file, which the CLI uses to locate the validator via the name and [hugetlbfs.mount_path] values.

  7. What is racesan and how does it work?

    main

    racesan is a deterministic, single-threaded fuzzer designed for testing shared memory concurrent algorithms. It is primarily used to verify the logic of Firedancer database components on x86 (TSO).

    Key Characteristics:

    • Logic vs. Hardware: It detects logic errors in concurrent algorithms but cannot detect true hardware data races (e.g., cache coherence issues or torn reads).
    • Deterministic: It provides deterministic execution of interleavings.
    • Low-level Support: It works with low-level concurrency primitives like compiler fences, volatile accesses, and _mm_mfence().
    • Instrumentation Required: Unlike ThreadSanitizer, it requires manual code changes to the target code to insert hooks.

    Testing Modes:

    1. Fault Injection: Modifies state or injects logic while a target is running.
    2. Interleaving: Races multiple algorithms against each other to find invalid outcomes.

  8. What is Frankendancer?

    main

    Frankendancer is an incremental implementation of the Firedancer validator. It combines Firedancer's high-performance networking layer with the existing Agave runtime and consensus code.

    Key components implemented in Firedancer (Frankendancer) include:

    • QUIC and UDP ingress networking (using high-performance kernel bypass).
    • Block distribution engine and egress networking (using kernel bypass, including a reimplementation of erasure coding and the Solana turbine protocol).
    • Signature verification (using a custom AVX512 ED25519 implementation).
    • Block packing logic.

    All other functionality, such as the runtime that tracks account state and executes transactions, is provided by Agave. When you run a Firedancer validator, it automatically builds and runs an Agave validator as a child process; you do not need to manage the Solana process separately.

  9. Understand tile-local performance metrics

    main
    In Firedancer, most performance counters are local to a specific tile and are not automatically aggregated across the system. If multiple tiles of the same type are running (for example, multiple CPU cores assigned to QUIC connections), each tile will report its own independent metrics. To get a system-wide total, you must manually aggregate the values from each tile.

  10. Understand the scope and limitations of the fd_h2 framing layer

    main

    The fd_h2 library is strictly an implementation of the HTTP/2 framing layer. It is not a full HTTP library and does not implement RFC 9113 Section 8.

    Key Limitations and Behaviors:

    • HPACK Fragmentation: The library assumes a single HPACK record is not fragmented across multiple frames (e.g., HEADERS and CONTINUATION). If a peer fragments a record, the library throws a connection error: COMPRESSION_ERROR.
    • Server Push: PUSH_PROMISE and HTTP Server Push are not supported and are disabled via SETTINGS.
    • Priority: HTTP/2 priority hints are ignored.
    • HPACK Dynamic Table: The dynamic table is not supported and is disabled via SETTINGS.
      • Warning: This may cause compatibility issues with conforming clients. A client might send multiple requests before receiving the SETTINGS frame that disables the dynamic table. If the second request attempts to reuse a header from the first via HPACK, fd_h2 will fail to understand it.
    • END_STREAM / CONTINUATION State: The library does not correctly support the case where a HEADERS frame with the END_STREAM flag set is followed by CONTINUATION frames on the same stream.

  11. How Firedancer manages forks and network partitions

    main

    Firedancer handles Solana's eventual consistency by being natively multi-versioned. This means it concurrently executes transactions on multiple live forks. To resolve network partitions, Firedancer follows multiple forks simultaneously, persists blocks that become 'rooted', and prunes blocks that lose.

    Key fork management operations include:

    • Rooting: When a block wins (e.g., advance_root(C)), the validator prunes conflicting branches.
    • Attaching: Adding new child forks to the existing graph (e.g., attach_child(E)).

  12. Understand the shredcap v0.1 file format

    main

    The shredcap container is a streaming file format designed for capturing Solana block data suitable for replay. It is layered on top of the pcapng format, allowing shredcap flows to coexist with other network traffic.

    Shredcap stores block data via UDP/IP packets, where each packet contains a Solana shred in Turbine wire format. Because shreds require context to be interpreted, the format embeds interfaces and metadata packets to provide necessary parsing context.

    Key Parsing Rule: Readers should transparently handle files containing multiple Section Header Blocks (SHB) by resetting any cached parse state, such as cached interfaces or endpoints, whenever an SHB is encountered.