Inclusion Lists PoC Specification

# Inclusion Lists PoC Specification <img src=https://storage.googleapis.com/ethereum-hackmd/upload_c173120b579569424400977177a02414.png width=69%> $\cdot$ > **Purpose:** *describe and reference the consensus, execution, & engine API specification for the Inclusion Lists Proof-of-Concept. See [EIP-7547 related work](https://gist.github.com/michaelneuder/ba32e608c75d48719a7ecba29ec3d64b) for context.* *Disclaimer: this is only the specification for the PoC; the final spec could differ significantly.* $\cdot$ ### Links | repo | draft pr link | | -- | -- | | consensus-specs | https://github.com/ethereum/consensus-specs/pull/3617 | | execution-apis | https://github.com/michaelneuder/execution-apis/pull/1 | | execution-specs | https://github.com/michaelneuder/execution-specs/pull/1 | ### Core elements 1. Unconditional – guaranteed inclusion with a 3 million gas limit on the IL. 2. Anywhere in block – the transactions in the `slot N` IL must appear anywhere in either the `slot N` or `slot N+1` payloads. 3. IL not committed to in beacon block – the `slot N` beacon block has no reference to the `slot N` IL summary. 4. Unbundled gossip – the IL is an independent P2P topic. ### Details For the key files: `beacon-chain.md`, `fork-choice.md`, `p2p-networking.md`, & `validator.md`, we present extended details to highlight the critical changes. #### `beacon-chain.md` **Overview:** *Add the inclusion list data to the execution layer block, the state transition, and the block processing.* **Itemized:** - Define a constant domain for IL signature verification. - Create a constant for size of IL: `MAX_TRANSACTIONS_PER_INCLUSION_LIST` - Create new containers. - `InclusionListSummaryEntry` - `InclusionListSummary` - `SignedInclusionListSummary` - `InclusionList` - Extended containers. - `ExecutionPayload` - `ExecutionPayloadHeader` - `BeaconState` - State transition - Define `NewInclusionListRequest` for engine API - Define new engine API to be called upon receipt of a new IL: `verify_and_notify_new_inclusion_list`. - Block processing - Update `process_execution_payload` to verify signature over IL. - Define `verify_inclusion_list_summary_signature` as helper. #### `fork-choice.md` **Overview:** *Add inclusion list verification handling.* **Itemized:** - Add `on_inclusion_list` handler to be called upon receipt of a new inclusion list. It updates the store if the IL is valid. - Add helper function to check for availability of IL: `is_inclusion_list_available`. #### `p2p-networking.md` **Overview:** *Create the inclusion list topic for the p2p network.* **Itemized:** - Add `SignedInclusionList` object which is an envelope for the full IL. - Add the `inclusion_list` topic and associated validation rules. #### `validator.md` **Overview:** *Define the new validator behavior and engine APIs for fetching and validating inclusion lists from the EL.* **Itemized:** - Define `engine_getInclusionListV1` engine API interface, which requests a new IL constructed by the EL and returns a `SignedInclusionList`. - Beacon chain responsibilities - Add condition to validate inclusion lists before rebroadcasting them. - Add condition to block validation to ensure there exists an available inclusion list. - Add condition for honest block production that ensures a signed IL is published. ### Execution API – [link to draft PR](https://github.com/michaelneuder/execution-apis/pull/1) **Overview:** Engine API changes to reflect new types and contain IL data. **Itemized:** - Define `INCLUSION_LIST_MAX_GAS` constant. - Structures - `InclusionListSummaryEntryV1` - `InclusionListSummaryV1` - `InclusionListStatusV1` - Methods - `engine_newInclusionListV1` (new API) - CL requests the validation of an inclusion list from the EL. - `engine_getInclusionListV1` (new API) - CL requests the construction of an inclusion list from the EL. The sequence diagram below shows the block production flow, using each of the above APIs. <img src=https://storage.googleapis.com/ethereum-hackmd/upload_f1c1c3a778842163bf65b543bf819fe6.png width=69%> ### Execution specs – [link to draft PR](https://github.com/michaelneuder/execution-specs/pull/1) **Overview:** Update `state_transition` and `apply_body` to make IL checks part of block validation. **Itemized:** - `fork_types.py` - Create `InclusionListSummaryEntry` and `InclusionListSummary` - Add inclusion list fields to both the `Header` (`ExecutionPayloadHeader` in the CL spec) and `Block` (`ExecutionPayload` in the CL spec) types. - Update `state_transition` to pass the IL summary to `apply_body`. - Update `apply_body` (called from `state_transition`) to calculate the added gas from the inclusion list and assert that the inclusion list entries are satisfied.