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

- From comments on PR ethereum#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.

Author: fselmo

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,
@@ -234,7 +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": Hash([]) if fork.header_bal_hash_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)

src/ethereum_test_specs/blockchain.py

@@ -338,7 +338,7 @@ def get_fixture_block(self) -> FixtureBlock | InvalidFixtureBlock:
                 if self.withdrawals is not None
                 else None
             ),
-            block_access_list=self.block_access_list.rlp() if self.block_access_list else None,
+            block_access_list=self.block_access_list.rlp if self.block_access_list else None,
             fork=self.fork,
         ).with_rlp(txs=self.txs)
 
@@ -611,7 +611,7 @@ def generate_block_data(
                 "by the transition tool"
             )
 
-            rlp = transition_tool_output.result.block_access_list.rlp()
+            rlp = transition_tool_output.result.block_access_list.rlp
             computed_bal_hash = Hash(rlp.keccak256())
             assert computed_bal_hash == header.block_access_list_hash, (
                 "Block access list hash in header does not match the "

src/ethereum_test_types/block_access_list/__init__.py

@@ -5,7 +5,8 @@
 these are simple data classes that can be composed together.
 """
 
-from typing import Any, Callable, ClassVar, List
+from functools import cached_property
+from typing import Any, Callable, ClassVar, Dict, List
 
 import ethereum_rlp as eth_rlp
 from pydantic import Field
@@ -138,10 +139,40 @@ def to_list(self) -> List[Any]:
         """Return the list for RLP encoding per EIP-7928."""
         return to_serializable_element(self.root)
 
+    @cached_property
     def rlp(self) -> Bytes:
         """Return the RLP encoded block access list for hash verification."""
         return Bytes(eth_rlp.encode(self.to_list()))
 
+    @cached_property
+    def rlp_hash(self) -> Bytes:
+        """Return the hash of the RLP encoded block access list."""
+        return self.rlp.keccak256()
+
+
+class BalAccountExpectation(CamelModel):
+    """
+    Represents expected changes to a specific account in a block.
+
+    Same as BalAccountChange but without the address field, used for expectations.
+    """
+
+    nonce_changes: List[BalNonceChange] = Field(
+        default_factory=list, description="List of expected nonce changes"
+    )
+    balance_changes: List[BalBalanceChange] = Field(
+        default_factory=list, description="List of expected balance changes"
+    )
+    code_changes: List[BalCodeChange] = Field(
+        default_factory=list, description="List of expected code changes"
+    )
+    storage_changes: List[BalStorageSlot] = Field(
+        default_factory=list, description="List of expected storage changes"
+    )
+    storage_reads: List[StorageKey] = Field(
+        default_factory=list, description="List of expected read storage slots"
+    )
+
 
 class BlockAccessListExpectation(CamelModel):
     """
@@ -151,22 +182,23 @@ class BlockAccessListExpectation(CamelModel):
     - Partial validation (only checks explicitly set fields)
     - Convenient test syntax with named parameters
     - Verification against actual BAL from t8n
+    - Explicit exclusion of addresses (using None values)
 
     Example:
         # In test definition
         expected_block_access_list = BlockAccessListExpectation(
-            account_changes=[
-                BalAccountChange(
-                    address=alice,
+            account_expectations={
+                alice: BalAccountExpectation(
                     nonce_changes=[BalNonceChange(tx_index=1, post_nonce=1)]
-                )
-            ]
+                ),
+                bob: None,  # Bob should NOT be in the BAL
+            }
         )
 
     """
 
-    account_changes: List[BalAccountChange] = Field(
-        default_factory=list, description="Expected account changes to verify"
+    account_expectations: Dict[Address, BalAccountExpectation | None] = Field(
+        default_factory=dict, description="Expected account changes or exclusions to verify"
     )
 
     modifier: Callable[["BlockAccessList"], "BlockAccessList"] | None = Field(
@@ -191,7 +223,7 @@ def modify(
             from ethereum_test_types.block_access_list.modifiers import remove_nonces
 
             expectation = BlockAccessListExpectation(
-                account_changes=[...]
+                account_expectations={...}
             ).modify(remove_nonces(alice))
 
         """
@@ -213,8 +245,7 @@ def to_fixture_bal(self, t8n_bal: "BlockAccessList") -> "BlockAccessList":
             The potentially transformed BlockAccessList for the fixture
 
         """
-        # Only validate if we have expectations
-        if self.account_changes:
+        if self.account_expectations:
             self.verify_against(t8n_bal)
 
         # Apply modifier if present (for invalid tests)
@@ -235,49 +266,42 @@ def verify_against(self, actual_bal: "BlockAccessList") -> None:
 
         """
         actual_accounts_by_addr = {acc.address: acc for acc in actual_bal.root}
-        expected_accounts_by_addr = {acc.address: acc for acc in self.account_changes}
 
-        # Check for missing accounts
-        missing_accounts = set(expected_accounts_by_addr.keys()) - set(
-            actual_accounts_by_addr.keys()
-        )
-        if missing_accounts:
-            raise Exception(
-                "Expected accounts not found in actual BAL: "
-                f"{', '.join(str(a) for a in missing_accounts)}"
-            )
-
-        # Verify each expected account
-        for address, expected_account in expected_accounts_by_addr.items():
-            actual_account = actual_accounts_by_addr[address]
-
-            try:
-                self._compare_account_changes(expected_account, actual_account)
-            except AssertionError as e:
-                raise Exception(f"Account {address}: {str(e)}") from e
-
-    def _compare_account_changes(
-        self, expected: BalAccountChange, actual: BalAccountChange
+        for address, expectation in self.account_expectations.items():
+            if expectation is None:
+                # check explicit exclusion of address when set to `None`
+                if address in actual_accounts_by_addr:
+                    raise Exception(f"Address {address} should not be in BAL but was found")
+            else:
+                # Address should be in BAL with expected values
+                if address not in actual_accounts_by_addr:
+                    raise Exception(f"Expected address {address} not found in actual BAL")
+
+                actual_account = actual_accounts_by_addr[address]
+                try:
+                    self._compare_account_expectations(expectation, actual_account)
+                except AssertionError as e:
+                    raise Exception(f"Account {address}: {str(e)}") from e
+
+    def _compare_account_expectations(
+        self, expected: BalAccountExpectation, actual: BalAccountChange
     ) -> None:
         """
-        Compare two BalAccountChange models with detailed error reporting.
+        Compare expected account changes with actual BAL account entry.
 
         Only validates fields that were explicitly set in the expected model,
         using model_fields_set to determine what was intentionally specified.
         """
         # Only check fields that were explicitly set in the expected model
         for field_name in expected.model_fields_set:
-            if field_name == "address":
-                continue  # Already matched by account lookup
-
             expected_value = getattr(expected, field_name)
             actual_value = getattr(actual, field_name)
 
-            # If we explicitly set a field to None, verify it's None/empty
+            # explicit check for None
             if expected_value is None:
                 if actual_value is not None and actual_value != []:
                     raise AssertionError(
-                        f"Expected {field_name} to be empty/None but found: {actual_value}"
+                        f"Expected {field_name} to be `None` but found: {actual_value}"
                     )
                 continue
 
@@ -314,7 +338,8 @@ def _compare_account_changes(
                     # The comparison method will raise with details
                     pass
 
-    def _compare_change_lists(self, field_name: str, expected: List, actual: List) -> bool:
+    @staticmethod
+    def _compare_change_lists(field_name: str, expected: List, actual: List) -> bool:
         """Compare lists of change objects using set operations for better error messages."""
         if field_name == "storage_changes":
             # Storage changes are nested (slot -> changes)
@@ -390,6 +415,7 @@ def _compare_change_lists(self, field_name: str, expected: List, actual: List) -
     # Core models
     "BlockAccessList",
     "BlockAccessListExpectation",
+    "BalAccountExpectation",
     # Change types
     "BalAccountChange",
     "BalNonceChange",

tests/amsterdam/eip7928_block_level_access_lists/test_block_access_lists.py

@@ -13,7 +13,7 @@
 )
 from ethereum_test_tools.vm.opcode import Opcodes as Op
 from ethereum_test_types.block_access_list import (
-    BalAccountChange,
+    BalAccountExpectation,
     BalBalanceChange,
     BalCodeChange,
     BalNonceChange,
@@ -53,12 +53,11 @@ def test_bal_nonce_changes(
             bob: Account(balance=100),
         },
         expected_block_access_list=BlockAccessListExpectation(
-            account_changes=[
-                BalAccountChange(
-                    address=alice,
+            account_expectations={
+                alice: BalAccountExpectation(
                     nonce_changes=[BalNonceChange(tx_index=1, post_nonce=1)],
                 ),
-            ]
+            }
         ),
     )
 
@@ -105,20 +104,17 @@ def test_bal_balance_changes(
             bob: Account(balance=100),
         },
         expected_block_access_list=BlockAccessListExpectation(
-            account_changes=[
-                BalAccountChange(
-                    address=alice,
+            account_expectations={
+                alice: BalAccountExpectation(
                     nonce_changes=[BalNonceChange(tx_index=1, post_nonce=1)],
                     balance_changes=[
                         BalBalanceChange(tx_index=1, post_balance=alice_final_balance)
                     ],
                 ),
-                BalAccountChange(
-                    address=bob,
+                bob: BalAccountExpectation(
                     balance_changes=[BalBalanceChange(tx_index=1, post_balance=100)],
                 ),
-                # TODO: Validate coinbase
-            ]
+            }
         ),
     )
 
@@ -153,17 +149,16 @@ def test_bal_storage_writes(
             storage_contract: Account(storage={0x01: 0x42}),
         },
         expected_block_access_list=BlockAccessListExpectation(
-            account_changes=[
-                BalAccountChange(
-                    address=storage_contract,
+            account_expectations={
+                storage_contract: BalAccountExpectation(
                     storage_changes=[
                         BalStorageSlot(
                             slot=0x01,
                             slot_changes=[BalStorageChange(tx_index=1, post_value=0x42)],
                         )
                     ],
                 ),
-            ]
+            }
         ),
     )
 
@@ -196,12 +191,11 @@ def test_bal_storage_reads(
             storage_contract: Account(storage={0x01: 0x42}),
         },
         expected_block_access_list=BlockAccessListExpectation(
-            account_changes=[
-                BalAccountChange(
-                    address=storage_contract,
+            account_expectations={
+                storage_contract: BalAccountExpectation(
                     storage_reads=[0x01],
                 ),
-            ]
+            }
         ),
     )
 
@@ -266,19 +260,16 @@ def test_bal_code_changes(
             ),
         },
         expected_block_access_list=BlockAccessListExpectation(
-            account_changes=[
-                BalAccountChange(
-                    address=alice,
+            account_expectations={
+                alice: BalAccountExpectation(
                     nonce_changes=[BalNonceChange(tx_index=1, post_nonce=1)],
                 ),
-                BalAccountChange(
-                    address=factory_contract,
+                factory_contract: BalAccountExpectation(
                     nonce_changes=[BalNonceChange(tx_index=1, post_nonce=2)],
                 ),
-                BalAccountChange(
-                    address=created_contract,
+                created_contract: BalAccountExpectation(
                     code_changes=[BalCodeChange(tx_index=1, new_code=runtime_code_bytes)],
                 ),
-            ]
+            }
         ),
     )