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.
| 24 | @dataclass |
|---|
class TransactionStart:
TransactionEnd
Trace event that is triggered at the end of a transaction.
| 31 | @dataclass |
|---|
class TransactionEnd:
gas_used
| 37 | gas_used: int |
|---|
output
| 42 | output: bytes |
|---|
error
| 47 | error: Optional[Exception] |
|---|
PrecompileStart
Trace event that is triggered before executing a precompile.
| 59 | @dataclass |
|---|
class PrecompileStart:
address
| 65 | address: bytes |
|---|
PrecompileEnd
Trace event that is triggered after executing a precompile.
| 71 | @dataclass |
|---|
class PrecompileEnd:
OpStart
Trace event that is triggered before executing an opcode.
| 78 | @dataclass |
|---|
class OpStart:
op
| 84 | op: enum.Enum |
|---|
OpEnd
Trace event that is triggered after executing an opcode.
| 95 | @dataclass |
|---|
class OpEnd:
OpException
Trace event that is triggered when an opcode raises an exception.
| 102 | @dataclass |
|---|
class OpException:
error
| 108 | error: Exception |
|---|
EvmStop
Trace event that is triggered when the EVM stops.
| 121 | @dataclass |
|---|
class EvmStop:
op
| 127 | op: enum.Enum |
|---|
GasAndRefund
Trace event that is triggered when gas is deducted.
| 138 | @dataclass |
|---|
class GasAndRefund:
gas_cost
| 144 | gas_cost: int |
|---|
TraceEvent
All possible types of events that an EvmTracer is expected to handle.
| 150 | TraceEvent = Union[ |
|---|---|
| 151 | TransactionStart, |
| 152 | TransactionEnd, |
| 153 | PrecompileStart, |
| 154 | PrecompileEnd, |
| 155 | OpStart, |
| 156 | OpEnd, |
| 157 | OpException, |
| 158 | EvmStop, |
| 159 | GasAndRefund, |
| 160 | ] |
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:
| 175 | """ |
|---|---|
| 176 | An [`EvmTracer`] that discards all events. |
| 177 | |
| 178 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 179 | """ |
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:
| 203 | """ |
|---|---|
| 204 | Call `self` as a function, recording a trace event. |
| 205 | |
| 206 | `evm` is the live state of the EVM, and will be a fork-specific type |
| 207 | like [`ethereum.frontier.vm.Evm`][evm]. |
| 208 | |
| 209 | `event`, a [`TraceEvent`], is the reason why the tracer was triggered. |
| 210 | |
| 211 | `trace_memory` requests a full memory dump in the resulting trace. |
| 212 | |
| 213 | `trace_stack` requests the full stack in the resulting trace. |
| 214 | |
| 215 | `trace_return_data` requests that return data be included in the |
| 216 | resulting trace. |
| 217 | |
| 218 | See [`discard_evm_trace`] for an example function implementing this |
| 219 | protocol. |
| 220 | |
| 221 | [`discard_evm_trace`]: ref:ethereum.trace.discard_evm_trace |
| 222 | [evm]: ref:ethereum.frontier.vm.Evm |
| 223 | [`TraceEvent`]: ref:ethereum.trace.TraceEvent |
| 224 | """ |
evm_trace
Active EvmTracer that is used for generating traces.
| 227 | evm_trace: EvmTracer = discard_evm_trace |
|---|