feat(specs): Implement EIP-7928: Block-Level Access Lists

fix(tests): Fix Amsterdam filling after rebase
fix(specs): Fix issues with new ruff + mypy rules after rebase

- bal -> block_access_list; re-add custom rlp encoding for block access list
- bytes to uint
- move away from method-style

- Update EIP-7928 implementation: system contracts at index 0, migrate to RLP
  - System contracts (parent hash, beacon root) now use block_access_index 0
  - Transactions use block_access_index 1 to len(transactions)
  - Post-execution changes use block_access_index len(transactions) + 1
  - Migrated from SSZ to RLP encoding as per updated EIP-7928 spec
  - Updated all tests to match new API and structure
  - Replaced tx_index with block_access_index throughout codebase

- add system contract logic
- add markdown docstrings
- update BAL format; address comments
- ssz encoding and bal validation
- six ssz types
- bal tests
- balspecs

fix: do not track setting empty code to a new account (#19)
fix: track implicit SLOAD within SSTORE for OOG cases (#18)
refactor: Put back explicit acct tracking outside 7702 delegation path (#17)
fix non-tracked 7702 authority for invalid delegations (#16)
    * fix non-tracked 7702 authority for invalid delegations
    * fix: lint issues
    * fix: track delegation target when loaded as call target
    * fix: track delegation target when loaded as call target from call
      opcodes
    * chore: fix issues with documentation generation

Fix self-destruct cases with pre-execution balance cache / tracking
    * fix self-destruct implementation
    * fix self-destruct tracking balance
    * fix it in the bal finalization by filtering
    * add balance reset and fix tests
    * simplify pre-balance tracking not using snapshots

fix duplicated code entries for in transaction self destruct
fix self destruct in same transaction bug
fix call/delagate call tracking bug
fix zero-value transfer tracking (#6)
    * fix zero-value transfer tracking
    * fix reverted frame tracking
    * rename variables
    * fix missing addresses bug
    * fix: docs run & move imports to top of file

refactor: move rlp_utils to block_access_lists; bal -> block_access_lists
Some remaining fixes due to large refactor in `forks/osaka`:

- Move BALs from amsterdam -> forks/amsterdam
- rename: build -> build_block_access_list
- fix docc issues

move state change tracker to State

correct system contract addresses

Fixes to communicate with BALs EEST branch:

- fix(bal): Initialize the state tracker before system contract calls

- We were missing system contract calls to beacon roots and history
  contracts. This change initializes the state tracker before system
  contract calls and passes the tracker to these calls if post-Amsterdam.

- fix(docs): Fix issues with toxenvs: lint, doc, json_infra
- fix(t8n): Only initialize the bal_change_tracker for amsterdam
- feat(fork criteria): Index upcoming forks for better ordering / fix issues
- chore(forks): Fix issues from lint after rebase with Osaka latest
- fix(setuptools): Update packages to include amsterdam
- chore(lint): Fix 'tox -e static' issues

- Fix bug in tracker
  Manually cherry-picked from e72991b
  Author: nerolation

- chore(tests): Attempt to resolve issues with CI tests
- chore(lint): fix issues from running ``tox -e static`` locally
- refactor(bal): Send BAL as a list over t8n tool
- fix(amsterdam): Add change tracker to state test in t8n
- chore(lint,tests): Fix tests after moving bal from osaka -> amsterdam
- chore(forks): Move bals from Osaka to Amsterdam
- chore(lint): Fix lint issues

- refactor(bal): Send the full bal object and bal_hash over t8n

  - If we send the full object over JSON, we can model_validate() on ESST.
  - If we send the hash, once we fill the pydantic model, we can get the rlp
    and the hash and validate that our objects match while only really
    validating the parts of the BAL we are interested in for each test.

- chore: point to working eest branch
- chore(bals): Remove unused SSZ utils.py
  The SSZ implementation is no longer needed as we are now using RLP
- refactor(bals): Clean up BAL module types and imports
  - Bytes -> Bytes32 type for storage slots
  - Remove unused imports / fix imports / fix linting
  - Update function signatures to match tracker

- fix(bals-tx-index): Track bal indexes in t8n
  Keep track of BAL index state in t8n

Author: fselmo

packages/testing/src/execution_testing/fixtures/blockchain.py

@@ -203,6 +203,9 @@ class FixtureHeader(CamelModel):
     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)
 
@@ -287,6 +290,11 @@ def genesis(cls, fork: Fork, env: Environment, state_root: Hash) -> Self:
             "requests_hash": Requests()
             if fork.header_requests_required(block_number=0, timestamp=0)
             else None,
+            "block_access_list_hash": (
+                BlockAccessList().rlp_hash
+                if fork.header_bal_hash_required(block_number=0, timestamp=0)
+                else None
+            ),
             "fork": fork,
         }
         return cls(**environment_values, **extras)
@@ -416,6 +424,14 @@ def from_fixture_header(
             "Invalid header for engine_newPayload"
         )
 
+        if fork.engine_execution_payload_block_access_list(
+            block_number=header.number, timestamp=header.timestamp
+        ):
+            if block_access_list is None:
+                raise ValueError(
+                    f"`block_access_list` is required in engine `ExecutionPayload` for >={fork}."
+                )
+
         execution_payload = FixtureExecutionPayload.from_fixture_header(
             header=header,
             transactions=transactions,

packages/testing/src/execution_testing/forks/base_fork.py

@@ -351,6 +351,14 @@ def header_requests_required(
         """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
@@ -743,6 +751,17 @@ def engine_new_payload_target_blobs_per_block(
         """
         pass
 
+    @classmethod
+    @abstractmethod
+    def engine_execution_payload_block_access_list(
+        cls, *, block_number: int = 0, timestamp: int = 0
+    ) -> bool:
+        """
+        Return `True` if the engine api version requires execution payload to
+        include a `block_access_list`.
+        """
+        pass
+
     @classmethod
     @abstractmethod
     def engine_payload_attribute_target_blobs_per_block(

packages/testing/src/execution_testing/forks/forks/forks.py

@@ -947,6 +947,14 @@ def header_requests_required(
         del block_number, timestamp
         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."""
+        del block_number, timestamp
+        return False
+
     @classmethod
     def engine_new_payload_version(
         cls, *, block_number: int = 0, timestamp: int = 0
@@ -987,6 +995,14 @@ def engine_new_payload_requests(
         del block_number, timestamp
         return False
 
+    @classmethod
+    def engine_execution_payload_block_access_list(
+        cls, *, block_number: int = 0, timestamp: int = 0
+    ) -> bool:
+        """At genesis, payloads do not have block access list."""
+        del block_number, timestamp
+        return False
+
     @classmethod
     def engine_new_payload_target_blobs_per_block(
         cls,
@@ -3264,6 +3280,16 @@ class Amsterdam(BPO2):
     #  related Amsterdam specs change over time, and before Amsterdam is
     #  live on mainnet.
 
+    @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).
+        """
+        del block_number, timestamp
+        return True
+
     @classmethod
     def is_deployed(cls) -> bool:
         """Return True if this fork is deployed."""
@@ -3277,6 +3303,17 @@ def engine_new_payload_version(
         del block_number, timestamp
         return 5
 
+    @classmethod
+    def engine_execution_payload_block_access_list(
+        cls, *, block_number: int = 0, timestamp: int = 0
+    ) -> bool:
+        """
+        From Amsterdam, engine execution payload includes `block_access_list`
+        as a parameter.
+        """
+        del block_number, timestamp
+        return True
+
 
 class EOFv1(Prague, solc_name="cancun"):
     """EOF fork."""

packages/testing/src/execution_testing/specs/blockchain.py

@@ -699,6 +699,24 @@ def generate_block_data(
             )
             requests_list = block.requests
 
+        if self.fork.header_bal_hash_required(
+            block_number=header.number, timestamp=header.timestamp
+        ):
+            assert (
+                transition_tool_output.result.block_access_list is not None
+            ), (
+                "Block access list is required for this block but was not provided "
+                "by the transition tool"
+            )
+
+            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 "
+                f"computed hash from BAL: {header.block_access_list_hash} "
+                f"!= {computed_bal_hash}"
+            )
+
         if block.rlp_modifier is not None:
             # Modify any parameter specified in the `rlp_modifier` after
             # transition tool processing.
@@ -707,6 +725,23 @@ def generate_block_data(
                 self.fork
             )  # Deleted during `apply` because `exclude=True`
 
+        # Process block access list - apply transformer if present for invalid
+        # tests
+        t8n_bal = transition_tool_output.result.block_access_list
+        bal = t8n_bal
+        if (
+            block.expected_block_access_list is not None
+            and t8n_bal is not None
+        ):
+            block.expected_block_access_list.verify_against(t8n_bal)
+
+            bal = block.expected_block_access_list.modify_if_invalid_test(
+                t8n_bal
+            )
+            if bal != t8n_bal:
+                # If the BAL was modified, update the header hash
+                header.block_access_list_hash = Hash(bal.rlp.keccak256())
+
         built_block = BuiltBlock(
             header=header,
             alloc=transition_tool_output.alloc,
@@ -720,7 +755,7 @@ def generate_block_data(
             expected_exception=block.exception,
             engine_api_error_code=block.engine_api_error_code,
             fork=self.fork,
-            block_access_list=None,
+            block_access_list=bal,
         )
 
         try:

pyproject.toml

@@ -142,6 +142,13 @@ packages = [
     "ethereum.forks.osaka.vm.instructions",
     "ethereum.forks.osaka.vm.precompiled_contracts",
     "ethereum.forks.osaka.vm.precompiled_contracts.bls12_381",
+    "ethereum.forks.amsterdam",
+    "ethereum.forks.amsterdam.block_access_lists",
+    "ethereum.forks.amsterdam.utils",
+    "ethereum.forks.amsterdam.vm",
+    "ethereum.forks.amsterdam.vm.instructions",
+    "ethereum.forks.amsterdam.vm.precompiled_contracts",
+    "ethereum.forks.amsterdam.vm.precompiled_contracts.bls12_381",
 ]
 
 [tool.setuptools.package-data]
@@ -378,13 +385,26 @@ ignore = [
 "src/ethereum_spec_tools/evm_tools/t8n/evm_trace.py" = [
     "N815"          # The traces must use camel case in JSON property names
 ]
+"src/ethereum/forks/amsterdam/blocks.py" = [
+    "E501"          # Line too long - needed for long ref links
+]
+ "src/ethereum/forks/amsterdam/block_access_lists/builder.py" = [
+    "E501"          # Line too long - needed for long ref links
+ ]
+"src/ethereum/forks/amsterdam/block_access_lists/rlp_utils.py" = [
+    "E501"          # Line too long - needed for long ref links
+ ]
 "tests/*" = ["ARG001"]
 "vulture_whitelist.py" = [
     "B018",  # Useless expression (intentional for Vulture whitelisting)
     "F403",  # Star imports needed for whitelisting
     "F405",  # Undefined names from star imports
 ]
 
+[tool.ruff.lint.mccabe]
+# Set the maximum allowed cyclomatic complexity. C901 default is 10.
+max-complexity = 7
+
 [tool.codespell]
 builtin = "clear,code,usage"
 # Version control & tooling, build artifacts, data files, test fixtures, temp files, lock files

src/ethereum/forks/amsterdam/block_access_lists/__init__.py

@@ -0,0 +1,57 @@
+"""
+Block Access Lists (EIP-7928) implementation for Ethereum Amsterdam fork.
+"""
+
+from .builder import (
+    BlockAccessListBuilder,
+    add_balance_change,
+    add_code_change,
+    add_nonce_change,
+    add_storage_read,
+    add_storage_write,
+    add_touched_account,
+    build_block_access_list,
+)
+from .rlp_utils import (
+    compute_block_access_list_hash,
+    rlp_encode_block_access_list,
+    validate_block_access_list_against_execution,
+)
+from .tracker import (
+    StateChangeTracker,
+    begin_call_frame,
+    commit_call_frame,
+    rollback_call_frame,
+    set_block_access_index,
+    track_address_access,
+    track_balance_change,
+    track_code_change,
+    track_nonce_change,
+    track_storage_read,
+    track_storage_write,
+)
+
+__all__ = [
+    "BlockAccessListBuilder",
+    "StateChangeTracker",
+    "add_balance_change",
+    "add_code_change",
+    "add_nonce_change",
+    "add_storage_read",
+    "add_storage_write",
+    "add_touched_account",
+    "begin_call_frame",
+    "build_block_access_list",
+    "commit_call_frame",
+    "compute_block_access_list_hash",
+    "rollback_call_frame",
+    "set_block_access_index",
+    "rlp_encode_block_access_list",
+    "track_address_access",
+    "track_balance_change",
+    "track_code_change",
+    "track_nonce_change",
+    "track_storage_read",
+    "track_storage_write",
+    "validate_block_access_list_against_execution",
+]