Ethereum Virtual Machine transaction tracing tool

• python3 version 3.8 to 3.11.

You can install the latest release via pip:

pip install evm-trace

You can clone the repository and use setuptools for the most up-to-date version:

git clone https://github.com/ApeWorX/evm-trace.git
cd evm-trace
python3 setup.py install

If you are using a node that supports the debug_traceTransaction RPC, you can use web3.py to get trace frames:

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)

If you want to get the call-tree node, you can do:

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,
}

# Where `trace` is a `TraceFrame` (see example above)
calltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)

If you are using a node that supports the trace_transaction RPC, you can use web3.py to get trace objects:

from evm_trace import CallType, ParityTraceList

raw_trace_list = web3.manager.request_blocking("trace_transaction", [txn_hash])
trace_list = ParityTraceList.model_validate(raw_trace_list)

And to make call-tree nodes, you can do:

from evm_trace import get_calltree_from_parity_trace

tree = get_calltree_from_parity_trace(trace_list)

If you are using a node that supports creating traces, you can get a gas report.

from evm_trace.gas import get_gas_report

# see examples above for creating a calltree
calltree = get_calltree_from_geth_trace(trace, **root_node_kwargs)

gas_report = get_gas_report(calltree)

For a more custom report, use the merge_reports method to combine a list of reports into a single report. Pass two or more Dict[Any, Dict[Any, List[int]]] to combine reports where List[int] is the gas used.

Customize the values of Any accordingly:

1. The first Any represents the bytes from the address.
2. The second Any represents the method selector.

For example, you may replace addresses with token names or selector bytes with signature call strings.

Import the method like so:

from evm_trace.gas import merge_reports

This project is in development and should be considered a beta. Things might not be in their final state and breaking changes may occur. Comments, questions, criticisms and pull requests are welcomed.

This project is licensed under the Apache 2.0.