nolletmatilde / fuel-vm

Fuel v2 interpreter in Rust

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-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::Absolute, 0, 0, 100 => Ok(4); "absolute 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 test_helpers::run_script.

For example:

#[test]
fn dynamic_call_frame_ops_bug_missing_ssp_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.