<style>table { white-space: nowrap; }</style>

## 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](https://hackmd.io/G48BKqdPScyoFDHPNzgOYQ) for more |
| `IsPersistant` | if call's state write will persist (if call is within red box, see [here](https://hackmd.io/G48BKqdPScyoFDHPNzgOYQ) for more) |
| `IsSuccess` | if call is success or not |
| `IsStatic` | if call is within a static call |
| `IsCreate` | if call is a contract creation |

<!-- IsInternal seems to be redundant if only few things need -->
<!-- | `IsInternal` | if call is a internal call | -->

### `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.