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
| 41 | gas_used: int |
|---|
output
| 46 | output: Bytes |
|---|
error
| 51 | error: Optional[EthereumException] |
|---|
PrecompileStart
Trace event that is triggered before executing a precompile.
| 63 | @dataclass |
|---|
class PrecompileStart:
address
| 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
| 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
| 112 | error: Exception |
|---|
EvmStop
Trace event that is triggered when the EVM stops.
| 125 | @dataclass |
|---|
class EvmStop:
op
| 131 | op: enum.Enum |
|---|
GasAndRefund
Trace event that is triggered when gas is deducted.
| 142 | @dataclass |
|---|
class GasAndRefund:
gas_cost
| 148 | gas_cost: int |
|---|
TraceEvent
All possible types of events that an EvmTracer is expected to handle.
| 154 | TraceEvent = Union[ |
|---|---|
| 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, trace_memory: bool, trace_stack: bool, trace_return_data: bool) -> None:
| 179 | """ |
|---|---|
| 180 | An [`EvmTracer`] that discards all events. |
| 181 | |
| 182 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 183 | """ |
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:
| 207 | """ |
|---|---|
| 208 | Call `self` as a function, recording a trace event. |
| 209 | |
| 210 | `evm` is the live state of the EVM, and will be a fork-specific type |
| 211 | like [`ethereum.frontier.vm.Evm`][evm]. |
| 212 | |
| 213 | `event`, a [`TraceEvent`], is the reason why the tracer was triggered. |
| 214 | |
| 215 | `trace_memory` requests a full memory dump in the resulting trace. |
| 216 | |
| 217 | `trace_stack` requests the full stack in the resulting trace. |
| 218 | |
| 219 | `trace_return_data` requests that return data be included in the |
| 220 | resulting trace. |
| 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.frontier.vm.Evm |
| 227 | [`TraceEvent`]: ref:ethereum.trace.TraceEvent |
| 228 | """ |
_evm_trace
Active EvmTracer that is used for generating traces.
| 231 | _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:
| 240 | """ |
|---|---|
| 241 | Change the active [`EvmTracer`] that is used for generating traces. |
| 242 | |
| 243 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 244 | """ |
| 245 | global _evm_trace |
| 246 | old = _evm_trace |
| 247 | _evm_trace = tracer |
| 248 | return old |
evm_trace
Emit a trace to the active EvmTracer.
def evm_trace(evm: object, event: TraceEvent, /, trace_memory: bool, trace_stack: bool, trace_return_data: bool) -> None:
| 259 | """ |
|---|---|
| 260 | Emit a trace to the active [`EvmTracer`]. |
| 261 | |
| 262 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 263 | """ |
| 264 | global _evm_trace |
| 265 | _evm_trace( |
| 266 | evm, |
| 267 | event, |
| 268 | trace_memory=trace_memory, |
| 269 | trace_stack=trace_stack, |
| 270 | trace_return_data=trace_return_data, |
| 271 | ) |