A project by the HOPR Association
HOPR is a privacy-preserving messaging protocol which enables the creation of a secure communication network via relay nodes powered by economic incentives using digital tokens.
- Table of Contents
- About
- Install
- Usage
- Testnet accessibility
- Migrating between releases
- Develop
- Local cluster
- Test
- Contact
- License
The HOPR project produces multiple artifacts that allow running, maintaining and modiyfing the HOPR node. The most relevant components for production use cases are:
- hopr-lib
- A fully self-contained referential implementation of the HOPR protocol over a libp2p based connection mechanism that can be incroporated into another projects as a transport layer.
- hoprd
- Daemon application providing a higher level interface for creating a HOPR protocol compliant node that can use a dedicated REST API.
- hoprd-api-schema
- Utility to generate the OpenAPI spec for the
hoprdserved REST API.
- Utility to generate the OpenAPI spec for the
- hoprd-cfg
- Utility for configuration management of the
hoprd
- Utility for configuration management of the
- hopli
- Utility designed to simplify and unify the management of on-chain and identity related tasks.
Unless stated otherwise, the following sections only apply to hoprd.
For production purposes always run the latest stable release.
Multiple options for installation exist, the preferred choice for any production system should be to use the container image (e.g. using docker).
All releases and associated changelogs are located in the official releases section of the hoprnet repository.
The following instructions show how any $RELEASE may be installed, to select the release, override the $RELEASE variable, e.g.:
export RELEASE=latestto track the latest changes on the repository'smasterbranchexport RELEASE=saint-louisto track the latest changes on the repository'srelease/saint-louisbranch (2.1.X)export RELEASE=<version>to get a specific<version>
Container image has the format
europe-west3-docker.pkg.dev/hoprassociation/docker-images/$PROJECT:$RELEASE.
where:
$PROJECTcan be eitherhopliorhoprd
Pull the container image with docker:
$ docker pull europe-west3-docker.pkg.dev/hoprassociation/docker-images/hoprd:saint-louisIt is recommended to setup an alias hoprd for the docker command invocation.
Install via Nix package manager
WARNING: This setup should only be used for development or advanced usage without any further support.
Clone and initialize the hoprnet repository:
$ git clone https://github.com/hoprnet/hoprnet
$ cd hoprnetBuild and install the hoprd binary, e.g. on a UNIX platform:
$ nix build
$ sudo cp result/bin/* /usr/local/bin/hoprd provides various command-line switches to configure its behaviour. For reference these are documented here as well:
$ hoprd --help
HOPR node executable.
Usage: hoprd [OPTIONS]
Options:
--network <NETWORK>
ID of the network the node will attempt to connect to [env: HOPRD_NETWORK=]
--identity <IDENTITY>
The path to the identity file [env: HOPRD_IDENTITY=]
--data <DATA>
Specifies the directory to hold all the data [env: HOPRD_DATA=]
--host <HOST>
Host to listen on for P2P connections [env: HOPRD_HOST=]
--announce...
Announce the node on chain with a public address [env: HOPRD_ANNOUNCE=]
--api...
Expose the API on localhost:3001 [env: HOPRD_API=]
--apiHost <HOST>
Set host IP to which the API server will bind [env: HOPRD_API_HOST=]
--apiPort <PORT>
Set port to which the API server will bind [env: HOPRD_API_PORT=]
--apiToken <TOKEN>
A REST API token and for user authentication [env: HOPRD_API_TOKEN=]
--password <PASSWORD>
A password to encrypt your keys [env: HOPRD_PASSWORD=]
--disableUnrealizedBalanceCheck...
Disables checking of unrealized balance before validating unacknowledged tickets. [env: HOPRD_DISABLE_UNREALIZED_BALANCE_CHECK=]
--maxBlockRange <MAX_BLOCK_RANGE>
Maximum number of blocks that can be fetched in a batch request from the RPC provider. [env: HOPRD_MAX_BLOCK_RANGE=]
--maxRequestsPerSec <MAX_RPC_REQUESTS_PER_SEC>
Maximum number of RPC requestes that can be performed per second. [env: HOPRD_MAX_RPC_REQUESTS_PER_SEC=]
--provider <PROVIDER>
A custom RPC provider to be used for the node to connect to blockchain [env: HOPRD_PROVIDER=]
--init...
initialize a database if it doesn't already exist [env: HOPRD_INIT=]
--forceInit...
initialize a database, even if it already exists [env: HOPRD_FORCE_INIT=]
--inbox-capacity <INBOX_CAPACITY>
Set maximum capacity of the HOPRd inbox [env: HOPRD_INBOX_CAPACITY=]
--heartbeatInterval <MILLISECONDS>
Interval in milliseconds in which the availability of other nodes get measured [env: HOPRD_HEARTBEAT_INTERVAL=]
--heartbeatThreshold <MILLISECONDS>
Timeframe in milliseconds after which a heartbeat to another peer is performed, if it hasn't been seen since [env: HOPRD_HEARTBEAT_THRESHOLD=]
--heartbeatVariance <MILLISECONDS>
Upper bound for variance applied to heartbeat interval in milliseconds [env: HOPRD_HEARTBEAT_VARIANCE=]
--networkQualityThreshold <THRESHOLD>
Minimum quality of a peer connection to be considered usable [env: HOPRD_NETWORK_QUALITY_THRESHOLD=]
--configurationFilePath <CONFIG_FILE_PATH>
Path to a file containing the entire HOPRd configuration [env: HOPRD_CONFIGURATION_FILE_PATH=]
--safeTransactionServiceProvider <HOPRD_SAFE_TX_SERVICE_PROVIDER>
Base URL for safe transaction service [env: HOPRD_SAFE_TRANSACTION_SERVICE_PROVIDER=]
--safeAddress <HOPRD_SAFE_ADDR>
Address of Safe that safeguards tokens [env: HOPRD_SAFE_ADDRESS=]
--moduleAddress <HOPRD_MODULE_ADDR>
Address of the node mangement module [env: HOPRD_MODULE_ADDRESS=]
--protocolConfig <HOPRD_PROTOCOL_CONFIG_PATH>
Path to the protocol-config.json file [env: HOPRD_PROTOCOL_CONFIG_PATH=]
--dryRun
DEPRECATED [env: HOPRD_DRY_RUN=]
--healthCheck
DEPRECATED
--healthCheckHost <HEALTH_CHECK_HOST>
DEPRECATED
--healthCheckPort <HEALTH_CHECK_PORT>
DEPRECATED
--defaultStrategy <DEFAULT_STRATEGY>
DEPRECATED [env: HOPRD_DEFAULT_STRATEGY=] [possible values: promiscuous, aggregating, auto_redeeming, auto_funding, closure_finalizer, multi, passive]
--maxAutoChannels <MAX_AUTO_CHANNELS>
DEPRECATED [env: HOPRD_MAX_AUTO_CHANNELS=]
--disableTicketAutoRedeem...
DEPRECATED [env: HOPRD_DISABLE_AUTO_REDEEEM_TICKETS=]
-h, --help
Print help
-V, --version
Print versionRunning the node without any command-line argument might not work depending on the installation method used. Some command line arguments are required.
A basic reasonable setup is that uses a custom identity and enabels a REST API of the hoprd could look like:
hoprd --identity /app/hoprd-db/.hopr-identity --password switzerland --init --announce --host "0.0.0.0:9091" --apiToken <MY_TOKEN> --network doufurHere is a short breakdown of each argument.
hoprd
# store your node identity information in the persisted database folder
--identity /app/hoprd-db/.hopr-identity
# set the encryption password for your identity
--password switzerland
# initialize the database and identity if not present
--init
# announce the node to other nodes in the network and act as relay if publicly reachable
--announce
# set IP and port of the P2P API to the container's external IP so it can be reached on your host
--host "0.0.0.0:9091"
# specify password for accessing REST API
--apiToken <MY_TOKEN>
# an network is defined as a chain plus a number of deployed smart contract addresses to use on that chain
--network doufurSpecial care needs to given to the network argument, which defines the specific network hoprd node should join. Only nodes within the same network can communicate using the HOPR protocol.
An optional docker compose setup can be used to run the above containerized hoprd along with extension to observe the node's metrics using Prometheus + Grafana dashboard:
docker compose --file scripts/compose/docker-compose.yml up -dCopy the scripts/compose/default.env to scripts/compose/.env and change the variables as desired.
The composite setup will publish multiple additional services alongside the hoprd:
- Admin UI at
localhost:3000 - Grafana with
hoprddashboards atlocalhost:3030(default user:adminand passhopr)
To participate in a public network the node must be eligible. See Network Registry for details.
Node eligibility is not required in a local development cluster (see Develop section below).
There is NO backward compatibility between releases.
We attempt to provide instructions on how to migrate your tokens between releases.
- Set your automatic channel strategy to
passive. - Redeem all unredeemed tickets.
- Close all open payment channels.
- Once all payment channels have closed, withdraw your funds to an external wallet.
- Run
infoand take note of the network name. - Once funds are confirmed to exist in a different wallet, backup
.hopr-identityfolder. - Launch new
HOPRdinstance using latest release, observe the account address. - Only transfer funds to new
HOPRdinstance ifHOPRdoperates on the same network as last release, you can compare the two networks usinginfo.
Either setup nix and flake to use the nix environment, or install Rust toolchain from the rust-toolchain.toml, as well as foundry-rs binaries (forge, anvil).
Install `nix`` from the official website at https://nix.dev/install-nix.html.
Create a nix configuration file at ~/.config/nix/nix.conf with the following content:
experimental-features = nix-command flakesInstall the nix-direnv package to introduce the direnv:
$ nix-env -i nix-direnvAppend the following line to the shell rc file (depending on the shell used it can be ~\.zshrc, ~\.bashrc, ~\.cshrc, etc.). Modify the <shell> variable inside the below command with the currently used (zsh, bash, csh, etc.):
$ eval "$(direnv hook <shell>)"From within the hoprnet repository's directory, execute the following command.
$ direnv allow .We provide a couple of packages, apps and shells to make building and development easier, to get the full list execute:. You may get the full list like so:
$ nix flake showAll nix, rust, solidity and python code can be automatically formatted:
nix fmtThese formatters are also automatically run as a Git pre-commit check.
All linters can be executed via a Nix flake helper app:
nix run .#lintThis will in particular run clippy for the entire Rust codebase.
Running one node in test mode, with safe and module attached (in an anvil-localhost network)
# clean up, e.g.
# make kill-anvil
# make clean
# build deps and HOPRd code
make -j deps && make -j build
# starting network
make run-anvil args="-p"
# update protocol-config
scripts/update-protocol-config.sh -n anvil-localhost
# create identity files
make create-local-identity id_count=1
# create a safe and a node management module instance,
# and passing the created safe and module as argument to
# run a test node local (separate terminal)
# It also register the created pairs in network registry, and
# approve tokens for channels to move token.
# fund safe with 2k token and 1 native token
make run-local-with-safe id_file_path=/tmp
# or to restart a node and use the same id, safe and module
# run:
# make run-local id_path=$(find `pwd` -name ".identity-local*.id" | sort -r | head -n 1)
# fund all your nodes to get started
make fund-local-all id_dir=`pwd`
# start local HOPR admin in a container (and put into background)
make run-hopr-admin &Running one node in test mode, with safe and module attached (in dufour network)
# build deps and HOPRd code
make -j deps && make -j build
# Fill out the `ethereum/contract/.env` from the `ethereum/contract/example.env`
#
# ensure a private key with enough xDAI is set as PRIVATE_KEY
# This PRIVATE_KEY is the "admin_key" (i.e. owner of the created safe and node management module)
#
# Please use the deployer private key as DEPLOYER_PRIVATE_KEY
# The Ethereum address to the DEPLOYER_PRIVATE_KEY should be a "manager" of the network registry.
# Role can be checked in the explorer:
# ```
# echo "https://gnosisscan.io/address/$(jq '.networks.dufour.addresses.network_registry' ./ethereum/contracts/contracts-addresses.json)\#readContract"
# ```
source ./ethereum/contracts/.env
export HOPR_NETWORK="dufour"
export IDENTITY_PASSWORD="SOmeranDOmPassHere-DefiniteLyChangeThis!"
# create identity files
bash scripts/generate-identity.sh
# start local HOPR admin in a container (and put into background)
make run-hopr-admin &The best way to test with multiple HOPR nodes is by using a local cluster of interconnected nodes.
Tests both the Rust and Solidity code.
make testWe run a fair amount of automation using Github Actions. To ease development of these workflows one can use act to run workflows locally in a Docker environment.
E.g. running the build workflow:
$ act -j buildFor more information please refer to act's documentation.
When using the nix environment, the test environment preparation and activation is automatic.
Tests are using the pytest infrastructure.
If not using nix, setup the pytest environment:
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r tests/requirements.txtTo deactivate the activated testing environment if no longer needed:
deactivateWith the environment activated, execute the tests locally:
make smoke-test-fullGPL v3 © HOPR Association
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
![repo-ranger[bot] avatar](https://avatars.githubusercontent.com/in/11906?v=4 "repo-ranger[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent