fuel-core Admin Guide

This guide is for node operators, infrastructure engineers, blockchain architects, and contributors. It covers the architecture, the full configuration surface, deployment topologies, security model, operational runbooks, and contributor internals of fuel-core 0.48.0.

If you are a dapp developer or new operator looking for "how do I run a node and submit a transaction?", start with the User Guide instead.

1. Executive Summary

fuel-core is the reference node implementation for the Fuel blockchain protocol. Written in Rust (edition 2024, toolchain 1.93.0), it provides a modular, service-oriented architecture with 40+ workspace crates covering consensus, execution, networking, storage, gas pricing, L1 bridging, and a GraphQL API. The project is licensed under BUSL-1.1.

Key architectural properties:

• UTXO-based transaction model with parallel execution via FuelVM (fuel-vm 0.66.2)
• Proof-of-Authority (PoA) consensus with four trigger modes and height-based parameter overrides (PoAV2)
• libp2p networking (v0.54.1) with gossipsub, Kademlia DHT, and request-response protocols
• RocksDB storage with six logical database descriptions (OnChain, OffChain, Relayer, GasPrice, Compression, BlockAggregator)
• WASM-based upgradable executor (wasmtime 43.0.1) enabling forkless protocol upgrades
• Ethereum L1 relayer monitoring FuelMessagePortal for bridged messages and forced transactions
• GraphQL API (async-graphql 7.0.15) as the primary client interface on port 4000

Important

This document covers version 0.48.0 at commit c453f81 (2026-04-23). Configuration fields and feature flags may change between releases.

2. Architecture Overview

2.1 High-Level Component Map

                          ┌──────────────────────────────────────┐
                          │            fuel-core (bin)           │
                          │  CLI entry point + service wiring    │
                          └──────────┬───────────────────────────┘
                                     │
          ┌──────────────────────────┼────────────────────────────┐
          │                          │                            │
    ┌─────▼─────┐           ┌───────▼────────┐          ┌───────▼────────┐
    │  GraphQL   │           │   Consensus    │          │      P2P       │
    │   API      │           │   (PoA/BFT)    │          │   (libp2p)     │
    │ port 4000  │           │                │          │                │
    └─────┬──────┘           └───────┬────────┘          └───────┬────────┘
          │                          │                            │
    ┌─────▼──────┐           ┌───────▼────────┐          ┌───────▼────────┐
    │  TxPool    │           │   Producer      │          │     Sync       │
    │  v2        │◄──────────┤                 │          │   Service      │
    └─────┬──────┘           └───────┬────────┘          └───────┬────────┘
          │                          │                            │
          │                  ┌───────▼────────┐                   │
          │                  │   Executor      │                   │
          │                  │ (Native/WASM)   │                   │
          │                  └───────┬────────┘                   │
          │                          │                            │
    ┌─────▼──────────────────────────▼────────────────────────────▼──┐
    │                        Importer Service                        │
    │              (validates, commits blocks to storage)            │
    └──────────────────────────┬─────────────────────────────────────┘
                               │
    ┌──────────────────────────▼─────────────────────────────────────┐
    │                    Combined Database                            │
    │  OnChain │ OffChain │ Relayer │ GasPrice │ Compression │ Agg   │
    │                    (RocksDB / In-Memory)                       │
    └────────────────────────────────────────────────────────────────┘

2.2 Service Lifecycle

All services implement the fuel_core_services::Service trait, which provides a state machine with Started, Stopped, and StoppedWithError states. Services are managed through ServiceRunner which handles:

1. Initialization -- each service validates its configuration and opens required resources
2. Start -- spawns an async task on the tokio runtime
3. Graceful shutdown -- propagates stop signals via StateWatcher channels
4. Error handling -- services that crash transition to StoppedWithError and can be restarted

The AsyncProcessor and SyncProcessor provide bounded-concurrency task execution for CPU-heavy work (transaction verification, block execution) with semaphore-based backpressure.

2.3 Crate Architecture

The workspace contains 40 member crates organized into layers:

Note

The bin/fuel-core crate (the CLI binary) uses clap derive macros for argument parsing. The AST extractor found 0 CLI commands because Rust derive macros are not statically extractable. All CLI flags are derived from the service config structs documented in Section 5.

3. System Requirements

3.1 Build Requirements

Additional dev tools (for CI):

cargo install cargo-sort cargo-make cargo-insta cargo-nextest
npm install prettier prettier-plugin-toml

