0 Fork 0

Files

T

Passphrase-based peer rendezvous for iroh-gossip swarms over the public
Mainline DHT. Two nodes that share a passphrase + application salt find
each other and join the same gossip topic — no bootstrap server, no
prior knowledge of peer addresses.

The algorithm is a clock-free variant of HyParView-style partition
healing on BEP 44 mutable items, with K-sharded slots, logical aging
with random-tie eviction, vouching of up to V neighbors at age 1, and
a two-layer AEAD record envelope. Full spec in PROTOCOL.md.

Ships with:

* 119 tests (unit / property / integration / doctest) all green
* 100% mutation-testing catch rate (cargo-mutants)
* cargo-fuzz harnesses for the parse surface
* Kani proofs of no-UB / no-panic on crypto::epoch_of and
  wire::decode_entries across their full symbolic input spaces
* Stateright distributed-system model: safety invariants S1 + S2
  proved exhaustively for N ≤ 6, K ≤ 3; liveness witness under weak
  fairness
* Miri green on the synchronous modules
* cargo-deny + cargo-audit clean
* criterion benches
* Full-matrix CI (Linux + macOS + Windows × stable + MSRV 1.93.0)
* Dedicated nightly lane for Miri / mutation / fuzz / Kani / Stateright

Pinned iroh 0.98.x. License MIT.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 22:52:46 -06:00

3.2 KiB

Raw Blame History

Contributing to iroh-gossip-rendezvous

Bug reports, feature requests, and pull requests welcome.

Developer setup

# Clone the repo.
git clone https://github.com/swaits/iroh-gossip-rendezvous
cd iroh-gossip-rendezvous

# Install the dev toolchain. Most tools are lightweight; Kani is the
# heaviest and only needed if you're running formal proofs.
cargo install --locked \
    cargo-nextest \
    cargo-llvm-cov \
    cargo-deny \
    cargo-audit \
    cargo-semver-checks \
    cargo-mutants \
    cargo-fuzz

# Optional: Kani bounded model checker (needed only for `just kani`).
cargo install --locked kani-verifier
cargo kani setup  # one-time; downloads the solver toolchain.

# Optional: just (task runner). Most distros package it; via cargo:
cargo install just

# Sanity check.
just check

MSRV is 1.93.0. Newer Rust features are not allowed in the main crate; they are allowed in dev-dependencies and examples only.

Local testing

Every CI lane is replayable locally via just:

Task	What it runs
`just check`	fmt check + clippy + nextest + doctests (the fast CI lane)
`just test`	nextest + doctests only
`just fmt`	apply rustfmt
`just clippy`	lint only
`just deny`	cargo-deny (licenses, advisories, bans)
`just audit`	cargo-audit (RUSTSEC)
`just semver`	cargo-semver-checks vs last published
`just coverage`	cargo-llvm-cov HTML report
`just mutants`	cargo-mutants (30–90 min)
`just fuzz TARGET=x`	60s fuzz run (nightly toolchain required)
`just miri`	cargo-miri on sync modules (nightly)
`just kani`	Kani proofs (`kani` feature)
`just model-bfs`	Stateright BFS N=4, K=3
`just model-random`	Stateright random N=20, K=3, 10⁷ steps
`just bench`	criterion (not a release gate)
`just docs`	open rustdoc locally
`just all`	everything, in order

Before you open a PR

just check must pass locally.
Add tests for new behavior. Aim for ≥90% coverage on the module you touched; crate-wide minimum is 85%.
If you change the wire format, the protocol spec, or public API, update PROTOCOL.md / CHANGELOG.md / doctests as appropriate.
If you touch the algorithmic core (keys, wire, crypto, merge, protocol), re-run just mutants and just kani locally.
Breaking API changes require cargo-semver-checks to flag them and a major/minor version bump depending on the semver rules.

Where things live

See ARCHITECTURE.md for the module map.

Algorithm spec: PROTOCOL.md.
Security posture: SECURITY.md.
API docs: run just docs or visit https://docs.rs/iroh-gossip-rendezvous.

Style

rustfmt with default config; clippy pedantic + nursery with the module-level allows documented in Cargo.toml's [lints.clippy] block.
unwrap_used, expect_used, panic denied in non-test code. If you need one, justify it with a SAFETY comment and #[allow(...)].
Keep async code in protocol.rs / rendezvous.rs / gossip_glue.rs. Algorithmic core (keys, wire, crypto, merge) must stay pure — Miri and Kani both want sync code.

License

By contributing, you agree that your contributions will be licensed under the MIT license.

3.2 KiB Raw Blame History Unescape Escape