# 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:

| Layer | Crates | Purpose |
|-------|--------|---------|
| **Binary** | `bin/fuel-core`, `bin/keygen`, `bin/fuel-core-client`, `bin/e2e-test-client`, `bin/chaos-test` | CLI entry points |
| **Core** | `crates/fuel-core` | Main node logic, database, GraphQL schema, service adapters |
| **Services** | `crates/services/{poa,bft,executor,producer,importer,sync,p2p,txpool_v2,relayer,compression,gas_price_service,tx_status_manager,parallel-executor,shared-sequencer,block_aggregator_api,upgradable-executor}` | Individual service implementations |
| **Foundation** | `crates/{types,storage,database,services,chain-config,metrics,trace,keygen,client,provider,compression,syscall}` | Shared types, storage primitives, telemetry |
| **Algorithm** | `crates/fuel-gas-price-algorithm` | Gas price calculation (v0, v1) |
| **Testing** | `tests/`, `benches/`, `version-compatibility/` | Integration tests, benchmarks, forkless upgrade testing |

> [!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

| Requirement | Version |
|-------------|---------|
| Rust toolchain | 1.93.0 (stable) |
| Rust edition | 2024 |
| WASM target | `wasm32-unknown-unknown` (for wasm-executor builds) |
| RocksDB | Bundled via `rocksdb` crate 0.21 |
| Clang/LLVM | Required by RocksDB compilation |
| OpenSSL | Required for P2P/relayer TLS (or rustls alternative) |

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

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| CPU | 2 cores | 4+ cores (parallel executor benefits from `number_of_cores` config) |
| RAM | 4 GB | 16+ GB (RocksDB memory-mapped files, txpool, GraphQL cache) |
| Disk | 50 GB SSD | 500+ GB NVMe (historical state grows with chain height) |
| Network | 10 Mbps | 100+ Mbps (P2P sync, relayer RPC polling) |
| OS | Linux x86_64 | Linux x86_64 or aarch64 (Cross.toml supports both) |

> [!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`):

| Field | Type | Description |
|-------|------|-------------|
| `trigger` | `Trigger` enum | Block production strategy |
| `signer` | `SignMode` | Signing key mode (see Section 7.1) |
| `metrics` | `bool` | Enable PoA metrics |
| `min_connected_reserved_peers` | `usize` | Required peer count before producing |
| `time_until_synced` | `Duration` | Grace period before sync is assumed |
| `production_timeout` | `Duration` | Max time for block production (default: 20s) |
| `chain_id` | `ChainId` | Network chain identifier |

**Trigger modes:**

| Mode | Behavior | Use Case |
|------|----------|----------|
| `Instant` | Produce immediately when txpool has transactions | Testing, low-latency devnets |
| `Interval { block_time }` | Produce on a fixed timer | Simulated consensus delay |
| `Open { period }` | Open block immediately, seal after `period` | Accumulate transactions into batches |
| `Never` | Never produce blocks | Passive listener / follower nodes |

### 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:

| Mode | Description |
|------|-------------|
| `Unavailable` | No signing key configured (follower mode) |
| `Key(Secret)` | Local secret key (for development) |
| `Kms` | AWS KMS signing (production) |

> [!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`):

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `utxo_validation` | `bool` | -- | Validate UTXOs exist in database |
| `allow_syscall` | `bool` | -- | Allow ECAL syscall transactions |
| `max_txs_chain_count` | `usize` | -- | Max transactions per dependency chain |
| `pool_limits` | `PoolLimits` | -- | Size and count limits for the pool |
| `service_channel_limits` | `ServiceChannelLimits` | -- | Internal channel buffer sizes |
| `ttl_check_interval` | `Duration` | -- | How often to check for expired transactions |
| `max_txs_ttl` | `Duration` | -- | Maximum transaction time-to-live |
| `heavy_work` | `HeavyWorkConfig` | -- | Thread pool config for verification |
| `black_list` | `BlackList` | -- | Blocked addresses, UTXOs, messages, contracts |
| `pending_pool_tx_ttl` | `Duration` | -- | TTL for transactions in pending pool |
| `max_pending_pool_size_percentage` | `u16` | -- | Max % of pool for pending transactions |
| `metrics` | `bool` | -- | Enable txpool metrics |

**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:

| Sub-Behaviour | Protocol | Purpose |
|---------------|----------|---------|
| `blocked_peer` | allow_block_list | Block specific PeerIds |
| `connection_limits` | Custom | Enforce max connection counts |
| `discovery` | Kademlia + mDNS | Peer discovery and DHT |
| `gossipsub` | gossipsub | Transaction and block propagation |
| `heartbeat` | Custom | Peer liveness checks |
| `identify` | identify | Peer identification and agent exchange |
| `peer_report` | Custom | Periodic BlockHeight polling |
| `request_response` | request-response | Sealed block/header fetching |

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

| Parameter | Description |
|-----------|-------------|
| `keypair` | libp2p identity keypair (ed25519) |
| `network_name` | Network identifier (must match across peers) |
| `enable_mdns` | Enable mDNS for local peer discovery |
| `max_discovery_peers_connected` | Upper bound on discovered peer connections |
| `bootstrap_nodes` | Initial peer multiaddresses for DHT bootstrap |
| `reserved_nodes` | Always-connect peer list |
| `reserved_nodes_only_mode` | Only connect to reserved peers |
| `random_walk` | Optional Kademlia random walk interval |

**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`):

| Field | Default | Description |
|-------|---------|-------------|
| `da_deploy_height` | `0` | DA block height of contract deployment |
| `relayer` | `None` | Ethereum RPC URL(s); `None` disables relayer |
| `eth_v2_listening_contracts` | `[0x03E4...0911]` | FuelMessagePortal contract address(es) |
| `log_page_size` | `10,000` | Blocks per RPC `eth_getLogs` call |
| `max_logs_per_rpc` | `10,000` | Max logs per RPC response before page reduction |
| `sync_minimum_duration` | `5s` | Minimum loop interval to avoid DA node spam |
| `syncing_call_frequency` | `5s` | Poll frequency during DA sync |
| `syncing_log_frequency` | `60s` | Progress log interval during sync |
| `metrics` | `false` | Enable relayer metrics |

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`):

| State | Meaning |
|-------|---------|
| `NotSynced` | Gas price service not yet synchronized |
| `Synced(BlockHeight)` | Synchronized up to given height |

**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**:

| Field | Default | Description |
|-------|---------|-------------|
| `enabled` | `false` | Enable shared sequencer integration |
| `block_posting_frequency` | `12s` | How often to post blocks |
| `endpoints` | `None` | Tendermint RPC + blockchain REST URLs |
| `topic` | `[0u8; 32]` | Topic identifier for block posts |

### 5.6 Block Importer

**Config struct** (`importer::Config`):

| Field | Default | Description |
|-------|---------|-------------|
| `max_block_notify_buffer` | `1024` | Channel buffer size for block notifications |
| `metrics` | `false` | Enable importer metrics |

### 5.7 Block Sync

**Config struct** (`sync::import::Config`):

| Field | Default | Description |
|-------|---------|-------------|
| `block_stream_buffer_size` | `10` | Max concurrent block fetch requests |
| `header_batch_size` | `100` | Headers requested per batch |

### 5.8 Parallel Executor

**Config struct** (`parallel_executor::Config`):

| Field | Default | Description |
|-------|---------|-------------|
| `number_of_cores` | `1` | Cores for parallel block execution |
| `executor_config` | (inherited) | Underlying upgradable 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:

| Feature | Crate | Effect |
|---------|-------|--------|
| `rocksdb` | fuel-core | Enable RocksDB persistent storage |
| `rocksdb-production` | fuel-core | Production RocksDB tuning |
| `rpc` | fuel-core | Enable RPC capabilities |
| `fault-proving` | multiple | Enable fault proving support |
| `wasm-executor` | upgradable-executor | Enable WASM executor for forkless upgrades |
| `test-helpers` | multiple | Test utilities (never enable in production) |
| `alloc` | types, storage, executor | `no_std` + alloc support (WASM targets) |
| `std` | types, storage | Standard library support |
| `benchmarking` | sync | Benchmark test helpers |

