Debugging for EVM

Overview

To debug EVM transactions on Sei, you need to understand both how transactions are created and how to analyze their behavior. This guide covers advanced debugging techniques: transaction template generation, analysis tools, and transaction inspection methods. Use them to find and fix issues in your EVM interactions.

Transaction template generation

The --generate-only flag turns any seid transaction command into a template generator. The command creates a complete transaction structure but does not broadcast it. With the --generate-only flag and Foundry’s cast tool, you can build, analyze, and debug transactions in the EVM environment.

Basic command pattern

The general command pattern is:

seid tx <module> <action> <parameters> --from <key> --evm-rpc http://url-to-sei-evm-rpc --generate-only

Generating EVM transaction templates

To generate an EVM transaction template, use the evm module with --generate-only. This example sends SEI to another EVM address:

seid tx evm send 0xRecipientAddress 1000000000000000000 \
--gas-fee-cap=100000000000 \
--gas-limit=21000 \
--evm-rpc=http://url-to-sei-evm-rpc \
--from=mykey \
--generate-only

This command returns a transaction template that you can analyze before you broadcast it. The template includes all transaction details, but the command does not execute the transaction.

Analyzing EVM transactions with Cast

When you have a transaction hash, you can use Foundry’s cast command to inspect the transaction details:

cast tx 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=http://url-to-sei-evm-rpc

Example output:

blockHash               0x4696d63a9a9ae88b03bcc94ccbd87f407e994b309d1dff9c0626de51ac57b76e
blockNumber             130076639
from                    0xAa55a16dD4E73c48C968928983c2bcC98d913d96
transactionIndex        7
effectiveGasPrice       100000000000
accessList              []
chainId                 1329
gasLimit                2500000
hash                    0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1
input                   0xc31d960f0000...
maxFeePerGas            100000000000
maxPriorityFeePerGas    100000000000
nonce                   3
to                      0x000000000000000000000000000000000000100b
type                    2
value                   0

Additional analysis commands

Get the transaction receipt:

cast receipt 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=http://url-to-sei-evm-rpc

Decode the transaction input data:

cast 4byte-decode 0xc31d960f0000...

All template generation commands create JSON files. You can inspect, modify, and use these files for debugging before you execute the transactions.

RPC consistency

Always point cast commands to an EVM RPC endpoint (for example, $EVM_RPC_URL), not a Cosmos RPC URL.

Tracing and revert reasons

If your endpoint supports debug RPC methods, you can get full execution traces and revert reasons:

# Full transaction trace
cast rpc debug_traceTransaction 0xTX_HASH '{"tracer":"callTracer","timeout":"120s"}' \
  --rpc-url=$EVM_RPC_URL

# Simulate and trace a call without broadcasting
cast rpc debug_traceCall '{"from":"0xFROM","to":"0xTO","data":"0xDATA"}' \
  'latest' '{"tracer":"callTracer","timeout":"120s"}' \
  --rpc-url=$EVM_RPC_URL

Many public RPC endpoints disable debug methods. If they are disabled, run a local fork and trace there. See the tracing documentation.

Reproduce with a local fork

Fork the network locally to reproduce issues deterministically. You can then run traces even if the remote debug RPC is disabled:

# Start a local fork
anvil --fork-url $EVM_RPC_URL

# Re-run calls against the fork
cast call 0xContract "method(uint256)" 1 --rpc-url=http://127.0.0.1:8545

# Trace the call on the fork via debug RPC
cast rpc debug_traceCall '{"to":"0xContract","data":"0xENCODED_DATA"}' \
  'latest' '{"tracer":"callTracer"}' --rpc-url=http://127.0.0.1:8545

Event logs and decoding

Use the receipt to inspect the logs, and decode them with the contract ABI:

# Fetch receipt JSON and view logs
cast receipt 0xTX_HASH --rpc-url=$EVM_RPC_URL --json | jq '.logs'

# Compute an event signature for topic[0]
cast keccak "Transfer(address,address,uint256)"

Decode event topics and data with the contract ABI (from your repository or a block explorer). Topic[0] equals the keccak hash of the event signature.

Nonce, balance, and gas diagnostics

Check common failure points quickly:

cast nonce 0xYourAddress --rpc-url=$EVM_RPC_URL
cast balance 0xYourAddress --rpc-url=$EVM_RPC_URL
cast gas-price --rpc-url=$EVM_RPC_URL
cast block latest baseFeePerGas --rpc-url=$EVM_RPC_URL
cast chain-id --rpc-url=$EVM_RPC_URL

Checklist:

Incorrect nonce (a pending transaction in the mempool)
Insufficient native balance for gas
Underpriced maxFeePerGas or maxPriorityFeePerGas
Chain ID mismatch

Try it live

Each cast diagnostic above is a plain read-only JSON-RPC call. Run four of them against Sei Mainnet here. The example address (0xAa55…3d96) is the sender from the cast tx output earlier on this page.

