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
@final
29
@dataclass
class TransactionStart:

TransactionEnd

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

36
@final
37
@dataclass
class TransactionEnd:

gas_used

Total gas consumed by this transaction.

43
    gas_used: int

output

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

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

53
    error: Optional[EthereumException]

PrecompileStart

Trace event that is triggered before executing a precompile.

65
@final
66
@dataclass
class PrecompileStart:

address

Precompile that is about to be executed.

72
    address: Bytes

PrecompileEnd

Trace event that is triggered after executing a precompile.

78
@final
79
@dataclass
class PrecompileEnd:

OpStart

Trace event that is triggered before executing an opcode.

86
@final
87
@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.

93
    op: enum.Enum

OpEnd

Trace event that is triggered after executing an opcode.

104
@final
105
@dataclass
class OpEnd:

OpException

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

112
@final
113
@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.

119
    error: Exception

EvmStop

Trace event that is triggered when the EVM stops.

132
@final
133
@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.

139
    op: enum.Enum

GasAndRefund

Trace event that is triggered when gas is deducted.

150
@final
151
@dataclass
class GasAndRefund:

gas_cost

Amount of gas charged or refunded.

157
    gas_cost: int

StateGasAndRefund

Trace event that is triggered when state gas is deducted.

163
@final
164
@dataclass
class StateGasAndRefund:

state_gas_cost

Amount of state gas charged.

170
    state_gas_cost: int

TraceEvent

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

176
TraceEvent = (
177
    TransactionStart
178
    | TransactionEnd
179
    | PrecompileStart
180
    | PrecompileEnd
181
    | OpStart
182
    | OpEnd
183
    | OpException
184
    | EvmStop
185
    | GasAndRefund
186
    | StateGasAndRefund
187
)

discard_evm_trace

An EvmTracer that discards all events.

def discard_evm_trace(​evm: object, ​​event: TraceEvent​) -> None:
199
    <snip>
204
    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:
224
        <snip>
239
        raise NotImplementedError

_evm_trace

Active EvmTracer that is used for generating traces.

242
_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:
251
    <snip>
256
    global _evm_trace
257
    old = _evm_trace
258
    _evm_trace = tracer
259
    return old

evm_trace

Emit a trace to the active EvmTracer.

def evm_trace(​evm: object, ​​event: TraceEvent​) -> None:
266
    <snip>
271
    global _evm_trace
272
    _evm_trace(
273
        evm,
274
        event,
275
    )