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.forks.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.forks.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.forks.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.forks.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

StateGasAndRefund

Trace event that is triggered when state gas is deducted.

154
@dataclass
class StateGasAndRefund:

state_gas_cost

Amount of state gas charged.

160
    state_gas_cost: int

TraceEvent

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

166
TraceEvent = (
167
    TransactionStart
168
    | TransactionEnd
169
    | PrecompileStart
170
    | PrecompileEnd
171
    | OpStart
172
    | OpEnd
173
    | OpException
174
    | EvmStop
175
    | GasAndRefund
176
    | StateGasAndRefund
177
)

discard_evm_trace

An EvmTracer that discards all events.

def discard_evm_trace(​evm: object, ​​event: TraceEvent​) -> None:
189
    """
190
    An [`EvmTracer`] that discards all events.
191
192
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
193
    """
194
    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.forks.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:
214
        """
215
        Call `self` as a function, recording a trace event.
216
217
        `evm` is the live state of the EVM, and will be a fork-specific type
218
        like [`ethereum.forks.frontier.vm.Evm`][evm].
219
220
        `event`, a [`TraceEvent`], is the reason why the tracer was triggered.
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.forks.frontier.vm.Evm
227
        [`TraceEvent`]: ref:ethereum.trace.TraceEvent
228
        """
229
        raise NotImplementedError

_evm_trace

Active EvmTracer that is used for generating traces.

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

evm_trace

Emit a trace to the active EvmTracer.

def evm_trace(​evm: object, ​​event: TraceEvent​) -> None:
256
    """
257
    Emit a trace to the active [`EvmTracer`].
258
259
    [`EvmTracer`]: ref:ethereum.trace.EvmTracer
260
    """
261
    global _evm_trace
262
    _evm_trace(
263
        evm,
264
        event,
265
    )