Show / Hide Table of Contents

NeoVM Instructions

Built-in data types

NeoVM has seven built-in data types:

TypeDescription
BooleanImplemented as two byte arrays, TRUE and FALSE .
IntegerImplemented as a BigInteger value.
ByteArrayImplemented as a byte[] .
ArrayImplemented as a List<StackItem> , the StackItem is an abstract class, and all the built-in data types are inherited from it.
StructInherited from Array, a Clone method is added and Equals method is overridden.
MapImplemented as a key-value pair Dictionary<StackItem, StackItem> .
InteropInterfaceInteroperable interface
// boolean type
private static readonly byte[] TRUE = { 1 };
private static readonly byte[] FALSE = { 0 };

private bool value;

Instructions

NeoVM has implemented 113 instructions (and four unimplemented instructions). The categories are as follows:

ConstantFlow ControlStack OperationString OperationLogical OperationArithmetic OperationCryptographyAdvanced Data StructureStack IsolationException Processing
25916552571452

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

Constant

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

PUSH0

InstructionPUSH0
Bytecode:0x00
Alias: PUSHF
Function:Push an empty array into the EvaluationStack

PUSHBYTES

InstructionPUSHBYTES1~PUSHBYTES75
Bytecode:0x01~0x4B
Function:Push a byte array into the EvaluationStack , the length of which is equal to the value of this instruction's bytecode.

PUSHDATA

InstructionPUSHDATA1, PUSHDATA2, PUSHDATA4
Bytecode:0x4C, 0x4D, 0x4E
Function:Push a byte array into the EvaluationStack , the length of which is specified by 1|2|4 bytes after this instruction.

PUSHM1

InstructionPUSHM1
Bytecode:0x4F
Function:Push a BigInteger of -1 into the EvaluationStack .

PUSHN

InstructionPUSH1~PUSH16
Bytecode:0x51~0x60
Alias: PUSHT
Function:Push a BigInteger into the EvaluationStack , the value of which is equal to 1~16.

Flow Control

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

NOP

InstructionNOP
Bytecode:0x61
Function:Empty operation, but it will add 1 to the instruction counter.

JMP

InstructionJMP
Bytecode:0x62
Function:Jump to the specified offset unconditionally, which is specified by 2 bytes after this instruction.

JMPIF

InstructionJMPIF
Bytecode:0x63
Function:When the top element of the EvaluationStack isn't 0, then jump to the specified offset, which is specified by 2 bytes after this instruction.
Whether the condition is true or false, the top element of the stack will be removed.

JMPIFNOT

InstructionJMPIFNOT
Bytecode:0x64
Function:When the top element of the EvaluationStack is 0, then jump to the specified offset, which is specified by 2 bytes after this instruction.

CALL

InstructionCALL
Bytecode:0x65
Function:Call the function at the specified offset, which is specified by 2 bytes after this instruction.

RET

InstructionRET
Bytecode:0x66
Function:Remove the top element of the InvocationStack and set the instruction counter point to the next frame of the stack.
If the InvocationStack is empty, the virtual machine enters HALT state.

APPCALL

InstructionAPPCALL
Bytecode:0x67
Function:Call the function with the specified address, which is specified by 20 bytes after this instruction

SYSCALL

InstructionSYSCALL
Bytecode:0x68
Function:Call the specified interoperable function whose name is specified by the string after this instruction.

TAILCALL

InstructionTAILCALL
Bytecode:0x69
Function:Tail call (no longer returning back to the current execution environment after the call).
Call the specified interoperable function whose name is specified by the string after this instruction.

Stack Operation

It's used to copy, remove and swap the elements of the stack.

DUPFROMALTSTACK

InstructionDUPFROMALTSTACK
Bytecode:0x6A
Function:Copy the top element of the AltStack , and push it into the EvaluationStack .

TOALTSTACK

InstructionTOALTSTACK
Bytecode:0x6B
Function:Remove the top element of the EvaluationStack , and push it into the AltStack .

FROMALTSTACK

InstructionFROMALTSTACK
Bytecode:0x6C
Function:Remove the top element of the AltStack , and push it into the EvaluationStack .

XDROP

InstructionXDROP
Bytecode:0x6D
Function:Remove the element n at the top of the EvaluationStack , and remove the remaining element with index n.
Input:Xn Xn-1 ... X2 X1 X0 n
Output:Xn-1 ... X2 X1 X0

XSWAP

InstructionXSWAP
Bytecode:0x72
Function:Remove the element n at the top of the EvaluationStack , and swap the remaining element with index 0 and the element with index n.
Input:Xn Xn-1 ... X2 X1 X0 n
Output:X0 Xn-1 ... X2 X1 Xn

XTUCK

