trace_transaction

The trace_transaction method retrieves detailed trace information for a transaction identified by its hash. This method provides insight into every step of the transaction's execution, including internal calls between contracts, allowing for in-depth analysis and debugging.

Use Cases

• Debugging specific transactions to identify errors
• Analyzing gas consumption for individual operations
• Tracing internal calls within a transaction
• Understanding complex contract interactions
• Investigating transaction failures
• Security auditing and vulnerability analysis
• Verifying expected contract behavior
• Tracking funds flow across multiple contracts
• Analyzing execution patterns of similar transactions
• Debugging failed or reverted transactions

Method Details

This method returns an array of traces for all operations executed during the transaction.

Response Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": [
		{
			"action": {
				"callType": "call",
				"from": "0x83806d539d4ea1c140489a06660319c9a303f874",
				"gas": "0x1a1f8",
				"input": "0x",
				"to": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
				"value": "0x7a16c911b4d00000"
			},
			"blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
			"blockNumber": 3068185,
			"result": {
				"gasUsed": "0x2982",
				"output": "0x"
			},
			"subtraces": 2,
			"traceAddress": [],
			"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
			"transactionPosition": 2,
			"type": "call"
		},
		{
			"action": {
				"callType": "call",
				"from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
				"gas": "0x13e99",
				"input": "0x16c72721",
				"to": "0x2bd2326c993dfaef84f696526064ff22eba5b362",
				"value": "0x0"
			},
			"blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
			"blockNumber": 3068185,
			"result": {
				"gasUsed": "0x183",
				"output": "0x0000000000000000000000000000000000000000000000000000000000000001"
			},
			"subtraces": 0,
			"traceAddress": [0],
			"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
			"transactionPosition": 2,
			"type": "call"
		},
		{
			"action": {
				"callType": "call",
				"from": "0x1c39ba39e4735cb65978d4db400ddd70a72dc750",
				"gas": "0x8fc",
				"input": "0x",
				"to": "0x70faa28a6b8d6829a4b1e649d26ec9a2a39ba413",
				"value": "0x7a16c911b4d00000"
			},
			"blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
			"blockNumber": 3068185,
			"result": {
				"gasUsed": "0x0",
				"output": "0x"
			},
			"subtraces": 0,
			"traceAddress": [1],
			"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
			"transactionPosition": 2,
			"type": "call"
		}
	]
}

Understanding the Trace Tree

The trace tree represents the execution flow of the transaction:

1. Root level trace: The main transaction (empty traceAddress)
2. Subtrace level 1: Internal calls directly from the main transaction (traceAddress of [0], [1], etc.)
3. Deeper levels: Subsequent internal calls (traceAddress of [0, 0], [0, 1], etc.)

Call Types

The callType field may have different values:

• call: A regular message call
• delegatecall: A call where the code is executed in the context of the caller
• staticcall: A read-only call (no state modifications allowed)
• callcode: Similar to delegatecall but with the value passed (legacy)

Trace Types

The type field indicates the operation type:

• call: A message call
• create: A contract creation
• suicide: A contract self-destruct (SELFDESTRUCT opcode)

Important Notes

• This method requires trace APIs to be enabled on the Ethereum node
• The response can be very large for complex transactions with many internal calls
• The method is computationally intensive and may take time to complete for complex transactions
• Not all Ethereum clients support this method
• Historical transactions can only be traced if the node maintains archive data
• Some clients may have limitations on how far back transactions can be traced
• For more detailed VM-level execution traces, consider using trace_replayTransaction
• Unlike event logs, traces capture all contract interactions including those that don't emit events
• Failed transactions will still produce traces up to the point of failure
• SELFDESTRUCT operations appear with type "suicide" for historical reasons

See also

• trace_filter - Search for traces based on criteria
• trace_block - Retrieve traces for all transactions in a block
• trace_replayTransaction - Get more detailed traces with state changes
• debug_traceTransaction - Alternative detailed transaction tracing