Fuel execution environment

The repository contains crates implementing the FuelVM specification used by fuel-core and the Sway compiler.

Crates living here

| Crate | Version | Description | |--------------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | fuel-asm | | Contains the FuelVM instruction set - opcodes used by the Sway and VM. | | fuel-compression | | DA-layer compression of Fuel transaction types | | fuel-crypto | | Cryptographic primitives used across Fuel Rust based projects. | | fuel-merkle | | Implementations of the Merkle Tree used by the fuel-core to fulfill fraud proofs requirements, and fuel-tx to validate transaction validity. | | fuel-storage | | Storage abstraction is used to connect FuelVM, fuel-merkle, and fuel-core together without direct access. | | fuel-tx | | Contains a definition of types from the specification, with canonical serialization and deserialization. The Transaction and Checked<Tx> type implements fee calculation and validation of rules defined by the specification. | | fuel-types | | Atomic types are used by almost all Fuel Rust-based crates. The crate defines the most common entities and implements their serialization/deserialization. | | fuel-vm | | The VM itself executes fuel-asm opcodes generated by the Sway compiler. It is used as a core component of the fuel-core block executor to validate, estimate, and execute Create and Script transactions. |

Testing

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

source ci_checks.sh

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

cat ci_checks.sh

Bug reporting and reproduction

If you find any bug or unexpected behavior, please open an issue. It would be helpful to provide a scenario of how to reproduce the problem:

A text description of the problem(maybe with links)
A runnable script with instruction
A repository with reproduction code and instructions on how to compile/run
A unit test with the usage of the pure opcodes from fuel-asm

How to use pure opcodes

The fuel-vm has many unit tests, almost for each opcode. Supporting a huge test codebase requires proper test utils that you can re-use to reproduce a bug.

Add a new test case

If a specific opcode has unexpected behaviors, maybe there is a unit test already that you can reuse to reproduce a bug. You need to add a new test_case like:

#[test_case(JumpMode::RelativeIS, 0, 0, 100 => Ok(4); "is-relative jump")]

Before the test and run this specific test or all tests.

Build custom scripts

If you need to write your own specific script and run it, you can use testhelpers::runscript.

For example:

#[test]
fn dynamiccallframeopsbugmissingssp_check() {
    let ops = vec![
        op::cfs(RegId::SP),
        op::slli(0x10, RegId::ONE, 26),
        op::aloc(0x10),
        op::sw(RegId::ZERO, 0x10, 0),
        op::ret(RegId::ONE),
    ];
    let receipts = run_script(ops);
    assert_panics(&receipts, PanicReason::MemoryOverflow);
}

It returns receipts that contain result of execution. The assert_panics can be used to check for panics.

Build custom transactions

The fuel-tx provides fuel_tx::TransactionBuilder that simplifies the building of custom transaction for testing purposes.

You can check how TransactionBuilder::script or TransactionBuilder::create are used for better understanding.

🔗 More in this category