Skip to content

FATE

The fast æternity transaction engine.

Design

The high level machine (or the fast æternity transaction engine) has æternity transactions as its basic operations and it operates directly on the state tree of the æternity chain. This is a new paradigm in blockchain virtual machine specifications which makes it possible to create type safe and efficient implementations of the machine.

Every operation is typed and all values are typed (either by being stored in a typed memory or by a tag). Any type violation results in an exception and reverts all state changes. In version 1.0 there will be no catch instruction.

In addition to normal machine instructions, such as ADD, the machine also has support for constructing most of the transactions available on the æternity chain from native low level chain transaction instructions.

The instruction memory is divided into functions and basic blocks. Only basic blocks can be indexed and used as jump destinations.

There are instructions to operate on the chain state tree in a safe and formalized way.

FATE is "functional" in the sense that "updates" of data structures, such as tuples, lists or maps do not change the old values of the structure. Instead a new version is created, unless specific operations to write to the contract store are used.

FATE does have the ability to write the value of an operation back to the same register or stack position as one of the arguments, in effect updating the memory. Thus, any other references to the structure before the operation will have the same structure as before the operation.

Objectives

Type safety

FATE solves some fundamental problems programmers run into when coding for Ethereum: integer overflow, weak type checking and poor data flow. FATE checks all arithmetic operations to keep the right meaning of it. Also you can't implicitly cast types (eg integers to booleans).

In EVM contracts are not typed. When calling a function, EVM will try to find which function you wanted to use by looking at the data that you send into the code. In FATE, you have actual functions and the functions have types - function call has to match the function type.

FATE ultimately makes a safer coding platform for smart contracts.

Rich data types

FATE has more built in data types: like maps, lists.

Faster transactions, smaller code size

Having a higher level instructions makes the code deployed smaller and it reduces the blockchain size. Smaller code and smaller hashes also keeps a blockchain network from clogging up and results in cheaper transactions.

Components

Machine State

  • Current contract: Address
  • Current owner: Address
  • Caller: Address
  • Code: Code of current contract
  • Memory: Several components as defined below
  • CF, current function: Hash of current function
  • CBB, current basic block: Index of current basic block.
  • EC, Execution continuation: A list of instructions left in the current basic block.

Memory

The machine memory is divided into:

  • The chain top (block height, etc)
  • Event stream
  • The account state tree
  • The contract store
  • The execution/code memory
  • Execution stack (push/pop on call/return)
  • Accumulator stack (push/pop on instruction level)
  • Local storage/stack/environment/context (push/pop on let...in...end)

The execution memory

The code to execute is stored in the execution memory. The execution memory is a three level map. The key on the top level is a contract address. The second level is a map from function hashes to a map of basic blocks. The keys in the map of basic blocks are indices to basic blocks (a 0 based, dense enumeration). The values are lists of instructions.

When a contract is called the code of the contract is read from the state tree into the execution memory. At this point the machine implementation can deserialize the serialized version of FATE code into instructions and basic blocks.

The serialization format for FATE code is described in Appendix 1: Fate instruction set and serialization.

The chain

The chain "memory" contains information about the current block and the current iteration. These values are available through special instructions.

  • Beneficiary
  • Timestamp
  • (Block) Height
  • Difficulty
  • Gaslimit
  • Address
  • Balance
  • Caller
  • Value

The contract store

The permanent storage of a contract. Stored in the chain state tree. This is a key value store that is mapped to the contract state by the compiler.

The compiler can choose how to represent the contract state in the store. For instance, save the entire state under a single key (this is how it works in AEVM at the moment), or it could flatten any state records and store each field under a separate key.

The state tree

Contains all accounts, oracles and contracts on the chain. Most values such as account balances can be read directly through specific load instructions. Some values can be changed through transaction instructions.

The local storage

The local storage is a key value store. The key is a an integer. The value can be of any FATE type. The local store is local to a function call.

The accumulator stack

The accumulator stack is a stack of typed values. The top of the stack can be used as an argument to an operation. Values can be pushed to the stack and popped from the stack.

The execution stack

The execution stack contain return addresses as a tuple in the form of {contract address, function hash, and basic block index}.

The event stream

A contract can emit events similar to the EVM.

Types

The machine supports the following types:

  • Integer (signed arbitrary precision integers)
  • Boolean (true | false)
  • Strings (arbitrary size byte arrays)
  • Bytes (fixed size byte arrays)
  • Bits (An arbitrary size bitmap)
  • Address (A pointer into the state tree)
  • Contract Address (A pointer to a contract)
  • Oracle (A pointer to an oracle)
  • Oracle Query (A pointer to an oracle query)
  • Channel (A pointer to a channel)
  • Tuples (a typed series of values)
  • Lists (a list of values of a specific type)
  • Maps (a key value store)
  • Store Map (a key value store mapped to the contract state)
  • Variant Types (a set of tagged and typed values)
  • Type (a representation of a FATE type)

These types can be used as argument and return types of functions and also as the type of the elements in the contract store.

Integer

The type Integer, is used for any integer, infinitely large or small (below zero).

Examples:

 0
 1
-1
589465789334
-51315353513513131656462262

Boolean

The Boolean type only has two values, true or false.

Examples (all of them): 

 true
 false

Operations on booleans include:

  • and, or, not
  • conditional jumps

Addresses, Contract Addresses, Oracles, Oracle Querries, Channels

Values of any address type are 32-byte (256-bit) pointers to entities on the chain (Accounts, Oracles, Contracts, etc)

Examples: 

<<ak_2HNb8bivUoJTcaxD6VKDy2wPHvTuQgQRJ3dkF9RSyVFqBkMneC>>

Strings

Strings are stored as byte arrays. From VM version FATE_02 they are strictly UTF-8 encoded unicode characters. In particular operations String.to_list and String.from_list ensure that they only contain well formed code points.

Examples: 

"Hello world"
"eof"

Bytes

In VM versions FATE_01 and FATE_02 only fixed (size known at compile time) size byte arrays exist. With the change to Strings, making them UTF-8 encoded byte arrays, there is a need for general arbitrary length byte arrays. These are introduced in FATE_03 - and a couple of new operations handling (and converting) byte arrays are added. Technical note: the bytes type was {bytes, N} / bytes(n) - to change as little as possible arbitrary size byte arrays have the type {bytes, -1} / bytes().

Tuples

Tuples have an arity indicating the number of elements in the tuple. Each element in the tuple has a type. The 0-tuple is also sometimes called unit. The maximum number of elements in the tuple is 255 (included).

Examples: 

 {}                Type: unit
 {1, 2}            Type: Tuple(Integer, Integer)
 {"foo", 42, true} Type: Tuple(String, Integer, Boolean)

Lists

Lists are monomorphic series of values. Hence lists have a type. There is also an empty list (or Nil).

Examples: 