InstructionXTUCK
Bytecode:0x73
Function:Remove the element n at the top of the EvaluationStack , copy the element with index 0, and insert to the index n.
Input:Xn Xn-1 ... X2 X1 X0 n
Output:Xn X0 Xn-1 ... X2 X1 X0

DEPTH

InstructionDEPTH
Bytecode:0x74
Function:Push the number of elements in the EvaluationStack into the top of the EvaluationStack .

DROP

InstructionDROP
Bytecode:0x75
Function:Remove the top element of the EvaluationStack

DUP

InstructionDUP
Bytecode:0x76
Function:Copy the top element of the EvaluationStack , and push it into the EvaluationStack .
Input:X
Output:X X

NIP

InstructionNIP
Bytecode:0x77
Function:Remove the second top element of the EvaluationStack
Input:X1 X0
Output:X0

OVER

InstructionOVER
Bytecode:0x78
Function:Copy the second top element of the EvaluationStack , and push it into the EvaluationStack .
Input:X1 X0
Output:X1 X0 X1

PICK

InstructionPICK
Bytecode:0x79
Function:Remove the element n at the top of the EvaluationStack , and copy the element with index n to the top.
Input:Xn Xn-1 ... X2 X1 X0 n
Output:Xn Xn-1 ... X2 X1 X0 Xn

ROLL

InstructionROLL
Bytecode:0x7A
Function:Remove the element n at the top of the EvaluationStack , and move the element with index n to the top.
Input:Xn Xn-1 ... X2 X1 X0 n
Output:Xn-1 ... X2 X1 X0 Xn

ROT

InstructionROT
Bytecode:0x7B
Function:Move the third top element of the EvaluationStack to the top.
Input:X2 X1 X0
Output:X1 X0 X2

SWAP

InstructionSWAP
Bytecode:0x7C
Function:Swap the two elements at the top of the EvaluationStack
Input:X1 X0
Output:X0 X1

TUCK

InstructionTUCK
Bytecode:0x7D
Function:Copy the top element of the EvaluationStack , and insert to the index 2.
Input:X1 X0
Output:X0 X1 X0

String Operation

CAT

InstructionCAT
Bytecode:0x7E
Function:Remove the two top elements of the EvaluationStack , concat them together and push it back to the EvaluationStack
Input:X1 X0
Output:Concat(X1,X0)

SUBSTR

InstructionSUBSTR
Bytecode:0x7F
Function:Remove the three top elements of the EvaluationStack , calculate the substring and push it back.
Input:X index len
Output:SubString(X,index,len)

LEFT

InstructionLEFT
Bytecode:0x80
Function:Remove the two top elements of the EvaluationStack , calculate the left-side substring and push it back.
Input:X len
Output:Left(X,len)

RIGHT

InstructionRIGHT
Bytecode:0x81
Function:Remove the two top elements of the EvaluationStack , calculate the right-side substring and push it back.
Input:X len
Output:Right(X,len)

SIZE

InstructionSIZE
Bytecode:0x82
Function:Push the length of the top string element to the EvaluationStack top.
Input:X
Output:X len(X)

Logical Operation

INVERT

InstructionINVERT
Bytecode:0x83
Function:Remove the top element, inverse by bit, and push it back to the EvaluationStack top.
Input:X
Output:~X

AND

InstructionAND
Bytecode:0x84
Function:Remove the two top elements, push the logic AND result of the two elements back to the EvaluationStack top.
Input:AB
Output:A&B

OR

InstructionOR
Bytecode:0x85
Function:Remove the two top elements, push the logic OR result of the two elements back to the EvaluationStack top.
Input:AB
Output:A|B

XOR

InstructionXOR
Bytecode:0x86
Function:Remove the two top elements, push the logic XOR result of the two elements back to the EvaluationStack top.
Input:AB
Output:A^B

EQUAL

InstructionEQUAL
Bytecode:0x87
Function:Check whether the top two elements are equivalence bit-by-bit.
Input:AB
Output:Equals(A,B)

Arithmetic Operation

INC

InstructionINC
Bytecode:0x8B
Function:Add 1 to the top element of the EvaluationStack .
Input:X
Output:X+1

DEC

InstructionDEC
Bytecode:0x8C
Function:Add -1 to the top element of the EvaluationStack .
Input:X
Output:X-1

SIGN

InstructionSIGN
Bytecode:0x8D
Function:Remove the top element and push the sign of it back to the EvaluationStack .
Input:X
Output:X.Sign()

NEGATE

InstructionNEGATE
Bytecode:0x8F
Function:Remove the top element and push the opposite number back to the EvaluationStack .
Input:X
Output:-X

ABS

