MCPcopy Index your code
hub / github.com/Galxe/grevm

github.com/Galxe/grevm @v2.2.6

Chat with this repo
repository ↗ · DeepWiki ↗ · release v2.2.6 ↗ · + Follow
332 symbols 852 edges 29 files 88 documented · 27%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

Grevm

Grevm (both 1.0 and 2.1) is reth-ready, please see use-with-reth.md for more details.

Grevm is a Block-STM inspired optimistic parallel EVM execution engine that leverages DAG-based task scheduling, dynamic dependency management, and parallel state storage to significantly boost throughput of revm, while reducing CPU overhead in high-conflict scenarios.

Design Diagram

TL;DR – Highlights of Grevm 2.1

  • Grevm 2.1 achieves near-optimal performance in low-contention scenarios, matching Block-STM with 11.25 gigagas/s for Uniswap workloads and outperforming it with 95% less CPU usage in inherently non-parallelizable cases by 20–30%, achieving performance close to sequential execution.
  • Breaks Grevm 1.0’s limitations in handling highly dependent transactions, delivering a 5.5× throughput increase to 2.96 gigagas/s in 30%-hot-ratio hybrid workloads by minimizing re-executions through DAG-based scheduling and Task Groups.
  • Introduces Parallel State Store, leveraging asynchronous execution result bundling to overlap and amortize 30-60ms of post-execution overhead within parallel execution, effectively hiding these costs within execution time. It also seamlessly handles miner rewards and the self-destruct opcode without the performance penalties of sequential fallbacks.
  • In-depth analysis of optimistic parallel execution reveals the underestimated efficiency of Block-STM and the strength of optimistic parallelism, providing new insights into parallel execution.
  • Lock-Free DAG (introduced in 2.1) replaces global locking with fine-grained, node-level synchronization. This change reduces DAG scheduling overhead by 60% and improves overall performance by more than 30%. In workloads with fast-executing transactions—such as raw and ERC20 transfers—it delivers nearly higher throughput.

Architecture Overview

Grevm 2.1 is composed of three main modules:

  • Dependency Manager (DAG Manager):
    Constructs a directed acyclic graph (DAG) of transaction dependencies based on speculative read/write hints.

  • Execution Scheduler:
    Selects transactions with no dependencies (out-degree of 0) for parallel execution, groups adjacent dependent transactions into task groups, and dynamically updates dependencies to minimize re-execution.

  • Parallel State Storage:
    Provides an asynchronous commit mechanism with multi-version memory to reduce latency and manage miner rewards and self-destruct opcodes efficiently.

Testing

All tests and benchmarks require the test-utils feature:

cargo test --features test-utils

This runs the library unit tests plus the integration suites (erc20, native_transfers, uniswap, eip-7702, and the mainnet replay test). See Testing & Benchmarking for the full guide, including how to replay real mainnet blocks (EIP-7702 included) and the available environment-variable knobs.

Running the Benchmark

To reproduce the synthetic gigagas benchmark:

JEMALLOC_SYS_WITH_MALLOC_CONF="thp:always,metadata_thp:always" \
NUM_EOA=<num_accounts> HOT_RATIO=<hot_ratio> DB_LATENCY_US=<latency_in_us> \
cargo bench --features test-utils --bench gigagas

Replace <num_accounts>, <hot_ratio>, and <latency_in_us> with your desired parameters. There is also a continuous benchmark that runs merged real-mainnet "big blocks"; see Testing & Benchmarking.

Further Details

For a comprehensive explanation of the design, algorithmic choices, and in-depth benchmark analysis, please refer to the full technical report.

Extension points exported contracts — how you extend this code

ParallelBundleState (Interface)
A trait that provides functionality for applying state transitions in parallel and creating reverts for a `BundleState`. [1 …
src/storage.rs
ParallelTakeBundle (Interface)
Provides functionality for extracting a `BundleState` from a `ParallelState` while applying state transitions in paralle [1 …
src/storage.rs

Core symbols most depended-on inside this repo

mock_eoa_address
called by 44
src/test_utils/common/account.rs
set
called by 37
src/test_utils/common/storage.rs
mock_block_accounts
called by 20
src/test_utils/common/account.rs
authority_a
called by 18
tests/eip-7702.rs
compare_evm_execute
called by 15
src/test_utils/common/execute.rs
from_address
called by 15
src/test_utils/common/storage.rs
req_str
called by 14
src/test_utils/common/mainnet.rs
bench
called by 13
benches/gigagas.rs

Shape

Method 163
Function 114
Class 41
Enum 12
Interface 2

Languages

Rust100%

Modules by API surface

src/parallel_state.rs49 symbols
src/test_utils/common/mainnet.rs36 symbols
src/scheduler.rs29 symbols
src/storage.rs20 symbols
tests/eip-7702.rs18 symbols
src/test_utils/common/storage.rs17 symbols
src/test_utils/uniswap/contract.rs16 symbols
src/async_commit.rs16 symbols
benches/gigagas.rs16 symbols
src/lib.rs15 symbols
src/hint.rs15 symbols
src/bin/rpc.rs13 symbols

For agents

$ claude mcp add grevm \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact