Unveiling the Ethereum Execution Layer: A Comprehensive Guide

tl;dr

• EELS is a reference implementation of an execution layer in Python.
• It is aligned with the mainnet.
• It fulfills tests and successfully passes the existing ones.
• Below is an example of an EIP implemented in EELS.

Introduction

After over a year in development, we are excited to publicly present the Ethereum Execution Layer Specification (affectionately referred to as EELS.) EELS serves as a reference implementation in Python for the essential elements of an Ethereum execution client, emphasizing clarity and readability. As a spiritual successor to the Yellow Paper, it is designed to be more programmer-friendly and up-to-date with post-merge forks; EELS can fill and execute state tests, follow mainnet¹, and serves as an excellent environment to prototype new EIPs.

EELS supplies comprehensive snapshots of the protocol at each fork—including forthcoming ones—making it significantly easier to comprehend than EIPs (which merely propose alterations) and production clients (which frequently amalgamate several forks in the same codebase.)

History

Initiated in 2021, as an initiative of ConsenSys’ Quilt team together with the Ethereum Foundation, the eth1.0-spec (previously known) emerged from the overwhelming challenge of interpreting the esoteric notation of the Yellow Paper (Figure 1) to grasp the precise functionality of an EVM instruction.

Leveraging the success of the Consensus Layer Specification, we aimed to develop a comparable executable specification for the execution layer.

Present

Currently, EELS can be accessed as a standard Python repository as well as rendered documentation. Although it still has a few rough spots and lacks extensive annotations or English clarifications of various components, improvements will be made over time.

It’s merely Python

A side-by-side comparison of the Yellow Paper and the corresponding code from EELS is likely to illustrate why EELS serves as a beneficial complement:

def less_than(evm: Evm) -> None:
    # STACK
    left = pop(evm.stack)
    right = pop(evm.stack)

    # GAS
    charge_gas(evm, GAS_VERY_LOW)

    # OPERATION
    result = U256(left  right)

    insert(evm.stack, outcome)

    # PROGRAM COUNTER
    evm.pc += 1

Although Figure 2 may be understandable to scholars, Figure 3 is undoubtedly more intuitive for developers.

If you’re interested, here’s a video guide on incorporating a basic EVM instruction.

Creating Tests

It’s worth reiterating: EELS is simply standard Python. It can be tested akin to any other Python package! Alongside the complete ethereum/tests collection, we also offer an array of pytest tests.

With some assistance from execution-spec-tests, any tests crafted for EELS can also be utilized with production clients!²

Displaying Differences

Having snapshots at each fork is beneficial for a smart contract developer examining the particulars of how an EVM instruction operates, but it isn’t very helpful for the developers of clients themselves. For them, EELS can reveal the discrepancies among forks:

A Sample EIP

EIP-6780 is the inaugural EIP to receive an EELS implementation provided by the creator, Guillaume Ballet! Let’s examine it.

Initially, we introduce a created_contracts variable to the EVM with transaction-level visibility:

 @dataclass
 class Environment:
     caller: Address
     block_hashes: List[Hash32]
     origin: Address
     coinbase: Address
     number: Uint
     base_fee_per_gas: Uint
     gas_limit: Uint
     gas_price: Uint
     time: U256
     prev_randao: Bytes32
     state: State
     chain_id: U64
+    created_contracts: Set[Address]

Secondly, we indicate which contracts were formed during each transaction:

+    evm.env.created_contracts.add(contract_address)

In conclusion, we alter selfdestruct so it solely operates on contracts recorded in created_contracts:

-    # register account for deletion
-    evm.accounts_to_delete.add(originator)
-
+    # Only proceed if the contract has been created in the same tx
+    if originator in evm.env.created_contracts:
+
+        # register account for deletion
+        evm.accounts_to_delete.add(originator)
+

Future

Our goal is for EELS to become the standard method for defining Core EIPs, the primary resource for EIP authors to prototype their proposals, and the ultimate guide on how Ethereum functions.

If you are keen on contributing or prototyping your EIP, join us in the #specifications channel or take an issue from our repository.