Icon LinkFuelVM Instruction Set

• Reading Guide
• Arithmetic/Logic (ALU) Instructions
  • ADD: Add
  • ADDI: Add immediate
  • AND: AND
  • ANDI: AND immediate
  • DIV: Divide
  • DIVI: Divide immediate
  • EQ: Equals
  • EXP: Exponentiate
  • EXPI: Exponentiate immediate
  • GT: Greater than
  • LT: Less than
  • MLOG: Math logarithm
  • MOD: Modulus
  • MODI: Modulus immediate
  • MOVE: Move
  • MOVI: Move immediate
  • MROO: Math root
  • MUL: Multiply
  • MULI: Multiply immediate
  • MLDV: Fused multiply-divide
  • NOOP: No operation
  • NOT: Invert
  • OR: OR
  • ORI: OR immediate
  • SLL: Shift left logical
  • SLLI: Shift left logical immediate
  • SRL: Shift right logical
  • SRLI: Shift right logical immediate
  • SUB: Subtract
  • SUBI: Subtract immediate
  • SUBI: Subtract immediate
  • WDCM: 128-bit integer comparison
  • WQCM: 256-bit integer comparison
  • WDOP: Misc 128-bit integer operations
  • WQOP: Misc 256-bit integer operations
  • WDML: Multiply 128-bit integers
  • WQML: Multiply 256-bit integers
  • WDDV: 128-bit integer division
  • WQDV: 256-bit integer division
  • WDMD: 128-bit integer fused multiply-divide
  • WQMD: 256-bit integer fused multiply-divide
  • WDAM: Modular 128-bit integer addition
  • WQAM: Modular 256-bit integer addition
  • WDMM: Modular 128-bit integer multiplication
  • WQMM: Modular 256-bit integer multiplication
  • XOR: XOR
  • XORI: XOR immediate
• Control Flow Instructions
  • JMP: Jump
  • JI: Jump immediate
  • JNE: Jump if not equal
  • JNEI: Jump if not equal immediate
  • JNZI: Jump if not zero immediate
  • JMPB: Jump relative backwards
  • JMPF: Jump relative forwards
  • JNZB: Jump if not zero relative backwards
  • JNZF: Jump if not zero relative forwards
  • JNEB: Jump if not equal relative backwards
  • JNEF: Jump if not equal relative forwards
  • RET: Return from context
• Memory Instructions
  • ALOC: Allocate memory
  • CFE: Extend call frame
  • CFEI: Extend call frame immediate
  • CFS: Shrink call frame
  • CFSI: Shrink call frame immediate
  • LB: Load byte
  • LW: Load word
  • MCL: Memory clear
  • MCLI: Memory clear immediate
  • MCP: Memory copy
  • MCPI: Memory copy immediate
  • MEQ: Memory equality
  • POPH: Pop a set of high registers from stack
  • POPL: Pop a set of low registers from stack
  • PSHH: Push a set of high registers to stack
  • PSHL: Push a set of low registers to stack
  • SB: Store byte
  • SW: Store word
• Contract Instructions
  • BAL: Balance of contract ID
  • BHEI: Block height
  • BHSH: Block hash
  • BURN: Burn existing coins
  • CALL: Call contract
  • CB: Coinbase contract id
  • CCP: Code copy
  • CROO: Code Merkle root
  • CSIZ: Code size
  • LDC: Load code from an external contract
  • LOG: Log event
  • LOGD: Log data event
  • MINT: Mint new coins
  • RETD: Return from context with data
  • RVRT: Revert
  • SMO: Send message to output
  • SCWQ: State clear sequential 32 byte slots
  • SRW: State read word
  • SRWQ: State read sequential 32 byte slots
  • SWW: State write word
  • SWWQ: State write sequential 32 byte slots
  • TIME: Timestamp at height
  • TR: Transfer coins to contract
  • TRO: Transfer coins to output
• Cryptographic Instructions
  • ECK1: Secp251k1 signature recovery
  • ECR1: Secp256r1 signature recovery
  • ED19: EdDSA curve25519 verification
  • K256: keccak-256
  • S256: SHA-2-256
• Other Instructions
  • ECAL: Call external function
  • FLAG: Set flags
  • GM: Get metadata
  • GTF: Get transaction fields

Icon LinkReading Guide

This page provides a description of all instructions for the FuelVM. Encoding is read as a sequence of one 8-bit value (the opcode identifier) followed by four 6-bit values (the register identifiers or immediate value). A single i indicates a 6-bit immediate value, i i indicates a 12-bit immediate value, i i i indicates an 18-bit immediate value, and i i i i indicates a 24-bit immediate value. All immediate values are interpreted as big-endian unsigned integers.

• The syntax MEM[x, y] used in this page means the memory range starting at byte x, of length y bytes.
• The syntax STATE[x, y] used in this page means the sequence of storage slots starting at key x and spanning y bytes.

Icon LinkPanics

Some instructions may panic, i.e. enter an unrecoverable state. Additionally, attempting to execute an instruction not in this list causes a panic and consumes no gas. How a panic is handled depends on context :

• In a predicate context, cease VM execution and return false.
• In other contexts, revert (described below).

On a non-predicate panic, append a receipt to the list of receipts:

then append an additional receipt to the list of receipts:

Icon LinkReceipts

The number of receipts is limited to 216, with the last two reserved to panic and script result receipts. Trying to add any other receipts after 216-2 will panic.

Icon LinkEffects

A few instructions are annotated with the effects they produce, the table below explains each effect:

If an instruction is not annotated with an effect, it means it does not produce any of the aforementioned affects.

Icon LinkArithmetic/Logic (ALU) Instructions

All these instructions advance the program counter $pc by 4 after performing their operation.

Normally, if the result of an ALU operation is mathematically undefined (e.g. dividing by zero), the VM panics. However, if the F_UNSAFEMATH flag is set, $err is set to true and execution continues.

If an operation would overflow, so that the result doesn't fit into the target field, the VM will panic. Results below zero are also considered overflows. If the F_WRAPPING flag is set, instead $of is set to true or the overflowing part of the result, depending on the operation.

Icon LinkADD: Add

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

Icon LinkADDI: Add immediate

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

Icon LinkAND: AND

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkANDI: AND immediate

Panic if:

• $rA is a reserved register

imm is extended to 64 bits, with the high 52 bits set to 0.

$of and $err are cleared.

Icon LinkDIV: Divide

Panic if:

• $rA is a reserved register

If $rC == 0, $rA is cleared and $err is set to true.

Otherwise, $err is cleared.

$of is cleared.

Icon LinkDIVI: Divide immediate

Panic if:

• $rA is a reserved register

If imm == 0, $rA is cleared and $err is set to true.

Otherwise, $err is cleared.

$of is cleared.

Icon LinkEQ: Equals

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkEXP: Exponentiate

Panic if:

• $rA is a reserved register

If the result cannot fit in 8 bytes, $of is set to 1 and $rA is instead set to 0, otherwise $of is cleared.

$err is cleared.

Icon LinkEXPI: Exponentiate immediate

Panic if:

• $rA is a reserved register

If the result cannot fit in 8 bytes, $of is set to 1 and $rA is instead set to 0, otherwise $of is cleared.

$err is cleared.

Icon LinkGT: Greater than

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkLT: Less than

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkMLOG: Math logarithm

Panic if:

• $rA is a reserved register

If $rB == 0, both $rA and $of are cleared and $err is set to true.

If $rC <= 1, both $rA and $of are cleared and $err is set to true.

Otherwise, $of and $err are cleared.

Icon LinkMOD: Modulus

Panic if:

• $rA is a reserved register

If $rC == 0, both $rA and $of are cleared and $err is set to true.

Otherwise, $of and $err are cleared.

Icon LinkMODI: Modulus immediate

Panic if:

• $rA is a reserved register

If imm == 0, both $rA and $of are cleared and $err is set to true.

Otherwise, $of and $err are cleared.

Icon LinkMOVE: Move

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkMOVI: Move immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkMROO: Math root

Panic if:

• $rA is a reserved register

If $rC == 0, both $rA and $of are cleared and $err is set to true.

Otherwise, $of and $err are cleared.

Icon LinkMUL: Multiply

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

Icon LinkMULI: Multiply immediate

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

Icon LinkMLDV: Fused multiply-divide

If the divisor ($rD) is zero, then instead the value is divided by 1 << 64. This returns the higher half of the 128-bit multiplication result. This operation never overflows.

If the result of after the division doesn't fit into a register, $of is assigned the overflow of the operation. Otherwise, $of is cleared.

$err is cleared.

Icon LinkNOOP: No operation

$of and $err are cleared.

Icon LinkNOT: Invert

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkOR: OR

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkORI: OR immediate

Panic if:

• $rA is a reserved register

imm is extended to 64 bits, with the high 52 bits set to 0.

$of and $err are cleared.

Icon LinkSLL: Shift left logical

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkSLLI: Shift left logical immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkSRL: Shift right logical

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkSRLI: Shift right logical immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkSUB: Subtract

Panic if:

• $rA is a reserved register

$of is assigned the underflow of the operation, as though $of is the high byte of a 128-bit register.

$err is cleared.

Icon LinkSUBI: Subtract immediate

Panic if:

• $rA is a reserved register

$of is assigned the underflow of the operation, as though $of is the high byte of a 128-bit register.

$err is cleared.

Icon LinkWDCM: 128-bit integer comparison

The six-bit immediate value is used to select operating mode, as follows:

Then the actual operation that's performed:

The leading zero count can be used to compute rounded-down log2 of a number using the following formula TOTAL_BITS - 1 - lzc(n). Note that log2(0) is undefined, and will lead to integer overflow with this method.

Clears $of and $err.

Panic if:

• A reserved compare mode is given
• $rA is a reserved register
• $rB + 16 overflows or > VM_MAX_RAM
• indirect == 1 and $rC + 16 overflows or > VM_MAX_RAM

