Architecture and API

REVM is a flexible implementation of the Ethereum Virtual Machine (EVM). It follows the rules of the Ethereum mainnet and stays up to date with changes through hardforks as defined in the official Ethereum execution specs.

You can use REVM in two main ways:

  1. Run regular Ethereum transactions using an Execution API
  2. Create your own custom version of the EVM (for Layer 2 solutions or other chains) using the EVM framework

To see usage examples you can check the examples folder. Other than documentation, examples are the main resource to see and learn about Revm.

The main revm library combines all crates into one package and reexports them, standalone libraries are useful if there is a need to import functionality with smaller scope. You can see an overview of all revm crates in the crates folder.

REVM works in no_std environments which means it can be used in zero-knowledge virtual machines (zkVMs) and it is the standard library in that use case. It also has very few external dependencies.

Execution API

Evm the main structure for executing mainnet ethereum transaction is built with a Context and a builder, code for it looks like this:

let mut evm = Context::mainnet().with_block(block).build_mainnet();
let out = evm.transact(tx);

Evm struct contains:

And Context contains data used in execution:

  • Environment data, the data that is known before execution starts are Transaction, Block, Cfg.
  • Journal is the place where internal state is stored. Internal state is returned after execution ends.
    • And Database is an interface that allows fetching external data that is needed at runtime. That data are account, storage and bytecode. When loaded they are stored in Journal

REVM provides four ways to execute transactions through traits (API):

  • transact(tx) and replay() are function of ExecuteEvm trait that allow execution transactions. They return the status of execution with reason, changed state and in case of failed execution an error.
  • transact_commit(tx) and replay_commit() are part of ExecuteCommitEvm that internally commits the state diff to the database and returns status of execution. Database is required to support DatabaseCommit trait.
  • inspect(), inspect_replay(tx) and a few others are part of InspectEvm trait that allow execution with inspection. This is how tracers are called.
  • inspect_commit(),inspect_replay_commit(tx) are part of the InspectCommitEvm trait that extends InspectEvm to allow committing state diff after tracing.

For inspection API to be enabled, Evm needs to be created with inspector.

let mut evm = Context::mainnet().with_block(block).build_mainnet().with_inspector(inspector);
let _ = evm.inspect_tx(tx);

EVM Framework

To learn how to build your own custom EVM:

Each trait needed to build custom EVM has detailed documentation explaining how it works and is worth reading.

In summary, REVM is built around several key traits that enable customizable EVM functionality. The core traits include:

  • EvmTr: The core EVM trait that provides access to Context, Instruction, Precompiles:
  • ContextTr: Accessed through EvmTr, defines the execution environment including Tx/Block/Journal/Db.
  • Handler: Implements the core execution logic, taking an EvmTr implementation. The default implementation follows Ethereum consensus.

And traits that provide support for inspection and tracing: