# ronin-chain/ronin architecture

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

- Interactive diagram: https://gitdiagram.com/ronin-chain/ronin
- Repository: https://github.com/ronin-chain/ronin

## Overview

This project is a Go implementation of the Ronin execution layer (a fork of go‑ethereum) that implements the core blockchain client, EVM execution, networking and consensus mechanisms for the Ronin protocol. Its purpose is to run a full node on the Ronin network (using either full, archive, or light sync modes), while also providing utilities such as signing (clef), contract code generation (abigen), network discovery (devp2p/bootnode), and even standalone debugging tools (evm, rlpdump, puppeth).

##### Main Components
- CLI/Executable Layer: This includes the different commands found in the “cmd” directory such as “ronin” (the main node client), “clef” (the signing backend), “evm”, “abigen”, “bootnode”, “puppeth”, and more.
- Network & P2P Layer: Components in directories like “p2p”, “eth”, “discovery”, “enode” and “nat” represent the nodes’ discovery, peer-to-peer communication and message transport.
- Consensus Engine: The consensus-related code is found under “consensus” with various modules (e.g., “ethash”, “clique”, “consortium”) that implement the Delegated Proof of Stake (or other consensus mechanisms) for finalizing blocks.
- Core Blockchain & State Management: Components in “core” (blockchain, transaction pool, state, rawdb, trie, etc.) manage the chain’s data, state updates, and encoding/decoding (RLP) operations.
- EVM and Execution Environment: Directories like “core/vm”, “cmd/evm”, and “common/compiler” indicate the embedded Ethereum Virtual Machine and smart contract execution logic.
- Cryptography & Security: Code in “crypto”, “accounts”, as well as key management (keystore, wallet, and even bls implementations) show handling of keys, signatures, and other crypto primitives.
- RPC Interfaces: The project has multiple ways to interact with the node – via JSON‑RPC (HTTP, WebSocket, IPC) – detailed in “rpc” and the documentation in the README.
- Auxiliary Tools: Utilities to generate and manage configuration (e.g., dumpconfig, genesis initialization) and to support debugging and testing (the “tests” and “internal” directories).

##### Relationships and Data Flows
- User Interaction & CLI -> The entry point (ronin executable) receives user commands and configuration.
- Node Initialization -> The node sets up the blockchain core (importing genesis, managing state via rawdb, trie, state objects).
- Consensus and Transaction Processing -> Incoming transactions flow through the transaction pool, then go through state transition rules and are executed in the EVM.
- P2P Networking -> The node communicates with other nodes using the p2p/discovery and enode modules, exchanging blocks and state data.
- RPC & External APIs -> The node exposes APIs (JSON‑RPC via HTTP, WS, IPC) which route user and programmatic requests to the core and EVM subsystems.
- Cryptographic Operations -> Throughout the system, operations from account management, signature verification, and contract ABI operations are handled by the crypto and accounts modules.
- Developer Utilities -> Tools like abigen and evm are connected to the EVM and ABI libraries, aiding in contract code generation and bytecode debugging.

##### Architectural Patterns and Technology Choices
- Layered Architecture: Each layer—from the networking and consensus layers, to core blockchain and state management, to the EVM and external interfaces—is distinctly separated.
- Component/Modular Design: The project’s structure indicates a modular design where consensus mechanisms, chain storage, and P2P communication are isolated in separate packages.
- Use of JSON‑RPC as standardized API. Tools like RLP for serialization and Go’s concurrency patterns (goroutines, channels) are inherent in the design.
- The integration of external signing services (e.g., clef) shows a separation between the node’s execution engine and its key management/security requirements.

