feature: Add engine API execution payload information in fixtures

src/ethereum_test_forks/base_fork.py

@@ -2,7 +2,7 @@
 Abstract base class for Ethereum forks
 """
 from abc import ABC, ABCMeta, abstractmethod
-from typing import Type
+from typing import Optional, Type
 
 
 class BaseForkMeta(ABCMeta):
@@ -30,6 +30,7 @@ class BaseFork(ABC, metaclass=BaseForkMeta):
     Must contain all the methods used by every fork.
     """
 
+    # Header information abstract methods
     @classmethod
     @abstractmethod
     def header_base_fee_required(cls, block_number: int, timestamp: int) -> bool:
@@ -86,6 +87,25 @@ def get_reward(cls, block_number: int, timestamp: int) -> int:
         """
         pass
 
+    # Engine API information abstract methods
+    @classmethod
+    @abstractmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        Returns `None` if this fork's payloads cannot be sent over the engine API,
+        or the payload version if it can.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def engine_new_payload_blob_hashes(cls, block_number: int, timestamp: int) -> bool:
+        """
+        Returns true if the engine api version requires new payload calls to include blob hashes.
+        """
+        pass
+
+    # Meta information about the fork
     @classmethod
     def name(cls) -> str:
         """

src/ethereum_test_forks/forks/forks.py

@@ -1,6 +1,8 @@
 """
 All Ethereum fork class definitions.
 """
+from typing import Optional
+
 from ..base_fork import BaseFork
 
 
@@ -52,6 +54,20 @@ def header_data_gas_used_required(cls, block_number: int, timestamp: int) -> boo
         """
         return False
 
+    @classmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        At genesis, payloads cannot be sent through the engine API
+        """
+        return None
+
+    @classmethod
+    def engine_new_payload_blob_hashes(cls, block_number: int, timestamp: int) -> bool:
+        """
+        At genesis, payloads do not have blob hashes.
+        """
+        return False
+
     @classmethod
     def get_reward(cls, block_number: int, timestamp: int) -> int:
         """
@@ -186,6 +202,13 @@ def get_reward(cls, block_number: int, timestamp: int) -> int:
         """
         return 0
 
+    @classmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        Starting at the merge, payloads can be sent through the engine API
+        """
+        return 1
+
 
 class Shanghai(Merge):
     """
@@ -199,6 +222,13 @@ def header_withdrawals_required(cls, block_number: int, timestamp: int) -> bool:
         """
         return True
 
+    @classmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        Starting at Shanghai, new payload calls must use version 2
+        """
+        return 2
+
 
 class Cancun(Shanghai):
     """
@@ -226,3 +256,17 @@ def header_data_gas_used_required(cls, block_number: int, timestamp: int) -> boo
         Data gas used is required starting from Cancun.
         """
         return True
+
+    @classmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        Starting at Cancun, new payload calls must use version 3
+        """
+        return 3
+
+    @classmethod
+    def engine_new_payload_blob_hashes(cls, block_number: int, timestamp: int) -> bool:
+        """
+        Starting at Cancun, payloads must have blob hashes.
+        """
+        return True

src/ethereum_test_forks/forks/transition.py

@@ -1,6 +1,8 @@
 """
 List of all transition fork definitions.
 """
+from typing import Optional
+
 from ..transition_base_fork import transition_fork
 from .forks import Berlin, Cancun, London, Merge, Shanghai
 
@@ -33,6 +35,13 @@ def header_withdrawals_required(cls, _: int, timestamp: int) -> bool:
         """
         return timestamp >= 15_000
 
+    @classmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        Starting at Shanghai, new payload calls must use version 2
+        """
+        return 2 if timestamp >= 15_000 else 1
+
 
 @transition_fork(to_fork=Cancun)
 class ShanghaiToCancunAtTime15k(Shanghai):
@@ -46,3 +55,17 @@ def header_excess_data_gas_required(cls, _: int, timestamp: int) -> bool:
         Excess data gas is required if transitioning to Cancun.
         """
         return timestamp >= 15_000
+
+    @classmethod
+    def engine_new_payload_version(cls, block_number: int, timestamp: int) -> Optional[int]:
+        """
+        Starting at Cancun, new payload calls must use version 3
+        """
+        return 3 if timestamp >= 15_000 else 2
+
+    @classmethod
+    def engine_new_payload_blob_hashes(cls, block_number: int, timestamp: int) -> bool:
+        """
+        Starting at Cancun, payloads must have blob hashes.
+        """
+        return timestamp >= 15_000

src/ethereum_test_tools/__init__.py

@@ -9,8 +9,10 @@
     Account,
     Auto,
     Block,
+    EngineAPIError,
     Environment,
     Fixture,
+    FixtureEngineNewPayload,
     Header,
     JSONEncoder,
     Storage,
@@ -46,8 +48,10 @@
     "BlockchainTestFiller",
     "Code",
     "CodeGasMeasure",
+    "EngineAPIError",
     "Environment",
     "Fixture",
+    "FixtureEngineNewPayload",
     "Header",
     "Initcode",
     "JSONEncoder",

src/ethereum_test_tools/common/__init__.py

@@ -5,6 +5,7 @@
     AddrAA,
     AddrBB,
     EmptyTrieRoot,
+    EngineAPIError,
     TestAddress,
     TestAddress2,
     TestPrivateKey,
@@ -30,6 +31,7 @@
     Environment,
     Fixture,
     FixtureBlock,
+    FixtureEngineNewPayload,
     FixtureHeader,
     Header,
     JSONEncoder,
@@ -51,10 +53,12 @@
     "AddrBB",
     "Auto",
     "Block",
+    "EngineAPIError",
     "EmptyTrieRoot",
     "Environment",
     "Fixture",
     "FixtureBlock",
+    "FixtureEngineNewPayload",
     "FixtureHeader",
     "Header",
     "JSONEncoder",

src/ethereum_test_tools/common/constants.py

@@ -2,6 +2,8 @@
 Common values used in Ethereum tests.
 """
 
+from enum import IntEnum
+
 TestAddress = "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b"
 TestAddress2 = "0x8a0A19589531694250d570040a0c4B74576919B8"
 
@@ -17,3 +19,21 @@
 EmptyHash = bytes([0] * 32)
 EmptyNonce = bytes([0] * 8)
 ZeroAddress = bytes([0] * 20)
+
+
+class EngineAPIError(IntEnum):
+    """
+    List of Engine API errors
+    """
+
+    ParseError = -32700
+    InvalidRequest = -32600
+    MethodNotFound = -32601
+    InvalidParams = -32602
+    InternalError = -32603
+    ServerError = -32000
+    UnknownPayload = -38001
+    InvalidForkchoiceState = -38002
+    InvalidPayloadAttributes = -38003
+    TooLargeRequest = -38004
+    UnsupportedFork = -38005