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, ​​trace_memory: bool, ​​trace_stack: bool, ​​trace_return_data: bool​) -> None:
179
    """
180
    An [`EvmTracer`] that discards all events.
181
182
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
183
    """

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.

trace_memory requests a full memory dump in the resulting trace.

trace_stack requests the full stack in the resulting trace.

trace_return_data requests that return data be included in the resulting trace.

See discard_evm_trace for an example function implementing this protocol.

def __call__(​self, ​​evm: object, ​​event: TraceEvent, ​​/, ​​trace_memory: bool, ​​trace_stack: bool, ​​trace_return_data: bool​) -> None:
207
        """
208
        Call `self` as a function, recording a trace event.
209
210
        `evm` is the live state of the EVM, and will be a fork-specific type
211
        like [`ethereum.frontier.vm.Evm`][evm].
212
213
        `event`, a [`TraceEvent`], is the reason why the tracer was triggered.
214
215
        `trace_memory` requests a full memory dump in the resulting trace.
216
217
        `trace_stack` requests the full stack in the resulting trace.
218
219
        `trace_return_data` requests that return data be included in the
220
        resulting trace.
221
222
        See [`discard_evm_trace`] for an example function implementing this
223
        protocol.
224
225
        [`discard_evm_trace`]: ref:ethereum.trace.discard_evm_trace
226
        [evm]: ref:ethereum.frontier.vm.Evm
227
        [`TraceEvent`]: ref:ethereum.trace.TraceEvent
228
        """

_evm_trace

Active EvmTracer that is used for generating traces.

231
_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:
240
    """
241
    Change the active [`EvmTracer`] that is used for generating traces.
242
243
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
244
    """
245
    global _evm_trace
246
    old = _evm_trace
247
    _evm_trace = tracer
248
    return old

evm_trace

Emit a trace to the active EvmTracer.

def evm_trace(​evm: object, ​​event: TraceEvent, ​​/, ​​trace_memory: bool, ​​trace_stack: bool, ​​trace_return_data: bool​) -> None:
259
    """
260
    Emit a trace to the active [`EvmTracer`].
261
262
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
263
    """
264
    global _evm_trace
265
    _evm_trace(
266
        evm,
267
        event,
268
        trace_memory=trace_memory,
269
        trace_stack=trace_stack,
270
        trace_return_data=trace_return_data,
271
    )