Offline workflow with —generate-only

Generate, inspect, sign, and broadcast a transaction safely:

# 1) Generate a template (no broadcast)
seid tx evm send 0xTO 1000000000000000000 \
  --from=$WALLET_NAME --evm-rpc=$EVM_RPC_URL --generate-only > tx.json

# 2) Sign offline with your key
seid tx sign tx.json --from $WALLET_NAME --chain-id $CHAIN_ID > signed.json

# 3) Broadcast the signed tx
seid tx broadcast signed.json

Never commit signed transactions or private keys. Use environment variables and .gitignore for sensitive data.

Precompile awareness

Calls to system precompiles (for example, addresses such as 0x...100b) may have specific input and output formats and error behavior.

See EVM precompiles and CosmWasm precompiles
Cross-check expected selectors, parameter encoding, and revert messages

Storage inspection

When you debug state changes, check the on-chain state directly:

cast storage 0xContract 0xSLOT --rpc-url=$EVM_RPC_URL

Transaction analysis

When you analyze transactions, follow these practices:

Always verify EVM transactions thoroughly
Use cast to decode the input data of EVM transactions
Keep track of gas parameters
Monitor the transaction status on the EVM layer

Analysis tips:

# Use Foundry's cast tool for detailed transaction inspection
cast tx 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=$EVM_RPC_URL

# Get transaction receipt to verify success
cast receipt 0x5010e6600e67f04a9bc3d3b670a7c2de380b180713d9a014a5dbd76b7e2190f1 \
--rpc-url=$EVM_RPC_URL

# Decode transaction input data
cast 4byte-decode 0xa9059cbb000000...

Transaction analysis checklist: Always verify that a transaction succeeded before you continue. Check gas usage to optimize future transactions. Use Foundry’s cast tool for detailed transaction inspection.

Error handling

Monitor EVM transactions so that you can handle potential issues:

try {
  // Check EVM transaction status
  const evmStatus = await checkEvmStatus(txHash);
  if (!evmStatus.success) {
    const evmError = await cast.call(['tx', txHash, '--rpc-url', evmRpcUrl]);
    console.error('EVM transaction failed:', evmError);
  }
} catch (error) {
  console.error('Transaction analysis failed:', error);
}

Best practices for error handling:

Always check the transaction status on both the Cosmos and EVM layers
Use detailed error logging to debug failed transactions
Implement retry logic for network-related failures
Monitor gas usage and adjust limits accordingly

Security guidelines

Critical security requirements: Keep private keys secure, and never include them in templates. When you work with wallet keys or mnemonics, use an .env file or other environment variables. Never commit sensitive information to version control. Always verify transaction details before you sign.

Environment variable setup:

# Create .env file for sensitive data
WALLET_NAME=mykey
EVM_RPC_URL=http://url-to-sei-evm-rpc
PRIVATE_KEY=your_private_key_here

# Add .env to .gitignore
echo ".env" >> .gitignore

Secure transaction execution:

# Use environment variables in commands
seid tx evm send 0x1234567890abcdef... 1000000000000000000 \
--from=$WALLET_NAME \
--evm-rpc=$EVM_RPC_URL

# Generate transaction template first to verify details
seid tx evm send 0x1234567890abcdef... 1000000000000000000 \
--from=$WALLET_NAME \
--evm-rpc=$EVM_RPC_URL \
--generate-only

Overview

Essentials

seid CLI

Frontend Development

Smart Contracts

sei-js Library

Videos

Ecosystem Tutorials

Reference

Hardware Wallets

Debugging for EVM

Overview

Transaction template generation

Basic command pattern

Generating EVM transaction templates

Analyzing EVM transactions with Cast

Additional analysis commands

RPC consistency

Tracing and revert reasons

Reproduce with a local fork

Event logs and decoding

Nonce, balance, and gas diagnostics

Try it live

Offline workflow with —generate-only

Precompile awareness

Storage inspection

Transaction analysis

Error handling

Security guidelines

​Overview

​Transaction template generation

​Basic command pattern

​Generating EVM transaction templates

​Analyzing EVM transactions with Cast

​Additional analysis commands

​RPC consistency

​Tracing and revert reasons

​Reproduce with a local fork

​Event logs and decoding

​Nonce, balance, and gas diagnostics

​Try it live

​Offline workflow with —generate-only

​Precompile awareness

​Storage inspection

​Transaction analysis

​Error handling

​Security guidelines

Overview

Transaction template generation

Basic command pattern

Generating EVM transaction templates

Analyzing EVM transactions with Cast

Additional analysis commands

RPC consistency

Tracing and revert reasons

Reproduce with a local fork

Event logs and decoding

Nonce, balance, and gas diagnostics

Try it live

Offline workflow with —generate-only

Precompile awareness

Storage inspection

Transaction analysis

Error handling

Security guidelines