Debug Tracing Overview
Requirements
Install Ethers.js v6.14.4+:
npm install ethers@^6.14.4
All examples use modern ES6 modules and TypeScript patterns.
Debug tracing is your primary tool for understanding EVM transaction execution on Sei. This comprehensive system allows you to analyze transaction flow, optimize gas usage, debug smart contract interactions, and troubleshoot production issues.
What You Can Trace
Transaction Execution
- Step-by-step opcode execution
- Contract call hierarchy
- Gas consumption breakdown
- State changes and storage access
Contract Interactions
- Cross-contract calls and returns
- Event emission analysis
- Precompile usage tracking
- External library calls
Performance Analysis
- Gas optimization opportunities
- Bottleneck identification
- Cache hit/miss patterns
- State access efficiency
Security Analysis
- Suspicious operation detection
- Reentrancy pattern analysis
- Access control verification
- Vulnerability scanning
Available Tracing Methods
Method | Purpose | Use Case |
---|---|---|
debug_traceTransaction | Trace specific transaction | Debugging failed transactions |
debug_traceBlockByNumber | Trace entire block | Block-level analysis |
debug_traceCall | Simulate and trace | Testing before execution |
debug_traceStateAccess | State access patterns | Performance optimization |
Transaction Analysis Example
Tracing an ERC-20 transfer transaction:
Transaction Details
# Real transaction on Sei mainnet
TRANSACTION_HASH="0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3"
# Transaction details
curl -X POST -H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "eth_getTransactionByHash",
"params": ["'$TRANSACTION_HASH'"],
"id": 1
}' \
https://evm-rpc.sei-apis.com
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"blockHash": "0xbc229fe41605ba2b46fcd7aa7ce328dc2f6da78385dfea84ca8dbef7b4325462",
"blockNumber": "0x97aefcf",
"from": "0x4cbee7ad42d33e9d3b41e8b6faca2f6f173c8a94",
"gas": "0x66f24",
"gasPrice": "0x565dd756",
"maxFeePerGas": "0x565dd756",
"maxPriorityFeePerGas": "0x5e679d6",
"hash": "0x75b7ba10248e90db85b224eae587db1728520b6f72c795b9185064f444cee7c3",
"input": "0x733214a3e5f551789f7ee58322679a2b141e64533098b8ba41d9e10cf8061a18a777d6ce00000000000000000000000000000000000000000000000000000000000000c000000000000000000000000000000000000000000000000000000000000001000000000000000000000000004cbee7ad42d33e9d3b41e8b6faca2f6f173c8a940000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000000f6a756d7065722e65786368616e67650000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002a30783030303030303030303030303030303030303030303030303030303030303030303030303030303000000000000000000000000000000000000000000000000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f000000000000000000000000fde9ce4e17b650efdca13d524f132876700d806f0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004faaa00000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000001642646478b0000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000000000000000000000000000000000000004faaa000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000dd26083bfc745570000000000000000000000001231deb6f5749ef6ce6943a275a1d3e7486f4eae00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000070023894085ef7ff0f0aedf52e2a2704928d1ec074f101ffff015cfa8db453c9904511c4ea9eb0bfc903e36b9f5f01fde9ce4e17b650efdca13d524f132876700d806f01e30fedd158a2e3b13e9badaeabafc5516e95e8c701ffff02001231deb6f5749ef6ce6943a275a1d3e7486f4eae0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"nonce": "0x4",
"to": "0x1231deb6f5749ef6ce6943a275a1d3e7486f4eae",
"transactionIndex": "0x14",
"value": "0x0",
"type": "0x2",
"accessList": [],
"chainId": "0x531",
"v": "0x0",
"r": "0x3a107aca9cd554a9171a65ea2e8ef56ebeca8cfdc17f4bbecfb0f86837ca90d6",
"s": "0x426134cf65b701bc8d43162f78bcf787319ff17cc6293188bcbb30fd99feb60",
"yParity": "0x0"
}
}
Debugging Failed Transactions
Steps to analyze and resolve transaction failures:
Step 1: Identify the Problem
# Get transaction receipt
FAILED_TX="0xb2a6f4f7f37d8df728968126c05d1a8b0391003cf375ed5abb1b5e02fe66c717"
curl -X POST -H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "eth_getTransactionReceipt",
"params": ["'$FAILED_TX'"],
"id": 1
}' \
https://evm-rpc.sei-apis.com
Step 2: Trace the Execution
# Trace to see where it failed
curl -X POST -H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_traceTransaction",
"params": [
"'$FAILED_TX'",
{
"tracer": "callTracer",
"tracerConfig": {
"withLog": true
}
}
],
"id": 1
}' \
https://evm-rpc.sei-apis.com
Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"from": "0x2c80b1b0473bb765ef536d2526ec63195794d945",
"gas": "0xc3500",
"gasUsed": "0x2863d",
"to": "0xd1efe48b71acd98db16fcb9e7152b086647ef544",
"input": "0x414bf3890000000000000000000000003894085ef7ff0f0aedf52e2a2704928d1ec074f1000000000000000000000000e30fedd158a2e3b13e9badaeabafc5516e95e8c70000000000000000000000000000000000000000000000000000000000000bb80000000000000000000000002c80b1b0473bb765ef536d2526ec63195794d94500000000000000000000000000000000000000000000000000000000688a24580000000000000000000000000000000000000000000000000000000031aba85500000000000000000000000000000000000000000000009556d1a971e567965b0000000000000000000000000000000000000000000000000000000000000000",
"output": "0x08c379a000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000013546f6f206c6974746c6520726563656976656400000000000000000000000000",
"error": "execution reverted",
"revertReason": "Too little received",
"calls": [
...
]
}
}
Step 3: Fix and Test
# Simulate the fix with debug_traceCall
curl -X POST \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"method": "debug_traceCall",
"params": [
{
"from": "0x2c80b1b0473bb765ef536d2526ec63195794d945",
"to": "0xd1efe48b71acd98db16fcb9e7152b086647ef544",
"gas": "0xc3500",
"gasPrice": "0x2127ddd32",
"value": "0x0"
},
"0x98a87cc",
{
"tracer": "callTracer",
"tracerConfig": {
"onlyTopCall": false,
"withLog": true
}
}
],
"id": 1
}' \
https://evm-rpc.sei-apis.com
Common Debugging Scenarios
Transaction Reverted
Problem: Transaction failed with revert
Solution: Use callTracer
to find the exact revert reason
Out of Gas
Problem: Transaction ran out of gas Solution: Use gas analysis tracer to optimize gas usage
Unexpected Behavior
Problem: Transaction succeeded but wrong result Solution: Use opcode tracer for step-by-step analysis
Slow Performance
Problem: Transaction uses too much gas Solution: Use state access tracer to find inefficiencies
Quick Reference
Essential Commands
# Trace transaction
debug_traceTransaction(hash, {tracer: "callTracer"})
# Trace block
debug_traceBlockByNumber("latest", {tracer: "callTracer"})
# Simulate call
debug_traceCall(tx, "latest", {tracer: "callTracer"})
# State access
debug_traceStateAccess(hash)
Common Tracers
callTracer
: Contract call hierarchyopcodeTracer
: Opcode-level execution- Custom JS: Custom analysis logic
Next Steps
- JavaScript Tracers - Custom analysis scripts
- Complete Workflows - Real-world debugging scenarios
- Troubleshooting - Common issues and solutions
callTracer
for general debugging, then use specialized tracers for specific analysis needs.