- Clear Labels: Mark each primary component – “CLI/Node (ronin)”, “RPC Interfaces”, “Consensus Engine”, “P2P Network”, “Blockchain State/Database”, “EVM/Smart Contract Execution”, “Accounts & Crypto Modules”, and “Developer Utilities” (abigen, clef, etc.).
- Annotations: Add notes that indicate architectural patterns (e.g., “Layered Architecture”, “Modularity”, “Separation of Concerns”) and specify critical technologies (JSON‑RPC, RLP, Go concurrency, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction Layer"
        CLI["Ronin CLI"]:::cli
        Clef["Clef"]:::cli
        EVMCLI["EVM CLI"]:::cli
        Abigen["Abigen"]:::cli
        Bootnode["Bootnode"]:::cli
        Puppeth["Puppeth"]:::cli
        RPC["RPC Interfaces"]:::rpc
    end

    %% Core Blockchain & State Management
    subgraph "Core Blockchain & State Management"
        BC["Blockchain"]:::core
        TxPool["TxPool"]:::core
        State["State"]:::core
        RawDB["RawDB"]:::core
    end

    %% EVM and Execution Environment
    subgraph "EVM/Execution Environment"
        EVMExec["EVM Execution"]:::evm
        Compiler["Compiler"]:::evm
    end

    %% Consensus Engine
    subgraph "Consensus Engine"
        Consensus["Consensus Engine"]:::consensus
        Ethash["Ethash"]:::consensus
        Clique["Clique"]:::consensus
        Consortium["Consortium"]:::consensus
    end

    %% Network & P2P Layer
    subgraph "Network & P2P Layer"
        P2PCore["P2P Core"]:::p2p
        Enode["Enode"]:::p2p
        NAT["NAT"]:::p2p
        Discovery["Discovery"]:::p2p
        Devp2p["Devp2p"]:::p2p
    end

    %% Cryptography & Security
    subgraph "Cryptography & Security"
        Crypto["Crypto"]:::crypto
        Accounts["Accounts"]:::crypto
    end

    %% Auxiliary Developer Utilities
    subgraph "Developer Utilities"
        RLPdump["RLPdump"]:::aux
    end

    %% Data Flows
    %% From User Interaction Layer to Core
    CLI -->|"init_node"| BC
    Clef -->|"provides_signing"| CLI
    Bootnode -->|"bootstrap_network"| RPC
    RPC -->|"submit_tx"| TxPool

    %% Core Blockchain flows
    BC -->|"enqueue_tx"| TxPool
    TxPool -->|"execute_tx"| EVMExec
    EVMExec -->|"state_update"| State
    EVMExec -->|"block_proposal"| Consensus
    Consensus -->|"finalize_block"| BC
    BC -->|"persist_block"| RawDB

    %% EVM and Compiler relation
    Compiler -->|"compile_contracts"| EVMExec

    %% Consensus details
    Consensus -->|"use"| Ethash
    Consensus -->|"use"| Clique
    Consensus -->|"use"| Consortium

    %% P2P Network interactions
    BC -->|"broadcast_block"| P2PCore
    P2PCore -->|"sync_block"| BC
    P2PCore --- Enode
    P2PCore --- NAT
    P2PCore --- Discovery
    P2PCore --- Devp2p

    %% Security associations (dotted connections indicate usage across layers)
    CLI ---|"crypto_ops"| Crypto
    EVMExec ---|"verify_sig"| Accounts
    Consensus ---|"consensus_crypto"| Crypto
    Consensus ---|"account_management"| Accounts

    %% Developer Utilities interactions
    RLPdump -->|"debug_tx"| EVMExec
    RLPdump -->|"config_dump"| CLI

    %% Click Events
    click CLI "https://github.com/ronin-chain/ronin/tree/main/cmd/ronin"
    click Clef "https://github.com/ronin-chain/ronin/tree/main/cmd/clef"
    click EVMCLI "https://github.com/ronin-chain/ronin/tree/main/cmd/evm"
    click Abigen "https://github.com/ronin-chain/ronin/tree/main/cmd/abigen"
    click Bootnode "https://github.com/ronin-chain/ronin/tree/main/cmd/bootnode"
    click Puppeth "https://github.com/ronin-chain/ronin/tree/main/cmd/puppeth"
    click RPC "https://github.com/ronin-chain/ronin/tree/main/rpc/"
    click BC "https://github.com/ronin-chain/ronin/blob/main/core/blockchain.go"
    click TxPool "https://github.com/ronin-chain/ronin/tree/main/core/txpool"
    click State "https://github.com/ronin-chain/ronin/tree/main/core/state"
    click RawDB "https://github.com/ronin-chain/ronin/tree/main/core/rawdb"
    click EVMExec "https://github.com/ronin-chain/ronin/tree/main/core/vm"
    click Compiler "https://github.com/ronin-chain/ronin/tree/main/common/compiler"
    click Ethash "https://github.com/ronin-chain/ronin/tree/main/consensus/ethash"
    click Clique "https://github.com/ronin-chain/ronin/tree/main/consensus/clique"
    click Consortium "https://github.com/ronin-chain/ronin/tree/main/consensus/consortium"
    click P2PCore "https://github.com/ronin-chain/ronin/tree/main/p2p/"
    click Enode "https://github.com/ronin-chain/ronin/tree/main/p2p/enode"
    click NAT "https://github.com/ronin-chain/ronin/tree/main/p2p/nat"
    click Discovery "https://github.com/ronin-chain/ronin/tree/main/p2p/discover"
    click Devp2p "https://github.com/ronin-chain/ronin/tree/main/cmd/devp2p"
    click Crypto "https://github.com/ronin-chain/ronin/tree/main/crypto/"
    click Accounts "https://github.com/ronin-chain/ronin/tree/main/accounts/"
    click RLPdump "https://github.com/ronin-chain/ronin/tree/main/cmd/rlpdump"

    %% Styles
    classDef cli fill:#ffccff,stroke:#660066,stroke-width:2px;
    classDef rpc fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef core fill:#cce6ff,stroke:#0066cc,stroke-width:2px;
    classDef evm fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef consensus fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef p2p fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef crypto fill:#ccffff,stroke:#006666,stroke-width:2px;
    classDef aux fill:#e6ffe6,stroke:#339933,stroke-width:2px;
```
