# hathornetwork/hathor-core architecture

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

- Interactive diagram: https://gitdiagram.com/hathornetwork/hathor-core
- Repository: https://github.com/hathornetwork/hathor-core

## Overview

##### Project type and purpose
- Hathor-core is a Python-based, monolithic full-node client for the Hathor blockchain. It implements peer-to-peer networking, consensus (DAG-based PoW/PoA), transaction processing, storage (RocksDB), mining interfaces (CPU, Stratum, merged mining), API endpoints (REST + WebSocket), metrics (Prometheus), CLI tooling, feature-activation flags, and an event queue/simulator.

##### File-structure analysis
- Top-level module “hathor/” contains all domain code, divided into subpackages:
- p2p – network layer, peer discovery, message protocol, sync agents
- consensus – block/tx consensus rules, PoA, DAA
- transaction – tx models, scripts, storage, validators, migrations
- storage – RocksDB storage abstraction
- indexes – secondary indexes over blocks/UTXOs/mempool
- mining – block template, CPU service, Stratum server, merged-mining support
- api resources under transaction/resources, p2p/resources, wallet/resources, profiler/resources, sysctl/websocket, etc.
- cli – command-line interfaces to start node, import/export DB, simulate events, generate keys/tx, etc.
- reactor – event loop and protocol dispatch
- event – event-queue, simulation, websocket notifications
- wallet – HD and thin wallets, key management, tx‐signing, REST endpoints
- feature_activation – fork/feature flag service and storage
- merged_mining – Bitcoin RPC integration and status APIs
- promethus, metrics, profiler – instrumentation and resource endpoints
- sysctl – dynamic settings management via REST/WebSocket
- Configuration and deployment: Dockerfile, Makefile, .github/workflows, extras/docker templates, flake.nix, pyproject.toml.

##### README insights

