Show / Hide Table of Contents

NeoVM Instructions

Built-in data types

NeoVM has following built-in data types:

TypeDescription
ArrayImplemented as a List<StackItem> , the StackItem is an abstract class, and all the built-in data types are inherited from it.
BooleanImplemented as two byte arrays, TRUE and FALSE .
BufferReadonly byte array, implemented as a buffer array byte[]
ByteStringReadonly byte array, implemented as a ReadOnlyMemory<byte>
IntegerImplemented as a BigInteger value.
InteropInterfaceInteroperable interface
MapImplemented as a key-value pair Dictionary<StackItem, StackItem> .
NullNull type
PointerImplemented as a context Script and an instruction Position
StructInherited from Array, a Clone method is added and Equals method is overridden.
  • CompoundType : Compound type, which includes Array , Map and Struct

  • PrimitiveType : Basic type which includes Boolean , ByteString and Integer

// boolean type
private static readonly byte[] TRUE = { 1 };
private static readonly byte[] FALSE = { 0 };

private bool value;

Instructions

NeoVM has implemented 189 instructions. The categories are as follows:

ConstantFlow ControlStack OperationSlot OperationString OperationLogical OperationArithmetic OperationAdvanced Data StructureType Operation
293215506625183

Details of each instruction in each category are introduced as follows.

Constants

The constant instructions mainly complete the function of pushing constants or arrays into the EvaluationStack .

PUSHINT

InstructionPUSHINT8, PUSHINT16, PUSHINT32, PUSHINT64, PUSHINT128, PUSHINT256
Bytecode0x00, 0x01, 0x02, 0x03, 0x04, 0x05
Fee0.00000001 GAS, 0.00000001 GAS, 0.00000001 GAS, 0.00000001 GAS, 0.00000004 GAS, 0.00000004 GAS
FunctionPush an integer onto the stack, the bit length of which is specified with the number 8\16\32\64\128\256.

PUSHA

InstructionPUSHA
Bytecode0x0A
Fee0.00000004 GAS
FunctionConvert the next four bytes to an address, and push the address onto the stack.

PUSHNULL

InstructionPUSHNULL
Bytecode0x0B
Fee0.00000001 GAS
FunctionThe item null is pushed onto the stack.

PUSHDATA

InstructionPUSHDATA1, PUSHDATA2, PUSHDATA4
Bytecode0x0C, 0x0D, 0x0E
Fee0.00000008 GAS, 0.00000512 GAS, 0.00004096 GAS
FunctionThe next n bytes contain the number of bytes to be pushed onto the stack, where n is specified by 1|2|4.

PUSHM1

InstructionPUSHM1
Bytecode0x0F
Fee0.00000001 GAS
FunctionThe number -1 is pushed onto the stack.

PUSHN

InstructionPUSH0~PUSH16
Bytecode0x10~0x20
Fee0.00000001 GAS
FunctionThe number n is pushed onto the stack,where n is specified by 0~16.

Flow Control

It's used to control the running process of NeoVM, including jump, call and other instructions.

NOP

InstructionNOP
Bytecode0x21
Fee0.00000001 GAS
FunctionThe NOP operation does nothing. It is intended to fill in space if opcodes are patched.

JMP

InstructionJMP
Bytecode0x22
Fee0.00000002 GAS
FunctionUnconditionally transfers control to a target instruction. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMP_L

InstructionJMP_L
Bytecode0x23
Fee0.00000002 GAS
FunctionUnconditionally transfers control to a target instruction. The target instruction is represented as a 4-bytes signed offset from the beginning of the current instruction.

JMPIF

InstructionJMPIF
Bytecode0x24
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the value is true , not null , or non-zero. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPIF_L

InstructionJMPIF
Bytecode0x25
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the value is true , not null , or non-zero. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPIFNOT

InstructionJMPIFNOT
Bytecode0x26
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the value is false , a null reference, or zero. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPIFNOT_L

InstructionJMPIFNOT_L
Bytecode0x27
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the value is false , a null reference, or zero. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPEQ

InstructionJMPEQ
Bytecode0x28
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if two values are equal. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPEQ_L

InstructionJMPEQ_L
Bytecode0x29
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if two values are equal. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPNE

InstructionJMPNE
Bytecode0x2A
Fee0.00000002 GAS
FunctionTransfers control to a target instruction when two values are not equal. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPNE_L

InstructionJMPNE_L
Bytecode0x2B
Fee0.00000002 GAS
FunctionTransfers control to a target instruction when two values are not equal. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPGT

InstructionJMPGT
Bytecode0x2C
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is greater than the second value. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPGT_L

InstructionJMPGT_L
Bytecode0x2D
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is greater than the second value. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPGE

InstructionJMPGE
Bytecode0x2E
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is greater than or equal to the second value. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPGE_L

InstructionJMPGE_L
Bytecode0x2F
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is greater than or equal to the second value. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPLT

InstructionJMPLT
Bytecode0x30
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is less than the second value. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPLT_L

InstructionJMPLT_L
Bytecode0x31
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is less than the second value. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

JMPLE

InstructionJMPLE
Bytecode0x32
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is less than or equal to the second value. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

JMPLE_L

InstructionJMPLE_L
Bytecode0x33
Fee0.00000002 GAS
FunctionTransfers control to a target instruction if the first value is less than or equal to the second value. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

CALL

InstructionCALL
Bytecode0x34
Fee0.00000512 GAS
FunctionCalls the function at the target address which is represented as a 1-byte signed offset from the beginning of the current instruction.

CALL_L

InstructionCALL_L
Bytecode0x35
Fee0.00000512 GAS
FunctionCalls the function at the target address which is represented as a 4-bytes signed offset from the beginning of the current instruction.

CALLA

InstructionCALLA
Bytecode0x36
Fee0.00000512 GAS
FunctionPops the address of a function from the stack, and call the function.

CALLT

InstructionCALLT
Bytecode0x37
Fee0.00032768 GAS
FunctionPops the function Token from the stack, and call the function.

ABORT

InstructionABORT
Bytecode0x37
Fee0 GAS
FunctionIt turns the vm state to FAULT immediately, and the exception cannot be caught.

ASSERT

InstructionASSERT
Bytecode0x38
Fee0.00000001 GAS
FunctionPop the top value of the stack, if it is false, then exit vm execution and set vm state to FAULT.

THROW

InstructionTHROW
Bytecode0x3A
Fee0.00000512 GAS
FunctionThrows the exception of stack top

TRY

InstructionTRY
Bytecode0x3B
Fee0.00000004 GAS
FunctionEnters the block of Try statement. The Catch and Finally address offset are represented as a 1-byte signed offset from the beginning of the current instruction.

TRY_L

InstructionTRY_L
Bytecode0x3C
Fee0.00000004 GAS
FunctionEnters the block of Try statement. The Catch and Finally address offset are represented as a 4-byte signed offset from the beginning of the current instruction.

ENDTRY

InstructionENDTRY
Bytecode0x3D
Fee0.00000004 GAS
FunctionTerminates the block Try and unconditionally transfers control to a target instruction. The target instruction is represented as a 1-byte signed offset from the beginning of the current instruction.

ENDTRY_L

InstructionENDTRY_L
Bytecode0x3E
Fee0.00000004 GAS
FunctionTerminates the block Try and unconditionally transfers control to a target instruction. The target instruction is represented as a 4-byte signed offset from the beginning of the current instruction.

ENDFINALLY

InstructionENDFINALLY
Bytecode0x3F
Fee0.00000004 GAS
FunctionTerminates the block Finally and goes to the target instruction ENDTRY/ENDTRY_L if there is no exception, or throw the exception to the upper level again.

RET

InstructionRET
Bytecode0x40
Fee0 GAS
FunctionReturns from the current method.

SYSCALL

InstructionSYSCALL
Bytecode0x41
Fee0 GAS
FunctionCalls to an interop service.

Stack Operation

Copy, remove and swap the elements of the stack.

DEPTH

InstructionDEPTH
Bytecode0x43
Fee0.00000002 GAS
FunctionPuts the number of stack items onto the stack.

DROP

InstructionDROP
Bytecode0x45
Fee0.00000002 GAS
FunctionRemoves the top stack item.

NIP

InstructionNIP
Bytecode0x46
Fee0.00000002 GAS
FunctionRemoves the second-to-top stack item.

XDROP

InstructionXDROP
Bytecode0x48
Fee0.00000016 GAS
FunctionThe item n back in the main stack is removed.
FunctionGets the integer N from the top stack and removes elements indexed to N from the remaining elements of the stack.

CLEAR

InstructionCLEAR
Bytecode0x49
Fee0.00000016 GAS
FunctionClear the stack

DUP

InstructionDUP
Bytecode0x4A
Fee0.00000002 GAS
FunctionCopies the top stack item to the top.

OVER

InstructionOVER
Bytecode0x4B
Fee0.00000002 GAS
FunctionCopies the second-to-top stack item to the top.

PICK

InstructionPICK
Bytecode0x4D
Fee0.00000002 GAS
FunctionGets the integer N from the top stack and copies elements indexed to N from the remaining elements of the stack to the top.

TUCK

InstructionTUCK
Bytecode0x4E
Fee0.00000002 GAS
FunctionThe item at the top of the stack is copied and inserted before the second-to-top item.

SWAP

InstructionSWAP
Bytecode0x50
Fee0.00000002 GAS
FunctionThe top two items on the stack are swapped.

ROT

InstructionROT
Bytecode0x51
Fee0.00000002 GAS
FunctionMoves the elements indexed to 2 to the top

ROLL

InstructionROLL
Bytecode0x52
Fee0.00000016 GAS
FunctionGets the integer N from the top stack and moves elements indexed to N from the remaining elements of the stack to the top.

REVERSE3

InstructionREVERSE3
Bytecode0x53
Fee0.00000002 GAS
FunctionReverse the order of the top 3 items on the stack.

REVERSE4

InstructionREVERSE4
Bytecode0x54
Fee0.00000002 GAS
FunctionReverse the order of the top 4 items on the stack.

REVERSEN

InstructionREVERSEN
Bytecode0x55
Fee0.00000016 GAS
FunctionGets the integer N from the top stack, and reverse the order of the top N items on the stack.

Slot

INITSSLOT

InstructionINITSSLOT
Bytecode0x56
Fee0.00000016 GAS
FunctionInitialize the static field list for the current execution context.

INITSLOT

InstructionINITSLOT
Bytecode0x57
Fee0.00000064 GAS
FunctionInitialize the argument slot and the local variable list for the current execution context.

LDSFLDN

InstructionLDSFLD0~LDSFLD6
Bytecode0x58~0x5E
Fee0.00000002 GAS
FunctionLoads the static field at index n onto the evaluation stack, where the n is 0~6。

LDSFLD

InstructionLDSFLD
Bytecode0x5F
Fee0.00000002 GAS
FunctionLoads the static field at a specified index onto the evaluation stack. The index is represented as a 1-byte unsigned integer.

STSFLDN

InstructionSTSFLD0~STSFLD6
Bytecode0x60~0x0x66
Fee0.00000002 GAS
FunctionStores the value on top of the evaluation stack in the static field list at index n , where the n is 0~6。

STSFLD

InstructionSTSFLD
Bytecode0x67
Fee0.00000002 GAS
FunctionStores the value on top of the evaluation stack in the static field list at a specified index. The index is represented as a 1-byte unsigned integer.

LDLOCN

InstructionLDLOC0~LDLOC6
Bytecode0x68~0x6E
Fee0.00000002 GAS
FunctionLoads the local variable at index n onto the evaluation stack, where the n is 0~6。

LDLOC

InstructionLDLOC
Bytecode0x6F
Fee0.00000002 GAS
FunctionLoads the local variable at a specified index onto the evaluation stack. The index is represented as a 1-byte unsigned integer.

STLOCN

InstructionSTLOC0~STLOC6
Bytecode0x70~0x76
Fee0.00000002 GAS
FunctionStores the value on top of the evaluation stack in the local variable list at index n , where the n is 0~6。

STLOC

InstructionSTLOC
Bytecode0x77
Fee0.00000002 GAS
FunctionStores the value on top of the evaluation stack in the local variable list at a specified index. The index is represented as a 1-byte unsigned integer.

LDARGN

InstructionLDARG0~LDARG6
Bytecode0x78~0x7E
Fee0.00000002 GAS
FunctionLoads the argument at index n onto the evaluation stack, where the n is 0~6.

LDARG

InstructionLDARG
Bytecode0x7F
Fee0.00000002 GAS
FunctionLoads the argument at a specified index onto the evaluation stack. The index is represented as a 1-byte unsigned integer.

STARGN

InstructionSTARG0~STARG6
Bytecode0x80~0x86
Fee0.00000002 GAS
FunctionStores the value on top of the evaluation stack in the argument slot at index n , where the n is 0~6.

STARG

InstructionSTARG
Bytecode0x87
Fee0.00000002 GAS
FunctionStores the value on top of the evaluation stack in the argument slot at a specified index. The index is represented as a 1-byte unsigned integer.

String Operation

NEWBUFFER

InstructionNEWBUFFER
Bytecode0x88
Fee0.00000256 GAS
FunctionCreate a new buffer

MEMCPY

InstructionMEMCPY
Bytecode0x89
Fee0.00002048 GAS
Functionmemory copy

CAT

InstructionCAT
Bytecode0x8B
Fee0.00002048 GAS
FunctionConcatenates two strings.

SUBSTR

InstructionSUBSTR
Bytecode0x8C
Fee0.00002048 GAS
FunctionReturns a section of a string.

LEFT

InstructionLEFT
Bytecode0x8D
Fee0.00002048 GAS
FunctionGets characters in the left of the specified point in a string.

RIGHT

InstructionRIGHT
Bytecode0x8E
Fee0.00002048 GAS
FunctionGets characters in the right of the specified point in a string.

Logical Operation

INVERT

InstructionINVERT
Bytecode0x90
Fee0.00000004 GAS
FunctionFlips all of the bits in the input.

AND

InstructionAND
Bytecode0x91
Fee0.00000008 GAS
FunctionBoolean and between each bit in the inputs

OR

InstructionOR
Bytecode0x92
Fee0.00000008 GAS
FunctionBoolean or between each bit in the inputs.

XOR

InstructionXOR
Bytecode0x93
Fee0.00000008 GAS
FunctionBoolean exclusive or between each bit in the inputs.

EQUAL

InstructionEQUAL
Bytecode0x97
Fee0.00000032 GAS
FunctionReturns 1 if the inputs are exactly equal, 0 otherwise.

NOTEQUAL

InstructionNOTEQUAL
Bytecode0x98
Fee0.00000032 GAS
FunctionReturns 1 if the inputs are not equal, 0 otherwise.

Arithmetic Operation

SIGN

InstructionSIGN
Bytecode0x99
Fee0.00000004 GAS
FunctionPuts the sign of top stack item on top of the main stack. If value is negative, put -1; if positive, put 1; if value is zero, put 0.

ABS

InstructionABS
Bytecode0x9A
Fee0.00000004 GAS
FunctionThe input is made positive.

NEGATE

InstructionNEGATE
Bytecode0x9B
Fee0.00000004 GAS
FunctionThe sign of the input is flipped.

INC

InstructionINC
Bytecode0x9C
Fee0.00000004 GAS
Function1 is added to the input.

DEC

InstructionDEC
Bytecode0x9D
Fee0.00000004 GAS
Function1 is subtracted from the input.

ADD

InstructionADD
Bytecode0x9E
Fee0.00000008 GAS
Functiona is added to b.

SUB

InstructionSUB
Bytecode0x9F
Fee0.00000008 GAS
Functionb is subtracted from a.

MUL

InstructionMUL
Bytecode0xA0
Fee0.00000008 GAS
Functiona is multiplied by b.

DIV

InstructionDIV
Bytecode0xA1
Fee0.00000008 GAS
Functiona is divided by b.

MOD

InstructionMOD
Bytecode0xA2
Fee0.00000008 GAS
FunctionReturns the remainder after dividing a by b.

SHL

InstructionSHL
Bytecode0xA8
Fee0.00000008 GAS
FunctionGets the integer n from the top stack and performs a n-bit left shift operation on the remaining BigInteger on the stack.

SHR

InstructionSHR
Bytecode0xA9
Fee0.00000008 GAS
FunctionGets the integer n from the top stack and performs a n-bit right shift operation on the remaining BigInteger on the stack.

NOT

InstructionNOT
Bytecode0xAA
Fee0.00000004 GAS
FunctionIf the input is 0 or 1, it is flipped. Otherwise the output will be 0.

BOOLAND

InstructionBOOLAND
Bytecode0xAB
Fee0.00000008 GAS
FunctionIf both a and b are not 0, the output is 1. Otherwise 0.

BOOLOR

InstructionBOOLOR
Bytecode0xAC
Fee0.00000008 GAS
FunctionIf a or b is not 0, the output is 1. Otherwise 0.

NZ

InstructionNZ
Bytecode0xB1
Fee0.00000004 GAS
FunctionReturns 0 if the input is 0. 1 otherwise.

NUMEQUAL

InstructionNUMEQUAL
Bytecode0xB3
Fee0.00000008 GAS
FunctionReturns 1 if the numbers are equal, 0 otherwise.

NUMNOTEQUAL

InstructionNUMNOTEQUAL
Bytecode0xB4
Fee0.00000008 GAS
FunctionReturns 1 if the numbers are not equal, 0 otherwise.

LT

InstructionLT
Bytecode0xB5
Fee0.00000008 GAS
FunctionReturns 1 if a is less than b, 0 otherwise.

LE

InstructionLE
Bytecode0xB6
Fee0.00000008 GAS
FunctionReturns 1 if a is less than or equal to b, 0 otherwise.

GT

InstructionGT
Bytecode0xB7
Fee0.00000008 GAS
FunctionReturns 1 if a is greater than b, 0 otherwise.

GE

InstructionGE
Bytecode0xB8
Fee0.00000008 GAS
FunctionReturns 1 if a is greater than or equal to b, 0 otherwise.

MIN

InstructionMIN
Bytecode0xB9
Fee0.00000008 GAS
FunctionReturns the smaller of a and b.

MAX

InstructionMAX
Bytecode0xBA
Fee0.00000008 GAS
FunctionReturns the larger of a and b.

WITHIN

InstructionWITHIN
Bytecode0xBB
Fee0.00000008 GAS
FunctionReturns 1 if x is within the specified range (left-inclusive), 0 otherwise.

Advanced Data Structure

It has implemented common operations for array, map, struct, etc.

PACK

InstructionPACK
Bytecode0xC0
Fee0.00000512 GAS
FunctionA value n is taken from top of main stack. The next n items on main stack are removed, put inside n-sized array and this array is put on top of the main stack.

UNPACK

InstructionUNPACK
Bytecode0xC1
Fee0.00000512 GAS
FunctionAn array is removed from top of the main stack. Its elements are put on top of the main stack (in reverse order) and the array size is also put on main stack.

NEWARRAY0

InstructionNEWARRAY0
Bytecode0xC2
Fee0.00000016 GAS
FunctionAn array with size n is put on top of the main stack.

NEWARRAY

InstructionNEWARRAY
Bytecode0xC3
Fee0.00000512 GAS
FunctionA value n is taken from top of main stack. A null-filled array with size n is put on top of the main stack.

NEWARRAY_T

InstructionNEWARRAY_T
Bytecode0xC4
Fee0.00000512 GAS
FunctionAn array of type T with size n is put on top of the main stack.

NEWSTRUCT0

InstructionNEWSTRUCT0
Bytecode0xC5
Fee0.00000016 GAS
FunctionA structure with size n and all 0 elements is put on top of the main stack.

NEWSTRUCT

InstructionNEWSTRUCT
Bytecode0xC6
Fee0.00000512 GAS
FunctionA value n is taken from top of main stack. A zero-filled struct with size n is put on top of the main stack.

NEWMAP

InstructionNEWMAP
Bytecode0xC8
Fee0.00000008 GAS
FunctionAn empty Map is put on top of the main stack.

SIZE

InstructionSIZE
Bytecode0xCA
Fee0.00000004 GAS
FunctionGets the size of elements on the top stack.

HASKEY

InstructionHASKEY
Bytecode0xCB
Fee0.00000064 GAS
FunctionAn input index n (or key) and an array (Map,Buffer, ByteString) are returned from the top of the main stack. Puts True on top of main stack if n is in the length range of the array (Map,Buffer, ByteString), and False otherwise.

KEYS

InstructionKEYS
Bytecode0xCC
Fee0.00000016 GAS
FunctionGets all Keys of the map from top of the main stack and constructs a new array with all Key and puts it on top of the main stack.

VALUES

InstructionVALUES
Bytecode0xCD
Fee0.00008192 GAS
FunctionGets all Values of the elements (Array or Map) from top of the main stack and constructs a new array with all Value and puts it on top of the main stack.

PICKITEM

InstructionPICKITEM
Bytecode0xCE
Fee0.00000064 GAS
FunctionGets the Nth element in the array of the top stack

APPEND

InstructionAPPEND
Bytecode0xCF
Fee0.00008192 GAS
FunctionAdds a new item to the arry of the top stack

SETITEM

InstructionSETITEM
Bytecode0xD0
Fee0.00008192 GAS
FunctionAssigns a value to the specified index of element (Array,Map or Buffer)in the top stack

REVERSEITEMS

InstructionREVERSEITEMS
Bytecode0xD1
Fee0.00008192 GAS
FunctionReverses the elements in Array or Buffer from the top stack.

REMOVE

InstructionREMOVE
Bytecode0xD2
Fee0.00000016 GAS
FunctionRemoves the specified index or Key elements from Array or Map

CLEARITEMS

InstructionCLEARITEMS
Bytecode0xD3
Fee0.00000016 GAS
FunctionRemove all the items from the compound-type.

POPITEM

InstructionPOPITEM
Bytecode0xD4
Fee0.00000016 GAS
FunctionPops the last element in Array from the stack top and push into the stack.

Type

ISNULL

InstructionISNULL
Bytecode0xD8
Fee0.00000002 GAS
FunctionReturns true if the input is null. Returns false otherwise.

ISTYPE

InstructionISTYPE
Bytecode0xD9
Fee0.00000002 GAS
FunctionReturns true if the top item is of the specified type.

CONVERT

InstructionCONVERT
Bytecode0xDB
Fee0.00002048 GAS
FunctionConverts the top item to the specified type.

The operation code with * indicates that the result of the operation is not pushed back to the EvaluationStack using PUSH() .