[]                   Type: Nil
[1, 2, 3]            Type: List(Integer)
[true, true, false]  Type: List(Boolean)

Maps

Maps are monomorphic key value stores, that is the key is always the same type for all elements in a map and the value has the same type in all mappings in a map. The key can have any type except a map. The value can have any type including a map.

Examples: 

#{ (1, "foo"), (2, "bar") }
Type: Map(Integer, String)

#{ ("Fruit prices", #{ ("banana", 42), ("apple", 12)}),
   ("Stock prices", #{("Apple", 142), ("Orange", 112)}) }
Type: Map(String, Map(String, Integer))

Variant Types

The variant type is a type consisting of a list of sizes and a tag (index) where each tag represents a series of values of specified types. For example you could have the Option type which could be None or Some(Integer). The sizes of the variant are 0 and 1 (there are two variants), The value None would be indicated by tag 0. The value Some(42) would be represented by tag 1 followed by the integer 42.

Examples: 

  (| [0,1] | 0 | () |)      ;; None
  (| [0,1] | 1 | (42) |)    ;; Some(42)

  (| 4 | 3 | (42, "foo", true) |) ;; Three(42, "foo", true)

Note that the tuple syntax for the elements does not indicate a Fate tuple but a series of values.

TypeRep

A TypeRep is the representation of a type as a value. A TypeRep is one of

  • integer
  • boolean
  • any
  • {list, T}
  • {tuple, Ts}
  • address
  • contract
  • oracle
  • oracle_query
  • channel
  • bits
  • {bytes, N}
  • {map, K, V}
  • string
  • {variant, ListOfVariants}
  • {tvar, N}

where T, K and V are TypeReps, Ts is a list of TypeReps ([T1, T2, ... ]), and ListOfVariants is a list ([]) of tuples of TypeReps ([{tuple, [Ts1]}, {tuple, [Ts2]} ... ]). N is a byte (0...255).

Operations

All operations are typed. An operand can be the accumulator, an immediate, a name, a reference to a field in the state tree, or a reference to the contract state. The operand must be of the right type.

Operands

Operand specifiers are

  • immediate
  • arg
  • var
  • a (accumulator == stack 0)

The specifiers are encoded as

what bits
immediate 11
var 10
arg 01
stack 00

Operand specifiers for operations with 1 to 4 arguments are stored in the byte following the opcode. Operand specifiers for operations with 5 to 8 arguments are stored in the two bytes following the opcode. Note that for many operation the first argument (arg0) is the destination for the operation.

value: arg3 arg3 arg2 arg2 arg1 arg1 arg0 arg0
bit: 7 6 5 4 3 2 1 0
value: arg8 arg7 arg6 arg6 arg5 arg5 arg4 arg4
bit: 7 6 5 4 3 2 1 0

Unused arguments should be set to 0.

E.g. an a := immediate + a would have the bit pattern 00 11 00 00.

Each use of the accumulator pops an argument from the stack. Writing to the accumulator pushes a value to the stack.

Operations

Description of operations

Name Args Description Arg types Res type Added in VM version
RETURN Return from function call, top of stack is return value . The type of the retun value has to match the return type of the function. {} any FATE_01
RETURNR Arg0 Push Arg0 and return from function. The type of the retun value has to match the return type of the function. {any} any FATE_01
CALL Arg0 Call the function Arg0 with args on stack. The types of the arguments has to match the argument typs of the function. {string} any FATE_01
CALL_R Arg0 Identifier Arg2 Arg3 Arg4 Remote call to contract Arg0 and function Arg1 of type Arg2 => Arg3 with value Arg4. The types of the arguments has to match the argument types of the function. {contract,string,typerep,typerep,integer} any FATE_01
CALL_T Arg0 Tail call to function Arg0. The types of the arguments has to match the argument typs of the function. And the return type of the called function has to match the type of the current function. {string} any FATE_01
CALL_GR Arg0 Identifier Arg2 Arg3 Arg4 Arg5 Remote call with gas cap in Arg4. Otherwise as CALL_R. {contract,string,typerep,typerep,integer,integer} any FATE_01
JUMP Integer Jump to a basic block. The basic block has to exist in the current function. {integer} none FATE_01
JUMPIF Arg0 Integer Conditional jump to a basic block. If Arg0 then jump to Arg1. {boolean,integer} none FATE_01
SWITCH_V2 Arg0 Integer Integer Conditional jump to a basic block on variant tag. {variant,integer,ingeger} none FATE_01
SWITCH_V3 Arg0 Integer Integer Integer Conditional jump to a basic block on variant tag. {variant,integer,integer,ingeger} none FATE_01
SWITCH_VN Arg0 [Integers] Conditional jump to a basic block on variant tag. {variant,{list,integer}} none FATE_01
CALL_VALUE Arg0 The value sent in the current remote call. {} integer FATE_01
PUSH Arg0 Push argument to stack. {any} any FATE_01
DUPA Duplicate top of stack. {any} any FATE_01
DUP Arg0 push Arg0 stack pos on top of stack. {any} any FATE_01
POP Arg0 Arg0 := top of stack. {integer} integer FATE_01
INCA Increment accumulator. {integer} integer FATE_01
INC Arg0 Increment argument. {integer} integer FATE_01
DECA Decrement accumulator. {integer} integer FATE_01
DEC Arg0 Decrement argument. {integer} integer FATE_01
ADD Arg0 Arg1 Arg2 Arg0 := Arg1 + Arg2. {integer,integer} integer FATE_01
SUB Arg0 Arg1 Arg2 Arg0 := Arg1 - Arg2. {integer,integer} integer FATE_01
MUL Arg0 Arg1 Arg2 Arg0 := Arg1 * Arg2. {integer,integer} integer FATE_01
DIV Arg0 Arg1 Arg2 Arg0 := Arg1 / Arg2. {integer,integer} integer FATE_01
MOD Arg0 Arg1 Arg2 Arg0 := Arg1 mod Arg2. {integer,integer} integer FATE_01
POW Arg0 Arg1 Arg2 Arg0 := Arg1 ^ Arg2. {integer,integer} integer FATE_01
STORE Arg0 Arg1 Arg0 := Arg1. {any} any FATE_01
SHA3 Arg0 Arg1 Arg0 := sha3(Arg1). {any} hash FATE_01
SHA256 Arg0 Arg1 Arg0 := sha256(Arg1). {any} hash FATE_01
BLAKE2B Arg0 Arg1 Arg0 := blake2b(Arg1). {any} hash FATE_01
LT Arg0 Arg1 Arg2 Arg0 := Arg1 < Arg2. {integer,integer} boolean FATE_01
GT Arg0 Arg1 Arg2 Arg0 := Arg1 > Arg2. {integer,integer} boolean FATE_01
EQ Arg0 Arg1 Arg2 Arg0 := Arg1 = Arg2. {integer,integer} boolean FATE_01
ELT Arg0 Arg1 Arg2 Arg0 := Arg1 =< Arg2. {integer,integer} boolean FATE_01
EGT Arg0 Arg1 Arg2 Arg0 := Arg1 >= Arg2. {integer,integer} boolean FATE_01
NEQ Arg0 Arg1 Arg2 Arg0 := Arg1 /= Arg2. {integer,integer} boolean FATE_01
AND Arg0 Arg1 Arg2 Arg0 := Arg1 and Arg2. {boolean,boolean} boolean FATE_01
OR Arg0 Arg1 Arg2 Arg0 := Arg1 or Arg2. {boolean,boolean} boolean FATE_01
NOT Arg0 Arg1 Arg0 := not Arg1. {boolean} boolean FATE_01
TUPLE Arg0 Integer Arg0 := tuple of size = Arg1. Elements on stack. {integer} tuple FATE_01
ELEMENT Arg0 Arg1 Arg2 Arg1 := element(Arg2, Arg3). {integer,tuple} any FATE_01
SETELEMENT Arg0 Arg1 Arg2 Arg3 Arg0 := a new tuple similar to Arg2, but with element number Arg1 replaced by Arg3. {integer,tuple,any} tuple FATE_01
MAP_EMPTY Arg0 Arg0 := #{}. {} map FATE_01
MAP_LOOKUP Arg0 Arg1 Arg2 Arg0 := lookup key Arg2 in map Arg1. {map,any} any FATE_01
MAP_LOOKUPD Arg0 Arg1 Arg2 Arg3 Arg0 := lookup key Arg2 in map Arg1 if key exists in map otherwise Arg0 := Arg3. {map,any,any} any FATE_01
MAP_UPDATE Arg0 Arg1 Arg2 Arg3 Arg0 := update key Arg2 in map Arg1 with value Arg3. {map,any,any} map FATE_01
MAP_DELETE Arg0 Arg1 Arg2 Arg0 := delete key Arg2 from map Arg1. {map,any} map FATE_01
MAP_MEMBER Arg0 Arg1 Arg2 Arg0 := true if key Arg2 is in map Arg1. {map,any} boolean FATE_01
MAP_FROM_LIST Arg0 Arg1 Arg0 := make a map from (key, value) list in Arg1. {{list,{tuple,[any,any]}}} map FATE_01
MAP_SIZE Arg0 Arg1 Arg0 := The size of the map Arg1. {map} integer FATE_01
MAP_TO_LIST Arg0 Arg1 Arg0 := The tuple list representation of the map Arg1. {map} list FATE_01
IS_NIL Arg0 Arg1 Arg0 := true if Arg1 == []. {list} boolean FATE_01
CONS Arg0 Arg1 Arg2 Arg0 := [Arg1] ++ Arg2. {any,list} list FATE_01
HD Arg0 Arg1 Arg0 := head of list Arg1. {list} any FATE_01
TL Arg0 Arg1 Arg0 := tail of list Arg1. {list} list FATE_01
LENGTH Arg0 Arg1 Arg0 := length of list Arg1. {list} integer FATE_01
NIL Arg0 Arg0 := []. {} list FATE_01
APPEND Arg0 Arg1 Arg2 Arg0 := Arg1 ++ Arg2. {list,list} list FATE_01
STR_JOIN Arg0 Arg1 Arg2 Arg0 := string Arg1 followed by string Arg2. {string,string} string FATE_01
INT_TO_STR Arg0 Arg1 Arg0 := turn integer Arg1 into a string. {integer} string FATE_01
ADDR_TO_STR Arg0 Arg1 Arg0 := turn address Arg1 into a string. {address} string FATE_01
STR_REVERSE Arg0 Arg1 Arg0 := the reverse of string Arg1. {string} string FATE_01
STR_LENGTH Arg0 Arg1 Arg0 := The length of the string Arg1. {string} integer FATE_01
BYTES_TO_INT Arg0 Arg1 Arg0 := bytes_to_int(Arg1) {bytes} integer FATE_01
BYTES_TO_STR Arg0 Arg1 Arg0 := bytes_to_str(Arg1) {bytes} string FATE_01
BYTES_CONCAT Arg0 Arg1 Arg2 Arg0 := bytes_concat(Arg1, Arg2) {bytes,bytes} bytes FATE_01
BYTES_SPLIT Arg0 Arg1 Arg2 Arg0 := bytes_split(Arg2, Arg1), where Arg2 is the length of the first chunk. {bytes,integer} bytes FATE_01
INT_TO_ADDR Arg0 Arg1 Arg0 := turn integer Arg1 into an address. {integer} address FATE_01
VARIANT Arg0 Arg1 Arg2 Arg3 Arg0 := create a variant of size Arg1 with the tag Arg2 (Arg2 < Arg1) and take Arg3 elements from the stack. {integer,integer,integer} variant FATE_01
VARIANT_TEST Arg0 Arg1 Arg2 Arg0 := true if variant Arg1 has the tag Arg2. {variant,integer} boolean FATE_01
VARIANT_ELEMENT Arg0 Arg1 Arg2 Arg0 := element number Arg2 from variant Arg1. {variant,integer} any FATE_01
BITS_NONEA push an empty bitmap on the stack. {} bits FATE_01
BITS_NONE Arg0 Arg0 := empty bitmap. {} bits FATE_01
BITS_ALLA push a full bitmap on the stack. {} bits FATE_01
BITS_ALL Arg0 Arg0 := full bitmap. {} bits FATE_01
BITS_ALL_N Arg0 Arg1 Arg0 := bitmap with Arg1 bits set. {integer} bits FATE_01
BITS_SET Arg0 Arg1 Arg2 Arg0 := set bit Arg2 of bitmap Arg1. {bits,integer} bits FATE_01
BITS_CLEAR Arg0 Arg1 Arg2 Arg0 := clear bit Arg2 of bitmap Arg1. {bits,integer} bits FATE_01
BITS_TEST Arg0 Arg1 Arg2 Arg0 := true if bit Arg2 of bitmap Arg1 is set. {bits,integer} boolean FATE_01
BITS_SUM Arg0 Arg1 Arg0 := sum of set bits in bitmap Arg1. Exception if infinit bitmap. {bits} integer FATE_01
BITS_OR Arg0 Arg1 Arg2 Arg0 := Arg1 v Arg2. {bits,bits} bits FATE_01
BITS_AND Arg0 Arg1 Arg2 Arg0 := Arg1 ^ Arg2. {bits,bits} bits FATE_01
BITS_DIFF Arg0 Arg1 Arg2 Arg0 := Arg1 - Arg2. {bits,bits} bits FATE_01
BALANCE Arg0 Arg0 := The current contract balance. {} integer FATE_01
ORIGIN Arg0 Arg0 := Address of contract called by the call transaction. {} address FATE_01
CALLER Arg0 Arg0 := The address that signed the call transaction. {} address FATE_01
BLOCKHASH Arg0 Arg1 Arg0 := The blockhash at height. {integer} variant FATE_01
BENEFICIARY Arg0 Arg0 := The address of the current beneficiary. {} address FATE_01
TIMESTAMP Arg0 Arg0 := The current timestamp. Unreliable, don't use for anything. {} integer FATE_01
GENERATION Arg0 Arg0 := The block height of the current generation. {} integer FATE_01
MICROBLOCK Arg0 Arg0 := The current micro block number. {} integer FATE_01
DIFFICULTY Arg0 Arg0 := The current difficulty. {} integer FATE_01
GASLIMIT Arg0 Arg0 := The current gaslimit. {} integer FATE_01
GAS Arg0 Arg0 := The amount of gas left. {} integer FATE_01
ADDRESS Arg0 Arg0 := The current contract address. {} address FATE_01
GASPRICE Arg0 Arg0 := The current gas price. {} integer FATE_01
LOG0 Arg0 Create a log message in the call object. {string} none FATE_01
LOG1 Arg0 Arg1 Create a log message with one topic in the call object. {integer,string} none FATE_01
LOG2 Arg0 Arg1 Arg2 Create a log message with two topics in the call object. {integer,integer,string} none FATE_01
LOG3 Arg0 Arg1 Arg2 Arg3 Create a log message with three topics in the call object. {integer,integer,integer,string} none FATE_01
LOG4 Arg0 Arg1 Arg2 Arg3 Arg4 Create a log message with four topics in the call object. {integer,integer,integer,integer,string} none FATE_01
SPEND Arg0 Arg1 Transfer Arg1 coins to account Arg0. (If the contract account has at least that many coins. {address,integer} none FATE_01
ORACLE_REGISTER Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 Arg6 Arg0 := New oracle with address Arg2, query fee Arg3, TTL Arg4, query type Arg5 and response type Arg6. Arg0 contains delegation signature. {signature,address,integer,variant,typerep,typerep} oracle FATE_01
ORACLE_QUERY Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 Arg6 Arg7 Arg0 := New oracle query for oracle Arg1, question in Arg2, query fee in Arg3, query TTL in Arg4, response TTL in Arg5. Typereps for checking oracle type is in Arg6 and Arg7. {oracle,any,integer,variant,variant,typerep,typerep} oracle_query FATE_01
ORACLE_RESPOND Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 Respond as oracle Arg1 to query in Arg2 with response Arg3. Arg0 contains delegation signature. Typereps for checking oracle type is in Arg4 and Arg5. {signature,oracle,oracle_query,any,typerep,typerep} none FATE_01
ORACLE_EXTEND Arg0 Arg1 Arg2 Extend oracle in Arg1 with TTL in Arg2. Arg0 contains delegation signature. {signature,oracle,variant} none FATE_01
ORACLE_GET_ANSWER Arg0 Arg1 Arg2 Arg3 Arg4 Arg0 := option variant with answer (if any) from oracle query in Arg1 given by oracle Arg0. Typereps for checking oracle type is in Arg3 and Arg4. {oracle,oracle_query,typerep,typerep} any FATE_01
ORACLE_GET_QUESTION Arg0 Arg1 Arg2 Arg3 Arg4 Arg0 := question in oracle query Arg2 given to oracle Arg1. Typereps for checking oracle type is in Arg3 and Arg4. {oracle,oracle_query,typerep,typerep} any FATE_01
ORACLE_QUERY_FEE Arg0 Arg1 Arg0 := query fee for oracle Arg1 {oracle} integer FATE_01
AENS_RESOLVE Arg0 Arg1 Arg2 Arg3 Resolve name in Arg0 with tag Arg1. Arg2 describes the type parameter of the resolved name. {string,string,typerep} variant FATE_01
AENS_PRECLAIM Arg0 Arg1 Arg2 Preclaim the hash in Arg2 for address in Arg1. Arg0 contains delegation signature. {signature,address,hash} none FATE_01
AENS_CLAIM Arg0 Arg1 Arg2 Arg3 Arg4 Attempt to claim the name in Arg2 for address in Arg1 at a price in Arg4. Arg3 contains the salt used to hash the preclaim. Arg0 contains delegation signature. {signature,address,string,integer,integer} none FATE_01
AENS_UPDATE Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 Updates name in Arg2 for address in Arg1. Arg3 contains optional ttl (of type Chain.ttl), Arg4 contains optional client_ttl (of type int), Arg5 contains optional pointers (of type map(string, pointee)). Arg0 contains delegation signature. {signature,address,string,variant,variant,variant} none FATE_01
AENS_TRANSFER Arg0 Arg1 Arg2 Arg3 Transfer ownership of name Arg3 from account Arg1 to Arg2. Arg0 contains delegation signature. {signature,address,address,string} none FATE_01
AENS_REVOKE Arg0 Arg1 Arg2 Revoke the name in Arg2 from owner Arg1. Arg0 contains delegation signature. {signature,address,string} none FATE_01
BALANCE_OTHER Arg0 Arg1 Arg0 := The balance of address Arg1. {address} integer FATE_01
VERIFY_SIG Arg0 Arg1 Arg2 Arg3 Arg0 := verify_sig(Hash, PubKey, Signature) {bytes,address,bytes} boolean FATE_01
VERIFY_SIG_SECP256K1 Arg0 Arg1 Arg2 Arg3 Arg0 := verify_sig_secp256k1(Hash, PubKey, Signature) {bytes,bytes,bytes} boolean FATE_01
CONTRACT_TO_ADDRESS Arg0 Arg1 Arg0 := Arg1 - A no-op type conversion {contract} address FATE_01
AUTH_TX_HASH Arg0 If in GA authentication context return Some(TxHash) otherwise None. {} variant FATE_01
ORACLE_CHECK Arg0 Arg1 Arg2 Arg3 Arg0 := is Arg1 an oracle with the given query (Arg2) and response (Arg3) types {oracle,typerep,typerep} bool FATE_01
ORACLE_CHECK_QUERY Arg0 Arg1 Arg2 Arg3 Arg4 Arg0 := is Arg2 a query for the oracle Arg1 with the given types (Arg3, Arg4) {oracle,oracle_query,typerep,typerep} bool FATE_01
IS_ORACLE Arg0 Arg1 Arg0 := is Arg1 an oracle {address} bool FATE_01
IS_CONTRACT Arg0 Arg1 Arg0 := is Arg1 a contract {address} bool FATE_01
IS_PAYABLE Arg0 Arg1 Arg0 := is Arg1 a payable address {address} bool FATE_01
CREATOR Arg0 Arg0 := contract creator {} address FATE_01
ECVERIFY_SECP256K1 Arg0 Arg1 Arg2 Arg3 Arg0 := ecverify_secp256k1(Hash, Addr, Signature) {bytes,bytes,bytes} bytes FATE_01
ECRECOVER_SECP256K1 Arg0 Arg1 Arg2 Arg0 := ecrecover_secp256k1(Hash, Signature) {bytes,bytes} bytes FATE_01
ADDRESS_TO_CONTRACT Arg0 Arg1 Arg0 := Arg1 - A no-op type conversion {address} contract FATE_01
BLS12_381_G1_NEG Arg0 Arg1 Arg0 := BLS12_381.g1_neg(Arg1) - Negate a G1-value {tuple} tuple FATE_02
BLS12_381_G1_NORM Arg0 Arg1 Arg0 := BLS12_381.g1_normalize(Arg1) - Normalize a G1-value {tuple} tuple FATE_02
BLS12_381_G1_VALID Arg0 Arg1 Arg0 := BLS12_381.g1_valid(Arg1) - Check if G1-value is a valid group member {tuple} bool FATE_02
BLS12_381_G1_IS_ZERO Arg0 Arg1 Arg0 := BLS12_381.g1_is_zero(Arg1) - Check if G1-value is zero {tuple} bool FATE_02
BLS12_381_G1_ADD Arg0 Arg1 Arg2 Arg0 := BLS12_381.g1_add(Arg1, Arg2) - Add two G1-values {tuple,tuple} tuple FATE_02
BLS12_381_G1_MUL Arg0 Arg1 Arg2 Arg0 := BLS12_381.g1_mul(Arg1, Arg2) - Scalar multiplication for a G1-value (Arg1), and an Fr-value {tuple,tuple} tuple FATE_02
BLS12_381_G2_NEG Arg0 Arg1 Arg0 := BLS12_381.g2_neg(Arg1) - Negate a G2-value {tuple} tuple FATE_02
BLS12_381_G2_NORM Arg0 Arg1 Arg0 := BLS12_381.g2_normalize(Arg1) - Normalize a G2-value {tuple} tuple FATE_02
BLS12_381_G2_VALID Arg0 Arg1 Arg0 := BLS12_381.g2_valid(Arg1) - Check if G2-value is a valid group member {tuple} bool FATE_02
BLS12_381_G2_IS_ZERO Arg0 Arg1 Arg0 := BLS12_381.g2_is_zero(Arg1) - Check if G2-value is zero {tuple} bool FATE_02
BLS12_381_G2_ADD Arg0 Arg1 Arg2 Arg0 := BLS12_381.g2_add(Arg1, Arg2) - Add two G2-values {tuple,tuple} tuple FATE_02
BLS12_381_G2_MUL Arg0 Arg1 Arg2 Arg0 := BLS12_381.g2_mul(Arg1, Arg2) - Scalar multiplication for a G2-value (Arg2), and an Fr-value {tuple,tuple} tuple FATE_02
BLS12_381_GT_INV Arg0 Arg1 Arg0 := BLS12_381.gt_inv(Arg1) - Invert a GT-value {tuple} tuple FATE_02
BLS12_381_GT_ADD Arg0 Arg1 Arg2 Arg0 := BLS12_381.gt_add(Arg1, Arg2) - Add two GT-values {tuple,tuple} tuple FATE_02
BLS12_381_GT_MUL Arg0 Arg1 Arg2 Arg0 := BLS12_381.gt_mul(Arg1, Arg2) - Multiply two GT-values {tuple,tuple} tuple FATE_02
BLS12_381_GT_POW Arg0 Arg1 Arg2 Arg0 := BLS12_381.gt_pow(Arg1, Arg2) - Scalar exponentiation for a GT-value (Arg2), and an Fr-value {tuple,tuple} tuple FATE_02
BLS12_381_GT_IS_ONE Arg0 Arg1 Arg0 := BLS12_381.gt_is_one(Arg1) - Check if a GT value is "one" {tuple} bool FATE_02
BLS12_381_PAIRING Arg0 Arg1 Arg2 Arg0 := BLS12_381.pairing(Arg1, Arg2) - Find the pairing of a G1-value (Arg1) and a G2-value (Arg2) {tuple,tuple} tuple FATE_02
BLS12_381_MILLER_LOOP Arg0 Arg1 Arg2 Arg0 := BLS12_381.miller_loop(Arg1, Arg2) - Do the Miller-loop step of pairing for a G1-value (Arg1) and a G2-value (Arg2) {tuple,tuple} tuple FATE_02
BLS12_381_FINAL_EXP Arg0 Arg1 Arg0 := BLS12_381.final_exp(Arg1) - Do the final exponentiation in pairing {tuple} tuple FATE_02
BLS12_381_INT_TO_FR Arg0 Arg1 Arg0 := to_montgomery(Arg1) - Convert (Big)integer to Montgomery representation (32 bytes) {tuple} tuple FATE_02
BLS12_381_INT_TO_FP Arg0 Arg1 Arg0 := to_montgomery(Arg1) - Convert (Big)integer to Montgomery representation (48 bytes) {tuple} tuple FATE_02
BLS12_381_FR_TO_INT Arg0 Arg1 Arg0 := from_montgomery(Arg1) - Convert Montgomery representation (32 bytes) to integer {tuple} tuple FATE_02
BLS12_381_FP_TO_INT Arg0 Arg1 Arg0 := from_montgomery(Arg1) - Convert Montgomery representation (48 bytes) to integer {tuple} tuple FATE_02
AENS_LOOKUP Arg0 Arg1 Lookup the name of Arg0. Returns option(AENS.name) {string} variant FATE_02
ORACLE_EXPIRY Arg0 Arg1 Arg0 := expiry block for oracle Arg1 {oracle} int FATE_02
AUTH_TX Arg0 If in GA authentication context return Some(Tx) otherwise None. {} variant FATE_02
STR_TO_LIST Arg0 Arg1 Arg0 := string converted to list of characters {string} list FATE_02
STR_FROM_LIST Arg0 Arg1 Arg0 := string converted from list of characters {list} string FATE_02
STR_TO_UPPER Arg0 Arg1 Arg0 := to_upper(string) {string} string FATE_02
STR_TO_LOWER Arg0 Arg1 Arg0 := to_lower(string) {string} string FATE_02
CHAR_TO_INT Arg0 Arg1 Arg0 := integer representation of UTF-8 character {char} int FATE_02
CHAR_FROM_INT Arg0 Arg1 Arg0 := Some(UTF-8 character) from integer if valid, None if not valid. {int} variant FATE_02
CALL_PGR Arg0 Identifier Arg2 Arg3 Arg4 Arg5 Arg6 Potentially protected remote call. Arg5 is protected flag, otherwise as CALL_GR. {contract,string,typerep,typerep,integer,integer,bool} variant FATE_02
CREATE Arg0 Arg1 Arg2 Deploys a contract with a bytecode Arg1 and value Arg3. The init arguments should be placed on the stack and match the type in Arg2. Writes contract address to the top of the accumulator stack. If an account on the resulting address did exist before the call, the payable flag will be updated. {contract_bytearray,typerep,integer} contract FATE_02
CLONE Arg0 Arg1 Arg2 Arg3 Clones the contract under Arg1 and deploys it with value of Arg3. The init arguments should be placed on the stack and match the type in Arg2. Writes contract (or None on fail when protected) to the top of the accumulator stack. Does not copy the existing contract's store – it will be initialized by a fresh call to the init function. If an account on the resulting address did exist before the call, the payable flag will be updated. {contract,typerep,integer,bool} any FATE_02
CLONE_G Arg0 Arg1 Arg2 Arg3 Arg4 Like CLONE but additionally limits the gas of the init call by Arg3 {contract,typerep,integer,integer,bool} any FATE_02
BYTECODE_HASH Arg0 Arg1 Arg0 := hash of the deserialized contract's bytecode under address given in Arg1 (or None on fail). Fails on AEVM contracts and contracts deployed before Iris. {contract} variant FATE_02
FEE Arg0 Arg0 := The fee for the current call tx. {} integer FATE_02
ADDRESS_TO_BYTES Arg0 Arg1 Arg0 := the fixed size byte representation of the address Arg1 {address} bytes FATE_03
POSEIDON Arg0 Arg1 Arg2 Arg0 := the Poseidon hash of Arg1 and Arg2 - all integers in the BLS12-381 scalar field {integer, integer} integer FATE_03
MULMOD Arg0 Arg1 Arg2 Arg3 Arg0 := (Arg1 * Arg2) mod Arg3 {integer, integer, integer} integer FATE_03
BAND Arg0 Arg1 Arg2 Arg0 := Arg1 & Arg2 {integer, integer} integer FATE_03
BOR Arg0 Arg1 Arg2 Arg0 := Arg1 Arg2 {integer, integer} integer
BXOR Arg0 Arg1 Arg2 Arg0 := Arg1 ^ Arg2 {integer, integer} integer FATE_03
BNOT Arg0 Arg1 Arg0 := ~Arg1 {integer} integer FATE_03
BSL Arg0 Arg1 Arg2 Arg0 := Arg1 << Arg2 {integer, integer} integer FATE_03
BSR Arg0 Arg1 Arg2 Arg0 := Arg1 >> Arg2 {integer, integer} integer FATE_03
BYTES_SPLIT_ANY Arg0 Arg1 Arg2 Arg0 := bytes_split_any(Arg1, Arg2), where a positive Arg2 is the length of the first chunk, and a negative Arg2 is the length of the second chunk. Returns None if byte array is not long enough. {bytes, integer} variant FATE_03
BYTES_SIZE Arg0 Arg1 Arg0 := bytes_size(Arg1), returns the number of bytes in the byte array. {bytes} integer FATE_03
BYTES_TO_FIXED_SIZE Arg0 Arg1 Arg2 Arg0 := bytes_to_fixe_size(Arg1, Arg2), returns Some(Arg1') if byte_size(Arg1) == Arg2, None otherwise. The type of Arg1' is bytes(Arg2) but the value is unchanged {bytes, integer} variant FATE_03
INT_TO_BYTES Arg0 Arg1 Arg2 Arg0 := turn integer Arg1 into a byte array (big endian) length Arg2 (truncating if not fit). {integer, integer} bytes FATE_03
STR_TO_BYTES Arg0 Arg1 Arg0 := turn string Arg1 into the corresponding byte array. {string} bytes FATE_03
DEACTIVATE Mark the current contract for deactivation. {} none FATE_01
ABORT Arg0 Abort execution (dont use all gas) with error message in Arg0. {string} none FATE_01
EXIT Arg0 Abort execution (use upp all gas) with error message in Arg0. {string} none FATE_01
NOP The no op. does nothing. {} none FATE_01

Opcodes, Flags and Gas

Opcode Name Ends basic block Allowed in auth Allowed offchain Gas cost
0x0 RETURN true true true 10
0x1 RETURNR true true true 10
0x2 CALL true true true 10
0x3 CALL_R true false true 100
0x4 CALL_T true true true 10
0x5 CALL_GR true false true 100
0x6 JUMP true true true 10
0x7 JUMPIF true true true 10
0x8 SWITCH_V2 true true true 10
0x9 SWITCH_V3 true true true 10
0xa SWITCH_VN true true true 10
0xb CALL_VALUE false true true 10
0xc PUSH false true true 10
0xd DUPA false true true 10
0xe DUP false true true 10
0xf POP false true true 10
0x10 INCA false true true 10
0x11 INC false true true 10
0x12 DECA false true true 10
0x13 DEC false true true 10
0x14 ADD false true true 10
0x15 SUB false true true 10
0x16 MUL false true true 10
0x17 DIV false true true 10
0x18 MOD false true true 10
0x19 POW false true true 10
0x1a STORE false true true 10
0x1b SHA3 false true true 100
0x1c SHA256 false true true 100
0x1d BLAKE2B false true true 100
0x1e LT false true true 10
0x1f GT false true true 10
0x20 EQ false true true 10
0x21 ELT false true true 10
0x22 EGT false true true 10
0x23 NEQ false true true 10
0x24 AND false true true 10
0x25 OR false true true 10
0x26 NOT false true true 10
0x27 TUPLE false true true 10
0x28 ELEMENT false true true 10
0x29 SETELEMENT false true true 10
0x2a MAP_EMPTY false true true 10
0x2b MAP_LOOKUP false true true 10
0x2c MAP_LOOKUPD false true true 10
0x2d MAP_UPDATE false true true 10
0x2e MAP_DELETE false true true 10
0x2f MAP_MEMBER false true true 10
0x30 MAP_FROM_LIST false true true 10
0x31 MAP_SIZE false true true 10
0x32 MAP_TO_LIST false true true 10
0x33 IS_NIL false true true 10
0x34 CONS false true true 10
0x35 HD false true true 10
0x36 TL false true true 10
0x37 LENGTH false true true 10
0x38 NIL false true true 10
0x39 APPEND false true true 10
0x3a STR_JOIN false true true 10
0x3b INT_TO_STR false true true 100
0x3c ADDR_TO_STR false true true 100
0x3d STR_REVERSE false true true 100
0x3e STR_LENGTH false true true 10
0x3f BYTES_TO_INT false true true 10
0x40 BYTES_TO_STR false true true 100
0x41 BYTES_CONCAT false true true 10
0x42 BYTES_SPLIT false true true 10
0x43 INT_TO_ADDR false true true 10
0x44 VARIANT false true true 10
0x45 VARIANT_TEST false true true 10
0x46 VARIANT_ELEMENT false true true 10
0x47 BITS_NONEA false true true 10
0x48 BITS_NONE false true true 10
0x49 BITS_ALLA false true true 10
0x4a BITS_ALL false true true 10
0x4b BITS_ALL_N false true true 10
0x4c BITS_SET false true true 10
0x4d BITS_CLEAR false true true 10
0x4e BITS_TEST false true true 10
0x4f BITS_SUM false true true 10
0x50 BITS_OR false true true 10
0x51 BITS_AND false true true 10
0x52 BITS_DIFF false true true 10
0x53 BALANCE false true true 10
0x54 ORIGIN false true true 10
0x55 CALLER false true true 10
0x56 BLOCKHASH false true true 1000 (iris), 10 (lima)
0x57 BENEFICIARY false true true 10
0x58 TIMESTAMP false true true 10
0x59 GENERATION false true true 10
0x5a MICROBLOCK false true true 10
0x5b DIFFICULTY false true true 10
0x5c GASLIMIT false true true 10
0x5d GAS false true true 10
0x5e ADDRESS false true true 10
0x5f GASPRICE false true true 10
0x60 LOG0 false true true 1000
0x61 LOG1 false true true 1100
0x62 LOG2 false true true 1200
0x63 LOG3 false true true 1300
0x64 LOG4 false true true 1400
0x65 SPEND false false true 5000 (iris), 100 (lima)
0x66 ORACLE_REGISTER false false false 10000 (iris), 100 (lima)
0x67 ORACLE_QUERY false false false 10000 (iris), 100 (lima)
0x68 ORACLE_RESPOND false false false 10000 (iris), 100 (lima)
0x69 ORACLE_EXTEND false false false 10000 (iris), 100 (lima)
0x6a ORACLE_GET_ANSWER false false true 2000 (iris), 100 (lima)
0x6b ORACLE_GET_QUESTION false false true 2000 (iris), 100 (lima)
0x6c ORACLE_QUERY_FEE false false true 2000 (iris), 100 (lima)
0x6d AENS_RESOLVE false false true 2000 (iris), 100 (lima)
0x6e AENS_PRECLAIM false false false 10000 (iris), 100 (lima)
0x6f AENS_CLAIM false false false 10000 (iris), 100 (lima)
0x70 AENS_UPDATE false false false 10000 (iris), 100 (lima)
0x71 AENS_TRANSFER false false false 10000 (iris), 100 (lima)
0x72 AENS_REVOKE false false false 10000 (iris), 100 (lima)
0x73 BALANCE_OTHER false true true 2000 (iris), 50 (lima)
0x74 VERIFY_SIG false true true 1300
0x75 VERIFY_SIG_SECP256K1 false true true 1300
0x76 CONTRACT_TO_ADDRESS false true true 10
0x77 AUTH_TX_HASH false true true 10
0x78 ORACLE_CHECK false false true 100
0x79 ORACLE_CHECK_QUERY false false true 100
0x7a IS_ORACLE false false true 100
0x7b IS_CONTRACT false false true 100
0x7c IS_PAYABLE false false true 100
0x7d CREATOR false true true 10
0x7e ECVERIFY_SECP256K1 false true true 1300
0x7f ECRECOVER_SECP256K1 false true true 1300
0x80 ADDRESS_TO_CONTRACT false true true 10
0x81 BLS12_381_G1_NEG false true true 100
0x82 BLS12_381_G1_NORM false true true 100
0x83 BLS12_381_G1_VALID false true true 2000
0x84 BLS12_381_G1_IS_ZERO false true true 30
0x85 BLS12_381_G1_ADD false true true 100
0x86 BLS12_381_G1_MUL false true true 1000
0x87 BLS12_381_G2_NEG false true true 100
0x88 BLS12_381_G2_NORM false true true 100
0x89 BLS12_381_G2_VALID false true true 2000
0x8a BLS12_381_G2_IS_ZERO false true true 30
0x8b BLS12_381_G2_ADD false true true 100
0x8c BLS12_381_G2_MUL false true true 1000
0x8d BLS12_381_GT_INV false true true 100
0x8e BLS12_381_GT_ADD false true true 100
0x8f BLS12_381_GT_MUL false true true 100
0x90 BLS12_381_GT_POW false true true 2000
0x91 BLS12_381_GT_IS_ONE false true true 30
0x92 BLS12_381_PAIRING false true true 12000
0x93 BLS12_381_MILLER_LOOP false true true 5000
0x94 BLS12_381_FINAL_EXP false true true 7000
0x95 BLS12_381_INT_TO_FR false true true 30
0x96 BLS12_381_INT_TO_FP false true true 30
0x97 BLS12_381_FR_TO_INT false true true 30
0x98 BLS12_381_FP_TO_INT false true true 30
0x99 AENS_LOOKUP false false true 2000
0x9a ORACLE_EXPIRY false false true 2000
0x9b AUTH_TX false true true 100
0x9c STR_TO_LIST false true true 100
0x9d STR_FROM_LIST false true true 100
0x9e STR_TO_UPPER false true true 100
0x9f STR_TO_LOWER false true true 100
0xa0 CHAR_TO_INT false true true 10
0xa1 CHAR_FROM_INT false true true 10
0xa2 CALL_PGR true false true 100
0xa3 CREATE true false true 10000
0xa4 CLONE true false true 5000
0xa5 CLONE_G true false true 5000
0xa6 BYTECODE_HASH false true true 100
0xa7 FEE false true true 10
0xa8 ADDRESS_TO_BYTES false true true 10
0xa9 POSEIDON false true true 6000
0xaa MULMOD false true true 10
0xab BAND false true true 10
0xac BOR false true true 10
0xad BXOR false true true 10
0xae BNOT false true true 10
0xaf BSL false true true 10
0xb0 BSR false true true 10
0xb1 BYTES_SPLIT_ANY false true true 10
0xb2 BYTES_SIZE false true true 10
0xb3 BYTES_TO_FIXED_SIZE false true true 10
0xb4 INT_TO_BYTES false true true 10
0xb5 STR_TO_BYTES false true true 10
0xfa DEACTIVATE false true true 10
0xfb ABORT true true true 10
0xfc EXIT true true true 10
0xfd NOP false true true 1

Gas

Each instruction uses the base gas as described in the table above. In addition to the instruction base cost (some) instructions also cost gas in relation to the memory they use. The base cost for memory is one gas per "cell" used. A cell is the memory word of an underlying machine which is defined to be a 64-bit word.

Each use of a a cell is counted and for each 1024 cells used the price is increased by 1. If a contract uses 1024 cells it will cost 1024 gas, if it uses 1025 cells it will cost 1026 gas. Using 2049 cells costs 3072 gas and so on.

When calculating the cell cost the total number of cells used after the instruction is used to determine the price for all new cells used by the instruction. So if you have used 1020 cells and then one instruction uses 5 new cells, then the gas cost for that instruction is 10 and not 6.

Each use of a stack slot (a push) costs gas in the same way and is also counted towards the number of used cells. Each pop of a stack slot does not cost gas and does not decrease the gas cost either but it reduced the count of number of cells in use.

The instructions uses cells in the following way.

ADD, SUB, MUL, DIV, MOD

After the operation is done the size of the absolute value of the result is calculated, and one cell is used per 64 bits that has a 1 set. Integers -18446744073709551615 to 18446744073709551615 uses 1 cell, and integers -340282366920938463463374607431768211456 to -18446744073709551616 and 18446744073709551616 to 340282366920938463463374607431768211456 uses 2 cells, and so on.

POW

The result of the pow instruction is computed recursively and for each step in the recursion the words used are calculated and the operation is aborted if all gas is used up. Given the function words which calculates the number of cells in an integer as described above (1 per 64 bits used). The number of cells are calculated as follows.

pow(a, b)    := pow(a, b, 1)

pow(a, b, r) := r  when b = 0
pow(a, b, r) := cells += words(a) * 2, pow(a*a, b/2, r) when b rem 2 = 0
pow(a, b, r) := cells += words(r) + words(a) * 3, pow(a*a, b/2, r*a)

TUPLE

For creating a tuple you have already payed gas for the elements when you pushed them on the stack with other operations, then the new tuple increase the cell count by the size of the tuple plus 2.

Note that creating the tuple pops the elements from the stack so the cell count only increases by 2 by the make_tuple instruction, but the gas cost is the cost for size+2 cells.

Note also that when calculating cell cost the total number of cells used after the instruction is used to determine the price for all new cells used by the instruction.

SETELEMENT

The number of cells used is the tuple size + 2.

MAP_EMPTY

The cell cost is 2.

MAP_UPDATE

The cell cost is 2.

MAP_FROM_LIST

The cell cost is 2 + length of the list.

MAP_TO_LIST

The cell cost is 2 * length of the list.

CONS

The cell cost is 2.

APPEND

The cell cost is 2 * length of the first list.

STR_JOIN

The cell cost is 1 cell per 8 bytes in the joined string + 1 cell.

INT_TO_STR

The cell cost is 1 cell per 8 bytes in the produced string + 1 cell.

ADDR_TO_STR

The cell cost is 1 cell per 8 bytes in the produced string + 1 cell.

STR_REVERSE

The cell cost is 1 cell per 8 bytes in the produced string + 1 cell.

INT_TO_ADDR

The cell cost is 1 cell per 8 bytes in the produced address + 1 cell.

BITS_NONE, BITS_NONEA, BITS_ALL, BITS_ALLA

The cell cost is 1 cell.

BITS_ALL_N

The cell cost is 1 for every 64 bits used.

BITS_SET, BITS_CLEAR

The cell cost is 1 for every 64 bits used by the resulting bit field.

BYTES_CONCAT

The cell cost is 1 cell per 8 bytes in the produced byte array.

BYTES_TO_STR

The cell cost is 1 cell per 8 bytes in resulting string + 1 cell.

BYTES_SPLIT

The number of cells used is the tuple size which is 2 + 2.

AUTH_TX_HASH

If in auth context the number of cells used is 2 + 2, otherwise the number of cells used is 1 + 2.

VARIANT

The cell cost is two times the length of the list of arities plus one for each element in the variant plus four.

Appendix 1: FATE serialization

A more formal description of the serialization can be found in the general serialization document. Here we will try to describe the serialization more with words.

FATE code is serialized in three chunks:

  1. Code: The code itself.
  2. Symbols: An optional symbol table.
  3. Annotations: Optional additional information.

Each chunk is an RLP encoding of a byte array that is the serialization of the chunk. They all have to be there in the serialization but they can be empty. An empty code chunk is just the RPL encoding of the empty byte array, i.e the byte 128. Symbols and Annotations can be empty but they have to be there as the RLP encoding of the RLP encoding of the empty map i.e. the bytes 130, 47, 0.

An empty FATE contract is encoded as the byte sequence 128, 130, 47, 0, 130, 47, 0.

Appendix 2: Delegation signatures

A couple of FATE operations can perform actions on behalf of a "user", these operations are: AENS_PRECLAIM, AENS_CLAIM, AENS_UPDATE, AENS_TRANSFER, AENS_REVOKE, ORACLE_REGISTER, ORACLE_RESPOND, and ORACLE_EXTEND. The first argument of these operations is a delegation signature - the signature "proves" that the user is allowed to manipulate the object (name or oracle). Naturally, if the contract itself is the owner of the name/oracle the signature is not needed. Otherwise, the user signs (using the private key) data authorizing the operation. Note: it is not possible to make a delegation signature using a generalized account.

There are five different delegation signatures: - AENS_PRECLAIM - the user signs: owner account + contract - AENS_CLAIM,AENS_UPDATE, AENS_TRANSFER, AENS_REVOKE - the user signs: owner account + name hash + contract - AENS wildcard (valid for any name) - the user signs: owner account + contract [New in FATE_03] - ORACLE_REGISTER, ORACLE_EXTEND - the user signs: owner account + contract - ORACLE_RESPOND - the user signs: query id + contract

To protect about cross network re-use of signatures, the data to be signed is also prefixed with the network id.

From Ceres: Serialized signature data

From Ceres/FATE_03 the material to be signed is more structured; the reason is two-fold, (a) to make it easier for the signer to see the what is signed and why, and (b) to safeguard against spoofing a transaction as a delegation signature (their structure was similar). Note: the semantic data to be signed has not changed from the description above, only the exact bytes to be signed and its structure.

For general information about serialization, RLP encoding, etc, see the general serialization document.

We use the tag 0x1a01 to identify delegation signatures. We use the following tags/types to identify the different delegation signatures:

Tag Delegation type
1 aens wildcard
2 aens name
3 aens preclaim
4 oracle
5 oracle response

For serialization we use a schema similar to chain object serialization with the tags in the table above and version is 1. I.e. S = rlp([tag, vsn] ++ fields) with fields as described below. The complete binary to sign is: 

 0x1a01 + <network_id> + S

AENS Wildcard

[ <account>  :: id()
, <contract> :: id() ]

AENS Name

[ <account>  :: id()
, <name>     :: id()
, <contract> :: id() ]

AENS Preclaim

[ <account>  :: id()
, <contract> :: id() ]

Oracle handling

[ <account>  :: id()
, <contract> :: id() ]

Oracle response

[ <query_id> :: id()     %% using id type 'oracle'
, <contract> :: id() ]

Notation

Some notes on notation and definition of terms used in this document.

Bits

Bits are counted from the least significant bit, starting on 0. When bits are written out they are written from the most significant bit to the least significant bit.

Example the number 1 in a byte would be written in binary as: 

00000001
And we would say that bit 0 is set to 1. All other bits 1 to 7 are set to 0.

Word size

The word size of the machine is 8 bits (one byte) but each type and instruction uses words of varying sizes, all multiples of bytes though.