evm-trace

In struct-log call trees, events (LOG0–LOG4) are included in each node's events list.

• Ordering: event.position indicates the number of child calls preceding that event in its parent. This allows for interleaving events and calls in execution order.
• Log Inclusion: To include logs in a callTracer request, use {"tracer": "callTracer", "tracerConfig": {"withLog": true}}.
• Reverted Logs: Struct logs include attempted emissions even if the execution reverts. However, some clients might discard reverted logs in their callTracer output.
• LOG0 Specifics: LOG0 events have no topics and their selector is None.

To install the current development version from source, clone the repository and install it using pip.

git clone https://github.com/ApeWorX/evm-trace.git
cd evm-trace
python -m pip install .

You can install the latest release of evm-trace using pip.

pip install evm-trace

A VMTraceFrame is a synthetic snapshot of the EVM state at a specific instruction step. It is used for replaying traces in a format compatible with Geth-style debuggers.

Fields:

• address (str): The contract address being executed.
• pc (int): The program counter.
• op (str): The opcode name.
• depth (int): The call depth.
• stack (list[int]): The current stack values.
• memory (bytes | memoryview): The current memory state.
• storage (dict[int, int]): The current storage state (mapping of key to value).

The title property of a TreeRepresentation object dynamically formats information based on the type of node being displayed:

1. EventNodes: Displays the CallType and the hex-encoded selector (e.g., LOG: 0xabcdef12).
2. CallTreeNodes:
   • Address: Displays the checksummed Ethereum address.
   • Method ID: If the call is not a CREATE or SELFDESTRUCT type, it extracts the first 4 bytes of calldata and displays it as <0x...>.
   • Gas Cost: If available, appends the gas used in brackets, e.g., [500 gas].
   • Reversion: If the root call failed, it prefixes the title with [reverted].

Example title format: CALL: 0x71C...<0x12345678> [1200 gas]

If your node supports the trace_transaction RPC, you can retrieve trace objects and validate them using ParityTraceList.model_validate(raw_trace_list). To build a call-tree from these traces, use get_calltree_from_parity_trace.

from evm_trace import CallType, ParityTraceList, get_calltree_from_parity_trace

# Get raw trace list from node
raw_trace_list = web3.manager.request_blocking("trace_transaction", [txn_hash])
# Validate as ParityTraceList
trace_list = ParityTraceList.model_validate(raw_trace_list)
# Create call-tree
tree = get_calltree_from_parity_trace(trace_list)

If your node supports the debug_traceTransaction RPC, you can use web3.py to retrieve struct logs and convert them into TraceFrame objects using TraceFrame.model_validate(item).

from web3 import HTTPProvider, Web3
from evm_trace import TraceFrame

web3 = Web3(HTTPProvider("https://path.to.my.node"))
txn_hash = "0x..."
struct_logs = web3.manager.request_blocking("debug_traceTransaction", [txn_hash]).structLogs
for item in struct_logs:
    frame = TraceFrame.model_validate(item)

To reconstruct a call-tree from Geth struct logs, use get_calltree_from_geth_trace. You must provide a TraceFrame (the trace) and a dictionary of root node arguments including gas_cost, gas_limit, address, calldata, value, and call_type.

from evm_trace import CallType, get_calltree_from_geth_trace

root_node_kwargs = {
    "gas_cost": 10000000,
    "gas_limit": 10000000000,
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "calldata": "0x00",
    "value": 1000,
    "call_type": CallType.CALL,
}

# Assuming 'trace' is a TraceFrame obtained from Geth logs
calltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)

You can generate a gas report from a call-tree using get_gas_report(calltree).

To combine multiple reports into one, use merge_reports. This method accepts a list of Dict[Any, Dict[Any, List[int]]] where the inner List[int] represents the gas used. You can customize the keys (the Any types) to represent addresses, token names, or method selectors.

from evm_trace.gas import get_gas_report, merge_reports

# Assuming 'calltree' was created previously
gas_report = get_gas_report(calltree)

# To combine multiple reports:
# combined_report = merge_reports([report1, report2])

For clients supporting trace_replayTransaction with ["vmTrace"], you can process the opcode trace (containing stack and memory deltas) using evm_trace.vmtrace.

Use from_rpc_response(response_bytes) to parse the raw JSON-RPC response and to_trace_frames(vm_trace, address=...) to iterate through frames.

Note: These synthetic frames are not complete TraceFrame substitutes; they do not expose gas, refund, or error fields, and storage only contains deltas reported in that specific call.

from evm_trace.vmtrace import from_rpc_response, to_trace_frames

# response_bytes is the complete JSON-RPC response, encoded as bytes.
vm_trace = from_rpc_response(response_bytes)
for frame in to_trace_frames(vm_trace, address=transaction_to):
    print(frame.pc, frame.op, frame.stack)