Skip to content

BR-402: guardian quorum headroom check and alert unit; new-host provisioning script - #14

Merged
dendisuhubdy merged 1 commit into
mainfrom
feat/i32-quorum-headroom
Nov 18, 2026
Merged

dendisuhubdy merged 1 commit into
mainfrom
feat/i32-quorum-headroom

Conversation

@dendisuhubdy

Copy link
Copy Markdown
Member

Tracks randprotocol/monorepo#32

What is added

  • rand-bridge-audit --config <relayer config> --headroom [--min-spare 1]: reads the registered set from the Rand node and /v1/health from every guardian origin, and prints how many guardians are signing against the quorum, for releases and for mints, with the spare. Exits non-zero under --min-spare. Read-only.
  • /v1/health gains pq_key_sha256: the hash of the Dilithium2 public key the guardian co-signs with, so the mints line can count co-signers. Optional both ways: an older reader ignores it, an older guardian omits it and is listed as unknown, not counted.
  • daemons/mainnet/systemd/rand-bridge-headroom.{service,timer}: the check every five minutes on the relayer host, with OnFailure= for a notifier the operator supplies.
  • daemons/mainnet/provision-guardian.sh: run on a new host, it checks the binary's checksum and that the config is that guardian's, and writes binary, config, unit, an empty mode-600 secrets file (variable names only) and the data directory. It reads and writes no key, overwrites nothing that differs, contacts nothing, and does not start the service.
  • Runbook: docs/guardian-hosts.md, "Quorum headroom" and "Bringing a guardian up on its own host".

Files

  • daemons/src/headroom.rs (new), daemons/src/api.rs, daemons/src/bin/audit.rs, daemons/src/bin/guardian.rs, daemons/src/lib.rs
  • daemons/mainnet/provision-guardian.sh, daemons/mainnet/systemd/ (new)
  • daemons/tests/headroom.rs (5 tests), daemons/tests/provision_guardian_script.rs (3 tests)
  • docs/guardian-hosts.md, daemons/README.md

Tests

cargo test --release in daemons/: all test binaries pass, no failures. The script was run only under --root <tempdir>; the check only against loopback fakes.

Upgrade

  • Nothing changes for a running guardian or relayer until its binary is replaced; the new health field is additive.
  • Until the guardians run this build, the mints line under-counts (unknown keys are not counted): read it as a floor. The releases line is exact with today's guardians.
  • With six of eight running the check fails at the default --min-spare 1. That is the finding, not a fault of the check.

Left for the owner

  • Bringing guardians 7 and 8 up on their own hosts (or rotating the ECDSA and PQ sets together), ideally under other hosting accounts.
  • Installing the timer on the relayer host and choosing the notifier.

🤖 Generated with Claude Code

… lays a guardian down on a new host

rand-bridge-audit --headroom reads the registered guardian set from the
Rand node and /v1/health from every guardian origin, and says how many
guardians are signing against the quorum, for releases and for mints,
and how many could stop before signing stops. It exits non-zero under
--min-spare (default 1). A guardian counts when it answers as a
registered address and is not paused; one answering twice counts once.
For mints it counts only when its health names the PQ key registered at
its index; a build that does not report the key is listed as unknown and
not counted.

/v1/health gains pq_key_sha256, the hash of the Dilithium2 public key
the guardian co-signs with (the key is public on the chain). Optional in
both directions: an older reader ignores it, an older guardian omits it.

mainnet/systemd/rand-bridge-headroom.{service,timer} run the check
every five minutes on the relayer host; the notifier is the operator's.

mainnet/provision-guardian.sh, run on a new host, checks the binary's
checksum and that the config is that guardian's, and writes the binary,
config, unit, an empty secrets file (mode 600, names only) and the data
directory. It reads and writes no key, overwrites nothing that differs,
contacts nothing and does not start the service.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGaYNQ4cvFtg2UmokVgrAN
@codecov

codecov Bot commented Nov 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@dendisuhubdy
dendisuhubdy merged commit bb45d0d into main Nov 18, 2026
2 checks passed
@dendisuhubdy
dendisuhubdy deleted the feat/i32-quorum-headroom branch November 18, 2026 05:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant