feat(types,forks,fixtures,specs): EIP-7691: Add blob schedule

Co-authored-by: danceratopz <[email protected]>

Author: 2 people

docs/CHANGELOG.md

@@ -80,6 +80,7 @@ Release tarball changes:
 - ✨ Allow verification of the transaction receipt on executed test transactions ([#1068](https://github.com/ethereum/execution-spec-tests/pull/1068)).
 - ✨ Modify `valid_at_transition_to` marker to add keyword arguments `subsequent_transitions` and `until` to fill a test using multiple transition forks ([#1081](https://github.com/ethereum/execution-spec-tests/pull/1081)).
 - 🐞 fix(consume): use `"HIVE_CHECK_LIVE_PORT"` to signal hive to wait for port 8551 (Engine API port) instead of the 8545 port when running `consume engine` ([#1095](https://github.com/ethereum/execution-spec-tests/pull/1095)).
+- ✨ `state_test`, `blockchain_test` and `blockchain_test_engine` fixtures now contain the `blobSchedule` from [EIP-7840](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7840.md), only for tests filled for Cancun and Prague forks ([#1040](https://github.com/ethereum/execution-spec-tests/pull/1040)).
 
 ### 🔧 EVM Tools
 
@@ -107,6 +108,7 @@ Release tarball changes:
 - The EOF fixture format contained in `eof_tests` may now contain multiple exceptions in the `"exception"` field in the form of a pipe (`|`) separated string ([#759](https://github.com/ethereum/execution-spec-tests/pull/759)).
 - Remove redundant tests within stable and develop fixture releases, moving them to a separate legacy release ([#788](https://github.com/ethereum/execution-spec-tests/pull/788)).
 - Ruff now replaces Flake8, Isort and Black resulting in significant changes to the entire code base including its usage ([#922](https://github.com/ethereum/execution-spec-tests/pull/922)).
+- `state_test`, `blockchain_test` and `blockchain_test_engine` fixtures now contain a `config` field, which contains an object that contains a `blobSchedule` field. On the `blockchain_test` and `blockchain_test_engine` fixtures, the object also contains a duplicate of the `network` root field. The root's `network` field will be eventually deprecated ([#1040](https://github.com/ethereum/execution-spec-tests/pull/1040)).
 
 ## [v3.0.0](https://github.com/ethereum/execution-spec-tests/releases/tag/v3.0.0) - 2024-07-22
 

docs/consuming_tests/blockchain_test.md

@@ -98,6 +98,10 @@ Chain configuration object to be applied to the client running the blockchain te
 
 Fork configuration for the test. It is guaranteed that this field contains the same value as the root field `network`.
 
+#### - `blobSchedule`: [`BlobSchedule`](./common_types.md#blobschedule-mappingforkforkblobschedule)
+
+Optional; present from Cancun on. Maps forks to their blob schedule configurations as defined by [EIP-7840](https://eips.ethereum.org/EIPS/eip-7840).
+
 ### `FixtureHeader`
 
 #### - `parentHash`: [`Hash`](./common_types.md#hash)

docs/consuming_tests/blockchain_test_engine.md

@@ -85,6 +85,10 @@ Chain configuration object to be applied to the client running the blockchain en
 
 Fork configuration for the test. It is guaranteed that this field contains the same value as the root field `network`.
 
+#### - `blobSchedule`: [`BlobSchedule`](./common_types.md#blobschedule-mappingforkforkblobschedule)
+
+Optional; present from Cancun on. Maps forks to their blob schedule configurations as defined by [EIP-7840](https://eips.ethereum.org/EIPS/eip-7840).
+
 ### `FixtureEngineNewPayload`
 
 #### - `executionPayload`: [`FixtureExecutionPayload`](#fixtureexecutionpayload)

docs/consuming_tests/common_types.md

@@ -82,6 +82,26 @@ Storage of the account.
 
 State allocation represented as a JSON object, where the keys are the addresses of the accounts, and the values are the accounts.
 
+### `BlobSchedule`: [`Mapping`](#mapping)`[`[`Fork`](#fork)`,`[`ForkBlobSchedule`](#forkblobschedule)`]`
+
+Maps forks to blob schedule configurations as defined by [EIP-7840](https://eips.ethereum.org/EIPS/eip-7840).
+
+### `ForkBlobSchedule`
+
+A fork blob schedule as defined by [EIP-7840](https://eips.ethereum.org/EIPS/eip-7840) as a JSON dictionary with the following entries:
+
+#### - `target`: [`ZeroPaddedHexNumber`](#zeropaddedhexnumber)
+
+The target blob count for a block.
+
+#### - `max`: [`ZeroPaddedHexNumber`](#zeropaddedhexnumber)
+
+The maximum possible blob count for a block.
+
+#### - `base_fee_update_fraction`: [`ZeroPaddedHexNumber`](#zeropaddedhexnumber)
+
+The blob base fee update fraction (adjusts the responsiveness of blob gas pricing per fork).
+
 ## Fork
 
 Fork type is represented as a JSON string that can be set to one of the following values:

docs/consuming_tests/state_test.md

@@ -66,7 +66,11 @@ Chain configuration object.
 
 ### `FixtureConfig`
 
-At the moment, this object is an empty dictionary and contains no fields.
+At the moment this object can contain only the `blobSchedule` that is necessary to apply the correct cap to the maximum amount of blobs that a transaction can have. Otherwise, in forks prior to Cancun for example, it will be an empty JSON object.
+
+#### - `blobSchedule`: [`BlobSchedule`](./common_types.md#blobschedule-mappingforkforkblobschedule)
+
+Optional; present from Cancun on. Maps forks to their blob schedule configurations as defined by [EIP-7840](https://eips.ethereum.org/EIPS/eip-7840).
 
 ### `FixtureEnvironment`
 

src/ethereum_test_base_types/__init__.py

@@ -16,7 +16,15 @@
     Wei,
     ZeroPaddedHexNumber,
 )
-from .composite_types import AccessList, Account, Alloc, Storage, StorageRootType
+from .composite_types import (
+    AccessList,
+    Account,
+    Alloc,
+    BlobSchedule,
+    ForkBlobSchedule,
+    Storage,
+    StorageRootType,
+)
 from .constants import (
     AddrAA,
     AddrBB,
@@ -39,16 +47,18 @@
     "AddrBB",
     "Address",
     "Alloc",
+    "BlobSchedule",
     "Bloom",
     "BLSPublicKey",
     "BLSSignature",
     "Bytes",
     "CamelModel",
     "EmptyOmmersRoot",
     "EmptyTrieRoot",
-    "FixedSizeBytes",
     "EthereumTestBaseModel",
     "EthereumTestRootModel",
+    "FixedSizeBytes",
+    "ForkBlobSchedule",
     "Hash",
     "HashInt",
     "HeaderNonce",

src/ethereum_test_base_types/composite_types.py

@@ -462,3 +462,29 @@ class AccessList(CamelModel):
     def to_list(self) -> List[Address | List[Hash]]:
         """Return access list as a list of serializable elements."""
         return [self.address, self.storage_keys]
+
+
+class ForkBlobSchedule(CamelModel):
+    """Representation of the blob schedule of a given fork."""
+
+    target_blobs_per_block: HexNumber = Field(..., alias="target")
+    max_blobs_per_block: HexNumber = Field(..., alias="max")
+    base_fee_update_fraction: HexNumber = Field(...)
+
+
+class BlobSchedule(EthereumTestRootModel[Dict[str, ForkBlobSchedule]]):
+    """Blob schedule configuration dictionary."""
+
+    root: Dict[str, ForkBlobSchedule] = Field(default_factory=dict, validate_default=True)
+
+    def append(self, *, fork: str, schedule: Any):
+        """Append a new fork schedule."""
+        if not isinstance(schedule, ForkBlobSchedule):
+            schedule = ForkBlobSchedule(**schedule)
+        self.root[fork] = schedule
+
+    def last(self) -> ForkBlobSchedule | None:
+        """Return the last schedule."""
+        if len(self.root) == 0:
+            return None
+        return list(self.root.values())[-1]

src/ethereum_test_fixtures/blockchain.py

@@ -43,6 +43,7 @@
 )
 
 from .base import BaseFixture
+from .common import FixtureBlobSchedule
 
 
 class HeaderForkRequirement(str):
@@ -400,6 +401,7 @@ class FixtureConfig(CamelModel):
     """Chain configuration for a fixture."""
 
     fork: str = Field(..., alias="network")
+    blob_schedule: FixtureBlobSchedule | None = None
 
 
 class InvalidFixtureBlock(CamelModel):

src/ethereum_test_fixtures/common.py

@@ -0,0 +1,37 @@
+"""Common types used to define multiple fixture types."""
+
+from typing import Dict
+
+from pydantic import Field
+
+from ethereum_test_base_types import (
+    BlobSchedule,
+    CamelModel,
+    EthereumTestRootModel,
+    ZeroPaddedHexNumber,
+)
+
+
+class FixtureForkBlobSchedule(CamelModel):
+    """Representation of the blob schedule of a given fork."""
+
+    target_blobs_per_block: ZeroPaddedHexNumber = Field(..., alias="target")
+    max_blobs_per_block: ZeroPaddedHexNumber = Field(..., alias="max")
+    base_fee_update_fraction: ZeroPaddedHexNumber = Field(...)
+
+
+class FixtureBlobSchedule(EthereumTestRootModel[Dict[str, FixtureForkBlobSchedule]]):
+    """Blob schedule configuration dictionary."""
+
+    root: Dict[str, FixtureForkBlobSchedule] = Field(default_factory=dict, validate_default=True)
+
+    @classmethod
+    def from_blob_schedule(
+        cls, blob_schedule: BlobSchedule | None
+    ) -> "FixtureBlobSchedule | None":
+        """Return a FixtureBlobSchedule from a BlobSchedule."""
+        if blob_schedule is None:
+            return None
+        return cls(
+            root=blob_schedule.model_dump(),
+        )

src/ethereum_test_fixtures/state.py

@@ -4,7 +4,14 @@
 
 from pydantic import BaseModel, Field
 
-from ethereum_test_base_types import AccessList, Address, Alloc, Bytes, Hash, ZeroPaddedHexNumber
+from ethereum_test_base_types import (
+    AccessList,
+    Address,
+    Alloc,
+    Bytes,
+    Hash,
+    ZeroPaddedHexNumber,
+)
 from ethereum_test_exceptions import TransactionExceptionInstanceOrList
 from ethereum_test_types.types import (
     AuthorizationTupleGeneric,
@@ -15,6 +22,7 @@
 )
 
 from .base import BaseFixture
+from .common import FixtureBlobSchedule
 
 
 class FixtureEnvironment(EnvironmentGeneric[ZeroPaddedHexNumber]):
@@ -89,7 +97,7 @@ class FixtureForkPost(CamelModel):
 class FixtureConfig(CamelModel):
     """Chain configuration for a fixture."""
 
-    pass
+    blob_schedule: FixtureBlobSchedule | None = None
 
 
 class StateFixture(BaseFixture):