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
    """
181
182
    del evm, event

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:
202
        """
203
        Call `self` as a function, recording a trace event.
204
205
        `evm` is the live state of the EVM, and will be a fork-specific type
206
        like [`ethereum.frontier.vm.Evm`][evm].
207
208
        `event`, a [`TraceEvent`], is the reason why the tracer was triggered.
209
210
        See [`discard_evm_trace`] for an example function implementing this
211
        protocol.
212
213
        [`discard_evm_trace`]: ref:ethereum.trace.discard_evm_trace
214
        [evm]: ref:ethereum.frontier.vm.Evm
215
        [`TraceEvent`]: ref:ethereum.trace.TraceEvent
216
        """
217
        raise NotImplementedError

_evm_trace

Active EvmTracer that is used for generating traces.

220
_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:
229
    """
230
    Change the active [`EvmTracer`] that is used for generating traces.
231
232
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
233
    """
234
    global _evm_trace
235
    old = _evm_trace
236
    _evm_trace = tracer
237
    return old

evm_trace

Emit a trace to the active EvmTracer.

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