# risechain/pevm architecture

> Architecture diagram of the GitHub repository risechain/pevm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/risechain/pevm
- Repository: https://github.com/risechain/pevm

## Overview

##### Project Type and Purpose
- This is a Rust-based blockchain execution engine focused on parallelizing EVM (Ethereum Virtual Machine) block execution.
- Its purpose is to leverage parallel execution (through techniques like Block-STM, a collaborative scheduler, and multi-version data structures) to improve throughput and enable new dApp designs.
- The design aims to deliver deterministic yet highly concurrent transaction execution with special handling for gas payment and transfers.

##### Analyzing the File Structure
- The project is organized as a Cargo workspace with distinct sections:
- The “crates” directory holds the core logic under the “pevm” crate. This includes modules for chain handling (for Ethereum and Optimism), memory management (mv_memory), scheduling, storage implementations (in_memory and rpc), and the main VM logic.
- The “bins” directory contains at least one CLI tool (“fetch”) for grabbing real block data, which feeds into the testing and benchmarking workflows.
- The “data” directory stores block and pre-state JSON files used for validations, tests, and benchmarking.
- There are directories for benchmarks (“benches”) and extensive tests (including unit tests and integration tests for multiple scenarios such as raw transfers, ERC-20, and uniswap contracts).
- Configuration files (like Cargo.toml, GitHub workflows, and cmake dependency notes for snmalloc) hint at performance and deployment considerations.

##### Insights from the README
- The README outlines both the problem and solution areas. It explains that RISE pevm is purposely built to optimize EVM execution through parallelism, using techniques like:
- Lazy updates for beneficiary and transfer scenarios.
- A collaborative scheduler that aggressively finds tasks to minimize overhead.
- Multi-version concurrency control for maintaining deterministic state execution.
- The README also highlights testing groups (Ethereum state tests, mocked block tests, and mainnet block tests) and a dedicated CLI tool for fetching blocks.

a. Main Components to Include:
- Core Execution Engine ("pevm" Crate):
- VM Module
- Scheduler module (collaborative scheduling)
- Chain handlers (modules: ethereum.rs, optimism.rs under chain)
- Lazy Update Mechanisms (for beneficiary and token transfers)
- Multi-version storage system (with in_memory and rpc submodules)
- Memory management module (mv_memory)
- CLI and Fetch Module:
- bins/fetch as the command-line tool to fetch real block data from various networks.
- Testing, Benchmarks, and Data:
- Benchmarking modules (in benches)
- Test suites for ethereum, raw transfers, ERC-20, uniswap, etc.
- Data ingestion from the “data” directory containing block & pre_state JSON files.
- External Dependencies and Integrations:
- Integration with Ethereum mainnet and potential integration with Ethereum clients like Reth.
- Use of external libraries (e.g., snmalloc for memory allocation, cmake for builds).

b. Relationships and Interactions:
- The core execution engine processes EVM block transactions in parallel using its scheduler and the multi-version memory storage.
- Lazy update mechanisms allow safe parallel modifications (representing dependencies like beneficiary updates) while ensuring output consistency.
- The CLI tool interacts with external Ethereum nodes via RPC to fetch blocks, then deposits data to the “data” directory for subsequent execution by the engine.
- Testing modules feed various scenarios into the core engine to validate correctness and performance, indicating tight integration between unit/integration tests and the engine’s key modules.

c. Architectural Patterns and Design Principles:
- Separation of concerns:
– The execution logic (VM, scheduler, storage) is decoupled from I/O and block fetching.
– Modular design with separate components for chain-specific handling.
- Use of optimistic concurrency via multi-version data structures and the lazy update techniques.
- Acknowledge the importance of determinism in blockchain execution, underlining error handling and conflict resolution.

d. Relevant Technologies, Frameworks, or Libraries:
- Programming Language: Rust.
- Build and Package Management: Cargo.
- Memory Allocation: snmalloc (via cmake).
- Testing and Benchmarking frameworks integrated with Cargo.
- GitHub workflows for continuous integration that might affect build/deployment aspects.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External Layer"
        CLI["Fetch (CLI)"]:::external
        ETHNode["Ethereum RPC Node"]:::external
        DataIngest["Data Ingestion (data)"]:::external
    end

    %% Core Execution Engine
    subgraph "Core Execution Engine"
        Engine["Parallel Execution Engine (pevm)"]:::core
        subgraph "Core Modules"
            VM["VM Module"]:::core
            Scheduler["Scheduler Module (Collaborative)"]:::core
            subgraph "Chain Handlers"
                EthHandler["Ethereum Handler"]:::core
                OptHandler["Optimism Handler"]:::core
            end
            Memory["Multi-Version Memory Storage"]:::core
            subgraph "Storage Implementations"
                InMemory["In-Memory Storage"]:::storage
                RPCStore["RPC-based Storage"]:::storage
            end
            LazyUpdate["Lazy Update Mechanisms"]:::core
        end
    end

    %% Testing and Benchmarking
    subgraph "Testing & Benchmarking"
        Benchmark["Benchmarking Modules"]:::test
        TestSuites["Testing Suites"]:::test
    end

    %% Data Flow Connections
    CLI -->|"fetches_data"| DataIngest
    ETHNode -->|"provides_block_data"| CLI
    DataIngest -->|"feeds_blocks_to"| Scheduler
    Scheduler -->|"dispatches_tasks_to"| VM
    Scheduler -->|"calls_chain_logic_on"| EthHandler
    Scheduler -->|"calls_chain_logic_on"| OptHandler
    VM -->|"executes_transactions_with"| Memory
    Memory -->|"persists_state_in"| InMemory
    Memory -->|"persists_state_in"| RPCStore
    VM -->|"triggers_lazy_updates"| LazyUpdate

    %% Aggregation within Core Engine
    Engine -->|"aggregates"| VM
    Engine -->|"aggregates"| Scheduler
    Engine -->|"aggregates"| EthHandler
    Engine -->|"aggregates"| OptHandler
    Engine -->|"aggregates"| Memory
    Engine -->|"aggregates"| InMemory
    Engine -->|"aggregates"| RPCStore
    Engine -->|"aggregates"| LazyUpdate

    %% Testing Connections
    TestSuites -.->|"validates"| Engine
    Benchmark -.->|"benchmarks"| Engine

    %% Click Events
    click Engine "https://github.com/risechain/pevm/tree/main/crates/pevm"
    click VM "https://github.com/risechain/pevm/blob/main/crates/pevm/src/vm.rs"
    click Scheduler "https://github.com/risechain/pevm/blob/main/crates/pevm/src/scheduler.rs"
    click EthHandler "https://github.com/risechain/pevm/blob/main/crates/pevm/src/chain/ethereum.rs"
    click OptHandler "https://github.com/risechain/pevm/blob/main/crates/pevm/src/chain/optimism.rs"
    click Memory "https://github.com/risechain/pevm/blob/main/crates/pevm/src/mv_memory.rs"
    click InMemory "https://github.com/risechain/pevm/blob/main/crates/pevm/src/storage/in_memory.rs"
    click RPCStore "https://github.com/risechain/pevm/blob/main/crates/pevm/src/storage/rpc.rs"
    click LazyUpdate "https://github.com/risechain/pevm/blob/main/crates/pevm/tests/beneficiary.rs"
    click CLI "https://github.com/risechain/pevm/tree/main/bins/fetch"
    click Benchmark "https://github.com/risechain/pevm/tree/main/crates/pevm/benches"
    click TestSuites "https://github.com/risechain/pevm/tree/main/crates/pevm/tests"
    click DataIngest "https://github.com/risechain/pevm/tree/main/data"

    %% Styles
    classDef core fill:#e6f7ff,stroke:#007acc,stroke-width:2px;
    classDef external fill:#fff2e6,stroke:#ffaa00,stroke-width:2px;
    classDef storage fill:#e6ffe6,stroke:#28a745,stroke-width:2px;
    classDef test fill:#ffe6f7,stroke:#ff66cc,stroke-width:2px;
```
