Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/FuelLabs/fuel-vm
Fuel v2 interpreter in Rust
https://github.com/FuelLabs/fuel-vm
blockchain fuel vm
Last synced: 8 days ago
JSON representation
Fuel v2 interpreter in Rust
- Host: GitHub
- URL: https://github.com/FuelLabs/fuel-vm
- Owner: FuelLabs
- License: other
- Created: 2021-06-02T02:13:24.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-17T12:00:33.000Z (23 days ago)
- Last Synced: 2024-10-17T13:45:36.061Z (23 days ago)
- Topics: blockchain, fuel, vm
- Language: Rust
- Homepage:
- Size: 165 MB
- Stars: 354
- Watchers: 26
- Forks: 87
- Open Issues: 39
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-blockchain-rust - FuelVM
README
# Fuel execution environment
[](https://github.com/FuelLabs/fuel-vm/actions/workflows/ci.yml)[](https://discord.gg/xfpK4Pe)
The repository contains crates implementing the
[FuelVM specification](https://github.com/FuelLabs/fuel-specs/blob/master/src/fuel-vm/index.md)
used by [fuel-core](https://github.com/FuelLabs/fuel-core)
and [the Sway compiler](https://github.com/FuelLabs/sway/).
## Crates living here
| Crate | Version | Description |
|--------------|-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| fuel-asm | [](https://crates.io/crates/fuel-asm) | Contains the FuelVM instruction set - opcodes used by the Sway and VM. |
| fuel-compression | [](https://crates.io/crates/fuel-compression) | DA-layer compression of Fuel transaction types |
| fuel-crypto | [](https://crates.io/crates/fuel-crypto) | Cryptographic primitives used across Fuel Rust based projects. |
| fuel-merkle | [](https://crates.io/crates/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 | [](https://crates.io/crates/fuel-storage) | Storage abstraction is used to connect FuelVM, `fuel-merkle`, and `fuel-core` together without direct access. |
| fuel-tx | [](https://crates.io/crates/fuel-tx) | Contains a definition of types from the specification, with canonical serialization and deserialization. The `Transaction` and `Checked` type implements fee calculation and validation of rules defined by the specification. |
| fuel-types | [](https://crates.io/crates/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 | [](https://crates.io/crates/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](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
```
## 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](https://github.com/FuelLabs/fuel-vm/tree/master/fuel-vm/src/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:
```rust
#[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:
```rust
#[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.