Flamenco

Flamenco is Firedancer’s implementation of the Solana protocol, providing transaction execution, account management, consensus logic, and validator operations. It serves as the runtime layer that processes Solana transactions and maintains blockchain state.

Overview

Flamenco implements the complete Solana runtime environment, including:

Transaction execution and validation
Account state management
Program execution (eBPF VM)
Consensus and leader scheduling
Stake and reward calculations
Feature gate management

Flamenco aims for complete compatibility with the Solana Labs validator while providing significant performance improvements through optimized data structures and parallel execution.

Core Components

Runtime Engine

Runtime (`runtime/`)

The core execution engine for Solana transactions:Key structures:

struct fd_runtime;
typedef struct fd_runtime fd_runtime_t;

struct fd_exec_instr_ctx;  // Instruction execution context
typedef struct fd_exec_instr_ctx fd_exec_instr_ctx_t;

Responsibilities:

Transaction execution orchestration
Cross-program invocation (CPI) handling
Compute unit metering
Account locking and conflict detection
Rent collection
Sysvar updates

Transaction Processing (`txn/`)

struct fd_txn_in;   // Input transaction
struct fd_txn_out;  // Execution result

Processing pipeline:

Parse and validate transaction format
Verify signatures (via Ballet Ed25519)
Load and lock accounts
Execute instructions sequentially
Update account states
Calculate fees and rent
Unlock accounts and commit

Transaction limits:

Max transaction size: 1232 bytes (FD_TPU_MTU)
Max signatures: Variable (typically 64)
Max accounts: 256 per transaction
Max instructions: 64 per transaction

Account Management

Account Database (`accdb/`)

High-performance account storage and retrieval:Features:

Concurrent read access
Write coalescing
Account versioning
Snapshot support
Cache hierarchy (L1/L2)

Account Metadata

struct fd_account_meta {
  uchar owner[32];      // Program that owns this account
  ulong lamports;       // Account balance in lamports
  ulong slot;           // Last modified slot
  uint  dlen;           // Data length
  uchar executable;     // Is this a program?
  uchar padding[3];
};

// Get account data
uchar * fd_account_data(fd_account_meta_t const * acc);

Borrowed Accounts

struct fd_borrowed_account;  // Transaction-scoped account reference

Lifecycle:

Borrowed at transaction start
Locked for write if writable
Modified during execution
Committed or rolled back at end

Account Manager (`fd_acc_mgr_t`)

Account lifecycle management
Memory pooling (fd_acc_pool_t)
Efficient allocation/deallocation

Virtual Machine

eBPF VM (`vm/`)

Solana’s eBPF (extended Berkeley Packet Filter) virtual machine:Capabilities:

sBPF instruction set execution
JIT compilation (optional)
Compute unit metering
Memory safety checks
Call depth limiting

Program execution:

Load program from account
Verify program (via Ballet sBPF)
Compile to native code (JIT)
Execute with instruction context
Meter compute units
Return result or error

Program Cache (`progcache/`)

struct fd_progcache;

Features:

Compiled program caching
LRU eviction policy
Concurrent access
Invalidation on program upgrades

Cache strategy:

Hot programs: JIT compiled, cached
Cold programs: Interpreted or compiled on-demand
Redeployment: Invalidate and recompile

Consensus & Leader Scheduling

Leader Schedule (`leaders/`)

Determines which validator is leader for each slot:Algorithm:

Get stake distribution at epoch boundary
Apply weighted sampling (Ballet wsample)
Generate deterministic leader sequence
Cache for current and next epoch

Key functions:

Leader rotation every 4 slots (typically)
Epoch-based recalculation
Stake-weighted selection

Stake Management (`stakes/`)

struct fd_vote_stakes;    // Voting stake distribution
struct fd_stake_rewards;  // Reward calculations

Stake tracking:

Active stake per validator
Delegated stake
Activation/deactivation epochs
Warm-up/cool-down periods

Rewards (`rewards/`)

Reward types:

Staking rewards (inflationary)
Transaction fees
Rent collection (deprecated)

Distribution:

Calculated at epoch boundary
Distributed to stake accounts
Commission split to vote accounts

Gossip & Networking

Gossip Protocol (`gossip/`)

Distributed cluster information exchange:Gossiped data:

Cluster topology (validator IPs/ports)
Vote account information
Shred versions
Contact info updates
Node health metrics

Gossip messages:

Push messages: Broadcast new information
Pull messages: Request missing data
Prune messages: Stop forwarding
Ping/pong: Liveness checks

Properties:

Eventually consistent
Epidemic broadcast protocol
Fanout-based propagation
CRDT merge semantics

Features & Versioning

Feature Gates (`features/`)

union fd_features;
typedef union fd_features fd_features_t;

Control activation of protocol changes:Feature lifecycle:

Defined in code (pending)
Activated by stake vote
Effective at next epoch
Remains active forever

Usage:

if (fd_features_test(features, FD_FEATURE_ID)) {
  // New behavior
} else {
  // Legacy behavior
}

Common features:

Transaction version support
Account rent changes
Compute unit pricing
New syscalls
VM improvements

Utility Components