3.2 Runtime Requirements

Warning

Running with --db-type in-memory provides no persistence. All state is lost on restart. Use only for development and testing.

4. Consensus

4.1 Proof-of-Authority (PoA)

fuel-core uses PoA consensus with a single block-producing authority. The consensus module lives in crates/services/consensus_module/poa/.

Configuration struct (poa::Config):

Trigger modes:

4.2 PoAV2: Height-Based Parameter Overrides

PoAV2 enables consensus parameter changes at specific block heights without a hard fork. Consensus parameters (gas limits, transaction size limits, etc.) are stored on-chain via ConsensusParametersVersions and can be updated through governance transactions.

4.3 BFT Module

The crates/services/consensus_module/bft/ crate provides a Byzantine Fault Tolerance module stub. As of 0.48.0 it contains only the module structure (src/lib.rs, 140 chars) and is not yet active in production.

4.4 Block Signing

The SignMode enum (in crates/types/src/signer.rs) supports multiple signing backends:

Caution

Never use SignMode::Key with an unencrypted secret in production. For production block producers, use AWS KMS signing. Error messages like "no PoA signing key configured" or "Failed to sign with AWS KMS" indicate signing misconfiguration.

5. Configuration Reference

5.1 Transaction Pool (TxPool v2)

The txpool (crates/services/txpool_v2/) manages pending transactions with a dependency graph (petgraph), collision detection, and TTL expiration.

Config struct (txpool::Config):

Blacklist supports four categories:

• owners: Blocked Address values (sender or recipient)
• coins: Blocked UtxoId values
• messages: Blocked message Nonce values
• contracts: Blocked ContractId values

5.2 P2P Networking

The P2P layer (crates/services/p2p/) implements the FuelBehaviour composite libp2p behaviour:

Key P2P configuration parameters (from p2p::Config):

Connection authentication: Connections use libp2p Noise encryption with a FuelAuthenticated wrapper that adds a SHA-256 chain config checksum to the protocol string. Peers with mismatched chain configurations are rejected at the transport layer. The ConnectionTracker enforces slot-based admission: reserved peers are always accepted; other peers only if slots are available.

Important

MAX_PENDING_INCOMING_CONNECTIONS and MAX_PENDING_OUTGOING_CONNECTIONS are hardcoded at 100 each in behavior.rs. These are not configurable at runtime.

5.3 Relayer (L1 Bridge)

The relayer (crates/services/relayer/) monitors Ethereum L1 for bridged messages and forced transactions from the FuelMessagePortal contract.

Config struct (relayer::Config):

The relayer tracks two event types:

• MessageSent (3 indexed topics): Bridged messages from L1 to Fuel
• Transaction (1 indexed topic): Forced transactions submitted via L1

Note

The relayer uses alloy libraries (v1.7) for Ethereum interaction, with reqwest + rustls for TLS. Cookie-based sticky sessions are enabled for L7 load balancer compatibility.

5.4 Gas Price Service

The gas price service (crates/services/gas_price_service/) supports two algorithm versions:

Static algorithm (StaticAlgorithm): Returns a fixed gas price regardless of network conditions. Configured via StaticAlgorithm::new(price).

Dynamic v0: Adjustable gas price based on block utilization.

Dynamic v1: Cumulative percentage-based algorithm with DA cost integration. Uses fuel_gas_price_algorithm::cumulative_percentage_change for price updates factoring in L2 block usage and DA layer recording costs.

Synchronization states (SyncState):

Storage ports: The gas price service requires implementations of L2Data, SetMetadataStorage, GetMetadataStorage, SetLatestRecordedHeight, GetLatestRecordedHeight, and GasPriceServiceAtomicStorage.

5.5 Shared Sequencer

The shared sequencer (crates/services/shared-sequencer/) integrates with a Cosmos SDK / Tendermint chain for cross-chain block posting.

Config struct:

5.6 Block Importer

Config struct (importer::Config):

5.7 Block Sync

Config struct (sync::import::Config):

5.8 Parallel Executor

Config struct (parallel_executor::Config):

5.9 Block Aggregator API

The block aggregator API (crates/services/block_aggregator_api/) provides a gRPC/protobuf interface backed by S3 storage for historical block data.

Dependencies: aws-sdk-s3, tonic, prost, flate2 (gzip compression).

5.10 Feature Flags

Key Cargo feature flags affecting build and runtime behavior:

6. Storage Architecture

6.1 Combined Database

