# multiversx/mx-chain-go architecture

> Architecture diagram of the GitHub repository multiversx/mx-chain-go, 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/multiversx/mx-chain-go
- Repository: https://github.com/multiversx/mx-chain-go

## Overview

This project is a full‐featured blockchain node written in Go for the MultiversX protocol. It implements numerous key components of a blockchain system – from networking (P2P communication and libp2p integration) and consensus (SPoS, block signing, multi-signatures, etc.) to state management (tries, account databases, snapshots) and a smart contract VM layer (EVM, K-Framework, IELE, and system smart contracts). The repository’s file tree is huge and modular; it clearly separates functionality into directories such as “api”, “cmd”, “consensus”, “dataRetriever”, “sharding”, “state”, “process”, “trie”, “vm”, and many others. The README also highlights the installation steps, key generation, and a broad list of “Done” items that give insight into the depth of the architecture (for instance cryptography, threshold signatures, consensus optimizations, and multiple testing suites).

##### Main Components
- Node & Command-line Interface – Found within cmd/node and related key generator tools. This is the entry point that starts the node.
- P2P Networking Module – Look into “p2p” (and related submodules like p2p/config, p2p/mock) which handle peer discovery, message dispatching, and the wiring protocol.
- Consensus Engine – Found under “consensus” and its subdirectories (like the “spos” folder) where the consensus (SPoS) mechanisms, block signing, and round management are implemented.
- Block & Transaction Processing – Present in “process” (which contains subdirectories for block pre‐processing, processing, post‐processing, interceptors, and even reward transactions). This layer is responsible for validating, processing, and applying state changes.
- State Management and Storage – Look at “state”, “trie”, and “storage” modules. The system uses trie structures for maintaining account data, snapshots for state persistence, and storage pruning.
- Virtual Machine & Smart Contracts – The “vm” directory handles the integration with various VMs (K-Framework, EVM, IELE) and the system smart contracts. This layer is critical for smart contract deployment, execution, and state updates.
- API/Monitoring – Several files (in “api”, “health”, “heartbeat”, “statusHandler”) handle REST endpoints, Prometheus metrics, and dashboards for monitoring. Also consider dashboards and external configurations in “docker” and “scripts” directories.
- Auxiliary Components – Additional modules include “keysManagement” (node identity), “sharding” (managing sharded data and network sharding), “outport” (for external communication and event notification), and update/factory components to bootstrap and update the node state.

##### Relationships and Data Flow
- The P2P layer receives and sends network messages (blocks, transactions, heartbeat messages) and hands off data to the Consensus Engine.
- The Consensus Engine collaborates with block processing modules (in “process”) to validate and finalize blocks.
- Block processing components interact intensively with the State Management, updating the ledger state via tries and persistent storage.
- The Virtual Machine layer hooks into block processing to execute smart contracts and validate transactions.
- The API and monitoring services expose node status and metrics collected from various layers.
- External tools (e.g., key generator, Docker scripts) help bootstrap or interact with the node.

##### Architectural Patterns & Design Principles
- Modular and Layered Architecture: Each major component (networking, consensus, processing, state, VM) is isolated into its own package and directory, following a strict separation of concerns.
- Interface-based Design: Many directories have “interface.go” and “mock” subfolders; this suggests heavy use of interfaces allowing dependency injection and testing.
- Chain-of-Responsibility: The block/transaction processing pipeline is implemented via interceptors (see process/interceptors) which form a chain that processes data sequentially.
- Extensive Testing Infrastructure: The repository includes unit tests, integration tests, and mocks in nearly every component, which highlights the design’s emphasis on testability.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Node & CLI Entry
    subgraph "Node & CLI Entry"
        N1["Node (cmd/node)"]:::cli
        N2["Key-generator (cmd/keygenerator)"]:::cli
    end

    %% Network & P2P Communication
    subgraph "Network & P2P Communication"
        P2["P2P Networking (p2p)"]:::p2p
    end

    %% Consensus Engine
    subgraph "Consensus Engine"
        C1["Consensus Engine (consensus)"]:::consensus
    end

    %% Block & Transaction Processing
    subgraph "Block & Transaction Processing"
        BP["Block/Transaction Processing (process)"]:::processing
    end

    %% State Management and Storage
    subgraph "State Management and Storage"
        S1["State (state)"]:::state
        S2["Storage (storage)"]:::state
        S3["Trie (trie)"]:::state
    end

    %% Virtual Machine & Smart Contracts
    subgraph "Virtual Machine & Smart Contracts"
        V1["VM (vm)"]:::vm
        V2["System Smart Contracts (vm/systemSmartContracts)"]:::vm
    end

    %% API / Monitoring
    subgraph "API / Monitoring"
        A1["API Services (api)"]:::api
        A2["Health Monitoring (health)"]:::api
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        X1["Keys Management (keysManagement)"]:::aux
        X2["Sharding (sharding)"]:::aux
        X3["Outport (outport)"]:::aux
    end

    %% Relationships and Data Flow
    N2 -->|"init"| N1
    N1 -->|"starts"| P2
    P2 -->|"forwards"| C1
    C1 -->|"triggers"| BP
    BP -->|"updates"| S1
    BP -->|"invokes"| V1
    V1 <-->|"state-update"| S1
    V1 -->|"leverages"| V2
    C1 -->|"reports"| A1
    BP -->|"notifies"| A1
    S1 -->|"exposes"| A1

    %% Auxiliary interactions
    X1 -->|"provides identity"| N1
    X2 -->|"supports"| S1
    X3 -->|"communicates"| A1

    %% Click Events
    click N1 "https://github.com/multiversx/mx-chain-go/tree/master/cmd/node"
    click N2 "https://github.com/multiversx/mx-chain-go/tree/master/cmd/keygenerator"
    click P2 "https://github.com/multiversx/mx-chain-go/tree/master/p2p/"
    click C1 "https://github.com/multiversx/mx-chain-go/tree/master/consensus/"
    click BP "https://github.com/multiversx/mx-chain-go/tree/master/process/"
    click S1 "https://github.com/multiversx/mx-chain-go/tree/master/state/"
    click S2 "https://github.com/multiversx/mx-chain-go/tree/master/storage/"
    click S3 "https://github.com/multiversx/mx-chain-go/tree/master/trie/"
    click V1 "https://github.com/multiversx/mx-chain-go/tree/master/vm/"
    click V2 "https://github.com/multiversx/mx-chain-go/tree/master/vm/systemSmartContracts"
    click A1 "https://github.com/multiversx/mx-chain-go/tree/master/api/"
    click A2 "https://github.com/multiversx/mx-chain-go/tree/master/health/"
    click X1 "https://github.com/multiversx/mx-chain-go/tree/master/keysManagement/"
    click X2 "https://github.com/multiversx/mx-chain-go/tree/master/sharding/"
    click X3 "https://github.com/multiversx/mx-chain-go/tree/master/outport/"

    %% Styles
    classDef cli fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef p2p fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef consensus fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef processing fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef state fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef vm fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef api fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef aux fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
