# moonbeam-foundation/moonbeam architecture

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

- Interactive diagram: https://gitdiagram.com/moonbeam-foundation/moonbeam
- Repository: https://github.com/moonbeam-foundation/moonbeam

## Overview

##### Project type and purpose
- This repository is the Moonbeam parachain node: a blockchain node (Rust/FRAME) that is Ethereum-compatible and runs as a Polkadot parachain.
- It provides a Substrate-based node binary, a WASM runtime composed of FRAME pallets (Polkadot-SDK, Frontier, plus Moonbeam-specific pallets), EVM integration, RPC endpoints (Ethereum JSON-RPC and Substrate RPC), developer tooling, TypeScript-based API clients, and end-to-end test suites.

##### Top-level architecture overview
┌─────────────────────────────┐
│ 1) Client/API & CLI Tools  │
├─────────────────────────────┤
│ 2) Node Binary & Service    │
├─────────────────────────────┤
│ 3) Runtime (WASM + Pallets) │
├─────────────────────────────┤
│ 4) External Integrations    │
└─────────────────────────────┘

##### Main components and relationships
a. Client / API Layer
– TypeScript-API (typescript-api/, types-bundle/)
- Generates strong-typed JSON-RPC clients from on-chain metadata.
– Tools and CLI (cli-opt/, node/cli/, scripts/, tools/)
- Helpers for spec generation, block tracking, testing, release bots.
– Integration Tests (test/)
- Moonwall harness driving the node via JSON-RPC to exercise EVM, precompiles, XCM, staking, etc.

b. Node Binary & Service
– node/cli/ + node/service/
- Parses CLI flags (chain, dev, sealing), sets up networking, consensus (Cumulus), RPC servers (HTTP, WS, Ethereum JSON-RPC).
- Embeds the compiled WASM runtime and native runtime for block execution.
– client/
- client/rpc-core, client/rpc (trace, dev, finality, debug), client/evm-tracing, client/vrf
- Implements official JSON-RPC methods, tracing subsystems, VRF randomness providers.

c. Runtime (FRAME + Pallets + Precompiles)
– runtime/common, runtime/moonbeam, runtime/moonbase, runtime/moonriver, runtime/evm_tracer, runtime/relay-encoder, …
- FRAME runtime crates split by target network, each defining the same set of pallets with network-specific params (ChainId, origins, weights).
– Polkadot-SDK Pallets (Utility, Balances, Sudo, Timestamp, ParachainInfo, ParachainUpgrade, RandomnessCollectiveFlip)
– Frontier pallets (Ethereum, EVM, EVMChainId)
– Moonbeam-specific pallets (in pallets/): AssetManager, ParachainStaking, XCM-bridge, EVM precompiles in precompiles/
– Precompiles (assets-erc20, balances-erc20, proxy, …) for EVM compatibility

d. External Integrations
– Polkadot Relay Chain (Cumulus): parachain block submission & finality
– Ethereum tooling and wallets via JSON-RPC
– Docker registry for published node images
– GitHub Actions / CI for build, tests, benchmarks