Genesis (`genesis/`)

struct fd_genesis;

Genesis block configuration:

Initial account states
System program accounts
Stake pools
Inflation parameters
Epoch schedule

Capture (`capture/`)

struct fd_capture_ctx;  // Capture replay data

Features:

Transaction replay capture
Account state snapshots
Deterministic debugging
Conformance testing

Log Collector (`log_collector/`)

struct fd_log_collector;

Program log message collection:

Syscall log output
Error messages
Return to RPC clients

Types (`types/`)

Solana protocol type definitions:

Serialization formats
Wire protocol structures
Custom type definitions (fd_types_custom.h)
Type casting utilities (fd_cast.h)

Address Utilities

// Convert Solana address to base58 string
char * fd_acct_addr_cstr(
  char        cstr[FD_BASE58_ENCODED_32_SZ],
  uchar const addr[32]
);

// Result: Base58-encoded address string (32-44 chars)

Data Structures

Bank State

struct fd_bank;        // Current bank (slot state)
struct fd_banks;       // Multi-slot bank management
struct fd_bank_data;   // Bank persistent data

Banking stages:

Bank 0: Current leader slot
Bank 1: Next slot preparation
Bank N: Historical banks for forks

Synchronization

// fd_rwlock.h - Read-write lock for account access
struct fd_banks_locks;  // Per-account locking

Lock ordering:

Sort accounts by address
Acquire locks in order
Prevents deadlocks
Enables parallel execution

Execution Flow

Transaction → Parse → Signature Check → Load Accounts
     ↓
Lock Accounts → Execute Instructions → Update State
     ↓
Calculate Fees → Commit or Rollback → Unlock

Instruction Execution

struct fd_exec_instr_ctx {
  // Instruction being executed
  // Account references
  // Program ID
  // Compute unit budget
  // Instruction data
};

Execution:

Verify program ownership
Check account permissions
Execute program (native or eBPF)
Meter compute units
Update account data
Handle cross-program invocations

Performance Features

Parallel Execution: Banking stages execute transactions concurrently
Account Sharding: Partition accounts for parallel access
Program Caching: JIT-compiled programs cached in memory
Optimized Data Structures: Custom allocators and pools
SIMD Acceleration: Vectorized operations where applicable

Compatibility

Flamenco maintains compatibility with Solana Labs validator:

Identical transaction execution behavior
Same account state transitions
Compatible consensus rules
Matching feature gate activation
Equivalent RPC responses (via Agave integration)

Header Files

#include "flamenco/fd_flamenco.h"      // Main header
#include "flamenco/fd_flamenco_base.h" // Base types
#include "flamenco/fd_rwlock.h"        // Locking primitives

Ballet - Cryptographic primitives for signatures and hashing
Disco - Tile-based transaction processing pipeline
Tango - IPC for inter-stage communication

Components

Monitoring

Overview

Core Components

Runtime (`runtime/`)

Transaction Processing (`txn/`)

Account Database (`accdb/`)

Account Metadata

Borrowed Accounts

Account Manager (`fd_acc_mgr_t`)

eBPF VM (`vm/`)

Program Cache (`progcache/`)

Leader Schedule (`leaders/`)

Stake Management (`stakes/`)

Rewards (`rewards/`)

Gossip Protocol (`gossip/`)

Feature Gates (`features/`)

Genesis (`genesis/`)

Capture (`capture/`)

Log Collector (`log_collector/`)

Types (`types/`)

Address Utilities

Data Structures

Bank State

Synchronization

Execution Flow

Instruction Execution

Performance Features

Compatibility

Header Files

Build docs developers (and LLMs) love

Components

Monitoring

​Overview

​Core Components

​Runtime (runtime/)

​Transaction Processing (txn/)

​Account Database (accdb/)

​Account Metadata

​Borrowed Accounts

​Account Manager (fd_acc_mgr_t)

​eBPF VM (vm/)

​Program Cache (progcache/)

​Leader Schedule (leaders/)

​Stake Management (stakes/)

​Rewards (rewards/)

​Gossip Protocol (gossip/)

​Feature Gates (features/)

​Genesis (genesis/)

​Capture (capture/)

​Log Collector (log_collector/)

​Types (types/)

​Address Utilities

​Data Structures

​Bank State

​Synchronization

​Execution Flow

​Instruction Execution

​Performance Features

​Compatibility

​Header Files

​Related Components

Build docs developers (and LLMs) love

Overview

Core Components

Runtime (`runtime/`)

Transaction Processing (`txn/`)

Account Database (`accdb/`)

Account Metadata

Borrowed Accounts

Account Manager (`fd_acc_mgr_t`)

eBPF VM (`vm/`)

Program Cache (`progcache/`)

Leader Schedule (`leaders/`)

Stake Management (`stakes/`)

Rewards (`rewards/`)

Gossip Protocol (`gossip/`)

Feature Gates (`features/`)

Genesis (`genesis/`)

Capture (`capture/`)

Log Collector (`log_collector/`)

Types (`types/`)

Address Utilities

Data Structures

Bank State

Synchronization

Execution Flow

Instruction Execution

Performance Features

Compatibility

Header Files

Related Components