trace_filter

The trace_filter method allows you to search for specific traces within a range of blocks, filtering by various criteria such as from/to addresses, block range, and trace types. This provides a powerful way to analyze blockchain activity for specific contracts or accounts.

Use Cases

• Finding all internal transactions for a specific address
• Tracking token transfers that aren't visible in transaction logs
• Forensic analysis of contract interactions and vulnerabilities
• Monitoring specific contract calls across a range of blocks
• Auditing contract-to-contract interactions for security review
• Analyzing smart contract execution patterns
• Detecting MEV and frontrunning activities
• Tracing arbitrage paths across DeFi protocols
• Building comprehensive block explorers
• Validating complex financial flows in DeFi applications

Method Details

This method retrieves transaction traces based on the specified filter criteria.

Filter Parameters

Response Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": [
		{
			"action": {
				"callType": "call",
				"from": "0x8bbb73bcb5d553b5a556358d27625323fd781d37",
				"to": "0x6090a6e47849629b7245dfa1ca21d94cd15878ef",
				"gas": "0x12a94",
				"input": "0x0000000000000000000000000000000000000000000000000000000000000000",
				"value": "0x0"
			},
			"blockHash": "0x7eb25504e4c202cf3d62fd585d3e238f592c780cca82dacb2ed3cb5b38883add",
			"blockNumber": 3928366,
			"result": {
				"gasUsed": "0xd979",
				"output": "0x0000000000000000000000000000000000000000000000000000000000000001"
			},
			"subtraces": 1,
			"traceAddress": [],
			"transactionHash": "0x17104ac9d3312d8c136b7f44d4b8b47852618065ebfa534bd2d3b5ef218ca1f3",
			"transactionPosition": 2,
			"type": "call"
		}
	]
}

Filter Strategies

Different filter combinations can be used to answer specific questions:

To find all calls to a specific contract:

{
  "toAddress": ["0x1234567890123456789012345678901234567890"]
}

To find all internal transactions from a contract:

{
  "fromAddress": ["0x1234567890123456789012345678901234567890"]
}

To find interactions between two specific addresses:

{
  "fromAddress": ["0x1234567890123456789012345678901234567890"],
  "toAddress": ["0xabcdef0123456789abcdef0123456789abcdef01"]
}

To analyze activity within a specific block range:

{
  "fromBlock": "0x429d3b",
  "toBlock": "0x429d3d"
}

Pagination

For large result sets, use the after and count parameters to paginate through results:

1. First request: { "after": 0, "count": 100, ... }
2. Next request: { "after": 100, "count": 100, ... }
3. Continue incrementing after by count value

Performance Considerations

• Filtering across large block ranges can be resource-intensive
• Always specify the narrowest block range necessary
• Use address filtering to reduce result set size
• Consider splitting large queries into smaller block ranges
• For heavy usage, consider running your own archive node with trace indexing

Trace Types

The method returns different types of traces:

• call: A message call to an address
• create: A contract creation
• suicide: A contract self-destruct operation (also known as SELFDESTRUCT)

Important Notes

• This method requires trace APIs to be enabled on the Ethereum node
• Not all Ethereum clients support trace filtering (primarily Geth with --gcmode=archive and OpenEthereum/Nethermind)
• Public RPC providers often limit or disable trace methods due to their resource intensity
• Filters apply only to the stored traces, not to log events (use eth_getLogs for event logs)
• The response size can be very large for wide block ranges or popular addresses
• Block range restrictions may be imposed by the RPC provider (often limited to a few thousand blocks)
• Calling this method on a non-archive node will return incomplete results
• Trace filtering is significantly more resource-intensive than regular transaction queries
• Unlike events, traces are not indexed by topics but only by addresses and block numbers
• Transactions that failed due to out-of-gas or reverts still produce traces up to the failure

See also

• trace_transaction - Retrieve traces for a single transaction
• trace_block - Retrieve traces for all transactions in a block
• trace_call - Execute and trace a call without creating a transaction
• eth_getLogs - Alternative for filtering event logs
• debug_traceTransaction - Get lower-level execution details for transactions