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.
| 26 | @dataclass |
|---|
class TransactionStart:
TransactionEnd
Trace event that is triggered at the end of a transaction.
| 33 | @dataclass |
|---|
class TransactionEnd:
gas_used
| 39 | gas_used: int |
|---|
output
| 44 | output: bytes |
|---|
error
| 49 | error: Optional[EthereumException] |
|---|
PrecompileStart
Trace event that is triggered before executing a precompile.
| 61 | @dataclass |
|---|
class PrecompileStart:
address
| 67 | address: bytes |
|---|
PrecompileEnd
Trace event that is triggered after executing a precompile.
| 73 | @dataclass |
|---|
class PrecompileEnd:
OpStart
Trace event that is triggered before executing an opcode.
| 80 | @dataclass |
|---|
class OpStart:
op
| 86 | op: enum.Enum |
|---|
OpEnd
Trace event that is triggered after executing an opcode.
| 97 | @dataclass |
|---|
class OpEnd:
OpException
Trace event that is triggered when an opcode raises an exception.
| 104 | @dataclass |
|---|
class OpException:
error
| 110 | error: Exception |
|---|
EvmStop
Trace event that is triggered when the EVM stops.
| 123 | @dataclass |
|---|
class EvmStop:
op
| 129 | op: enum.Enum |
|---|
GasAndRefund
Trace event that is triggered when gas is deducted.
| 140 | @dataclass |
|---|
class GasAndRefund:
gas_cost
| 146 | gas_cost: int |
|---|
TraceEvent
All possible types of events that an EvmTracer is expected to handle.
| 152 | TraceEvent = Union[ |
|---|---|
| 153 | TransactionStart, |
| 154 | TransactionEnd, |
| 155 | PrecompileStart, |
| 156 | PrecompileEnd, |
| 157 | OpStart, |
| 158 | OpEnd, |
| 159 | OpException, |
| 160 | EvmStop, |
| 161 | GasAndRefund, |
| 162 | ] |
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:
| 177 | """ |
|---|---|
| 178 | An [`EvmTracer`] that discards all events. |
| 179 | |
| 180 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 181 | """ |
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:
| 205 | """ |
|---|---|
| 206 | Call `self` as a function, recording a trace event. |
| 207 | |
| 208 | `evm` is the live state of the EVM, and will be a fork-specific type |
| 209 | like [`ethereum.frontier.vm.Evm`][evm]. |
| 210 | |
| 211 | `event`, a [`TraceEvent`], is the reason why the tracer was triggered. |
| 212 | |
| 213 | `trace_memory` requests a full memory dump in the resulting trace. |
| 214 | |
| 215 | `trace_stack` requests the full stack in the resulting trace. |
| 216 | |
| 217 | `trace_return_data` requests that return data be included in the |
| 218 | resulting trace. |
| 219 | |
| 220 | See [`discard_evm_trace`] for an example function implementing this |
| 221 | protocol. |
| 222 | |
| 223 | [`discard_evm_trace`]: ref:ethereum.trace.discard_evm_trace |
| 224 | [evm]: ref:ethereum.frontier.vm.Evm |
| 225 | [`TraceEvent`]: ref:ethereum.trace.TraceEvent |
| 226 | """ |
evm_trace
Active EvmTracer that is used for generating traces.
| 229 | evm_trace: EvmTracer = discard_evm_trace |
|---|