execution_specs.py

"""
Ethereum Specs EVM Transition Tool Interface.
"""

import tempfile
from pathlib import Path
from typing import Any, ClassVar, Dict, Optional

import ethereum
from ethereum_spec_tools.evm_tools.t8n import T8N, ForkCache
from ethereum_spec_tools.evm_tools.t8n.evm_trace.eip3155 import Eip3155Tracer
from ethereum_spec_tools.evm_tools.t8n.evm_trace.group import GroupTracer
from ethereum_spec_tools.evm_tools.utils import get_supported_forks
from typing_extensions import override

from execution_testing.client_clis.cli_types import (
    TransitionToolOutput,
)
from execution_testing.client_clis.file_utils import (
    dump_files_to_directory,
)
from execution_testing.client_clis.transition_tool import (
    Profiler,
    TransitionTool,
    model_dump_config,
)
from execution_testing.exceptions import (
    BlockException,
    ExceptionBase,
    ExceptionMapper,
    TransactionException,
)
from execution_testing.forks import Fork


class ExecutionSpecsTransitionTool(TransitionTool):
    """Implementation of the EELS T8N for execution-spec-tests."""

    supports_opcode_count: ClassVar[bool] = True
    supports_blob_params: ClassVar[bool] = True

    def __init__(
        self,
        *,
        binary: Optional[Path] = None,
        trace: bool = False,
    ):
        """Initialize the EELS Transition Tool interface."""
        del binary  # EELS doesn't use an external binary
        self.exception_mapper = ExecutionSpecsExceptionMapper()
        self.trace = trace
        self._info_metadata: Optional[Dict[str, Any]] = {}
        self.fork_cache = ForkCache()

    @override
    def shutdown(self) -> None:
        self.fork_cache.__exit__()

    def version(self) -> str:
        """Version of the t8n tool."""
        return ethereum.__version__

    def is_fork_supported(self, fork: Fork) -> bool:
        """Return True if the fork is supported by the tool."""
        return fork.transition_tool_name() in get_supported_forks()

    def _evaluate(
        self,
        *,
        transition_tool_data: TransitionTool.TransitionToolData,
        debug_output_path: Path | None,
        slow_request: bool,
        profiler: Profiler,
    ) -> TransitionToolOutput:
        """
        Evaluate using the EELS T8N entry point in-process.

        ``transition_tool_data`` is handed to ``T8N`` as-is — fork,
        chain_id, reward, state_test, blob_schedule all flow through
        — and ``T8N.run()`` returns the ``TransitionToolOutput``
        directly.
        """
        del slow_request, profiler

        temp_dir = tempfile.TemporaryDirectory()

        tracers = None
        if self.trace:
            # TODO: Eip3155 traces still round-trip through tempfile
            # JSON — the tracer writes one ``trace-<i>.jsonl`` per tx
            # to ``output_basedir`` and ``collect_traces`` reads them
            # back. Same JSON round-trip we eliminated for alloc /
            # result / body; a follow-up should wire the tracer
            # output through memory like the rest of the in-process
            # path.
            tracers = GroupTracer()
            tracers.add(
                Eip3155Tracer(
                    trace_memory=True,
                    trace_stack=True,
                    trace_return_data=True,
                    output_basedir=temp_dir.name,
                )
            )

        t8n = T8N(
            transition_tool_data,
            cache=self.fork_cache,
            tracers=tracers,
            exception_mapper=self.exception_mapper,
        )
        output = t8n.run()

        if debug_output_path:
            dump_files_to_directory(
                debug_output_path,
                {
                    "input/alloc.json": transition_tool_data.alloc,
                    "input/env.json": transition_tool_data.env,
                    "input/txs.json": [
                        tx.model_dump(mode="json", **model_dump_config)
                        for tx in transition_tool_data.txs
                    ],
                },
            )

            dump_files_to_directory(
                debug_output_path,
                {
                    "output/alloc.json": output.alloc,
                    "output/result.json": output.result,
                },
            )

        if self.trace:
            self.collect_traces(
                output.result.receipts, temp_dir, debug_output_path
            )
        temp_dir.cleanup()

        return output

    @classmethod
    def is_installed(cls, binary_path: Optional[Path] = None) -> bool:
        """ExecutionSpecs is always installed."""
        del binary_path
        return True


class ExecutionSpecsExceptionMapper(ExceptionMapper):
    """
    Translate between EEST exceptions and error strings returned by
    ExecutionSpecs.
    """

    mapping_substring: ClassVar[Dict[ExceptionBase, str]] = {
        TransactionException.TYPE_4_EMPTY_AUTHORIZATION_LIST: (
            "EmptyAuthorizationListError"
        ),
        TransactionException.SENDER_NOT_EOA: "InvalidSenderError",
        TransactionException.TYPE_4_TX_CONTRACT_CREATION: (
            "TransactionTypeContractCreationError("
            "'transaction type `SetCodeTransaction` not allowed to "
            "create contracts')"
        ),
        TransactionException.INSUFFICIENT_ACCOUNT_FUNDS: (
            "InsufficientBalanceError"
        ),
        TransactionException.TYPE_3_TX_MAX_BLOB_GAS_ALLOWANCE_EXCEEDED: (
            "BlobGasLimitExceededError"
        ),
        TransactionException.INSUFFICIENT_MAX_FEE_PER_BLOB_GAS: (
            "InsufficientMaxFeePerBlobGasError"
        ),
        TransactionException.TYPE_3_TX_INVALID_BLOB_VERSIONED_HASH: (
            "InvalidBlobVersionedHashError"
        ),
        # This message is the same as TYPE_3_TX_MAX_BLOB_GAS_ALLOWANCE_EXCEEDED
        TransactionException.TYPE_3_TX_BLOB_COUNT_EXCEEDED: (
            "BlobCountExceededError"
        ),
        TransactionException.TYPE_3_TX_ZERO_BLOBS: "NoBlobDataError",
        TransactionException.INTRINSIC_GAS_TOO_LOW: (
            "InsufficientTransactionGasError"
        ),
        TransactionException.INTRINSIC_GAS_BELOW_FLOOR_GAS_COST: (
            "InsufficientTransactionGasError"
        ),
        TransactionException.INITCODE_SIZE_EXCEEDED: "InitCodeTooLargeError",
        TransactionException.PRIORITY_GREATER_THAN_MAX_FEE_PER_GAS: (
            "PriorityFeeGreaterThanMaxFeeError"
        ),
        TransactionException.NONCE_MISMATCH_TOO_HIGH: (
            "NonceMismatchError('nonce too high')"
        ),
        TransactionException.NONCE_MISMATCH_TOO_LOW: (
            "NonceMismatchError('nonce too low')"
        ),
        TransactionException.TYPE_3_TX_CONTRACT_CREATION: (
            "TransactionTypeContractCreationError("
            "'transaction type `BlobTransaction` not allowed to "
            "create contracts')"
        ),
        TransactionException.NONCE_IS_MAX: "NonceOverflowError",
        TransactionException.GAS_ALLOWANCE_EXCEEDED: (
            "GasUsedExceedsLimitError"
        ),
        TransactionException.GAS_LIMIT_EXCEEDS_MAXIMUM: (
            "TransactionGasLimitExceededError"
        ),
        BlockException.SYSTEM_CONTRACT_EMPTY: "System contract address",
        BlockException.SYSTEM_CONTRACT_CALL_FAILED: "call failed:",
        BlockException.INVALID_DEPOSIT_EVENT_LAYOUT: "deposit",
        BlockException.BLOCK_ACCESS_LIST_GAS_LIMIT_EXCEEDED: (
            "Block access list exceeds gas limit"
        ),
        TransactionException.LOG_MISMATCH: "LogMismatchError",
    }
    mapping_regex: ClassVar[Dict[ExceptionBase, str]] = {
        # Temporary solution for issue #1981.
        TransactionException.INSUFFICIENT_MAX_FEE_PER_GAS: (
            r"InsufficientMaxFeePerGasError|InvalidBlock"
        ),
        TransactionException.TYPE_1_TX_PRE_FORK: (
            r"module '.*transactions' has no attribute "
            r"'AccessListTransaction'|"
            r"transaction type 1 is not supported in .*"
        ),
        TransactionException.TYPE_2_TX_PRE_FORK: (
            r"'.*transactions' has no attribute 'FeeMarketTransaction'|"
            r"transaction type 2 is not supported in .*"
        ),
        TransactionException.TYPE_3_TX_PRE_FORK: (
            r"module '.*transactions' has no attribute 'BlobTransaction'|"
            r"transaction type 3 is not supported in .*"
        ),
        TransactionException.TYPE_4_TX_PRE_FORK: (
            r"'.*transactions' has no attribute 'SetCodeTransaction'|"
            r"transaction type 4 is not supported in .*"
        ),
    }