Fuel Specifications

Fuel: A Secure Decentralized Generalized Massively Scalable Transaction Ledger

This book specifies the Fuel protocol, including the Fuel Virtual Machine (short: FuelVM), a blazingly fast verifiable blockchain virtual machine.

Protocol

• Transaction Format - The Fuel transaction format.
• Computing Identifiers - Computing unique IDs for transactions, contracts and UTXOs.
• Transaction Validity - Defines transaction validity rules.
• Cryptographic Primitives - Cryptographic primitives used in Fuel.
• Application Binary Interface (ABI) - Low-level details on interfacing with Fuel bytecode.
• Storage Slot Initialization - JSON format for contract storage slot initialization.
• Block Header Format - The Fuel block header format.

FuelVM

• Overview - Describes the FuelVM at a high level, from its architecture to how it is initialized.
• Instruction Set - Defines the FuelVM instruction set.

Network-Specific

• Proof of Authority (PoA) - The Fuel Proof of Authority Network.

Testing

• Sparse Merkle Tree - A test suite for verifying correctness of SMT outputs.

Protocol

• Transaction Format
• Computing Identifiers
• Transaction Validity
• Cryptographic Primitives
• Application Binary Interface (ABI)
• Storage Slot Initialization
• Block Header Format

Transaction Format

The Fuel Transaction Format.

• Constants
• Transaction
  • TransactionScript
  • TransactionCreate
  • TransactionMint
• Input
  • InputCoin
  • InputContract
  • InputMessage
• Output
  • OutputCoin
  • OutputContract
  • OutputChange
  • OutputVariable
  • OutputContractCreated
• Witness
• TXPointer

Constants

Transaction

enum TransactionType : uint8 {
    Script = 0,
    Create = 1,
    Mint = 2,
}

Transaction is invalid if:

• type > TransactionType.Create
• gasLimit > MAX_GAS_PER_TX
• blockheight() < maturity
• inputsCount > MAX_INPUTS
• outputsCount > MAX_OUTPUTS
• witnessesCount > MAX_WITNESSES
• No inputs are of type InputType.Coin or InputType.Message with input.dataLength == 0
• More than one output is of type OutputType.Change for any asset ID in the input set
• Any output is of type OutputType.Change for any asset ID not in the input set
• More than one input of type InputType.Coin for any Coin ID in the input set
• More than one input of type InputType.Contract for any Contract ID in the input set
• More than one input of type InputType.Message for any Message ID in the input set

When serializing a transaction, fields are serialized as follows (with inner structs serialized recursively):

1. uint8, uint16, uint32, uint64: big-endian right-aligned to 8 bytes.
2. byte[32]: as-is.
3. byte[]: as-is, with padding zeroes aligned to 8 bytes.

When deserializing a transaction, the reverse is done. If there are insufficient bytes or too many bytes, the transaction is invalid.

TransactionScript

enum ReceiptType : uint8 {
    Call = 0,
    Return = 1,
    ReturnData = 2,
    Panic = 3,
    Revert = 4,
    Log = 5,
    LogData = 6,
    Transfer = 7,
    TransferOut = 8,
    ScriptResult = 9,
    MessageOut = 10,
}

Given helper len() that returns the number of bytes of a field.

Transaction is invalid if:

• Any output is of type OutputType.ContractCreated
• scriptLength > MAX_SCRIPT_LENGTH
• scriptDataLength > MAX_SCRIPT_DATA_LENGTH
• scriptLength * 4 != len(script)
• scriptDataLength != len(scriptData)
• gasLimit is less than the sum of all predicateGasUsed for InputType.Coin or InputType.Message where predicate length is greater than zero.

Note: when signing a transaction, receiptsRoot is set to zero.

Note: when verifying a predicate, receiptsRoot is initialized to zero.

Note: when executing a script, receiptsRoot is initialized to zero.

The receipts root receiptsRoot is the root of the binary Merkle tree of receipts. If there are no receipts, its value is set to the root of the empty tree, i.e. 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

TransactionCreate

Transaction is invalid if:

• Any input is of type InputType.Contract or InputType.Message where input.dataLength > 0
• Any output is of type OutputType.Contract or OutputType.Variable or OutputType.Message
• More than one output is of type OutputType.Change with asset_id of zero
• Any output is of type OutputType.Change with non-zero asset_id
• It does not have exactly one output of type OutputType.ContractCreated
• bytecodeLength * 4 > CONTRACT_MAX_SIZE
• tx.data.witnesses[bytecodeWitnessIndex].dataLength != bytecodeLength * 4
• bytecodeWitnessIndex >= tx.witnessesCount
• The keys of storageSlots are not in ascending lexicographic order
• The computed contract ID (see below) is not equal to the contractID of the one OutputType.ContractCreated output
• storageSlotsCount > MAX_STORAGE_SLOTS
• The Sparse Merkle tree root of storageSlots is not equal to the stateRoot of the one OutputType.ContractCreated output

Creates a contract with contract ID as computed here.

TransactionMint

The transaction is created by the block producer and is not signed. Since it is not usable outside of block creation or execution, all fields must be fully set upon creation without any zeroing.

Transaction is invalid if:

• Any output is not of type OutputType.Coin
• Any two outputs have the same asset_id
• txPointer is zero or doesn't match the block.

Input

enum InputType : uint8 {
    Coin = 0,
    Contract = 1,
    Message = 2,
}

Transaction is invalid if:

• type > InputType.Message

InputCoin

Given helper len() that returns the number of bytes of a field.

Transaction is invalid if:

• witnessIndex >= tx.witnessesCount
• predicateLength > MAX_PREDICATE_LENGTH
• predicateDataLength > MAX_PREDICATE_DATA_LENGTH
• If predicateLength > 0; the computed predicate root (see below) is not equal owner
• predicateLength * 4 != len(predicate)
• predicateDataLength != len(predicateData)
• predicateGasUsed > MAX_GAS_PER_PREDICATE

If h is the block height the UTXO being spent was created, transaction is invalid if blockheight() < h + maturity.

Note: when signing a transaction, txPointer and predicateGasUsed is set to zero.

Note: when verifying a predicate, txPointer is initialized to zero.

Note: when estimating a predicate, txPointer and predicateGasUsed is initialized to zero.

Note: when executing a script, txPointer is initialized to zero.

The predicate root is computed here.

InputContract

Transaction is invalid if:

• there is not exactly one output of type OutputType.Contract with inputIndex equal to this input's index

Note: when signing a transaction, txID, outputIndex, balanceRoot, stateRoot, and txPointer are set to zero.

Note: when verifying a predicate, txID, outputIndex, balanceRoot, stateRoot, and txPointer are initialized to zero.

Note: when executing a script, txID, outputIndex, balanceRoot, and stateRoot are initialized to the transaction ID, output index, amount, and state root of the contract with ID contractID, and txPointer is initialized to zero.

InputMessage

Given helper len() that returns the number of bytes of a field.

Transaction is invalid if:

• witnessIndex >= tx.witnessesCount
• dataLength > MAX_MESSAGE_DATA_LENGTH
• predicateLength > MAX_PREDICATE_LENGTH
• predicateDataLength > MAX_PREDICATE_DATA_LENGTH
• If predicateLength > 0; the computed predicate root (see below) is not equal recipient
• dataLength != len(data)
• predicateLength * 4 != len(predicate)
• predicateDataLength != len(predicateData)
• predicateGasUsed > MAX_GAS_PER_PREDICATE

The predicate root is computed here.

Note: InputMessages with data length greater than zero are not considered spent until they are included in a transaction of type TransactionType.Script with a ScriptResult receipt where result is equal to 0 indicating a successful script exit

Note: when signing a transaction, predicateGasUsed is set to zero.

Note: when estimating a predicate, predicateGasUsed is initialized to zero.

Output

enum OutputType : uint8 {
    Coin = 0,
    Contract = 1,
    Change = 2,
    Variable = 3,
    ContractCreated = 4,
}

Transaction is invalid if:

• type > OutputType.ContractCreated

OutputCoin

OutputContract

Transaction is invalid if:

• inputIndex >= tx.inputsCount
• tx.inputs[inputIndex].type != InputType.Contract

Note: when signing a transaction, balanceRoot and stateRoot are set to zero.

Note: when verifying a predicate, balanceRoot and stateRoot are initialized to zero.

Note: when executing a script, balanceRoot and stateRoot are initialized to the balance root and state root of the contract with ID tx.inputs[inputIndex].contractID.

The balance root balanceRoot is the root of the SMT of balance leaves. Each balance is a uint64, keyed by asset ID (a byte[32]).

The state root stateRoot is the root of the SMT of storage slots. Each storage slot is a byte[32], keyed by a byte[32].

OutputChange

Transaction is invalid if:

• any other output has type OutputType.OutputChange and asset ID asset_id (i.e. only one change output per asset ID is allowed)

Note: when signing a transaction, amount is set to zero.

Note: when verifying a predicate or executing a script, amount is initialized to zero.

This output type indicates that the output's amount may vary based on transaction execution, but is otherwise identical to a Coin output. An amount of zero after transaction execution indicates that the output is unspendable and can be pruned from the UTXO set.

OutputVariable

Note: when signing a transaction, to, amount, and asset_id are set to zero.

Note: when verifying a predicate or executing a script, to, amount, and asset_id are initialized to zero.

This output type indicates that the output's amount and owner may vary based on transaction execution, but is otherwise identical to a Coin output. An amount of zero after transaction execution indicates that the output is unspendable and can be pruned from the UTXO set.

OutputContractCreated

Witness

TXPointer

The location of the transaction in the block. It can be used by UTXOs as a reference to the transaction or by the transaction itself to make it unique.

Identifiers

This chapter defines how to compute unique identifiers.

• Transaction ID
• Contract ID
• Predicate ID
• UTXO ID
  • Coin ID
  • Message ID
    • Message Nonce
  • Fee ID

Transaction ID

The transaction ID (also called transaction hash) of a transaction is computed as the hash of CHAIN_ID and the serialized transaction with fields zeroed out for signing (see different inputs and outputs for which fields are set to zero), and without witness data. In other words, only all non-witness data is hashed.

sha256(CHAIN_ID ++ serialized_tx(tx))

Contract ID

For a transaction of type TransactionType.Create, tx, the contract ID is sha256(0x4655454C ++ tx.data.salt ++ root(tx.data.witnesses[bytecodeWitnessIndex].data) ++ root_smt(tx.storageSlots)), where root is the Merkle root of the binary Merkle tree with each leaf being an 8-byte word of two instructions, and root_smt is the Sparse Merkle tree root of the provided key-value pairs. If the bytecode is not a multiple of 8 bytes (i.e. if there are an odd number of instructions), the last instruction is padded with 4-byte zero.

UTXO ID

Coin ID

Is represented as an outpoint: a pair of transaction ID as byte[32] and output index as a uint8.

Message ID

The ID of a message is computed as the hash of:

1. the sender address as byte[32],
2. the recipient address as byte[32],
3. the Message nonce as byte[32],
4. the amount being sent with the message as uint64,
5. the message data as byte[]

hash(byte[32] ++ byte[32] ++ byte[32] ++ uint64 ++ byte[]). The address values are serialized as a byte array of length 32 left-padded with zeroes, and all other value types are serialized according to the standard transaction serialization. Note that the message data length is not included since there is only one dynamically sized field and can be implicitly determined by the hash preimage size.

Message Nonce

The nonce value for InputMessage is determined by the sending system and is published at the time the message is sent. The nonce value for OutputMessage is computed as the hash of the Transaction ID that emitted the message and the index of the message receipt uint8: hash(byte[32] ++ uint8).

Fee ID

The UTXO ID of collected fees in a block is the block height as a 32-byte big-endian unsigned integer (i.e. the first byte of the 32-byte array is the most significant byte, and so on).

Transaction Validity

• Transaction Lifecycle
• Access Lists
• VM Precondition Validity Rules
  • Base Sanity Checks
  • Spending UTXOs and Created Contracts
  • Sufficient Balance
  • Valid Signatures
• Predicate Verification
• Script Execution
• VM Postcondition Validity Rules
  • Correct Change
  • State Changes

Transaction Lifecycle

Once a transaction is seen, it goes through several stages of validation, in this order:

1. Pre-checks
2. Predicate verification
3. Script execution
4. Post-checks

Access Lists

The validity rules below assume sequential transaction validation for side effects (i.e. state changes). However, by construction, transactions with disjoint write access lists can be validated in parallel, including with overlapping read-only access lists. Transactions with overlapping write access lists must be validated and placed in blocks in topological order.

UTXOs and contracts in the read-only and write-destroy access lists must exist (i.e. have been created previously) in order for a transaction to be valid. In other words, for a unique state element ID, the write-create must precede the write-destroy.

Read-only access list:

Write-destroy access list:

• For each input InputType.Coin
  • The UTXO ID (txID, outputIndex)
• For each input InputType.Contract
  • The UTXO ID (txID, outputIndex)
• For each input InputType.Message
  • The message ID messageID

Write-create access list:

• For each output OutputType.ContractCreated
  • The contract ID contractID
• For each output
  • The created UTXO ID

Note that block proposers use the contract ID contractID for inputs and outputs of type InputType.Contract and OutputType.Contract rather than the pair of txID and outputIndex.

VM Precondition Validity Rules

This section defines VM precondition validity rules for transactions: the bare minimum required to accept an unconfirmed transaction into a mempool, and preconditions that the VM assumes to hold prior to execution. Chains of unconfirmed transactions are omitted.

For a transaction tx, UTXO set state, contract set contracts, and message set messages, the following checks must pass.

Note: InputMessages where input.dataLength > 0 are not dropped from the messages message set until they are included in a transaction of type TransactionType.Script with a ScriptResult receipt where result is equal to 0 indicating a successful script exit.

Base Sanity Checks

Base sanity checks are defined in the transaction format.

Spending UTXOs and Created Contracts

for input in tx.inputs:
    if input.type == InputType.Contract:
        if not input.contractID in contracts:
                return False
    elif input.type == InputType.Message:
        if not input.nonce in messages:
                return False
    else:
        if not (input.txID, input.outputIndex) in state:
            return False
return True

If this check passes, the UTXO ID (txID, outputIndex) fields of each contract input is set to the UTXO ID of the respective contract. The txPointer of each input is also set to the TX pointer of the UTXO with ID utxoID.

Sufficient Balance

For each asset ID asset_id in the input and output set:

def sum_data_messages(tx, asset_id) -> int:
    """
    Returns the total balance available from messages containing data
    """
    total: int = 0
    if asset_id == 0:
        for input in tx.inputs:
            if input.type == InputType.Message and input.dataLength > 0:
                total += input.amount
    return total

def sum_inputs(tx, asset_id) -> int:
    total: int = 0
    for input in tx.inputs:
        if input.type == InputType.Coin and input.asset_id == asset_id:
            total += input.amount
        elif input.type == InputType.Message and asset_id == 0 and input.dataLength == 0:
            total += input.amount
    return total

def sum_outputs(tx, asset_id) -> int:
    total: int = 0
    for output in tx.outputs:
        if output.type == OutputType.Coin and output.asset_id == asset_id:
            total += output.amount
    return total

def available_balance(tx, asset_id) -> int:
    """
    Make the data message balance available to the script
    """
    availableBalance = sum_inputs(tx, asset_id) + sum_data_messages(tx, asset_id)
    return availableBalance

def unavailable_balance(tx, asset_id) -> int:
    sentBalance = sum_outputs(tx, asset_id)
    gasBalance = gasPrice * gasLimit / GAS_PRICE_FACTOR
    # Size excludes witness data as it is malleable (even by third parties!)
    bytesBalance = size(tx) * GAS_PER_BYTE * gasPrice / GAS_PRICE_FACTOR
    # Total fee balance
    feeBalance = ceiling(gasBalance + bytesBalance)
    # Only base asset can be used to pay for gas
    if asset_id == 0:
        return sentBalance + feeBalance
    return sentBalance

# The sum_data_messages total is not included in the unavailable_balance since it is spendable as long as there 
# is enough base asset amount to cover gas costs without using data messages. Messages containing data can't
# cover gas costs since they are retryable.
return available_balance(tx, asset_id) >= (unavailable_balance(tx, asset_id) + sum_data_messages(tx, asset_id))

Valid Signatures

def address_from(pubkey: bytes) -> bytes:
    return sha256(pubkey)[0:32]

for input in tx.inputs:
    if (input.type == InputType.Coin || input.type == InputType.Message) and input.predicateLength == 0:
        # ECDSA signatures must be 64 bytes
        if tx.witnesses[input.witnessIndex].dataLength != 64:
            return False
        # Signature must be from owner
        if address_from(ecrecover(txhash(), tx.witnesses[input.witnessIndex].data)) != input.owner:
            return False
