Ultimate EVM Tracing Reference

This repo is a collection of trace-related information for easy reference.

A best effort is made to provide accurate information. Please submit corrections to the issue tracker.

Tracers
Trace Methods
Node Client Support
RPC Provider Support
Ecosystem Tooling Support
Hosted Data Platform Support
Example Tracer Data

Tracers

A tracer gives a detailed view into what happened during a block or transaction.

Each tracer type provides a different set of information. There are two main categories of tracers, parity and geth. Each node client supports these tracer types to varying degrees.

To see the specific information returned by each tracer, see the schemas and data samples in the Example Tracer Data below.

tracer	description	parameters
`parity calls`¹	calls in a flat list structure	`[ "trace" ]`
`parity stateDiffs`²	all state changes for each tx	`[ "stateDiff" ]`
`parity vmTraces`	opcode-level trace	`[ "vmTrace" ]`
`geth opcodes`	opcode-level trace	`{ }`
`geth calls`¹	calls in a nested structure	`{ "tracer": "callTracer" }`
`geth preState`²	data that was read before each tx	`{ "tracer": "prestateTracer" }`
`geth stateDiffs`²	all state changes for each tx	`{ "tracer": "prestateTracer", "diffMode": true }`
`geth 4byte`	4byte prefixes of function calls	`{ "tracer": "4byteTracer" }`
`geth javascript`³	custom javascript tracer functions	`{ "tracer": "{ fault: ..., result: ... }" }`

¹: Geth call traces contain nearly identical information to Parity call traces. There are differences such as 1) they include precompile calls, 2) they used a nested schema instead of a list, 3) they do not include block rewards. See here for additional differences.

²: There are four types of state changes: balances, codes, nonces, and storage. State-related traces include information about all four.

³: "tracer is interpreted as a JavaScript expression that is expected to evaluate to an object which must expose the result and fault methods. There exist 4 additional methods, namely: setup, step, enter, and exit. enter and exit must be present or omitted together."

Trace Methods

RPC methods are used to obtain trace data from RPC endpoints.

Each method applies one or more tracers to a particular scope of data, such as a block, transaction, or call data.

rpc method	description	tracers
`trace_block`	basic block trace	parity calls
`trace_transaction`	basic transaction trace	parity calls
`trace_replayBlockTransactions`	advanced block trace	all parity tracers
`trace_replayTransaction`	advanced transaction trace	all parity tracers
`trace_filter`	query a subset of traces	all parity tracers
`trace_call`	trace custom call_data	all parity tracers
`trace_callMany`	trace sequence of call_data	all parity tracers
`trace_rawTransaction`	parity call_data trace	all parity tracers
`trace_get`	parity indexed trace	parity calls
`debug_traceBlock`	advanced block trace	all geth tracers
`debug_traceTransaction`	basic transaction trace	all geth tracers
`debug_traceCall`	trace custom call_data	all geth tracers
`debug_traceBlockByNumber`	advanced block trace	all geth tracers
`debug_traceBlockByHash`	advanced block trace	all geth tracers

Node Client Support

Node clients track the state of the chain and can perform tracing on the chain's history.

Each node client supports a different set of tracers and trace methods.

rpc method	geth	reth	erigon	besu	nethermind
`trace_block`	❌	✅	✅	✅	✅
`trace_transaction`	❌	✅	✅	✅	✅
`trace_replayBlockTransactions`	❌	✅	✅	✅	✅
`trace_replayTransaction`	❌	✅	✅	❌	✅
`trace_filter`	❌	✅	✅	✅	✅
`trace_call`	❌	✅	✅	✅	✅
`trace_callMany`	❌	✅	✅	✅	❌
`trace_rawTransaction`	❌	✅	✅	✅	✅
`trace_get`	❌	✅	✅	✅	❌
`debug_traceBlock`	✅	✅	✅	✅	✅
`debug_traceTransaction`	✅	✅	✅	❌	✅
`debug_traceCall`	✅	✅	✅	❌	✅
`debug_traceBlockByNumber`	✅	✅	✅	❌	✅
`debug_traceBlockByHash`	✅	✅	✅	✅	✅

The set of traces that can be obtained for a chain is determined by the clients that support that chain:

rpc method	geth	reth	erigon	besu	nethermind	geth fork
ethereum	✅	✅	✅	✅	✅	❌
goerli	✅	✅	✅	✅	✅	❌
arbitrum	❌	❌	❌	❌	❌	✅
optimism	❌	✅	❌	❌	❌	✅
zora	❌	✅	❌	❌	❌	✅
base	❌	✅	❌	❌	❌	✅
polygon	❌	❌	✅	❌	❌	✅
gnosis	✅	❌	✅	✅	✅	❌
bnb	❌	❌	✅*	❌	❌	✅

RPC Provider Support

RPC providers create endpoints where customers can access RPC data without having to run their own nodes.

Every node provider supports different tracers and trace methods.

rpc method	infura	alchemy (pricing)	quicknode (pricing)	llamanodes (pricing)	chainstack (pricing)
`trace_block`	✅	✅	✅	✅	✅
`trace_transaction`	✅	✅	✅	✅	✅
`trace_replayBlockTransactions`	❌	✅	✅	✅	✅
`trace_replayTransaction`	❌	✅	✅	✅	✅
`trace_filter`	✅	✅	✅	✅	✅
`trace_call`	✅	✅	✅	✅	✅
`trace_callMany`	✅	❌	✅	✅	✅
`trace_rawTransaction`	❌	✅	✅	❌	✅
`trace_get`	❌	✅	❌	✅	✅
`debug_traceBlock`	❌	❌	✅	❌	✅
`debug_traceTransaction`	❌	✅	✅	✅	✅
`debug_traceCall`	❌	✅	✅	✅	✅
`debug_traceBlockByNumber`	❌	✅	✅	✅	✅
`debug_traceBlockByHash`	❌	✅	✅	✅	✅

Ecosystem Tooling Support

Many different tools exist for obtaining and analyzing traces.

Each tool supports a different set of tracers and trace methods. The libraries in the javascript ecosystem generally do not support tracing.

📟 = can use from command line
🐍 = can use as a python library
🦀 = can use as a rust library

tracer	cryo 📟🐍🦀	ethereum etl 📟	ethers.rs 🦀	ctc 🐍	ape 🐍	web3py 🐍
`parity calls`	✅	✅	✅	✅	✅	✅
`parity stateDiffs`	✅	❌	✅	✅	✅	✅
`parity vmTraces`	✅	❌	✅	✅	✅	✅
`geth opcodes`	✅	❌	✅	❌	✅	❌
`geth calls`	✅	✅	✅	✅	✅	❌
`geth preState`	✅	❌	✅	✅	✅	❌
`geth stateDiffs`	✅	❌	✅	✅	✅	❌
`geth 4byte counts`	✅	❌	✅	❌	❌	❌
`geth javascript`	✅	❌	✅	❌	❌	❌

Hosted Data Platform Support

Hosted data platforms allow customers to interact with trace data directly without running their own infrastructure.

Most platforms only support call traces.

tracer	Dune	Flipside	Bigquery	Allium
`parity calls`	✅	✅	✅	✅
`parity stateDiffs`	❌	❌	❌	❌
`parity vmTraces`	❌	❌	❌	❌
`geth opcodes`	❌	❌	❌	❌
`geth calls`	✅	✅	✅	✅
`geth preState`	❌	❌	❌	❌
`geth state diffs`	❌	❌	❌	❌
`geth 4byte counts`	❌	❌	❌	❌
`geth javascript`	❌	❌	❌	❌

Example Tracer Data

A 100 block sample of data is provided for each tracer (block range 10,000,000 through 10,000,099)

tracer	schema	data	collection command
`parity calls`	schema - action_from: binary - action_to: binary - action_value: string - action_gas: uint32 - action_input: binary - action_call_type: string - action_init: binary - action_reward_type: string - action_type: string - result_gas_used: uint32 - result_output: binary - result_code: binary - result_address: binary - trace_address: string - subtraces: uint32 - transaction_index: uint32 - transaction_hash: binary - block_number: uint32 - block_hash: binary - error: string - chain_id: uint64	parquet	`cryo traces -b 10M:+100`
`parity stateDiffs balances`	schema - transaction_hash: binary - block_number: uint32 - address: binary - from_value_string: string - from_value_binary: binary - from_value_f64: float64 - to_value_string: string - to_value_binary: binary - to_value_f64: float64 - chain_id: uint64 - transaction_index: uint32	parquet	`cryo balance_diffs -b 10M:+100`
`parity stateDiffs codes`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - address: binary - from_value: binary - to_value: binary - chain_id: uint64	parquet	`cryo code_diffs -b 10M:+100`
`parity stateDiffs nonces`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - address: binary - from_value: uint64 - to_value: uint64 - chain_id: uint64	parquet	`cryo nonce_diffs -b 10M:+100`
`parity stateDiffs storage`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - address: binary - slot: binary - from_value: binary - to_value: binary - chain_id: uint64	parquet	`cryo storage_diffs -b 10M:+100`
`parity vmTraces`	schema - block_number: uint32 - transaction_index: uint32 - pc: uint64 - cost: uint64 - used: uint64 - op: string - chain_id: uint64	parquet	`cryo vm_traces -b 10M:+100`
`geth opcodes`	schema - block_number: uint32 - transaction_hash: binary - transaction_index: uint32 - trace_address: string - depth: uint64 - error: string - gas: uint64 - gas_cost: uint64 - op: string - pc: uint64 - refund_counter: uint64 - return_data: binary - chain_id: uint64	parquet	`cryo geth_opcodes -b 10M:+100 \` `--include-columns stack storage`
`geth calls`	schema - typ: string - from_address: binary - to_address: binary - value_string: string - value_binary: binary - value_f64: float64 - gas_string: string - gas_binary: binary - gas_f64: float64 - gas_used_string: string - gas_used_binary: binary - gas_used_f64: float64 - input: binary - output: binary - error: string - block_number: uint32 - transaction_hash: binary - transaction_index: uint32 - trace_address: string - chain_id: uint64	parquet	`cryo geth_calls -b 10M:+100`
`geth prestate balances`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - address: binary - balance_binary: binary - balance_string: string - balance_f64: float64 - chain_id: uint64	parquet	`cryo balance_reads -b 10M:+100`
`geth prestate codes`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - contract_address: binary - code: binary - chain_id: uint64	parquet	`cryo code_reads -b 10M:+100`
`geth prestate nonces`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - address: binary - nonce: uint64 - chain_id: uint64	parquet	`cryo nonce_reads -b 10M:+100`
`geth prestate storages`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - contract_address: binary - slot: binary - value: binary - chain_id: uint64	parquet	`cryo storage_reads -b 10M:+100`
`geth stateDiffs balances`	schema - block_number: uint32 - transaction_index: uint64 - transaction_hash: binary - address: binary - from_value_f64: float64 - from_value_binary: binary - from_value_string: string - to_value_f64: float64 - to_value_binary: binary - to_value_string: string - chain_id: uint64	parquet	`cryo geth_balance_diffs -b 10M:+100`
`geth stateDiffs codes`	schema - block_number: uint32 - transaction_index: uint64 - transaction_hash: binary - address: binary - from_value: binary - to_value: binary - chain_id: uint64	parquet	`cryo geth_code_diffs -b 10M:+100`
`geth stateDiffs nonces`	schema - block_number: uint32 - transaction_index: uint64 - transaction_hash: binary - address: binary - from_value_f64: float64 - from_value_binary: binary - from_value_string: string - to_value_f64: float64 - to_value_binary: binary - to_value_string: string - chain_id: uint64	parquet	`cryo geth_nonce_diffs -b 10M:+100`
`geth stateDiffs storages`	schema - block_number: uint32 - transaction_index: uint64 - transaction_hash: binary - address: binary - slot: binary - from_value: binary - to_value: binary - chain_id: uint64	parquet	`cryo geth_storage_diffs -b 10M:+100`
`geth 4byte counts`	schema - block_number: uint32 - transaction_index: uint32 - transaction_hash: binary - signature: binary - size: uint64 - count: uint64 - chain_id: uint64	parquet	`cryo 4byte_counts -b 10M:+100`

paradigmxyz/ultimate_evm_tracing_reference

paradigmxyz

Reviews

Repository Details