The CombinedDatabase (crates/fuel-core/src/combined_database.rs) aggregates six logical database descriptions:

6.2 Storage Backends

RocksDB (production): Enabled via rocksdb + rocksdb-production features. Uses WAL, column families for logical separation, and supports historical state via historical_rocksdb.

In-Memory (development): No persistence. Useful for unit tests and short-lived devnets.

6.3 Storage Blueprint System

The storage layer (crates/storage/) uses a blueprint pattern for table definitions:

• Plain blueprint: Simple CRUD key-value storage
• Sparse Merkle Tree (SMT) blueprint: Maintains a valid Merkle tree over entries
• Merklized blueprint: Merkle root computation for storage verification

Codecs (Encode/Decode) handle serialization. The system uses postcard (1.0) for binary serialization across most tables.

6.4 Database Versioning

Database schema versions are tracked per-description. On startup, fuel-core validates expected vs found versions and fails fast on mismatch:

Invalid database version, expected 0x{expected}, found 0x{found}

Warning

There is no automatic migration. A version mismatch requires either a fresh resync or manual migration tooling (not included in 0.48.0).

6.5 Historical State

The historical_rocksdb module provides rollback capabilities. Each block commit stores a changeset. Rollback removes the latest changeset and reverts the database. Error ReachedEndOfHistory indicates no more history is available.

7. Security

7.1 Key Management

fuel-core uses two key types (crates/keygen/):

Key generation: fuel-core-keygen new --key-type block-production generates a random key using StdRng seeded from OS entropy.

Key parsing: fuel-core-keygen parse --key-type peering --secret <hex> derives the public key and PeerId from an existing secret.

Production signing: AWS KMS integration (aws-sdk-kms 1.96.0) supports remote signing for block production keys. The KMS path validates DER-encoded signatures and public keys, and rejects reduced-x form coordinates.

7.2 P2P Security

• Transport encryption: All connections use Noise protocol (libp2p-noise)
• Chain isolation: The FuelAuthenticated upgrade appends a SHA-256 checksum of the chain configuration to the Noise protocol ID, preventing cross-chain peer connections
• Connection admission: ConnectionTracker enforces a slot-based model; reserved peers bypass slot limits
• Peer blocking: The allow_block_list::Behaviour enables runtime peer blocking

7.3 Transaction Validation

• UTXO validation: When enabled, verifies that referenced UTXOs exist in the database with correct data
• Blacklisting: The txpool's BlackList rejects transactions referencing blocked addresses, UTXOs, messages, or contracts
• Predicate verification: Predicates are verified in a sandboxed FuelVM execution with bounded gas
• Syscall gating: The allow_syscall flag controls whether ECAL (external call) instructions are accepted

7.4 GraphQL API Security

• Query depth/complexity limits: async-graphql provides built-in query complexity analysis
• Pagination enforcement: All collection queries require first or last parameters; whole-range queries are rejected ("The queries for the whole range is not supported")
• Subscription limits: "Maximum number of subscriptions reached" is enforced per connection

Caution

The GraphQL API listens on all interfaces by default (port 4000). In production, place it behind a reverse proxy with rate limiting, authentication, and TLS termination. The API itself does not provide authentication.

8. Deployment

8.1 Docker

The project includes deployment/Dockerfile and docker-compose.yml at the repository root. Cross-compilation targets are defined in Cross.toml:

• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• aarch64-unknown-linux-gnu
• aarch64-unknown-linux-musl

8.2 Build Profiles

The release profile (Cargo.toml) uses:

[profile.release]
codegen-units = 1
lto = "fat"
panic = "unwind"

Tip

For faster iteration during benchmarking or profiling, switch to lto = "thin" which compiles significantly faster with minimal performance difference.

8.3 Node Roles

8.4 High Availability

Block producer HA uses Redis-based leader election (documented in docs/poa/). Only one node produces blocks at a time; others remain in standby. The leader lease mechanism prevents split-brain scenarios. Scripts for Redis leader lease setup are in crates/fuel-core/redis_leader_lease_adapter_scripts/.

9. Operations

9.1 Metrics

The metrics crate (crates/metrics/) uses prometheus-client 0.22.0. Metrics are exposed when metrics: true is set on individual service configs.

Histogram buckets (predefined in buckets.rs):

The FuturesMetrics wrapper provides automatic instrumentation for any async future via MeteredFuture.

9.2 Tracing

The fuel-core-trace crate (crates/trace/) integrates with tracing (0.1) and tracing-subscriber (0.3). Enable trace logging with the FUEL_TRACE=1 environment variable.