Icon LinkWQCM: 256-bit integer comparison

The immediate value is interpreted identically to WDCM.

Clears $of and $err.

Panic if:

• A reserved compare mode is given
• $rA is a reserved register
• $rB + 32 overflows or > VM_MAX_RAM
• indirect == 1 and $rC + 32 overflows or > VM_MAX_RAM

Icon LinkWDOP: Misc 128-bit integer operations

The six-bit immediate value is used to select operating mode, as follows:

Then the actual operation that's performed:

Operations behave $of and $err similarly to their 64-bit counterparts, except that $of is set to 1 instead of the overflowing part.

Panic if:

• Reserved bits of the immediate are set
• The memory range MEM[$rA, 16] does not pass ownership check
• $rB + 16 overflows or > VM_MAX_RAM
• indirect == 1 and $rC + 16 overflows or > VM_MAX_RAM

Icon LinkWQOP: Misc 256-bit integer operations

The immediate value is interpreted identically to WDOP.

Operations behave $of and $err similarly to their 64-bit counterparts.

Panic if:

• Reserved bits of the immediate are set
• The memory range MEM[$rA, 32] does not pass ownership check
• $rB + 32 overflows or > VM_MAX_RAM
• indirect == 1 and $rC + 32 overflows or > VM_MAX_RAM

Icon LinkWDML: Multiply 128-bit integers

The six-bit immediate value is used to select operating mode, as follows:

$of is set to 1 in case of overflow, and cleared otherwise.

$err is cleared.

Panic if:

• Reserved bits of the immediate are set
• The memory range MEM[$rA, 16] does not pass ownership check
• indirect0 == 1 and $rB + 16 overflows or > VM_MAX_RAM
• indirect1 == 1 and $rC + 16 overflows or > VM_MAX_RAM

Icon LinkWQML: Multiply 256-bit integers

The immediate value is interpreted identically to WDML.

$of is set to 1 in case of overflow, and cleared otherwise.

$err is cleared.

Panic if:

• Reserved bits of the immediate are set
• The memory range MEM[$rA, 32] does not pass ownership check
• indirect0 == 1 and $rB + 32 overflows or > VM_MAX_RAM
• indirect1 == 1 and $rC + 32 overflows or > VM_MAX_RAM

Icon LinkWDDV: 128-bit integer division

The six-bit immediate value is used to select operating mode, as follows:

$of is cleared.

If the rhs operand is zero, MEM[$rA, 16] is cleared and $err is set to true. Otherwise, $err is cleared.

Panic if:

• Reserved bits of the immediate are set
• The memory range MEM[$rA, 16] does not pass ownership check
• $rB + 16 overflows or > VM_MAX_RAM
• indirect == 1 and $rC + 16 overflows or > VM_MAX_RAM

Icon LinkWQDV: 256-bit integer division

The immediate value is interpreted identically to WDDV.

$of is cleared.

If the rhs operand is zero, MEM[$rA, 32] is cleared and $err is set to true. Otherwise, $err is cleared.

Panic if:

• Reserved bits of the immediate are set
• The memory range MEM[$rA, 32] does not pass ownership check
• $rB + 32 overflows or > VM_MAX_RAM
• indirect == 1 and $rC + 32 overflows or > VM_MAX_RAM

Icon LinkWDMD: 128-bit integer fused multiply-divide

If the divisor MEM[$rA, 16] is zero, then instead the value is divided by 1 << 128. This returns the higher half of the 256-bit multiplication result.

If the result of after the division is larger than operand size, $of is set to one. Otherwise, $of is cleared.

$err is cleared.

Panic if:

• The memory range MEM[$rA, 16] does not pass ownership check
• $rB + 16 overflows or > VM_MAX_RAM
• $rC + 16 overflows or > VM_MAX_RAM
• $rD + 16 overflows or > VM_MAX_RAM

Icon LinkWQMD: 256-bit integer fused multiply-divide

If the divisor MEM[$rA, 32] is zero, then instead the value is divided by 1 << 256. This returns the higher half of the 512-bit multiplication result.

If the result of after the division is larger than operand size, $of is set to one. Otherwise, $of is cleared.

$err is cleared.

Panic if:

• The memory range MEM[$rA, 32] does not pass ownership check
• $rB + 32 overflows or > VM_MAX_RAM
• $rC + 32 overflows or > VM_MAX_RAM
• $rD + 32 overflows or > VM_MAX_RAM

Icon LinkWDAM: Modular 128-bit integer addition

$of is cleared.

If the rhs operand is zero, MEM[$rA, 16] is cleared and $err is set to true. Otherwise, $err is cleared.

Panic if:

• The memory range MEM[$rA, 16] does not pass ownership check
• $rB + 16 overflows or > VM_MAX_RAM
• $rC + 16 overflows or > VM_MAX_RAM
• $rD + 16 overflows or > VM_MAX_RAM

Icon LinkWQAM: Modular 256-bit integer addition

$of is cleared.

If the rhs operand is zero, MEM[$rA, 16] is cleared and $err is set to true. Otherwise, $err is cleared.

