Skip to content

a collection of EVM tracing information for easy reference

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

paradigmxyz/ultimate_evm_tracing_reference

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
 
 
 
 
 
 

Repository files navigation

Ultimate EVM Tracing Reference

Telegram Chat

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.

Contents

  1. Tracers
  2. Trace Methods
  3. Node Client Support
  4. RPC Provider Support
  5. Ecosystem Tooling Support
  6. Hosted Data Platform Support
  7. 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 calls1 calls in a flat list structure [ "trace" ]
parity stateDiffs2 all state changes for each tx [ "stateDiff" ]
parity vmTraces opcode-level trace [ "vmTrace" ]
geth opcodes opcode-level trace { }
geth calls1 calls in a nested structure { "tracer": "callTracer" }
geth preState2 data that was read before each tx { "tracer": "prestateTracer" }
geth stateDiffs2 all state changes for each tx { "tracer": "prestateTracer", "diffMode": true }
geth 4byte 4byte prefixes of function calls { "tracer": "4byteTracer" }
geth javascript3 custom javascript tracer functions { "tracer": "{ fault: ..., result: ... }" }

1: 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.

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

3: "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

About

a collection of EVM tracing information for easy reference

Topics

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Stars

Watchers

Forks