eip7928: introduce specs for block access lists

Makefile

@@ -13,7 +13,8 @@ ALL_EXECUTABLE_SPEC_NAMES = \
 	gloas     \
 	eip6800   \
 	eip7441   \
-	eip7805
+	eip7805   \
+	eip7928
 
 # A list of fake targets.
 .PHONY: \

pysetup/constants.py

@@ -10,6 +10,7 @@
 EIP6800 = "eip6800"
 EIP7441 = "eip7441"
 EIP7805 = "eip7805"
+EIP7928 = "eip7928"
 
 
 # The helper functions that are used when defining constants

pysetup/md_doc_paths.py

@@ -8,6 +8,7 @@
     EIP6800,
     EIP7441,
     EIP7805,
+    EIP7928,
     ELECTRA,
     FULU,
     GLOAS,
@@ -26,6 +27,7 @@
     EIP6800: DENEB,
     EIP7441: CAPELLA,
     EIP7805: FULU,
+    EIP7928: ELECTRA,
 }
 
 ALL_FORKS = list(PREVIOUS_FORK_OF.keys())

pysetup/spec_builders/__init__.py

@@ -5,6 +5,7 @@
 from .eip6800 import EIP6800SpecBuilder
 from .eip7441 import EIP7441SpecBuilder
 from .eip7805 import EIP7805SpecBuilder
+from .eip7928 import EIP7928SpecBuilder
 from .electra import ElectraSpecBuilder
 from .fulu import FuluSpecBuilder
 from .gloas import GloasSpecBuilder
@@ -24,5 +25,6 @@
         EIP6800SpecBuilder,
         EIP7441SpecBuilder,
         EIP7805SpecBuilder,
+        EIP7928SpecBuilder,
     )
 }

pysetup/spec_builders/eip7928.py

@@ -0,0 +1,12 @@
+from ..constants import EIP7928
+from .base import BaseSpecBuilder
+
+
+class EIP7928SpecBuilder(BaseSpecBuilder):
+    fork: str = EIP7928
+
+    @classmethod
+    def imports(cls, preset_name: str):
+        return f"""
+from eth2spec.electra import {preset_name} as electra
+"""

specs/_features/eip7928/beacon-chain.md

