# harmony-one/harmony architecture

> Architecture diagram of the GitHub repository harmony-one/harmony, 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/harmony-one/harmony
- Repository: https://github.com/harmony-one/harmony

## Overview

##### Main Components
- Node Core: Represents the executable that runs a Harmony node (found in directories like cmd/harmony, node/harmony). This is where node lifecycle management, block validation, and basic service startup happens.
- Consensus Engine: Modules under consensus/ and parts of api/service/consensus implement FBFT and view-change protocols. Include components for block proposals, message passing, and multi-signature verification.
- Blockchain & State Management: The core package (core/) manages the blockchain’s data, block validation, chain state, genesis initialization, state transition logic, and snapshotting.
- Virtual Machine (EVM/Smart Contract Execution): The core/vm/ directory shows the implementation of the EVM and related execution logic, along with gas accounting, opcodes, and instruction processing.
- P2P Networking: Found in p2p/ and rpc/ directories. This layer covers discovery, host management, stream handling, and secure message exchanges between nodes.
- Crypto & Cryptographic Primitives: The crypto/, accounts/ and consensus/signature directories encapsulate BLS, VRF, VDF, as well as other cryptographic functions essential for staking, consensus, and identity.
- API & RPC Services: The rpc/harmony/ and api/ directories implement the HTTP/JSON/GRPC RPC interfaces (including Ethereum RPC compatibility and Rosetta support) that allow external systems – like wallets, explorers, and testers – to interact with the blockchain.
- Staking & Governance: Modules in staking/ and consensus/reward manage staking, rewards, slashing, delegation, and validator management.
- Infrastructure & Build Tools: Dockerfile, Makefile, CI workflows, and scripts/ offer the build, deployment, and testing infrastructure that supports regular development and operation.

##### Relationships and Interactions
- Data flows from the P2P layer (and external API calls) into the node. Transactions and blocks are validated by the blockchain core and executed within the VM.
- The consensus engine communicates with the P2P layer to broadcast messages (e.g., for block proposals and votes) and then instructs the blockchain core to append new blocks.
- Cryptographic modules (BLS, VRF, etc.) support both consensus (multisignature generation/verification) and account management.
- The RPC and API services act as the interface layer between the blockchain internals and outside clients (wallets, explorers, and monitoring tools).

##### Architectural Patterns and Design Principles
- Modularity: The project is separated into discrete modules (consensus, core, network, crypto, etc.) each with well-defined responsibilities.
- Layering: There’s a clear separation from the lower-level cryptographic and storage systems up to consensus, networking, execution, and finally external API interfaces.
- Use of Distributed Consensus (FBFT): Emphasize how block proposal, multi-signature aggregation, and view-change protocols interact.

