ethereum.trace

Defines the functions required for creating EVM traces during execution.

A trace is a log of operations that took place during an event or period of time. In the case of an EVM trace, the log is built from a series of TraceEvents emitted during the execution of a transaction.

Note that this module does not contain a trace implementation. Instead, it defines only the events that can be collected into a trace by some other package. See EvmTracer.

See EIP-3155 for more details on EVM traces.

TransactionStart

Trace event that is triggered at the start of a transaction.

28
@dataclass
class TransactionStart:

TransactionEnd

Trace event that is triggered at the end of a transaction.

35
@dataclass
class TransactionEnd:

gas_used

Total gas consumed by this transaction.

41
    gas_used: int

output

Return value or revert reason of the outermost frame of execution.

46
    output: Bytes

error

The exception, if any, that caused the transaction to fail.

See ethereum.exceptions as well as fork-specific modules like ethereum.frontier.vm.exceptions for details.

51
    error: Optional[EthereumException]

PrecompileStart

Trace event that is triggered before executing a precompile.

63
@dataclass
class PrecompileStart:

address

Precompile that is about to be executed.

69
    address: Bytes

PrecompileEnd

Trace event that is triggered after executing a precompile.

75
@dataclass
class PrecompileEnd:

OpStart

Trace event that is triggered before executing an opcode.

82
@dataclass
class OpStart:

op

Opcode that is about to be executed.

Will be an instance of a fork-specific type like, for example, ethereum.frontier.vm.instructions.Ops.

88
    op: enum.Enum

OpEnd

Trace event that is triggered after executing an opcode.

99
@dataclass
class OpEnd:

OpException

Trace event that is triggered when an opcode raises an exception.

106
@dataclass
class OpException:

error

Exception that was raised.

See ethereum.exceptions as well as fork-specific modules like ethereum.frontier.vm.exceptions for examples of exceptions that might be raised.

112
    error: Exception

EvmStop

Trace event that is triggered when the EVM stops.

125
@dataclass
class EvmStop:

op

Last opcode executed.

Will be an instance of a fork-specific type like, for example, ethereum.frontier.vm.instructions.Ops.

131
    op: enum.Enum

GasAndRefund

Trace event that is triggered when gas is deducted.

142
@dataclass
class GasAndRefund:

gas_cost

Amount of gas charged or refunded.

148
    gas_cost: int

TraceEvent

All possible types of events that an EvmTracer is expected to handle.

154
TraceEvent = (
155
    TransactionStart
156
    | TransactionEnd
157
    | PrecompileStart
158
    | PrecompileEnd
159
    | OpStart
160
    | OpEnd
161
    | OpException
162
    | EvmStop
163
    | GasAndRefund
164
)

discard_evm_trace

An EvmTracer that discards all events.

def discard_evm_trace(​evm: object, ​​event: TraceEvent​) -> None:
176
    """
177
    An [`EvmTracer`] that discards all events.
178
179
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
180
    """

EvmTracer

Protocol that describes tracer functions.

See ethereum.trace for details about tracing in general, and __call__ for more on how to implement a tracer.

class EvmTracer:

__call__

Call self as a function, recording a trace event.

evm is the live state of the EVM, and will be a fork-specific type like ethereum.frontier.vm.Evm.

event, a TraceEvent, is the reason why the tracer was triggered.

See discard_evm_trace for an example function implementing this protocol.

def __call__(​self, ​​evm: object, ​​event: TraceEvent​) -> None:
200
        """
201
        Call `self` as a function, recording a trace event.
202
203
        `evm` is the live state of the EVM, and will be a fork-specific type
204
        like [`ethereum.frontier.vm.Evm`][evm].
205
206
        `event`, a [`TraceEvent`], is the reason why the tracer was triggered.
207
208
        See [`discard_evm_trace`] for an example function implementing this
209
        protocol.
210
211
        [`discard_evm_trace`]: ref:ethereum.trace.discard_evm_trace
212
        [evm]: ref:ethereum.frontier.vm.Evm
213
        [`TraceEvent`]: ref:ethereum.trace.TraceEvent
214
        """

_evm_trace

Active EvmTracer that is used for generating traces.

217
_evm_trace: EvmTracer = discard_evm_trace

set_evm_trace

Change the active EvmTracer that is used for generating traces.

def set_evm_trace(​tracer: EvmTracer​) -> EvmTracer:
226
    """
227
    Change the active [`EvmTracer`] that is used for generating traces.
228
229
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
230
    """
231
    global _evm_trace
232
    old = _evm_trace
233
    _evm_trace = tracer
234
    return old

evm_trace

Emit a trace to the active EvmTracer.

def evm_trace(​evm: object, ​​event: TraceEvent​) -> None:
241
    """
242
    Emit a trace to the active [`EvmTracer`].
243
244
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
245
    """
246
    global _evm_trace
247
    _evm_trace(
248
        evm,
249
        event,
250
    )