Introduction

This note aims to explore how EVM circuit handles EOA call (transaction) and internal call.

EVM circuit basically iterate over a list of transactions and verify each transaction's update is applied to state trie. Also each transaction could have serveral recursive internal calls with max depth 1024.

Every time when we encounter a internal call, we switch to a new execution environment. And we switch back to caller when encountering a explicit STOP and REVERT, or any kinds of error.

But it's hard for circuit to memorize all caller's execution state like program_counter, stack_pointer, etc… So we use state circuit to help maintain the consistency of execution state just like the way we maintain stack and memory.

So this note proposes 3 extra targets in state circuit:

1. Tx - Immutable object of tx information shared between all internal calls within same tx.
2. Call - Immutable object of call information (including EOA call's).
3. CallState - Mutable state of call.

where Tx and Call might be loaded in evm circuit directly instead of in state circuit becasue it's immutable.

Structure

Each call has Tx, Call and CallState, we seperate different call by a unique identifier Id.

Tx

Name	Description
Id	sequence id of tx
Origin	address of tx sender (EOA address)
GasPrice	gas price of tx

Call

Name	Description
Id	sequence id of call
TxId	tx's id
Depth	depth of call, should ∈ [0,1024]
GlobalCounterBegin	global counter at the beginning of call
CallerId	caller’s id
CallerAddress	address of caller
CalldataOffset	offset of calldata
CalldataSize	size of calldata
CodeAddress	address of code
ReceiverAddress	address of receiver
GasAvailable	gas given of call
Value	value in wei of call
Result	result of call. A bool success when *CALL*, and address when CREATE*
GlobalCounterEndOfRevert	global counter in the end of revert section, see here for more
IsPersistant	if call's state write will persist (if call is within red box, see here for more)
IsSuccess	if call is success or not
IsStatic	if call is within a static call
IsCreate	if call is a contract creation

CallState

Name	Description
ProgramCounter	program counter
StackPointer	stack pointer
MemeorySize	memory size
GasLeft	gas left
StateWriteCounter	world state write counter
CalleeId	last callee's unique identifier
ReturndataOffset	offset of returndata
ReturndataSize	size of returndata

Call Lifecycle

EVM circuit tracks a flag is_initialization in each slot to specify if it's the beginning of a call. When in the beginning of circuit, any *CALL happens, and any transaction ends, it sets next slot's is_initialization to 1, and also set the id of the next call.

Also EVM circuit tracks call's state like program_counter or stack_pointer from slot to slot. We can definitely maintain these state in state circuit, but it blows up the size of bus mapping because these state almost change every slot. Only when we encounter a *CALL, we write call's state into state circuit to memorize for further resumption. The pseudo code looks like:

# THINK: is_initialization could be call_id != prev.call_id?
is_executing = 1 - is_initialization
is_root = depth == 0
is_internal = not is_root

if is_executing and op in (CALL, STATICCALL, ...):
    # handle op logic...

    # memorize caller program counter
    bus_mapping_lookup(gc++, call_id, CallState, ProgramCounter, pc, Write)
    # memorize caller stack pointer
    bus_mapping_lookup(gc++, call_id, CallState, StackPointer, sp, Write)
    # memorize other stuff...

    # goto next internal call
    assert next.is_initialization is True
    assert next.tx_id == tx_id
    call_lookup(next.call_id, GlobalCounterBegin, gc++)
    # lookup other call information decided by caller

if is_executing and op in (STOP, REVERT): # or any other kinds of error
    # handle op logic...

    if is_internal:
        # resume caller's program counter
        bus_mapping_lookup(gc++, caller_id, CallState, ProgramCounter, next.pc, Read)
        # resume caller's stack pointer
        bus_mapping_lookup(gc++, caller_id, CallState, StackPointer, next.sp, Read)
        # resume caller's other stuff...
        
        # set returndata offset and size for caller
        bus_mapping_lookup(gc++, caller_id, CallState, CalleeId, call_id, Write)
        bus_mapping_lookup(gc++, caller_id, CallState, ReturndataOffset, returndata_offset, Write)
        bus_mapping_lookup(gc++, caller_id, CallState, ReturndataSize, returndata_size, Write)
    else:
        # goto next EOA call (transaction)
        assert next.is_initialization is True
        assert next.tx_id == tx_id + 1
        call_lookup(next.call_id, GlobalCounterBegin, gc++)

if is_initialization:
    if is_root:
        # verify transaction nonce, balance, signature, etc...

    # initialize call's state for next slot
    # if receiver has code and not suicided: dive into the call 
    # else: resume to caller or goto next transaction

The rationale to track some call's state slot by slot instead of in state circuit is due to their high frequency of update. To save volume of bus mapping, we track state like program_counter and stack_pointer which almost change every slot.

Then there are other state we only read them out or update them from bus mapping in specific op. For example, we only read CalleeId, ReturndataOffset, and ReturndataSize when RETURNDATACOPY, and we only increase StateWriteCounter when SSTORE or CALL with value.