Harmony core protocol: building and running a sharded node

Harmony's protocol scope and intended users

Harmony solves the implementation side of running and modifying its blockchain rather than offering a small client SDK. The repository description identifies it as the core protocol, while the package layout shows the expected system boundaries: `consensus/`, `shard/`, `staking/`, `p2p/`, `crypto/`, `rpc/`, `node/` and `hmy/`. This is a full protocol codebase for people working on node software, consensus behavior, validators, networking, transaction processing or the public RPC surface.

The repository topics connect the implementation to BLS cryptography, PBFT, proof of stake and sharding. That combination is more specialized than a generic application framework. Harmony is a poor fit for a developer who only needs wallet signing or transaction submission through a small library. It is also a poor fit for someone expecting the README to provide a complete production deployment procedure. The documented path is primarily a source build, a developer image or a local test network.

Several compatibility layers are visible in the tree. The `eth/` directory and the `github.com/ethereum/go-ethereum v1.13.4` dependency indicate that Harmony incorporates Ethereum-related implementation components rather than existing as a blank Go service with blockchain naming alone. Other directories, including `rosetta/`, `accounts/`, `contracts/`, `block/`, `core/` and `api/`, place the protocol components within a node implementation that exposes several operational interfaces.

This is infrastructure code, not an application framework that can be imported merely because Go is available. Its native dependencies and assumptions about repository placement make environment setup part of the adoption decision.

Consensus, shard state and node package boundaries

The repository structure supports a concrete description of Harmony's node flow. `node/` is the natural assembly point, while `consensus/` contains agreement behavior and `shard/` contains shard-specific processing. Transactions enter through interfaces associated with `api/` and `rpc/`, then reach account, block and core processing rather than being handled by a standalone web application. `p2p/` supplies the networking side, while `multibls/`, `crypto/` and related packages provide the cryptographic building blocks.

The repository topics also identify PBFT and BLS as protocol concerns. Harmony does not describe consensus as a simple majority callback. Its implementation is distributed across packages and must coordinate validators, cryptographic signing material, shard state and network communication. The `staking/` package is consistent with the stated proof-of-stake model, while `consensus/` and `shard/` separate agreement machinery from shard context. These package names establish the architecture, but the truncated README does not provide a complete message sequence or state-transition specification.

That distinction matters during review. The tree lets an engineer locate the relevant implementation, but it does not prove how a transaction becomes final, how validator rotation works or which failure conditions trigger consensus changes. Those questions require source inspection under `consensus/`, `shard/` and `staking/`. It would be misleading to infer detailed protocol behavior merely from the package names.

For integration work, the boundary between `rpc/`, `api/` and the internal chain packages is especially relevant. Exposing a method through an API does not mean it maps directly to a simple application function. Calls may cross consensus and shard state. Repository reviewers should trace each endpoint through those boundaries before assuming that a local HTTP response represents final network behavior.

Building Harmony from source with Go and native libraries

The README requires Go 1.24.2, GMP, OpenSSL and Bash 4 or later. `go.mod` declares Go 1.24.0 and selects the `go1.24.2` toolchain. Harmony also depends on the native MCL and BLS libraries. On Ubuntu, the documented system packages provide the compiler and cryptographic development prerequisites:

sudo apt install libgmp-dev libssl-dev make gcc g++

The source layout follows the GOPATH convention even though Go modules are enabled. Create the expected parent directory, change into it, and clone MCL, BLS and Harmony in that order so the native dependencies sit beside the protocol repository:

mkdir -p $(go env GOPATH)/src/github.com/harmony-one
cd $(go env GOPATH)/src/github.com/harmony-one

Clone the three repositories with the exact locations used by the Makefile's include and library paths:

git clone https://github.com/harmony-one/mcl.git
git clone https://github.com/harmony-one/bls.git
git clone https://github.com/harmony-one/harmony.git
cd harmony

The first build resolves Go modules and delegates executable and native-library work to the build system:

go mod tidy
make

The Makefile's default target runs `libs` and then `bash ./scripts/go_executable_build.sh -S`. If the required build-tool versions are absent, the README identifies `bash scripts/install_build_tools.sh` as the setup command. It also directs developers who encounter a missing `go.sum` entry to run `go mod tidy`.

On macOS, the library configuration is part of the build rather than an optional convenience. The README defines `MCL_PATH`, `BLS_PATH`, `CGO_CFLAGS`, `CGO_LDFLAGS`, `LD_LIBRARY_PATH`, `LIBRARY_PATH` and `DYLD_FALLBACK_LIBRARY_PATH` in `.zshrc`. Linux can use the Makefile's relative paths for sibling `bls/` and `mcl/` directories, but developers bypassing `make` must reproduce the relevant environment themselves.

A first local-network run through Docker

The repository's Dockerfile is the cleaner first route when the host does not already have Harmony's C and C++ library configuration. It uses Ubuntu 22.04, installs Go 1.24.2, clones Harmony, BLS, MCL and the Go SDK, and builds BLS with `make -j8 BLS_SWAP_G=1`. The image therefore packages a known directory arrangement, although the build still depends on network access while the image is created.

Build the image from the Harmony checkout after cleaning the previous build output:

cd $(go env GOPATH)/src/github.com/harmony-one/harmony
make clean
docker build -t harmony .

The README states that ARM-based hosts, including Apple silicon M1 systems, default to `linux/arm64`. An x86-64 image can be requested explicitly:

docker build --platform linux/amd64 -t harmony .

Start an interactive shell with the repository mounted from the host:

docker run --rm --name harmony -it -v "$(go env GOPATH)/src/github.com/harmony-one/harmony:/root/go/src/github.com/harmony-one/harmony" harmony /bin/bash

Only the Harmony checkout persists through the mount. Other container changes are ephemeral. A second shell can be opened while the named container is running:

docker exec -it harmony /bin/bash

For the first actual local protocol run, execute this command inside the prepared environment:

make debug

The Makefile identifies this target as a two-shard local network with shard 0 RPC at `localhost:9700` and shard 1 RPC at `localhost:9800`. The README also identifies explorer endpoints at `http://localhost:9599` for shard 0 and an HTTP endpoint for shard 1 that is truncated before its port. Because that second endpoint is incomplete, it should not be copied or guessed. The RPC addresses in the Makefile provide the first concrete check: the local processes must bind there before broader protocol testing begins.

Operational limits and native-library failure modes

The largest limitation is environmental. Harmony is not a pure Go checkout that can be compiled on any machine with a current Go installation. CGO links the node to MCL, BLS, GMP and OpenSSL, and the Makefile searches paths such as `../bls`, `../mcl` and `/opt/homebrew/opt/[email protected]`. Moving or renaming a checkout without preserving those relationships can cause compilation or linking failures.

Architecture is another boundary. The README calls out Apple silicon and provides an explicit `linux/amd64` Docker build option. This distinction matters for CI workers and development machines because a Docker image architecture and the host architecture must agree with the intended executable. The repository does not present cross-compilation as a simple supported workflow in the documented build path.

The local network is for development and testing, not evidence that mainnet operation is covered. `make debug` starts a prescribed test topology, but the truncated documentation does not specify validator key requirements, genesis configuration, persistent volume setup, monitoring or node recovery. The repository contains test and configuration directories, yet their presence does not replace operational documentation for production.

There is also no single documented application API for using Harmony as a library. The top-level `api/` and `rpc/` packages serve a running node, while `contracts/` and `eth/` expose protocol-adjacent functionality. Teams that need only transaction submission through a managed endpoint may find that operating this node adds unnecessary build and upgrade work.

These constraints are not incidental setup details. The native build can fail before any Go package behavior can be evaluated, and a successful compile still does not establish correct shard coordination, staking configuration or release compatibility.

Maintenance, releases and LGPL-3.0 implications

The repository is not archived. Its last push was on 2026-09-03, so recent source changes are visible, but commit activity alone does not establish compatibility with a particular deployment. Three mainnet releases are listed in August 2026: `v2026.1.3` on 2026-08-19, `v2026.1.2` on 2026-08-15, and `v2026.1.1` on 2026-08-12. That release cadence makes tag selection a concrete part of node setup.

The default branch is `main`, while the visible CI badge references `dev`. Developers should therefore decide which branch and release tag they intend to compile rather than assuming the latest `main` checkout corresponds to the mainnet binary they expect. The README also documents dependency versions, including `github.com/harmony-one/bls v0.0.6`, while the macOS workflow separately clones the BLS repository. Source dependency metadata and native source-tree behavior are both relevant to build planning.

Harmony is licensed under LGPL-3.0. That identifier defines the license context for reviewing distribution and modification obligations. This article does not interpret legal requirements. Engineers modifying or redistributing binaries should review the repository's `LICENSE`, dependency licenses and the exact linking and distribution model applicable to their use.

Upgrade cost extends beyond fetching a new tag. Native libraries must remain compatible, Go tooling is pinned to a specific patch release, and protocol releases may alter assumptions outside an application that merely calls the RPC endpoint. The repository includes `scripts/`, packaging targets and several service-related directories, but the truncated README does not provide a complete rolling-upgrade or rollback procedure.

Harmony against a conventional single-repository node

A useful alternative is adopting an established Ethereum-oriented node codebase such as go-ethereum rather than operating Harmony's protocol implementation. Harmony depends on `github.com/ethereum/go-ethereum v1.13.4` in `go.mod` and has an `eth/` area, so the relationship is concrete. The practical difference is not that one repository contains more blockchain code. It is that Harmony's codebase adds its own node, shard, consensus, staking, BLS and local-network machinery around Ethereum-derived components.

For an engineer validating Harmony-specific sharding, PBFT, staking or node behavior, that added protocol surface is the reason to use this repository. An Ethereum-oriented codebase would be the wrong choice when the requirement is Harmony consensus behavior. Conversely, Harmony is the more demanding option when the actual need is familiar Ethereum execution behavior without Harmony's shard and staking model.

The trade-off appears in maintenance and diagnosis. A Harmony checkout requires three sibling repositories in the documented layout, plus native build dependencies and Harmony-specific release decisions. A caller that needs only an RPC client can remain outside both node implementations and use the supplied API endpoint. The decision should therefore follow the protocol boundary, not a general preference for Go or for blockchain software.

Editorial conclusion

Protocol researchers, node developers and contributors who need to inspect Harmony's sharded node implementation have a concrete starting point in this repository. Operators seeking a packaged single-command node deployment, and developers who cannot provide CGO, GMP, OpenSSL, MCL and BLS dependencies, should look elsewhere. Before adoption, verify the exact native libraries produced by the build, confirm that the expected binaries start on the target architecture, and review the release corresponding to any mainnet deployment.

Frequently asked questions

Official sources

1. harmony-one/harmony on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases