September 21, 2023
- EELS is an execution layer reference implementation in Python.
- It’s up-to-date with the Ethereum mainnet.
- It can fill and pass existing tests.
- An example of an EIP implemented in EELS is provided below.
Introduction
After more than a year of development, the Ethereum Foundation introduces the Ethereum Execution Layer Specification (EELS). EELS is a Python-based reference implementation of the core components of an Ethereum execution client. It prioritizes readability and clarity, serving as an approachable alternative to the Yellow Paper while also being more current with post-merge forks. EELS can fill and execute state tests, follow the mainnet, and is an excellent environment for prototyping new Ethereum Improvement Proposals (EIPs).
EELS provides complete snapshots of the Ethereum protocol at each fork, including upcoming ones, making it easier to understand than EIPs (which propose changes) and production clients (which often mix multiple forks in the same codebase).
History
The project began in 2021 as a collaboration between ConsenSys’ Quilt team and the Ethereum Foundation. Originally known as “eth1.0-spec,” it was inspired by the challenges of deciphering the complex notation of the Yellow Paper to understand specific EVM instruction behavior.
By drawing on the success of the Consensus Layer Specification, the goal was to create an executable specification for the execution layer.
Present
Today, EELS is available as a traditional Python repository and as rendered documentation. While it’s still a work in progress, annotations and detailed explanations will be added over time.
Comparison
To illustrate the value of EELS, let’s compare the Yellow Paper and its equivalent code from EELS using the Less-than (LT) opcode.
In Figure 2, the LT instruction from the Yellow Paper may be understood by academics, but the corresponding code in EELS (Figure 3) is more straightforward for programmers.
For a video walkthrough of adding a simple EVM instruction, click here.
Writing Tests
EELS is just regular Python, so it can be tested like any other Python library. Besides the entire ethereum/tests suite, there is also a selection of pytest tests. Thanks to execution-spec-tests, tests written for EELS can also be applied to production clients.
Displaying Differences
EELS’s snapshots at each fork are useful for smart contract developers looking for specifics on EVM instruction behavior. For client developers, EELS can highlight differences between forks, making comparisons and transitions clearer.
Example EIP
EIP-6780, authored by Guillaume Ballet, is the first EIP to receive an EELS implementation. The provided code demonstrates the specification section for this EIP.
First, a new variable, created_contracts, is added to the EVM with transaction-level scope:
@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]Then, contracts created in each transaction are noted:
+ evm.env.created_contracts.add(contract_address)Finally, the selfdestruct function is modified to only work for contracts noted in created_contracts:
- # register account for deletion
- evm.accounts_to_delete.add(originator)
-
+ # Only continue 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
EELS aims to become the standard for specifying Core EIPs, the first choice for prototyping EIPs, and the best reference for understanding how Ethereum works.
If you’re interested in contributing or prototyping your EIP, join the #specifications channel or pick up an issue from the repository.