---

## 6. Storage Architecture

### 6.1 Combined Database

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

| Description | Column Families | Purpose |
|-------------|----------------|---------|
| **OnChain** | Blocks, transactions, coins, contracts, consensus parameters | Consensus-critical state |
| **OffChain** | GraphQL indexation, transaction status, receipts | Query-optimized read replicas |
| **Relayer** | DA messages, forced transactions, sync height | L1 bridge state |
| **GasPrice** | Algorithm metadata, recorded heights, unrecorded blocks | Gas pricing state |
| **Compression** | Compressed block payloads, DA registries | Data availability |
| **BlockAggregator** | Aggregated blocks from remote sources | Historical block cache |

### 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 Type | Algorithm | Purpose | Output |
|----------|-----------|---------|--------|
| `BlockProduction` | secp256k1 | Signing blocks | Fuel `Address` |
| `Peering` | ed25519 | P2P identity | libp2p `PeerId` |

**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:

```toml
[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

| Role | Configuration | Purpose |
|------|--------------|---------|
| **Block Producer** | `trigger != Never`, signing key configured | Produces and signs new blocks |
| **Follower** | `trigger = Never`, no signing key | Syncs and serves queries |
| **Archive** | Follower + full historical state | Provides historical queries |
| **Relayer-enabled** | `relayer` URL(s) configured | Monitors L1 for bridged assets |

### 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`):

| Bucket Set | Values | Use |
|------------|--------|-----|
| `Timing` | 5ms to 10s (11 buckets) | General operation latency |
| `TransactionSize` | 1KB to 256KB (18 buckets) | Transaction byte sizes |
| `TransactionInsertionTimeInThreadPool` | 50us to 5s (8 buckets) | Txpool insertion latency |
| `SelectTransactionsTime` | 50us to 5s (8 buckets) | Transaction selection for block production |
| `TransactionTimeInTxpool` | 1s to 100+s (5+ buckets) | Time transactions spend waiting |

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:

```graphql
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

| Error | Source | Meaning |
|-------|--------|---------|
| `unable to produce blocks without a consensus key` | PoA service | No signing key configured on a producer node |
| `unable to produce blocks without a signer` | PoA service | `SignMode::Unavailable` on a producer |
| `Block production timed out` | PoA service | Exceeded `production_timeout` (default 20s) |
| `The block timestamp should monotonically increase` | PoA service | Clock skew or replay detected |
| `Maximum number of subscriptions reached` | tx_status_manager | Client subscription limit exceeded |
| `Invalid database version` | database | Schema version mismatch after upgrade |
| `HeightsAreNotLinked` | database | Gap detected in committed block heights |
| `ConflictingChanges` | database | Concurrent writes to the same key |
| `Failed to bind to address` | block_aggregator_api | Port already in use for gRPC server |

---

## 10. Testing and CI

### 10.1 Test Infrastructure

| Tool | Usage |
|------|-------|
| `cargo nextest` | Primary test runner (replaces `cargo test`) |
| `cargo make` | Workspace-aware task runner (avoids feature unification issues) |
| `cargo criterion` | Benchmark runner |
| `proptest` | Property-based testing (regressions tracked in `proptest-regressions/` dirs) |
| `mockall` | Trait mocking for unit tests |
| `insta` | Snapshot testing |

### 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:

| Benchmark | Purpose |
|-----------|---------|
| `import` | Block import performance |
| `state` | Database state operations |
| `vm` | FuelVM opcode execution (gas cost derivation) |
| `block_target_gas` | Block-level gas target benchmarks |
| `transaction_throughput` | End-to-end transaction processing |
| `db_lookup_times` | Database lookup latency |

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:

```rust
#![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:

