feat(static): implement address tag resolution for static test fillers

Hard-coded address conversion in yml and json fillers:
  - Add convert_addresses.py script to automate tag conversion
  - The correct way to run this is with the ``CONVERT_COINBASE`` flag set to ``False``
    as this allows the same coinbase for all tests (just as python tests do). If we
    decide we want to handle the coinbase setting on the python side, we can turn this
    flag on and hard-code on the python side... but the currect approach seems correct.
  - Convert 1000+ static test YAML/JSON files to use address tags

(Python) Generate deterministic addresses from tags coming from static test fillers:
  - Resolve tags to deterministic addresses in the same way python tests do - via pytest static filler plugin
  - Add ``BlockchainEngineXFixture`` support for pre-allocation groups

This enables static tests to use symbolic address tags instead of hardcoded addresses,
minimizing muddied context across tests when running via pre alloc sharing.

Author: fselmo

convert_addresses.py

@@ -4,7 +4,7 @@
 
 from pydantic import BaseModel
 
-from .common import CodeInFiller, ValueInFiller
+from .common import CodeInFiller, ValueInFiller, ValueOrTagInFiller
 
 
 class AccountInFiller(BaseModel):
@@ -13,7 +13,7 @@ class AccountInFiller(BaseModel):
     balance: ValueInFiller
     code: CodeInFiller
     nonce: ValueInFiller
-    storage: Dict[ValueInFiller, ValueInFiller]
+    storage: Dict[ValueInFiller, ValueOrTagInFiller]
 
     class Config:
         """Model Config."""

src/ethereum_test_specs/static_state/account.py

@@ -1,5 +1,27 @@
 """Ethereum/tests structures."""
 
-from .common import AddressInFiller, CodeInFiller, Hash32InFiller, ValueInFiller
+from .common import (
+    AccessListInFiller,
+    AddressInFiller,
+    AddressOrTagInFiller,
+    AddressTag,
+    CodeInFiller,
+    Hash32InFiller,
+    Hash32OrTagInFiller,
+    ValueInFiller,
+    ValueOrTagInFiller,
+    parse_address_or_tag,
+)
 
-__all__ = ["AddressInFiller", "ValueInFiller", "CodeInFiller", "Hash32InFiller"]
+__all__ = [
+    "AccessListInFiller",
+    "AddressInFiller",
+    "AddressOrTagInFiller",
+    "AddressTag",
+    "ValueInFiller",
+    "ValueOrTagInFiller",
+    "CodeInFiller",
+    "Hash32InFiller",
+    "Hash32OrTagInFiller",
+    "parse_address_or_tag",
+]

src/ethereum_test_specs/static_state/common/__init__.py

@@ -4,11 +4,13 @@
 import subprocess
 import tempfile
 from functools import cached_property
-from typing import Any
+from typing import Any, List, Union
 
 from eth_abi import encode
 from eth_utils import function_signature_to_4byte_selector
+from pydantic import BaseModel, Field, field_validator
 from pydantic.functional_validators import BeforeValidator
+from pydantic_core import core_schema
 from typing_extensions import Annotated
 
 from ethereum_test_base_types import Address, Hash, HexNumber
@@ -30,6 +32,22 @@ def parse_hex_number(i: str | int) -> int:
     return int(i, 10)
 
 
+def parse_value_or_address_tag(value: Any) -> Union[HexNumber, str]:
+    """Parse either a hex number or an address tag for storage values."""
+    if not isinstance(value, str):
+        # Non-string values should be converted to HexNumber normally
+        return HexNumber(parse_hex_number(value))
+
+    # Check if it matches address tag pattern: <type:name:0xaddress> or <type:0xaddress>
+    tag_pattern = r"^<(eoa|contract):.+>$"
+    if re.match(tag_pattern, value.strip()):
+        # Return the tag string as-is for later resolution
+        return value.strip()
+    else:
+        # Parse as hex number
+        return HexNumber(parse_hex_number(value))
+
+
 def parse_args_from_string_into_array(stream: str, pos: int, delim: str = " "):
     """Parse YUL options into array."""
     args = []
