Skip to content

FuelLabs/fuel-vm

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date
Aug 5, 2023
Aug 1, 2023
Aug 19, 2023
Aug 19, 2023
Aug 19, 2023
Aug 8, 2023
Jun 13, 2023
Aug 19, 2023
Aug 19, 2023
Aug 19, 2023
Jul 25, 2023
Jun 13, 2023
Aug 19, 2023
Aug 15, 2023
Mar 21, 2023
Aug 8, 2023
Aug 5, 2023
Apr 27, 2022

Repository files navigation

Fuel execution environment

builddiscord

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

Crates living here

Crate Version Description
fuel-asm crates.io Contains the FuelVM instruction set - opcodes used by the Sway and VM.
fuel-crypto crates.io Cryptographic primitives used across Fuel Rust based projects.
fuel-merkle crates.io Implementations of the Merkle Tree used by the fuel-core to fulfill fraud proofs requirements, and fuel-tx to validate transaction validity.
fuel-storage crates.io Storage abstraction is used to connect FuelVM, fuel-merkle, and fuel-core together without direct access.
fuel-tx crates.io 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 crates.io 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 crates.io 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.