How hathornetwork/hathor-core works
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