@@ -186,7 +204,121 @@ def parse_code_label(code) -> CodeInFillerSource:
     return CodeInFillerSource(code, label)
 
 
+class AddressTag:
+    """Represents an address tag like <eoa:sender> or <contract:token>."""
+
+    def __init__(self, tag_type: str, tag_name: str, original_string: str):
+        """Initialize address tag."""
+        self.tag_type = tag_type  # "eoa" or "contract"
+        self.tag_name = tag_name  # e.g., "sender", "token"
+        self.original_string = original_string
+
+    def __str__(self) -> str:
+        """Return original tag string."""
+        return self.original_string
+
+    def __repr__(self) -> str:
+        """Return debug representation."""
+        return f"AddressTag(type={self.tag_type}, name={self.tag_name})"
+
+    def __eq__(self, other) -> bool:
+        """Check equality based on original string."""
+        if isinstance(other, AddressTag):
+            return self.original_string == other.original_string
+        return False
+
+    def __hash__(self) -> int:
+        """Hash based on original string for use as dict key."""
+        return hash(self.original_string)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: Any, handler) -> core_schema.CoreSchema:
+        """Pydantic core schema for AddressTag."""
+        return core_schema.str_schema()
+
+
+def parse_address_or_tag(value: Any) -> Union[Address, AddressTag]:
+    """Parse either a regular address or an address tag."""
+    if not isinstance(value, str):
+        # Non-string values should be converted to Address normally
+        return Address(value, left_padding=True)
+
+    # Check if it matches tag pattern:
+    # - <eoa:0x...> or <contract:0x...>
+    # - <eoa:name:0x...> or <contract:name:0x...>
+    tag_pattern = r"^<(eoa|contract):(.+)>$"
+    match = re.match(tag_pattern, value.strip())
+
+    if match:
+        tag_type = match.group(1)
+        # The tag_name is everything after the type and colon
+        # Could be "0x1234..." or "sender:0x1234..."
+        tag_name = match.group(2)
+
+        return AddressTag(tag_type, tag_name, value.strip())
+    else:
+        # Regular address string
+        return Address(value, left_padding=True)
+
+
+def parse_address_or_tag_for_access_list(value: Any) -> Union[Address, str]:
+    """
+    Parse either a regular address or an address tag, keeping tags as strings for later
+    resolution.
+    """
+    if not isinstance(value, str):
+        # Non-string values should be converted to Address normally
+        return Address(value, left_padding=True)
+
+    # Check if it matches a tag pattern
+    tag_pattern = r"^<(eoa|contract):.+>$"
+    if re.match(tag_pattern, value.strip()):
+        # Return the tag string as-is for later resolution
+        return value.strip()
+    else:
+        # Regular address string
+        return Address(value, left_padding=True)
+
+
+def validate_address_or_tag_string(value: Union[Address, str]) -> Union[Address, str]:
+    """Validate and normalize address or tag as string for later resolution."""
+    if isinstance(value, str):
+        return value.strip()
+    else:
+        return Address(value, left_padding=True)
+
+
+def parse_hash32_or_sender_key_tag(value: Any) -> Union[Hash, str]:
+    """Parse either a regular hash or a sender key tag for later resolution."""
+    if isinstance(value, str) and value.strip().startswith("<sender:key:"):
+        return value.strip()
+    return Hash(value, left_padding=True)
+
+
 AddressInFiller = Annotated[Address, BeforeValidator(lambda a: Address(a, left_padding=True))]
+AddressOrTagInFiller = Annotated[
+    Union[Address, str], BeforeValidator(validate_address_or_tag_string)
+]
+ValueOrTagInFiller = Annotated[Union[HexNumber, str], BeforeValidator(parse_value_or_address_tag)]
+Hash32OrTagInFiller = Annotated[Union[Hash, str], BeforeValidator(parse_hash32_or_sender_key_tag)]
 ValueInFiller = Annotated[HexNumber, BeforeValidator(parse_hex_number)]
 CodeInFiller = Annotated[CodeInFillerSource, BeforeValidator(parse_code_label)]
 Hash32InFiller = Annotated[Hash, BeforeValidator(lambda h: Hash(h, left_padding=True))]