##### Architectural Patterns & Design Principles
- Modular Rust workspace: each logical component (runtime, node, clients, tools) lives in its own crate.
- Clear separation of concerns:
– Runtime handles state transition logic (WASM VM + pallets).
– Node binary handles networking, consensus, RPC interfaces.
– Clients and tools consume the node’s JSON-RPC surface.
- FRAME / pallet-based extensibility: easy to add or replace pallets.
- Cumulus for parachain integration.
- Frontier for EVM compatibility.
- TypeScript code generation from on-chain metadata for strong typing.
- CI/CD via GitHub Actions and Docker for releases.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client/API & CLI Tools Layer
    subgraph "Client/API & CLI Tools"
        direction TB
        TSAPI["TypeScript API Clients"]:::js
        TSBundle["Type Definitions Bundle"]:::js
        CLISpec["CLI Tools - Spec Generation"]:::js
        CLIParser["CLI Tools - Node CLI Parser"]:::rust
        DevTools["Developer Tooling & Bots"]:::js
        TestHarness["Integration Test Harness (Moonwall)"]:::js
    end

    %% Node Binary & Service Layer
    subgraph "Node Binary & Service"
        direction TB
        NodeMain["Node Binary Entry Point"]:::rust
        NodeService["Node Service (Networking, Consensus, RPC)"]:::rust
        RPCCore["JSON-RPC Core & Methods"]:::rust
        RPCImpl["JSON-RPC Implementations"]:::rust
        EVMTrace["EVM Tracing Subsystem"]:::rust
        VRF["VRF Randomness Provider"]:::rust
    end

    %% Runtime Layer
    subgraph "Runtime (WASM + Pallets)"
        direction TB
        RuntimeCommon["FRAME Runtime Common Logic"]:::rust
        EVMTracerRT["WASM EVM Tracer Runtime"]:::rust
        MoonbeamRT["Moonbeam Runtime (native & WASM)"]:::rust
        MoonbaseRT["Moonbase Runtime (native & WASM)"]:::rust
        MoonriverRT["Moonriver Runtime (native & WASM)"]:::rust
        RelayEnc["Relay-Encoder Runtime Crate"]:::rust
        Pallets["Moonbeam-Specific Pallets"]:::rust
        Precompiles["EVM Precompiles"]:::rust
    end

    %% External Integrations Layer
    subgraph "External Integrations"
        direction TB
        RelayChain["Polkadot Relay Chain"]:::network
        EthWallets["Ethereum Wallets & Tooling"]:::network
        DockerReg["Docker Images & Build Definitions"]:::external
        CICD["CI/CD Workflows"]:::external
        CI_Templates["Release & Versioning CI Templates"]:::external
    end

    %% Connections: Client -> Node
    TSAPI -->|HTTP/WS JSON-RPC| RPCCore
    TSBundle -->|HTTP/WS JSON-RPC| RPCCore
    CLISpec -->|calls| NodeService
    CLIParser -->|invokes| NodeMain
    DevTools -->|scripts| NodeService
    TestHarness -->|JSON-RPC| RPCCore

    %% Node Internal Connections
    NodeMain -->|starts| NodeService
    NodeService -->|exposes| RPCCore
    RPCCore -->|implements| RPCImpl
    RPCImpl -->|uses| EVMTrace
    RPCImpl -->|uses| VRF

    %% Node -> Runtime
    NodeService -->|dispatches| RuntimeCommon
    NodeService -->|exec block| MoonbeamRT

    %% Runtime Internal
    RuntimeCommon -->|includes| Pallets
    RuntimeCommon -->|includes| Frontier["Frontier Pallets"]:::rust
    RuntimeCommon -->|includes| PolkadotSDK["Polkadot-SDK Pallets"]:::rust
    RuntimeCommon -->|calls| Precompiles
    EVMTracerRT -->|hooks| Precompiles
    RuntimeCommon -->|encodes| RelayEnc

    %% Node -> Relay Chain
    NodeService -->|Cumulus XCM| RelayChain

    %% External flows
    CICD -->|publishes| DockerReg
    CICD -->|runs workflows| NodeService
    CI_Templates -->|templates| CICD

    %% Developer Tools to Tests
    DevTools -->|automation| TestHarness

    %% Styles
    classDef rust fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef js fill:#ABEBC6,stroke:#1D8348,color:#0B5345;
    classDef network fill:#F5CBA7,stroke:#B9770E,color:#7E5109;
    classDef external fill:#D5D8DC,stroke:#566573,color:#2C3E50;

    %% Click Events
    click TSAPI "https://github.com/moonbeam-foundation/moonbeam/tree/master/typescript-api/"
    click TSBundle "https://github.com/moonbeam-foundation/moonbeam/tree/master/types-bundle/"
    click CLISpec "https://github.com/moonbeam-foundation/moonbeam/tree/master/scripts/"
    click CLIParser "https://github.com/moonbeam-foundation/moonbeam/tree/master/node/cli/"
    click NodeMain "https://github.com/moonbeam-foundation/moonbeam/blob/master/node/src/main.rs"
    click NodeService "https://github.com/moonbeam-foundation/moonbeam/tree/master/node/service/"
    click RPCCore "https://github.com/moonbeam-foundation/moonbeam/tree/master/client/rpc-core/"
    click RPCImpl "https://github.com/moonbeam-foundation/moonbeam/tree/master/client/rpc/"
    click EVMTrace "https://github.com/moonbeam-foundation/moonbeam/tree/master/client/evm-tracing/"
    click VRF "https://github.com/moonbeam-foundation/moonbeam/tree/master/client/vrf/"
    click RuntimeCommon "https://github.com/moonbeam-foundation/moonbeam/tree/master/runtime/common/"
    click EVMTracerRT "https://github.com/moonbeam-foundation/moonbeam/tree/master/runtime/evm_tracer/"
    click MoonbeamRT "https://github.com/moonbeam-foundation/moonbeam/tree/master/runtime/moonbeam/"
    click MoonbaseRT "https://github.com/moonbeam-foundation/moonbeam/tree/master/runtime/moonbase/"
    click MoonriverRT "https://github.com/moonbeam-foundation/moonbeam/tree/master/runtime/moonriver/"
    click RelayEnc "https://github.com/moonbeam-foundation/moonbeam/tree/master/runtime/relay-encoder/"
    click Pallets "https://github.com/moonbeam-foundation/moonbeam/tree/master/pallets/"
    click Precompiles "https://github.com/moonbeam-foundation/moonbeam/tree/master/precompiles/"
    click DockerReg "https://github.com/moonbeam-foundation/moonbeam/tree/master/docker/"
    click CICD "https://github.com/moonbeam-foundation/moonbeam/tree/master/.github/workflows/"
    click CI_Templates "https://github.com/moonbeam-foundation/moonbeam/tree/master/.github/workflow-templates/"
```