##### Relevant Technologies, Frameworks, & Libraries
- Programming language: Go (with use of Go modules, testing frameworks, and CI tools).
- Docker: Shown by the Dockerfile and the dev Docker image instructions.
- CI/CD: GitHub workflows and Makefile support regular builds and tests.
- External C/C++ libraries: The build instructions mention linking to native libraries (mcl, bls, GMP, OpenSSL) which support cryptographic operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph for Node Operations
    subgraph "Node Operations"
        NodeCore["Node Core"] 
        ConsensusEngine["Consensus Engine"] 
        BlockchainCore["Blockchain & State Management"] 
        VirtualMachine["Virtual Machine (EVM)"] 
        P2PNetworking["P2P Networking"] 
        Staking["Staking & Governance"]
    end

    %% Subgraph for Support & Interfaces
    subgraph "Support & Interfaces"
        API_RPC["API & RPC Services"] 
        Crypto["Crypto & Cryptographic Primitives"] 
        Infrastructure["Infrastructure & Build Tools"] 
        Clients["External Clients"]
    end

    %% Relationships
    Clients -->|"connects"| API_RPC
    API_RPC -->|"interfacesTo"| NodeCore
    NodeCore -->|"orchestrates"| ConsensusEngine
    ConsensusEngine -->|"proposesTo"| BlockchainCore
    BlockchainCore -->|"executesIn"| VirtualMachine
    NodeCore -->|"manages"| P2PNetworking
    P2PNetworking -->|"broadcastsTo"| ConsensusEngine
    ConsensusEngine -->|"utilizes"| Crypto
    BlockchainCore -->|"validatesWith"| Crypto
    NodeCore -->|"handles"| Staking
    Staking -->|"integratesWith"| ConsensusEngine
    Infrastructure -->|"buildsAndDeploys"| NodeCore

    %% Click Events for Node Core
    click NodeCore "https://github.com/harmony-one/harmony/tree/main/cmd/harmony"
    click NodeCore "https://github.com/harmony-one/harmony/tree/main/node/harmony"

    %% Click Events for Consensus Engine
    click ConsensusEngine "https://github.com/harmony-one/harmony/tree/main/consensus/"
    click ConsensusEngine "https://github.com/harmony-one/harmony/tree/main/api/service/consensus"

    %% Click Event for Blockchain & State Management
    click BlockchainCore "https://github.com/harmony-one/harmony/tree/main/core/"

    %% Click Event for Virtual Machine
    click VirtualMachine "https://github.com/harmony-one/harmony/tree/main/core/vm"

    %% Click Events for P2P Networking
    click P2PNetworking "https://github.com/harmony-one/harmony/tree/main/p2p/"
    click P2PNetworking "https://github.com/harmony-one/harmony/tree/main/rpc/harmony"

    %% Click Events for Crypto & Cryptographic Primitives
    click Crypto "https://github.com/harmony-one/harmony/tree/main/crypto/"
    click Crypto "https://github.com/harmony-one/harmony/tree/main/crypto/bls"
    click Crypto "https://github.com/harmony-one/harmony/tree/main/crypto/vrf"
    click Crypto "https://github.com/harmony-one/harmony/tree/main/accounts"
    click Crypto "https://github.com/harmony-one/harmony/tree/main/consensus/signature"

    %% Click Events for API & RPC Services
    click API_RPC "https://github.com/harmony-one/harmony/tree/main/rpc/harmony"
    click API_RPC "https://github.com/harmony-one/harmony/tree/main/api/"

    %% Click Events for Staking & Governance
    click Staking "https://github.com/harmony-one/harmony/tree/main/staking/"
    click Staking "https://github.com/harmony-one/harmony/tree/main/consensus/reward"

    %% Click Events for Infrastructure & Build Tools
    click Infrastructure "https://github.com/harmony-one/harmony/tree/main/Dockerfile"
    click Infrastructure "https://github.com/harmony-one/harmony/tree/main/Makefile"
    click Infrastructure "https://github.com/harmony-one/harmony/tree/main/.github/workflows"
    click Infrastructure "https://github.com/harmony-one/harmony/tree/main/scripts/"

    %% Styles and Classes
    class NodeCore nodeCore;
    class ConsensusEngine consensus;
    class BlockchainCore blockchain;
    class VirtualMachine vm;
    class P2PNetworking p2p;
    class Staking staking;
    class API_RPC api;
    class Crypto crypto;
    class Infrastructure infra;
    class Clients clients;

    classDef nodeCore fill:#a8dadc,stroke:#1d3557,stroke-width:2px;
    classDef consensus fill:#f1faee,stroke:#457b9d,stroke-width:2px;
    classDef blockchain fill:#ffddd2,stroke:#e63946,stroke-width:2px;
    classDef vm fill:#e9c46a,stroke:#f4a261,stroke-width:2px;
    classDef p2p fill:#d8e2dc,stroke:#2b2d42,stroke-width:2px;
    classDef staking fill:#e0fbfc,stroke:#006d77,stroke-width:2px;
    classDef api fill:#cce3de,stroke:#6497b1,stroke-width:2px;
    classDef crypto fill:#fcd5ce,stroke:#e29578,stroke-width:2px;
    classDef infra fill:#f1f1f1,stroke:#aaa,stroke-width:2px;
    classDef clients fill:#ffe066,stroke:#ff9900,stroke-width:2px;
```
