feat(execute): Add identifiers to sent txs (#2056)

* feat(types): Add `metadata` field to transactions

* feat(rpc): Embed tx metadata into the request id for send_transaction

* feat(pytest/execute): Add transaction metadata to all transactions

* docs: Add tx id documentation

* fix: tox

Author: marioevz

docs/running_tests/execute/index.md

@@ -7,6 +7,7 @@ See:
 - [Execute Hive](./hive.md) for help with the `execute` simulator in order to run tests on a single-client local network.
 - [Execute Remote](./remote.md) for help with executing tests on a remote network such as a devnet, or even mainnet.
 - [Execute Eth Config](./eth_config.md) for help verifying client configurations on a remote network such as a devnet, or even mainnet.
+- [Transaction Metadata](./transaction_metadata.md) for detailed information about transaction metadata tracking in execute mode.
 
 The rest of this page describes how `execute` works and explains its architecture.
 

docs/running_tests/execute/remote.md

@@ -32,6 +32,19 @@ It is recommended to only run a subset of the tests when executing on a live net
 uv run execute remote --fork=Prague --rpc-endpoint=https://rpc.endpoint.io --rpc-seed-key 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --rpc-chain-id 12345 ./tests/prague/eip7702_set_code_tx/test_set_code_txs.py::test_set_code_to_sstore
 ```
 
+## Transaction Metadata on Remote Networks
+
+When executing tests on remote networks, all transactions include metadata that helps with debugging and monitoring. This metadata is embedded in the RPC request ID and includes:
+
+- **Test identification**: Each transaction is tagged with the specific test being executed
+- **Execution phase**: Transactions are categorized as setup, testing, or cleanup
+- **Action tracking**: Specific actions like contract deployment, funding, or refunding are tracked
+- **Target identification**: The account or contract being targeted is labeled
+
+This metadata is particularly useful when debugging test failures on live networks, as it allows you to correlate blockchain transactions with specific test operations and phases.
+
+See [Transaction Metadata](./transaction_metadata.md) for details.
+
 ## `execute` Command Test Execution
 
 The `execute remote` and `execute hive` commands first creates a random sender account from which all required test accounts will be deployed and funded, and this account is funded by sweeping (by default) this "seed" account.

docs/running_tests/execute/transaction_metadata.md

@@ -0,0 +1,77 @@
+# Transaction Metadata in Execute Mode
+
+The `execute` plugin automatically adds metadata to all transactions it sends to the network. This feature was introduced to improve debugging, monitoring, and transaction tracking capabilities.
+
+## Overview
+
+Transaction metadata provides context about each transaction sent during test execution, making it easier to:
+
+- Debug test failures by correlating blockchain transactions with test operations
+- Monitor test execution patterns and performance
+- Track transaction flow across different phases of test execution
+- Identify which transactions belong to which tests and phases
+
+## Metadata Structure
+
+Each transaction includes a `TransactionTestMetadata` object with the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `testId` | `str` | The unique identifier of the test being executed (pytest node ID) |
+| `phase` | `str` | The execution phase: `setup`, `testing`, or `cleanup` |
+| `action` | `str` | The specific action being performed (e.g., `deploy_contract`, `fund_eoa`) |
+| `target` | `str` | The label of the account or contract being targeted |
+| `txIndex` | `int` | The index of the transaction within its phase |
+
+## Transaction Phases
+
+### Setup Phase (`setup`)
+
+Transactions that prepare the test environment:
+
+- **`deploy_contract`**: Contract deployment transactions
+- **`fund_eoa`**: Funding EOAs with initial balances
+- **`eoa_storage_set`**: Setting storage values for EOAs
+- **`fund_address`**: Funding specific addresses
+
+### Testing Phase (`testing`)
+
+The actual test transactions defined by the test:
+
+- User-defined test transactions
+- Blob testing transactions
+
+### Cleanup Phase (`cleanup`)
+
+Transactions that clean up after the test:
+
+- **`refund_from_eoa`**: Refunding EOAs back to the sender account
+
+## Example Metadata
+
+```json
+{
+  "testId": "tests/example_test.py::test_example",
+  "phase": "setup",
+  "action": "deploy_contract",
+  "target": "contract_label",
+  "txIndex": 0
+}
+```
+
+## Debugging Test Failures
+
+When a test fails on a remote network, you can use the transaction metadata to:
+
+1. Identify which transactions belong to the failing test
+2. Determine which phase of execution failed
+3. Correlate blockchain transactions with specific test operations
+
+The ID will normally be printed in the client logs when execute is running tests against the client, but the logging level might need to be increased for some of the clients (`--sim.loglevel` when running with hive).
+
+## Technical Notes
+
+- Metadata is automatically handled by the execute plugin
+- No additional configuration is required
+- Metadata is embedded in RPC requests without affecting transaction execution
+- The feature is backward compatible and doesn't change test behavior

src/ethereum_test_execution/base.py

@@ -4,6 +4,7 @@
 from typing import Annotated, Any, ClassVar, Dict, Type
 
 from pydantic import PlainSerializer, PlainValidator
+from pytest import FixtureRequest
 
 from ethereum_test_base_types import CamelModel
 from ethereum_test_forks import Fork
@@ -32,7 +33,9 @@ def __pydantic_init_subclass__(cls, **kwargs):
             BaseExecute.formats[cls.format_name] = cls
 
     @abstractmethod
-    def execute(self, fork: Fork, eth_rpc: EthRPC, engine_rpc: EngineRPC | None):
+    def execute(
+        self, fork: Fork, eth_rpc: EthRPC, engine_rpc: EngineRPC | None, request: FixtureRequest
+    ):
         """Execute the format."""
         pass
 

src/ethereum_test_execution/blob_transaction.py

@@ -3,11 +3,13 @@
 from hashlib import sha256
 from typing import ClassVar, Dict, List
 
-from ethereum_test_base_types import Hash
+from pytest import FixtureRequest
+
+from ethereum_test_base_types import Address, Hash
 from ethereum_test_base_types.base_types import Bytes
 from ethereum_test_forks import Fork
 from ethereum_test_rpc import BlobAndProofV1, BlobAndProofV2, EngineRPC, EthRPC
-from ethereum_test_types import NetworkWrappedTransaction, Transaction
+from ethereum_test_types import NetworkWrappedTransaction, Transaction, TransactionTestMetadata
 
 from .base import BaseExecute
 
@@ -53,22 +55,33 @@ class BlobTransaction(BaseExecute):
 
     txs: List[NetworkWrappedTransaction | Transaction]
 
-    def execute(self, fork: Fork, eth_rpc: EthRPC, engine_rpc: EngineRPC | None):
+    def execute(
+        self, fork: Fork, eth_rpc: EthRPC, engine_rpc: EngineRPC | None, request: FixtureRequest
+    ):
         """Execute the format."""
         assert engine_rpc is not None, "Engine RPC is required for this format."
         versioned_hashes: Dict[Hash, BlobAndProofV1 | BlobAndProofV2] = {}
         sent_txs: List[Transaction] = []
-        for tx in self.txs:
+        for tx_index, tx in enumerate(self.txs):
             if isinstance(tx, NetworkWrappedTransaction):
                 tx.tx = tx.tx.with_signature_and_sender()
                 sent_txs.append(tx.tx)
                 expected_hash = tx.tx.hash
                 versioned_hashes.update(versioned_hashes_with_blobs_and_proofs(tx))
+                to_address = tx.tx.to
             else:
                 tx = tx.with_signature_and_sender()
                 sent_txs.append(tx)
                 expected_hash = tx.hash
-            received_hash = eth_rpc.send_raw_transaction(tx.rlp())
+                to_address = tx.to
+            label = to_address.label if isinstance(to_address, Address) else None
+            metadata = TransactionTestMetadata(
+                test_id=request.node.nodeid,
+                phase="testing",
+                target=label,
+                tx_index=tx_index,
+            )
+            received_hash = eth_rpc.send_raw_transaction(tx.rlp(), request_id=metadata.to_json())
             assert expected_hash == received_hash, (
                 f"Expected hash {expected_hash} does not match received hash {received_hash}."
             )

src/ethereum_test_execution/transaction_post.py

@@ -3,11 +3,12 @@
 from typing import ClassVar, List
 
 import pytest
+from pytest import FixtureRequest
 
-from ethereum_test_base_types import Alloc, Hash
+from ethereum_test_base_types import Address, Alloc, Hash
 from ethereum_test_forks import Fork
 from ethereum_test_rpc import EngineRPC, EthRPC, SendTransactionExceptionError
-from ethereum_test_types import Transaction
+from ethereum_test_types import Transaction, TransactionTestMetadata
 
 from .base import BaseExecute
 
@@ -23,21 +24,36 @@ class TransactionPost(BaseExecute):
         "Simple transaction sending, then post-check after all transactions are included"
     )
 
-    def execute(self, fork: Fork, eth_rpc: EthRPC, engine_rpc: EngineRPC | None):
+    def execute(
+        self, fork: Fork, eth_rpc: EthRPC, engine_rpc: EngineRPC | None, request: FixtureRequest
+    ):
         """Execute the format."""
         assert not any(tx.ty == 3 for block in self.blocks for tx in block), (
             "Transaction type 3 is not supported in execute mode."
         )
         for block in self.blocks:
-            if any(tx.error is not None for tx in block):
-                for transaction in block:
+            signed_txs = []
+            for tx_index, tx in enumerate(block):
+                # Add metadata
+                tx = tx.with_signature_and_sender()
+                to_address = tx.to
+                label = to_address.label if isinstance(to_address, Address) else None
+                tx.metadata = TransactionTestMetadata(
+                    test_id=request.node.nodeid,
+                    phase="testing",
+                    target=label,
+                    tx_index=tx_index,
+                )
+                signed_txs.append(tx)
+            if any(tx.error is not None for tx in signed_txs):
+                for transaction in signed_txs:
                     if transaction.error is None:
-                        eth_rpc.send_wait_transaction(transaction.with_signature_and_sender())
+                        eth_rpc.send_wait_transaction(transaction)
                     else:
                         with pytest.raises(SendTransactionExceptionError):
-                            eth_rpc.send_transaction(transaction.with_signature_and_sender())
+                            eth_rpc.send_transaction(transaction)
             else:
-                eth_rpc.send_wait_transactions([tx.with_signature_and_sender() for tx in block])
+                eth_rpc.send_wait_transactions(signed_txs)
 
         for address, account in self.post.root.items():
             balance = eth_rpc.get_balance(address)

src/ethereum_test_rpc/rpc.py

@@ -75,17 +75,26 @@ def __init_subclass__(cls) -> None:
             namespace = namespace.removesuffix("RPC")
         cls.namespace = namespace.lower()
 
-    def post_request(self, method: str, *params: Any, extra_headers: Dict | None = None) -> Any:
+    def post_request(
+        self,
+        method: str,
+        *params: Any,
+        extra_headers: Dict | None = None,
+        request_id: int | str | None = None,
+    ) -> Any:
         """Send JSON-RPC POST request to the client RPC server at port defined in the url."""
         if extra_headers is None:
             extra_headers = {}
         assert self.namespace, "RPC namespace not set"
 
+        next_request_id_counter = next(self.request_id_counter)
+        if request_id is None:
+            request_id = next_request_id_counter
         payload = {
             "jsonrpc": "2.0",
             "method": f"{self.namespace}_{method}",
             "params": params,
-            "id": next(self.request_id_counter),
+            "id": request_id,
         }
         base_header = {
             "Content-Type": "application/json",
@@ -197,10 +206,16 @@ def gas_price(self) -> int:
         """`eth_gasPrice`: Returns the number of transactions sent from an address."""
         return int(self.post_request("gasPrice"), 16)
 
-    def send_raw_transaction(self, transaction_rlp: Bytes) -> Hash:
+    def send_raw_transaction(
+        self, transaction_rlp: Bytes, request_id: int | str | None = None
+    ) -> Hash:
         """`eth_sendRawTransaction`: Send a transaction to the client."""
         try:
-            result_hash = Hash(self.post_request("sendRawTransaction", f"{transaction_rlp.hex()}"))
+            result_hash = Hash(
+                self.post_request(
+                    "sendRawTransaction", f"{transaction_rlp.hex()}", request_id=request_id
+                ),
+            )
             assert result_hash is not None
             return result_hash
         except Exception as e:
@@ -210,7 +225,11 @@ def send_transaction(self, transaction: Transaction) -> Hash:
         """`eth_sendRawTransaction`: Send a transaction to the client."""
         try:
             result_hash = Hash(
-                self.post_request("sendRawTransaction", f"{transaction.rlp().hex()}")
+                self.post_request(
+                    "sendRawTransaction",
+                    f"{transaction.rlp().hex()}",
+                    request_id=transaction.metadata_string(),
+                )
             )
             assert result_hash == transaction.hash
             assert result_hash is not None
@@ -312,7 +331,13 @@ class EngineRPC(BaseRPC):
     simulators.
     """
 
-    def post_request(self, method: str, *params: Any, extra_headers: Dict | None = None) -> Any:
+    def post_request(
+        self,
+        method: str,
+        *params: Any,
+        extra_headers: Dict | None = None,
+        request_id: int | str | None = None,
+    ) -> Any:
         """Send JSON-RPC POST request to the client RPC server at port defined in the url."""
         if extra_headers is None:
             extra_headers = {}
@@ -324,7 +349,9 @@ def post_request(self, method: str, *params: Any, extra_headers: Dict | None = N
         extra_headers = {
             "Authorization": f"Bearer {jwt_token}",
         } | extra_headers
-        return super().post_request(method, *params, extra_headers=extra_headers)
+        return super().post_request(
+            method, *params, extra_headers=extra_headers, request_id=request_id
+        )
 
     def new_payload(self, *params: Any, version: int) -> PayloadStatus:
         """`engine_newPayloadVX`: Attempts to execute the given payload on an execution client."""

src/ethereum_test_types/__init__.py

@@ -27,6 +27,7 @@
     NetworkWrappedTransaction,
     Transaction,
     TransactionDefaults,
+    TransactionTestMetadata,
     TransactionType,
 )
 from .utils import Removable, keccak256
@@ -47,6 +48,7 @@
     "Transaction",
     "TransactionDefaults",
     "TransactionReceipt",
+    "TransactionTestMetadata",
     "TransactionType",
     "Withdrawal",
     "WithdrawalRequest",

src/ethereum_test_types/transaction_types.py

@@ -185,6 +185,10 @@ class TransactionGeneric(BaseModel, Generic[NumberBoundTypeVar]):
     s: NumberBoundTypeVar = Field(0)  # type: ignore
     sender: EOA | None = None
 
+    def metadata_string(self) -> str | None:
+        """Return the metadata field as a formatted json string or None."""
+        return None
+
 
 class TransactionValidateToAsEmptyString(CamelModel):
     """Handler to validate the `to` field from an empty string."""
@@ -233,6 +237,23 @@ def serialize_to_as_none(self, serializer):
         return default
 
 
+class TransactionTestMetadata(CamelModel):
+    """Represents the metadata for a transaction."""
+
+    test_id: str | None = None
+    phase: str | None = None
+    action: str | None = None  # e.g. deploy / fund / execute
+    target: str | None = None  # account/contract label
+    tx_index: int | None = None  # index within this phase
+
+    def to_json(self) -> str:
+        """
+        Convert the transaction metadata into json string for it to be embedded in the
+        request id.
+        """
+        return self.model_dump_json(exclude_none=True, by_alias=True)
+
+
 class Transaction(
     TransactionGeneric[HexNumber], TransactionTransitionToolConverter, SignableRLPSerializable
 ):
@@ -255,6 +276,8 @@ class Transaction(
 
     zero: ClassVar[Literal[0]] = 0
 
+    metadata: TransactionTestMetadata | None = Field(None, exclude=True)
+
     model_config = ConfigDict(validate_assignment=True)
 
     class InvalidFeePaymentError(Exception):
@@ -612,6 +635,12 @@ def get_rlp_signing_prefix(self) -> bytes:
             return bytes([self.ty])
         return b""
 
+    def metadata_string(self) -> str | None:
+        """Return the metadata field as a formatted json string or None."""
+        if self.metadata is None:
+            return None
+        return self.metadata.to_json()
+
     @cached_property
     def hash(self) -> Hash:
         """Returns hash of the transaction."""