tl;dr<\/abbr><\/h2>\n<\/p>\n
\n- EELS is a reference implementation of an execution layer in Python.<\/li>\n
- It is aligned with the mainnet.<\/li>\n
- It fulfills tests and successfully passes the existing ones.<\/li>\n
- Below is an example of an EIP implemented in EELS.<\/li>\n<\/ul>\n
<\/p>\n
Introduction<\/h2>\n
<\/p>\n
After over a year in development, we are excited to publicly present the Ethereum Execution Layer Specification<\/a> (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<\/a>, it is designed to be more programmer-friendly and up-to-date with post-merge forks; EELS can fill and execute state tests, follow mainnet1<\/a><\/sup>, and serves as an excellent environment to prototype new EIPs.<\/p>\n<\/p>\n
EELS supplies comprehensive snapshots of the protocol at each fork\u2014including forthcoming ones\u2014making it significantly easier to comprehend than EIPs<\/a> (which merely propose alterations) and production clients (which frequently amalgamate several forks in the same codebase.)<\/p>\n<\/p>\n
History<\/h2>\n
<\/p>\n
Initiated in 2021, as an initiative of ConsenSys’ Quilt team together with the Ethereum Foundation, the eth1.0-spec<\/span> (previously known) emerged from the overwhelming challenge of interpreting the esoteric notation of the Yellow Paper (Figure 1<\/a>) to grasp the precise functionality of an EVM instruction.<\/p>\n<\/p>\n\n
\n Figure 1.<\/strong> mystical symbols characterizing the foundation of the blockchain paradigm<\/figcaption><\/figure>\n<\/p>\n
Leveraging the success of the Consensus Layer Specification<\/a>, we aimed to develop a comparable executable specification for the execution layer.<\/p>\n<\/p>\n
Present<\/h2>\n
<\/p>\n
Currently, EELS can be accessed as a standard Python repository<\/a> as well as rendered documentation<\/a>. Although it still has a few rough spots and lacks extensive annotations or English clarifications of various components, improvements will be made over time.<\/p>\n<\/p>\n
It\u2019s merely Python<\/h3>\n
<\/p>\n
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:<\/p>\n
<\/p>\n\n<\/p>\n![\"Less-than](\"https:\/\/storage.googleapis.com\/ethereum-hackmd\/upload_7a45bc80a3438c232dfbf64460c44376.png\")
<\/p>\n
Figure 2.<\/strong> Less-than (LT<\/span>) EVM instruction from Yellow Paper<\/figcaption><\/figure>\n<\/p>\n\n<\/p>\n\ndef<\/span> <\/span>less_than<\/span>(<\/span>evm<\/span>:<\/span> Evm<\/span>)<\/span> <\/span>-<\/span>><\/span> <\/span>None<\/span>:<\/span>\n<\/span> <\/span># STACK<\/span>\n<\/span> left <\/span>=<\/span> pop<\/span>(<\/span>evm<\/span>.<\/span>stack<\/span>)<\/span>\n<\/span> right <\/span>=<\/span> pop<\/span>(<\/span>evm<\/span>.<\/span>stack<\/span>)<\/span>\n<\/span>\n <\/span># GAS<\/span>\n<\/span> charge_gas<\/span>(<\/span>evm<\/span>,<\/span> GAS_VERY_LOW<\/span>)<\/span>\n<\/span>\n <\/span># OPERATION<\/span>\n<\/span> result <\/span>=<\/span> U256<\/span>(<\/span>left <\/span> right<\/span>)<\/span>\n<\/span>\n insert<\/span>(<\/span>evm<\/span>.<\/span>stack<\/span>,<\/span> outcome<\/span>)<\/span>\n<\/span>\n <\/span># PROGRAM COUNTER<\/span>\n<\/span> evm<\/span>.<\/span>pc <\/span>+=<\/span> <\/span>1<\/span>\n<\/span><\/code><\/pre>\n<\/div>\nFigure 3.<\/strong> Less-than (LT<\/span>) EVM directive from EELS<\/figcaption><\/figure>\n<\/p>\n
Although Figure 2<\/a> may be understandable to scholars, Figure 3<\/a> is undoubtedly more intuitive for developers.<\/p>\n<\/p>\n
If you’re interested, here’s a video guide on incorporating a basic EVM instruction<\/a>.<\/p>\n<\/p>\n
Creating Tests<\/h3>\n
<\/p>\n
It’s worth reiterating: EELS is simply standard Python. It can be tested akin to any other Python package! Alongside the complete ethereum\/tests<\/span><\/a> collection, we also offer an array of pytest<\/a> tests.<\/p>\n<\/p>\n
With some assistance from execution-spec-tests<\/span><\/a>, any tests crafted for EELS can also be utilized with production clients!2<\/a><\/sup><\/p>\n<\/p>\n
Displaying Differences<\/h3>\n
<\/p>\n
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:<\/p>\n
<\/p>\n\n<\/p>\n![\"Screenshot](\"https:\/\/storage.googleapis.com\/ethereum-hackmd\/upload_156402252698322ea52892e0a7352ac1.png\")
<\/p>\n
Figure 4.<\/strong> a distinction between homestead and the DAO fork<\/figcaption><\/figure>\n<\/p>\n
A Sample EIP<\/h3>\n
<\/p>\n
EIP-6780<\/a> is the inaugural EIP to receive an EELS implementation<\/a> provided by the creator, Guillaume Ballet<\/a>! Let’s examine it.<\/p>\n<\/p>\n\n<\/p>\n![\"Screenshot](\"https:\/\/storage.googleapis.com\/ethereum-hackmd\/upload_a852d191eb6c78e036d01c7efbed1ac1.png\")
<\/p>\n
Figure 5.<\/strong> EIP-6780’s specification section<\/figcaption><\/figure>\n<\/p>\n
Initially, we introduce a created_contracts<\/span> variable to the EVM with transaction-level visibility:<\/p>\n<\/p>\n
\n <\/span>@dataclass\n<\/span> <\/span>class Environment:\n<\/span> <\/span> caller: Address\n<\/span> <\/span> block_hashes: List[Hash32]\n<\/span> <\/span> origin: Address\n<\/span> <\/span> coinbase: Address\n<\/span> <\/span> number: Uint\n<\/span> <\/span> base_fee_per_gas: Uint\n<\/span> <\/span> gas_limit: Uint\n<\/span> <\/span> gas_price: Uint\n<\/span> <\/span> time: U256\n<\/span> <\/span> prev_randao: Bytes32\n<\/span> <\/span> state: State\n<\/span> <\/span> chain_id: U64\n<\/span>+<\/span> created_contracts: Set[Address]\n<\/span><\/code><\/pre>\n<\/div>\n<\/p>\n
Secondly, we indicate which contracts were formed during each transaction:<\/p>\n
<\/p>\n
\n+<\/span> evm.env.created_contracts.add(contract_address)\n<\/span><\/code><\/pre>\n<\/div>\n<\/p>\n
In conclusion, we alter selfdestruct<\/span> so it solely operates on contracts recorded in created_contracts<\/span>:<\/p>\n<\/p>\n
\n-<\/span> # register account for deletion\n<\/span>-<\/span> evm.accounts_to_delete.add(originator)\n<\/span>-<\/span>\n<\/span>+<\/span> # Only proceed if the contract has been created in the same tx\n<\/span>+<\/span> if originator in evm.env.created_contracts:\n<\/span>+<\/span>\n<\/span>+<\/span> # register account for deletion\n<\/span>+<\/span> evm.accounts_to_delete.add(originator)\n<\/span>+<\/span>\n<\/span><\/code><\/pre>\n<\/div>\n<\/p>\n
Future<\/h2>\n
<\/p>\n
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.<\/p>\n
<\/p>\n
If you are keen on contributing or prototyping your EIP, join us in the #specifications<\/a> channel or take an issue from our repository<\/a>.<\/p>\n<\/div>\n
<\/p>\n
Introduction<\/h2>\n
<\/p>\n
After over a year in development, we are excited to publicly present the Ethereum Execution Layer Specification<\/a> (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<\/a>, it is designed to be more programmer-friendly and up-to-date with post-merge forks; EELS can fill and execute state tests, follow mainnet1<\/a><\/sup>, and serves as an excellent environment to prototype new EIPs.<\/p>\n <\/p>\n EELS supplies comprehensive snapshots of the protocol at each fork\u2014including forthcoming ones\u2014making it significantly easier to comprehend than EIPs<\/a> (which merely propose alterations) and production clients (which frequently amalgamate several forks in the same codebase.)<\/p>\n <\/p>\n <\/p>\n Initiated in 2021, as an initiative of ConsenSys’ Quilt team together with the Ethereum Foundation, the eth1.0-spec<\/span> (previously known) emerged from the overwhelming challenge of interpreting the esoteric notation of the Yellow Paper (Figure 1<\/a>) to grasp the precise functionality of an EVM instruction.<\/p>\n <\/p>\n <\/p>\n Leveraging the success of the Consensus Layer Specification<\/a>, we aimed to develop a comparable executable specification for the execution layer.<\/p>\n <\/p>\n <\/p>\n Currently, EELS can be accessed as a standard Python repository<\/a> as well as rendered documentation<\/a>. Although it still has a few rough spots and lacks extensive annotations or English clarifications of various components, improvements will be made over time.<\/p>\n <\/p>\n <\/p>\n 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:<\/p>\n <\/p>\n <\/p>\n <\/p>\n Although Figure 2<\/a> may be understandable to scholars, Figure 3<\/a> is undoubtedly more intuitive for developers.<\/p>\n <\/p>\n If you’re interested, here’s a video guide on incorporating a basic EVM instruction<\/a>.<\/p>\n <\/p>\n <\/p>\n It’s worth reiterating: EELS is simply standard Python. It can be tested akin to any other Python package! Alongside the complete ethereum\/tests<\/span><\/a> collection, we also offer an array of pytest<\/a> tests.<\/p>\n <\/p>\n With some assistance from execution-spec-tests<\/span><\/a>, any tests crafted for EELS can also be utilized with production clients!2<\/a><\/sup><\/p>\n <\/p>\n <\/p>\n 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:<\/p>\n <\/p>\n <\/p>\n <\/p>\n EIP-6780<\/a> is the inaugural EIP to receive an EELS implementation<\/a> provided by the creator, Guillaume Ballet<\/a>! Let’s examine it.<\/p>\n <\/p>\n <\/p>\n Initially, we introduce a created_contracts<\/span> variable to the EVM with transaction-level visibility:<\/p>\n <\/p>\n <\/p>\n Secondly, we indicate which contracts were formed during each transaction:<\/p>\n <\/p>\n <\/p>\n In conclusion, we alter selfdestruct<\/span> so it solely operates on contracts recorded in created_contracts<\/span>:<\/p>\n <\/p>\n <\/p>\n <\/p>\n 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.<\/p>\n <\/p>\n If you are keen on contributing or prototyping your EIP, join us in the #specifications<\/a> channel or take an issue from our repository<\/a>.<\/p>\n <\/div>\nHistory<\/h2>\n
\n Present<\/h2>\n
It\u2019s merely Python<\/h3>\n
<\/p>\ndef<\/span> <\/span>less_than<\/span>(<\/span>evm<\/span>:<\/span> Evm<\/span>)<\/span> <\/span>-<\/span>><\/span> <\/span>None<\/span>:<\/span>\n<\/span> <\/span># STACK<\/span>\n<\/span> left <\/span>=<\/span> pop<\/span>(<\/span>evm<\/span>.<\/span>stack<\/span>)<\/span>\n<\/span> right <\/span>=<\/span> pop<\/span>(<\/span>evm<\/span>.<\/span>stack<\/span>)<\/span>\n<\/span>\n <\/span># GAS<\/span>\n<\/span> charge_gas<\/span>(<\/span>evm<\/span>,<\/span> GAS_VERY_LOW<\/span>)<\/span>\n<\/span>\n <\/span># OPERATION<\/span>\n<\/span> result <\/span>=<\/span> U256<\/span>(<\/span>left <\/span> right<\/span>)<\/span>\n<\/span>\n insert<\/span>(<\/span>evm<\/span>.<\/span>stack<\/span>,<\/span> outcome<\/span>)<\/span>\n<\/span>\n <\/span># PROGRAM COUNTER<\/span>\n<\/span> evm<\/span>.<\/span>pc <\/span>+=<\/span> <\/span>1<\/span>\n<\/span><\/code><\/pre>\n<\/div>\nCreating Tests<\/h3>\n
Displaying Differences<\/h3>\n
<\/p>\nA Sample EIP<\/h3>\n
<\/p>\n <\/span>@dataclass\n<\/span> <\/span>class Environment:\n<\/span> <\/span> caller: Address\n<\/span> <\/span> block_hashes: List[Hash32]\n<\/span> <\/span> origin: Address\n<\/span> <\/span> coinbase: Address\n<\/span> <\/span> number: Uint\n<\/span> <\/span> base_fee_per_gas: Uint\n<\/span> <\/span> gas_limit: Uint\n<\/span> <\/span> gas_price: Uint\n<\/span> <\/span> time: U256\n<\/span> <\/span> prev_randao: Bytes32\n<\/span> <\/span> state: State\n<\/span> <\/span> chain_id: U64\n<\/span>+<\/span> created_contracts: Set[Address]\n<\/span><\/code><\/pre>\n<\/div>\n+<\/span> evm.env.created_contracts.add(contract_address)\n<\/span><\/code><\/pre>\n<\/div>\n-<\/span> # register account for deletion\n<\/span>-<\/span> evm.accounts_to_delete.add(originator)\n<\/span>-<\/span>\n<\/span>+<\/span> # Only proceed if the contract has been created in the same tx\n<\/span>+<\/span> if originator in evm.env.created_contracts:\n<\/span>+<\/span>\n<\/span>+<\/span> # register account for deletion\n<\/span>+<\/span> evm.accounts_to_delete.add(originator)\n<\/span>+<\/span>\n<\/span><\/code><\/pre>\n<\/div>\nFuture<\/h2>\n