refactor(all): update lang from 'shared pre-alloc' to 'pre-allocation groups' 2/2

Author: danceratopz

docs/CHANGELOG.md

@@ -31,7 +31,7 @@ Users can select any of the artifacts depending on their testing needs for their
 
 - ✨ Add the `ported_from` test marker to track Python test cases that were converted from static fillers in [ethereum/tests](https://github.com/ethereum/tests) repository [#1590](https://github.com/ethereum/execution-spec-tests/pull/1590).
 - ✨ Add a new pytest plugin, `ported_tests`, that lists the static fillers and PRs from `ported_from` markers for use in the coverage Github Workflow [#1634](https://github.com/ethereum/execution-spec-tests/pull/1634).
-- ✨ Enable two-phase filling of fixtures with shared pre-allocation groups and add a `BlockchainEngineXFixture` format [#1606](https://github.com/ethereum/execution-spec-tests/pull/1706).
+- ✨ Enable two-phase filling of fixtures with pre-allocation groups and add a `BlockchainEngineXFixture` format [#1606](https://github.com/ethereum/execution-spec-tests/pull/1706).
 - 🔀 Refactor: Encapsulate `fill`'s fixture output options (`--output`, `--flat-output`, `--single-fixture-per-file`) into a `FixtureOutput` class ([#1471](https://github.com/ethereum/execution-spec-tests/pull/1471),[#1612](https://github.com/ethereum/execution-spec-tests/pull/1612)).
 - ✨ Don't warn about a "high Transaction gas_limit" for `zkevm` tests ([#1598](https://github.com/ethereum/execution-spec-tests/pull/1598)).
 - 🐞 `fill` no longer writes generated fixtures into an existing, non-empty output directory; it must now be empty or `--clean` must be used to delete it first ([#1608](https://github.com/ethereum/execution-spec-tests/pull/1608)).

docs/library/cli/extract_config.md

@@ -120,7 +120,7 @@ Since Hive doesn't directly expose container IDs, the tool uses a detection mech
 The tool supports:
 
 - Individual fixture JSON files (BlockchainFixture format)
-- SharedPreStateGroup JSON files
+- PreAllocGroup JSON files
 - Directories containing multiple fixture files
 
 ## Troubleshooting

docs/running_tests/test_formats/blockchain_test_engine_x.md

@@ -1,30 +1,30 @@
 # Blockchain Engine X Tests  <!-- markdownlint-disable MD051 (MD051=link-fragments "Link fragments should be valid") -->
 
-The Blockchain Engine X Test fixture format tests are included in the fixtures subdirectory `blockchain_tests_engine_x`, and use Engine API directives with optimized shared pre-allocation for improved execution performance.
+The Blockchain Engine X Test fixture format tests are included in the fixtures subdirectory `blockchain_tests_engine_x`, and use Engine API directives with optimized pre-allocation groups for improved execution performance.
 
-These are produced by the `StateTest` and `BlockchainTest` test specs when using the `--generate-shared-pre` and `--use-shared-pre` flags.
+These are produced by the `StateTest` and `BlockchainTest` test specs when using the `--generate-grouped-pre-allocs` and `--use-grouped-pre-allocs` flags.
 
 ## Description
 
 The Blockchain Engine X Test fixture format is an optimized variant of the [Blockchain Engine Test](./blockchain_test_engine.md) format designed for large-scale test execution with performance optimizations.
 
-It uses the Engine API to test block validation and consensus rules while leveraging **shared pre-allocation state** to significantly reduce test execution time and resource usage. Tests are grouped by their initial state (fork + environment + pre-allocation). Each groups are executed against the same client instance using a common genesis state.
+It uses the Engine API to test block validation and consensus rules while leveraging **pre-allocation groups** to significantly reduce test execution time and resource usage. Tests are grouped by their initial state (fork + environment + pre-allocation). Each group is executed against the same client instance using a common genesis state.
 
 The key optimization is that **clients need only be started once per group** instead of once per test (as in the original engine fixture format), dramatically improving execution performance for large test suites.
 
-Instead of including large pre-allocation state in each test fixture, this format references a shared pre-allocation folder (`pre_alloc`) which includes all different pre-allocation combinations used for any test fixture group.
+Instead of including large pre-allocation state in each test fixture, this format references a pre-allocation groups folder (`pre_alloc`) which contains all different pre-allocation combinations organized by group.
 
 A single JSON fixture file is composed of a JSON object where each key-value pair is a different [`BlockchainTestEngineXFixture`](#BlockchainTestEngineXFixture) test object, with the key string representing the test name.
 
 The JSON file path plus the test name are used as the unique test identifier.
 
-## Shared Pre-Allocation File
+## Pre-Allocation Groups Folder
 
-The `blockchain_tests_engine_x` directory contains a special directory `pre_alloc` that stores shared pre-allocation state file used by all tests in this format, one per pre-allocation group with the name of the pre-alloc hash. This folder is essential for test execution and must be present alongside the test fixtures.
+The `blockchain_tests_engine_x` directory contains a special directory `pre_alloc` that stores pre-allocation group files used by all tests in this format, one per pre-allocation group with the name of the pre-alloc hash. This folder is essential for test execution and must be present alongside the test fixtures.
 
-### Pre-Allocation File Structure
+### Pre-Allocation Group File Structure
 
-Each file in the `pre_alloc` folder corresponds to a pre-allocation hash to shared state groups:
+Each file in the `pre_alloc` folder corresponds to a pre-allocation group identified by a hash:
 
 ```json
 {
@@ -37,14 +37,14 @@ Each file in the `pre_alloc` folder corresponds to a pre-allocation hash to shar
 }
 ```
 
-#### SharedPreStateGroup Fields
+#### Pre-Allocation Group Fields
 
-- **`test_count`**: Number of tests sharing this pre-allocation group
-- **`pre_account_count`**: Number of accounts in the shared pre-allocation state
-- **`testIds`**: Array of test identifiers that use this shared state
+- **`test_count`**: Number of tests in this pre-allocation group
+- **`pre_account_count`**: Number of accounts in the pre-allocation group
+- **`testIds`**: Array of test identifiers that belong to this group
 - **`network`**: Fork name (e.g., "Prague", "Cancun")
 - **`environment`**: Complete [`Environment`](./common_types.md#environment) object with execution context
-- **`pre`**: Shared [`Alloc`](./common_types.md#alloc-mappingaddressaccount) object containing initial account states
+- **`pre`**: Pre-allocation group [`Alloc`](./common_types.md#alloc-mappingaddressaccount) object containing initial account states
 
 ## Consumption
 
@@ -70,7 +70,7 @@ For each [`BlockchainTestEngineXFixture`](#BlockchainTestEngineXFixture) test ob
 4. **Verify Final State**:
    - Compare the final chain head against [`lastblockhash`](#-lastblockhash-hash)
    - If [`postStateDiff`](#-poststatediff-optionalalloc) is present:
-     - Apply the state differences to the shared pre-allocation
+     - Apply the state differences to the pre-allocation group
      - Verify the resulting state matches the client's final state
    - If `post` field were present (not typical), verify it directly
 
@@ -88,11 +88,11 @@ This field is going to be replaced by the value contained in `config.network`.
 
 #### - `preHash`: `string`
 
-Hash identifier referencing a shared pre-allocation group in the `pre_alloc` folder. This hash uniquely identifies the combination of fork, environment, and pre-allocation state shared by multiple tests.
+Hash identifier referencing a pre-allocation group in the `pre_alloc` folder. This hash uniquely identifies the combination of fork, environment, and pre-allocation state that defines the group.
 
 #### - `genesisBlockHeader`: [`FixtureHeader`](./blockchain_test.md#fixtureheader)
 
-Genesis block header. The state root in this header must match the state root calculated from the shared pre-allocation referenced by [`preHash`](#-prehash-string).
+Genesis block header. The state root in this header must match the state root calculated from the pre-allocation group referenced by [`preHash`](#-prehash-string).
 
 #### - `engineNewPayloads`: [`List`](./common_types.md#list)`[`[`FixtureEngineNewPayload`](#fixtureenginenewpayload)`]`
 
@@ -108,11 +108,11 @@ Hash of the last valid block after all payloads have been processed, or the gene
 
 #### - `postStateDiff`: [`Optional`](./common_types.md#optional)`[`[`Alloc`](./common_types.md#alloc-mappingaddressaccount)`]`
 
-State differences from the shared pre-allocation state after test execution. This optimization stores only the accounts that changed, were created, or were deleted during test execution, rather than the complete final state.
+State differences from the pre-allocation group after test execution. This optimization stores only the accounts that changed, were created, or were deleted during test execution, rather than the complete final state.
 
 To reconstruct the final state:
 
-1. Start with the shared pre-allocation from the `pre_alloc` folder
+1. Start with the pre-allocation group from the `pre_alloc` folder
 2. Apply the changes in `postStateDiff`:
    - **Modified accounts**: Replace existing accounts with new values
    - **New accounts**: Add accounts not present in pre-allocation  
@@ -138,7 +138,7 @@ Engine API payload structure identical to the one defined in [Blockchain Engine
 
 ## Usage Notes
 
-- This format is only generated when using `--generate-shared-pre` and `--use-shared-pre` flags
+- This format is only generated when using `--generate-grouped-pre-allocs` and `--use-grouped-pre-allocs` flags
 - The `pre_alloc` folder is essential and must be distributed with the test fixtures
 - Tests are grouped by identical (fork + environment + pre-allocation) combinations
 - The format is optimized for Engine API testing (post-Paris forks)

src/cli/extract_config.py

@@ -21,7 +21,7 @@
 from ethereum_test_fixtures import BlockchainFixtureCommon
 from ethereum_test_fixtures.blockchain import FixtureHeader
 from ethereum_test_fixtures.file import Fixtures
-from ethereum_test_fixtures.shared_alloc import SharedPreStateGroup
+from ethereum_test_fixtures.pre_alloc_groups import PreAllocGroup
 from ethereum_test_forks import Fork
 from pytest_plugins.consume.simulators.helpers.ruleset import ruleset
 
@@ -111,9 +111,9 @@ def create_genesis_from_fixture(fixture_path: Path) -> Tuple[FixtureHeader, Allo
         alloc = fixture.pre
         chain_id = int(fixture.config.chain_id)
     else:
-        shared_alloc = SharedPreStateGroup.model_validate(fixture_json)
-        genesis = shared_alloc.genesis  # type: ignore
-        alloc = shared_alloc.pre
+        pre_alloc_group = PreAllocGroup.model_validate(fixture_json)
+        genesis = pre_alloc_group.genesis  # type: ignore
+        alloc = pre_alloc_group.pre
 
     return genesis, alloc, chain_id
 

src/cli/show_pre_alloc_group_stats.py

@@ -10,7 +10,7 @@
 from rich.table import Table
 
 from ethereum_test_base_types import CamelModel
-from ethereum_test_fixtures import SharedPreState
+from ethereum_test_fixtures import PreAllocGroups
 
 
 def extract_test_module(test_id: str) -> str:
@@ -102,22 +102,22 @@ def calculate_size_distribution(
 
 def analyze_pre_alloc_folder(folder: Path, verbose: int = 0) -> Dict:
     """Analyze pre-allocation folder and return statistics."""
-    pre_state = SharedPreState.from_folder(folder)
+    pre_alloc_groups = PreAllocGroups.from_folder(folder)
 
     # Basic stats
-    total_groups = len(pre_state)
-    total_tests = sum(group.test_count for group in pre_state.values())
-    total_accounts = sum(group.pre_account_count for group in pre_state.values())
+    total_groups = len(pre_alloc_groups)
+    total_tests = sum(group.test_count for group in pre_alloc_groups.values())
+    total_accounts = sum(group.pre_account_count for group in pre_alloc_groups.values())
 
     # Group by fork
     fork_stats: Dict[str, Dict] = defaultdict(lambda: {"groups": 0, "tests": 0})
-    for group in pre_state.values():
+    for group in pre_alloc_groups.values():
         fork_stats[group.fork.name()]["groups"] += 1
         fork_stats[group.fork.name()]["tests"] += group.test_count
 
     # Group by test module
     module_stats: Dict[str, Dict] = defaultdict(lambda: {"groups": set(), "tests": 0})
-    for hash_key, group in pre_state.items():
+    for hash_key, group in pre_alloc_groups.items():
         # Count tests per module in this group
         module_test_count: defaultdict = defaultdict(int)
         for test_id in group.test_ids:
@@ -135,7 +135,7 @@ def analyze_pre_alloc_folder(folder: Path, verbose: int = 0) -> Dict:
 
     # Per-group details
     group_details = []
-    for hash_key, group in pre_state.items():
+    for hash_key, group in pre_alloc_groups.items():
         group_details.append(
             {
                 "hash": hash_key[:8] + "...",  # Shortened hash for display
@@ -158,7 +158,7 @@ class SplitTestFunction(CamelModel):
     split_test_functions: Dict[str, SplitTestFunction] = defaultdict(lambda: SplitTestFunction())
 
     # Process all size-1 groups directly from pre_state
-    for _hash_key, group_data in pre_state.items():
+    for _hash_key, group_data in pre_alloc_groups.items():
         if group_data.test_count == 1:  # Size-1 group
             test_id = group_data.test_ids[0]
             test_function = extract_test_function(test_id)

src/ethereum_test_fixtures/__init__.py

@@ -11,7 +11,7 @@
 from .collector import FixtureCollector, TestInfo
 from .consume import FixtureConsumer
 from .eof import EOFFixture
-from .shared_alloc import SharedPreState, SharedPreStateGroup
+from .pre_alloc_groups import PreAllocGroup, PreAllocGroups
 from .state import StateFixture
 from .transaction import TransactionFixture
 
@@ -27,8 +27,8 @@
     "FixtureConsumer",
     "FixtureFormat",
     "LabeledFixtureFormat",
-    "SharedPreState",
-    "SharedPreStateGroup",
+    "PreAllocGroups",
+    "PreAllocGroup",
     "StateFixture",
     "TestInfo",
     "TransactionFixture",

src/ethereum_test_fixtures/blockchain.py

@@ -523,7 +523,7 @@ class BlockchainEngineFixtureCommon(BaseFixture):
     Base blockchain test fixture model for Engine API based execution.
 
     Similar to BlockchainFixtureCommon but excludes the 'pre' field to avoid
-    duplicating large pre-allocations when using shared genesis approaches.
+    duplicating large pre-allocations.
     """
 
     fork: Fork = Field(..., alias="network")
@@ -564,15 +564,15 @@ class BlockchainEngineXFixture(BlockchainEngineFixtureCommon):
     """
     Engine X specific test fixture information.
 
-    Uses shared pre-allocations (and a shared client instance) for efficient
+    Uses pre-allocation groups (and a single client instance) for efficient
     test execution without client restarts.
     """
 
     format_name: ClassVar[str] = "blockchain_test_engine_x"
     description: ClassVar[str] = "Tests that generate a Blockchain Test Engine X fixture."
 
     pre_hash: str
-    """Hash of the shared pre-allocation group this test belongs to."""
+    """Hash of the pre-allocation group this test belongs to."""
 
     post_state_diff: Alloc | None = None
     """State difference from genesis after test execution (efficiency optimization)."""

src/ethereum_test_fixtures/shared_alloc.py renamed to src/ethereum_test_fixtures/pre_alloc_groups.py

@@ -13,7 +13,7 @@
 from .blockchain import FixtureHeader
 
 
-class SharedPreStateGroup(CamelModel):
+class PreAllocGroup(CamelModel):
     """
     Pre-allocation group for tests with identical Environment and fork values.
 
@@ -49,45 +49,43 @@ def genesis(self) -> FixtureHeader:
         )
 
     def to_file(self, file: Path) -> None:
-        """Save SharedPreStateGroup to a file."""
+        """Save PreAllocGroup to a file."""
         lock_file_path = file.with_suffix(".lock")
         with FileLock(lock_file_path):
             if file.exists():
                 with open(file, "r") as f:
-                    previous_shared_pre_state_group = SharedPreStateGroup.model_validate_json(
-                        f.read()
-                    )
-                    for account in previous_shared_pre_state_group.pre:
+                    previous_pre_alloc_group = PreAllocGroup.model_validate_json(f.read())
+                    for account in previous_pre_alloc_group.pre:
                         if account not in self.pre:
-                            self.pre[account] = previous_shared_pre_state_group.pre[account]
-                    self.pre_account_count += previous_shared_pre_state_group.pre_account_count
-                    self.test_count += previous_shared_pre_state_group.test_count
-                    self.test_ids.extend(previous_shared_pre_state_group.test_ids)
+                            self.pre[account] = previous_pre_alloc_group.pre[account]
+                    self.pre_account_count += previous_pre_alloc_group.pre_account_count
+                    self.test_count += previous_pre_alloc_group.test_count
+                    self.test_ids.extend(previous_pre_alloc_group.test_ids)
 
             with open(file, "w") as f:
                 f.write(self.model_dump_json(by_alias=True, exclude_none=True, indent=2))
 
 
-class SharedPreState(EthereumTestRootModel):
-    """Root model mapping pre-state hashes to test groups."""
+class PreAllocGroups(EthereumTestRootModel):
+    """Root model mapping pre-allocation group hashes to test groups."""
 
-    root: Dict[str, SharedPreStateGroup]
+    root: Dict[str, PreAllocGroup]
 
     def __setitem__(self, key: str, value: Any):
         """Set item in root dict."""
         self.root[key] = value
 
     @classmethod
-    def from_folder(cls, folder: Path) -> "SharedPreState":
-        """Create SharedPreState from a folder of pre-allocation files."""
+    def from_folder(cls, folder: Path) -> "PreAllocGroups":
+        """Create PreAllocGroups from a folder of pre-allocation files."""
         data = {}
         for file in folder.glob("*.json"):
             with open(file) as f:
-                data[file.stem] = SharedPreStateGroup.model_validate_json(f.read())
+                data[file.stem] = PreAllocGroup.model_validate_json(f.read())
         return cls(root=data)
 
     def to_folder(self, folder: Path) -> None:
-        """Save SharedPreState to a folder of pre-allocation files."""
+        """Save PreAllocGroups to a folder of pre-allocation files."""
         for key, value in self.root.items():
             value.to_file(folder / f"{key}.json")