+
+
+class AccessListInFiller(BaseModel):
+    """Access List for transactions in fillers that can contain address tags."""
+
+    address: Union[Address, str]  # Can be an address or a tag string
+    storage_keys: List[Hash] = Field([], alias="storageKeys")
+
+    @field_validator("address", mode="before")
+    @classmethod
+    def validate_address(cls, v):
+        """Allow both addresses and tags."""
+        return parse_address_or_tag_for_access_list(v)
+
+    class Config:
+        """Model config."""
+
+        populate_by_name = True

src/ethereum_test_specs/static_state/common/common.py

@@ -9,7 +9,7 @@
 from ethereum_test_exceptions import TransactionExceptionInstanceOrList
 from ethereum_test_forks import get_forks
 
-from .common import AddressInFiller, CodeInFiller, ValueInFiller
+from .common import AddressOrTagInFiller, CodeInFiller, ValueInFiller, ValueOrTagInFiller
 
 
 class Indexes(BaseModel):
@@ -31,7 +31,7 @@ class AccountInExpectSection(BaseModel):
     balance: ValueInFiller | None = Field(None)
     code: CodeInFiller | None = Field(None)
     nonce: ValueInFiller | None = Field(None)
-    storage: Dict[ValueInFiller, ValueInFiller | Literal["ANY"]] | None = Field(None)
+    storage: Dict[ValueOrTagInFiller, ValueOrTagInFiller | Literal["ANY"]] | None = Field(None)
     expected_to_not_exist: str | int | None = Field(None, alias="shouldnotexist")
 
     class Config:
@@ -108,7 +108,7 @@ class ExpectSectionInStateTestFiller(CamelModel):
 
     indexes: Indexes = Field(default_factory=Indexes)
     network: List[str]
-    result: Dict[AddressInFiller, AccountInExpectSection]
+    result: Dict[AddressOrTagInFiller, AccountInExpectSection]
     expect_exception: Dict[str, TransactionExceptionInstanceOrList] | None = None
 
     class Config:

src/ethereum_test_specs/static_state/expect_section.py

@@ -4,16 +4,23 @@
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 
-from ethereum_test_base_types import AccessList, Hash
+from ethereum_test_base_types import Hash
 
-from .common import AddressInFiller, CodeInFiller, Hash32InFiller, ValueInFiller
+from .common import (
+    AccessListInFiller,
+    AddressOrTagInFiller,
+    CodeInFiller,
+    Hash32InFiller,
+    Hash32OrTagInFiller,
+    ValueInFiller,
+)
 
 
 class DataWithAccessList(BaseModel):
     """Class that represents data with access list."""
 
     data: CodeInFiller
-    access_list: List[AccessList] | None = Field(None, alias="accessList")
+    access_list: List[AccessListInFiller] | None = Field(None, alias="accessList")
 
     class Config:
         """Model Config."""
@@ -47,9 +54,9 @@ class GeneralTransactionInFiller(BaseModel):
     gas_limit: List[ValueInFiller] = Field(..., alias="gasLimit")
     gas_price: ValueInFiller | None = Field(None, alias="gasPrice")
     nonce: ValueInFiller
-    to: AddressInFiller | None
+    to: AddressOrTagInFiller | None
     value: List[ValueInFiller]
-    secret_key: Hash32InFiller = Field(..., alias="secretKey")
+    secret_key: Hash32OrTagInFiller = Field(..., alias="secretKey")
 
     max_fee_per_gas: ValueInFiller | None = Field(None, alias="maxFeePerGas")
     max_priority_fee_per_gas: ValueInFiller | None = Field(None, alias="maxPriorityFeePerGas")