@@ -0,0 +1,144 @@
+# EIP-7928 -- The Beacon Chain
+
+*Note*: This document is a work-in-progress for researchers and implementers.
+
+<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
+
+- [Introduction](#introduction)
+- [Custom types](#custom-types)
+- [Extended Containers](#extended-containers)
+  - [`ExecutionPayload`](#executionpayload)
+  - [`ExecutionPayloadHeader`](#executionpayloadheader)
+  - [`NewPayloadRequest`](#newpayloadrequest)
+- [Beacon chain state transition function](#beacon-chain-state-transition-function)
+  - [Block processing](#block-processing)
+    - [Execution payload](#execution-payload)
+      - [Modified `process_execution_payload`](#modified-process_execution_payload)
+
+<!-- mdformat-toc end -->
+
+## Introduction
+
+*Note*: This specification is built upon
+[Electra](../../electra/beacon-chain.md) and is under active development.
+
+## Custom types
+
+| Name              | SSZ equivalent                        | Description                   |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| `BlockAccessList` | `ByteList[MAX_BYTES_PER_TRANSACTION]` | RLP encoded block access list |
+
+## Extended Containers
+
+### `ExecutionPayload`
+
+```python
+class ExecutionPayload(Container):
+    parent_hash: Hash32
+    fee_recipient: ExecutionAddress
+    state_root: Bytes32
+    receipts_root: Bytes32
+    logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
+    prev_randao: Bytes32
+    block_number: uint64
+    gas_limit: uint64
+    gas_used: uint64
+    timestamp: uint64
+    extra_data: ByteList[MAX_EXTRA_DATA_BYTES]
+    base_fee_per_gas: uint256
+    block_hash: Hash32
+    transactions: List[Transaction, MAX_TRANSACTIONS_PER_PAYLOAD]
+    withdrawals: List[Withdrawal, MAX_WITHDRAWALS_PER_PAYLOAD]
+    blob_gas_used: uint64
+    excess_blob_gas: uint64
+    # [New in EIP7928]
+    block_access_list: BlockAccessList
+```
+
+### `ExecutionPayloadHeader`
+
+```python
+class ExecutionPayloadHeader(Container):
+    parent_hash: Hash32
+    fee_recipient: ExecutionAddress
+    state_root: Bytes32
+    receipts_root: Bytes32
+    logs_bloom: ByteVector[BYTES_PER_LOGS_BLOOM]
+    prev_randao: Bytes32
+    block_number: uint64
+    gas_limit: uint64
+    gas_used: uint64
+    timestamp: uint64
+    extra_data: ByteList[MAX_EXTRA_DATA_BYTES]
+    base_fee_per_gas: uint256
+    block_hash: Hash32
+    transactions_root: Root
+    withdrawals_root: Root
+    blob_gas_used: uint64
+    excess_blob_gas: uint64
+    # [New in EIP7928]
+    block_access_list_root: Root
+```
+
+### `NewPayloadRequest`
+
+*Note*: The `NewPayloadRequest` remains unchanged. The `block_access_list` is
+passed as part of the `execution_payload`.
+
+## Beacon chain state transition function
+
+### Block processing
+
+#### Execution payload
+
+##### Modified `process_execution_payload`
+
+```python
+def process_execution_payload(
+    state: BeaconState, body: BeaconBlockBody, execution_engine: ExecutionEngine
+) -> None:
+    payload = body.execution_payload
+
+    # Verify consistency of the parent hash with respect to the previous execution payload header
+    assert payload.parent_hash == state.latest_execution_payload_header.block_hash
+    # Verify prev_randao
+    assert payload.prev_randao == get_randao_mix(state, get_current_epoch(state))
+    # Verify timestamp
+    assert payload.timestamp == compute_time_at_slot(state, state.slot)
+    # Verify commitments are under limit
+    assert len(body.blob_kzg_commitments) <= MAX_BLOB_COMMITMENTS_PER_BLOCK
+    # Verify the execution payload is valid
+    versioned_hashes = [
+        kzg_commitment_to_versioned_hash(commitment) for commitment in body.blob_kzg_commitments
+    ]
+    assert execution_engine.verify_and_notify_new_payload(
+        NewPayloadRequest(
+            execution_payload=payload,
+            versioned_hashes=versioned_hashes,
+            parent_beacon_block_root=state.latest_block_header.parent_root,
+            execution_requests=body.execution_requests,
+        )
+    )
+    # Cache execution payload header
+    state.latest_execution_payload_header = ExecutionPayloadHeader(
+        parent_hash=payload.parent_hash,
+        fee_recipient=payload.fee_recipient,
+        state_root=payload.state_root,
+        receipts_root=payload.receipts_root,
+        logs_bloom=payload.logs_bloom,
+        prev_randao=payload.prev_randao,
+        block_number=payload.block_number,
+        gas_limit=payload.gas_limit,
+        gas_used=payload.gas_used,
+        timestamp=payload.timestamp,
+        extra_data=payload.extra_data,
+        base_fee_per_gas=payload.base_fee_per_gas,
+        block_hash=payload.block_hash,
+        transactions_root=hash_tree_root(payload.transactions),
+        withdrawals_root=hash_tree_root(payload.withdrawals),
+        blob_gas_used=payload.blob_gas_used,
+        excess_blob_gas=payload.excess_blob_gas,
+        # [New in EIP7928]
+        block_access_list_root=hash_tree_root(payload.block_access_list),
+    )
+```

specs/_features/eip7928/fork.md

@@ -0,0 +1,138 @@
+# EIP-7928 -- Fork Logic
+
+*Note*: This document is a work-in-progress for researchers and implementers.
+
+<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
+
+- [Introduction](#introduction)
+- [Configuration](#configuration)
+- [Helper functions](#helper-functions)
+  - [Misc](#misc)
+    - [Modified `compute_fork_version`](#modified-compute_fork_version)
+- [Fork to EIP-7928](#fork-to-eip-7928)
+  - [Fork trigger](#fork-trigger)
+  - [Upgrading the state](#upgrading-the-state)
+
+<!-- mdformat-toc end -->
+
+## Introduction
+
+This document describes the process of the EIP-7928 upgrade.
+
+## Configuration
+
+Warning: this configuration is not definitive.
+
+| Name                   | Value                                 |
+| ---------------------- | ------------------------------------- |
+| `EIP7928_FORK_VERSION` | `Version('0x09000000')`               |
+| `EIP7928_FORK_EPOCH`   | `Epoch(18446744073709551615)` **TBD** |
+
+## Helper functions
+
+### Misc
+
+#### Modified `compute_fork_version`
+
+```python
+def compute_fork_version(epoch: Epoch) -> Version:
+    """
+    Return the fork version at the given ``epoch``.
+    """
+    if epoch >= EIP7928_FORK_EPOCH:
+        return EIP7928_FORK_VERSION
+    if epoch >= ELECTRA_FORK_EPOCH:
+        return ELECTRA_FORK_VERSION
+    if epoch >= DENEB_FORK_EPOCH:
+        return DENEB_FORK_VERSION
+    if epoch >= CAPELLA_FORK_EPOCH:
+        return CAPELLA_FORK_VERSION
+    if epoch >= BELLATRIX_FORK_EPOCH:
+        return BELLATRIX_FORK_VERSION
+    if epoch >= ALTAIR_FORK_EPOCH:
+        return ALTAIR_FORK_VERSION
+    return GENESIS_FORK_VERSION
+```
+
+## Fork to EIP-7928
+
+### Fork trigger
+
+The fork is triggered at epoch `EIP7928_FORK_EPOCH`.
+
+### Upgrading the state
+
+If `state.slot % SLOTS_PER_EPOCH == 0` and
+`compute_epoch_at_slot(state.slot) == EIP7928_FORK_EPOCH`, an irregular state
+change is made to upgrade to EIP-7928.
+
+```python
+def upgrade_to_eip7928(pre: electra.BeaconState) -> BeaconState:
+    epoch = electra.get_current_epoch(pre)
+    latest_execution_payload_header = ExecutionPayloadHeader(
+        parent_hash=pre.latest_execution_payload_header.parent_hash,
+        fee_recipient=pre.latest_execution_payload_header.fee_recipient,
+        state_root=pre.latest_execution_payload_header.state_root,
+        receipts_root=pre.latest_execution_payload_header.receipts_root,
+        logs_bloom=pre.latest_execution_payload_header.logs_bloom,
+        prev_randao=pre.latest_execution_payload_header.prev_randao,
+        block_number=pre.latest_execution_payload_header.block_number,
+        gas_limit=pre.latest_execution_payload_header.gas_limit,
+        gas_used=pre.latest_execution_payload_header.gas_used,
+        timestamp=pre.latest_execution_payload_header.timestamp,
+        extra_data=pre.latest_execution_payload_header.extra_data,
+        base_fee_per_gas=pre.latest_execution_payload_header.base_fee_per_gas,
+        block_hash=pre.latest_execution_payload_header.block_hash,
+        transactions_root=pre.latest_execution_payload_header.transactions_root,
+        withdrawals_root=pre.latest_execution_payload_header.withdrawals_root,
+        blob_gas_used=pre.latest_execution_payload_header.blob_gas_used,
+        excess_blob_gas=pre.latest_execution_payload_header.excess_blob_gas,
+        # [New in EIP7928]
+        block_access_list_root=Root(),
+    )
+    post = BeaconState(
+        genesis_time=pre.genesis_time,
+        genesis_validators_root=pre.genesis_validators_root,
+        slot=pre.slot,
+        fork=Fork(
+            previous_version=pre.fork.current_version,
+            current_version=EIP7928_FORK_VERSION,
+            epoch=epoch,
+        ),
+        latest_block_header=pre.latest_block_header,
+        block_roots=pre.block_roots,
+        state_roots=pre.state_roots,
+        historical_roots=pre.historical_roots,
+        eth1_data=pre.eth1_data,
+        eth1_data_votes=pre.eth1_data_votes,
+        eth1_deposit_index=pre.eth1_deposit_index,
+        validators=pre.validators,
+        balances=pre.balances,
+        randao_mixes=pre.randao_mixes,
+        slashings=pre.slashings,
+        previous_epoch_participation=pre.previous_epoch_participation,
+        current_epoch_participation=pre.current_epoch_participation,
+        justification_bits=pre.justification_bits,
+        previous_justified_checkpoint=pre.previous_justified_checkpoint,
+        current_justified_checkpoint=pre.current_justified_checkpoint,
+        finalized_checkpoint=pre.finalized_checkpoint,
+        inactivity_scores=pre.inactivity_scores,
+        current_sync_committee=pre.current_sync_committee,
+        next_sync_committee=pre.next_sync_committee,
+        latest_execution_payload_header=latest_execution_payload_header,
+        next_withdrawal_index=pre.next_withdrawal_index,
+        next_withdrawal_validator_index=pre.next_withdrawal_validator_index,
+        historical_summaries=pre.historical_summaries,
+        deposit_requests_start_index=pre.deposit_requests_start_index,
+        deposit_balance_to_consume=pre.deposit_balance_to_consume,
+        exit_balance_to_consume=pre.exit_balance_to_consume,
+        earliest_exit_epoch=pre.earliest_exit_epoch,
+        consolidation_balance_to_consume=pre.consolidation_balance_to_consume,
+        earliest_consolidation_epoch=pre.earliest_consolidation_epoch,
+        pending_deposits=pre.pending_deposits,
+        pending_partial_withdrawals=pre.pending_partial_withdrawals,
+        pending_consolidations=pre.pending_consolidations,
+    )
+
+    return post
+```