Panic if:

• The memory range MEM[$rA, 32] does not pass ownership check
• $rB + 32 overflows or > VM_MAX_RAM
• $rC + 32 overflows or > VM_MAX_RAM
• $rD + 32 overflows or > VM_MAX_RAM

Icon LinkWDMM: Modular 128-bit integer multiplication

$of is cleared.

If the rhs operand is zero, MEM[$rA, 16] is cleared and $err is set to true. Otherwise, $err is cleared.

Panic if:

• The memory range MEM[$rA, 16] does not pass ownership check
• $rB + 16 overflows or > VM_MAX_RAM
• $rC + 16 overflows or > VM_MAX_RAM
• $rD + 16 overflows or > VM_MAX_RAM

Icon LinkWQMM: Modular 256-bit integer multiplication

$of is cleared.

If the rhs operand is zero, MEM[$rA, 16] is cleared and $err is set to true. Otherwise, $err is cleared.

Panic if:

• The memory range MEM[$rA, 32] does not pass ownership check
• $rB + 32 overflows or > VM_MAX_RAM
• $rC + 32 overflows or > VM_MAX_RAM
• $rD + 32 overflows or > VM_MAX_RAM

Icon LinkXOR: XOR

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkXORI: XOR immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Icon LinkControl Flow Instructions

Icon LinkJMP: Jump

Panic if:

• $is + $rA * 4 > VM_MAX_RAM - 1

Icon LinkJI: Jump immediate

Panic if:

• $is + imm * 4 > VM_MAX_RAM - 1

Icon LinkJNE: Jump if not equal

Panic if:

• $is + $rC * 4 > VM_MAX_RAM - 1 and the jump would be performed (i.e. $rA != $rB)

Icon LinkJNEI: Jump if not equal immediate

Panic if:

• $is + imm * 4 > VM_MAX_RAM - 1 and the jump would be performed (i.e. $rA != $rB)

Icon LinkJNZI: Jump if not zero immediate

Panic if:

• $is + imm * 4 > VM_MAX_RAM - 1and the jump would be performed (i.e. $rA != $zero)

Icon LinkJMPB: Jump relative backwards

Panic if:

• $pc - ($rA + imm + 1) * 4 < 0

Icon LinkJMPF: Jump relative forwards

Panic if:

• $pc + ($rA + imm + 1) * 4 > VM_MAX_RAM - 1

Icon LinkJNZB: Jump if not zero relative backwards

Panic if:

• $pc - ($rB + imm + 1) * 4 < 0

Icon LinkJNZF: Jump if not zero relative forwards

Panic if:

• $pc + ($rB + imm + 1) * 4 > VM_MAX_RAM - 1

Icon LinkJNEB: Jump if not equal relative backwards

Panic if:

• $pc - ($rC + imm + 1) * 4 < 0

Icon LinkJNEF: Jump if not equal relative forwards

Panic if:

• $pc + ($rC + imm + 1) * 4 > VM_MAX_RAM - 1

Icon LinkRET: Return from context

Append a receipt to the list of receipts:

If current context is external, append an additional receipt to the list of receipts:

If current context is external, cease VM execution and return $rA.

Returns from contract call, popping the call frame. Before popping perform the following operations.

Return the unused forwarded gas to the caller:

1. $cgas = $cgas + $fp->$cgas (add remaining context gas from previous context to current remaining context gas)

Set the return value:

1. $ret = $rA
2. $retl = 0

Then pop the call frame and restore all registers except $ggas, $cgas, $ret, $retl and $hp. Afterwards, set the following registers:

1. $pc = $pc + 4 (advance program counter from where we called)

Icon LinkMemory Instructions

All these instructions advance the program counter $pc by 4 after performing their operation.

Icon LinkALOC: Allocate memory

Panic if:

• $hp - $rA underflows
• $hp - $rA < $sp

Icon LinkCFE: Extend call frame

Panic if:

• $sp + $rA overflows
• $sp + $rA > $hp

Icon LinkCFEI: Extend call frame immediate

Panic if:

• $sp + imm overflows
• $sp + imm > $hp

Icon LinkCFS: Shrink call frame

Panic if:

• $sp - $rA underflows
• $sp - $rA < $ssp

Icon LinkCFSI: Shrink call frame immediate

Panic if:

• $sp - imm underflows
• $sp - imm < $ssp

Icon LinkLB: Load byte

Panic if:

• $rA is a reserved register
• $rB + imm + 1 overflows
• $rB + imm + 1 > VM_MAX_RAM

Icon LinkLW: Load word

Panic if:

• $rA is a reserved register
• $rB + (imm * 8) + 8 overflows
• $rB + (imm * 8) + 8 > VM_MAX_RAM

Icon LinkMCL: Memory clear

Panic if:

• $rA + $rB overflows
• $rA + $rB > VM_MAX_RAM
• The memory range MEM[$rA, $rB] does not pass ownership check

Icon LinkMCLI: Memory clear immediate

Panic if:

