The Stack

The AVM Stack is the core structure for the interpreter’s execution. It is constructed and used as a regular stack data structure.

Important

IMPLEMENTATION:

Stack reference implementation.

On a new AVM program execution, the Stack starts empty. After opcode execution the Stack can contain arbitrary values of either:

• 64-bit unsigned integer type (referred to as uint64), or

• Byte-array type (referred to as bytes or []byte).

Byte-arrays length MUST NOT exceed \( 4096 \) bytes.

A value that may be of either one of these types (not simultaneously) is generically referred to as a StackValue.

Most operations act on the stack, popping arguments from it and pushing results to it. Some operations have immediate arguments encoded directly into the instruction, rather than coming from the Stack.

The maximum Stack depth is \( 1000 \). If the Stack depth is exceeded or if a byte-array element exceeds \( 4096 \) bytes, the program fails.

If an opcode is documented to access a position in the Stack that does not exist, the operation fails.

Important

EXAMPLE:

This is often an attempt to access an element below the Stack. A simple example is an operation like concat that expects two arguments on the Stack: if the Stack has fewer than two elements, the operation fails.

Some operations (like frame_dig and proto) could fail because of an attempt to access above the current Stack.

Stack Types

While every element of the Stack is restricted to the types uint64 and bytes, the values of these types may be known to be bounded.

The most common bounded types are named to provide more semantic information in the documentation and as type checking during assembly time to provide more informative error messages.