refactor(specs): make State fork agnostic (#2381)

* refactor(spec): make Trie fork-agnostic for amsterdam

Move all trie logic to a shared `src/ethereum/trie.py`, removing the
fork-specific `src/ethereum/forks/amsterdam/trie.py`. Also move trie
internal node types (LeafNode, ExtensionNode, BranchNode, InternalNode)
from `ethereum.state` into `ethereum.trie`, and trim `ethereum.state`
to just account types and the PreState protocol.

- New `ethereum/trie.py`: Trie, trie_set/get/copy, root, patricialize,
  encode_node/account/internal_node, EMPTY_TRIE_ROOT, and node types
- `ethereum/state.py`: remove trie node types; import InternalNode from
  ethereum.trie under TYPE_CHECKING to break the runtime cycle
- `amsterdam/trie.py`: deleted; consumers updated to import directly
  from ethereum.trie
- `fork_loader.py`: fall back to ethereum.trie when a fork has no
  fork-specific trie module

* refactor(spec): make State fork-agnostic for amsterdam

Move the `State` class and all state helper functions from
`ethereum/forks/amsterdam/state.py` into the shared `ethereum/state.py`,
making the state implementation fork-agnostic for amsterdam.

To break the circular import that would arise between `state.py` and
`trie.py`, introduce `ethereum/types.py` as a thin module holding the
base account types (`Account`, `Address`, `Root`, `EMPTY_CODE_HASH`,
`EMPTY_ACCOUNT`). `trie.py` now imports from `types.py`, allowing
`state.py` to import from both `types.py` and `trie.py` without a cycle.

`ethereum/state.py` re-exports the base types so that the ~260 existing
`from ethereum.state import ...` call sites across all forks require no
changes.

`fork_loader.py` and `t8n_types.py` are updated to fall back to the
shared `ethereum.state` module when the fork-specific `state` module no
longer exists.

* refactor(tests): fall back to ethereum.state in VmTestLoader

Add `_state_module()` helper to `VmTestLoader` that tries the
fork-specific state module first and falls back to the shared
`ethereum.state` when the fork no longer ships its own
`state.py` (e.g. after the fork-agnostic-state refactor).

TODO: remove the fallback once the state module is ported over
to the older forks.

* fix(tests): fix other json_infra tests

* fix(docs): fix docs references

* refactor(spec): address review feedback on encode_node

Add a note explaining why `EMPTY_TRIE_ROOT` uses `Hash32` rather than
`Root` (circular import), unify the `storage_root` annotation on
`encode_node` to use `Bytes | None` for consistency with the `node`
parameter, and tighten `encode_node`'s `node` parameter to `Extended`
(non-nullable) now that `_prepare_trie` narrows `value` away from
`None` before calling in.

Author: gurukamath

src/ethereum/forks/amsterdam/blocks.py

@@ -112,8 +112,8 @@ class Header:
     Ethereum world state after applying the block's state changes.
 
     [`keccak256`]: ref:ethereum.crypto.hash.keccak256
-    [changes]: ref:ethereum.forks.amsterdam.state.State.compute_state_root_and_trie_changes
-    [Trie]: ref:ethereum.forks.amsterdam.trie.Trie
+    [changes]: ref:ethereum.state.State.compute_state_root_and_trie_changes
+    [Trie]: ref:ethereum.merkle_patricia_trie.Trie
     """  # noqa: E501
 
     transactions_root: Root
@@ -124,8 +124,8 @@ class Header:
     transactions as the parameter.
 
     [`keccak256`]: ref:ethereum.crypto.hash.keccak256
-    [`root()`]: ref:ethereum.forks.amsterdam.trie.root
-    [Trie]: ref:ethereum.forks.amsterdam.trie.Trie
+    [`root()`]: ref:ethereum.merkle_patricia_trie.root
+    [Trie]: ref:ethereum.merkle_patricia_trie.Trie
     """
 
     receipt_root: Root
@@ -135,8 +135,8 @@ class Header:
     function over the Merkle-Patricia [trie] constructed from the receipts.
 
     [`keccak256`]: ref:ethereum.crypto.hash.keccak256
-    [`root()`]: ref:ethereum.forks.amsterdam.trie.root
-    [Trie]: ref:ethereum.forks.amsterdam.trie.Trie
+    [`root()`]: ref:ethereum.merkle_patricia_trie.root
+    [Trie]: ref:ethereum.merkle_patricia_trie.Trie
     """
 
     bloom: Bloom

src/ethereum/forks/amsterdam/fork.py

@@ -29,7 +29,14 @@
     NonceMismatchError,
 )
 from ethereum.forks.bpo5.blocks import Header as PreviousHeader
-from ethereum.state import EMPTY_CODE_HASH, Address, BlockDiff, PreState
+from ethereum.merkle_patricia_trie import root, trie_set
+from ethereum.state import (
+    EMPTY_CODE_HASH,
+    Address,
+    BlockDiff,
+    State,
+    apply_changes_to_state,
+)
 
 from . import vm
 from .block_access_lists import (
@@ -60,10 +67,6 @@
     compute_requests_hash,
     parse_deposit_requests,
 )
-from .state import (
-    State,
-    apply_changes_to_state,
-)
 from .state_tracker import (
     BlockState,
     TransactionState,
@@ -89,7 +92,6 @@
     recover_sender,
     validate_transaction,
 )
-from .trie import root, trie_set
 from .utils.hexadecimal import hex_to_address
 from .utils.message import prepare_message
 from .vm import Message
@@ -263,7 +265,7 @@ def state_transition(chain: BlockChain, block: Block) -> None:
 
 def execute_block(
     block: Block,
-    pre_state: PreState,
+    pre_state: State,
     chain_context: ChainContext,
 ) -> BlockDiff:
     """

src/ethereum/forks/amsterdam/requests.py

@@ -35,10 +35,10 @@
 from ethereum_types.numeric import Uint, ulen
 
 from ethereum.exceptions import InvalidBlock
+from ethereum.merkle_patricia_trie import trie_get
 from ethereum.utils.hexadecimal import hex_to_bytes32
 
 from .blocks import decode_receipt
-from .trie import trie_get
 from .utils.hexadecimal import hex_to_address
 from .vm import BlockOutput
 

src/ethereum/forks/amsterdam/state.py

@@ -20,14 +20,14 @@
 
 from ethereum.crypto.hash import Hash32
 from ethereum.exceptions import EthereumException
+from ethereum.merkle_patricia_trie import Trie
 from ethereum.state import Address
 
 from ..block_access_lists import BlockAccessList, BlockAccessListBuilder
 from ..blocks import Log, Receipt, Withdrawal
 from ..fork_types import Authorization, VersionedHash
 from ..state_tracker import BlockState, TransactionState
 from ..transactions import LegacyTransaction
-from ..trie import Trie
 
 __all__ = ("Environment", "Evm", "Message")