Ethereum Execution Layer Specification

tl;dr

• EELS is an execution layer reference implementation in Python.
• It's up to date with mainnet.
• It fills tests, and passes existing ones.
• There's an example of an EIP implemented in EELS below.

Introduction

After more than a year in development, we're pleased to publicly introduce the Ethereum Execution Layer Specification (affectionately known as EELS.) EELS is a Python reference implementation of the core components of an Ethereum execution client focused on readability and clarity. Intended as a spiritual successor to the Yellow Paper that's more programmer friendly and up-to-date with post-merge forks, EELS can fill and execute state tests, follow mainnet¹, and is a great place to prototype new EIPs.

EELS provides complete snapshots of the protocol at each fork—including upcoming ones—making it much easier to follow than EIPs (which only propose changes) and production clients (which often mix multiple forks in the same codepath.)

History

Beginning in 2021, as a project of ConsenSys' Quilt team and the Ethereum Foundation, the eth1.0-spec (as it was known then) was inspired by the sheer frustration of having to decipher the cryptic notation of the Yellow Paper (Figure 1) to understand the specific behavior of an EVM instruction.

Drawing on the successful Consensus Layer Specification, we set out to create a similar executable specification for the execution layer.

Present

Today, EELS is consumable as a traditional Python repository and as rendered documentation. It's still a bit rough around the edges, and doesn't provide much in the way of annotations or English explanations for what various pieces do, but those will come with time.

It's just Python

Hopefully a side-by-side comparison of the Yellow Paper and the equivalent code from EELS can show why EELS is a valuable complement to it:

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 might be digestible to academics, Figure 3 is indisputably more natural to programmers.

Here's a video walk-through of adding a simple EVM instruction if that's your kind of thing.

Writing Tests

It bears repeating: EELS is just regular Python. It can be tested like any other Python library! In addition to the entire ethereum/tests suite, we also have a selection of pytest tests.

With a little help from execution-spec-tests, any tests written for EELS can also be applied to production clients!²

Showing Differences

Having snapshots at each fork is great for a smart contract developer popping in to see the specifics of how an EVM instruction works, but isn't very helpful for client developers themselves. For them, EELS can display the differences between forks:

An Example EIP

EIP-6780 is the first EIP to get an EELS implementation provided by the author, Guillaume Ballet! Let's take a look.

First, we introduce a created_contracts variable 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]

Second, we note which contracts were created in each transaction:

+    evm.env.created_contracts.add(contract_address)

Finally, we modify selfdestruct so it only works 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

We want EELS to become the default way to specify Core EIPs, the first place EIP authors go to prototype their proposals, and the best possible reference for how Ethereum works.

If you're interested in contributing or prototyping your EIP, join us on the #specifications channel or grab an issue from our repository.