Crate fuel_asm

FuelVM instruction and opcodes representation.

Fuel ASM

Instruction set for the FuelVM.

Compile features

• std: Unless set, the crate will link to the core-crate instead of the std-crate. More info here.
• serde: Add support for serde for the types exposed by this crate.

Example

use fuel_asm::*;

// A sample program to perform ecrecover
let program = vec![
    op::move_(0x10, 0x01),     // set r[0x10] := $one
    op::slli(0x20, 0x10, 5),   // set r[0x20] := `r[0x10] << 5 == 32`
    op::slli(0x21, 0x10, 6),   // set r[0x21] := `r[0x10] << 6 == 64`
    op::aloc(0x21),            // alloc `r[0x21] == 64` to the heap
    op::addi(0x10, 0x07, 1),   // set r[0x10] := `$hp + 1` (allocated heap)
    op::move_(0x11, 0x04),     // set r[0x11] := $ssp
    op::add(0x12, 0x04, 0x20), // set r[0x12] := `$ssp + r[0x20]`
    op::eck1(0x10, 0x11, 0x12),// recover public key in memory[r[0x10], 64]
    op::ret(0x01),             // return `1`
];

// Convert program to bytes representation
let bytes: Vec<u8> = program.iter().copied().collect();

// A program can be reconstructed from an iterator of bytes
let restored: Result<Vec<Instruction>, _> = fuel_asm::from_bytes(bytes).collect();
assert_eq!(program, restored.unwrap());

// Every instruction can be described as `u32` big-endian bytes
let halfwords: Vec<u32> = program.iter().copied().collect();
let bytes = halfwords.iter().copied().map(u32::to_be_bytes).flatten();
let restored: Result<Vec<Instruction>, _> = fuel_asm::from_bytes(bytes).collect();
assert_eq!(program, restored.unwrap());

// We can also reconstruct the instructions individually
let restored: Result<Vec<Instruction>, _> = fuel_asm::from_u32s(halfwords).collect();
assert_eq!(program, restored.unwrap());

// An instruction is composed by the opcode representation, register IDs and immediate value.
let instruction = program[1];
assert_eq!(instruction.opcode(), Opcode::SLLI);
let slli = match instruction {
    Instruction::SLLI(slli) => slli,
    _ => panic!("unexpected instruction"),
};
let (ra, rb, imm) = slli.unpack();
assert_eq!(u8::from(ra), 0x20);
assert_eq!(u8::from(rb), 0x10);
assert_eq!(u32::from(imm), 5);

Re-exports

pub use args::wideint;

pub use args::GMArgs;

pub use args::GTFArgs;

Modules

macros

The impl_instructions! macro

op

Definitions and implementations for each unique instruction type, one for each unique Opcode variant.

Macros

enum_try_from

Defines the enum with TryFrom trait implementation.

Structs

Flags

Possible values for the FLAG instruction. See https://github.com/FuelLabs/fuel-specs/blob/master/src/fuel-vm/index.md#flags

Imm06

Represents a 6-bit immediate value, guaranteed to be masked by construction.

Imm12

Represents a 12-bit immediate value, guaranteed to be masked by construction.

Imm18

Represents a 18-bit immediate value, guaranteed to be masked by construction.

Imm24

Represents a 24-bit immediate value, guaranteed to be masked by construction.

InvalidOpcode

Given opcode doesn’t exist, or is the reserved part of the instruction (i.e. space outside arguments) is non-zero.

PanicInstruction

Describe a panic reason with the instruction that generated it

RegId

Represents a 6-bit register ID, guaranteed to be masked by construction.

Enums

Instruction

Representation of a single instruction for the interpreter.

Opcode

Solely the opcode portion of an instruction represented as a single byte.

PanicReason

Panic reason representation for the interpreter.

Traits

CheckRegId

Type is convertible to a RegId

Functions

from_bytes

Given an iterator yielding bytes, produces an iterator yielding Instructions.

from_u32s

Given an iterator yielding u32s (i.e. “half words” or “raw instructions”), produces an iterator yielding Instructions.

Type Aliases

RawInstruction

An instruction in its raw, packed, unparsed representation.

RegisterId

Register ID type

Word

Register value type