Clippy configuration (clippy.toml) enforces tracing over log:

Use tracing instead of log

All log::* macros are disallowed project-wide.

9.3 Health Checks

The GraphQL API exposes a health query:

query { health }

Returns true when the node is operational.

9.4 Rollback

The historical RocksDB module supports rolling back the database to a previous block height. This operates on the OnChain and OffChain databases. Errors during rollback:

• Database doesn't have a height to rollback -- no rollback state available
• on-chain database doesn't have height / off-chain database doesn't have height -- corrupted height tracking

9.5 Common Operational Errors

10. Testing and CI

10.1 Test Infrastructure

10.2 CI Checks

The ci_checks.sh script runs the full CI pipeline locally:

1. cargo +nightly fmt --all -- formatting
2. cargo sort -w --check -- dependency sorting
3. cargo clippy --all-targets --all-features -- linting
4. WASM target checks for types, storage, client, chain-config, executor, wasm-executor
5. cargo make check with various feature combinations
6. Integration tests with OVERRIDE_CHAIN_CONFIGS=true
7. cargo nextest run --workspace -- full test suite
8. FUEL_ALWAYS_USE_WASM=true cargo test -- WASM executor path

10.3 Benchmarks

Benchmarks live in benches/ with six benchmark binaries:

Gas costs are derived from VM benchmarks and output to gas-costs.yaml or default-gas-costs.rs via the collect binary.

Tip

To profile a specific benchmark: build with CARGO_PROFILE_RELEASE_DEBUG=true, locate the binary in target/release/deps/, then run flamegraph <binary> --bench '<regex>' --profile-time 10.

11. Upgradable Executor (Forkless Upgrades)

11.1 Architecture

The upgradable executor (crates/services/upgradable-executor/) enables protocol upgrades without hard forks:

1. A new WASM executor binary is uploaded on-chain as a state transition
2. The UpgradableExecutor detects the version change via ConsensusParametersVersions
3. wasmtime (43.0.1) compiles and executes the new WASM module
4. The old native executor remains as fallback

11.2 WASM Executor

The WASM executor entry point (crates/services/upgradable-executor/wasm-executor/src/main.rs) exposes an execute() extern function. It receives serialized blocks via host calls (ext) and returns execution results.

Host call interface (ext.rs):

• Block data deserialization
• Transaction deserialization
• Event deserialization
• Error serialization (v0 and current format)

11.3 Version Compatibility Testing

The version-compatibility/forkless-upgrade/ directory contains integration tests that verify upgrade paths between chain configurations (e.g., v44, ignition). The build script (build.rs) embeds chain configurations at compile time.

12. Code Quality and Conventions

12.1 Enforced Lint Rules

All crates enforce:

#![deny(clippy::arithmetic_side_effects)]
#![deny(clippy::cast_possible_truncation)]
#![deny(unused_crate_dependencies)]
#![deny(warnings)]

The relayer additionally enforces #![forbid(unsafe_code)] and #![deny(missing_docs)].

12.2 Formatting

.rustfmt.toml enforces:

12.3 Code Review Policy

.policy.yml requires:

• At least one approval from FuelLabs/engineering-managers for all changes
• EM approval required for .bulldozer.yml and .policy.yml changes
• Any EM disapproval blocks merge until resolved

12.4 Serialization

• On-wire / storage: postcard (1.0) -- compact binary format
• Client API: cynic (3.12.0) for GraphQL client codegen, schema at crates/client/assets/schema.sdl
• Block aggregator: prost (0.14.1) for protobuf, tonic (0.14.2) for gRPC
• Shared sequencer: cosmrs for Cosmos SDK transaction encoding
• Config snapshots: parquet (58) for chain state snapshots

12.5 Allocator

Production builds use tikv-jemallocator (0.5) for improved memory allocation performance.

13. Module Reference

13.1 Top-Level Module Index (74 HIGH-priority modules)

14. Known Issues

14.1 Open Issues (from GitHub)

14.2 Closed Issues (Recently Resolved)

14.3 Dependency Advisories

Warning

Two RUSTSEC advisories affect rustls-webpki (#3279, #3265). The async-std dependency (#3084) is discontinued and rustls-pemfile (#3161) is unmaintained. These are tracked but unresolved as of 0.48.0.

15. Quick Reference

15.1 Key Environment Variables

15.2 Key Ports

15.3 Project Links