Introduction to Fuel Core

Relevant source files

• .changes/added/3131.md
• CHANGELOG.md
• Cargo.lock
• Cargo.toml
• README.md
• bin/fuel-core/Cargo.toml
• bin/fuel-core/chainspec/local-testnet/chain_config.json
• bin/fuel-core/src/cli.rs
• bin/fuel-core/src/cli/archive.rs
• bin/fuel-core/src/cli/run.rs
• bin/fuel-core/src/cli/run/graphql.rs
• bin/fuel-core/src/cli/snapshot.rs
• crates/chain-config/src/config/snapshots/fuel_core_chain_config__config__chain__tests__snapshot_local_testnet_config.snap
• crates/fuel-core/Cargo.toml
• crates/fuel-core/src/graphql_api.rs
• crates/fuel-core/src/graphql_api/api_service.rs
• crates/fuel-core/src/service.rs
• crates/fuel-core/src/service/adapters.rs
• crates/fuel-core/src/service/config.rs
• crates/fuel-core/src/service/sub_services.rs
• crates/services/src/service.rs
• crates/services/src/state.rs
• crates/services/sync/src/service.rs
• crates/services/upgradable-executor/src/executor.rs
• crates/types/src/blockchain/header.rs
• tests/tests/dos.rs

Fuel Core is the official Rust-based node implementation for the Fuel blockchain network. This document provides an overview of the fuel-core codebase, its architecture, core components, and fundamental concepts necessary for understanding how the system operates.

Scope: This page covers the high-level structure and purpose of fuel-core. For detailed information about specific subsystems, refer to:

• Block production and validation: Core Execution Engine
• Service lifecycle and orchestration: Service Orchestration
• Storage architecture: Storage Layer
• Network communication: Networking and P2P
• External API: GraphQL API

Sources: README.md1-241 Cargo.toml1-195 crates/fuel-core/src/service.rs1-136

---

What is Fuel Core

Fuel Core is a modular blockchain client that implements the Fuel protocol. It serves as the foundation for running Fuel network nodes, providing block production, transaction execution, state management, and network communication capabilities.

Key Characteristics:

• Modular Architecture: Organized into distinct crates with clear separation of concerns Cargo.toml3-43
• Upgradable Execution: Supports both native Rust execution and WASM-based state transition functions, enabling protocol upgrades without node software updates crates/services/upgradable-executor/src/executor.rs138-164
• GraphQL API: Exposes blockchain data and operations through a GraphQL interface at /v1/graphql README.md237-238
• Rust Implementation: Built entirely in Rust with a minimum version requirement of 1.90.0 Cargo.toml56

Current Version: 0.47.1 is deployed on Fuel Ignition (mainnet), Testnet, and Devnet README.md12-18

Workspace Structure:

The codebase is organized as a Cargo workspace containing:

• bin/fuel-core: CLI binary for running nodes
• crates/fuel-core: Core library aggregating all business logic
• crates/services/*: Individual service implementations (executor, txpool, p2p, relayer, etc.)
• crates/types: Shared type definitions
• crates/storage: Storage abstractions and implementations
• crates/database: Database layer
• crates/chain-config: Chain configuration and genesis

Sources: README.md1-10 Cargo.toml1-46 crates/fuel-core/Cargo.toml1-13

---

High-Level Architecture

Architecture Overview: Fuel Core Node Layers

The system is organized into distinct layers:

1. External Interface: The fuel-core CLI binary and external SDKs that interact with the node
2. API Layer: GraphQL service providing HTTP/WebSocket endpoints for queries, mutations, and subscriptions
3. FuelService Orchestrator: The ServiceRunner manages the lifecycle of all sub-services through the SharedState structure
4. Core Services: Block execution, production, validation, and transaction management
5. Infrastructure Services: Network communication, data availability, gas pricing, and compression
6. Storage: Multi-domain database system with on-chain and off-chain data separation

Sources: crates/fuel-core/src/service.rs77-112 crates/fuel-core/src/service/sub_services.rs1-50 Diagram 1 from high-level diagrams

---

Core Components

FuelService

The FuelService is the main entry point that orchestrates all sub-services crates/fuel-core/src/service.rs114-136:

It manages the lifecycle of the node through the ServiceRunner pattern, which implements a state machine with states: NotStarted, Starting, Started, Stopping, Stopped crates/services/src/state.rs6-20

Sources: crates/fuel-core/src/service.rs114-136 crates/services/src/state.rs1-20

Upgradable Executor

The executor supports protocol upgrades through a dual execution model crates/services/upgradable-executor/src/executor.rs138-164:

• Native Execution: Uses the compiled Rust fuel-vm directly when block version matches (version 32)
• WASM Execution: Loads WASM modules from on-chain storage for different protocol versions

The current native version is defined as:

Sources: crates/services/upgradable-executor/src/executor.rs138-267

Transaction Pool

The transaction pool v2 (fuel-core-txpool) manages pending transactions with features including bin/fuel-core/src/cli/run.rs276-278:

• Gas price estimation
• Transaction validation
• Dependency tracking
• P2P gossip integration

Sources: bin/fuel-core/src/cli/run.rs276-278 Cargo.toml129

Storage System

The CombinedDatabase aggregates multiple domain-specific databases crates/fuel-core/src/service.rs94:

• OnChain: Blocks, transactions, UTXOs, contracts, consensus parameters
• OffChain: Derived indexes for efficient querying (balances, owned coins)
• Relayer: DA layer events and messages
• GasPrice: Gas price algorithm state
• Compression: DA compression data

Sources: crates/fuel-core/src/service.rs77-112 Diagram 3 from high-level diagrams

P2P Network

The P2P service uses libp2p 0.54 with multiple protocol behaviors Cargo.lock119-120:

• Gossipsub for transaction broadcasting
• RequestResponse for block/transaction sync
• Heartbeat for block height consensus
• Discovery via Kademlia DHT
• PeerReport for reputation management

Sources: Diagram 4 from high-level diagrams, Cargo.toml1-195

---

Getting Started

System Requirements

Build Dependencies:

• Rust 1.90.0 or later Cargo.toml56
• cmake, pkg-config, build-essential, clang (Linux) README.md41-52
• wasm32-unknown-unknown target for WASM executor README.md57-60

Runtime Requirements:

• Sufficient file descriptors (recommended: 10240 on macOS) README.md195-201
• Database storage (default: ~/.fuel/db) bin/fuel-core/src/cli.rs28-30

Sources: README.md30-60 README.md195-201 bin/fuel-core/src/cli.rs28-30

Building from Source

The cargo xtask build command handles additional build steps like GraphQL schema generation README.md107-114

Sources: README.md73-114

Running a Node

Basic local node:

Configuration options via CLI bin/fuel-core/src/cli/run.rs127-340:

• --db-path: Database location (default: ~/.fuel/db)
• --db-type: rocks-db (persistent) or in-memory (testing)
• --snapshot: Path to genesis snapshot
• --port: GraphQL API port (default: 4000)
• --debug: Enable debug mode (manual block production, debugger endpoints)
• --poa-instant: Instant block production on transaction arrival
• --utxo-validation: Enable full UTXO validation

Sources: README.md133-168 bin/fuel-core/src/cli/run.rs127-340

Configuration File

Chain configuration is specified via JSON snapshot files bin/fuel-core/chainspec/local-testnet/chain_config.json:

Sources: bin/fuel-core/chainspec/local-testnet/chain_config.json1-50

---

Key Concepts

Blocks and State Transitions

Block Structure: Fuel uses versioned block headers crates/types/src/blockchain/header.rs38-48:

Each block header contains:

• Application Header: da_height, consensus_parameters_version, state_transition_bytecode_version, transactions data
• Consensus Header: prev_root, height, time, consensus-specific data

State Transition Bytecode Version: Determines which executor version processes the block crates/types/src/blockchain/header.rs70-80:

• Version 32 uses native execution
• Other versions load WASM from on-chain storage

Sources: crates/types/src/blockchain/header.rs1-80 crates/services/upgradable-executor/src/executor.rs203-267

Transaction Lifecycle

Transaction Lifecycle States

Transactions progress through states managed by the TxStatusManager crates/fuel-core/src/service.rs83-84:

1. Submitted: Accepted into transaction pool
2. PreconfirmationSuccess/Failure: Executed during block production before commitment
3. Success/Failure: Block containing transaction committed to chain
4. SqueezedOut: Removed from pool (conflicting inputs, expired, etc.)

Sources: Diagram 2 from high-level diagrams, crates/fuel-core/src/service.rs77-112

Consensus

Fuel Core currently implements Proof of Authority (PoA) consensus crates/fuel-core/src/service/config.rs96:

Block Production Triggers crates/fuel-core/src/service/config.rs96:

• Instant: Produce block immediately when transactions arrive
• Interval: Produce blocks at fixed time intervals
• Never: Disable block production (validator/follower mode)

Block Production Flow:

1. Producer gathers transactions from TxPool
2. Executor runs transactions through fuel-vm
3. Preconfirmations broadcast during execution
4. Changes committed to database
5. Block propagated via P2P network

Sources: crates/fuel-core/src/service/config.rs8-9 crates/fuel-core/src/service/config.rs96 Diagram 2 from high-level diagrams

On-Chain vs Off-Chain Data

The storage architecture separates consensus-critical data from derived indexes crates/fuel-core/src/service.rs94:

On-Chain Database (consensus-critical):

• FuelBlocks: Block headers and transactions
• Coins, Messages: UTXO set
• ContractsRawCode, ContractsState: Contract bytecode and storage
• ConsensusParameters: Protocol parameters by version
• StateTransitionBytecode: WASM modules for upgrades

Off-Chain Database (derived/indexed):

• TransactionStatuses: Transaction execution status
• OwnedCoins, OwnedMessageIds: UTXO ownership indexes
• CoinBalances, MessageBalances: Aggregated balances by owner
• CoinsToSpendIndex: Optimized coin selection index

The GraphQL Worker maintains off-chain indexes by processing block import events asynchronously crates/fuel-core/src/service.rs94

Sources: crates/fuel-core/src/service.rs77-112 Diagram 3 from high-level diagrams

State Rewind and Historical Execution

When RocksDB is enabled, fuel-core supports state rewind through StateRewindPolicy bin/fuel-core/src/cli/run.rs169-180:

• Default: 7 days (604,800 blocks assuming 1 block/second)
• Maximum: ~136 years (full block history)

Historical execution enables:

• Dry run queries at past block heights crates/fuel-core/src/service/config.rs85-89
• Storage read replay for debugging crates/services/upgradable-executor/src/executor.rs553-568
• Historical contract state queries via GraphQL

Sources: bin/fuel-core/src/cli/run.rs169-180 crates/fuel-core/src/service/config.rs85-89

---

Next Steps

For detailed information about specific subsystems:

• Block Execution: See Core Execution Engine for native/WASM execution, block production, and validation
• Service Management: See Service Orchestration for lifecycle management and configuration
• Data Storage: See Storage Layer for database architecture, transactions, and historical state
• Networking: See Networking and P2P for libp2p integration and synchronization
• API Interface: See GraphQL API for query/mutation resolvers and subscriptions
• Transactions: See Transaction Management for pool architecture and status tracking
• Data Availability: See Data Availability and Economics for relayer and gas pricing

Sources: Table of contents JSON provided in prompt