Revm

CI License revm Chat

Revm is a highly efficient and stable implementation of the Ethereum Virtual Machine (EVM) written in Rust.

banner

Known for its robustness, it stands as one of the most popular libraries and critical component of the Ethereum ecosystem. Revm plays a crucial role across various projects, being widely utilized by almost all tooling and block builders. It is integrated into Reth, multiple Layer 2 variants and other clients and serving as a standard for zkVMs.

Revm offers two primary applications: firstly, it functions as an executor where users can set up block info and process mainnet transactions; secondly, it acts as a framework that facilitates the extension and support of different EVM variants such as op-revm.

How to use:

Here is a straightforward example of using the Execution API: It allows us to create an Ethereum Virtual Machine (EVM) and execute transactions. Additionally, it can be utilized to generate traces with the inspector or more complex example of foundry cheatcodes.

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

// or you can use powerful inspection tool to trace it
let mut evm = evm.with_inspector(tracer);
let out = evm.inspect_with_tx(tx);

The Evm Framework API is somewhat complex to use, but this document provides a detailed explanation. It enables users to extend logic, incorporate various context types, and offers built-in support for inspection. For a practical example, you can refer to the op-revm crate.

Users:

As previously noted, there are several groups of projects that utilize this technology:

The full list of projects that use Revm is available in the awesome-revm section of the book.

How to, dev section

The book and Architecture and API page is the best starting resource.

Some quicklinks can be found here. Some point to code documentation or book. code docs are there to explain usage of particular part of the code where book is to get more of the overview on architecture or how components/projects fit toggether.

  • How to build and use revm can be found here. (code)
  • Architecture overview can be seen here. book
  • Structure of the project (list of crates and their versions) can be seen here. book
  • How to use Revm Framework can be foud in MyEvm example. book
  • Release procedure and changelogs explanation. book
  • How to use revme (Revm binary with few commands) can be found here. code
  • How to run Ethereum test can be found here: book
  • If there is more explanations please open PR request for it.

Community:

For questions please open an github issue or join public telegram group: https://t.me/+Ig4WDWOzikA3MzA0

Licence

Revm is licensed under MIT Licence.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, shall be licensed as above, without any additional terms or conditions.

Security

For any security questions or findings, please reach out to me directly via email at dragan0rakita@gmail.com or contact me on Keybase under the username @draganrakita.

Awesome Revm

A curated list of excellent Revm-related resources. Feel free to contribute to this list!

Repositories

Audits

API Extensions:

  • alloy-evm is an abstraction layer on top of revm providing common implementations of EVMs
  • Trevm is a typestate API wrapper for revm

Clients

  • Reth: A modular, contributor-friendly, and ultra-fast implementation of the Ethereum protocol.
  • Helios is a trustless, efficient, and portable multichain light client written in Rust.
  • Trin is a Rust implementation of a Portal Network client.

EVM Variants

  • Optimism is a ethereum L2 network.
  • Base is an Ethereum Layer 2 (L2) chain that offers a safe, low-cost, developer-friendly way to build on-chain
  • Scroll is its own Layer 2 network built on Ethereum (more specifically, a “zero-knowledge rollup”).

Tools

  • Foundry: A portable and modular toolkit for rapid Ethereum application development in Rust.
  • Hardhat: A comprehensive development environment for compiling, deploying, testing, and debugging Ethereum software.
  • Arbiter: smart-contract simulation.

Frameworks and Libraries

  • revm-inspectors: Hooks for EVM execution.
  • eip3074-instructions: Implements custom instructions for AUTH and AUTHCALL operations.
  • Revmc: JIT and AOT compiler for the Ethereum Virtual Machine, leveraging Revm.
  • Risc0-ethereum is a zero-knowledge verifiable general computing platform, with Ethereum integration
  • Kona is a suite of portable implementations of the OP Stack rollup state transition, namely the derivation pipeline and the block execution logic.
  • mevlog-rs: Rust-based CLI tool for querying and monitoring Ethereum blockchain transactions, with flexible filtering and EVM tracing capabilities. It's a tool for MEV searchers who prefer command-line workflows over web-based explorers.

Tutorials

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 a Execution API
  2. Create your own custom version of the EVM (for Layer 2 solutions or other chains) using EVM framework

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

The main revm library combines all crates into one package and reexports them, standalone library are useful if there is need to import functionality with smaller scope. You can see overview of revm crates in 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 place where internal state is stored. Internal state is returned after execution ends.
    • And Database is a interface that allows fetching external data that is needed in 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_with_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:

Building from source

It requires running

git clone https://github.com/bluealloy/revm.git
cd revm
cargo build --release

Note: This project tends to use the newest rust version, so if you're encountering a build error try running rustup update first.

Note: clang is required for building revm with c-kzg or secp256k1 feature flags as they depend on C libraries. If you don't have it installed, you can install it with apt install clang.

Revm

Is a binary that allows running statetest and eof validation.

$: revme --help
Usage: revme <COMMAND>

Commands:
  statetest       Execute Ethereum state tests
  eof-validation  Execute EOF validation tests
  evm             Run arbitrary EVM bytecode
  bytecode        Print the structure of an EVM bytecode
  bench           Run bench from specified list
  help            Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Running eth tests

Eth tests are suite of tests from Ethereum Fondation that are used to test EVM implementations. Part of these tests are included in revm repository in tests folder.

Download eth tests git clone https://github.com/ethereum/tests. They can be run with revme with command: cargo run --release -p revme -- statetest tests/GeneralStateTests/ tests/LegacyTests/Constantinople/GeneralStateTests All statetest that can be run by revme can be found in GeneralStateTests folder.

Release procedure

This document describes the procedure for releasing a new version of the revm project. The repository is hosted on github and the published to the crates. Every published crate is part of one tag (currently tag v55) that contains all crates versions. The versions depending on the change can be major, minor or patch, we dont have one version for all packages.

Link of tag to the particular version of the crate can be found in CHANGELOG file.

Contact

Git repo can be found https://github.com/bluealloy/revm/

For questions please open github issue or join public telegram group: https://t.me/+Ig4WDWOzikA3MzA0

Licence

Licensed under MIT Licence.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, shall be licensed as above, without any additional terms or conditions.

Security

If there is security question/findings please contact me directly on email atdragan0rakita@gmail.com or on keybase @draganrakita