Harmony
General Documentation
https://docs.harmony.one
API Guide
http://api.hmny.io/
Requirements
Go 1.24.2
GMP and OpenSSL
On macOS:
brew install gmp
brew install openssl
sudo ln -sf /usr/local/opt/[email protected] /usr/local/opt/openssl
On Linux (Ubuntu):
sudo apt install libgmp-dev libssl-dev make gcc g++
On Linux (Cent OS / Amazon Linux 2):
sudo yum install glibc-static gmp-devel gmp-static openssl-libs openssl-static gcc-c++
Docker (for testing)
On macOS:
brew install --cask docker
open /Applications/Docker.app
On Linux, reference official documentation here.
Bash 4+
For macOS, you can reference this guide. For Linux, you can reference this guide.
On macOS, make sure you have the Xcode Command Line Tools installed. This includes essential tools like git, make, and other development utilities:
xcode-select --install
Setting Up MCL & BLS Libraries on macOS
The Harmony project depends on the MCL (multi-curve library) and BLS (Boneh-Lynn-Shacham) cryptographic libraries. These need to be installed and configured before building the project.
Clone and Build MCL & BLS Repositories
First, clone the MCL and BLS repositories:
git clone https://github.com/harmony-one/mcl.git
git clone https://github.com/harmony-one/bls.git
Update .zshrc for MCL and BLS Paths
To ensure the libraries are correctly located when building the project, you need to add the MCL and BLS library paths to your .zshrc file.
Add the following lines to your .zshrc (or .bash_profile for bash users):
# MCL & BLS paths for Harmony
export MCL_PATH=$GOPATH/src/github.com/harmony-one/mcl
export BLS_PATH=$GOPATH/src/github.com/harmony-one/bls
# Add library paths for MCL and BLS
export CGO_CFLAGS="-I$MCL_PATH/include -I$BLS_PATH/include -I/opt/homebrew/opt/[email protected]/include"
export CGO_LDFLAGS="-L$MCL_PATH/lib -L$BLS_PATH/lib -L/opt/homebrew/opt/[email protected]/lib"
export LD_LIBRARY_PATH=$MCL_PATH/lib:$BLS_PATH/lib:/opt/homebrew/opt/[email protected]/lib
export LIBRARY_PATH=$LD_LIBRARY_PATH
export DYLD_FALLBACK_LIBRARY_PATH=$LD_LIBRARY_PATH
Then, apply the changes by running:
source ~/.zshrc
Dev Environment
Most repos from harmony-one assume the GOPATH convention. More information here.
First Install
Clone and set up all of the repos with the following set of commands:
- Create the appropriate directories:
mkdir -p $(go env GOPATH)/src/github.com/harmony-one
cd $(go env GOPATH)/src/github.com/harmony-one
If you get ‘unknown command’ or something along those lines, make sure to install golang first.
- Clone this repo & dependent repos.
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
- Build the harmony binary & dependent libs
go mod tidy
make
Run bash scripts/install_build_tools.sh to ensure build tools are of correct versions.
If you get ‘missing go.sum entry for module providing package <package_name>’, run go mod tidy.
Dev Docker Image
Included in this repo is a Dockerfile that has a full harmony development environment and comes with emacs, vim, ag, tig, and other creature comforts. Most importantly, it already has the go environment with our C/C++ based library dependencies (libbls and mcl) set up correctly for you.
You can build the docker image for yourself with the following commands:
cd $(go env GOPATH)/src/github.com/harmony-one/harmony
make clean
docker build -t harmony .
If your build machine has an ARM-based chip, like Apple silicon (M1), the image is built for linux/arm64 by default. To build for x86_64, apply the --platform arg like so:
docker build --platform linux/amd64 -t harmony .
Learn more about the --platform arg and multi-CPU architecture support, here and here.
Then you can start your docker container with the following command:
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
Note that the harmony repo will be shared between your docker container and your host machine. However, everything else in the docker container will be ephemeral.
If you need to open another shell, just do:
docker exec -it harmony /bin/bash
Learn more about docker here.
Build
The make command should automatically build the Harmony binary & all dependent libs.
However, if you wish to bypass the Makefile, first export the build flags:
export CGO_CFLAGS="-I$GOPATH/src/github.com/harmony-one/bls/include -I$GOPATH/src/github.com/harmony-one/mcl/include -I/opt/homebrew/opt/[email protected]/include"
export CGO_LDFLAGS="-L$GOPATH/src/github.com/harmony-one/bls/lib -L/opt/homebrew/opt/[email protected]/lib"
export LD_LIBRARY_PATH=$GOPATH/src/github.com/harmony-one/bls/lib:$GOPATH/src/github.com/harmony-one/mcl/lib:/opt/homebrew/opt/[email protected]/lib
export LIBRARY_PATH=$LD_LIBRARY_PATH
export DYLD_FALLBACK_LIBRARY_PATH=$LD_LIBRARY_PATH
export GO111MODULE=on
Then you can build all executables with the following command:
bash ./scripts/go_executable_build.sh -S
Reference bash ./scripts/go_executable_build.sh -h for more build options
Debugging
One can start a local network (a.k.a localnet) with your current code using the following command:
make debug
This localnet has 2 shards, with 11 nodes on shard 0 (+1 explorer node) and 10 nodes on shard 0 (+1 explorer node).
The shard 0 endpoint will be on the explorer at http://localhost:9599. The shard 1 endpoint will be on the explorer at http://localhost:9598.
You can view the localnet configuration at /test/configs/local-resharding.txt. The fields for the config are (space-delimited & in order) ip, port, mode, bls_pub_key, and shard (optional).
One can force kill the local network with the following command:
make debug-kill
You can view all make commands with make help
Testing
To keep things consistent, we have a docker image to run all tests. These are the same tests ran on the pull request checks.
Note that all test Docker containers bind several ports to the host machine for your convenience. The ports are:
9500 - Shard 0 RPC for a validator9501 - Shard 1 RPC for a validator9599 - Shard 0 RPC for an explorer9598 - Shard 1 RPC for an explorer9799 - Shard 0 Rosetta (for an explorer)9798 - Shard 1 Rosetta (for an explorer)9899 - Shard 0 WS for an explorer9898 - Shard 1 WS for an explorer
This allows you to use curl, hmy CLI, postman, rosetta-cli, etc… on your host machine to play with or probe the localnet that was used for the test.
Go tests
To run this test, do:
make test-go
This test runs the go tests along with go lint, go fmt, go imports, go mod, and go generate checks.
RPC tests
To run this test, do:
make test-rpc
This test starts a localnet (within the Docker container), ensures it reaches a consensus, and runs a series of tests to ensure correct RPC behavior.
This test also acts as a preliminary integration test (more thorough tests are done on the testnets).
The tests ran by this command can be found here.
If you wish to debug further with the localnet after the tests are done, open a new shell and run:
make test-rpc-attach
This will open a shell in the docker container that is running the Node API tests.
Note that the docker container has the Harmony CLI on path,
therefore you can use that to debug if needed. For example, one could do hmy blockchain latest-headers to check
the current block height of localnet. Reference the documentation for the CLI here
for more details & commands.
Rosetta tests
To run this test, do:
make test-rosetta
This test starts a localnet (within the Docker container), ensures it reaches a consensus, and runs the Construction & Data API checks using the rosetta-cli.
This test also acts as a preliminary integration test (more thorough tests are done on the testnets).
The config for this test can be found here & here
Similar to the RPC tests, if you wish to debug further with the localnet after the tests are done, open a new shell and run:
make test-rosetta-attach
License
Harmony is licensed under GNU Lesser General Public License v3.0. See LICENSE file for the terms and conditions.
Harmony includes third-party open-source code. In general, a source subtree with a LICENSE or COPYRIGHT file is from a third party, and our modifications thereto are licensed under the same third-party open source license.
Also please see our Fiduciary License Agreement if you are
contributing to the project. By your submission of your contribution to us, you
and we mutually agree to the terms and conditions of the agreement.
Contributing To Harmony
See CONTRIBUTING for details.
Development Status
Finished Features
- Fully sharded network with beacon chain and shard chains
- Sharded P2P network and P2P gossiping
- FBFT (Fast Byzantine Fault Tolerance) Consensus with BLS multi-signature
- Consensus view-change protocol
- Account model and support for Solidity
- Cross-shard transaction
- VRF (Verifiable Random Function) and VDF (Verifiable Delay Function)
- Cross-links
- EPoS staking mechanism
- Kademlia routing
Planned Features
- Resharding
- Integration with WASM
- Fast state synchronization
- Auditable privacy asset using ZK proof
评论