# ethereumproject/cpp-ethereum architecture

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

- Interactive diagram: https://gitdiagram.com/ethereumproject/cpp-ethereum
- Repository: https://github.com/ethereumproject/cpp-ethereum

## Overview

##### Main Components
- Blockchain Node Core: This includes the Ethereum-specific parts – components for block creation, transaction processing, state management, consensus, and chain syncing. In the file tree you see directories like “eth”, “libethcore”, “libethereum”, and “libevmcore” that together implement the core blockchain logic, block validation, and state updates.
- Virtual Machine and Smart Contract Execution: Modules such as “ethvm”, “libevm”, and “evmjit” implement the Ethereum Virtual Machine. They are responsible for executing smart contract code and handling EVM bytecode.
- Cryptography and Utility Libraries: A solid part of the design comes from crypto operations. This includes “libdevcrypto”, “utils/secp256k1”, and other cryptographic helpers (for encryption, signing, hashing) found in “libdevcore” and related files.
- P2P Networking: The blockchain requires decentralized peer-to-peer communication. Directories like “libp2p” implement peer discovery, session management, and message passing.
- JSON-RPC and API Services: Communication with external clients (wallets, explorers, UI tools) is enabled in “libweb3jsonrpc” and parts of “libwebthree”. These modules expose an API interface (e.g., over IPC, HTTP, or sockets) for interacting with the node.
- Auxiliary Tools and Libraries: There are executables and support libraries such as “ethkey” (for key management), “ethminer” (for mining), benchmarking (“bench”), and testing support (“test”). These show that the project is designed for a multi-faceted operation.

##### Relationships and Data Flow
- Cryptographic libraries underpin both transaction signing and state hashing – these support the core modules and are called by nearly every component. Represent this as an underlying library that several modules depend on.
- Testing and benchmarking tools (under “test” and “bench”) interact with almost every layer to verify functionality and performance. You may show them as peripheral modules validating the system.

##### Architectural Patterns and Design Principles
- Modularity: The project is broken into multiple self-contained libraries (each with its own CMakeLists.txt and headers). Emphasize separation of concerns (e.g., crypto, networking, blockchain, EVM).
- Layered Architecture: The design can be visualized as multiple tiers – network layer, core blockchain state management, execution layer (EVM), and external interfacing through JSON-RPC.
- Dependency Injection and Abstraction: With components such as “libdevcore” and “libdevcrypto”, many modules are abstracted to allow reuse and testing.

##### Technology and Frameworks
- The build system is based on CMake (evident from many CMakeLists.txt files) which builds each library and executable.
- Cross-platform portability is supported by a variety of scripts and configuration files.
- Testing infrastructure and scripts indicate use of both unit tests and performance metrics.

##### Final Recommendation
- P2P layer sending data to Blockchain Core.
- Blockchain Core invoking the EVM for contract execution.
- JSON-RPC layer interfacing with external clients.
- Cryptographic libraries underlying several modules.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Node Modules
    subgraph "Core Node Modules"
        BC1["Blockchain Core (eth)"]:::core
        BC2["Blockchain Core (libethcore)"]:::core
        BC3["Blockchain Core (libethereum)"]:::core
    end

    %% Virtual Machine and Smart Contract Execution
    subgraph "Smart Contract Execution"
        VM1["Smart Contract VM (ethvm)"]:::vm
        VM2["Smart Contract VM (libevm)"]:::vm
        VM3["Smart Contract VM (libevmcore)"]:::vm
    end

    %% Cryptography and Utility Libraries
    subgraph "Cryptography & Utility"
        CR1["Cryptography (libdevcrypto)"]:::crypto
        CR2["Utility (libdevcore)"]:::crypto
        CR3["Secp256k1 (utils/secp256k1)"]:::crypto
    end

    %% P2P Networking
    subgraph "P2P Networking"
        P2P["P2P Network (libp2p)"]:::network
    end

    %% JSON-RPC and API Services
    subgraph "JSON-RPC API"
        RPC1["JSON-RPC API (libweb3jsonrpc)"]:::api
        RPC2["Web3 Interface (libwebthree)"]:::api
    end

    %% Auxiliary Tools and Libraries
    subgraph "Auxiliary Tools"
        AT1["Key Management (ethkey)"]:::aux
        AT2["Mining (ethminer)"]:::aux
        AT3["Benchmarking (bench)"]:::aux
        AT4["Testing (test)"]:::aux
    end

    %% Data Flow Relationships
    P2P -->|"block_tx_input"| BC1
    BC1 -->|"executes_contracts"| VM1
    RPC1 <-->|"api_calls"| BC1
    CR1 -->|"crypto_support"| BC1
    CR1 -->|"crypto_support"| VM1
    CR1 -->|"crypto_support"| RPC1
    AT3 -->|"performance_valid"| BC1
    AT4 -->|"run_tests"| BC1
    AT3 -->|"performance_valid"| VM1
    AT1 -->|"key_management"| RPC1

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef vm fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef crypto fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef network fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef api fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef aux fill:#D3D3D3,stroke:#000,stroke-width:2px,stroke-dasharray: 5,5;

    %% Click Events for Core Node Modules
    click BC1 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/eth"
    click BC2 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libethcore"
    click BC3 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libethereum"

    %% Click Events for Virtual Machine and Smart Contract Execution
    click VM1 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/ethvm"
    click VM2 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libevm"
    click VM3 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libevmcore"

    %% Click Events for Cryptography and Utility Libraries
    click CR1 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libdevcrypto"
    click CR2 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libdevcore"
    click CR3 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/utils/secp256k1"

    %% Click Event for P2P Networking
    click P2P "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libp2p"

    %% Click Events for JSON-RPC and API Services
    click RPC1 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libweb3jsonrpc"
    click RPC2 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/libwebthree"

    %% Click Events for Auxiliary Tools and Libraries
    click AT1 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/ethkey"
    click AT2 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/ethminer"
    click AT3 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/bench"
    click AT4 "https://github.com/ethereumproject/cpp-ethereum/tree/develop/test"
```
