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 |
|---|
TraceEvent
All possible types of events that an EvmTracer is expected to handle.
| 154 | TraceEvent = ( |
|---|---|
| 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) -> None:
| 176 | """ |
|---|---|
| 177 | An [`EvmTracer`] that discards all events. |
| 178 | |
| 179 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 180 | """ |
| 181 | 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:
| 201 | """ |
|---|---|
| 202 | Call `self` as a function, recording a trace event. |
| 203 | |
| 204 | `evm` is the live state of the EVM, and will be a fork-specific type |
| 205 | like [`ethereum.forks.frontier.vm.Evm`][evm]. |
| 206 | |
| 207 | `event`, a [`TraceEvent`], is the reason why the tracer was triggered. |
| 208 | |
| 209 | See [`discard_evm_trace`] for an example function implementing this |
| 210 | protocol. |
| 211 | |
| 212 | [`discard_evm_trace`]: ref:ethereum.trace.discard_evm_trace |
| 213 | [evm]: ref:ethereum.forks.frontier.vm.Evm |
| 214 | [`TraceEvent`]: ref:ethereum.trace.TraceEvent |
| 215 | """ |
| 216 | raise NotImplementedError |
_evm_trace
Active EvmTracer that is used for generating traces.
| 219 | _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:
| 228 | """ |
|---|---|
| 229 | Change the active [`EvmTracer`] that is used for generating traces. |
| 230 | |
| 231 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 232 | """ |
| 233 | global _evm_trace |
| 234 | old = _evm_trace |
| 235 | _evm_trace = tracer |
| 236 | return old |
evm_trace
Emit a trace to the active EvmTracer.
def evm_trace(evm: object, event: TraceEvent) -> None:
| 243 | """ |
|---|---|
| 244 | Emit a trace to the active [`EvmTracer`]. |
| 245 | |
| 246 | [`EvmTracer`]: ref:ethereum.trace.EvmTracer |
| 247 | """ |
| 248 | global _evm_trace |
| 249 | _evm_trace( |
| 250 | evm, |
| 251 | event, |
| 252 | ) |