| Setting | Value |
|---------|-------|
| `max_width` | 90 |
| `imports_layout` | Vertical |
| `imports_granularity` | Crate |
| `edition` | 2024 |
| `use_try_shorthand` | true |
| `use_field_init_shorthand` | true |

### 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)

| Module Path | Files | Size | Purpose |
|-------------|-------|------|---------|
| `crates/fuel-core/src` | 12 | 389K | Main node: database, GraphQL, executor, schema |
| `crates/services/p2p/src` | 18 | 183K | libp2p networking layer |
| `crates/services/txpool_v2/src` | 11 | 154K | Transaction pool with dependency graph |
| `crates/storage/src` | 12 | 114K | Storage primitives and blueprints |
| `crates/services/consensus_module/poa/src` | 8 | 109K | PoA consensus service |
| `crates/services/executor/src` | 6 | 96K | Block execution engine |
| `crates/client/src` | 5 | 88K | GraphQL client library |
| `crates/services/tx_status_manager/src` | 9 | 86K | Transaction status tracking |
| `crates/services/upgradable-executor/src` | 6 | 86K | WASM executor management |
| `crates/types/src/services` | 10 | 68K | Service type definitions |
| `crates/chain-config/src/config` | 10 | 70K | Chain configuration and snapshots |
| `crates/services/src` | 8 | 60K | Service framework (async/sync processors) |
| `crates/services/compression/src` | 9 | 52K | DA compression |
| `crates/fuel-gas-price-algorithm/src` | 4 | 50K | Gas price algorithms (v0, v1) |
| `crates/services/sync/src` | 6 | 46K | Block sync service |
| `crates/types/src` | 6 | 40K | Core type definitions |
| `crates/compression/src` | 7 | 41K | Compression primitives |
| `crates/services/relayer/src` | 9 | 40K | Ethereum L1 relayer |
| `crates/metrics/src` | 13 | 37K | Prometheus metrics |
| `crates/services/importer/src` | 6 | 36K | Block importer |
| `crates/services/producer/src` | 5 | 33K | Block producer |
| `crates/services/block_aggregator_api/src` | 10 | 32K | gRPC block aggregator |
| `crates/services/shared-sequencer/src` | 6 | 23K | Cosmos shared sequencer |
| `crates/services/upgradable-executor/wasm-executor/src` | 9 | 25K | WASM executor binary |

---

## 14. Known Issues

### 14.1 Open Issues (from GitHub)

| Issue | Status | Description |
|-------|--------|-------------|
| #3279 | Open | RUSTSEC advisory for `rustls-webpki` |
| #3265 | Open | RUSTSEC advisory for `rustls-webpki` (duplicate) |
| #3179 | Open | Paginate transactions in block GraphQL queries |
| #3084 | Open | `async-std` crate discontinued |
| #3161 | Open | `rustls-pemfile` unmaintained |

### 14.2 Closed Issues (Recently Resolved)

| Issue | Description |
|-------|-------------|
| #3098 | Rollback unsuccessful preconfs in mempool |
| #3196 | Wasmtime segfault with `f64.copysign` |

### 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

| Variable | Purpose |
|----------|---------|
| `FUEL_TRACE` | Set to `1` to enable trace-level logging |
| `FUEL_ALWAYS_USE_WASM` | Force WASM executor path (testing) |
| `OVERRIDE_CHAIN_CONFIGS` | Use local chain configs in integration tests |

### 15.2 Key Ports

| Port | Protocol | Service |
|------|----------|---------|
| 4000 | HTTP | GraphQL API |
| 30333 | TCP | P2P (libp2p) |

### 15.3 Project Links

| Resource | Location |
|----------|----------|
| Repository | `https://github.com/FuelLabs/fuel-core` |
| License | BUSL-1.1 |
| Rust toolchain | 1.93.0 |
| Workspace version | 0.48.0 |

---

_Generated May 2026 from FuelLabs/fuel-core at c453f81. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._