ethereum
diff --git a/‎docs/CHANGELOG.md
Lines changed: 1 addition & 0 deletions b/‎docs/CHANGELOG.md
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/navigation.md
Lines changed: 1 addition & 0 deletions b/‎docs/navigation.md
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/running_tests/test_formats/blockchain_test_engine_reorg.md
Lines changed: 145 additions & 0 deletions b/‎docs/running_tests/test_formats/blockchain_test_engine_reorg.md
Lines changed: 145 additions & 0 deletions
diff --git a/‎pyproject.toml
Lines changed: 1 addition & 0 deletions b/‎pyproject.toml
Lines changed: 1 addition & 0 deletions
diff --git a/‎pytest-execute.ini
Lines changed: 1 addition & 0 deletions b/‎pytest-execute.ini
Lines changed: 1 addition & 0 deletions
diff --git a/‎pytest.ini
Lines changed: 1 addition & 0 deletions b/‎pytest.ini
Lines changed: 1 addition & 0 deletions
diff --git a/‎src/cli/gen_index.py
Lines changed: 15 additions & 6 deletions b/‎src/cli/gen_index.py
Lines changed: 15 additions & 6 deletions
diff --git a/‎src/cli/pytest_commands/base.py
Lines changed: 4 additions & 2 deletions b/‎src/cli/pytest_commands/base.py
Lines changed: 4 additions & 2 deletions
diff --git a/‎src/cli/pytest_commands/fill.py
Lines changed: 128 additions & 0 deletions b/‎src/cli/pytest_commands/fill.py
Lines changed: 128 additions & 0 deletions
@@ -31,6 +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 `BlockchainEngineReorgFixture` 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)).
 
@@ -41,6 +41,7 @@
           * [State Tests](running_tests/test_formats/state_test.md)
           * [Blockchain Tests](running_tests/test_formats/blockchain_test.md)
           * [Blockchain Engine Tests](running_tests/test_formats/blockchain_test_engine.md)
+          * [Blockchain Engine Reorg Tests](running_tests/test_formats/blockchain_test_engine_reorg.md)
           * [EOF Tests](running_tests/test_formats/eof_test.md)
           * [Transaction Tests](running_tests/test_formats/transaction_test.md)
           * [Common Types](running_tests/test_formats/common_types.md)
 
@@ -0,0 +1,145 @@
+# Blockchain Engine Reorg Tests  <!-- markdownlint-disable MD051 (MD051=link-fragments "Link fragments should be valid") -->
+
+The Blockchain Engine Reorg Test fixture format tests are included in the fixtures subdirectory `blockchain_tests_engine_reorg`, and use Engine API directives with optimized shared pre-allocation 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.
+
+## Description
+
+The Blockchain Engine Reorg 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) and share common genesis states through blockchain reorganization.
+
+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.
+
+A single JSON fixture file is composed of a JSON object where each key-value pair is a different [`ReorgFixture`](#reorgfixture) 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
+
+The `blockchain_tests_engine_reorg` 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.
+
+### Pre-Allocation File Structure
+
+Each file in the `pre_alloc` folder corresponds to a pre-allocation hash to shared state groups:
+
+```json
+{
+   "test_count": 88,
+   "pre_account_count": 174,
+   "testIds": ["test1", "test2", ...],
+   "network": "Prague",
+   "environment": { ... },
+   "pre": { ... }
+}
+```
+
+#### SharedPreStateGroup 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
+- **`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
+
+## Consumption
+
+For each [`ReorgFixture`](#reorgfixture) test object in the JSON fixture file, perform the following steps:
+
+1. **Load Shared Pre-Allocation**:
+   - Read the appropriate file from the `pre_alloc` folder in the same directory
+   - Locate the shared state group using [`preHash`](#-prehash-string)
+   - Extract the `pre` allocation and `environment` from the shared group
+
+2. **Initialize Client**:
+   - Use [`network`](#-network-fork) to configure the execution fork schedule
+   - Use the shared `pre` allocation as the starting state
+   - Use the shared `environment` as the execution context
+   - Use [`genesisBlockHeader`](#-genesisblockheader-fixtureheader) as the genesis block header
+
+3. **Execute Engine API Sequence**:
+   - For each [`FixtureEngineNewPayload`](#fixtureenginenewpayload) in [`engineNewPayloads`](#-enginenewpayloads-listfixtureenginenewpayload):
+     1. Deliver the payload using `engine_newPayloadVX`
+     2. Validate the response according to the payload's expected status
+   - If [`syncPayload`](#-syncpayload-optionalfixtureenginenewpayload) is present, execute it for chain synchronization
+
+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
+     - Verify the resulting state matches the client's final state
+   - If `post` field were present (not typical), verify it directly
+
+## Structures
+
+### `ReorgFixture`
+
+#### - `network`: [`Fork`](./common_types.md#fork)
+
+##### TO BE DEPRECATED
+
+Fork configuration for the test.
+
+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.
+
+#### - `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).
+
+#### - `engineNewPayloads`: [`List`](./common_types.md#list)`[`[`FixtureEngineNewPayload`](#fixtureenginenewpayload)`]`
+
+List of `engine_newPayloadVX` directives to be processed after the genesis block. These define the sequence of blocks to be executed via the Engine API.
+
+#### - `syncPayload`: [`Optional`](./common_types.md#optional)`[`[`FixtureEngineNewPayload`](#fixtureenginenewpayload)`]`
+
+Optional synchronization payload used for blockchain reorganization scenarios. When present, this payload is typically used to sync the chain to a specific state before or after the main payload sequence.
+
+#### - `lastblockhash`: [`Hash`](./common_types.md#hash)
+
+Hash of the last valid block after all payloads have been processed, or the genesis block hash if all payloads are invalid.
+
+#### - `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.
+
+To reconstruct the final state:
+
+1. Start with the shared pre-allocation 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  
+   - **Deleted accounts**: Remove accounts (represented as `null` values)
+
+#### - `config`: [`FixtureConfig`](#fixtureconfig)
+
+Chain configuration object to be applied to the client running the blockchain engine reorg test.
+
+### `FixtureConfig`
+
+#### - `network`: [`Fork`](./common_types.md#fork)
+
+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`
+
+Engine API payload structure identical to the one defined in [Blockchain Engine Tests](./blockchain_test_engine.md#fixtureenginenewpayload). Includes execution payload, versioned hashes, parent beacon block root, validation errors, version, and error codes.
+
+## Usage Notes
+
+- This format is only generated when using `--generate-shared-pre` and `--use-shared-pre` 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)
+- Reorganization scenarios are supported through the `forkChoiceUpdate` mechanism
@@ -101,6 +101,7 @@ evm_bytes = "cli.evm_bytes:evm_bytes"
 hasher = "cli.hasher:main"
 eest = "cli.eest.cli:eest"
 fillerconvert = "cli.fillerconvert.fillerconvert:main"
+groupstats = "cli.show_pre_alloc_group_stats:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
 
@@ -7,6 +7,7 @@ markers =
     slow
     pre_alloc_modify
     ported_from
+    pre_alloc_group: Control shared pre-allocation grouping (use "separate" for isolated group or custom string for named groups)
 addopts = 
     -p pytest_plugins.concurrency
     -p pytest_plugins.execute.sender
 
@@ -7,6 +7,7 @@ markers =
     slow
     pre_alloc_modify
     ported_from
+    pre_alloc_group: Control shared pre-allocation grouping (use "separate" for isolated group or custom string for named groups)
 addopts = 
     -p pytest_plugins.concurrency
     -p pytest_plugins.filler.pre_alloc
 
@@ -23,13 +23,19 @@
 
 from .hasher import HashableItem
 
+# Files and directories to exclude from index generation
+INDEX_EXCLUDED_FILES = frozenset({"index.json"})
+INDEX_EXCLUDED_PATH_PARTS = frozenset({".meta", "pre_alloc"})
+
 
 def count_json_files_exclude_index(start_path: Path) -> int:
-    """
-    Return the number of json files in the specified directory, excluding
-    index.json files and tests in "blockchain_tests_engine".
-    """
-    json_file_count = sum(1 for file in start_path.rglob("*.json") if file.name != "index.json")
+    """Return the number of fixture json files in the specified directory."""
+    json_file_count = sum(
+        1
+        for file in start_path.rglob("*.json")
+        if file.name not in INDEX_EXCLUDED_FILES
+        and not any(part in INDEX_EXCLUDED_PATH_PARTS for part in file.parts)
+    )
     return json_file_count
 
 
@@ -144,7 +150,9 @@ def generate_fixtures_index(
         fixture_formats = set()
         test_cases: List[TestCaseIndexFile] = []
         for file in input_path.rglob("*.json"):
-            if file.name == "index.json" or ".meta" in file.parts:
+            if file.name in INDEX_EXCLUDED_FILES or any(
+                part in INDEX_EXCLUDED_PATH_PARTS for part in file.parts
+            ):
                 continue
 
             try:
@@ -165,6 +173,7 @@ def generate_fixtures_index(
                         or f"0x{fixture.info.get('generatedTestHash')}",
                         fork=fixture_fork,
                         format=fixture.__class__,
+                        pre_hash=getattr(fixture, "pre_hash", None),
                     )
                 )
                 if fixture_fork:
 
@@ -63,9 +63,11 @@ def run_multiple(self, executions: List[PytestExecution]) -> int:
         """
         for i, execution in enumerate(executions):
             if execution.description and len(executions) > 1:
-                self.console.print(
-                    f"Phase {i + 1}/{len(executions)}: [italic]{execution.description}[/italic]"
+                phase_text = (
+                    f"[bold blue]phase {i + 1}/{len(executions)}: "
+                    f"{execution.description}[/bold blue]"
                 )
+                self.console.rule(phase_text, style="bold blue")
 
             result = self.run_single(execution.config_file, execution.args)
             if result != 0:
 
@@ -21,6 +21,129 @@ def __init__(self):
             ],
         )
 
+    def create_executions(self, pytest_args: List[str]) -> List[PytestExecution]:
+        """
+        Create execution plan that supports two-phase shared pre-state generation.
+
+        Returns single execution for normal filling, or two-phase execution
+        when --gen-shared-pre is specified.
+        """
+        processed_args = self.process_arguments(pytest_args)
+
+        # Check if we need two-phase execution
+        if "--generate-shared-pre" in processed_args:
+            return self._create_two_phase_executions(processed_args)
+        elif "--use-shared-pre" in processed_args:
+            # Only phase 2: using existing shared pre-allocation state
+            return self._create_single_phase_with_shared_alloc(processed_args)
+        else:
+            # Normal single-phase execution
+            return [
+                PytestExecution(
+                    config_file=self.config_file,
+                    args=processed_args,
+                )
+            ]
+
+    def _create_two_phase_executions(self, args: List[str]) -> List[PytestExecution]:
+        """Create two-phase execution: shared allocation generation + fixture filling."""
+        # Phase 1: Shared allocation generation (clean and minimal output)
+        phase1_args = self._create_phase1_args(args)
+
+        # Phase 2: Main fixture generation (full user options)
+        phase2_args = self._create_phase2_args(args)
+
+        return [
+            PytestExecution(
+                config_file=self.config_file,
+                args=phase1_args,
+                description="generating shared pre-allocation state",
+            ),
+            PytestExecution(
+                config_file=self.config_file,
+                args=phase2_args,
+                description="filling test fixtures",
+            ),
+        ]
+
+    def _create_single_phase_with_shared_alloc(self, args: List[str]) -> List[PytestExecution]:
+        """Create single execution using existing shared pre-allocation state."""
+        return [
+            PytestExecution(
+                config_file=self.config_file,
+                args=args,
+            )
+        ]
+
+    def _create_phase1_args(self, args: List[str]) -> List[str]:
+        """Create arguments for phase 1 (shared allocation generation)."""
+        # Start with all args, then remove what we don't want for phase 1
+        filtered_args = self._remove_unwanted_phase1_args(args)
+
+        # Add required phase 1 flags (with quiet output by default)
+        phase1_args = [
+            "--generate-shared-pre",
+            "-qq",  # Quiet pytest output by default (user -v/-vv/-vvv can override)
+        ] + filtered_args
+
+        return phase1_args
+
+    def _create_phase2_args(self, args: List[str]) -> List[str]:
+        """Create arguments for phase 2 (fixture filling)."""
+        # Remove --generate-shared-pre and --clean, then add --use-shared-pre
+        phase2_args = self._remove_generate_shared_pre_flag(args)
+        phase2_args = self._remove_clean_flag(phase2_args)
+        phase2_args = self._add_use_shared_pre_flag(phase2_args)
+        return phase2_args
+
+    def _remove_unwanted_phase1_args(self, args: List[str]) -> List[str]:
+        """Remove arguments we don't want in phase 1 (pre-state generation)."""
+        unwanted_flags = {
+            # Output format flags
+            "--html",
+            # Report flags (we'll add our own -qq)
+            "-q",
+            "--quiet",
+            "-qq",
+            "--tb",
+            # Shared allocation flags (we'll add our own)
+            "--generate-shared-pre",
+            "--use-shared-pre",
+        }
+
+        filtered_args = []
+        i = 0
+        while i < len(args):
+            arg = args[i]
+
+            # Skip unwanted flags
+            if arg in unwanted_flags:
+                # Skip flag and its value if it takes one
+                if arg in ["--html", "--tb", "-n"] and i + 1 < len(args):
+                    i += 2  # Skip flag and value
+                else:
+                    i += 1  # Skip just the flag
+            # Skip unwanted flags with = format
+            elif any(arg.startswith(f"{flag}=") for flag in unwanted_flags):
+                i += 1
+            else:
+                filtered_args.append(arg)
+                i += 1
+
+        return filtered_args
+
+    def _remove_generate_shared_pre_flag(self, args: List[str]) -> List[str]:
+        """Remove --generate-shared-pre flag from argument list."""
+        return [arg for arg in args if arg != "--generate-shared-pre"]
+
+    def _remove_clean_flag(self, args: List[str]) -> List[str]:
+        """Remove --clean flag from argument list."""
+        return [arg for arg in args if arg != "--clean"]
+
+    def _add_use_shared_pre_flag(self, args: List[str]) -> List[str]:
+        """Add --use-shared-pre flag to argument list."""
+        return args + ["--use-shared-pre"]
+
 
 class PhilCommand(FillCommand):
     """Friendly fill command with emoji reporting."""
@@ -74,3 +197,8 @@ def phil(pytest_args: List[str], **kwargs) -> None:
     """Friendly alias for the fill command."""
     command = PhilCommand()
     command.execute(list(pytest_args))
+
+
+if __name__ == "__main__":
+    # to allow debugging in vscode: in launch config, set "module": "cli.pytest_commands.fill"
+    fill(prog_name="fill")