tl;dr
- EELS serves as a reference implementation for the execution layer in Python.
- It is synchronized with the current mainnet status.
- It successfully passes all existing tests, and includes tests of its own.
- An example of an implemented EIP can be found in EELS below.
Introduction
After over a year of development, we are excited to publicly unveil the
Ethereum Execution Layer Specification (endearingly referred to as EELS).
EELS is a reference implementation written in Python that emphasizes readability and clarity for core Ethereum execution client components. It is designed to be a more programmer-friendly version and an updated reference compared to the
Yellow Paper, accommodating the latest post-merge updates. EELS can execute state tests, validate the mainnet1, and serves as an excellent platform for prototyping new EIPs.
EELS offers complete protocol snapshots with each fork—including future ones—making it significantly easier to understand than
EIPs (which merely propose changes) and production clients (which often combine code paths across multiple forks).
History
Initiated in 2021 by ConsenSys’ Quilt team in collaboration with the Ethereum Foundation, the
eth1.0-spec (as it was known at that time) arose from the frustration of interpreting the complex notation found in the Yellow Paper (Figure 1) to grasp the exact behavior of various EVM instructions.
Leveraging the success of the
Consensus Layer Specification, we aimed to develop a similar executable specification specifically for the execution layer.
Present
Currently, EELS can be accessed as a
standard Python repository and also as documented materials. It remains a work in progress, still somewhat unrefined, lacking detailed annotations or thorough explanations of components, but enhancements are on the horizon.
It’s just Python
A comparative analysis of the Yellow Paper alongside EELS’s equivalent code might clarify the value that EELS adds:
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)
push(evm.stack, result)
# PROGRAM COUNTER
evm.pc += 1
While Figure 2 may make sense to academics, Figure 3 is undeniably more intuitive for programmers.
Here’s a video
demonstrating the addition of a simple EVM instruction if that interests you.
Writing Tests
It’s important to emphasize that EELS is simply standard Python. It can be tested like any other Python library! Alongside the comprehensive
ethereum/tests suite, we have incorporated a series of
pytest tests.
With assistance from
execution-spec-tests, any tests created for EELS are also applicable to production clients!2
Showing Differences
Having snapshots for every fork is beneficial for smart contract developers seeking insights into EVM instruction specifics, but it doesn’t greatly assist client developers themselves. For that reason, EELS can highlight the distinctions between forks:
An Example EIP
EIP-6780 represents the first EIP to receive
an EELS implementation from its author,
Guillaume Ballet! Let’s examine it.
Initially, we introduce a
created_contracts variable into the EVM, scoped to transactions:
@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]
Next, we identify the contracts created during each transaction:
+
evm.env.created_contracts.add(contract_address)
Lastly, we adjust
selfdestruct to restrict it only to contracts recorded in
created_contracts:
-
# register account for deletion
-
evm.accounts_to_delete.add(originator)
-
+
# Only allow if the contract was created during the same TX
+
if originator in evm.env.created_contracts:
+
# register account for deletion
+
evm.accounts_to_delete.add(originator)
Future
We aspire for EELS to establish itself as the primary tool for specifying Core EIPs, the go-to platform for EIP authors to bring their proposals to life, and the most comprehensive reference for understanding Ethereum.
If you’re interested in contributing or prototyping your own EIP, feel free to join us on the
#specifications channel or take on an issue from our
repository.
