FuelLabs/fuel-core: running a Fuel v2 full node in Rust

What fuel-core is, and the operator it is built for

fuel-core is described in its README as a "Fuel client implementation" and by the repository as the Rust full node implementation of the Fuel v2 protocol. The practical reading is that this is infrastructure: you run a binary that syncs, validates and serves a Fuel chain. The README's own framing points at operators, with a table of versions currently used in networks (Fuel Ignition, Testnet and Devnet all at 0.48.1) and a walkthrough titled Running a Ignition node. If you write contracts in Sway or build a front end against Fuel, you are not the audience for this repository. You are the audience for whatever talks to a node, and that node is this. The repository is a Cargo workspace, not a single crate. Cargo.toml lists members from bin/fuel-core through crates/services/executor, crates/services/p2p, crates/services/txpool_v2 and crates/storage, with exclude = ["version-compatibility"]. That layout is the honest signal about scope: this is a stack of services (consensus, executor, importer, producer, relayer, sync, gas price) assembled behind one binary. The last push was on 2026-08-27, and the most recent release is v0.48.3 on the same date, so the project is not dormant. It is also not something you can skim. There is no homepage field, and the README sends you to docs.fuel.network for the actual operator instructions rather than reproducing them.

The mechanism: a GraphQL endpoint over RocksDB with instant block production

The README is explicit about the service shape. Client functionality is available through a service endpoint that expects GraphQL queries, mounted at /v1/graphql, with the schema generated at build time into crates/client/assets/schema.sdl. The README states that the transaction executor currently performs instant block production and that changes are persisted to RocksDB by default. It also states that the service expects a mutation defined as submit that receives a Transaction in hex encoded binary format. Put together, the data flow is short: a client posts a hex-encoded transaction to the GraphQL endpoint, the executor runs it, a block is produced immediately, and the resulting state is committed to RocksDB. The example log output in the README shows a Committed block line with a block_id and height=0 alongside the binding message, which is what a fresh node looks like when it starts producing. Two flags control this behaviour. Passing --db-type in-memory gives a state that will not persist, which the README recommends for many development purposes. Passing --poa-instant=false disables block production entirely, and the README shows the log line Block production disabled. That second flag matters more than it looks: with instant production on, a local node bakes a block per transaction, so any timing-sensitive test you write against it is testing a chain that does not behave like a scheduled one. The consensus crate list in Cargo.toml includes both bft and poa under crates/services/consensus_module, so the production path is a module you can reason about rather than a hardcoded loop, but the README only documents the PoA instant switch.

Installing fuel-core and running a local network for the first time

There are two routes. The README says that if you plan to use pre-compiled binaries you can go directly to the Ignition node instructions and points at https://docs.fuel.network/docs/node-operator/fuel-ignition/mainnet-node/, which is where the actual operator steps live. If you build from source, the prerequisites come first. On Debian the README gives this set, and clang is called out as a system requirement rather than an optional extra.

apt update
apt install -y cmake pkg-config build-essential git clang libclang-dev

The Rust toolchain then needs the wasm32 target, which the README installs with a single rustup command.

rustup target add wasm32-unknown-unknown

Clone the repository and build. The Makefile's build target is documented as building a release binary with production features.

git clone https://github.com/FuelLabs/fuel-core.git
cd fuel-core
make build

For a throwaway local chain, the README's own example sets the database type to in-memory. You should see the GraphQL provider bind to 127.0.0.1:4000 and a Committed block line for height 0.

./target/debug/fuel-core run --db-type in-memory

If you want a node that accepts transactions but does not produce blocks, the README shows the flag and the log line it produces.

./target/debug/fuel-core run --poa-instant=false

The repository also ships a deployment directory. The README gives the Docker build and the kubectl apply commands, and docker-compose.yml maps port 4000 and mounts a named volume at /mnt/db.

docker build -t fuel-core . -f deployment/Dockerfile
kubectl create -f deployment/fuel-core.yml

The failure modes the README actually documents

Three operational problems are named, and each one is a real constraint rather than a footnote. The first is an outdated database. If fuel-core panics with an error about column families not being opened (the README shows a message listing column-11 down to column-0), the documented fix is to clear the local database with rm -rf ~/.fuel/db. That is a destructive command against the default data directory, and it is the README's own remedy, so treat any schema-affecting upgrade as a migration you have not been given a tool for. The second is file descriptor limits on macOS. The README warns that low defaults lead to Too many open files or even fatal runtime error: Rust cannot catch foreign exceptions when RocksDB hits the limit, and suggests ulimit -n 10240 with a note that it only affects the current shell session. The third is publishing, which is a maintainer concern rather than an operator one, and the README documents troubleshooting it locally with act. Beyond those, the honest limitation is scope. This is a full node. If you want to query Fuel state from an application, you do not need to run one; you need an endpoint. Running fuel-core to answer a handful of GraphQL reads means owning disk growth, log configuration through RUST_LOG, and the upgrade treadmill that the version table implies, because the README pins networks to 0.48.1 while the workspace version is 0.48.3.

Alternatives, and where the difference actually lies

The realistic alternative is not another Fuel node implementation, because the README presents fuel-core as the client implementation of the protocol. The alternative is not running a node at all and using a hosted Fuel endpoint instead. The difference is ownership of state. A hosted endpoint gives you a URL and someone else's uptime, and you never touch RocksDB, never hit the column family panic, and never set ulimit. Running fuel-core gives you the database under ~/.fuel/db, the ability to point --snapshot at a specific genesis, and the ability to run a local network with --db-type in-memory where no state persists between starts. That last capability has no equivalent through a remote endpoint, which is why the README keeps the local network instructions separate from the Ignition node instructions. A second, narrower alternative is to consume the workspace crates directly rather than the binary. Cargo.toml exposes crates/client, crates/types, crates/storage and others as separate members, so a Rust project could depend on a subset. The README does not document that as a supported path, and the licence terms apply to the crates just as they do to the binary, so this is a route to investigate rather than one to assume.

Licence, upgrades and what maintenance costs you

The workspace manifest in Cargo.toml declares license = "BUSL-1.1" for the package metadata, while the repository's licence field is reported as NOASSERTION. Those two facts do not contradict each other so much as leave a gap: the manifest names a licence, and the repository does not assert one in a machine-readable way. The Business Source License is not an open source licence in the usual sense, and the LICENSE file contents are not reproduced in the README, so the change date, the permitted non-production use and the commercial terms are all unverified here. Read LICENSE and SECURITY.md before you build anything commercial on this. On upgrades, the version table is the thing to watch. It lists Fuel Ignition, Testnet and Devnet at 0.48.1 while the workspace version is 0.48.3, so the newest release is not automatically the one the networks run, and the README's source-build instructions for Ignition tell you to check out a specific tag rather than master. The release cadence is uneven: v0.48.1 on 2026-04-30, v0.48.2 on 2026-05-17, v0.48.3 on 2026-08-27. Budget for the database reset when you move between versions, because the README's only documented recovery from a schema mismatch is deleting the data directory.

Editorial conclusion

Adopt fuel-core if you intend to run a node on Fuel Ignition, Testnet or Devnet, or to run a local network for development, and you are willing to keep the binary on the version the target network runs (the README lists 0.48.1 for all three). Do not adopt it as a client library for an application, and do not treat the licence as permissive: the workspace manifest declares BUSL-1.1 with no additional grant, so read LICENSE and SECURITY.md before any commercial use. Before you start, verify the clang and wasm32-unknown-unknown prerequisites, the free space for RocksDB under ~/.fuel/db, and the file descriptor limit on macOS, because the README ties specific failures to each of those.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes