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.

Transaction Format

The Fuel Transaction Format.

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

Consensus Parameters

Transaction

enum TransactionType : uint8 {
    Script = 0,
    Create = 1,
    Mint = 2,
    Upgrade = 3,
    Upload = 4,
}

Given helper max_gas() returns the maximum gas that the transaction can use. Given helper count_ones() that returns the number of ones in the binary representation of a field. Given helper count_variants() that returns the number of variants in an enum. Given helper sum_variants() that sums all variants of an enum.

Transaction is invalid if:

• type is not valid TransactionType value
• inputsCount > MAX_INPUTS
• outputsCount > MAX_OUTPUTS
• witnessesCount > MAX_WITNESSES
• size > MAX_TRANSACTION_SIZE. The size of a transaction is calculated as the sum of the sizes of its static and dynamic parts, as determined by canonical serialization.
• 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
• More than one output is of type OutputType.Change with identical asset_id fields.
• 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
• if type != TransactionType.Mint
  • max_gas(tx) > MAX_GAS_PER_TX
  • No policy of type PolicyType.MaxFee is set
  • count_ones(policyTypes) > count_variants(PolicyType)
  • policyTypes > sum_variants(PolicyType)
  • len(policies) > count_ones(policyTypes)

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,
    Mint = 11,
    Burn = 12,
}

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)

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

Note: when verifying a predicate or 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 input uses non-base asset.
• Any output is of type OutputType.Contract or OutputType.Variable or OutputType.Message
• Any output is of type OutputType.Change with non-base asset_id
• It does not have exactly one output of type OutputType.ContractCreated
• tx.data.witnesses[bytecodeWitnessIndex].dataLength > CONTRACT_MAX_SIZE
• 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. This means that the transaction ID must also include the correct txPointer value, not zeroed out.

Transaction is invalid if:

• txPointer is zero or doesn't match the block.
• outputContract.inputIndex is not zero

TransactionUpgrade

The Upgrade transaction allows upgrading either consensus parameters or state transition function used by the network to produce future blocks. The Upgrade Purpose type defines the purpose of the upgrade.

The Upgrade transaction is chargeable, and the sender should pay for it. Transaction inputs should contain only base assets.

Only the privileged address from ConsensusParameters can upgrade the network. The privileged address can be either a real account or a predicate.

When the upgrade type is UpgradePurposeType.ConsensusParameters serialized consensus parameters are available in the witnesses and the Upgrade transaction is self-contained because it has all the required information.

When the upgrade type is UpgradePurposeType.StateTransition, the bytecodeRoot field contains the Merkle root of the new bytecode of the state transition function. The bytecode should already be available on the blockchain at the upgrade point; otherwise, the upgrade will fail. The bytecode can be part of the genesis block or can be uploaded via the TransactionUpload transaction.

The block header contains information about which versions of consensus parameters and state transition function are used to produce a block, and the Upgrade transaction defines behavior corresponding to the version. When the block executes the Upgrade transaction, it defines new behavior for either BlockHeader.consensusParametersVersion + 1 or BlockHeader.stateTransitionBytecodeVersion + 1(it depends on the purpose of the upgrade).

When the Upgrade transaction is included in the block, it doesn't affect the current block execution. Since behavior is now defined, the inclusion of the Upgrade transaction allows the production of the next block with a new version. The block producer can still continue to use the previous version and start using a new version later unless the state transition function forbids it.

The behavior is set once per version. It is forbidden to override the behavior of the network. Each behavior should have its own version. The version should grow monotonically without jumps.

The BlockHeader.consensusParametersVersion and BlockHeader.stateTransitionBytecodeVersion are independent and can grow at different speeds.

Transaction is invalid if:

• Any input is of type InputType.Contract or InputType.Message where input.dataLength > 0
• Any input uses non-base asset.
• Any output is of type OutputType.Contract or OutputType.Variable or OutputType.Message or OutputType.ContractCreated
• Any output is of type OutputType.Change with non-base asset_id
• No input where InputType.Message.owner == PRIVILEGED_ADDRESS or InputType.Coint.owner == PRIVILEGED_ADDRESS
• The UpgradePurpose is invalid

TransactionUpload

The Upload transaction allows the huge bytecode to be divided into subsections and uploaded slowly to the chain. The Binary Merkle root built on top of subsections is an identifier of the bytecode.

Each transaction uploads a subsection of the code and must contain proof of connection to the root. All subsections should be uploaded sequentially, which allows the concatenation of previously uploaded subsections with new subsection. The bytecode is considered final when the last subsection is uploaded, and future Upload transactions with the same root fields should be rejected.

When the bytecode is completed it can be used to upgrade the network.

The size of each subsection can be arbitrary; the only limit is the maximum number of subsections allowed by the network. The combination of the transaction gas limit and the number of subsections limits the final maximum size of the bytecode.

Transaction is invalid if:

• Any input is of type InputType.Contract or InputType.Message where input.dataLength > 0
• Any input uses non-base asset.
• Any output is of type OutputType.Contract or OutputType.Variable or OutputType.Message or OutputType.ContractCreated
• Any output is of type OutputType.Change with non-base asset_id
• witnessIndex >= tx.witnessesCount
• subsectionIndex >= subsectionsNumber
• subsectionsNumber > MAX_BYTECODE_SUBSECTIONS
• The Binary Merkle tree root calculated from (witnesses[witnessIndex], subsectionIndex, subsectionsNumber, proofSet) is not equal to the root. Root calculation is affected by all fields, so modification of one of them invalidates the proof.

UpgradePurposeType

enum UpgradePurposeType : uint8 {
    ConsensusParameters = 0,
    StateTransition = 1,
}

Transaction is invalid if:

• type is not valid UpgradePurposeType value`

ConsensusParameters

Given helper deserialize_consensus_parameters() that deserializes the consensus parameters from a witness by using postcard algorithm.

Transaction is invalid if:

• witnessIndex >= tx.witnessesCount
• checksum != sha256(tx.data.witnesses[witnessIndex])
• deserialize_consensus_parameters(tx.data.witnesses[witnessIndex]) returns an error.

StateTransition

Policy

// index using powers of 2 for efficient bitmasking
enum PolicyType : uint32 {
    Tip = 1,
    WitnessLimit = 2,
    Maturity = 4,
    MaxFee = 8,
}

Tip

WitnessLimit

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

Transaction is invalid if:

• len(tx.witnesses) > witnessLimit

Maturity

Transaction is invalid if:

• blockheight() < maturity

MaxFee

Transaction is invalid if:

• max_fee > sum_inputs(tx, BASE_ASSET_ID) - sum_outputs(tx, BASE_ASSET_ID)
• max_fee < max_fee(tx, BASE_ASSET_ID, gas_price)

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

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

Note: when verifying and estimating a predicate or executing a script, txPointer and predicateGasUsed are 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 or executing a script, txID, outputIndex, balanceRoot, stateRoot, and txPointer are 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 verifying and 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 or executing a script, balanceRoot and stateRoot are initialized to zero.

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.

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

Asset ID

The asset ID (also called asset hash) of a asset is computed as the hash of the CONTRACT_ID and a 256-bit SUB_IDENTIFIER.

sha256(CONTRACT_ID ++ SUB_IDENTIFIER)

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 16KiB of instructions, and root_smt is the Sparse Merkle tree root of the provided key-value pairs. If the bytecode is not a multiple of 16 KiB, the final leaf should be zero-padded rounding up to the nearest multiple of 8 bytes.

Predicate ID

For an input of type InputType.Coin or InputType.Message, input, the predicate owner is calculated as: sha256(0x4655454C ++ root(input.predicate)), where root is the Merkle root of the binary Merkle tree each leaf being 16KiB of instructions. If the bytecode is not a multiple of 16 KiB, the final leaf should be zero-padded rounding up to the nearest multiple of 8 bytes.

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

UTXO ID

Coin ID

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

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 uint16 (with canonical encoding): hash(byte[32] ++ canonical(uint16)).

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

Protocol

• Transaction Validity
• Cryptographic Primitives
• Storage Slot Initialization
• Block Header Format

Transaction Validity

• Transaction Life Cycle
• 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 Life Cycle

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 assetId in the input and output set:

def gas_to_fee(gas, gasPrice) -> int:
    """
    Converts gas units into a fee amount
    """
    return ceil(gas * gasPrice / GAS_PRICE_FACTOR)


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


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


def transaction_size_gas_fees(tx) -> int:
    """
    Computes the intrinsic gas cost of a transaction based on size in bytes
    """
    return size(tx) * GAS_PER_BYTE


def minted(tx, assetId) -> int:
    """
    Returns any minted amounts by the transaction
    """
    if tx.type != TransactionType.Mint or assetId != tx.mintAssetId:
        return 0
    return tx.mint_amount


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


def input_gas_fees(tx) -> int:
    """
    Computes the intrinsic gas cost of verifying input utxos
    """
    total: int = 0
    witnessIndices = set()
    for input in tx.inputs:
        if input.type == InputType.Coin or input.type == InputType.Message:
            # add fees allocated for predicate execution
            if input.predicateLength == 0:
                # notate witness index if input is signed
                witnessIndices.add(input.witnessIndex)
            else:
                # add intrinsic gas cost of predicate merkleization based on number of predicate bytes
                total += contract_code_root_gas_fee(input.predicateLength)
                total += input.predicateGasUsed
                # add intrinsic cost of vm initialization
                total += vm_initialization_gas_fee()
    # add intrinsic cost of verifying witness signatures
    total += len(witnessIndices) * eck1_recover_gas_fee()
    return total


def metadata_gas_fees(tx) -> int:
    """
    Computes the intrinsic gas cost of processing transaction outputs
    
    The `contract_code_root_gas_fee`, `sha256_gas_fee`, and `contract_state_root_gas_fee` 
    are based on the benchmarked gas costs of these operations.
    
    Consensus parameters contain definitions of gas costs for all operations and opcodes in the network.
    """
    total: int = 0
    if tx.type == TransactionType.Create:
        for output in tx.outputs:
            if output.type == OutputType.OutputContractCreated:
                # add intrinsic cost of calculating the code root based on the size of the contract bytecode
                total += contract_code_root_gas_fee(tx.witnesses[tx.bytecodeWitnessIndex].dataLength)
                # add intrinsic cost of calculating the state root based on the number of sotrage slots
                total += contract_state_root_gas_fee(tx.storageSlotCount)
                # add intrinsic cost of calculating the contract id 
                # size = 4 byte seed + 32 byte salt + 32 byte code root + 32 byte state root
                total += sha256_gas_fee(100)
    elif tx.type == TransactionType.Upgrade:
        if tx.upgradePurpose.type == UpgradePurposeType.ConsensusParameters:
            # add intrinsic cost of calculating the consensus parameters hash
            total += sha256_gas_fee(size(tx.witnesses[tx.upgradePurpose.witnessIndex].data))
    elif tx.type == TransactionType.Upload:
        # add intrinsic cost of calculating the root based on the number of bytecode subsections
        total += contract_state_root_gas_fee(tx.subsectionsNumber)
        # add intrinsic cost of hashing the subsection for verification of the connection with Binary Merkle tree root
        total += sha256_gas_fee(size(tx.witnesses[tx.witnessIndex]))
            
    if tx.type != TransactionType.Mint:
        # add intrinsic cost of calculating the transaction id
        total += sha256_gas_fee(size(tx))
    return total


def intrinsic_gas_fees(tx) -> int:
    """
    Computes intrinsic costs for a transaction
    """
    fees: int = 0
    # add the cost of initializing a vm for the script
    if tx.type == TransactionType.Create or tx.type == TransactionType.Script:
        fees += vm_initialization_gas_fee()
        fees += metadata_gas_fees(tx)
        fees += intrinsic_input_gas_fees(tx)
    return fees


def min_gas(tx) -> int:
    """
    Comutes the minimum amount of gas required for a transaction to begin processing.
    """
    gas = transaction_size_gas_fees(tx) + intrinsic_gas_fees(tx)
    if tx.type == TransactionType.Upload
        # charge additionally for storing bytecode on chain
        gas += transaction_size_gas_fees(size(tx.witnesses[tx.witnessIndex]))
        
    return gas


def max_gas(tx) -> int:
    """
    Computes the amount of gas required to process a transaction.
    """
    gas = min_gas(tx)
    gas = gas + (tx.witnessBytesLimit - tx.witnessBytes) * GAS_PER_BYTE
    if tx.type == TransactionType.Script:
       gas += tx.gasLimit
    return gas
    
    
def maxFee(tx, assetId, gasPrice) -> int:
    """
    Computes the maximum potential amount of fees that may need to be charged to process a transaction.
    """
    maxGas = max_gas(tx)
    feeBalance = gas_to_fee(maxGas, gasPrice)
    # Only base asset can be used to pay for gas
    if assetId == 0:
        return feeBalance
    else:
        return 0


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


def unavailable_balance(tx, assetId) -> int:
    sentBalance = sum_outputs(tx, assetId)
    # Total fee balance
    feeBalance = tx.policies.max_fee
    # Only base asset can be used to pay for gas
    if assetId == 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, assetId) >= (unavailable_balance(tx, assetId) + sum_data_messages(tx, assetId))

Valid Signatures

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

for input in tx.inputs:
    if (input.type == InputType.Coin or 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_k1(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 assetId in the input set, the free balance available to be moved around by the script and called contracts is freeBalance[assetId]. The initial message balance available to be moved around by the script and called contracts is messageBalance:

freeBalance[assetId] = available_balance(tx, assetId) - unavailable_balance(tx, assetId)
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.

size(tx) encompasses the entire transaction serialized according to the transaction format, including witness data. This ensures every byte of block space either on Fuel or corresponding DA layer can be accounted for.

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

Fees

The cost of a transaction can be described by:

def cost(tx, gasPrice) -> int:
    return gas_to_fee(min_gas(tx) + tx.gasLimit - unspentGas, gasPrice)

where:

• min_gas(tx) is the minimum cost of the transaction in gas, including intrinsic gas fees incurred from:
  • The number of bytes comprising the transaction
  • Processing inputs, including predicates
  • Processing outputs
  • VM initialization
• unspentGas is the amount gas left over after intrinsic fees and execution of the transaction, extracted from the $ggas register. Converting unspent gas to a fee describes how much "change" is left over from the user's payment; the block producer collects this unspent gas as reward.
• gas_to_fee is a function that converts gas to a concrete fee based on a given gas price.

Fees incurred by transaction processing outside the context of execution are collectively referred to as intrinsic fees. Intrinsic fees include the cost of storing the transaction, calculated on a per-byte basis, the cost of processing inputs and outputs, including predicates and signature verification, and initialization of the VM prior to any predicate or script execution. Because intrinsic fees are independent of execution, they can be determined a priori and represent the bare minimum cost of the transaction.

A naturally occurring result of a variable gas limit is the concept of minimum and maximum fees. The minimum fee is, thus, the exact fee required to pay the fee balance, while the maximum fee is the minimum fee plus the gas limit:

min_gas = min_gas(tx)
max_gas = min_gas + (tx.witnessBytesLimit - tx.witnessBytes) * GAS_PER_BYTE + tx.gasLimit
min_fee = gas_to_fee(min_gas, gasPrice)
max_fee = gas_to_fee(max_gas, gasPrice)

The cost of the transaction cost(tx) must lie within the range defined by [min_fee, max_fee]. min_gas is defined as the sum of all intrinsic costs of the transaction known prior to execution. The definition of max_gas illustrates that the delta between minimum gas and maximum gas is the sum of:

• The remaining allocation of witness bytes, converted to gas
• The user-defined tx.gasLimit

Note that gasLimit applies to transactions of type Script. gasLimit is not applicable for transactions of type Create and is defined to equal 0 in the above formula.

A transaction cost cost(tx), in gas, greater than max_gas is invalid and must be rejected; this signifies that the user must provide a higher gas limit for the given transaction. min_fee is the minimum reward the producer is guaranteed to collect, and max_fee is the maximum reward the producer is potentially eligible to collect. In practice, the user is always charged intrinsic fees; thus, unspentGas is the remainder of max_gas after intrinsic fees and the variable cost of execution. Calculating a conversion from unspentGas to an unspent fee describes the reward the producer will collect in addition to min_fee.

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 * 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 * 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 collect transaction fees.

In order for a coinbase transaction to be valid:

1. It must be a Mint transaction.
2. The coinbase transaction must be the last transaction within a block, even if there are no other transactions in the block and the fee is zero.
3. The mintAmount doesn't exceed the total amount of fees processed from all other transactions within the same block.
4. The mintAssetId matches the assetId that fees are paid in (assetId == 0).

The minted amount of the coinbase transaction intrinsically increases the balance corresponding to the inputContract. This means the balance of mintAssetId is directly increased by mintAmount on the input contract, without requiring any VM execution. Compared to coin outputs, intrinsically increasing a contract balance to collect coinbase amounts prevents the accumulation of dust during low-usage periods.

Cryptographic Primitives

• Hashing
• Merkle Trees
  • Binary Merkle Tree
  • Sparse Merkle Tree
• EcDSA Public-Key Cryptography
• EdDSA Public-Key Cryptography

Hashing

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

HashDigest

Output of the hashing function. Exactly 256 bits (32 bytes) long.

Merkle Trees

Two Merkle tree structures are used: a Binary Merkle Tree (to commit to bytecode) and a Sparse Merkle Tree (to commit to contract storage, i.e. state).

Binary Merkle Tree

Binary Merkle trees are constructed in the same fashion as described in Certificate Transparency (RFC-6962), except for using a different hashing function. Leaves are hashed once to get leaf node values and internal node values are the hash of the concatenation of their children (either leaf nodes or other internal nodes).

Nodes contain a single field:

The base case (an empty tree) is defined as the hash of the empty string:

node.v = 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

For leaf node node of leaf data d:

node.v = h(0x00, serialize(d))

For internal node node with children l and r:

node.v = h(0x01, l.v, r.v)

Note that rather than duplicating the last node if there are an odd number of nodes (the Bitcoin design), trees are allowed to be imbalanced. In other words, the height of each leaf may be different. For an example, see Section 2.1.3 of Certificate Transparency (RFC-6962).

Leaves and internal nodes are hashed differently: the one-byte 0x00 is prepended for leaf nodes while 0x01 is prepended for internal nodes. This avoids a second-preimage attack where internal nodes are presented as leaves trees with leaves at different heights.

Binary Merkle Tree Inclusion Proofs

A proof for a leaf in a binary Merkle tree, as per Section 2.1.1 of Certificate Transparency (RFC-6962).

In some contexts, the array of sibling hashes is also known as the proof set. Note that proof format prescribes that leaf data be in its original, unhashed state, while the proof set (array of sibling data) uses hashed data. This format precludes the proof set from itself including the leaf data from the leaf undergoing the proof; rather, proof verification explicitly requires hashing the leaf data during the calculation of the proof set root.

Sparse Merkle Tree

Sparse Merkle Trees (SMTs) are sparse, i.e. they contain mostly empty leaves. They can be used as key-value stores for arbitrary data, as each leaf is keyed by its index in the tree. Storage efficiency is achieved through clever use of implicit defaults, avoiding the need to store empty leaves.

Additional rules are added on top of plain binary Merkle trees:

1. Default values are given to leaf nodes with empty leaves.
2. While the above rule is sufficient to pre-compute the values of intermediate nodes that are roots of empty subtrees, a further simplification is to extend this default value to all nodes that are roots of empty subtrees. The 32-byte zero, i.e. 0x0000000000000000000000000000000000000000000000000000000000000000, is used as the default value. This rule takes precedence over the above one.
3. The number of hashing operations can be reduced to be logarithmic in the number of non-empty leaves on average, assuming a uniform distribution of non-empty leaf keys. An internal node that is the root of a subtree that contains exactly one non-empty leaf is replaced by that leaf's leaf node.

Nodes contain a single field:

In the base case, where a sparse Merkle tree has height = 0, the root of a tree is defined as the hash of the empty string:

node.v = 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

When a sparse Merkle tree has a height of 0, it can have no leaves, and, therefore, no default value children. The root is then calculated as the hash of the empty string, similar to that of an empty binary Merkle tree.

For a tree with height > 0, the root of an empty tree is defined as the default value:

node.v = 0x0000000000000000000000000000000000000000000000000000000000000000

Note that this is in contrast to the base case of the sparse and binary Merkle trees, where the root is the hash of the empty string. When a sparse Merkle tree has a height greater than 0, a new tree instance is composed of default value leaves. Nodes containing only default value children have the default value as well. Applying these rules recursively percolates the default value up to the tree's root.

For leaf node node of leaf data d with key k:

node.v = h(0x00, k, h(serialize(d)))

The key of leaf nodes must be prepended, since the index of a leaf node that is not at maximum depth cannot be determined without this information. Leaf values are hashed so that they do not need to be included in full in non-membership proofs.

For internal node node with children l and r:

node.v = h(0x01, l.v, r.v)

Insertion

Before insertion of the key-value pair, each key of the Sparse Merkle Tree should be hashed with sha256 to prevent tree structure manipulations. During the proof verification, the original leaf key should be hashed similarly. Otherwise, the root will not match.

Sparse Merkle Tree Inclusion Proofs

SMTs can further be extended with compact proofs. Merkle proofs are composed, among other things, of a list of sibling node values. We note that, since nodes that are roots of empty subtrees have known values (the default value), these values do not need to be provided explicitly; it is sufficient to simply identify which siblings in the Merkle branch are roots of empty subtrees, which can be done with one bit per sibling.

For a Merkle branch of height h, an h-bit value is appended to the proof. The lowest bit corresponds to the sibling of the leaf node, and each higher bit corresponds to the next parent. A value of 1 indicates that the next value in the list of values provided explicitly in the proof should be used, and a value of 0 indicates that the default value should be used.

A proof into an SMT is structured as:

The includedSiblings is ordered by most-significant-byte first, with each byte ordered by most-significant-bit first. The lowest bit corresponds to the leaf node level.

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

ECDSA Public-Key Cryptography

Consensus-critical data is authenticated using ECDSA, with the curve secp256k1. A highly-optimized library is available in C, with wrappers in Go and Rust.

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.

EdDSA Public-Key Cryptography

Ed25519 is supported for use by applications built on Fuel. Edwards curve operations are performed by the ed25519-dalek Rust library.

Public keys are encoded in compressed form as specified by the Ed25519 format RFC-8032 5.1.5. Point compression is performed by replacing the most significant bit in the final octet of the y coordinate with the sign bit from the x coordinate:

#![allow(unused)]
fn main() {
let mut pk = y;
pk ^= x.is_negative().unwrap_u8() << 7;
}

Public keys are required to be strong enough to prevent malleability, and are checked for weakness during signature verification.

Signatures are 64 bytes, represented as the concatenation of R (32 bytes) and S (32 bytes) Where R and S are defined in RFC-8032 5.1.6.

Signatures must conform to strict verification requirements to avoid malleability concerns. While this is not part of the original Ed25519 specification, it has become a growing concern especially in cryptocurrency applications.

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.

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
  • Mint
  • Burn
  • 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"
}

Mint Receipt

• type: Mint.
• sub_id: Hexadecimal string representation of the 256-bit (32-byte) asset sub identifier ID; derived from register $rB.
• contract_id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context.
• 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": "Mint",
  "sub_id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "contract_id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "val": "18446744073709551613",
  "pc": "0xffffffffffffffff",
  "is": "0xfffffffffffffffe"
}

Burn Receipt

• type: Burn.
• sub_id: Hexadecimal string representation of the 256-bit (32-byte) asset sub identifier ID; derived from register $rB.
• contract_id: Hexadecimal string representation of the 256-bit (32-byte) contract ID of the current context.
• 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": "Burn",
  "sub_id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "contract_id": "0x39150017c9e38e5e280432d546fae345d6ce6d8fe4710162c2e3a95a6faff051",
  "val": "18446744073709551613",
  "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

Version 0

:warning: This version is being deprecated for Version 1 (see below).

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.
  • u128, 128 bits.
  • u256, 256 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
• Vectors
• Tuples

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, 64, 128 or 256 bits.

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

• In the case of M being 8, 16, 32 or 64, total length must be 8 bytes.
• If M is 128, total length must be 16 bytes.
• If M is 256, total length must be 32 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. Encoding u128::MAX - 1 yields: 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFE, it's right-aligned to 16 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`.

Vectors

ABI calls containing vectors are encoded in the following way:

• First, figure out the the length l of the vector. Its length will also be its capacity.
• Encode the content of the vector according to the spec of its type, e.g. for a Vec<bool>, encode each bool element according to the bool specs. This gives out data that is stored on the heap, and we encode only the pointer to this data

#![allow(unused)]
fn main() {
abi MyContract {
  fn foo(a: Vec<u32>);
} {
  fn foo(a: Vec<u32>) {};
}
}

Calling foo with vec![1u32, 2u32, 3u32, 4u32]:

• length is 4, capacity is 4
• data: [0x0000000000000001, 0x0000000000000002, 0x0000000000000003, 0x0000000000000004], stored at pointer address 0x000000000000beef

Note: to understand how the u32 are encoded, see the section about encoding integers.

0x
000000000000beef // pointer address
0000000000000004 // length = 4
0000000000000004 // capacity = 4

At the pointer address, then the vector's content are encoded as such:

0x
0000000000000001 // 1u32
0000000000000002 // 2u32
0000000000000003 // 3u32
0000000000000004 // 4u32

Tuples

ABI calls containing tuples are encoded as such: If X is a tuple with the type signature (T_1, T_2, ..., T_n), with T_1,...,T_n being any type except for vector, then enc(X) is encoded as the concatenation of enc(T_1), enc(T_2),enc (T_3), ..., enc(T_n).

#![allow(unused)]
fn main() {
abi MyContract {
  fn foo(a: (u64, str[3], bool));
} {
  fn foo(a: (u64, str[4], bool)) {};
}
}

Calling foo with (1u64, "fuel", true) :

0x
0000000000000001 // 1u64
6675656c00000000 // "fuel" encoded as per the specs
0000000000000001 // true

Version 1

This version was created to replace the older version 0 described above, and follows three philosophical tenets:

• being self-sufficient: it must be possible to completely decode the original data only using the encoded bytes and the original type (there are no references to data outside the encoded bytes);
• no overhead: only the bare minimum bytes are necessary to do the encoding. No metadata, headers, etc...;
• no relation with runtime memory layout: no padding, no alignment, etc...

Primitive Types

Primitive types will be encoded using the exact number of bits they need:

• u8: 1 byte;
• u16: 2 bytes;
• u32: 4 bytes;
• u64: 8 bytes;
• u256: 32 bytes;
• b256: 32 bytes;

Arrays

Arrays are encoded without any padding or alignment, with one item after the other.

• [T; 1] is encoded [encode(T)];
• [T; 2] is encoded [encode(T), encode(T)]

Strings

String arrays are encoded just like arrays, without any overhead.

• str[1] = 1 byte
• str[2] = 2 bytes
• str[n] = n bytes

String slices do contain their length as u64, and the string itself is encoded packed without alignment or padding.

• "abc" = [0, 0, 0, 0, 0, 0, 0, 3, "a", "b", "c"]

Slices

raw_slice, also being dynamic, contains their length as u64 and is treated as a "slice of bytes". Each byte is encoded as u8 (1 byte) and is packed without alignment and padding.

For example, a slice of three bytes like [0u8, 1u8, 2u8] will be encoded as bytes [0, 0, 0, 0, 0, 0, 0, 3, 0, 1, 2]

Tuple

Tuples are encoded just like arrays, without any overhead like padding and alignment:

• (A, B, C) = [encode(A), encode(B), encode(C)]

Structs (v1)

Structs can be encoded in two ways:

• first, with the automatic implementation;
• second, with the custom implementation.

Auto implementation follows the same rules as tuples. So we can imagine that

struct S {
    a: A,
    b: B,
    c: C
}

is encoded the same way as the tuple (A, B, C).

Custom implementation allows the developer to choose how a struct is encoded.

A struct has auto-implemented encoding if no custom was found.

Enums

Enums can also be encoded with the automatic or the custom implementation.

The auto implementation first encoded the variant with a u64 number starting from zero as the first variant and increments this value for each variant, following declaration order.

enum E {
    VARIANT_A: A, // <- variant 0
    VARIANT_B: B, // <- variant 1
    VARIANT_C: C  // <- variant 2 
}

will be encoded as [encode(variant), encode(value)].

The variant data will be encoded right after the variant tag, without any alignment or padding.

An enum has auto-implemented encoding if no custom was found.

Data Structures

Some common data structures also have well-defined encoding:

• Vec will be encoded as [encode(length), <encode each item>]
• Bytes will be encoded as [encode(length), <bytes>]
• String will be encoded as [encode (length), <data>]

All of them first contain the length and then their data right after, without any padding or alignment.

Fuel VM Specification

• Introduction
• Parameters
• Semantics
• Flags
• Instruction Set
• VM Initialization
• Contexts
• Predicate Estimation
• 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 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. Base asset ID (byte[32], word-aligned)
3. 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.
4. Transaction length, in bytes (uint64, word-aligned).
5. The transaction, serialized.

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

1. $ssp = 32 + 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 MAX_GAS_PER_PREDICATE.

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 MAX_GAS_PER_PREDICATE - $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.scriptGasLimit.

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.

After the script has been executed, tx.receiptsRoot is updated to contain the Merkle root of the receipts, as described in the TransactionScript spec.

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:

Access rights

Only memory that has been allocated is accessible. Attempting to read or write memory that has not been allocated will result in VM panic. Similarly reads or writes that cross from the stack to the heap will panic. Note stack remains readable even after stack frame has been shrunk. However, if heap is alter expanded to cover that area, the crossing read prohibition still remains. In other word, memory between highest-ever $sp value and current $hp is inaccessible.

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.

Executablity

Memory is only executable in range [$is, $ssp). Attempting to execute instructions outside these boundaries will panic. This area never overlaps with writable registers, essentially providing W^X protection.

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

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.

Panics

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

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

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

then append an additional receipt to the list of receipts:

Receipts

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

Effects

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.

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

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

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.

MLDV: Fused multiply-divide

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

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

$err is cleared.

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 and $err are cleared.

SRLI: Shift right logical immediate

Panic if:

• $rA is a reserved register

$of and $err are 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.

WDCM: 128-bit integer comparison

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

Then the actual operation that's performed:

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

Clears $of and $err.

Panic if:

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

WQCM: 256-bit integer comparison

The immediate value is interpreted identically to WDCM.

Clears $of and $err.

Panic if:

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

WDOP: Misc 128-bit integer operations

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

Then the actual operation that's performed:

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

Panic if:

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

WQOP: Misc 256-bit integer operations

The immediate value is interpreted identically to WDOP.

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

Panic if:

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

WDML: Multiply 128-bit integers

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

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

$err is cleared.

Panic if:

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

WQML: Multiply 256-bit integers

The immediate value is interpreted identically to WDML.

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

$err is cleared.

Panic if:

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

WDDV: 128-bit integer division

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

$of is cleared.

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

Panic if:

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

WQDV: 256-bit integer division

The immediate value is interpreted identically to WDDV.

$of is cleared.

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

Panic if:

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

WDMD: 128-bit integer fused multiply-divide

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

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

$err is cleared.

Panic if:

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

WQMD: 256-bit integer fused multiply-divide

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

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

$err is cleared.

Panic if:

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

WDAM: Modular 128-bit integer addition

$of is cleared.

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

Panic if:

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

WQAM: Modular 256-bit integer addition

$of is cleared.

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

Panic if:

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

WDMM: Modular 128-bit integer multiplication

$of is cleared.

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

Panic if:

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

WQMM: Modular 256-bit integer multiplication

$of is cleared.

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

Panic if:

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

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

JNEB: Jump if not equal relative backwards

Panic if:

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

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

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

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

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

Return the unused forwarded gas to the caller:

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

Set the return value:

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

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

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

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
• 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
• 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
• 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
• 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

PSHH: Push a set of high registers to stack

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

Panic if:

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

PSHL: Push a set of low registers to stack