feat(execute): Add Engine RPC option to execute remote (#2070)

* feat(rpc): Allow EngineRPC to have a custom jwt secret

* fix(rpc): Allow specifying a namespace for RPC subclasses

* refactor(rpc): Small changes

* feat(execute): Allow to specify an Engine RPC endpoint to drive the chain

refactor(execute): rename class

fix(plugins/execute): rebase issues

* docs: Update `docs/running_tests/execute/remote.md`

* docs: changelog

Author: marioevz

docs/CHANGELOG.md

@@ -105,6 +105,7 @@ Users can select any of the artifacts depending on their testing needs for their
 - ✨ Added new `Blob` class which can use the ckzg library to generate valid blobs at runtime ([#1614](https://github.com/ethereum/execution-spec-tests/pull/1614)).
 - ✨ Added `blob_transaction_test` execute test spec, which allows tests that send blob transactions to a running client and verifying its `engine_getBlobsVX` endpoint behavior ([#1644](https://github.com/ethereum/execution-spec-tests/pull/1644)).
 - ✨ Added `execute eth-config` command to test the `eth_config` RPC endpoint of a client, and includes configurations by default for Mainnet, Sepolia, Holesky, and Hoodi ([#1863](https://github.com/ethereum/execution-spec-tests/pull/1863)).
+- ✨ Command `execute remote` now allows specification of an Engine API endpoint to drive the chain via `--engine-endpoint` and either `--engine-jwt-secret` or `--engine-jwt-secret-file`. This mode is useful when there's no consensus client connected to the execution client so `execute` will automatically request blocks via the Engine API when it sends transactions ([#2070](https://github.com/ethereum/execution-spec-tests/pull/2070)).
 - ✨ Added `--address-stubs` flag to the `execute` command which allows to specify a JSON-formatted string, JSON file or YAML file which contains label-to-address of specific pre-deployed contracts already existing in the network where the tests are executed ([#2073](https://github.com/ethereum/execution-spec-tests/pull/2073)).
 
 ### 📋 Misc

docs/running_tests/execute/remote.md

@@ -24,6 +24,26 @@ One last requirement is that the `--rpc-chain-id` flag is set to the chain id of
 uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --rpc-seed-key 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --rpc-chain-id 12345
 ```
 
+## Engine RPC Endpoint (Optional)
+
+By default, the `execute remote` command assumes that the execution client is connected to a beacon node and the chain progresses automatically. However, you can optionally specify an Engine RPC endpoint to drive the chain manually when new transactions are submitted.
+
+To use this feature, you need to provide both the `--engine-endpoint` and JWT authentication:
+
+```bash
+uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --rpc-seed-key 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --rpc-chain-id 12345 --engine-endpoint=https://engine.endpoint.io --engine-jwt-secret "your-jwt-secret-here"
+```
+
+Alternatively, you can provide the JWT secret from a file:
+
+```bash
+uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --rpc-seed-key 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --rpc-chain-id 12345 --engine-endpoint=https://engine.endpoint.io --engine-jwt-secret-file /path/to/jwt-secret.txt
+```
+
+The JWT secret file must contain only the JWT secret as a hex string.
+
+When an engine endpoint is provided, the test execution will use the Engine API to create new blocks and include transactions, giving you full control over the chain progression.
+
 The `execute remote` command will connect to the client via the RPC endpoint and will start executing every test in the `./tests` folder in the same way as the `execute hive` command, but instead of using the Engine API to generate blocks, it will send the transactions to the client via the RPC endpoint.
 
 It is recommended to only run a subset of the tests when executing on a live network. To do so, a path to a specific test can be provided to the command:

src/ethereum_test_rpc/rpc.py

@@ -57,23 +57,22 @@ class BaseRPC:
     def __init__(
         self,
         url: str,
-        extra_headers: Dict | None = None,
+        *,
         response_validation_context: Any | None = None,
     ):
         """Initialize BaseRPC class with the given url."""
-        if extra_headers is None:
-            extra_headers = {}
         self.url = url
         self.request_id_counter = count(1)
-        self.extra_headers = extra_headers
         self.response_validation_context = response_validation_context
 
-    def __init_subclass__(cls) -> None:
+    def __init_subclass__(cls, namespace: str | None = None) -> None:
         """Set namespace of the RPC class to the lowercase of the class name."""
-        namespace = cls.__name__
-        if namespace.endswith("RPC"):
-            namespace = namespace.removesuffix("RPC")
-        cls.namespace = namespace.lower()
+        if namespace is None:
+            namespace = cls.__name__
+            if namespace.endswith("RPC"):
+                namespace = namespace.removesuffix("RPC")
+            namespace = namespace.lower()
+        cls.namespace = namespace
 
     def post_request(
         self,
@@ -99,7 +98,7 @@ def post_request(
         base_header = {
             "Content-Type": "application/json",
         }
-        headers = base_header | self.extra_headers | extra_headers
+        headers = base_header | extra_headers
 
         response = requests.post(self.url, json=payload, headers=headers)
         response.raise_for_status()
@@ -125,18 +124,12 @@ class EthRPC(BaseRPC):
 
     def __init__(
         self,
-        url: str,
-        extra_headers: Dict | None = None,
-        *,
+        *args,
         transaction_wait_timeout: int = 60,
-        response_validation_context: Any | None = None,
+        **kwargs,
     ):
         """Initialize EthRPC class with the given url and transaction wait timeout."""
-        if extra_headers is None:
-            extra_headers = {}
-        super().__init__(
-            url, extra_headers, response_validation_context=response_validation_context
-        )
+        super().__init__(*args, **kwargs)
         self.transaction_wait_timeout = transaction_wait_timeout
 
     def config(self):
@@ -331,6 +324,18 @@ class EngineRPC(BaseRPC):
     simulators.
     """
 
+    jwt_secret: bytes
+
+    def __init__(
+        self,
+        *args,
+        jwt_secret: bytes = b"secretsecretsecretsecretsecretse",  # Default secret used in hive
+        **kwargs,
+    ):
+        """Initialize Engine RPC class with the given JWT secret."""
+        super().__init__(*args, **kwargs)
+        self.jwt_secret = jwt_secret
+
     def post_request(
         self,
         method: str,
@@ -343,7 +348,7 @@ def post_request(
             extra_headers = {}
         jwt_token = encode(
             {"iat": int(time.time())},
-            b"secretsecretsecretsecretsecretse",  # the secret used within clients in hive
+            self.jwt_secret,
             algorithm="HS256",
         )
         extra_headers = {

src/pytest_plugins/execute/execute.py

@@ -1,5 +1,6 @@
 """Test execution plugin for pytest, to run Ethereum tests using in live networks."""
 
+import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, Generator, List, Type
@@ -73,6 +74,22 @@ def pytest_addoption(parser):
             f"(Default: {EnvironmentDefaults.gas_limit // 4})"
         ),
     )
+    execute_group.addoption(
+        "--transactions-per-block",
+        action="store",
+        dest="transactions_per_block",
+        type=int,
+        default=None,
+        help=("Number of transactions to send before producing the next block."),
+    )
+    execute_group.addoption(
+        "--get-payload-wait-time",
+        action="store",
+        dest="get_payload_wait_time",
+        type=float,
+        default=0.3,
+        help=("Time to wait after sending a forkchoice_updated before getting the payload."),
+    )
 
     report_group = parser.getgroup("tests", "Arguments defining html report behavior")
     report_group.addoption(
@@ -178,6 +195,18 @@ def pytest_html_report_title(report):
     report.title = "Execute Test Report"
 
 
+@pytest.fixture(scope="session")
+def transactions_per_block(request) -> int:  # noqa: D103
+    if transactions_per_block := request.config.getoption("transactions_per_block"):
+        return transactions_per_block
+
+    # Get the number of workers for the test
+    worker_count_env = os.environ.get("PYTEST_XDIST_WORKER_COUNT")
+    if not worker_count_env:
+        return 1
+    return max(int(worker_count_env), 1)
+
+
 @pytest.fixture(scope="session")
 def default_gas_price(request) -> int:
     """Return default gas price used for transactions."""