How harmony-one/harmony works
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.