REVM Transaction Simulator and Asset Tracer

A Rust library for simulating EVM-compatible blockchain transactions and tracking asset transfers (native tokens and ERC20 tokens) 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
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 asset transfer tracking

Installation

Add this to your Cargo.toml:

revm-trace = "0.1.0"

Quick Start

use revm_trace::{
  trace_tx_assets,
  TransactionTracer,
  create_evm_instance_with_inspector,
};
async fn example() -> anyhow::Result<()> {
  // Create EVM instance with transaction tracer
  let inspector = TransactionTracer::default();
  
  let mut evm = create_evm_instance_with_inspector(
    "https://rpc.ankr.com/eth", // Can be any EVM-compatible chain RPC
    inspector,
    None  // Use latest block
  )?;
  
  // 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
      );
    }
  }
  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;

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
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 0.1.1