# quilibriumnetwork/ceremonyclient architecture

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

## Overview

##### Main Components
- Node Runtime (written in Go): This is the “heart” of the system. It consists of several sub‑modules:
– Consensus Engine: Found in node/consensus (with “master”, “time” and “data” folders) that handles consensus, message broadcasting, registration, and time synchronization.
– P2P/Networking Layer: Located in node/p2p and interfacing with go‑libp2p libraries (e.g. go‑libp2p-blossomsub, kad‑dht, etc.) which manage peer discovery, gossip, and network communications.
– Execution Engine & Intrinsics: Managed in node/execution and its “intrinsics” folders for token management, transaction processing, and smart contract like operations.
– Storage Engine: Provided by the Pebble database (separate “pebble” directory) that is used for writing node state, logs, and snapshots.
– API / RPC Layers: The node also supports gRPC and REST endpoints (configured via node/protobufs and config entries) to expose read-only operations, such as querying token balances.
– Hypergraph & Additional Internal Modules: For state management and high‑level data organization (under node/hypergraph).

- Cryptographic Libraries and Protocols:
– Other Cryptographic Modules: Directories such as “bls48581”, “channel”, “rpm”, “verenc”, and “nekryptology” (the latter being a comprehensive Rust crypto suite) provide various cryptographic primitives (BLS signatures, threshold encryption, key exchange protocols, etc.) which are either directly used by the node or available as helper libraries.
– Signers: The “signers” directory contains tools and pre-generated PEM files for managing signatures and possibly cooperating with node operations when performing transaction signing.

- Build and Deployment Tooling:
– Docker-related files, Taskfiles, Makefiles and scripts for building, testing, and deployment.
– Hybrid build system that interleaves Rust+Go builds is shown via commands in the README.

##### Relationships and Interactions
– The consensus module communicating with the execution engine to process transactions.
– The node’s p2p network layer interfacing with lower-level libp2p libraries (illustrate dependency on go‑libp2p, which itself uses modules such as kad‑dht and blossomsub).
– The storage layer (Pebble) accessed by node components for state persistence.
– The API layer that exposes gRPC/REST endpoints to external clients.
- That the cryptographic libraries (BLS, verenc, channel, etc.) are referenced by the node’s crypto and consensus modules.
- Optionally, highlight that there are testing and generated code modules (like generated code under “generated” folders) that ensure correctness but are not part of the runtime execution path.

##### Architectural Patterns and Design Principles
- Modular design: Each major functionality (consensus, execution, networking, storage, crypto) is separated into its own module or directory.
- Hybrid Language Interoperability: The architecture emphasizes integration between Go (for networking, consensus, and orchestration) and Rust (for performance-critical cryptographic primitives such as VDF).
- Decentralization & Peer-to-Peer Communication: Leverage libp2p libraries showing a highly distributed network stack.
- API Exposure: gRPC and REST interfaces are provided for monitoring and interacting with the node (emphasize the potential security considerations such as firewall-based restrictions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Quilibrium Node (Go Runtime)"
        Node["Node Runtime"]:::go
        Consensus["Consensus Engine"]:::go
        P2P["P2P Networking Layer"]:::go
        Execution["Execution Engine & Intrinsics"]:::go
        API["API / RPC Endpoints"]:::go
        Hypergraph["Hypergraph Module"]:::go
        Node -->|"includes"| Consensus
        Node -->|"includes"| P2P
        Node -->|"includes"| Execution
        Node -->|"includes"| API
        Node -->|"includes"| Hypergraph
    end

    subgraph "Storage"
        Pebble["Storage Engine (Pebble DB)"]:::go
    end

    subgraph "External Rust Modules"
        VDF["Rust VDF Library"]:::rust
    end

    subgraph "Cryptographic Modules"
        BLS["BLS Signatures"]:::crypto
        Channel["Secure Channel Protocols"]:::crypto
        RPM["RPM Cryptographic Primitives"]:::crypto
        Verenc["Verifiable Encryption"]:::crypto
        Nekrypto["Nekryptology Suite"]:::crypto
        Signers["Signers & PEM Tools"]:::crypto
    end

    subgraph "Client Interfaces"
        Clients["gRPC/REST API Clients"]:::client
    end

    subgraph "Build & Deployment Tools"
        Build["Docker, Taskfiles, Makefiles & Scripts"]:::build
    end

    %% Relationships Among Components
    Consensus -->|"processes"| Execution
    Execution -->|"reads/writes"| Pebble
    API -->|"exposes"| Clients
    Node ---|"CGO_call"| VDF
    Consensus ---|"uses_crypto"| BLS
    Consensus ---|"uses_crypto"| Channel
    Consensus ---|"uses_crypto"| RPM
    Consensus ---|"uses_crypto"| Verenc
    Consensus ---|"uses_crypto"| Nekrypto
    Execution ---|"signs_tx"| Signers
    P2P ---|"peer_to_peer"| Clients
    Build --- Node

    %% Click Events
    click Node "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/node/"
    click Consensus "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/node/consensus/"
    click P2P "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/node/p2p/"
    click Execution "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/node/execution/"
    click API "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/node/protobufs/"
    click Hypergraph "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/node/hypergraph/"
    click Pebble "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/pebble/"
    click VDF "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/vdf/"
    click BLS "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/bls48581/"
    click Channel "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/channel/"
    click RPM "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/rpm/"
    click Verenc "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/verenc/"
    click Nekrypto "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/nekryptology/"
    click Signers "https://github.com/quilibriumnetwork/ceremonyclient/tree/develop/signers/"

    %% Styles
    classDef go fill:#AEDFF7,stroke:#1F77B4,color:#000000;
    classDef rust fill:#F7CFAA,stroke:#D14F4F,color:#000000;
    classDef crypto fill:#C1F7C1,stroke:#339933,color:#000000;
    classDef client fill:#F7F1AE,stroke:#D6A222,color:#000000;
    classDef build fill:#F7D2AE,stroke:#D46F22,color:#000000;
```
