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
• Develop
  • Nix environment setup
    • Nix flake outputs
    • Code Formatting
    • Code Linting
• Test
  • Github Actions CI
• Code Coverage
• Profiling & Instrumentation
  • Profiling Criterion benchmarks via flamegraph
    • Prerequisites
    • Profiling the benchmarking binaries
• Contact
• License

This repository contains the core HOPR protocol library and supporting crates.

1. 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.

The hoprd daemon (HOPR node with REST API) lives in the hoprd repository.

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 flakes

Install the nix-direnv package to introduce the direnv:

nix-env -i nix-direnv

Append 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. You may get the full list like so:

nix flake show

All nix, rust, solidity and python code can be automatically formatted:

nix fmt

These formatters are also automatically run as a Git pre-commit check.

All linters can be executed via a Nix flake helper app:

nix run .#check

This will in particular run clippy for the entire Rust codebase.

The workspace is built with --cfg tokio_unstable, configured centrally in .cargo/config.toml:

[build]
rustflags = ["--cfg", "tokio_unstable", "--check-cfg", "cfg(tokio_unstable)"]

This enables Tokio's unstable cooperative-scheduling APIs (tokio::task::coop), which hopr-utilities uses for improved, budget-aware yielding on the async hot paths (transport, session, mixer). A Tokio feature toggled by a downstream crate only takes effect if the tokio crate itself is compiled with the same cfg, so the flag is applied to the entire build graph — which is what propagates the improved yielding down into hopr-utilities. The paired --check-cfg keeps the workspace warning-free under -D warnings.

The Nix dev/CI shells set CARGO_BUILD_RUSTFLAGS themselves (for the linker), and Cargo lets that environment variable replace — not extend — the .cargo/config.toml value. So the flag is re-exported (appended to the existing rustflags) in each mkDevShell in flake.nix; the .cargo/config.toml entry is what covers a plain, non-Nix cargo build. If you export RUSTFLAGS/CARGO_BUILD_RUSTFLAGS yourself, re-add both flags, e.g.:

RUSTFLAGS="--cfg tokio_unstable --check-cfg cfg(tokio_unstable) -Clink-arg=-fuse-ld=lld" cargo bench --no-run -p hopr-crypto-packet

Run all tests: cargo test.

Run only unit tests: cargo test --lib

We run a fair amount of automation using Github Actions. Too see the full list of workflows checkout workflow docs

Coverage reports are generated using LLVM source-based instrumentation and uploaded to Codecov. See docs/coverage.md for workspace-wide and single-crate usage.

• perf installed on the host system
• flamegraph (install via e.g. cargo install flamegraph)

1. Perform a build of your chosen benchmark with --no-rosegment linker flag:

   RUSTFLAGS="--cfg tokio_unstable --check-cfg cfg(tokio_unstable) -Clink-arg=-fuse-ld=lld -Clink-arg=-Wl,--no-rosegment" cargo bench --no-run -p hopr-crypto-packet
   

   RUSTFLAGS replaces the .cargo/config.toml value, so the tokio_unstable flags are repeated here (see Build configuration).

   Use mold instead of lld if needed.

2. Find the built benchmarking binary and check if it contains debug symbols:

   readelf -S target/release/deps/packet_benches-ce70d68371e6d19a | grep debug
   

   The output of the above command should contain AT LEAST: .debug_line, .debug_info and .debug_loc

3. Run flamegraph on the benchmarking binary of a selected benchmark with a fixed profile time (e.g.: 30 seconds):

   flamegraph -- ./target/release/deps/packet_benches-ce70d68371e6d19a --bench --exact packet_sending_no_precomputation/0_hop_0_surbs --profile-time 30
   

4. The flamegraph.svg will be generated in the project root directory and can be opened in a browser.

• X
• Telegram
• Medium
• Reddit
• Email
• Discord
• Youtube

GPL v3 © HOPR Association