feat(tests): Support for EIP-7928 - Block-Level Access Lists (#2067)

* 🚧 wip(EIP-7928): Block-level Access Lists

* ✨ feat(EIP-7928): Spec params

* 🧹 chore(EIP-7928): Rename package

* ✨ feat(EIP-7928): Test cases

* ✨ feat(EIP-7928): Add BAL header

* 🧹 chore(EIP-7928): bal_hash header

* 🧹 chore: Populate bal_hash env

* ✨ feat(EIP-7928): Add BAL to block body

* ✨ feat(EIP-7928): Add pokebal package

* ✨ feat: update env

* 🚧 wip: Checklist and basic tests

* 🧹 chore: scope

* Add more sophisticated test cases (#2029)

Co-authored-by: raxhvl <[email protected]>

* WIP: Attempt to get EEST + EELS bals PRs talking to each other

* refactor(bal): Use full bal in t8n; verify and build fixtures

- Use the full bal object in the t8n. We can use this to model_validate()
  into our pydantic model.
- Also, pass the bal_hash via t8n so that once we do build the BAL, validate
  the explicitly defined values, rlp encode it, then hash it, we can compare
  the full BAL against the hash and make sure that even though we only validated
  the part that was important for our test, the full BAL is also always valid.

Bonus:

- Added a new type for ``StorageKey`` because these were not being rlp encoded
  properly without the left padding. This was tricky to find and I think this
  can be a common issue. New type here seemed appropriate.

* chore(lint): Fix lint issues, assign method to Frontier to be overridden

* fix(tests,lint): Set up code changes test case; fix remaining lint issues

* refactor(forks): move BAL tests to Amsterdam

- chore(cleanup): Remove reference to told BlockAccessLists fork
- refactor(fork): ``Amsterdam`` above old EOF fork.

* chore: Fix CI lint issues not present locally

- Update some docstrings to remove AI excessive verbosity and add
  CodeChanges case to example.

* refactor(bal): Apply comments from first pass at PR

- Use ``Number`` instead of ``int`` where appropriate
- Use ``default_factory=list`` without ``Optional`` and ``None`` where
  appropriate

* refactor(bal): Split BAL into two classes

- Use a root model class for the t8n BAL model. This lets us stick
  closer to the EIP definition where the BAL itself is a list.
- The class doesn't need to be `RLPSerializable`, just have
  simple instructions to serialize its elements (`rlp()`).
- Create a `BlockAccessListExpectation` class to represent the
  expected BAL for a given block. This class can describe different
  expectations for the test cases, such as defining mutations to
  be used for invalid tests.

* refactor(tests): Rename checklist.md -> test_cases.md for BAL test case tracking

* feat(tests,tools): [WIP] initial invalid BAL tests

* chore(spec-resolver): Update commit hash to point to for spec resolver

* fix(lint,resolver): Use latest commit in resolver; fix lint

* Address comments from PR #2067

* chore(docs): Add changelog entries for BAL updates

* refactor(types): Refactor BAL checks for explicit exclusion of acct changes

- From comments on PR #2067, we should allow for an explicit exclusion case
  for an entire set of account changes. If a test case warrants a sanity check
  that some account might have been impacted but shouldn't be accounted for,
  we should be able to specify that explicitly.

* fix(bal): Fix explicit empty checks for account changes; add unit tests

* feat(bal): Extend BAL support within framework

- Add BAL to engine execution payload as defined in:
  https://github.com/ethereum/consensus-specs/pull/4526/files#diff-4b950f0c895b4d521c9e8103d638e73a4c7746c6aea51250994425a1efd6f4c8R55

- Add BAL support for state tests to be able to create blockchain tests

* fix(warnings): Silence warning for unused reference in .md file

* fix(bal): Move state test expected bal to Block

* feat(release): Set up BAL work for a feature release

* fix: BAL as object in fixture block so RLP is correct

* chore(pytest): Add Amsterdam to ruleset for simulator plugin

---------

Co-authored-by: raxhvl <[email protected]>
Co-authored-by: Toni Wahrstätter <[email protected]>
Co-authored-by: raxhvl <[email protected]>

Author: 3 people

.github/configs/eels_resolutions.json

@@ -48,5 +48,10 @@
     },
     "BPO4": {
         "same_as": "Osaka"
+    },
+    "Amsterdam": {
+        "git_url": "https://github.com/fselmo/execution-specs.git",
+        "branch": "feat/amsterdam-fork-and-block-access-lists",
+        "commit": "a5c7b29a658320c2432de78883d350e9f4444d14"
     }
 }

