# asonnino/hotstuff architecture

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

- Interactive diagram: https://gitdiagram.com/asonnino/hotstuff
- Repository: https://github.com/asonnino/hotstuff

## Overview

##### Project’s Main Components
a. Node: The entry point for the distributed system (found in the “node” directory). The main node executable orchestrates the overall protocol run.
b. Consensus: The core of the protocol is implemented here (see the “consensus” directory). Break it down further into:
- Aggregator, Leader, Proposer, Synchronizer, and Timer (as supported by the individual source files).
c. Mempool: Manages and batches incoming transactions (the “mempool” directory).
d. Crypto: Provides real cryptography functions (in “crypto”) using libraries like ed25519-dalek.
e. Network: Handles the communications between nodes (see “network”) and uses asynchronous frameworks (tokio).
f. Store: Provides persistent storage for consensus data (the “store” module), integrating with rocksdb.
g. Benchmark: Although not part of the operational protocol, this directory (with Python scripts and Fabric configurations) enables local testing, deployment, and result aggregation.

##### Detail the Relationships and Interactions
- The Node (main executable) acts as the central unit that ties together:
- The Consensus module for handling BFT protocol steps.
- The Mempool module for transaction management.
- The Network layer ensuring communication between distributed nodes.
- The Crypto module, which supports signing and verifying messages throughout the protocol.
- The Store module for persistent storage of consensus decisions and blocks.

- Within Consensus, submodules (like proposer, synchronizer, etc.) collaborate to achieve consensus. For example, the leader node, after collecting proposals, communicates through the network layer.

- The Benchmark scripts (Python, using Fabric) trigger and manage node deployment/testing, invoking the compiled Rust components, gathering logs, and collecting metrics such as TPS (transaction per second) and latency.

##### Architectural Patterns and Design Principles
- Modular and layered design: Each core functionality is encapsulated in its own Rust crate (consensus, mempool, crypto, network, store), promoting separation of concerns.
- Asynchronous communication: The use of Tokio in the network layer suggests an event-driven and asynchronous design for inter-node communications.
- Real-world integration of libraries: The usage of dalek for cryptography and rocksdb for storage shows an intent to closely mimic production-like setups, even though the purpose here is benchmarking and prototyping.
- Testing emphasis: Each crate has a “tests” subdirectory, which implies the project strongly focuses on modular testing of each component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Node["Node (Entry Point)"]:::backend

    subgraph "Consensus Module"
        Consensus["Consensus Engine"]:::backend
        Aggregator["Aggregator"]:::backend
        Leader["Leader"]:::backend
        Proposer["Proposer"]:::backend
        Synchronizer["Synchronizer"]:::backend
        Timer["Timer"]:::backend
    end

    Mempool["Mempool (Transaction Pool)"]:::backend
    Crypto["Crypto (ed25519-dalek)"]:::backend
    Network["Network (Tokio)"]:::network
    Store["Store (rocksdb)"]:::backend
    Benchmark["Benchmark (Python/Fabric)"]:::benchmark

    %% Relationships
    Node -->|"init_consensus"| Consensus
    Node -->|"send_message"| Network
    Consensus -->|"batch_transactions"| Mempool
    Consensus -->|"crypto_sign_verify"| Crypto
    Consensus -->|"persist_data"| Store
    Consensus -->|"network_comm"| Network
    Network -->|"deliver_message"| Node

    Benchmark -.->|"orchestrates"| Node
    Benchmark -.->|"monitors"| Consensus

    %% Click Events
    click Node "https://github.com/asonnino/hotstuff/blob/main/node/src/main.rs"
    click Consensus "https://github.com/asonnino/hotstuff/tree/main/consensus/src"
    click Aggregator "https://github.com/asonnino/hotstuff/blob/main/consensus/src/aggregator.rs"
    click Leader "https://github.com/asonnino/hotstuff/blob/main/consensus/src/leader.rs"
    click Proposer "https://github.com/asonnino/hotstuff/blob/main/consensus/src/proposer.rs"
    click Synchronizer "https://github.com/asonnino/hotstuff/blob/main/consensus/src/synchronizer.rs"
    click Timer "https://github.com/asonnino/hotstuff/blob/main/consensus/src/timer.rs"
    click Mempool "https://github.com/asonnino/hotstuff/tree/main/mempool/src"
    click Crypto "https://github.com/asonnino/hotstuff/blob/main/crypto/src/lib.rs"
    click Network "https://github.com/asonnino/hotstuff/tree/main/network/src"
    click Store "https://github.com/asonnino/hotstuff/blob/main/store/src/lib.rs"
    click Benchmark "https://github.com/asonnino/hotstuff/tree/main/benchmark/"

    %% Styles
    classDef backend fill:#B3CDE0,stroke:#005B96,stroke-width:2px;
    classDef network fill:#FBB4AE,stroke:#E41A1C,stroke-width:2px;
    classDef benchmark fill:#FED9A6,stroke:#FF8C00,stroke-width:2px,stroke-dasharray: 5 5;
```
