Technical Architecture of the EVM Emulator

The EVM Bytecode Emulator is implemented as a system contract that interprets and executes EVM bytecode at runtime within the EraVM environment. While EVM execution is fully contained within the emulator, it interacts with multiple system contracts to ensure correct behavior.

The main invariant that emulation aims to preserve: behavior inside emulated EVM environment (i.e. not only within one contract, but during any sort of EVM <> EVM contracts interaction chain) is the same as it would’ve been on widespread EVM implementation (i.e. Geth).

For an overview of how to deploy and execute EVM contracts, refer to EVM Bytecode Deployment and Execution. For an overview of how EVM gas model is emulated, see EVM gas emulation. This page focuses on the internal mechanics of the emulator, including gas management, context and data handling.

Execution Model

When an EVM contract is called, the following steps occur:

1. Versioned Bytecode Hash Check
   • The system retrieves the contract’s versioned hash from AccountCodeStorage.
   • If the version is 0x02 (EVM contract), execution is routed through the EVM Emulator.
2. Bytecode Interpretation
   • The emulator loads the contract’s EVM bytecode.
   • It initializes execution context (EVM stack, memory, execution frames context).
   • The emulator derives available amount of EVM gas from passed EraVM native gas (ergs).
   • The emulator interprets and executes opcodes in a loop. Every opcode consumes emulated EVM gas. Emulation itself consumes native EraVM gas (ergs).
   • Execution continues until completion, error, or out-of-ergs condition.
3. External Calls
   • If external call to another EVM contract is requested, EVM emulator pushes new frame in EvmGasManager and invokes new instance of the EVM emulator for that contract.
   • If external call to EraVM contract is requested, EVM emulator calls that contract directly (EraVM gas is derived from passed EVM gas). When that call returns or fails, EVM emulator continues execution normally. Delegatecall to EraVM contracts is forbidden.
4. Returning from EVM context
   • If execution finalizes according to EVM rules, returndata may be passed to the caller (EraVM and EVM callers).
   • If execution fails unexpectedly for EVM (Internal revert on EraVM level, OUT-OF-ERGS), the entire EVM call stack reverts. This guarantees that EVM execution can be emulated fully by EVM rules or reverted completely.

Static calls

The static context is set off by EraVM for calls to EVM contracts. Emulator gets info whether context should static or non-static from internal call flags. This is needed because EvmGasManager need to perform writes to transient storage to emulate cold/warm access mechanics for accounts and storage slots.

EVM emulator guarantees that no state changes can occur if static context is requested. Additionally it forbids non-static calls from static environment.

Gas And Call Frames Management

The EvmGasManager system contract is responsible for:

• Tracking warm/cold storage and accounts accesses.
• Managing EVM call frames.

This contract is used to temporarily store contextual information needed to emulate the EVM environment.

See EVM Bytecode Deployment and Execution for a high-level explanation.

Warm/Cold Storage Logic

• First-time accesses are cold (higher cost).
• Subsequent accesses within the same transaction are warm (lower cost).
• Warm/cold tracking is stored in transient storage and resets per transaction.

By default, the following addresses are considered hot:

• Called EVM contract
• msg.sender (caller of the EVM contract)
• tx.origin
• coinbase
• precompiles

EVM Call Frames Management

If an EVM contract calls another EVM contract, info about EVM gas is passed using entries in call frames stack. Additionally entries keep static context flag if staticcall used.

Context parameters

While most of the context parameters (this/msg.sender/msg.value, etc) are reused as is from EraVM, some are explicitly maintained by the EvmEmulator:

• gas (as EVM gas model is emulated for compatibility with Ethereum smart contracts).
• If context is static or not (more on it in the section about static context).
• The info about warm/cold slots and addresses is maintained by the EvmGasManager system contract.

Calldata & returndata internals

EraVM contracts are agnostic about EVM emulation (and vice versa). When an EraVM contract calls an EVM contract, it passes the calldata as-is, and similarly, when an EVM contract returns data to an EraVM contract, the returndata is also returned "as-is" without modification.

When one EVM contract calls another, it also passes the calldata as-is. Additional context data like gas and isStatic flag managed by the EvmGasManager.

However, internal returndata logic is more complex. When an EVM contract returns data to another EVM contract, a tuple of (gas_left, returndata) is returned under the hood. This is needed to pass info about remaining EVM gas between EVM execution frames.

The EVM emulator internally performs technical calls to system contracts. Information about returndata from the last emulated call is stored in reserved pointer and does not change after these additional technical calls.

Contract Deployment Process

For a high-level overview of EVM contract deployment, see EVM Bytecode Deployment and Execution.

Internally, deployment of an EVM contract from another EVM contract follows these steps:

1. The emulator calls precreateEvmAccountFromEmulator in ContractDeployer for address derivation, increment of nonce and checks.
2. A temporary bytecode hash is assigned to mark the contract as an EVM contract.
3. The emulator executes in constructor mode by interpreting the passed calldata as initcode.
4. The final contract bytecode is returned by the emulator and stored.

Summary of system contracts

Deeper details

For more details, please refer to the system contract implementations and technical documentation in the era-contracts repository.

Next Steps

• Learn about EraVM ↔ EVM contract interactions.
• Review differences from Ethereum (Cancun).
• Explore the list of pre deployed contracts.
• Check how EVM gas emulation works.