1. P2P Network Layer
- Peer Discovery, Message Protocol, Sync Agents (sync_v1 & sync_v2)
2. Reactor / Event Loop
- Async dispatch of network, mining, CLI commands, simulation events
3. Consensus & Verification
- BlockConsensus, TxConsensus, PoA signer, DAA, verify/accept blocks & txs
4. Storage & Indexing
- RocksDB Storage backend, Migrations, TransactionStorage, EventStorage
- Index Manager: UTXO, Timestamp, Address, Mempool, Tips
5. API Layer
- REST Resources: transaction, p2p, wallet, profiler, sysctl, merged-mining, healthcheck
- WebSocket notifications: event queue, sysctl, mining updates
- Stratum Server (mining protocol)
6. Mining Clients
- CPU mining service, merged mining coordinator (Bitcoin RPC), mining API
7. Wallet Subsystem
- HD wallet, thin wallet, keypair management, tx signing, REST interfaces
8. Feature-Activation Service
- Bit signaling, feature criteria, activation storage
9. Metrics & Profiler
- Prometheus exporter, profiling endpoints, CPU profiler
10. CLI Tooling & Scripts
- run_node, db_export/import, event_simulator, genesis generation, POA keys, etc.
11. Simulator & Event Queue
- Fake connections, event replays, triggers for testing and benchmarking
12. Configuration & Sysctl
- Dynamic settings loader, REST/WebSocket manager for runtime changes
- P2P Network → Reactor → Consensus → Storage & Indexes
- CLI & Simulator → Reactor → invoke Consensus/Storage/API
- Consensus → triggers events → Event queue → WebSocket notifications
- API Layer ←→ Storage & Indexes (query)
- Mining Clients → Reactor → Consensus & Storage (new block production) → P2P Network
- Merged-mining coordinator ↔ Bitcoin RPC external service
- Feature-Activation Service ↔ Consensus ↔ P2P (signal bits)
- Metrics & Profiler ← hooks in Reactor, Consensus, P2P, Storage
- Sysctl API ↔ Configuration manager → all subsystems (e.g., toggling features)
c. Architectural patterns & principles:
- Modular domain packages (separation by responsibility)
- Layered architecture: Network → Core (Reactor + Consensus) → Storage → API/UI
- Event-driven (Reactor pattern) and resource-oriented (REST/WebSocket) layering
- Dependency injection via factory classes for P2P, storage, sysctl, websockets
- Use of migrations and pluggable backends (RocksDB abstraction)
d. Key technologies
- Python 3, asyncio/reactor
- RocksDB (via python bindings) for persistent storage
- HTTP REST (Bottle/Flask style), WebSocket for real-time updates
- Prometheus client library, p2p custom protocol over TLS
- Pycoin for Bitcoin merged-mining
- Docker for containerized deployment, flake.nix for reproducible builds

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Peers["P2P Peers"]:::external
    BitcoinRPC["Bitcoin RPC"]:::external

    %% Core Subsystems
    subgraph "1. P2P Network Layer"
        direction TB
        P2PLayer["P2P Network\n(Peer Discovery,\nMessage Protocol,\nSync Agents)"]:::module
    end

    subgraph "2. Reactor / Event Loop"
        direction TB
        Reactor["Reactor / Event Loop"]:::module
    end

    subgraph "3. Consensus & Verification"
        direction TB
        ConsensusEngine["Consensus Engine\n(BlockConsensus,\nTxConsensus,\nDAA, PoA)"]:::module
        Verifier["Verification Services"]:::module
    end

    subgraph "4. Storage & Indexing"
        direction TB
        DB["RocksDB Storage"]:::database
        EventStorage["Event Storage\n(RocksDB)"]:::database
        Indexes["Index Manager\n(UTXO, Address,\nTimestamp, Tips)"]:::module
    end

    subgraph "5. API Layer"
        direction TB
        REST["REST Resources"]:::api
        WebSocketAPI["WebSocket Notifications"]:::api
        Stratum["Stratum Server"]:::api
    end

    subgraph "6. Mining Clients"
        direction TB
        CPUMiner["CPU Mining Service"]:::module
        MergedCoordinator["Merged-Mining Coordinator"]:::module
    end

    subgraph "7. Wallet Subsystem"
        direction TB
        Wallet["Wallet (HD, Thin,\nKey Management)"]:::module
    end

    subgraph "8. Feature-Activation Service"
        direction TB
        FeatureSvc["Feature-Activation\nService"]:::module
    end

    subgraph "9. Metrics & Profiler"
        direction TB
        Prometheus["Prometheus Exporter"]:::module
        Profiler["Profiler Endpoints"]:::module
    end

    subgraph "10. CLI Tooling & Scripts"
        direction TB
        CLI["CLI Tools & Scripts"]:::module
    end

    subgraph "11. Simulator & Event Queue"
        direction TB
        Simulator["Simulator Harness"]:::module
        EventQueue["Event Queue"]:::module
    end

    subgraph "12. Configuration & Sysctl"
        direction TB
        Config["Static Configuration"]:::module
        Sysctl["Dynamic Sysctl Manager"]:::module
    end

    %% Data and Control Flows
    Peers -->|network messages| P2PLayer
    P2PLayer -->|events| Reactor
    CLI -->|commands| Reactor
    Simulator -->|test events| Reactor
    Reactor -->|calls| ConsensusEngine
    Reactor -->|dispatch| EventQueue
    ConsensusEngine -->|verify| Verifier
    ConsensusEngine -->|persist| DB
    DB -->|query| Indexes
    Indexes -->|data| REST
    REST -->|calls| DB
    WebSocketAPI -->|notifications| REST
    EventQueue -->|push| WebSocketAPI
    CLI -->|cli API| REST
    CPUMiner -->|mining ticks| Reactor
    MergedCoordinator -->|RPC calls| BitcoinRPC
    MergedCoordinator -->|mining tasks| Reactor
    ConsensusEngine -->|feature bits| FeatureSvc
    FeatureSvc -->|feature flags| Reactor
    Sysctl -->|settings| Reactor
    Sysctl -->|settings| ConsensusEngine
    Sysctl -->|settings| P2PLayer
    Prometheus -->|metrics| Reactor
    Prometheus -->|metrics| ConsensusEngine
    Prometheus -->|metrics| P2PLayer
    Prometheus -->|metrics| DB
    Profiler -->|profile| Reactor
    Profiler -->|profile| ConsensusEngine
    Profiler -->|profile| P2PLayer
    CLI -->|simulate| Simulator
    Simulator -->|generate| EventQueue

    %% Click Events
    click P2PLayer "https://github.com/hathornetwork/hathor-core/tree/master/hathor/p2p/"
    click Reactor "https://github.com/hathornetwork/hathor-core/tree/master/hathor/reactor/"
    click ConsensusEngine "https://github.com/hathornetwork/hathor-core/tree/master/hathor/consensus/"
    click Verifier "https://github.com/hathornetwork/hathor-core/tree/master/hathor/verification/"
    click DB "https://github.com/hathornetwork/hathor-core/blob/master/hathor/storage/rocksdb_storage.py"
    click EventStorage "https://github.com/hathornetwork/hathor-core/blob/master/hathor/event/storage/rocksdb_storage.py"
    click Indexes "https://github.com/hathornetwork/hathor-core/tree/master/hathor/indexes/"
    click REST "https://github.com/hathornetwork/hathor-core/tree/master/hathor/transaction/resources/"
    click WebSocketAPI "https://github.com/hathornetwork/hathor-core/tree/master/hathor/websocket/"
    click Stratum "https://github.com/hathornetwork/hathor-core/tree/master/hathor/stratum/"
    click CPUMiner "https://github.com/hathornetwork/hathor-core/blob/master/hathor/mining/cpu_mining_service.py"
    click MergedCoordinator "https://github.com/hathornetwork/hathor-core/blob/master/hathor/merged_mining/coordinator.py"
    click Wallet "https://github.com/hathornetwork/hathor-core/tree/master/hathor/wallet/"
    click FeatureSvc "https://github.com/hathornetwork/hathor-core/tree/master/hathor/feature_activation/"
    click Prometheus "https://github.com/hathornetwork/hathor-core/blob/master/hathor/prometheus.py"
    click Profiler "https://github.com/hathornetwork/hathor-core/tree/master/hathor/profiler/"
    click CLI "https://github.com/hathornetwork/hathor-core/tree/master/hathor/cli/"
    click Simulator "https://github.com/hathornetwork/hathor-core/tree/master/hathor/simulator/"
    click EventQueue "https://github.com/hathornetwork/hathor-core/tree/master/hathor/event/"
    click Config "https://github.com/hathornetwork/hathor-core/tree/master/hathor/conf/"
    click Sysctl "https://github.com/hathornetwork/hathor-core/blob/master/hathor/sysctl/core/manager.py"

    %% Styles
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef module fill:#FFDDAA,stroke:#E89300,stroke-width:1px
    classDef database fill:#FFEEAA,stroke:#E8A317,stroke-width:1px
    classDef api fill:#DDEEFF,stroke:#3178C6,stroke-width:1px
```
