REVM Transaction Simulator and Asset Tracer

A Rust library for simulating EVM-compatible blockchain transactions and tracking asset transfers, logs, and events using REVM. This library provides a safe and efficient way to simulate transactions and analyze their effects without actually submitting them to the blockchain.

Features

Transaction Simulation: Simulate transactions on any EVM-compatible chain (Ethereum, BSC, Polygon, etc.)
Asset Transfer Tracking: Track both native tokens (ETH, BNB, MATIC, etc.) and ERC20 token transfers
Event Collection: Capture and analyze all transaction logs and events
Token Information: Automatically collect token symbols and decimals
Proxy Support: Handle proxy contracts with implementation resolution
Safe Execution: Simulate transactions without affecting the blockchain
Flexible Inspector: Customizable transaction tracing

Installation

Add this to your Cargo.toml:

revm-trace = "1.0.0"

Quick Start

use revm_trace::{
  trace_tx_assets,
  create_evm_instance_with_tracer,
};
async fn example() -> anyhow::Result<()> {
  // Create EVM instance with transaction tracer
  let inspector = TransactionTracer::default();
  
  let mut evm = create_evm_instance_with_tracer(
    "https://rpc.ankr.com/eth", // Can be any EVM-compatible chain RPC
    Some(1) // Chain ID: 1 for Ethereum mainnet
  )?;
  
  // Simulate transaction and track transfers
  let result = trace_tx_assets(
    &mut evm,
    from_address,
    to_address,
    value,
    call_data,
    "ETH"  // Native token symbol
  ).await;
  
  // Process results
  for transfer in result.asset_transfers() {
    if transfer.is_native_token() {
      println!("Native token transfer: {} -> {}: {}",
        transfer.from,
        transfer.to,
        transfer.value
      );
    } else {
      let token_info = result.token_info.get(&transfer.token)
        .expect("Token info should exist");
      println!("Token transfer: {} {} -> {}: {}",
        token_info.symbol,
        transfer.from,
        transfer.to,
        transfer.value
      );
    }
  }
  // Process logs
  for log in result.logs {
    println!("Log from {}: {:?}", log.address, log);
  }
  Ok(())
}

Usage Examples

Tracking DeFi Transactions

// Example of tracking a Uniswap-like DEX swap on any EVM chain
let router = address!("7a250d5630B4cF539739dF2C5dAcb4c659F2488D");
let result = trace_tx_assets(
  &mut evm,
  user_address,
  router,
  native_token_amount,
  swap_data,
  "BNB"  // Use appropriate native token symbol
).await;
// Process transfers and logs
for transfer in result.asset_transfers() {
  println!("Transfer: {:?}", transfer);
}
for log in result.logs {
  if log.topics()[0] == SWAP_EVENT_SIGNATURE {
    println!("Swap event: {:?}", log);
  }
}

Reusing EVM Instance

When simulating multiple transactions using the same EVM instance, you need to reset the inspector state between simulations:

use revm_trace::{
  trace_tx_assets,
  create_evm_instance_with_tracer,
  GetTransactionTracer,
  Reset,
};
async fn simulate_multiple_txs() -> anyhow::Result<()> {
  let mut evm = create_evm_instance_with_tracer(
    "https://rpc.ankr.com/eth",
    Some(1)
  )?;
  // First simulation
  let result1 = trace_tx_assets(&mut evm, from, to1, value1, data1, "ETH").await;
  // Reset inspector state before next simulation
  evm.reset_inspector();
  // Second simulation with clean state
  let result2 = trace_tx_assets(&mut evm, from, to2, value2, data2, "ETH").await;
  Ok(())
}

Setting Block Environment

You can customize the block environment for simulation:

use revm_trace::{
  trace_tx_assets,
  create_evm_instance_with_tracer,
  BlockEnvConfig,
};
async fn simulate_at_specific_block() -> anyhow::Result<()> {
  let mut evm = create_evm_instance_with_tracer(
    "https://rpc.ankr.com/eth",
    Some(1)
  )?;
  // Set specific block number and timestamp
  evm.set_block_number(17_000_000)
  	.set_block_timestamp(1677777777);
  // Or set both at once
  evm.set_block_env(17_000_000, 1677777777);
  let result = trace_tx_assets(&mut evm, from, to, value, data, "ETH").await;
  Ok(())
}

Thread Safety and Parallel Processing

Important Note on Thread Safety

The core Evm instance from REVM is not thread-safe, and consequently, our tracing functionality cannot be used across threads. This means you cannot share an Evm instance between threads or use it in parallel operations.

Recommended Usage Patterns

❌ What to Avoid

// This will NOT work - do not share Evm across threads
let mut evm = create_evm_instance_with_tracer("https://rpc...", Some(1))?;
let handles: Vec<> = transactions
	.into_par_iter() // ❌ Parallel processing will fail
	.map(|tx| {
		trace_tx_assets(&mut evm, tx.from, tx.to, tx.value, tx.data, "ETH")
	})
	.collect();

✅ Correct Usage

// Create separate EVM instances for each thread
let handles: Vec<> = transactions
  .into_iter() // ✅ Sequential processing
  .map(|tx| {
  	let mut evm = create_evm_instance_with_tracer("https://rpc...", Some(1))?;
  	trace_tx_assets(&mut evm, tx.from, tx.to, tx.value, tx.data, "ETH")
  })
  .collect();

// Alternative: If you need parallel processing
	use rayon::prelude::;
  let results: Vec<> = transactions
  .par_iter()
  .map(|tx| {
    let mut evm = create_evm_instance_with_tracer("https://rpc...", Some(1))?;
    trace_tx_assets(&mut evm, tx.from, tx.to, tx.value, tx.data, "ETH")
  })
  .collect();

Performance Considerations

Create new EVM instances for parallel operations
Consider connection pool limits of your RPC provider
Balance between parallelism and RPC rate limits

Working with Proxy Contracts

The library automatically handles proxy contracts by resolving their implementations:

EIP-1967 proxies
EIP-1967 beacon proxies
OpenZeppelin transparent proxies
EIP-1822 (UUPS) proxies

Features in Detail

Asset Transfer Tracking

Native token transfers (including internal transfers)
ERC20 token transfers
Transaction logs and events
Chronological ordering of transfers
Complete token information collection

Transaction Simulation

Full EVM context simulation
Custom environment configuration
Detailed execution results
Error handling and revert messages

Historical State Access

When accessing historical blockchain state, capabilities depend on the node type:

Archive Nodes: Can access any historical block state
Full Nodes: Limited to recent blocks (typically ~128 blocks)

The actual accessible block range varies by provider and node configuration.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

Built with REVM and Alloy

revm-trace 1.0.0