evm-trace

0.2.6 verified Fri May 01 auth: no python

A Python library for Ethereum Virtual Machine transaction tracing, providing tools to decode and analyze EVM execution traces. Current version 0.2.6 (stable). Release cadence is irregular, with several patches per year.

pip install evm-trace

Common errors

error ImportError: cannot import name 'CallTreeNode' from 'evm_trace.call_trace' ↓

cause The CallTreeNode class is re-exported from the top-level package, not from the submodule.

fix

Use: from evm_trace import CallTreeNode

error ModuleNotFoundError: No module named 'msgspec' ↓

cause evm-trace version 0.2.4 removed msgspec from dependencies, but it's required for some optional functionality.

fix

Install msgspec separately: pip install msgspec, or upgrade evm-trace to >=0.2.5.

error TypeError: Object of type 'TraceFrame' is not JSON serializable ↓

cause Custom objects need serialization utilities.

fix

Use .dict() or .json() methods from Pydantic base model.

Warnings

breaking v0.2.0 dropped Python 3.8 support and added Python 3.12 support. ↓

fix Upgrade Python to 3.9+.

deprecated The msgspec dependency was removed in v0.2.4 due to Python 3.13 incompatibility, then reintroduced in v0.2.5 for 3.13+. ↓

fix Use evm-trace >=0.2.5 for Python 3.13 support.

gotcha TraceFrame fields may contain large integers; ensure your environment handles them properly. ↓

fix Use Python's built-in int (unbounded) – no need for custom handling.

Imports

TraceFrame
```
from evm_trace import TraceFrame
```

CallTreeNode

wrong

from evm_trace.call_trace import CallTreeNode

correct

from evm_trace import CallTreeNode

The correct import is from the top-level package.

Quickstart

Parses a raw EVM trace frame into a structured object. Replace raw_frame with actual trace data from an RPC provider.

from evm_trace import TraceFrame
# Example: process a raw trace dict
raw_frame = {
    'pc': 0,
    'op': 96,
    'gas': 100000,
    'gas_cost': 3,
    'depth': 0,
    'stack': [],
    'memory': [],
    'storage': {}
}
tf = TraceFrame.parse_obj(raw_frame)
print(tf.op)  # 96 (PUSH1)