# ava-labs/subnet-evm architecture

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

- Interactive diagram: https://gitdiagram.com/ava-labs/subnet-evm
- Repository: https://github.com/ava-labs/subnet-evm

## Overview

This project is the Subnet EVM – a standalone Ethereum Virtual Machine implementation designed to run as a subnet within the Avalanche network. It is a simplified and adapted version of Coreth (the C-Chain) that implements a VM for Ethereum smart contracts, with custom modifications (such as configurable fees, merged hardfork behavior, and altered block formats) to operate within the Avalanche ecosystem. The Subnet EVM runs in a separate process and communicates with AvalancheGo via gRPC.

##### Main Components
- EVM Core Engine – Located in the “core” and “vm” directories, this represents the heart of the virtual machine with modules for block validation, state processing, trie management, transaction processing, and EVM instructions execution.
- APIs and RPC Layer – The “eth”, “rpc”, “internal/ethapi”, and “ethclient” directories implement several API namespaces (eth, personal, txpool, debug) and RPC servers that expose blockchain operations.
- Accounts and Keystore Management – The “accounts” directory contains code for account manipulation, key storage (both secure and plain formats), and helper functions for signing transactions.
- Consensus and Network Communication – Look at the “consensus”, “peer”, “sync”, and “node” directories. These components handle block propagation, peer connection, state synchronization, and chain management.
- Plugins and Precompiles – The “plugin” and “precompile” directories show how the system extends EVM functionality with additional precompile contracts and upgradeable functionality.
- Auxiliary Components – “metrics”, “trie”, “triedb”, “utils”, and “scripts” support logging, metrics collection, testing, building, and other operational features.
- Command Line Tools – The “cmd” directory includes various CLI tools (abigen, evm, simulator, etc.) that support testing, deployment, debugging, and simulation of the network.

##### Relationships and Data Flow
- That the Accounts subsystem supplies credentials and key management to the Core engine, facilitating transaction signing and verification.
- Consensus and Peer/Networking layers with the Core, noting that block production/validation and state synchronization occur across these modules.
- A communication channel (using gRPC) between the Subnet EVM process and AvalancheGo, highlighting how the Subnet EVM receives block data, configuration changes, or commands.
- Plugins and Precompiles as pluggable modules attached to the VM, indicating that they provide additional functionalities like custom precompiled contracts.

##### Architectural Patterns and Technologies
- That this is a modular, layered architecture typically seen in blockchain clients.
- That the system separates concerns by isolating state management, execution (EVM), API exposure, and networking.
- Mention the use of Go as the primary language and many conventions from the Ethereum ecosystem (e.g., RLP encoding, Keystore file formats).
- That many of the directories follow an MVC-like separation where the “core” and “vm” are the Model/execution logic, “eth”, “rpc”, and “api” form the Controller/API, and the “cmd” and “cli” tools act as clients or views.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Interfaces"
        Eth["APIs: eth"]:::external
        RPC["APIs: rpc"]:::external
        EthAPI["APIs: internal/ethapi"]:::external
        EthClient["APIs: ethclient"]:::external
        CMD["Command Line Tools"]:::external
        AvalGo["AvalancheGo (gRPC)"]:::external
    end

    %% Execution Core
    subgraph "Execution Core"
        Core["EVM Core Engine (Core)"]:::execution
        VM["EVM Core Engine (VM)"]:::execution
        Accounts["Accounts & Keystore Management"]:::execution
    end

    %% Networking & Consensus
    subgraph "Networking & Consensus"
        Consensus["Consensus"]:::networking
        Peer["Peer"]:::networking
        Sync["Sync"]:::networking
        Node["Node"]:::networking
    end

    %% Extensions
    subgraph "Extensions"
        Plugin["Plugin"]:::plugin
        Precompile["Precompile"]:::plugin
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        Metrics["Metrics"]:::aux
        Trie["Trie"]:::aux
        Triedb["Triedb"]:::aux
        Utils["Utils"]:::aux
        Scripts["Scripts"]:::aux
    end

    %% Relationships - External Interfaces to Execution Core
    Eth -->|"calls"| Core
    RPC -->|"calls"| Core
    EthAPI -->|"calls"| Core
    EthClient -->|"calls"| Core
    CMD -->|"calls"| Core
    AvalGo -- "gRPC" --> Core

    %% Relationship - Accounts to Execution Core
    Accounts -->|"supplies"| Core

    %% Relationships - Networking & Consensus to Execution Core
    Consensus -->|"syncs"| Core
    Peer -->|"connects"| Core
    Sync -->|"updates"| Core
    Node -->|"manages"| Core

    %% Relationships - Extensions to Execution Core
    Plugin -->|"extends"| Core
    Precompile -->|"extends"| Core

    %% Relationships - Auxiliary Components supporting Execution Core
    Metrics ---|"logs"| Core
    Trie ---|"state"| Core
    Triedb ---|"data"| Core
    Utils ---|"helpers"| Core
    Scripts ---|"ops"| Core

    %% Internal integration within Execution Core
    VM -->|"integrates"| Core

    %% Click Events
    click Eth "https://github.com/ava-labs/subnet-evm/tree/master/eth"
    click RPC "https://github.com/ava-labs/subnet-evm/tree/master/rpc"
    click EthAPI "https://github.com/ava-labs/subnet-evm/tree/master/internal/ethapi"
    click EthClient "https://github.com/ava-labs/subnet-evm/tree/master/ethclient"
    click CMD "https://github.com/ava-labs/subnet-evm/tree/master/cmd"
    click Core "https://github.com/ava-labs/subnet-evm/tree/master/core"
    click VM "https://github.com/ava-labs/subnet-evm/tree/master/core/vm"
    click Accounts "https://github.com/ava-labs/subnet-evm/tree/master/accounts"
    click Consensus "https://github.com/ava-labs/subnet-evm/tree/master/consensus"
    click Peer "https://github.com/ava-labs/subnet-evm/tree/master/peer"
    click Sync "https://github.com/ava-labs/subnet-evm/tree/master/sync"
    click Node "https://github.com/ava-labs/subnet-evm/tree/master/node"
    click Plugin "https://github.com/ava-labs/subnet-evm/tree/master/plugin"
    click Precompile "https://github.com/ava-labs/subnet-evm/tree/master/precompile"
    click Metrics "https://github.com/ava-labs/subnet-evm/tree/master/metrics"
    click Trie "https://github.com/ava-labs/subnet-evm/tree/master/trie"
    click Triedb "https://github.com/ava-labs/subnet-evm/tree/master/triedb"
    click Utils "https://github.com/ava-labs/subnet-evm/tree/master/utils"
    click Scripts "https://github.com/ava-labs/subnet-evm/tree/master/scripts"

    %% Styles
    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef execution fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef networking fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef plugin fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef aux fill:#D5F5E3,stroke:#117864,stroke-width:2px;
```