InstructionABS
Bytecode:0x90
Function:Remove the top element and push the absolute number back to the EvaluationStack .
Input:X
Output:Abs(X)

NOT

InstructionNOT
Bytecode:0x91
Function:Remove the top element and push the logic "negation" value back to the EvaluationStack .
Input:X
Output:!X

NZ

InstructionNZ
Bytecode:0x92
Function:Check whether the top element of the EvaluationStack is a non-zero value.
Input:X
Output:X!=0

ADD

InstructionADD
Bytecode:0x93
Function:The addition operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A+B

SUB

InstructionSUB
Bytecode:0x94
Function:The subtraction operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A-B

MUL

InstructionMUL
Bytecode:0x95
Function:The multiplication operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A*B

DIV

InstructionDIV
Bytecode:0x96
Function:The division operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A/B

MOD

InstructionMOD
Bytecode:0x97
Function:The redundancy operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A%B

SHL

InstructionSHL
Bytecode:0x98
Function:The left-shift operation is performed on the top elment of the EvaluationStack .
InstructionXn
Bytecode:X<<n

SHR

InstructionSHR
Bytecode:0x99
Function:The right-shift operation is performed on the top elment of the EvaluationStack .
Input:Xn
Output:X>>n

BOOLAND

InstructionBOOLAND
Bytecode:0x9A
Function:The logic "and" operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A&&B

BOOLOR

InstructionBOOLOR
Bytecode:0x9D
Function:The logic "or" operation is performed on the top two elments of the EvaluationStack .
Input:AB
Output:A||B

NUMEQUAL

InstructionNUMEQUAL
Bytecode:0x9C
Function:Check whether the top two Bitintegers of the EvaluationStack are equal.
Input:AB
Output:A==B

NUMNOTEQUAL

InstructionNUMNOTEQUAL
Bytecode:0x9E
Function:Check whether the top two Bitintegers of the EvaluationStack aren't equal.
Input:AB
Output:A!=B

LT

InstructionLT
Bytecode:0x9F
Function:Check whether the first top element is less than the second top element in the EvaluationStack .
Input:AB
Output:A<B

GT

InstructionGT
Bytecode:0xA0
Function:Check whether the first top element is more than the second top element in the EvaluationStack .
Input:AB
Output:A>B

LTE

InstructionLTE
Bytecode:0xA1
Function:Check whether the first top element ls less than or equal to the second top element in the EvaluationStack .
Input:AB
Output:A<=B

GTE

InstructionGTE
Bytecode:0xA2
Function:Check whether the first top element is more than or equal to the second top element in the EvaluationStack .
Input:AB
Output:A>=B

MIN

InstructionMIN
Bytecode:0xA3
Function:Calculate the minimum of the two top elements in the EvaluationStack .
Input:AB
Output:Min(A,B)

MAX

InstructionMAX
Bytecode:0xA4
Function:Calculate the maximum of the two top elements in the EvaluationStack .
Input:AB
Output:Max(A,B)

WITHIN

InstructionWITHIN
Bytecode:0xA5
Function:Check whether the Biginteger value is within the specified range.
Input:XAB
Output:A<=X&&X<B

Cryptography

It has implemented hash operation and signature verification and so on.

SHA1

InstructionSHA1
Bytecode:0xA7
Function:Performs a built-in SHA1 hash operation on the top element in the EvaluationStack .
Input:X
Output:SHA1(X)

SHA256

InstructionSHA256
Bytecode:0xA8
Function:Performs a built-in SHA256 hash operation on the top element in the EvaluationStack .。
Input:X
Output:SHA256(X)

HASH160

InstructionHASH160
Bytecode:0xA9
Function:Performs a built-in 160-bit hash operation on the top element in the EvaluationStack .
Input:X
Output:HASH160(X)

HASH256

InstructionHASH256
Bytecode:0xAA
Function:Performs a built-in 256-bit hash operation on the top element in the EvaluationStack .
Input:X
Output:HASH256(X)

CHECKSIG

InstructionCHECKSIG
Bytecode:0xAC
Function:Using the given signature and public key in the EvaluationStack , the built-in asymmetric signaure verfication operation is performed on the current verification object.
Input:SK
Output:Verify(S,K)

VERIFY

InstructionVERIFY
Bytecode:0xAD
Function:Using the given signature and public key in the EvaluationStack , the built-in asymmetric signaure verfication operation is performed on the given verification object.
Input:MSK
Output:Verify(M,S,K)

CHECKMULTISIG

