Community validation runbook

Test an `hnsd` bootstrap seed update.

Bootstrap seeds help a new hnsd installation find its first Handshake peers. This guide gives contributors a repeatable way to check a proposed seed-list change and leave evidence that maintainers can use in a pull-request review.

The most valuable independent test

Run the candidate from a different country, ISP, hosting provider, or network. Automated checks can prove that the code builds; only distributed community testing can show that the replacement peers are broadly reachable.

Purpose

What are we validating?

Build integrity

The candidate branch compiles and its unit tests pass without local source changes.

Peer reachability

A useful share of the proposed peers accepts Handshake P2P connections on TCP port 44806.

Bootstrap behavior

hnsd starts with its built-in peers, connects, and begins advancing headers without a manually supplied seed.

Network diversity

The list does not depend too heavily on one operator, address range, provider, or geographic region.

Choose a test

Minimum or full validation.

Recommended

Runtime smoke test

Best when CI is already green. Build the candidate, start hnsd on safe local ports, and confirm that it finds peers and advances headers. Usually 10–15 minutes.

Additional evidence

Reachability survey

Check each proposed IP from your network and report how many accept TCP/44806. A failed individual peer is not automatically a failed proposal.

Procedure

Run the candidate.

Download the pull request

Replace 134 with the pull-request number you are testing.

git clone https://github.com/handshake-org/hnsd.git
cd hnsd
git fetch origin pull/134/head:validation-candidate
git switch validation-candidate

Install dependencies and build

macOS

brew install automake autoconf libtool unbound
./autogen.sh
./configure --with-unbound="$(brew --prefix unbound)"
make
./test_hnsd

Ubuntu or Debian

sudo apt update
sudo apt install -y git automake autoconf libtool \
  libunbound-dev build-essential
./autogen.sh
./configure
make
./test_hnsd

Expected: the build completes and ./test_hnsd passes.

Start hnsd with only its built-in seeds

These high local DNS ports avoid changing system DNS settings or requiring root access. Do not add the -s option: the point is to exercise the candidate seed list.

mkdir -p /tmp/hnsd-seed-validation
./hnsd -t -x /tmp/hnsd-seed-validation \
  -n 127.0.0.1:15369 \
  -r 127.0.0.1:15368

Let it run for a few minutes. A pass means hnsd loads its checkpoint, connects to peers, and begins receiving or advancing headers. A complete chain sync is unnecessary. Stop it with Ctrl+C.

Optionally count reachable peers

grep -Eo '([0-9]3\.)3[0-9]3' src/seeds.h |
sort -u |
while IFS= read -r ip; do
  if nc -z -w 3 "$ip" 44806; then
    echo "REACHABLE $ip"
  else
    echo "UNREACHABLE $ip"
  fi
done

Report the count and your approximate region. Do not publish your home IP address. Results vary by firewall, ISP, geography, and time.

Decision guide

What counts as a pass?

Pass

The candidate builds without local source patches.
Unit tests pass.
hnsd finds at least one peer and advances headers.
The seed set retains reasonable operator and network diversity.

Investigate

The branch needs a source edit to compile.
hnsd remains without peers after several minutes.
Most seeds are unreachable from multiple independent networks.
The proposed list is concentrated under one operator or address range.

Evidence

Leave a useful review report.

Paste this into the pull request and replace the bracketed fields:

Tested this hnsd seed update from [country/region] on [operating system].

- Candidate commit: [short commit SHA]
- Build: passed / failed
- Unit tests: passed / failed
- Reachable seeds: [X/Y, if checked]
- Connected using built-in seeds: yes / no
- Began advancing headers: yes / no
- Local source changes required: none / [describe]

Result: LGTM / needs investigation
Notes: [errors, timing, or other observations]

Maintainers can combine this report with CI results, the source diff, and reports from other regions. Community testing supplies evidence; repository maintainers still make the final merge and seed-policy decision.