return True

Signatures and signature verification are specified here.

The transaction hash is computed as defined here.

Predicate Verification

For each input of type InputType.Coin or InputType.Message, and predicateLength > 0, verify its predicate.

Script Execution

Given transaction tx, the following checks must pass:

If tx.scriptLength == 0, there is no script and the transaction defines a simple balance transfer, so no further checks are required.

If tx.scriptLength > 0, the script must be executed. For each asset ID asset_id in the input set, the free balance available to be moved around by the script and called contracts is freeBalance[asset_id]. The initial message balance available to be moved around by the script and called contracts is messageBalance:

freeBalance[asset_id] = available_balance(tx, asset_id) - unavailable_balance(tx, asset_id)
messageBalance = sum_data_messages(tx, 0)

Once the free balances are computed, the script is executed. After execution, the following is extracted:

1. The transaction in-memory on VM termination is used as the final transaction which is included in the block.
2. The unspent free balance unspentBalance for each asset ID.
3. The unspent gas unspentGas from the $ggas register.

The fees incurred for a transaction are ceiling(((size(tx) * GAS_PER_BYTE) + (tx.gasLimit - unspentGas)) * tx.gasPrice / GAS_PRICE_FACTOR).

If the transaction as included in a block does not match this final transaction, the block is invalid.

VM Postcondition Validity Rules

This section defines VM postcondition validity rules for transactions: the requirements for a transaction to be valid after it has been executed.

Given transaction tx, state state, and contract set contracts, the following checks must pass.

Correct Change

If change outputs are present, they must have:

• if the transaction does not revert;
  • if the asset ID is 0; an amount of unspentBalance + floor((unspentGas * tx.gasPrice) / GAS_PRICE_FACTOR)
  • otherwise; an amount of the unspent free balance for that asset ID after VM execution is complete
• if the transaction reverts;
  • if the asset ID is 0; an amount of the initial free balance plus (unspentGas * tx.gasPrice) - messageBalance
  • otherwise; an amount of the initial free balance for that asset ID.

State Changes

Transaction processing is completed by removing spent UTXOs from the state and adding created UTXOs to the state.

Coinbase Transaction

The coinbase transaction is a mechanism for block creators to convert fees into spendable UTXOs.

In order for a coinbase transaction to be valid:

1. It must be a Mint transaction.
2. The coinbase transaction must be the first transaction within a block, even if there are no other transactions in the block and the fee is zero.
3. The total output value of the coinbase transaction cannot exceed the total amount of fees processed from all other transactions within the same block.
4. The asset_id for coinbase transaction outputs must match the asset_id that fees are paid in (asset_id == 0).

Cryptographic Primitives

• Hashing
• Merkle Trees
  • Binary Merkle Tree
  • Binary Merkle Sum Tree
  • Sparse Merkle Tree
• Public-Key Cryptography

Hashing

All hashing is done with SHA-2-256 (also known as SHA-256), defined in FIPS 180-4.

Merkle Trees

Three Merkle tree structures are used: a Binary Merkle Tree (to commit to bytecode), a Binary Merkle Sum Tree (to commit to transactions and collected fees) and a Sparse Merkle Tree (to commit to contract storage, i.e. state).

Binary Merkle Tree

A specification for the Binary Merkle Tree is here.

Binary Merkle Sum Tree

The Binary Merkle Sum Tree is an extension of the tree defined in RFC-6962.

The root pair (fee, digest) of an empty tree is:

(0x0000000000000000, hash()) = (0x0000000000000000, 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855)

The root pair of a tree with one leaf:

(leaf.fee, hash(0x00 ++ leaf.fee ++ serialize(leaf)))

The root pair of a tree with two or more leaves is defined recursively:

(left.fee + right.fee, hash(0x01 ++ left.fee ++ left.digest ++ right.fee ++ right.digest))

In other words, the root pair is 40 bytes (8 for fee sum, 32 for hash digest).

Sparse Merkle Tree

A specification for the Sparse Merkle Tree is here.

A specification describing a suite of test vectors and outputs of a Sparse Merkle Tree is here.

Public-Key Cryptography

