If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/FuelLabs/fuel-core shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 14 active contributors
• Distributed ownership (top contributor 18% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live FuelLabs/fuel-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/FuelLabs/fuel-core.

What it runs against: a local clone of FuelLabs/fuel-core — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in FuelLabs/fuel-core | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of FuelLabs/fuel-core. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/FuelLabs/fuel-core.git
#   cd fuel-core
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of FuelLabs/fuel-core and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "FuelLabs/fuel-core(\\.git)?\\b" \\
  && ok "origin remote is FuelLabs/fuel-core" \\
  || miss "origin remote is not FuelLabs/fuel-core (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "bin/fuel-core/Cargo.toml" \\
  && ok "bin/fuel-core/Cargo.toml" \\
  || miss "missing critical file: bin/fuel-core/Cargo.toml"
test -f "crates/fuel-core/Cargo.toml" \\
  && ok "crates/fuel-core/Cargo.toml" \\
  || miss "missing critical file: crates/fuel-core/Cargo.toml"
test -f "crates/services/executor/Cargo.toml" \\
  && ok "crates/services/executor/Cargo.toml" \\
  || miss "missing critical file: crates/services/executor/Cargo.toml"
test -f "crates/services/consensus_module/Cargo.toml" \\
  && ok "crates/services/consensus_module/Cargo.toml" \\
  || miss "missing critical file: crates/services/consensus_module/Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/FuelLabs/fuel-core"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Fuel-core is a Rust implementation of a full node for the Fuel v2 blockchain protocol. It provides consensus (PoA/BFT), block execution, transaction pooling, P2P networking, and a GraphQL RPC API to enable participation in the Fuel network. Currently deployed on Ignition (mainnet, v0.47.4), Testnet, and Devnet networks. Monorepo organized as crates/: consensus (consensus_module/ with poa/ and bft/ submodules), execution (executor/, upgradable-executor/ with wasm-executor/), networking (p2p/), storage (storage/), transaction pool (txpool_v2/), and RPC client (crates/client/). bin/ contains executables (fuel-core binary, keygen, e2e-test-client). Entry point is bin/fuel-core (the full node binary).

Node operators running Fuel network infrastructure, protocol developers contributing to the Fuel v2 consensus and execution layer, and blockchain engineers integrating with Fuel via RPC endpoints. Contributors must understand Rust, async systems, and blockchain consensus mechanics.

Production-ready and actively maintained. Multiple live networks (Ignition mainnet, testnet, devnet) depend on this code. The workspace contains 50+ crates with comprehensive CI/CD (workflows in .github/workflows), cargo audit checks (.cargo/audit.toml), and test infrastructure (nextest config at .config/nextest.toml). Recent releases (0.48.0–0.48.1) indicate ongoing active development.

Moderate risk factors: BUSL-1.1 license restricts commercial use without negotiation. Large monorepo (50+ crates) with complex interdependencies increases onboarding friction. The repo depends on FuelLabs/fuel-vm and custom protocol specifications that must stay in sync. Breaking changes are tracked (.changes/ directory with breaking/ subdirectory), but migration paths require careful attention across network deployments.

Active development on network upgrade and compatibility (version-compatibility/ directory excluded from main builds suggests testing branch compatibility). Chaos testing and nightly benchmarks (.github/workflows/) indicate focus on stability and performance. Dependency management is automated (dependencies.yml workflow). GraphQL schema regeneration is part of the build process (xtask).

git clone https://github.com/FuelLabs/fuel-core.git
cd fuel-core
rustup target add wasm32-unknown-unknown
cargo xtask build

Daily commands: For development: cargo xtask build (regenerates GraphQL schema + cargo build). For running a local network: build with make build, then follow docs at https://docs.fuel.network/docs/node-operator/fuel-ignition/local-node/. For running Ignition mainnet: checkout v0.45.1 tag, build, configure, then run with parameters from mainnet-node docs.

• Cargo.toml — Root workspace definition for all fuel-core member crates; defines dependencies, profiles, and workspace-wide settings that affect the entire build.
• bin/fuel-core/Cargo.toml — Entry point binary for the Fuel v2 full node; defines main executable and its direct dependencies.
• crates/fuel-core/Cargo.toml — Core library crate containing the node implementation, state management, and consensus logic.
• crates/services/executor/Cargo.toml — Transaction executor and VM integration; critical for block production and validation.
• crates/services/consensus_module/Cargo.toml — Consensus protocol implementations (BFT and PoA); determines network safety and liveness.
• crates/database/Cargo.toml — Database abstraction and storage layer; handles persistent state for the blockchain.
• CONTRIBUTING.md — Contribution guidelines, coding standards, and development workflow for all contributors.

Add a New Consensus Module

1. Create a new crate under crates/services/consensus_module/ mirroring the structure of poa or bft (crates/services/consensus_module/new_consensus/Cargo.toml)
2. Implement the ConsensusModule trait defined in crates/fuel-core, exposing block proposal and validation hooks (crates/fuel-core/src/consensus.rs)
3. Register the new consensus variant in the node factory and configuration layer (crates/fuel-core/src/service.rs)
4. Add integration tests in bin/e2e-test-client exercising the new consensus under various fault scenarios (bin/e2e-test-client/Cargo.toml)
5. Update crates/chain-config/src/config.rs to accept configuration parameters for the new consensus (crates/chain-config/Cargo.toml)

Add a New RPC Endpoint

1. Define the endpoint method in crates/client with input/output types serializable to JSON-RPC (crates/client/Cargo.toml)
2. Implement the handler in the RPC server mounted in crates/fuel-core, querying the state database via crates/database abstractions (crates/fuel-core/src/graphql.rs)
3. Add integration test in bin/e2e-test-client verifying the endpoint responds correctly (bin/e2e-test-client/Cargo.toml)
4. Document the endpoint signature and behavior in the client library docs (crates/client/src/lib.rs)

Add a New Storage Backend

1. Implement the DbColumn and KvStore traits defined in crates/database/src/lib.rs for your storage engine (crates/database/Cargo.toml)
2. Add configuration option in crates/chain-config to select the new backend at node startup (crates/chain-config/Cargo.toml)
3. Register the backend in the database factory instantiated by crates/fuel-core on node initialization (crates/fuel-core/src/service.rs)
4. Add benchmarks in benches/benches/db_lookup_times.rs to validate performance characteristics (benches/benches/db_lookup_times.rs)

Add a New Instruction Type to the VM

1. Define the instruction opcode and operand encoding following the Fuel ISA in crates/services/executor (crates/services/executor/Cargo.toml)
2. Implement the execute logic in the VM interpreter within crates/services/executor/src/vm/ (crates/services/executor/Cargo.toml)
3. Add gas cost entry in crates/fuel-gas-price-algorithm matching the operation complexity (crates/fuel-gas-price-algorithm/Cargo.toml)
4. Create benchmark in benches/benches/block_target_gas_set/ to ensure gas costs are calibrated correctly (benches/benches/block_target_gas.rs)

• Rust — Memory safety without garbage collection; required for high-performance blockchain critical path with deterministic finality guarantees.
• RocksDB + abstracted KvStore — Efficient LSM-tree storage with predictable I/O for high-throughput state commits and fast historical queries.
• JSON-RPC 2.0 + optional GraphQL — Standard blockchain client API; supports both simple RPC calls and complex batched queries for dApp integration.
• BFT + PoA consensus abstractions — Modular consensus allows network operators to choose safety (BFT) or simplicity (PoA) without recompiling core logic.
• Embedded VM (FuelVM) — Execute smart contracts deterministically in-process with precise gas metering, avoiding external contract call overhead.

• Modular consensus (pluggable BFT/PoA)
  • Why: Different networks have different trust assumptions; PoA is simpler for private chains, BFT for permissionless.
  • Consequence: Added abstraction complexity in crates/fuel-core; each consensus must implement the same state transition interface.

1. wasm32-unknown-unknown target must be installed (rustup target add wasm32-unknown-unknown) or upgradable-executor/wasm-executor builds will fail. 2. The .changes/ directory is mandatory: all PRs must add changelog fragments (not edit CHANGELOG.md directly) for the release process to work. 3. cargo xtask build must be used instead of plain cargo build — it regenerates GraphQL schema files. 4. Cross-network version compatibility is tracked in version-compatibility/ (excluded from workspace) for testing breakpoints. 5. ci_checks.sh script is required before pushing (sourcing ensures all linters, tests, and audit checks run). 6. BFT and PoA are mutually exclusive consensus options at compile time; check feature flags when modifying.

• Proof-of-Authority (PoA) — fuel-core implements PoA consensus in crates/services/consensus_module/poa/ as an alternative to BFT; understanding when to use PoA vs BFT is critical for node operators choosing network participation mode
• Byzantine Fault Tolerance (BFT) — The other consensus engine in crates/services/consensus_module/bft/ provides safety guarantees against malicious validators; BFT vs PoA selection affects security model and block finality
• Merkle Tree (State Root) — fuel-core uses merkle trees in crates/storage/ to commit to account state and contract bytecode; modifications to storage must preserve merkle root invariants or blocks will be rejected
• UTXO (Unspent Transaction Output) — Fuel v2 uses a UTXO model (not account-based like Ethereum); the executor in crates/services/executor/ must track UTXOs and validate spend rules, affecting how transactions are processed
• Parallel Execution — fuel-core includes crates/services/parallel-executor/ for concurrent transaction execution when dependencies allow; this is non-trivial and affects determinism guarantees
• GraphQL API — The RPC interface in crates/client/ exposes node state via GraphQL (not JSON-RPC like Ethereum); schema generation is integrated into xtask build and must stay synchronized with core state changes
• WASM Executor (Upgradable Execution) — crates/services/upgradable-executor/wasm-executor/ enables protocol upgrades without hard forks by executing consensus logic in WebAssembly; this is a differentiated capability from traditional blockchains

• FuelLabs/fuel-vm — The Fuel Virtual Machine specification and reference implementation that fuel-core executes; must stay in sync with this crate for block validation
• FuelLabs/fuel-specs — Protocol specification repository defining the Fuel v2 consensus rules, transaction format, and block structure that fuel-core implements
• FuelLabs/sway — The Sway smart contract language that compiles to Fuel VM bytecode; fuel-core executes Sway contracts on-chain
• FuelLabs/fuels-rs — Rust SDK for interacting with Fuel nodes via RPC; commonly used by fuel-core operators and integrators to call the GraphQL API
• ethereum/go-ethereum — Go Ethereum full node implementation; architectural parallel in consensus, networking, and RPC patterns (though Fuel uses PoA/BFT instead of PoW/PoS)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for chaos-test binary with documented test scenarios

The chaos-test binary exists in bin/chaos-test but there are no visible integration tests in the test suite that validate its functionality. This is critical for a consensus/network testing tool where chaos scenarios must be reproducible and verified. Adding tests would ensure the tool works correctly across different network failure conditions.

• [ ] Create tests/chaos_test_integration/ directory with integration test modules
• [ ] Add tests for basic chaos scenarios: node disconnection, message delays, Byzantine behavior
• [ ] Document test scenarios in tests/chaos_test_integration/README.md
• [ ] Add CI workflow step in .github/workflows/ci.yml to run chaos-test integration tests
• [ ] Reference bin/chaos-test/src/main.rs to understand CLI interface for testing

Create comprehensive benchmarking suite for parallel-executor performance regression detection

The repo has benches/benches/block_target_gas_set/ with modular gas cost benchmarks, but there are no specific benchmarks for crates/services/parallel-executor which is a critical performance component. Adding regression detection benchmarks would catch performance regressions early and help validate parallel execution improvements.

• [ ] Create benches/benches/parallel_executor/ directory with benchmark modules
• [ ] Add benchmarks for: transaction execution parallelization, state root computation, lock contention
• [ ] Implement baseline comparison in benches/benches-outputs/src/lib.rs to track regressions
• [ ] Add nightly benchmark CI job in .github/workflows/nightly-benchmark.yml specifically for parallel-executor
• [ ] Reference crates/services/parallel-executor/src/ to understand architecture

Add validation tests for all .changes/ changelog entries to prevent orphaned entries

The .changes/ directory structure (added, breaking, changed, fixed, removed) is present but there's no CI validation to ensure all entries are properly formatted, referenced in PRs, or cleaned up after releases. This prevents changelog debt and ensures release notes are always accurate.

• [ ] Create xtask/src/commands/validate_changes.rs to parse and validate .changes/ entries
• [ ] Validate each entry has: valid YAML frontmatter, references to issue/PR numbers, valid category
• [ ] Add GitHub Actions workflow step in .github/workflows/ci.yml to run 'cargo xtask validate-changes'
• [ ] Ensure validation fails if .changes/ entries reference non-existent PRs or have incomplete formatting
• [ ] Document changelog process in CONTRIBUTING.md with examples from .changes/ structure

• Add integration tests for the gas price algorithm (crates/fuel-gas-price-algorithm/ has no obvious test file in the structure; create crates/fuel-gas-price-algorithm/tests/ with scenarios matching the RPC gas price estimation endpoint)
• Document the storage schema in comments (crates/storage/ likely has merkle tree operations for blocks and state; add module-level doc comments explaining the column families and their invariants so new contributors understand persistence)
• Create missing changelog fragments for recent commits (examine git log for merges without corresponding .changes/[added|changed|fixed|removed|breaking]/ entries and file the ones that exist to make release notes accurate)

The Fuel Core codebase demonstrates reasonable security practices with evidence of audit workflows and deliberate dependency feature control. However, the analysis is limited by incomplete file visibility. Primary concerns are: (1) truncated Cargo.toml preventing full dependency audit, (2) non-standard Rust edition specification, (3) inconsistent feature pinning across dependencies, and (4) blockchain/cryptographic complexity requiring elevated vigilance. The project has a responsible disclosure policy (SECURITY.md) and active CI/CD security checks. Recommend full dependency audit, MSRV validation in CI, and consistent security scanning.

• Medium · Incomplete Dependency Information in Cargo.toml — Cargo.toml (workspace dependencies section). The Cargo.toml file provided is truncated and incomplete, showing cut-off dependency declarations (e.g., 'alloy-provider = { ve'). This makes it impossible to verify all dependencies for known vulnerabilities. The workspace uses many complex dependencies related to blockchain, consensus, and cryptography that require careful version pinning. Fix: Ensure all dependencies are fully specified and pinned to specific versions. Run 'cargo audit' regularly as indicated in the CI pipeline (.github/workflows/nightly-cargo-audit.yml) and review audit.toml configuration for excluded vulnerabilities.
• Low · Rust Edition Set to 2024 — Cargo.toml [workspace.package] section. The workspace specifies edition = '2024', which appears to be a non-standard Rust edition. Standard editions are 2015, 2018, and 2021. This may indicate a typo or misconfiguration that could affect compilation and security tooling. Fix: Verify the intended Rust edition. Correct to '2021' (latest stable) if this was a typo. Ensure CI/CD pipeline explicitly tests with the specified Rust version (1.93.0).
• Low · Default Features Disabled Inconsistently — Cargo.toml [workspace.dependencies] section. Some dependencies like alloy-consensus, alloy-json-rpc, and alloy-primitives use 'default-features = false', while others may not. This pattern suggests careful feature control, but inconsistent application could lead to unexpected feature inclusion or security-relevant dependencies being unexpectedly enabled. Fix: Audit all external dependencies to ensure consistent explicit feature control. Document why default-features are disabled for specific packages and verify the rationale remains valid.
• Low · No Evidence of Security Scanning in CI/CD — .github/workflows/nightly-cargo-audit.yml (referenced but not shown). While a 'nightly-cargo-audit.yml' workflow exists, the absence of detailed CI configuration visibility prevents assessment of other security practices (SAST, dependency scanning frequency, security policy enforcement). Fix: Implement continuous security scanning including: daily cargo-audit runs, SAST tools, supply chain integrity checks, and automated vulnerability remediation workflows.
• Low · License Compliance Risk — Cargo.toml [workspace.package] and LICENSE. The project uses 'BUSL-1.1' (Business Source License) which is not a permissive open-source license. Dependencies must be compatible with this license or proper licensing documentation required. Fix: Maintain a license compatibility matrix. Use tools like cargo-license or FOSSA to ensure all transitive dependencies comply with BUSL-1.1 licensing requirements.
• Low · Minimum Supported Rust Version (MSRV) Not Explicitly Validated — Cargo.toml and .github/workflows/ci.yml (not fully shown). While rust-version = '1.93.0' is specified, there's no evidence of MSRV validation in CI (testing against exact MSRV, not just current stable). Fix: Add MSRV validation to CI pipeline using 'cargo +1.93.0 test' or similar to ensure compatibility claims are validated.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.