<p align="center"> <a href="https://hoprnet.org" target="_blank" rel="noopener noreferrer"> <img align="middle" width="100" src="https://github.com/hoprnet/hopr-assets/blob/master/v1/logo/hopr_logo_padded.png?raw=true" alt="HOPR Logo"> </a>  <h3 align="center">HOPR</h3> <p align="center"> <code>A project by the HOPR Association</code> </p> <p align="center"> 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. </p> </p> <p align="center"> <a href="https://codecov.io/gh/hoprnet/hoprnet"> <img src="https://codecov.io/gh/hoprnet/hoprnet/branch/master/graph/badge.svg" alt="codecov"> </a> </p>

Table of Contents
About
Install
Usage
Testnet accessibility
Migrating between releases
Develop
- Nix environment setup
- Building a Docker image
Local cluster
Test
- Github Actions CI
- End-to-End Testing
  - Running Tests Locally
    - Test execution
Profiling & Instrumentation
Contact
License

About

The HOPR project produces multiple artifacts that allow running, maintaining and modifying 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 incorporated into other 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 hoprd served REST API.
hoprd-cfg
- Utility for configuration management of the hoprd

Unless stated otherwise, the following sections only apply to hoprd.

Install

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.

Install via Docker

Checkout DockerHub for specific version tag or use a custom tag:

I want the latest code from active development → latest or latest-main
I want the latest stable release from active development → release-main
I want the latest code from the LTS branch → latest-lts
I want the latest stable release from the LTS branch → release-lts
I want what is currently running in production → stable

docker pull hoprnet/hoprd:stable

It is recommended to setup an alias hoprd for the docker command invocation.

Install via [Nix package manager][1]

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 hoprnet

Build and install the hoprd binary, e.g. on a UNIX platform:

nix build
sudo cp result/bin/* /usr/local/bin/

To build and access man pages for hoprd:

# Build man page for hoprd
nix build .#hoprd-man
man ./result/share/man/man1/hoprd.1.gz

# Or install them system-wide
sudo cp -r result/share/man/man1/* /usr/local/share/man/man1/

Install via linux package manager

Linux packages are available at every github release, download the latest package from https://github.com/hoprnet/hoprnet/releases/latest To install on specific distribution, see detailed information

Usage

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:
      --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=]
      --blokliUrl <URL>
          URL for Blokli provider to be used for the node to connect to blockchain [env: HOPRD_BLOKLI_URL=]
      --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=]
      --probeRecheckThreshold <SECONDS>
          Timeframe in seconds after which it is reasonable to recheck the nearest neighbor [env: HOPRD_PROBE_RECHECK_THRESHOLD=]
      --configurationFilePath <CONFIG_FILE_PATH>
          Path to a file containing the entire HOPRd configuration [env: HOPRD_CONFIGURATION_FILE_PATH=]
      --safeAddress <HOPRD_SAFE_ADDR>
          Address of Safe that safeguards tokens [env: HOPRD_SAFE_ADDRESS=]
      --moduleAddress <HOPRD_MODULE_ADDR>
          Address of the node management module [env: HOPRD_MODULE_ADDRESS=]
  -h, --help
          Print help
  -V, --version
          Print version

Environment variables

On top of the default configuration options generated for the command line, the following environment variables can be used in order to tweak the node functionality:

ENV_WORKER_THREADS - the number of environment worker threads for the tokio executor
HOPRD_LOG_FORMAT - override for the default stdout log formatter (follows tracing formatting options)
HOPRD_USE_OPENTELEMETRY - enable the OpenTelemetry output for this node
HOPRD_OTEL_SIGNALS - comma-separated OTLP signals to export when OpenTelemetry is enabled (traces, logs, metrics), defaults to traces
HOPR_INTERNAL_CHAIN_DISCOVERY_CHANNEL_CAPACITY - the maximum capacity of the channel for chain generated discovery signals for the p2p transport
HOPR_INTERNAL_ACKED_TICKET_CHANNEL_CAPACITY - the maximum capacity of the acknowledged ticket processing queue
HOPR_INTERNAL_LIBP2P_MAX_CONCURRENTLY_DIALED_PEER_COUNT - the maximum number of concurrently dialed peers in libp2p
HOPR_INTERNAL_LIBP2P_MAX_NEGOTIATING_INBOUND_STREAM_COUNT - the maximum number of negotiating inbound streams
HOPR_INTERNAL_LIBP2P_SWARM_IDLE_TIMEOUT - timeout for all idle libp2p swarm connections in seconds
HOPR_INTERNAL_DB_PEERS_PERSISTENCE_AFTER_RESTART_IN_SECONDS - cutoff duration from now to not retain the peers with older records in the peers database (e.g. after a restart)
HOPR_INTERNAL_MANUAL_PING_CHANNEL_CAPACITY - the maximum capacity of awaiting manual ping queue
HOPR_INTERNAL_MIXER_CAPACITY - capacity of the mixer buffer
HOPR_INTERNAL_MIXER_MINIMUM_DELAY_IN_MS - the minimum mixer delay in milliseconds
HOPR_INTERNAL_MIXER_DELAY_RANGE_IN_MS - the maximum range of the mixer delay from the minimum value in milliseconds
HOPR_INTERNAL_PROTOCOL_BIDIRECTIONAL_CHANNEL_CAPACITY - the maximum capacity of HOPR messages processed by the node
HOPR_INTERNAL_SESSION_CTL_CHANNEL_CAPACITY - the maximum capacity of the session control channel
HOPR_INTERNAL_SESSION_INCOMING_CAPACITY - the maximum capacity of the queue storing unprocessed incoming and outgoing messages inside a session
HOPR_INTERNAL_SESSION_BALANCER_LEVEL_CAPACITY - the maximum capacity of the session balancer
HOPR_INTERNAL_RAW_SOCKET_LIKE_CHANNEL_CAPACITY - the maximum capacity of the raw socket-like bidirectional API interface
HOPR_INTERNAL_IN_PACKET_PIPELINE_CONCURRENCY - the maximum number of incoming packets to process concurrently (default: 8 × CPU cores, 0 = no limit)
HOPR_INTERNAL_OUT_PACKET_PIPELINE_CONCURRENCY - th

Hoprnet

Install / Use

README

Table of Contents