Consensus-critical data is authenticated using ECDSA, with the curve secp256k1. A highly-optimized library is available in C (https://github.com/bitcoin-core/secp256k1), with wrappers in Go (https://pkg.go.dev/github.com/ethereum/go-ethereum/crypto/secp256k1) and Rust (https://docs.rs/crate/secp256k1).

Public keys are encoded in uncompressed form, as the concatenation of the x and y values. No prefix is needed to distinguish between encoding schemes as this is the only encoding supported.

Deterministic signatures (RFC-6979) should be used when signing, but this is not enforced at the protocol level as it cannot be.

Signatures are represented as the r and s (each 32 bytes), and v (1-bit) values of the signature. r and s take on their usual meaning (see: SEC 1, 4.1.3 Signing Operation), while v is used for recovering the public key from a signature more quickly (see: SEC 1, 4.1.6 Public Key Recovery Operation). Only low-s values in signatures are valid (i.e. s <= secp256k1.n//2); s can be replaced with -s mod secp256k1.n during the signing process if it is high. Given this, the first bit of s will always be 0, and can be used to store the 1-bit v value.

v represents the parity of the Y component of the point, 0 for even and 1 for odd. The X component of the point is assumed to always be low, since the possibility of it being high is negligible.

Putting it all together, the encoding for signatures is:

|    32 bytes   ||           32 bytes           |
[256-bit r value][1-bit v value][255-bit s value]

This encoding scheme is derived from EIP 2098: Compact Signature Representation.

Application Binary Interface (ABI)

This document describes and specifies the ABI (Application Binary Interface) of the FuelVM, the Sway programming language, and contracts written in Sway.

• JSON ABI Format
• Receipts
• Function Selector Encoding
• Argument Encoding

JSON ABI Format

The JSON of an ABI is the human-readable representation of the interface of a Sway contract.

Notation

Before describing the format of the JSON ABI, we provide some definitions that will make the JSON ABI spec easier to read.

Given the example below:

#![allow(unused)]
fn main() {
struct Foo { x: bool }
struct Bar<T> { y: T }

fn baz(input1: Foo, input2: Bar<u64>); // an ABI function
}

we define the following expressions:

• type declaration: the declaration or definition of a type which can be generic. struct Foo { .. } and struct Bar<T> { .. } in the example above are both type declarations.
• type application: the application or use of a type. Foo and Bar<u64> in fn baz(input1: Foo, input2: Bar<u64>); in the example above are both applications of the type declarations struct Foo { .. } and struct Bar<T> { .. } respectively.
• type parameter: a generic parameter used in a type declaration. T in struct Bar<T> in the example above is a type parameter.
• type argument: an application of a type parameter used in a type application. u64 in input2: Bar<u64> in the example above is a type argument.

JSON ABI Spec

The ABI of a contract is represented as a JSON object containing the following properties:

• "types": an array describing all the type declarations used (or transitively used) in the ABI. Each type declaration is a JSON object that contains the following properties:
  • "typeId": a unique integer ID.
  • "type": a string representation of the type declaration. The section JSON ABI Format for Each Possible Type Declaration specifies the format for each possible type.
  • "components": an array of the components of a given type, if any, and null otherwise. Each component is a type application represented as a JSON object that contains the following properties:
    • "name": the name of the component.
    • "type": the type declaration ID of the type of the component.
    • "typeArguments": an array of the type arguments used when applying the type of the component, if the type is generic, and null otherwise. Each type argument is a type application represented as a JSON object that contains the following properties:
      • "type": the type declaration ID of the type of the type argument.
      • "typeArguments": an array of the type arguments used when applying the type of the type argument, if the type is generic, and null otherwise. The format of the elements of this array recursively follows the rules described in this section.
  • "typeParameters": an array of type IDs of the type parameters of the type, if the type is generic, and null otherwise. Each type parameter is a type declaration and is represented as described in Generic Type Parameter.
• "functions": an array describing all the functions in the ABI. Each function is a JSON object that contains the following properties:
  • "name": the name of the function
  • "inputs": an array of objects that represents the inputs to the function (i.e. its parameters). Each input is a type application represented as a JSON object that contains the following properties:
    • "name": the name of the input.
    • "type": the type declaration ID of the type of the input.
    • "typeArguments": an array of the type arguments used when applying the type of the input, if the type is generic, and null otherwise. Each type argument is a type application represented as a JSON object that contains the following properties:
      • "type": the type declaration ID of the type of the type argument.
      • "typeArguments": an array of the type arguments used when applying the type of the type argument, if the type is generic, and null otherwise. The format of the elements of this array recursively follows the rules described in this section.
  • "output": an object representing the output of the function (i.e. its return value). The output is a type application, which is a JSON object that contains the following properties:
    • "type": the type declaration ID of the type of the output.
    • "typeArguments": an array of the type arguments used when applying the type of the output, if the type is generic, and null otherwise. Each type argument is a type application represented as a JSON object that contains the following properties:
      • "type": the type declaration ID of the type of the type argument.
      • "typeArguments": an array of the type arguments used when applying the type of the type argument, if the type is generic, and null otherwise. The format of the elements of this array recursively follows the rules described in this section.
  • "attributes": an optional array of attributes. Each attribute is explained in the dedicated section and is represented as a JSON object that contains the following properties:
    • "name": the name of the attribute.
    • "arguments": an array of attribute arguments.
• "loggedTypes": an array describing all instances of log or logd in the contract's bytecode. Each instance is a JSON object that contains the following properties:
  • "logId": a unique integer ID. The log and logd instructions must set their $rB register to that ID.
  • "loggedType": a type application represented as a JSON object that contains the following properties:
    • "type": the type declaration ID of the type of the value being logged.
    • "typeArguments": an array of the type arguments used when applying the type of the value being logged, if the type is generic, and null otherwise. Each type argument is a type application represented as a JSON object that contains the following properties:
      • "type": the type declaration ID of the type of the type argument.
      • "typeArguments": an array of the type arguments used when applying the type of the type argument, if the type is generic, and null otherwise. The format of the elements of this array recursively follows the rules described in this section.
• "messagesTypes": an array describing all instances of smo in the contract's bytecode. Each instance is a JSON object that contains the following properties:
  • "messageDataType": a type application represented as a JSON object that contains the following properties:
    • "type": the type declaration ID of the type of the message data being sent.
    • "typeArguments": an array of the type arguments used when applying the type of the message data being sent, if the type is generic, and null otherwise. Each type argument is a type application represented as a JSON object that contains the following properties:
      • "type": the type declaration ID of the type of the type argument.
      • "typeArguments": an array of the type arguments used when applying the type of the type argument, if the type is generic, and null otherwise. The format of the elements of this array recursively follows the rules described in this section.
• "configurables": an array describing all configurable variables used in the contract. Each configurable variable is represented as a JSON object that contains the following properties:
  • "name": the name of the configurable variable.
  • "configurableType": a type application represented as a JSON object that contains the following properties:
    • "type": the type declaration ID of the type of the configurable variable.
    • "typeArguments": an array of the type arguments used when applying the type of the configurable variable, if the type is generic, and null otherwise. Each type argument is a type application represented as a JSON object that contains the following properties:
      • "type": the type declaration ID of the type of the type argument.
      • "typeArguments": an array of the type arguments used when applying the type of the type argument, if the type is generic, and null otherwise. The format of the elements of this array recursively follows the rules described in this section.
  • "offset": the specific offset within the contract's bytecode, in bytes, to the data section entry for the configurable variable.

Note: This JSON should be both human-readable and parsable by the tooling around the FuelVM and the Sway programming language. There is a detailed specification for the binary encoding backing this readable descriptor. The Function Selector Encoding section specifies the encoding for the function being selected to be executed and each of the argument types.

Attributes Semantics

A Simple Example

Below is a simple example showing how the JSON ABI for an example that does not use generic or complex types. We will later go over more complex examples.

#![allow(unused)]
fn main() {
abi MyContract {
    fn first_function(arg: u64) -> bool;
    fn second_function(arg: b256);
}
}

the JSON representation of this ABI looks like:

{
  "types": [
    {
      "typeId": 0,
      "type": "()",
      "components": [],
      "typeParameters": null
    },
    {
      "typeId": 1,
      "type": "b256",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 2,
      "type": "bool",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 3,
      "type": "u64",
      "components": null,
      "typeParameters": null
    }
  ],
  "functions": [
    {
      "inputs": [
        {
          "name": "arg",
          "type": 3,
          "typeArguments": null
        }
      ],
      "name": "first_function",
      "output": {
        "type": 2,
        "typeArguments": null
      }
    },
    {
      "inputs": [
        {
          "name": "arg",
          "type": 1,
          "typeArguments": null
        }
      ],
      "name": "second_function",
      "output": {
        "type": 0,
        "typeArguments": null
      }
    }
  ],
  "loggedTypes": []
}

JSON ABI Format for Each Possible Type Declaration

Below is a list of the JSON ABI formats for each possible type declaration:

()

{
  "typeId": <id>,
  "type": "()",
  "components": null,
  "typeParameters": null
}

bool

{
  "typeId": <id>,
  "type": "bool",
  "components": null,
  "typeParameters": null
}

u8

{
  "typeId": <id>,
  "type": "u8",
  "components": null,
  "typeParameters": null
}

u16

{
  "typeId": <id>,
  "type": "u16",
  "components": null,
  "typeParameters": null
}

u32

{
  "typeId": <id>,
  "type": "u32",
  "components": null,
  "typeParameters": null
}

u64

{
  "typeId": <id>,
  "type": "u64",
  "components": null,
  "typeParameters": null
}

b256

{
  "typeId": <id>,
  "type": "b256",
  "components": null,
  "typeParameters": null
}

struct

{
  "typeId": <id>,
  "type": "struct <struct_name>",
  "components": [
    {
      "name": "<field1_name>",
      "type": <field1_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },
    {
      "name": "<field2_name>",
      "type": <field2_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },
    ...
  ],
  "typeParameters": [
    <type_param1_type_id>,
    <type_param2_type_id>,
    ...
  ]
}

enum

{
  "typeId": <id>,
  "type": "enum <enum_name>",
  "components": [
    {
      "name": "<variant1_name>",
      "type": <variant1_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },
    {
      "name": "<variant2_name>",
      "type": <variant2_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },
    ...
  ],
  "typeParameters": [
    <type_param1_type_id>,
    <type_param2_type_id>,
    ...
  ]
}

str[<n>]

{
  "typeId": <id>,
  "type": "str[<n>]",
  "components": null,
  "typeParameters": null
}

<n> is the length of the string.

array

{
  "typeId": <id>,
  "type": "[_; <n>]",
  "components": [
    {
      "name": "__array_element",
      "type": "<element_type>",
      "typeArguments": ...
    }
    {
      "name": "__array_element",
      "type": <element_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },

  ],
  "typeParameters": null
}

• <n> is the size of the array.

tuple

{
  "typeId": <id>,
  "type": "(_, _, ...)",
  "components": [
    {
      "name": "__tuple_element",
      "type": <field1_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },
    {
      "name": "__tuple_element",
      "type": <field2_type_id>,
      "typeArguments": [
        {
          "type": <type_arg1_type_id>,
          "typeArguments": ...
        },
        {
          "type": <type_arg2_type_id>,
          "typeArguments": ...
        },
        ...
      ]
    },
    ...
  ],
  "typeParameters": null
}

Generic Type Parameter

{
  "typeId": <id>,
  "type": "generic <name>",
  "components": null,
  "typeParameters": null
}

<name> is the name of the generic parameter as specified in the struct or enum declaration that uses it.

Some Complex Examples

An Example with Non-Generic Custom Types

Given the following ABI declaration:

#![allow(unused)]
fn main() {
enum MyEnum {
    Foo: u64,
    Bar: bool,
}

struct MyStruct {
    bim: u64,
    bam: MyEnum,
}

abi MyContract {
    /// this is a doc comment
    #[payable, storage(read, write)]
    fn complex_function(
        arg1: ([str[5]; 3], bool, b256),
        arg2: MyStruct,
    );
}
}

its JSON representation would look like:

{
  "types": [
    {
      "typeId": 0,
      "type": "()",
      "components": [],
      "typeParameters": null
    },
    {
      "typeId": 1,
      "type": "(_, _, _)",
      "components": [
        {
          "name": "__tuple_element",
          "type": 2,
          "typeArguments": null
        },
        {
          "name": "__tuple_element",
          "type": 4,
          "typeArguments": null
        },
        {
          "name": "__tuple_element",
          "type": 3,
          "typeArguments": null
        }
      ],
      "typeParameters": null
    },
    {
      "typeId": 2,
      "type": "[_; 3]",
      "components": [
        {
          "name": "__array_element",
          "type": 6,
          "typeArguments": null
        }
      ],
      "typeParameters": null
    },
    {
      "typeId": 3,
      "type": "b256",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 4,
      "type": "bool",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 5,
      "type": "enum MyEnum",
      "components": [
        {
          "name": "Foo",
          "type": 8,
          "typeArguments": null
        },
        {
          "name": "Bar",
          "type": 4,
          "typeArguments": null
        }
      ],
      "typeParameters": null
    },
    {
      "typeId": 6,
      "type": "str[5]",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 7,
      "type": "struct MyStruct",
      "components": [
        {
          "name": "bim",
          "type": 8,
          "typeArguments": null
        },
        {
          "name": "bam",
          "type": 5,
          "typeArguments": null
        }
      ],
      "typeParameters": null
    },
    {
      "typeId": 8,
      "type": "u64",
      "components": null,
      "typeParameters": null
    }
  ],
  "functions": [
    {
      "inputs": [
        {
          "name": "arg1",
          "type": 1,
          "typeArguments": null
        },
        {
          "name": "arg2",
          "type": 7,
          "typeArguments": null
        }
      ],
      "name": "complex_function",
      "output": {
        "type": 0,
        "typeArguments": null
      },
      "attributes": [
        {
          "name": "doc-comment",
          "arguments": [" this is a doc comment"]
        },
        {
          "name": "payable",
        },
        {
          "name": "storage",
          "arguments": ["read", "write"]
        }
      ]
    }
  ],
  "loggedTypes": []
}

An Example with Generic Types

Given the following ABI declaration:

#![allow(unused)]
fn main() {
enum MyEnum<T, U> {
    Foo: T,
    Bar: U,
}
struct MyStruct<W> {
    bam: MyEnum<W, W>,
}

abi MyContract {
    fn complex_function(
        arg1: MyStruct<b256>,
    );
}
}

its JSON representation would look like:

{
  "types": [
    {
      "typeId": 0,
      "type": "()",
      "components": [],
      "typeParameters": null
    },
    {
      "typeId": 1,
      "type": "b256",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 2,
      "type": "enum MyEnum",
      "components": [
        {
          "name": "Foo",
          "type": 3,
          "typeArguments": null
        },
        {
          "name": "Bar",
          "type": 4,
          "typeArguments": null
        }
      ],
      "typeParameters": [3, 4]
    },
    {
      "typeId": 3,
      "type": "generic T",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 4,
      "type": "generic U",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 5,
      "type": "generic W",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 6,
      "type": "struct MyStruct",
      "components": [
        {
          "name": "bam",
          "type": 2,
          "typeArguments": [
            {
              "type": 5,
              "typeArguments": null
            },
            {
              "type": 5,
              "typeArguments": null
            }
          ]
        }
      ],
      "typeParameters": [5]
    }
  ],
  "functions": [
    {
      "inputs": [
        {
          "name": "arg1",
          "type": 6,
          "typeArguments": [
            {
              "type": 1,
              "typeArguments": null
            }
          ]
        }
      ],
      "name": "complex_function",
      "output": {
        "type": 0,
        "typeArguments": null
      }
    }
  ],
  "loggedTypes": []
}

An Example with Logs

Given the following contract:

#![allow(unused)]
fn main() {
struct MyStruct<W> {
    x: W,
}

abi MyContract {
    fn logging();
}

...

fn logging() {
    log(MyStruct { x: 42 });
    log(MyStruct { x: true });
}
}

its JSON representation would look like:

{
  "types": [
    {
      "typeId": 0,
      "type": "()",
      "components": [],
      "typeParameters": null
    },
    {
      "typeId": 1,
      "type": "bool",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 2,
      "type": "generic W",
      "components": null,
      "typeParameters": null
    },
    {
      "typeId": 3,
      "type": "struct MyStruct",
      "components": [
        {
          "name": "x",
          "type": 2,
          "typeArguments": null
        }
      ],
      "typeParameters": [2]
    },
    {
      "typeId": 4,
      "type": "u64",
      "components": null,
      "typeParameters": null
    }
  ],
  "functions": [
    {
      "inputs": [],
      "name": "logging",
      "output": {
        "type": 0,
        "typeArguments": null
      }
    }
  ],
  "loggedTypes": [
    {
      "logId": 0,
      "loggedType": {
        "type": 3,
        "typeArguments": [
          {
            "type": 4,
            "typeArguments": null
          }
        ]
      }
    },
    {
      "logId": 1,
      "loggedType": {
        "type": 3,
        "typeArguments": [
          {
            "type": 1,
            "typeArguments": null
          }
        ]
      }
    }
  ]
}

Receipts

Upon execution of ABI calls, i.e scripts being executed, a JSON object representing a list of receipts will be returned to the caller. Below is the JSON specification of the possible receipt types. The root will be receipts_root which will include an array of receipts.

{
  "receipts_list":[
    {
      "type":"<receipt_type>",
      ...
    },
    ...
  ]
}

All receipts will have a type property:

• type: String; the type of the receipt. Can be one of:
  • Call
  • Return
  • ReturnData
  • Panic
  • Revert
  • Log
  • LogData
  • Transfer
  • TransferOut
  • ScriptResult
  • MessageOut

Then, each receipt type will have its own properties. Some of these properties are related to the FuelVM's registers, as specified in more detail here.

Important note: For the JSON representation of receipts, we represent 64-bit unsigned integers as a JSON String due to limitations around the type Number in the JSON specification, which only supports numbers up to 2^{53-1}, while the FuelVM's registers hold values up to 2^64.

Panic Receipt

• type: Panic.
• id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• reason: Decimal string representation of an 8-bit unsigned integer; panic reason.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.
• contractId: Optional hexadecimal string representation of the 256-bit (32-byte) contract ID if applicable. null otherwise. Not included in canonical receipt form. Primary use is for access-list estimation by SDK.

{
  "type": "Panic",
  "id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "reason": "1",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe",
  "contractId": "0x0000000000000000000000000000000000000000000000000000000000000000"
}

Return Receipt

• type: Return.
• id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context; null otherwise.
• val: Decimal string representation of a 64-bit unsigned integer; value of register $rA.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "Return",
  "id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "val": "18446744073709551613",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

Call Receipt

• type: Call.
• from: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context; null otherwise.
• to: Hexadecimal representation of the 256-bit (32-byte) contract ID of the callee.
• amount: Decimal string representation of a 64-bit unsigned integer; amount of coins to forward.
• asset_id: Hexadecimal string representation of the 256-bit (32-byte) asset ID of coins to forward.
• gas: Decimal string representation of a 64-bit unsigned integer; amount gas to forward; value in register $rD.
• param1: Hexadecimal string representation of a 64-bit unsigned integer; first parameter, holds the function selector.
• param2: Hexadecimal string representation of a 64-bit unsigned integer; second parameter, typically used for the user-specified input to the ABI function being selected.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "Call",
  "from": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "to": "0x1c98ff5d121a6d5afc8135821acb3983e460ef0590919266d620bfc7b9b6f24d",
  "amount": "10000",
  "asset_id": "0xa5149ac6064222922eaa226526b0d853e7871e28c368f6afbcfd60a6ef8d6e61",
  "gas": "500",
  "param1": "0x28f5c28f5c28f5c",
  "param2": "0x68db8bac710cb",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

Log Receipt

• type: Log.
• id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• val0: Decimal string representation of a 64-bit unsigned integer; value of register $rA.
• val1: Decimal string representation of a 64-bit unsigned integer; value of register $rB.
• val2: Decimal string representation of a 64-bit unsigned integer; value of register $rC.
• val3: Decimal string representation of a 64-bit unsigned integer; value of register $rD.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "Log",
  "id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "val0": "1844674407370",
  "val1": "1844674407371",
  "val2": "1844674407372",
  "val3": "1844674407373",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

LogData Receipt

• type: LogData.
• id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• val0: Decimal string representation of a 64-bit unsigned integer; value of register $rA
• val1: Decimal string representation of a 64-bit unsigned integer; value of register $rB
• ptr: Hexadecimal string representation of a 64-bit unsigned integer; value of register $rC.
• len: Decimal string representation of a 64-bit unsigned integer; value of register $rD.
• digest: Hexadecimal string representation of the 256-bit (32-byte) hash of MEM[$rC, $rD].
• data: Hexadecimal string representation of the value of the memory range MEM[$rC, $rD].
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "LogData",
  "id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "val0": "1844674407370",
  "val1": "1844674407371",
  "ptr": "0x1ad7f29abcc",
  "len": "66544",
  "digest": "0xd28b78894e493c98a196aa51b432b674e4813253257ed9331054ee8d6813b3aa",
  "pc": "0xffffffffffffffff",
  "data": "0xa7c5ac471b47",
  "is": "0xfffffffffffffffe"
}

ReturnData Receipt

• type: ReturnData.
• id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• ptr: Hexadecimal string representation of a 64-bit unsigned integer; value of register $rA.
• len: Decimal string representation of a 64-bit unsigned integer; value of register $rB.
• digest: Hexadecimal string representation of 256-bit (32-byte), hash of MEM[$rA, $rB].
• data: Hexadecimal string representation of the value of the memory range MEM[$rA, $rB].
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "ReturnData",
  "id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "ptr": "0x1ad7f29abcc",
  "len": "1844",
  "digest": "0xd28b78894e493c98a196aa51b432b674e4813253257ed9331054ee8d6813b3aa",
  "pc": "0xffffffffffffffff",
  "data": "0xa7c5ac471b47",
  "is": "0xfffffffffffffffe"
}

Revert Receipt

• type: Revert.
• id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• val: Decimal string representation of a 64-bit unsigned integer; value of register $rA.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "Revert",
  "id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "val": "1844674407372",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

Transfer Receipt

• type: Transfer.
• from: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• to: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the recipient contract.
• amount: Decimal string representation of a 64-bit unsigned integer; amount of coins to forward.
• asset_id: Hexadecimal string representation of the 256-bit (32-byte) asset ID of coins to forward.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "Transfer",
  "from": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "to": "0x1c98ff5d121a6d5afc8135821acb3983e460ef0590919266d620bfc7b9b6f24d",
  "amount": "10000",
  "asset_id": "0xa5149ac6064222922eaa226526b0d853e7871e28c368f6afbcfd60a6ef8d6e61",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

TransferOut Receipt

• type: TransferOut.
• from: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context if in an internal context. null otherwise.
• to: Hexadecimal string representation of the 256-bit (32-byte) address to transfer coins to.
• amount: Decimal string representation of a 64-bit unsigned integer; amount of coins to forward.
• asset_id: Hexadecimal string representation of the 256-bit (32-byte) asset ID of coins to forward.
• pc: Hexadecimal string representation of a 64-bit unsigned integer; value of register $pc.
• is: Hexadecimal string representation of a 64-bit unsigned integer; value of register $is.

{
  "type": "TransferOut",
  "from": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "to": "0x1c98ff5d121a6d5afc8135821acb3983e460ef0590919266d620bfc7b9b6f24d",
  "amount": "10000",
  "asset_id": "0xa5149ac6064222922eaa226526b0d853e7871e28c368f6afbcfd60a6ef8d6e61",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

ScriptResult Receipt

• type: ScriptResult.
• result: Hexadecimal string representation of a 64-bit unsigned integer; 0 if script exited successfully, any otherwise.
• gas_used: Decimal string representation of a 64-bit unsigned integer; amount of gas consumed by the script.

{
  "type": "ScriptResult",
  "result": "0x00",
  "gas_used": "400"
}

MessageOut Receipt

• type: MessageOut.
• sender: Hexadecimal string representation of the 256-bit (32-byte) address of the message sender: MEM[$fp, 32].
• recipient: Hexadecimal string representation of the 256-bit (32-byte) address of the message recipient: MEM[$rA, 32].
• amount: Hexadecimal string representation of a 64-bit unsigned integer; value of register $rD.
• nonce: Hexadecimal string representation of the 256-bit (32-byte) message nonce as described here.
• len: Decimal string representation of a 16-bit unsigned integer; value of register $rC.
• digest: Hexadecimal string representation of 256-bit (32-byte), hash of MEM[$rB, $rC].
• data: Hexadecimal string representation of the value of the memory range MEM[$rB, $rC].

{
  "type": "MessageOut",
  "sender": "0x38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff05139150017c9e",
  "recipient": "0x4710162c2e3a95a6faff05139150017c9e38e5e280432d546fae345d6ce6d8fe",
  "amount": "0xe6d8fe4710162c2e",
  "nonce": "0x47101017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "len": "65535",
  "digest": "0xd28b78894e493c98a196aa51b432b674e4813253257ed9331054ee8d6813b3aa",
  "data": "0xa7c5ac471b47"
}

Function Selector Encoding

To select which function you want to call, first, this function must be in an ABI struct of a Sway program. For instance:

#![allow(unused)]
fn main() {
abi MyContract {
    fn foo(a: u64);
    fn bar(a: InputStruct );
} {
    fn baz(a: ()) { }
}
}

The function selector is the first 4 bytes of the SHA-256 hash function of the signature of the Sway function being called. Then, these 4 bytes are right-aligned to 8 bytes, left-padded with zeroes.

Note: The word size for the FuelVM is 8 bytes.

Function Signature

The signature is composed of the function name with the parenthesized list of comma-separated parameter types without spaces. All strings encoded with UTF-8. For custom types such as enum and struct, there is a prefix added to the parenthesized list (see below). Generic struct and enum types also accept a list of comma-separated type arguments in between angle brackets right after the prefix.

For instance, to compute the selector for the following function:

#![allow(unused)]
fn main() {
    fn entry_one(arg: u64);
}

we should pass "entry_one(u64)" to the sha256() hashing algorithm. The full digest would be:

0x0c36cb9cb766ff60422db243c4fff06d342949da3c64a3c6ac564941f84b6f06

Then we would get only the first 4 bytes of this digest and left-pad it to 8 bytes:

0x000000000c36cb9c

The table below summarizes how each function argument type is encoded

Note: Non-generic structs and enums do not require angle brackets.

A Complex Example

#![allow(unused)]
fn main() {
enum MyEnum<V> {
    Foo: u64,
    Bar: bool,
}
struct MyStruct<T, U> {
    bim: T,
    bam: MyEnum<u64>,
}

struct MyOtherStruct {
    bom: u64,
}

fn complex_function(
    arg1: MyStruct<[b256; 3], u8>,
    arg2: [MyStruct<u64, bool>; 4],
    arg3: (str[5], bool),
    arg4: MyOtherStruct,
);
}

is encoded as:

abi MyContract {
    complex_function(s<a[b256;3],u8>(a[b256;3],e<u64>(u64,bool)),a[s<u64,bool>(u64,e<u64>(u64,bool));4],(str[5],bool),s(u64))
}

which is then hashed into:

51fdfdadc37ff569e281a622281af7ec055f8098c40bc566118cbb48ca5fd28b

and then the encoded function selector is:

0x0000000051fdfdad

Argument Encoding

When crafting transaction script data, you must encode the arguments you wish to pass to the script.

Types

These are the available types that can be encoded in the ABI:

• Unsigned integers:
  • u8, 8 bits.
  • u16, 16 bits.
  • u32, 32 bits.
  • u64, 64 bits.
• Boolean: bool, either 0 or 1 encoded identically to u8.
• B256: b256, arbitrary 256-bits value.
• Address : address, a 256-bit (32-byte) address.
• Fixed size string
• Array
• Enums (sum types)
• Structs

These types are encoded in-place. Here's how to encode them. We define enc(X) the encoding of the type X.

Unsigned Integers

u<M> where M is either 8, 16, 32, or 64 bits.

enc(X) is the big-endian (i.e. right-aligned) representation of X left-padded with zero-bytes. Total length must be 8 bytes.

Note: since all integer values are unsigned, there is no need to preserve the sign when extending/padding; padding with only zeroes is sufficient._

Example:

Encoding 42 yields: 0x000000000000002a, which is the hexadecimal representation of the decimal number 42, right-aligned to 8 bytes.

Boolean

enc(X) is 0 if X is false or 1 if X is true, left-padded with zero-bytes. Total length must be 8 bytes. Similar to the u8 encoding.

Example:

Encoding true yields:

0x0000000000000001

B256

b256 is a fixed size bit array of length 256. Used for 256-bit hash digests and other 256-bit types. It is encoded as-is.

Example:

Encoding 0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745 yields:

0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745

Address

A 256-bit (32-byte) address, encoded in the same way as a b256 argument: encoded as-is.

Example:

Encoding 0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745 yields:

0xc7fd1d987ada439fc085cfa3c49416cf2b504ac50151e3c2335d60595cb90745

Array

An array of a certain type T, [T; n], where n is the length of the array.

Arrays in Sway have a fixed-length which is known at compile time. This means the ABI encoding for arrays also happens in-place, with no need to account for dynamic sizing.

The encoding for the array contains, in order, the encoding of each element in [T; n], recursively following the encoding for the type T.

For instance, consider the function signature my_func(bool, [u64; 2]) with the values (true, [1, 2]).

The encoding will be:

1. 0x0000000000000001, the true bool encoded in-place.
2. 0x0000000000000001, First element of the parameter [u64; 2], 1, encoded as a u64.
3. 0x0000000000000002, Second element of the parameter [u64; 2], 2, encoded as a u64.

The resulting encoded ABI will be:

0x000000000000000100000000000000010000000000000002

Fixed-length Strings

Strings have fixed length and are encoded in-place. str[n], where n is the fixed-size of the string. Rather than padding the string, the encoding of the elements of the string is tightly packed. And unlike the other type encodings, the string encoding is left-aligned.

Note that all strings are encoded in UTF-8.

Example:

Encoding "Hello, World" as a str[12] yields:

0x48656c6c6f2c20576f726c6400000000

Note that we're padding with zeroes in order to keep it right-aligned to 8 bytes (FuelVM's word size).

Structs

Encoding ABIs that contain custom types, such as structs, is similar to encoding a set of primitive types. The encoding will proceed in the order that the inner types of a custom type are declared and recursively just like encoding any other type. This way you can encode structs with primitive types or structs with more complex types in them such as other structs, arrays, strings, and enums.

Here's an example:

#![allow(unused)]
fn main() {
struct InputStruct {
    field_1: bool,
    field_2: u8,
}


abi MyContract {
    fn foo(a: u64);
    fn bar(a: InputStruct);
} {
    fn baz(a: ()) { }
}
}

Calling bar with InputStruct { field_1: true, field_2: 5 } yields:

0x
0000000000000001 // `true` encoded as a bool
0000000000000005 // `5` encoded as u8

A more complex scenario:

#![allow(unused)]
fn main() {
struct InputStruct {
    field_1: bool,
    field_2: [u8; 2], // An array of u8, with length 2.
}


abi MyContract {
    fn foo(a: u64);
    fn bar(a: InputStruct);
} {
    fn baz(a: ()) { }
}
}

Calling bar with InputStruct { field_1: true, field_2: [1, 2] } yields:

0x
0000000000000001 // `true` encoded as a bool
0000000000000001 // `1` encoded as u8
0000000000000002 // `2` encoded as u8

Enums (sum types)

ABI calls containing enums (sum types) are encoded similarly to structs: encode the discriminant first, then recursively encode the type of the enum variant being passed to the function being called.

#![allow(unused)]
fn main() {
enum MySumType
{
    X: u32,
    Y: bool,
}

abi MyContract {
    fn foo(a: u64);
    fn bar(a: MySumType);
} {
    fn baz(a: ()) { }
}
}

Calling bar with MySumType::X(42) yields:

0x
0000000000000000 // The discriminant of the chosen enum, in this case `0`.
000000000000002a // `42` encoded as u64

If the sum type has variants of different sizes, then left padding is required.

#![allow(unused)]
fn main() {
enum MySumType
{
    X: b256,
    Y: u32,
}

abi MyContract {
    fn foo(a: u64);
    fn bar(a: MySumType);
} {
    fn baz(a: ()) { }
}
}

Calling bar with MySumType::Y(42) yields:

0x
0000000000000001 // The discriminant of the chosen enum, in this case `1`.
0000000000000000 // Left padding
0000000000000000 // Left padding
0000000000000000 // Left padding
000000000000002a // `42` encoded as u64

Note that three words of padding are required because the largest variant of MySumType is 4 words wide.

If all the variants of a sum type are of type (), or unit, then only the discriminant needs to be encoded.

#![allow(unused)]
fn main() {
enum MySumType
{
    X: (),
    Y: (),
    Z: (),
}

abi MyContract {
    fn foo(a: u64);
    fn bar(a: MySumType);
} {
    fn baz(a: ()) { }
}
}

Calling bar with MySumType::Z yields:

0x
0000000000000002 // The discriminant of the chosen enum, in this case `2`.

JSON Format for Contract Storage Initializers

Contracts can request that certain storage slots are initialized to specific values. These initialized slots are represented in JSON format as an array where each element represents a storage slot and has the following properties:

• "key": String, a 32-byte key for a given storage slot;
• "value": String, a 32-byte value that initializes the slot;

For instance, the following is a JSON object that requests that the 3 storage slots with keys 0x11..11, 0x22..22, and 0x33..33, are respectively initialized to the values indicated.

[
  {
    "key": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "value": "0x1010101010101010101010101010101010101010101010101010101010101010"
  }, 
  {
    "key": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "value": "0x2020202020202020202020202020202020202020202020202020202020202020"
  },
  {
    "key": "0x3333333333333333333333333333333333333333333333333333333333333333",
    "value": "0x0303030303030303030303030303030303030303030303030303030303030303"
  },
]

Block Header

Application Header

The application header is a network-agnostic block header. Different networks may wrap the application header in a consensus header, depending on their consensus protocol.

Fuel VM Specification

• Introduction
• Parameters
• Semantics
• Flags
• Instruction Set
• VM Initialization
• Contexts
• Predicate Estmation
• Predicate Verification
• Script Execution
• Call Frames
• Ownership

Introduction

This document provides the specification for the Fuel Virtual Machine (FuelVM). The specification covers the types, instruction set, and execution semantics.

Parameters

Semantics

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:

Integers are represented in big-endian format, and all operations are unsigned. Boolean false is 0 and Boolean true is 1.

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.

Flags

All other flags are reserved, any must be set to zero.

Instruction Set

A complete instruction set of the Fuel VM is documented in the following page.

VM Initialization

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:

1. Transaction hash (byte[32], word-aligned), computed as defined here.
2. MAX_INPUTS pairs of (asset_id: byte[32], balance: uint64), of:
   1. For predicate estimation and predicate verification, zeroes.
   2. For script execution, the free balance for each asset ID seen in the transaction's inputs, ordered in ascending order. If there are fewer than MAX_INPUTS asset IDs, the pair has a value of zero.
3. Transaction length, in bytes (uint64, word-aligned).
4. The transaction, serialized.

Then the following registers are initialized (without explicit initialization, all registers are initialized to zero):

1. $ssp = 32 + MAX_INPUTS*(32+8) + size(tx)): the writable stack area starts immediately after the serialized transaction in memory (see above).
2. $sp = $ssp: writable stack area is empty to start.
3. $hp = VM_MAX_RAM: the heap area begins at the top and is empty to start.

Contexts

There are 4 contexts in the FuelVM: predicate estimation, predicate verification, scripts, and calls. A context is an isolated execution environment with defined memory ownership and can be external or internal:

• External: predicate and script. $fp will be zero.
• Internal: call. $fp will be non-zero.

Returning from a context behaves differently depending on whether the context is external or internal.

Predicate Estimation

For any input of type InputType.Coin or InputType.Message, a non-zero predicateLength field means the UTXO being spent is a P2SH rather than a P2PKH output.

For each such input in the transaction, the VM is initialized, then:

1. $pc and $is are set to the start of the input's predicate field.
2. $ggas and $cgas are set to tx.gasLimit.

Predicate estimation will fail if gas is exhausted during execution.

During predicate mode, hitting any of the following instructions causes predicate estimation to halt, returning Boolean false:

1. Any contract instruction.

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 estimation halts returning Boolean false.

A predicate that halts without returning Boolean true would 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).

After successful execution, predicateGasUsed is set to tx.gasLimit - $ggas.

Predicate Verification

For any input of type InputType.Coin or InputType.Message, a non-zero predicateLength field means the UTXO being spent is a P2SH rather than a P2PKH output.

For each such input in the transaction, the VM is initialized, then:

1. $pc and $is are set to the start of the input's predicate field.
2. $ggas and $cgas are set to predicateGasUsed.

Predicate verification will fail if gas is exhausted during execution.

During predicate mode, hitting any contract instruction causes predicate verification to halt, returning Boolean false.

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 false.

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).

After execution, if $ggas is non-zero, predicate verification fails.

Script Execution

If script bytecode is present, transaction validation requires execution.

The VM is initialized, then:

1. $pc and $is are set to the start of the transaction's script bytecode.
2. $ggas and $cgas are set to tx.gasLimit minus the sum of predicateGasUsed for all predicates.

Following initialization, execution begins.

For each instruction, its gas cost gc is first computed. If gc > $cgas, deduct $cgas from $ggas and $cgas (i.e. spend all of $cgas and no more), then revert immediately without actually executing the instruction. Otherwise, deduct gc from $ggas and $cgas.

Call Frames

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:

1. 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.
2. 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:

Ownership

Whenever memory is written to (i.e. with SB or SW), or write access is granted (i.e. with CALL), ownership must be checked.

If the context is external, the owned memory range is:

1. [$ssp, $sp): the writable stack area.
2. [$hp, VM_MAX_RAM): the heap area allocated by this script or predicate.

If the context is internal, the owned memory range for a call frame is:

1. [$ssp, $sp): the writable stack area of the call frame.
2. [$hp, $fp->$hp): the heap area allocated by this call frame.

FuelVM 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
  • 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
  • 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
  • JEQB: Jump if not equal relative backwards
  • JEQF: 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
  • 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: Block proposer address
  • 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
  • ECR: Signature recovery
  • K256: keccak-256
  • S256: SHA-2-256
• Other Instructions
  • FLAG: Set flags
  • GM: Get metadata
  • GTF: Get transaction fields

Reading 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.

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, modifying tx.receiptsRoot:

then append an additional receipt to the list of receipts, again modifying tx.receiptsRoot:

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.

Arithmetic/Logic (ALU) Instructions

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

If the F_UNSAFEMATH flag is set, an ALU operation that would have panicked will instead set $err to true.

If the F_WRAPPING flag is set, an ALU operation that would have panicked will instead set $of to the overflow of the operation.

ADD: Add

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

ADDI: Add immediate

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

AND: AND

Panic if:

• $rA is a reserved register

$of and $err are cleared.

ANDI: 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.

DIV: 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.

DIVI: 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.

EQ: Equals

Panic if:

• $rA is a reserved register

$of and $err are cleared.

EXP: 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.

EXPI: 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.

GT: Greater than

Panic if:

• $rA is a reserved register

$of and $err are cleared.

LT: Less than

Panic if:

• $rA is a reserved register

$of and $err are cleared.

MLOG: 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.

MOD: 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.

MODI: 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.

MOVE: Move

Panic if:

• $rA is a reserved register

$of and $err are cleared.

MOVI: Move immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

MROO: 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.

MUL: Multiply

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

MULI: Multiply immediate

Panic if:

• $rA is a reserved register

$of is assigned the overflow of the operation.

$err is cleared.

NOOP: No operation

$of and $err are cleared.

NOT: Invert

Panic if:

• $rA is a reserved register

$of and $err are cleared.

OR: OR

Panic if:

• $rA is a reserved register

$of and $err are cleared.

ORI: 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.

SLL: Shift left logical

Panic if:

• $rA is a reserved register

$of and $err are cleared.

SLLI: Shift left logical immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

SRL: Shift right logical

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.

SRLI: Shift right logical 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.

SUB: 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.

SUBI: 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.

XOR: XOR

Panic if:

• $rA is a reserved register

$of and $err are cleared.

XORI: XOR immediate

Panic if:

• $rA is a reserved register

$of and $err are cleared.

Control Flow Instructions

JMP: Jump

Panic if:

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

JI: Jump immediate

Panic if:

• $is + imm * 4 > VM_MAX_RAM - 1

JNE: Jump if not equal

Panic if:

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

JNEI: Jump if not equal immediate

Panic if:

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

JNZI: Jump if not zero immediate

Panic if:

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

JMPB: Jump relative backwards

Panic if:

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

JMPF: Jump relative forwards

Panic if:

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

JNZB: Jump if not zero relative backwards

Panic if:

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

JNZF: Jump if not zero relative forwards

Panic if:

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

JEQB: Jump if not equal relative backwards

Panic if:

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

JEQF: Jump if not equal relative forwards

Panic if:

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

RET: Return from context

Append a receipt to the list of receipts, modifying tx.receiptsRoot:

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

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 restoring registers except $ggas, $cgas, $ret, and $retl. Afterwards, set the following registers:

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

Memory Instructions

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

ALOC: Allocate memory

Panic if:

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

CFE: Extend call frame

Panic if:

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

CFEI: Extend call frame immediate

Panic if:

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

CFS: Shrink call frame

Panic if:

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

CFSI: Shrink call frame immediate

Panic if:

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

LB: Load byte

Panic if:

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

LW: Load word

Panic if:

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

MCL: Memory clear

Panic if:

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

MCLI: Memory clear immediate

Panic if:

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

MCP: Memory copy

Panic if:

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

MCPI: Memory copy immediate

Panic if:

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

MEQ: 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
• $rD > MEM_MAX_ACCESS_SIZE

SB: 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

SW: 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

Contract Instructions

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

BAL: 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

BHEI: Block height

Panic if:

• $rA is a reserved register

BHSH: 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).

BURN: Burn existing coins

Panic if:

• Balance of asset ID MEM[$fp, 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 MEM[$fp, 32] by $rA.

This modifies the balanceRoot field of the appropriate output.

CALL: Call contract

Given helper balanceOfStart(asset_id: byte[32]) -> uint32 which returns the memory address of the remaining free balance of asset_id, or panics if asset_id has no free balance remaining.

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, modifying tx.receiptsRoot:

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).

CB: Block proposer address

Panic if:

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

CCP: 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
• $rD > MEM_MAX_ACCESS_SIZE
• Contract with ID MEM[$rB, 32] is not in tx.inputs

CROO: 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.

CSIZ: 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

LDC: 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
• $rC > MEM_MAX_ACCESS_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).

LOG: Log event

Append a receipt to the list of receipts, modifying tx.receiptsRoot:

LOGD: Log data event

Append a receipt to the list of receipts, modifying tx.receiptsRoot:

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

Panics if:

• $rC + $rD overflows
• $rA + $rD > VM_MAX_RAN
• $rD > MEM_MAX_ACCESS_SIZE

MINT: Mint new coins

Panic if:

• Balance of asset ID MEM[$fp, 32] 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 MEM[$fp, 32] by $rA.

This modifies the balanceRoot field of the appropriate output.

RETD: Return from context with data

Panic if:

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

Append a receipt to the list of receipts, modifying tx.receiptsRoot:

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

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 restoring registers except $ggas, $cgas, $ret, and $retl. Afterwards, set the following registers:

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

RVRT: Revert

Append a receipt to the list of receipts, modifying tx.receiptsRoot:

Then append an additional receipt to the list of receipts, modifying tx.receiptsRoot:

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.

SMO: Send message out

Given helper balanceOfStart(asset_id: byte[32]) -> uint32 which returns the memory address of the remaining free balance of asset_id, or panics if asset_id has no free balance remaining.

Panic if:

• $rA + 32 overflows
• $rB + $rC overflows
• $rA + 32 > VM_MAX_RAM
• $rB + $rC > VM_MAX_RAM
• $rC > MEM_MAX_ACCESS_SIZE
• $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, modifying tx.receiptsRoot:

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.

SCWQ: 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.

SRW: 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 any storage slot in the requested range is unset (default) and true if all the slots were set.

SRWQ: 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 were set.

SWW: 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 false if the storage slot was previously unset (default) and true if the slot was set.

SWWQ: 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 false if the first storage slot was previously unset (default) and true if the slot was set.

TIME: 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 format.

TR: Transfer coins to contract

Given helper balanceOfStart(asset_id: byte[32]) -> uint32 which returns the memory address of the remaining free balance of asset_id, or panics if asset_id has no free balance remaining.

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, modifying tx.receiptsRoot:

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).

TRO: Transfer coins to output

Given helper balanceOfStart(asset_id: byte[32]) -> uint32 which returns the memory address of the remaining free balance of asset_id, or panics if asset_id has no free balance remaining.

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, modifying tx.receiptsRoot:

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).

Cryptographic Instructions

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

ECR: 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.

K256: 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
• $rC > MEM_MAX_ACCESS_SIZE

S256: 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
• $rC > MEM_MAX_ACCESS_SIZE

Other Instructions

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

FLAG: Set flags

Panic if:

• Any reserved flags are set

GM: 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.

GTF: Get transaction fields

Get fields from the transaction.