revm Documentation

The revm project is modularized into several specialized crates. Depending on your needs, you can use the main revm crate which re-exports all other crates, or select specific components to minimize dependencies:

• Core Execution: revm (main entry point), revm-interpreter (contains all instructions), and revm-handler (manages validation, pre/post execution, and call frames).
• State & Data: revm-database-interface (traits for fetching state), revm-database (implementations of the database interface), revm-state (account and storage types), and revm-primitives (constants and primitive types).
• Ethereum Compatibility: revm-precompile (Ethereum-defined precompiled contracts) and revm-bytecode (opcode tables, legacy analysis, and EOF validation).
• Context & Tracing: revm-context-interface (traits for Block/Transaction/Cfg/Journal), revm-context (default implementations for those traits), and revm-inspector (supports inspectors and EIP-3155 tracer).
• Testing: revm-statetest-types (structs for state testing).

The Revm ecosystem includes various extensions, clients, tools, and tutorials for developers working with the Ethereum Virtual Machine in Rust. Use these resources to extend Revm functionality, integrate it into clients, or learn through practical examples.

API Extensions

• alloy-evm: An abstraction layer on top of revm providing common implementations of EVMs.
• Trevm: A typestate API wrapper for revm.

Clients and Tools

• Reth: A modular, ultra-fast implementation of the Ethereum protocol.
• Helios: A trustless, efficient, and portable multichain light client.
• Foundry: A portable and modular toolkit for rapid Ethereum application development.
• Hardhat: A comprehensive development environment for compiling, deploying, testing, and debugging.
• OpTrace: A high-performance, GUI-based EVM debugger for deep-dive trace analysis.

Frameworks and Libraries

• revm-inspectors: Hooks for EVM execution.
• Revmc: JIT and AOT compiler for the EVM, leveraging Revm.
• mevlog-rs: A Rust-based CLI tool for querying and monitoring Ethereum transactions with EVM tracing capabilities.

Learning and Tutorials

• MyEvm: Example of a custom EVM implementation.
• Uniswap Swap Example: Demonstrates a USDC swap on Uniswap V2.
• revm-by-example: Practical examples using the Rust EVM.
• Revm is All You Need: A guide on building simulated blockchain environments.

The Inspector trait is REVM's mechanism for observing and tracing EVM execution. It provides hooks into every aspect of a transaction's lifecycle, allowing you to monitor state changes, trace calls, capture events, and even override execution behavior.

It is primarily used for building debuggers, gas analyzers, security tools, and custom execution tracers. Because the trait provides default empty implementations, there is minimal overhead if you only implement the specific hooks you need.

pub trait Inspector<CTX, INTR: InterpreterTypes> {
    // Opcode-level tracing
    fn step(&mut self, interp: &mut Interpreter<INTR>, context: &mut CTX) {}
    fn step_end(&mut self, interp: &mut Interpreter<INTR>, context: &mut CTX) {}
    
    // Call and creation tracing  
    fn call(&mut self, context: &mut CTX, inputs: &mut CallInputs) -> Option<CallOutcome> { None }
    fn call_end(&mut self, context: &mut CTX, inputs: &CallInputs, outcome: &mut CallOutcome) {}
    fn create(&mut self, context: &mut CTX, inputs: &mut CreateInputs) -> Option<CreateOutcome> { None }
    fn create_end(&mut self, context: &mut CTX, inputs: &CreateInputs, outcome: &mut CreateOutcome) {}
    
    // Event tracing
    fn log(&mut self, context: &mut CTX, log: Log) {}
    fn log_full(&mut self, interp: &mut Interpreter<INTR>, context: &mut CTX, log: Log) {
        self.log(context, log)
    }
    fn selfdestruct(&mut self, contract: Address, target: Address, value: U256) {}
}

SSTORE

• New Slot: Writing from zero to non-zero on a fresh slot charges sstore_set_state_gas.
• Overwrite: Overwriting an existing non-zero slot does not charge additional state gas.
• Zero to Zero: Writing zero to an already-zero slot charges no state gas.

CREATE / CREATE2

• Empty Code: Deploying 0-byte code charges create_state_gas.
• With Code: Deploying code charges create_state_gas + (code_deposit_state_gas * number of bytes).
• With SSTORE: If init code performs an SSTORE to a new slot, it charges create_state_gas + sstore_set_state_gas + code_deposit_state_gas.

CALL

• New Account: A CALL with value to a non-existent account charges new_account_state_gas.
• Existing Account: A CALL to an existing account charges no state gas.
• No Value: A CALL to a non-existent account without a value transfer charges no state gas.