.github/configs/feature.yaml

@@ -15,3 +15,8 @@ benchmark_develop:
   evm-type: develop
   fill-params: --fork=Osaka --gas-benchmark-values 1,10,30,45,60,100,150 -m "benchmark and not state_test" ./tests/benchmark
   feature_only: true
+
+bal:
+  evm-type: develop
+  fill-params: --fork=Amsterdam ./tests/amsterdam/eip7928_block_level_access_lists
+  feature_only: true

docs/CHANGELOG.md

@@ -141,6 +141,7 @@ Users can select any of the artifacts depending on their testing needs for their
 - 🔀 Move Prague to stable and Osaka to develop ([#1573](https://github.com/ethereum/execution-spec-tests/pull/1573)).
 - ✨ Add a `pytest.mark.with_all_typed_transactions` marker that creates default typed transactions for each `tx_type` supported by the current `fork` ([#1890](https://github.com/ethereum/execution-spec-tests/pull/1890)).
 - ✨ Add basic support for ``Amsterdam`` fork in order to begin testing Glamsterdam ([#2069](https://github.com/ethereum/execution-spec-tests/pull/2069)).
+- ✨ [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928): Add initial framework support for `Block Level Access Lists (BAL)` testing for Amsterdam ([#2067](https://github.com/ethereum/execution-spec-tests/pull/2067)).
 
 ### 🧪 Test Cases
 
@@ -154,12 +155,13 @@ Users can select any of the artifacts depending on their testing needs for their
 - ✨ [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951): add test cases for `P256VERIFY` precompile to support secp256r1 curve [#1670](https://github.com/ethereum/execution-spec-tests/pull/1670).
 - ✨ Introduce blockchain tests for benchmark to cover the scenario of pure ether transfers [#1742](https://github.com/ethereum/execution-spec-tests/pull/1742).
 - ✨ [EIP-7934](https://eips.ethereum.org/EIPS/eip-7934): Add test cases for the block RLP max limit of 10MiB ([#1730](https://github.com/ethereum/execution-spec-tests/pull/1730)).
-- ✨ [EIP-7939](https://eips.ethereum.org/EIPS/eip-7939) Add count leading zeros (CLZ) opcode tests for Osaka ([#1733](https://github.com/ethereum/execution-spec-tests/pull/1733)).
+- ✨ [EIP-7939](https://eips.ethereum.org/EIPS/eip-7939): Add count leading zeros (CLZ) opcode tests for Osaka ([#1733](https://github.com/ethereum/execution-spec-tests/pull/1733)).
 - ✨ [EIP-7934](https://eips.ethereum.org/EIPS/eip-7934): Add additional test cases for block RLP max limit with all typed transactions and for a log-creating transactions ([#1890](https://github.com/ethereum/execution-spec-tests/pull/1890)).
 - ✨ [EIP-7825](https://eips.ethereum.org/EIPS/eip-7825): Pre-Osaka tests have been updated to either (1) dynamically adapt to the transaction gas limit cap, or (2) reduce overall gas consumption to fit the new limit ([#1924](https://github.com/ethereum/EIPs/pull/1924), [#1928](https://github.com/ethereum/EIPs/pull/1928), [#1980](https://github.com/ethereum/EIPs/pull/1980)).
 - ✨ [EIP-7918](https://eips.ethereum.org/EIPS/eip-7918): Blob base fee bounded by execution cost test cases (initial), includes some adjustments to [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) tests ([#1685](https://github.com/ethereum/execution-spec-tests/pull/1685)).
 - 🔀 Adds the max blob transaction limit to the tests including updates to [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) for Osaka ([#1884](https://github.com/ethereum/execution-spec-tests/pull/1884)).
 - 🐞 Fix issues when filling block rlp size limit tests with ``--generate-pre-alloc-groups`` ([#1989](https://github.com/ethereum/execution-spec-tests/pull/1989)).
+- ✨ [EIP-7928](https://eips.ethereum.org/EIPS/eip-7928): Add test cases for `Block Level Access Lists (BAL)` to Amsterdam ([#2067](https://github.com/ethereum/execution-spec-tests/pull/2067)).
 
 ## [v4.5.0](https://github.com/ethereum/execution-spec-tests/releases/tag/v4.5.0) - 2025-05-14
 

docs/running_tests/test_formats/blockchain_test_sync.md

@@ -15,7 +15,7 @@ The test works by:
 3. Having the sync client synchronize from the client under test.
 4. Verifying that both clients reach the same final state.
 
-A single JSON fixture file is composed of a JSON object where each key-value pair is a different [`SyncFixture`](#syncfixture) test object, with the key string representing the test name.
+A single JSON fixture file is composed of a JSON object where each key-value pair is a different [`HiveFixture`](#hivefixture) test object, with the key string representing the test name.
 
 The JSON file path plus the test name are used as the unique test identifier, as well as a `{client under test}::sync_{sync client}` identifier.
 

src/ethereum_clis/types.py

@@ -12,7 +12,13 @@
     TransactionException,
     UndefinedException,
 )
-from ethereum_test_types import Alloc, Environment, Transaction, TransactionReceipt
+from ethereum_test_types import (
+    Alloc,
+    BlockAccessList,
+    Environment,
+    Transaction,
+    TransactionReceipt,
+)
 
 
 class TransactionExceptionWithMessage(ExceptionWithMessage[TransactionException]):
@@ -57,6 +63,8 @@ class Result(CamelModel):
     blob_gas_used: HexNumber | None = None
     requests_hash: Hash | None = None
     requests: List[Bytes] | None = None
+    block_access_list: BlockAccessList | None = None
+    block_access_list_hash: Hash | None = None
     block_exception: Annotated[
         BlockExceptionWithMessage | UndefinedException | None, ExceptionMapperValidator
     ] = None

src/ethereum_test_base_types/__init__.py

@@ -14,6 +14,7 @@
     HexNumber,
     Number,
     NumberBoundTypeVar,
+    StorageKey,
     Wei,
     ZeroPaddedHexNumber,
 )
@@ -72,6 +73,7 @@
     "RLPSerializable",
     "SignableRLPSerializable",
     "Storage",
+    "StorageKey",
     "StorageRootType",
     "TestAddress",
     "TestAddress2",

src/ethereum_test_base_types/base_types.py

@@ -383,6 +383,20 @@ class Hash(FixedSizeBytes[32]):  # type: ignore
     pass
 
 
+class StorageKey(FixedSizeBytes[32]):  # type: ignore
+    """
+    Storage key type that automatically applies left padding for values shorter
+    than 32 bytes.
+    """
+
+    def __new__(cls, value, **kwargs):
+        """Create a new StorageKey with automatic left padding."""
+        # Always apply left_padding for storage keys unless explicitly set to False
+        if "left_padding" not in kwargs:
+            kwargs["left_padding"] = True
+        return super().__new__(cls, value, **kwargs)
+
+
 class Bloom(FixedSizeBytes[256]):  # type: ignore
     """Class that helps represent blooms in tests."""
 

src/ethereum_test_fixtures/blockchain.py

@@ -38,6 +38,7 @@
 from ethereum_test_exceptions import EngineAPIError, ExceptionInstanceOrList
 from ethereum_test_forks import Fork, Paris
 from ethereum_test_types import (
+    BlockAccessList,
     Environment,
     Requests,
     Transaction,
@@ -165,6 +166,9 @@ class FixtureHeader(CamelModel):
         None
     )
     requests_hash: Annotated[Hash, HeaderForkRequirement("requests")] | None = Field(None)
+    block_access_list_hash: Annotated[Hash, HeaderForkRequirement("bal_hash")] | None = Field(
+        None, alias="blockAccessListHash"
+    )
 
     fork: Fork | None = Field(None, exclude=True)
 
@@ -231,6 +235,9 @@ def genesis(cls, fork: Fork, env: Environment, state_root: Hash) -> "FixtureHead
         extras = {
             "state_root": state_root,
             "requests_hash": Requests() if fork.header_requests_required(0, 0) else None,
+            "block_access_list_hash": (
+                BlockAccessList().rlp_hash if fork.header_bal_hash_required(0, 0) else None
+            ),
             "fork": fork,
         }
         return FixtureHeader(**environment_values, **extras)
@@ -262,21 +269,27 @@ class FixtureExecutionPayload(CamelModel):
     transactions: List[Bytes]
     withdrawals: List[Withdrawal] | None = None
 
+    block_access_list: Bytes | None = Field(
+        None, description="RLP-serialized EIP-7928 Block Access List"
+    )
+
     @classmethod
     def from_fixture_header(
         cls,
         header: FixtureHeader,
         transactions: List[Transaction],
         withdrawals: List[Withdrawal] | None,
+        block_access_list: Bytes | None = None,
     ) -> "FixtureExecutionPayload":
         """
         Return FixtureExecutionPayload from a FixtureHeader, a list
-        of transactions and a list of withdrawals.
+        of transactions, a list of withdrawals, and an optional block access list.
         """
         return cls(
             **header.model_dump(exclude={"rlp"}, exclude_none=True),
             transactions=[tx.rlp() for tx in transactions],
             withdrawals=withdrawals,
+            block_access_list=block_access_list,
         )
 
 
@@ -331,6 +344,7 @@ def from_fixture_header(
         transactions: List[Transaction],
         withdrawals: List[Withdrawal] | None,
         requests: List[Bytes] | None,
+        block_access_list: Bytes | None = None,
         **kwargs,
     ) -> "FixtureEngineNewPayload":
         """Create `FixtureEngineNewPayload` from a `FixtureHeader`."""
@@ -344,6 +358,7 @@ def from_fixture_header(
             header=header,
             transactions=transactions,
             withdrawals=withdrawals,
+            block_access_list=block_access_list,
         )
 
         params: List[Any] = [execution_payload]
@@ -428,6 +443,9 @@ class FixtureBlockBase(CamelModel):
     ommers: List[FixtureHeader] = Field(default_factory=list, alias="uncleHeaders")
     withdrawals: List[FixtureWithdrawal] | None = None
     execution_witness: WitnessChunk | None = None
+    block_access_list: BlockAccessList | None = Field(
+        None, description="EIP-7928 Block Access List"
+    )
 
     @computed_field(alias="blocknumber")  # type: ignore[misc]
     @cached_property
@@ -446,6 +464,9 @@ def with_rlp(self, txs: List[Transaction]) -> "FixtureBlock":
         if self.withdrawals is not None:
             block.append([w.to_serializable_list() for w in self.withdrawals])
 
+        if self.block_access_list is not None:
+            block.append(self.block_access_list.to_list())
+
         return FixtureBlock(
             **self.model_dump(),
             rlp=eth_rlp.encode(block),

src/ethereum_test_forks/base_fork.py

@@ -269,6 +269,12 @@ def header_requests_required(cls, block_number: int = 0, timestamp: int = 0) ->
         """Return true if the header must contain beacon chain requests."""
         pass
 
+    @classmethod
+    @abstractmethod
+    def header_bal_hash_required(cls, block_number: int = 0, timestamp: int = 0) -> bool:
+        """Return true if the header must contain block access list hash."""
+        pass
+
     # Gas related abstract methods
 
     @classmethod

src/ethereum_test_forks/forks/forks.py

@@ -315,6 +315,11 @@ def header_requests_required(cls, block_number: int = 0, timestamp: int = 0) ->
         """At genesis, header must not contain beacon chain requests."""
         return False
 
+    @classmethod
+    def header_bal_hash_required(cls, block_number: int = 0, timestamp: int = 0) -> bool:
+        """At genesis, header must not contain block access list hash."""
+        return False
+
     @classmethod
     def engine_new_payload_version(
         cls, block_number: int = 0, timestamp: int = 0
@@ -1808,6 +1813,20 @@ class BPO5(BPO4, bpo_fork=True):
     pass
 
 
+class Amsterdam(Osaka):
+    """Amsterdam fork."""
+
+    @classmethod
+    def header_bal_hash_required(cls, block_number: int = 0, timestamp: int = 0) -> bool:
+        """From Amsterdam, header must contain block access list hash (EIP-7928)."""
+        return True
+
+    @classmethod
+    def is_deployed(cls) -> bool:
+        """Return True if this fork is deployed."""
+        return False
+
+
 class EOFv1(Prague, solc_name="cancun"):
     """EOF fork."""
 
@@ -1837,12 +1856,3 @@ def is_deployed(cls) -> bool:
         development.
         """
         return False
-
-
-class Amsterdam(Osaka):
-    """Amsterdam fork."""
-
-    @classmethod
-    def is_deployed(cls) -> bool:
-        """Return True if this fork is deployed."""
-        return False