• $rA + imm overflows
• $rA + imm > VM_MAX_RAM
• The memory range MEM[$rA, imm] does not pass ownership check

Icon LinkMCP: Memory copy

Panic if:

• $rA + $rC overflows
• $rB + $rC overflows
• $rA + $rC > VM_MAX_RAM
• $rB + $rC > VM_MAX_RAM
• The memory ranges MEM[$rA, $rC] and MEM[$rB, $rC] overlap
• The memory range MEM[$rA, $rC] does not pass ownership check

Icon LinkMCPI: Memory copy immediate

Panic if:

• $rA + imm overflows
• $rB + imm overflows
• $rA + imm > VM_MAX_RAM
• $rB + imm > VM_MAX_RAM
• The memory ranges MEM[$rA, imm] and MEM[$rB, imm] overlap
• The memory range MEM[$rA, imm] does not pass ownership check

Icon LinkMEQ: Memory equality

Panic if:

• $rA is a reserved register
• $rB + $rD overflows
• $rC + $rD overflows
• $rB + $rD > VM_MAX_RAM
• $rC + $rD > VM_MAX_RAM

Icon LinkPSHH: Push a set of high registers to stack

The nth bit of the bitmask corresponds to nth entry of the register range. In other words, the most significant (i.e. leftmost) bit of the bitmask corresponds to the highest register index. So for instance bitmask 011000000000000000000000 pushes the register 61 followed by register 62.

Panic if:

• $sp + popcnt(imm)*8 overflows
• $sp + popcnt(imm)*8 > $hp

Icon LinkPSHL: Push a set of low registers to stack

The nth bit of the bitmask corresponds to nth entry of the register range. In other words, the most significant (i.e. leftmost) bit of the bitmask corresponds to the highest register index. So for instance bitmask 011000000000000000000000 pushes the register 37 followed by register 38.

Panic if:

• $sp + popcnt(imm)*8 overflows
• $sp + popcnt(imm)*8 > $hp

Icon LinkPOPH: Pop a set of high registers from stack

The nth bit of the bitmask corresponds to nth entry of the register range. In other words, the most significant (i.e. leftmost) bit of the bitmask corresponds to the highest register index. So for instance bitmask 011000000000000000000000 pops the register 62 followed by register 61.

Note that the order is reverse from PSHH, so that PSHH a; POPH a returns to the original state.

Panic if:

• $sp - popcnt(imm)*8 overflows
• $sp - popcnt(imm)*8 < $ssp

Icon LinkPOPL: Pop a set of low registers from stack

The nth bit of the bitmask corresponds to nth entry of the register range. In other words, the most significant (i.e. leftmost) bit of the bitmask corresponds to the highest register index. So for instance bitmask 011000000000000000000000 pops the register 38 followed by register 37.

Note that the order is reverse from PSHL, so that PSHL a; POPL a returns to the original state.

Panic if:

• $sp - popcnt(imm)*8 overflows
• $sp - popcnt(imm)*8 < $ssp

Icon LinkSB: Store byte

Panic if:

• $rA + imm + 1 overflows
• $rA + imm + 1 > VM_MAX_RAM
• The memory range MEM[$rA + imm, 1] does not pass ownership check

Icon LinkSW: Store word

Panic if:

• $rA + (imm * 8) + 8 overflows
• $rA + (imm * 8) + 8 > VM_MAX_RAM
• The memory range MEM[$rA + (imm * 8), 8] does not pass ownership check

Icon LinkContract Instructions

All these instructions advance the program counter $pc by 4 after performing their operation, except for CALL , RETD and RVRT .

Icon LinkBAL: Balance of contract ID

Where helper balance(asset_id: byte[32], contract_id: byte[32]) -> uint64 returns the current balance of asset_id of contract with ID contract_id.

Panic if:

• $rA is a reserved register
• $rB + 32 overflows
• $rB + 32 > VM_MAX_RAM
• $rC + 32 overflows
• $rC + 32 > VM_MAX_RAM
• Contract with ID MEM[$rC, 32] is not in tx.inputs

Icon LinkBHEI: Block height

Panic if:

• $rA is a reserved register

Icon LinkBHSH: Block hash

Panic if:

• $rA + 32 overflows
• $rA + 32 > VM_MAX_RAM
• The memory range MEM[$rA, 32] does not pass ownership check

Block header hashes for blocks with height greater than or equal to current block height are zero (0x00**32).

Icon LinkBURN: Burn existing coins

The asset ID is constructed using the asset ID construction method.

Panic if:

• $rB + 32 > VM_MAX_RAM
• Balance of asset ID from constructAssetID(MEM[$fp, 32], MEM[$rB, 32]) of output with contract ID MEM[$fp, 32] minus $rA underflows
• $fp == 0 (in the script context)

For output with contract ID MEM[$fp, 32], decrease balance of asset ID constructAssetID(MEM[$fp, 32], MEM[$rB, 32]) by $rA.

This modifies the balanceRoot field of the appropriate output.

Append a receipt to the list of receipts:

Icon LinkCALL: Call contract

There is a balanceOfStart(asset_id: byte[32]) -> uint32 helper that returns the memory address of the remaining free balance of asset_id. If asset_id has no free balance remaining, the helper panics.

Panic if:

• $rA + 32 overflows
• $rC + 32 overflows
• Contract with ID MEM[$rA, 32] is not in tx.inputs
• Reading past MEM[VM_MAX_RAM - 1]
• In an external context, if $rB > MEM[balanceOfStart(MEM[$rC, 32]), 8]
• In an internal context, if $rB is greater than the balance of asset ID MEM[$rC, 32] of output with contract ID MEM[$fp, 32]

Register $rA is a memory address from which the following fields are set (word-aligned):

$rB is the amount of coins to forward. $rC points to the 32-byte asset ID of the coins to forward. $rD is the amount of gas to forward. If it is set to an amount greater than the available gas, all available gas is forwarded.

Append a receipt to the list of receipts:

For output with contract ID MEM[$rA, 32], increase balance of asset ID MEM[$rC, 32] by $rB. In an external context, decrease MEM[balanceOfStart(MEM[$rC, 32]), 8] by $rB. In an internal context, decrease asset ID MEM[$rC, 32] balance of output with contract ID MEM[$fp, 32] by $rB.

A call frame is pushed at $sp. In addition to filling in the values of the call frame, the following registers are set:

1. $fp = $sp (on top of the previous call frame is the beginning of this call frame)
2. Set $ssp and $sp to the start of the writable stack area of the call frame.
3. Set $pc and $is to the starting address of the code.
4. $bal = $rB (forward coins)
5. $cgas = $rD or all available gas (forward gas)

This modifies the balanceRoot field of the appropriate output(s).

Icon LinkCB: Coinbase contract id

Panic if:

• $rA + 32 overflows
• $rA + 32 > VM_MAX_RAM
• The memory range MEM[$rA, 32] does not pass ownership check

Icon LinkCCP: Code copy

This is used only for reading and inspecting code of other contracts. Use LDC to load code for executing.

Panic if:

• $rA + $rD overflows
• $rB + 32 overflows
• $rA + $rD > VM_MAX_RAM
• $rB + 32 > VM_MAX_RAM
• The memory range MEM[$rA, $rD] does not pass ownership check
• Contract with ID MEM[$rB, 32] is not in tx.inputs

Icon LinkCROO: Code Merkle root

Panic if:

• $rA + 32 overflows
• $rB + 32 overflows
• $rA + 32 > VM_MAX_RAM
• $rB + 32 > VM_MAX_RAM
• The memory range MEM[$rA, 32] does not pass ownership check
• Contract with ID MEM[$rB, 32] is not in tx.inputs

Code root computation is defined here .

Icon LinkCSIZ: Code size

Panic if:

• $rA is a reserved register
• $rB + 32 overflows
• $rB + 32 > VM_MAX_RAM
• Contract with ID MEM[$rB, 32] is not in tx.inputs

Icon LinkLDC: Load code from an external contract

Panic if:

• $ssp + $rC overflows
• $rA + 32 overflows
• $ssp + $rC > VM_MAX_RAM
• $rA + 32 > VM_MAX_RAM
• $ssp + $rC >= $hp
• $rC > CONTRACT_MAX_SIZE
• Contract with ID MEM[$rA, 32] is not in tx.inputs

Increment $fp->codesize, $ssp by $rC padded to word alignment. Then set $sp to $ssp.

This instruction can be used to concatenate the code of multiple contracts together. It can only be used when the stack area of the call frame is unused (i.e. prior to being used).

Icon LinkLOG: Log event

Append a receipt to the list of receipts:

Icon LinkLOGD: Log data event

Append a receipt to the list of receipts:

Logs the memory range MEM[$rC, $rD].

Panics if:

• $rC + $rD overflows
• $rA + $rD > VM_MAX_RAM

Icon LinkMINT: Mint new coins

The asset ID will be constructed using the asset ID construction method.

Panic if:

• $rB + 32 > VM_MAX_RAM
• Balance of asset ID constructAssetID(MEM[$fp, 32], MEM[$rB]) of output with contract ID MEM[$fp, 32] plus $rA overflows
• $fp == 0 (in the script context)

For output with contract ID MEM[$fp, 32], increase balance of asset ID constructAssetID(MEM[$fp, 32], MEM[$rB]) by $rA.

This modifies the balanceRoot field of the appropriate output.

Append a receipt to the list of receipts:

Icon LinkRETD: Return from context with data

Panic if:

• $rA + $rB overflows
• $rA + $rB > VM_MAX_RAM

Append a receipt to the list of receipts:

If current context is a script, append an additional receipt to the list of receipts:

If current context is external, cease VM execution and return MEM[$rA, $rB].

Returns from contract call, popping the call frame. Before popping, perform the following operations.

Return the unused forwarded gas to the caller:

1. $cgas = $cgas + $fp->$cgas (add remaining context gas from previous context to current remaining context gas)

Set the return value:

1. $ret = $rA
2. $retl = $rB

Then pop the call frame and restore all registers except $ggas, $cgas, $ret, $retl and $hp. Afterwards, set the following registers:

1. $pc = $pc + 4 (advance program counter from where we called)

Icon LinkRVRT: Revert

Append a receipt to the list of receipts:

Then append an additional receipt to the list of receipts:

Cease VM execution and revert script effects. After a revert:

1. All OutputContract outputs will have the same balanceRoot and stateRoot as on initialization.
2. All OutputVariable outputs will have to, amount, and asset_id of zero.

Icon LinkSMO: Send message out

There is a balanceOfStart(asset_id: byte[32]) -> uint32 helper that returns the memory address of the remaining free balance of asset_id. If asset_id has no free balance remaining, the helper panics.

Panic if:

• $rA + 32 overflows
• $rB + $rC overflows
• $rA + 32 > VM_MAX_RAM
• $rB + $rC > VM_MAX_RAM
• $rC > MESSAGE_MAX_DATA_SIZE
• In an external context, if $rD > MEM[balanceOfStart(0), 8]
• In an internal context, if $rD is greater than the balance of asset ID 0 of output with contract ID MEM[$fp, 32]

Append a receipt to the list of receipts:

In an external context, decrease MEM[balanceOfStart(0), 8] by $rD. In an internal context, decrease asset ID 0 balance of output with contract ID MEM[$fp, 32] by $rD. This modifies the balanceRoot field of the appropriate contract that had its' funds deducted.

Icon LinkSCWQ: State clear sequential 32 byte slots

Panic if:

• $rA + 32 overflows
• $rA + 32 > VM_MAX_RAM
• $rB is a reserved register
• $fp == 0 (in the script context)

Register $rB will be set to false if any storage slot in the requested range was already unset (default) and true if all the slots were set.

Icon LinkSRW: State read word

Panic if:

• $rA is a reserved register
• $rB is a reserved register
• $rC + 32 overflows
• $rC + 32 > VM_MAX_RAM
• $fp == 0 (in the script context)

Register $rB will be set to false if the requested slot is unset (default) and true if it's set.

Icon LinkSRWQ: State read sequential 32 byte slots

Panic if:

• $rA + 32 * rD overflows
• $rA + 32 * rD > VM_MAX_RAM
• $rB is a reserved register
• $rC + 32 * rD overflows
• $rC + 32 * rD > VM_MAX_RAM
• The memory range MEM[$rA, 32 * rD] does not pass ownership check
• $fp == 0 (in the script context)

Register $rB will be set to false if any storage slot in the requested range is unset (default) and true if all the slots are set.

Icon LinkSWW: State write word

Panic if:

• $rA + 32 overflows
• $rA + 32 > VM_MAX_RAM
• $rB is a reserved register
• $fp == 0 (in the script context)

The last 24 bytes of STATE[MEM[$rA, 32]] are set to 0. Register $rB will be set to the number of new slots written, i.e. 1 if the slot was previously unset, and 0 if it already contained a value.

Icon LinkSWWQ: State write sequential 32 byte slots

Panic if:

• $rA + 32 overflows
• $rB is a reserved register
• $rC + 32 * $rD overflows
• $rA + 32 > VM_MAX_RAM
• $rC + 32 * $rD > VM_MAX_RAM
• $fp == 0 (in the script context)

Register $rB will be set to the number of storage slots that were previously unset, and were set by this operation.

Icon LinkTIME: Timestamp at height

Panic if:

• $rA is a reserved register
• $rB is greater than the current block height.

Gets the timestamp of the block at height $rB. Time is in TAI64 Icon Link format.

Icon LinkTR: Transfer coins to contract

There is a balanceOfStart(asset_id: byte[32]) -> uint32 helper that returns the memory address of the remaining free balance of asset_id. If asset_id has no free balance remaining, the helper panics.

Panic if:

• $rA + 32 overflows
• $rC + 32 overflows
• $rA + 32 > VM_MAX_RAM
• $rC + 32 > VM_MAX_RAM
• Contract with ID MEM[$rA, 32] is not in tx.inputs
• In an external context, if $rB > MEM[balanceOfStart(MEM[$rC, 32]), 8]
• In an internal context, if $rB is greater than the balance of asset ID MEM[$rC, 32] of output with contract ID MEM[$fp, 32]
• $rB == 0

Append a receipt to the list of receipts:

For output with contract ID MEM[$rA, 32], increase balance of asset ID MEM[$rC, 32] by $rB. In an external context, decrease MEM[balanceOfStart(MEM[$rC, 32]), 8] by $rB. In an internal context, decrease asset ID MEM[$rC, 32] balance of output with contract ID MEM[$fp, 32] by $rB.

This modifies the balanceRoot field of the appropriate output(s).

Icon LinkTRO: Transfer coins to output

There is a balanceOfStart(asset_id: byte[32]) -> uint32 helper that returns the memory address of the remaining free balance of asset_id. If asset_id has no free balance remaining, the helper panics.

Panic if:

• $rA + 32 overflows
• $rD + 32 overflows
• $rA + 32 > VM_MAX_RAM
• $rD + 32 > VM_MAX_RAM
• $rB > tx.outputsCount
• In an external context, if $rC > MEM[balanceOfStart(MEM[$rD, 32]), 8]
• In an internal context, if $rC is greater than the balance of asset ID MEM[$rD, 32] of output with contract ID MEM[$fp, 32]
• $rC == 0
• tx.outputs[$rB].type != OutputType.Variable
• tx.outputs[$rB].amount != 0

Append a receipt to the list of receipts:

In an external context, decrease MEM[balanceOfStart(MEM[$rD, 32]), 8] by $rC. In an internal context, decrease asset ID MEM[$rD, 32] balance of output with contract ID MEM[$fp, 32] by $rC. Then set:

• tx.outputs[$rB].to = MEM[$rA, 32]
• tx.outputs[$rB].amount = $rC
• tx.outputs[$rB].asset_id = MEM[$rD, 32]

This modifies the balanceRoot field of the appropriate output(s).

Icon LinkCryptographic Instructions

All these instructions advance the program counter $pc by 4 after performing their operation.

Icon LinkECK1: Secp256k1 signature recovery

Panic if:

• $rA + 64 overflows
• $rB + 64 overflows
• $rC + 32 overflows
• $rA + 64 > VM_MAX_RAM
• $rB + 64 > VM_MAX_RAM
• $rC + 32 > VM_MAX_RAM
• The memory range MEM[$rA, 64] does not pass ownership check

Signatures and signature verification are specified here .

If the signature cannot be verified, MEM[$rA, 64] is set to 0 and $err is set to 1, otherwise $err is cleared.

To get the address from the public key, hash the public key with SHA-2-256 .

Icon LinkECR1: Secp256r1 signature recovery

Panic if:

• $rA + 64 overflows
• $rB + 64 overflows
• $rC + 32 overflows
• $rA + 64 > VM_MAX_RAM
• $rB + 64 > VM_MAX_RAM
• $rC + 32 > VM_MAX_RAM
• The memory range MEM[$rA, 64] does not pass ownership check

Signatures and signature verification are specified here .

If the signature cannot be verified, MEM[$rA, 64] is set to 0 and $err is set to 1, otherwise $err is cleared.

To get the address from the public key, hash the public key with SHA-2-256 .

Icon LinkED19: EdDSA curve25519 verification

Panic if:

• $rA + 32 overflows
• $rB + 64 overflows
• $rC + 32 overflows
• $rA + 32 > VM_MAX_RAM
• $rB + 64 > VM_MAX_RAM
• $rC + 32 > VM_MAX_RAM

Verification are specified here .

If there is an error in verification, $err is set to 1, otherwise $err is cleared.

Icon LinkK256: keccak-256

Panic if:

• $rA + 32 overflows
• $rB + $rC overflows
• $rA + 32 > VM_MAX_RAM
• $rB + $rC > VM_MAX_RAM
• The memory range MEM[$rA, 32] does not pass ownership check

Icon LinkS256: SHA-2-256

Panic if:

• $rA + 32 overflows
• $rB + $rC overflows
• $rA + 32 > VM_MAX_RAM
• $rB + $rC > VM_MAX_RAM
• The memory range MEM[$rA, 32] does not pass ownership check

Icon LinkOther Instructions

All these instructions advance the program counter $pc by 4 after performing their operation.

Icon LinkECAL: Call external function

This function provides an escape hatch from the VM, similar to ecall instruction of RISC-V. The suggested convention is to use $rA for "system call number", i.e. identifying the procedure to call, but all arguments can be used freely. The operation can modify the VM state freely, including writing to registers and memory. Again, the suggested convention is to use $rA for the return value and $err for any possible errors. However, these conventions can be ignored when necessary.

Panic if:

• The external function panics.

Icon LinkFLAG: Set flags

Panic if:

• Any reserved flags are set

Icon LinkGM: Get metadata

Read metadata from memory. A convenience instruction to avoid manually extracting metadata.

If imm == GM_IS_CALLER_EXTERNAL:

Panic if:

• $fp == 0 (in an external context)

Set $rA to true if parent is an external context, false otherwise.

If imm == GM_GET_CALLER:

Panic if:

• $fp == 0 (in an external context)
• $fp->$fp == 0 (if parent context is external)

Set $rA to $fp->$fp (i.e. $rA will point to the previous call frame's contract ID).

If imm == GM_GET_VERIFYING_PREDICATE:

Panic if:

• not in a predicate context

Set $rA to the index of the currently-verifying predicate.

Icon LinkGTF: Get transaction fields

Get fields from the transaction .

Panic if:

• $rA is a reserved register
• imm is not one of the values listed above
• The value of $rB results in an out of bounds access for variable-length fields
• The input or output type does not match (OutputChange and OutputVariable count as OutputCoin)
• The requested policy type is not set for this transaction.

For fixed-length fields, the value of $rB is ignored.