## File: README.md

# Fuel Client

[](https://github.com/FuelLabs/fuel-core/actions/workflows/ci.yml)
[](https://deepwiki.com/FuelLabs/fuel-core)
[](https://crates.io/crates/fuel-core)
[](https://docs.rs/fuel-core/)
[](https://discord.gg/xfpK4Pe)
[](https://x.com/fuel_network)

Fuel client implementation.

## Versions currently used in networks

| Network  | Version |
|----------|---------|
| Fuel Ignition | 0.48.1 |
| Testnet | 0.48.1 |
| Devnet | 0.48.1 |

## Contributing

If you are interested in contributing to Fuel, see our [CONTRIBUTING.md](CONTRIBUTING.md) guidelines for coding standards and review process.

Before pushing any changes or creating pull request please run `source ci_checks.sh`.

## Building

If you plan to use already pre-compiled binaries you can directly go to [Running a Ignition node](#running-a-ignition-node).

### System Requirements

There are several system requirements including clang.

#### MacOS

```bash
brew update
brew install cmake
```

#### Debian

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

#### Arch

```bash
pacman -Syu --needed --noconfirm cmake gcc pkgconf git clang
```

### Rust setup

You'll need `wasm32-unknown-unknown` target installed.

```bash
rustup target add wasm32-unknown-unknown
```


## Running a Ignition node

If you want to participate in the Ignition network with your own node you can launch it following these simple commands.

### From pre-compiled binaries

Follow : https://docs.fuel.network/docs/node-operator/fuel-ignition/mainnet-node/

### From source

Clone the `fuel-core` repository : 
```
git clone https://github.com/FuelLabs/fuel-core.git
```

Go to the latest release tag for ignition on the `fuel-core` repository :
```
git checkout v0.45.1
```

Build your node binary:
```bash
make build
```

To run the node follow : https://docs.fuel.network/docs/node-operator/fuel-ignition/mainnet-node/

## Running a Local network from source

Clone the `fuel-core` repository : 
```
git clone https://github.com/FuelLabs/fuel-core.git
```

Build your node binary:
```bash
make build
```

To run the node follow : https://docs.fuel.network/docs/node-operator/fuel-ignition/local-node/

## Setup to make contributions

### Compiling

We recommend using `xtask` to build fuel-core for development:

```sh
cargo xtask build
```

This will run `cargo build` as well as any other custom build processes we have such as re-generating a GraphQL schema for the client.

### Testing

The [ci_checks.sh](ci_checks.sh) script file can be used to run all CI checks,
including the running of tests.

```shell
source ci_checks.sh
```

The script requires pre-installed tools. For more information run:

```shell
cat ci_checks.sh
```

## Running

The service can be launched by executing `fuel-core run`. The list of options for running can be accessed via the `help` option:

```console
$ ./target/debug/fuel-core run --help

USAGE:
    fuel-core run [OPTIONS]

OPTIONS:
        --snapshot <SNAPSHOT>
          Snapshot from which to do (re)genesis. Defaults to local testnet configuration

          [env: SNAPSHOT=]
        ...
```

For many development purposes it is useful to have a state that won't persist and the `db-type` option can be set to `in-memory` as in the following example.

### Example

```console
$ ./target/debug/fuel-core run --db-type in-memory
2023-06-13T12:45:22.860536Z  INFO fuel_core::cli::run: 230: Block production mode: Instant
2023-06-13T12:38:47.059783Z  INFO fuel_core::cli::run: 310: Fuel Core version v0.18.1
2023-06-13T12:38:47.078969Z  INFO new{name=fuel-core}:_commit_result{block_id=b1807ca9f2eec7e459b866ecf69b68679fc6b205a9a85c16bd4943d1bfc6fb2a height=0 tx_status=[]}: fuel_core_importer::importer: 231: Committed block
2023-06-13T12:38:47.097777Z  INFO new{name=fuel-core}: fuel_core::graphql_api::service: 208: Binding GraphQL provider to 127.0.0.1:4000
```

To disable block production on your local node, set `--poa-instant=false`

### Example

```console
$ ./target/debug/fuel-core run --poa-instant=false
2023-06-13T12:44:12.857763Z  INFO fuel_core::cli::run: 232: Block production disabled
```

### Troubleshooting

#### Publishing

We use [`publish-crates`](https://github.com/katyo/publish-crates) action for automatic publishing of all crates.

If you have problems with publishing, you can troubleshoot it locally with [`act`](https://github.com/nektos/act).

```shell
act release -s GITHUB_TOKEN=<YOUR_GITHUB_TOKEN> -j publish-crates-check --container-architecture linux/amd64 --reuse
```

It requires GitHubToken to do request to the GitHub. You can create it 
with [this](https://docs.github.com/en/enterprise-server@3.4/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) instruction.

#### Outdated database

If you encounter an error such as

```console
thread 'main' panicked at 'unable to open database: DatabaseError(Error { message: "Invalid argument: Column families not opened: column-11, column-10, column-9, column-8, column-7, column-6, column-5, column-4, column-3, column-2, column-1, column-0" })', fuel-core/src/main.rs:23:66
```

Clear your local database using: `rm -rf ~/.fuel/db`

#### File descriptor limits

On some macOS versions the default file descriptor limit is quite low, which can lead to IO errors with messages like `Too many open files` or even `fatal runtime error: Rust cannot catch foreign exceptions` when RocksDB encounters these issues. Use the following command to increase the open file limit. Note that this only affects the current shell session, so consider adding it to `~/.zshrc`.

```bash
ulimit -n 10240
```

#### Log level

The service relies on the environment variable `RUST_LOG`. For more information, check the [EnvFilter examples](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#examples) crate.

Human logging can be disabled with the environment variable `HUMAN_LOGGING=false`

## Debugging

See the guide on [debugging](docs/developers/debugging.md) for an overview on running a debug build of a local node.

## Docker & Kubernetes

```sh
# Create Docker Image
docker build -t fuel-core . -f deployment/Dockerfile

# Delete Docker Image
docker image rm fuel-core

# Create Kubernetes Volume, Deployment & Service
kubectl create -f deployment/fuel-core.yml

# Delete Kubernetes Volume, Deployment & Service
kubectl delete -f deployment/fuel-core.yml
```

## GraphQL service

The client functionality is available through a service endpoint that expect GraphQL queries.

### Transaction executor

The transaction executor currently performs instant block production. Changes are persisted to RocksDB by default.

-   Service endpoint: `/v1/graphql`
-   Schema (available after building): `crates/client/assets/schema.sdl`

The service expects a mutation defined as `submit` that receives a [Transaction](https://github.com/FuelLabs/fuel-vm/tree/master/fuel-tx) in hex encoded binary format, as [specified here](https://github.com/FuelLabs/fuel-specs/blob/master/src/tx-format/transaction.md).

---

## File: benches/README.md

# Fuel Core Benches
This directory contains a set of benchmarks for Fuel Core. The benchmarks are
used for calculating gas metering costs for the Fuel Core VM.

## Running the benchmarks
To run the benchmarks, you can use `cargo bench -p fuel-core-benches` command available.
Alternatively you can use `cargo criterion -p fuel-core-benches` if you have it installed.
For more information on using criterion see [the guide](https://bheisler.github.io/criterion.rs/book/).

## Profiling a benchmark
Sometimes it is useful to produce a flamegraph from a benchmark to verify
you are measuring the correct things.
To do this you can use the `cargo flamegraph` [command](https://github.com/flamegraph-rs/flamegraph).

### Benchmarking a specific function
First build the benchmark with debug symbols:
`CARGO_PROFILE_RELEASE_DEBUG=true cargo-criterion -p fuel-core-benches --no-run`
Then you need to find the actual test binary that was built:
`ls target/release/deps/vm* -lat | head -1`
Should give you something like:
`target/release/deps/vm-a17190f2ca5e7169`
Then you can run the benchmark with the `flamegraph` command (runs the bench for 10 seconds):
`flamegraph target/release/deps/vm-a17190f2ca5e7169 --bench bench_name --profile-time 10`
For example if you want to profile the `swwq` op you would do (it's regex):
`flamegraph target/release/deps/vm-a17190f2ca5e7169 --bench '^swwq/swwq$' --profile-time 10`
Or for a dependent bench you would do:
`flamegraph target/release/deps/vm-a17190f2ca5e7169 --bench '^srwq/100$' --profile-time 10`

## Using `collect` to generate bench data
Firstly you should run the benchmarks and collect the output:
`cargo criterion -p fuel-core-benches --message-format json --bench vm > bench.json`
You could just pipe the output into the collect binary but benches are slow to run
so I suggest saving the output like above.

Then you can run the `collect` binary to generate the data you want:
`cargo run -p fuel-core-benches --bin collect --release -- --input bench.json`
This will generate a `gas-costs.yaml` file in the current directory like:
```yaml
burn: 35
call:
  base: 311
  dep_per_unit: 14
```
There are multiple output options. See `collect --help` for more information.

### Generating the `fuel-vm` `default-gas-costs.rs`
Do the same as above except run the following `collect` command.
`cargo run -p fuel-core-benches --bin collect --release -- --input bench.json -f rust --output default-gas-costs.rs`
This will generate a `default-gas-costs.rs` file in the current directory like:
```rust
```

This file can then replace the one in `fuel-vm/src/gas/default-gas-costs.rs`.

---

## File: bin/fuel-core/chainspec/local-testnet/README.md

# The configuration of the local network

## Chain config
- The `ChainId` is `0`.
- The initial `privileged_address` which can perform the network upgrade:
    ```shell
    {"address":"9f0e19d6c2a6283a3222426ab2630d35516b1799b503f37b02105bebe1b8a3e9","secret":"d80a243ef91956f626d1dad2f23bdfeb73fd0b363282b1eb2227ac5964144afb","type":"block_production"}
    ```
- The public address of the authority node that produces blocks: 
    ```shell
    {"address":"e0a9fcde1b73f545252e01b30b50819eb9547d07531fa3df0385c5695736634d","secret":"4dd0cdca64ef56a01fc81891f9beb6d898f19a22b2e287bce91d807fdf46589a","type":"block_production"}
    ```
- The block gas limit is `30000000`.

### Gas costs

The gas costs was created from the [benchmarks_fuel_core_0_35_0.json](benchmarks_fuel_core_0_35_0.json) benchmark results.
The `new_storage_per_byte` is manually set to be `63`.
The `gtf` is manually set to be `13`.

## State config
- The `coinbase` address hard coded in the genesis contract: 
    ```shell
    {"address":"7b4b30b2437b0073e5ba5a9324cf55831d180a89f66332b541827e12e647b751","secret":"9e24cfa071f6c1c4984a17ecf18061a8d0c9c304e7dd7703788bd122bd578650","type":"block_production"}
    ```
- Contains many wallets with fake ETHs:
  - Wallet 1:
    ```shell
    {"address":"6b63804cfbf9856e68e5b6e7aef238dc8311ec55bec04df774003a2c96e0418e","secret":"de97d8624a438121b86a1956544bd72ed68cd69f2c99555b08b1e8c51ffd511c","type":"block_production"}
    ```
- The base asset contract source code is taken from [here](https://github.com/FuelLabs/fuel-bridge/tree/b0ebf0b01a903f1866156b7c370ff03d6fb4ec49/packages/base-asset).
  - The `ContractId` of the contract is `0x7e2becd64cd598da59b4d1064b711661898656c6b1f4918a787156b8965dc83c`.
  - The derived(`SubId` is `0000000000000000000000000000000000000000000000000000000000000000`) base `AssetId` from this contract is `0xf8f8b6283d7fa5b672b530cbb84fcccb4ff8dc40f8176ef4544ddb1f1952ad07`.

---

## File: bin/e2e-test-client/README.md

# Fuel Core E2E Test Client

The test client provides a suite of idempotent tests intended to validate remote environments.

To customize the suite parameters for an existing node deployment, set the `FUEL_CORE_E2E_CONFIG` environment variable with a path to a valid configuration toml.

When `FUEL_CORE_E2E_CONFIG` is unset a default configuration is used which is suitable for local environment testing. The default configuration is:

```toml
endpoint = "http://localhost:4000"
wallet_sync_timeout = "10s"
full_test = false
coinbase_contract_id = "7777777777777777777777777777777777777777777777777777777777777777"


[wallet_a]
secret = "de97d8624a438121b86a1956544bd72ed68cd69f2c99555b08b1e8c51ffd511c"

[wallet_b]
secret = "37fa81c84ccd547c30c176b118d5cb892bdb113e8e80141f266519422ef9eefd"
```

```shell
FUEL_CORE_E2E_CONFIG="/Users/your_user_name/fuel/e2e.toml" cargo run -p fuel-core-e2e-client -- --nocapture
```

---

## File: ci/README.md

CI Tooling
===

Cross-platform compilation is handled using [cross](https://github.com/cross-rs/cross). 
This is because cross ensures binaries will run on as many platforms as possible. 
It also works-around various [bugs](https://github.com/rust-lang/rust-bindgen/issues/1229) 
in rust bind-gen that prevent us from simply using `--target` with cargo to cross-compile.

We use custom extensions of the docker images provided by cross 
in order to support building rocksdb with clang. Each target requires its own dockerfile,
as they all have slightly different distros, package managers and compiler toolchains.

To test cross compilation of fuel core locally, build the provided dockerfiles
with the image tags expected by Cross.toml using the helper script: 

```shell
./build-images.sh
```

To cross-compile fuel core for a supported target, you can build it as you
would with cargo but using cross instead:

```shell
cargo install cross
cross build --profile=release --target ${target} -p fuel-core
```

---

## File: crates/trace/README.md

# Fuel Core Trace
This crate provides a simple way to enable tracing for tests across the fuel repo.

## Usage
To enable tracing for a test, add the following to the lib.rs file of the crate you want to trace:
```rust
#[cfg(test)]
fuel_core_trace::enable_tracing!();
```
If you also want tracing in your integration tests, you need to add the above to each integration tests file.

Tracing is still disabled by default so to enable it set the following environment variable:
```bash
export FUEL_TRACE=1
```
Or if you just want it for a single test run:
```bash
FUEL_TRACE=1 cargo test
```

Now you will have error level tracing like:
```
2023-01-25T02:27:14.362856Z ERROR works: tracing: I'm visible if FUEL_TRACE=1 is set
```

You can use the `RUST_LOG` environment variable to control the level of tracing you want to see. For example:
```bash
FUEL_TRACE=1 RUST_LOG=trace cargo test
```
### Additional Subscribers
You can set a few different types of subscribers:

Compact output:
```bash
FUEL_TRACE=compact cargo test
```
Pretty output:
```bash
FUEL_TRACE=pretty cargo test
```
Log to file:
```bash
FUEL_TRACE=log-file cargo test
```
Log to file and output to console:
```bash
FUEL_TRACE=log-show cargo test
```
You can also set the log file path:
```bash
FUEL_TRACE_PATH=/some/path FUEL_TRACE=log-file cargo test
```
If you don't set the path, it will default to `CARGO_MANIFEST_DIR/logs/logfile`.

---

## File: crates/services/consensus_module/poa/README.md

# Fuel Core PoA Manager

Coordinates block production in a PoA network. This is used as a stopgap until a PoS network is implemented, but also useful for testing.

For the PoS implementation, see [`fuel-core-bft`](../bft/),