Async VM Instruction Set Reference

The Async VM is Firechain's virtual machine and execution engine. It is a stack-based VM that executes smart contract code. The Async VM natively supports asynchronous execution, which allows Firechain to execute smart contracts in parallel. This page provides a reference for the instructions available in the Async VM. Many of the instructions supported by the Async VM are similar or identical to those of the Ethereum Virtual Machine (EVM). However, there are some major differences that are important to understand.

For example, the Async VM handles CALLs asynchronously. This means that a CALL instruction will not block the execution of the current smart contract. Instead, it will return a message ID immediately and the execution of the current smart contract will continue. The CALL might be executed in parallel with the current smart contract, at a later point, or not at all, and it's therefore not guaranteed when or if it will return or have any observable effects. This is a major difference between the Async VM and the EVM. If your contract depends on the result of a CALL, you should use the CALL instruction in combination with the WAIT instruction. The WAIT instruction will block the execution of the current smart contract until the CALL returns or the deadline passes.

Instruction Set

The following table lists the instructions supported by the Async VM. The table is organized by instruction category. Each instruction is listed with its opcode, name, and description.

Arithmetic

The following instructions perform arithmetic operations on the stack.

Opcode	Name	Description
0x01	ADD	Add two operands and return the sum.
0x02	MUL	Multiply two operands and return the product.
0x03	SUB	Subtract two operands and return the difference.
0x04	DIV	Perform integer division on two operands and return the quotient.
0x05	SDIV	Same as DIV, but for signed integers.
0x06	MOD	Perform integer modulus on two operands and return the remainder.
0x07	SMOD	Same as MOD, but for signed integers.
0x08	ADDMOD	Add two operands and return the sum modulo a third operand.
0x09	MULMOD	Multiply two operands and return the product modulo a third operand.
0x0a	EXP	Raise a base to an exponent and return the result.
0x0b	SIGNEXTEND	Extend the length of a signed integer.

Comparison and Bitwise Logic

The following instructions perform comparison and bitwise logic operations on the stack.

Opcode	Name	Description
0x10	LT	Return 1 if the first operand is less than the second operand, otherwise return 0.
0x11	GT	Return 1 if the first operand is greater than the second operand, otherwise return 0.
0x12	SLT	Same as LT but for signed operands.
0x13	SGT	Same as GT but for signed operands.
0x14	EQ	Return 1 if the operands are equal, otherwise return 0.
0x15	ISZERO	Return 1 if the operand is zero, otherwise return 0.
0x16	AND	Bitwise AND two operands and return the result.
0x17	OR	Bitwise OR two operands and return the result.
0x18	XOR	Bitwise XOR two operands and return the result.
0x19	NOT	Bitwise NOT the operand and return the result.
0x1a	BYTE	Return the nth byte of the operand.
0x1b	SHL	Shift the operand left by the number of bits specified by the second operand.
0x1c	SHR	Shift the operand right by the number of bits specified by the second operand.
0x1d	SAR	Arithmetic right shift. The sign bit is copied.

Hashing and Cryptography

The following instructions perform synchronous hashing and cryptography operations on the stack. Note that there are many other cryptographic operations supported through the use of precompiled contracts which are not listed here, including functionality related to zero-knowledge proofs and elliptic curve cryptography.

Opcode	Name	Description
0x20	SHA3	Compute the SHA3-256 hash of the operand and return the result.
0x21	SHA256	Compute the SHA256 hash of the operand and return the result.
0x22	BLAKE2B	Compute the BLAKE2B hash of the operand and return the result.
0x23	RIPEMD160	Compute the RIPEMD160 hash of the operand and return the result.
0x24	KECCAK256	Compute the KECCAK256 hash of the operand and return the result.

Environment

The following instructions provide information about the environment in which the smart contract is executing.

Opcode	Name	Description
0x30	ADDRESS	Return the address of the current account context.
0x31	BALANCE	Return the balance of an account. Accepts an address and token ID as operands.
0x32	ORIGIN	Return the address of the current message's sender or event source.
0x33	CALLER	Same as ORIGIN but returns the current account's address in an event listener.
0x34	CALLVALUE	Return the token value of the current message. Accepts a token ID as an operand.
0x35	CALLDATALOAD	Return the data from the current message's body. Accepts an offset and length as operands.
0x36	CALLDATASIZE	Return the size of the current message's body.
0x37	CALLDATACOPY	Copy the data from the current message's body to memory. Accepts an offset and length as operands.
0x38	CODESIZE	Return the size of the current contract's code.
0x39	CODECOPY	Copy the current contract's code to memory. Accepts an offset and length as operands.
0x3a	HEAT	Return the amount of heat generated by the current message.
0x3b	RAND	Return a random number. Always returns a fresh random number.
0x3c	RRAND	Return a random number. Always returns the same number within the same execution context.
0x3d	RETURNDATASIZE	Return the size of an external call's return data, or 0 if not available. Accepts a message ID as an operand.
0x3e	RETURNDATACOPY	Copy an external call's return data to memory. Accepts a message ID, data offset and length as operands.
0x40	MSGHASH	Return the ID of the current message.
0x41	COINBASE	Return the address of the current validator.
0x42	TIMESTAMP	Return the current execution's timestamp. Will change if execution is suspended.
0x43	HEIGHT	Return the current account's height, including the current message.
0x44	LCVCOUNT	Return the number of validators in the local consensus group.
0x45	GCVCOUNT	Return the number of validators in the global consensus group.
0x46	QUEUETIME	Return the timestamp when the current message was added to the queue.
0x47	COMMITTIME	Return the timestamp when the current message was committed by the LCG.
0x48	CONFTIME	Return the timestamp when the current message was first globally confirmed. Returns 0 if not yet confirmed.
0x49	MSGTIME	Return the timestamp from the current message's header.
0x4a	CHAINID	Return the chain ID of the current chain.
0x4b	CONFDEPTH	Return the number of global confirmations. Returns 0 if not yet confirmed.

Stack and Memory

The following instructions manipulate the stack and memory.

Opcode	Name	Description
0x50	POP	Remove the top item from the stack.
0x51	MLOAD	Load a word from memory. Accepts an offset as an operand.
0x52	MSTORE	Store a word to memory. Accepts an offset as an operand.
0x53	MSTORE8	Store a byte to memory. Accepts an offset as an operand.
0x54	SLOAD	Load a word from storage. Accepts a key as an operand.
0x55	SSTORE	Store a word to storage. Accepts a key and a value as operands.
0x56	JUMPDEST	Mark a valid jump destination.
0x57	JUMP	Jump to a label. Accepts a label as an operand.
0x58	JUMPI	Jump to a label if the top item on the stack is not zero. Accepts a label as an operand.
0x59	PC	Return the current program counter.
0x5a	MSIZE	Return the current size of memory.

PUSH (Push a value onto the stack)

Opcode	Name	Description
0x60	PUSH1	Push a 1-byte value onto the stack.
0x61	PUSH2	Push a 2-byte value onto the stack.
0x62	PUSH3	Push a 3-byte value onto the stack.
...	...	...
0x7d	PUSH30	Push a 30-byte value onto the stack.
0x7e	PUSH31	Push a 31-byte value onto the stack.
0x7f	PUSH32	Push a 32-byte value onto the stack.

DUP (Duplicate an item on the stack)

Opcode	Name	Description
0x80	DUP1	Duplicate the top item on the stack.
0x81	DUP2	Duplicate the 2nd item on the stack.
0x82	DUP3	Duplicate the 3rd item on the stack.
...	...	...
0x8d	DUP14	Duplicate the 14th item on the stack.
0x8e	DUP15	Duplicate the 15th item on the stack.
0x8f	DUP16	Duplicate the 16th item on the stack.

Swap (Swap two items on the stack)

Opcode	Name	Description
0x90	SWAP1	Swap the top two items on the stack.
0x91	SWAP2	Swap the 1st and 3rd items on the stack.
0x92	SWAP3	Swap the 1st and 4th items on the stack.
...	...	...
0x9d	SWAP14	Swap the 1st and 15th items on the stack.
0x9e	SWAP15	Swap the 1st and 16th items on the stack.
0x9f	SWAP16	Swap the 1st and 17th items on the stack.

Logging

The following instructions are used to log data. Logs are stored in the current message's receipt and can be retrieved by the sender.

Opcode	Name	Description
0xa0	LOG0	Log an event with no topics. Accepts a memory offset and length as operands.
0xa1	LOG1	Log an event with one topic. Accepts a memory offset, length and topic as operands.
0xa2	LOG2	Log an event with two topics. Accepts a memory offset, length and two topics as operands.
0xa3	LOG3	Log an event with three topics. Accepts a memory offset, length and three topics as operands.
0xa4	LOG4	Log an event with four topics. Accepts a memory offset, length and four topics as operands.

System operations

The following instructions are used to interact with the system.

Opcode	Name	Description
0xf0	CALL	Create an async request to a remote contract. Accepts a target account, token id, token value, and message data as operands. Returns a message ID.
0xf1	WAIT	Wait for the result of a request. Accepts a message ID and deadline as operands.
0xf2	RETURN	Return from the current function. Accepts a value, length and offset as operands.
0xf3	REVERT	Revert the current message. Accepts a value, length and offset as operands.
0xf4	FREEZE	Freeze the current account. Suspends job execution, disables outbound messages, and freezes storage.
0xf5	UNFREEZE	Unfreeze the current account. Resumes scheduled job execution, enables outbound messaging, and restores storage.

Notes

The CALL opcode is used to create a new message to a remote contract. The message is not executed synchronously, but is added to the message queue of the target account. The message ID is returned as the result of the CALL opcode. The message ID can be used to query the status of the message, and to retrieve the return data of the message, however the return data is only available after the message has been confirmed by the global consensus group.
Several time-related opcodes are available to contracts. These opcodes return the timestamp when the current execution started, when the message was committed to the account's chain by the local consensus group, when the message was first globally confirmed, and the timestamp indicated by the message itself. These opcodes can be used to implement time-based logic in contracts.