- Instruction Set
- VM Initialization
- Predicate Verification
- Script Execution
- Call Frames
This document provides the specification for the Fuel Virtual Machine (FuelVM). The specification covers the types, instruction set, and execution semantics.
|Maximum contract size, in bytes.|
|Maximum memory access size, in bytes.|
|Maximum size of message data, in bytes.|
FuelVM instructions are exactly 32 bits (4 bytes) wide and comprise of a combination of:
- Opcode: 8 bits
- Register/special register (see below) identifier: 6 bits
- Immediate value: 12, 18, or 24 bits, depending on operation
Of the 64 registers (6-bit register address space), the first
16 are reserved:
|zero||Contains zero (|
|one||Contains one (|
|overflow||Contains overflow/underflow of addition, subtraction, and multiplication.|
|program counter||The program counter. Memory address of the current instruction.|
|stack start pointer||Memory address of bottom of current writable stack area.|
|stack pointer||Memory address on top of current writable stack area (points to free memory).|
|frame pointer||Memory address of beginning of current call frame.|
|heap pointer||Memory address below the current bottom of the heap (points to free memory).|
|error||Error codes for particular operations.|
|global gas||Remaining gas globally.|
|context gas||Remaining gas in the context.|
|balance||Received balance for this context.|
|instrs start||Pointer to the start of the currently-executing code.|
|return value||Return value or pointer.|
|return length||Return value length in bytes.|
Integers are represented in big-endian format, and all operations are unsigned. Boolean
0 and Boolean
Registers are 64 bits (8 bytes) wide. Words are the same width as registers.
Persistent state (i.e. storage) is a key-value store with 32-byte keys and 32-byte values. Each contract has its own persistent state that is independent of other contracts. This is committed to in a Sparse Binary Merkle Tree.
|If bit is set, safe arithmetic and logic is disabled.|
|If bit is set, wrapping does not cause panic.|
A complete instruction set of the Fuel VM is documented in the following page.
Every time the VM runs, a single monolithic memory of size
VM_MAX_RAM bytes is allocated, indexed by individual byte. A stack and heap memory model is used, allowing for dynamic memory allocation in higher-level languages. The stack begins at
0 and grows upward. The heap begins at
VM_MAX_RAM - 1 and grows downward.
To initialize the VM, the following is pushed on the stack sequentially:
- Transaction hash (
byte, word-aligned), computed as defined here.
(asset_id: byte, balance: uint64), of:
- Transaction length, in bytes (
- The transaction, serialized.
Then the following registers are initialized (without explicit initialization, all registers are initialized to zero):
$ssp = 32 + MAX_INPUTS*(32+8) + size(tx)): the writable stack area starts immediately after the serialized transaction in memory (see above).
$sp = $ssp: writable stack area is empty to start.
$hp = VM_MAX_RAM - 1: the heap area begins at the top and is empty to start.
- External: predicate and script.
$fpwill be zero.
- Internal: call.
$fpwill be non-zero.
Returning from a context behaves differently depending on whether the context is external or internal.
For each such input in the transaction, the VM is initialized, then:
$isare set to the start of the input's
During predicate mode, hitting any of the following instructions causes predicate verification to halt, returning Boolean
- Any contract instruction.
- JMP, JI, JNE, JNEI, or JNZI with jump-to value less than or equal to
$pc(these would allow loops). In other words,
$pcmust be strictly increasing.
In addition, during predicate mode if
$pc is set to a value greater than the end of predicate bytecode (this would allow bytecode outside the actual predicate), predicate verification halts returning Boolean
A predicate that halts without returning Boolean
true does not pass verification, making the entire transaction invalid. Note that predicate validity is monotonic with respect to time (i.e. if a predicate evaluates to
true then it will always evaluate to
true in the future).
If script bytecode is present, transaction validation requires execution.
The VM is initialized, then:
$isare set to the start of the transaction's script bytecode.
$cgasare set to
Following initialization, execution begins.
For each instruction, its gas cost
gc is first computed. If
gc > $cgas, deduct
$cgas (i.e. spend all of
$cgas and no more), then revert immediately without actually executing the instruction. Otherwise, deduct
Cross-contract calls push a call frame onto the stack, similar to a stack frame used in regular languages for function calls (which may be used by a high-level language that targets the FuelVM). The distinction is as follows:
- Stack frames: store metadata across trusted internal (i.e. intra-contract) function calls. Not supported natively by the FuelVM, but may be used as an abstraction at a higher layer.
- Call frames: store metadata across untrusted external (i.e. inter-contract) calls. Supported natively by the FuelVM.
Call frames are needed to ensure that the called contract cannot mutate the running state of the current executing contract. They segment access rights for memory: the currently-executing contracts may only write to their own call frame and their own heap.
A call frame consists of the following, word-aligned:
|Unwritable area begins.|
|32||Contract ID for this call.|
|32||asset ID of forwarded coins.|
|8*64||Saved registers from previous context.|
|8||Code size in bytes, padded to word alignment.|
|1*||Zero-padded to 8-byte alignment, but individual instructions are not aligned.|
|Unwritable area ends.|
|*||Call frame's stack.|
If the context is external, the owned memory range is:
[$ssp, $sp): the writable stack area.
($hp, VM_MAX_RAM - 1]: the heap area allocated by this script or predicate.
If the context is internal, the owned memory range for a call frame is:
[$ssp, $sp): the writable stack area of the call frame.
($hp, $fp->$hp]: the heap area allocated by this call frame.