InstructionCHECKMULTISIG
Bytecode:0xAE
Function:Using the given signatures and public keys in the EvaluationStack , the built-in asymmetric multi-signaure verfication operation is performed on the current verification object.
Input:Sm-1 ... S2 S1 S0 m Kn-1 ... K2 K1 K0 n
Output:Verify(Sm-1 ... S2 S1 S0 m Kn-1 ... K2 K1 K0 n)
Note:For any 𝑆𝑖∈{𝑆0,…, 𝑆𝑚−1}, there exists a 𝐾𝑗∈{𝐾0, … , 𝐾𝑛−1}
makes Verify(𝑆𝑖, 𝐾𝑗) ==1, then V=1; otherwise, V=0.

Advanced Data Structure

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

ARRAYSIZE

InstructionARRAYSIZE
Bytecode:0xC0
Function:Get the number of elements of the array at the top of the EvaluationStack .
Input:[X0 X1 X2 ... Xn-1]
Output:n

PACK

InstructionPACK
Bytecode:0xC1
Function:Pack the n elments at the top of the EvaluationStack into array.
Input:Xn-1 ... X2 X1 X0 n
Output:[X0 X1 X2 ... Xn-1]

UNPACK

InstructionUNPACK
Bytecode:0xC2
Function:Get the number of elements of the array at the top of the EvaluationStack .
Input:[X0 X1 X2 ... Xn-1]
Output:Xn-1 ... X2 X1 X0 n

PICKITEM

InstructionPICKITEM
Bytecode:0xC3
Function:Get the specified element in the array at the top of the EvaluationStack .
Input:[X0 X1 X2 ... Xn-1] i
Output:Xi

SETITEM*

InstructionSETITEM
Bytecode:0xC4
Function:Assign a value to the specified index element in the array at the top of the EvaluationStack .
Input:[X0 X1 X2 ... Xn-1] I V
Output:[X0 X1 X2 Xi-1 V X i+1 ... Xn-1]

NEWARRAY

InstructionNEWARRAY
Bytecode:0xC5
Function:Create a new N-size array on the top of the EvaluationStack .
Input:n
Output:Array(n) with all false elements.

NEWSTRUCT

InstructionNEWSTRUCT
Bytecode:0xC6
Function:Create a new N-size struct on the top of the EvaluationStack .
Input:n
Output:Struct(n) with all false elements.

NEWMAP

InstructionNEWMAP
Bytecode:0xC7
Function:Create a new map on the top of the EvaluationStack .
Input:
Output:Map()

APPEND*

InstructionAPPEND
Bytecode:0xC8
Function:Add a new item to the array
Input:Array item
Output:Array.add(item)

REVERSE*

InstructionREVERSE
Bytecode:0xC9
Function:Reverse the array.
Input:[X0 X1 X2 ... Xn-1]
Output:[Xn-1 ... X2 X1 X0]

REMOVE*

InstructionREMOVE
Bytecode:0xCA
Function:Remove the specified element from the array or map.
Input:[X0 X1 X2 ... Xn-1] m
Output:[X0 X1 X2 ... Xm-1 Xm+1 ... Xn-1]

HASKEY

InstructionHASKEY
Bytecode:0xCB
Function:Check whether the array or the map contains a specified key element.
Input:[X0 X1 X2 ... Xn-1] key
Output:true or false

KEYS

InstructionKEYS
Bytecode:0xCC
Function:Get all the keys of the map, and put them into a new array.
Input:Map
Output:[key1 key2 ... key n]

VALUES

InstructionVALUES
Bytecode:0xCD
Function:Get all the values of the array or the map, and put them into a new array.
Input:Map or Array
Output:[Value1 Value2... Value n]

Stack Isolation

CALL_I

InstructionCALL_I
Bytecode:0xE0
Function:Call a new execution context, the script is the script of the current execution context,
pcount specifies the number of parameters, and rvcount specifies the number of results.
Jump to the new execution context.

CALL_E

InstructionCALL_E
Bytecode:0xE1
Function:Call a new execution context, the script is specified by the 20-byte hash after the instruction,
pcount specifies the number of parameters, and rvcount specifies the number of results.
Jump to the new execution context.

CALL_ED

InstructionCALL_ED
Bytecode:0xE2
Function:Call a new execution context, the script is specified by the Hash at the top of the evaluation stack,
pcount specifies the number of parameters, and rvcount specifies the number of results.
Jump to the new execution context.

CALL_ET

InstructionCALL_ET
Bytecode:0xE3
Function:The tail call form of CALL_E.

CALL_EDT

InstructionCALL_EDT
Bytecode:0xE4
Function:The tail call form of CALL_ED.

Exception Processing

THROW

InstructionTHROW
Bytecode:0xF0
Function:Set the virtual machine state to FAULT

THROWIFNOT

InstructionTHROWIFNOT
Bytecode:0xF1
Function:Read a boolean value from the top of the stack, and if it's False, then set the virtual machine state to FAULT .

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