Skip to content

BRG-1: guardian all-token window and large-transfer delay; audit of the chain-side caps - #10

Merged
dendisuhubdy merged 3 commits into
mainfrom
feat/i4-loss-bounds
Nov 18, 2026
Merged

dendisuhubdy merged 3 commits into
mainfrom
feat/i4-loss-bounds

Conversation

@dendisuhubdy

Copy link
Copy Markdown
Member

Tracks randprotocol/monorepo#4

What main already has

  • Guardian: a per-transfer cap (the transfer is withheld until an operator releases it), a rolling per-token window per direction (deferred until there is room), a manual global pause (--pause-signing). All under [guardian.limits].
  • Endpoints (EVM, Tron, Solana): per-transfer and daily release caps per token, and a pause. Rand: a daily mint cap per backing.

What was missing, and is added here

  • A bound across tokens. per_window_total caps what a guardian signs across all tokens together, per direction, in the rolling window. Without it the bound is the per-token cap times the number of listed tokens.
  • A delay. delay_above + delay_secs: a transfer above the threshold is signed only delay_secs after the guardian first read it, on its own clock. The first-read time is kept under the guardian's seal (data_dir/delayed/); a record that is backdated, unsealed, from the future or unreadable starts the wait again. A delayed transfer holds back nothing else and is listed with the deferred ones in /v1/health.
  • A check that the chain-side caps are set. rand-bridge-audit --config <file> --limits reads every endpoint's release caps per approved backing and Rand's daily mint cap, prints them in one unit, and exits non-zero when an enabled backing has an unlimited cap (0) or a bound cannot be read. Read-only.

Not added: an automatic global pause. Commit 61757be removed it on purpose (with six of six guardians needed, one guardian's automatic pause stops every transfer); the manual pause stays the only global brake.

Files

  • daemons/src/limits.rs, daemons/src/guardian.rs: the two bounds.
  • daemons/src/bin/guardian.rs: startup lines saying which of the two are on.
  • daemons/src/bin/audit.rs: --limits.
  • daemons/tests/limits.rs (+10 tests), daemons/tests/audit_bin.rs (+4 tests); three other test files only gain the new struct fields.
  • daemons/README.md, daemons/config.example.toml, docs/architecture.md §1.1.

Tests

cargo test --release in daemons/: every test binary passes (limits 18, audit_bin 21; no failures anywhere).

Upgrade and rollback

  • Both bounds are opt-in. A config without the new keys behaves exactly as before; the mainnet configs in this repository are not changed.
  • A build older than this one refuses a config that carries the new keys ([guardian.limits] denies unknown fields). To roll back, remove the keys first.
  • Deferred records written for a delay carry an extra delay field that an older build ignores.

Left for the owner

🤖 Generated with Claude Code

…rdian, and an audit of the chain-side caps

Main already has a per-transfer cap (withheld for an operator), a rolling
per-token window (deferred), a manual signing pause, and the endpoints'
release caps and pause. It had no delay anywhere, no bound across tokens,
and no check that the chain-side caps are set. This adds the three.

[guardian.limits] gains two optional bounds, off unless configured:

- per_window_total: what the guardian signs across all tokens together,
  per direction, in the same rolling window. A transfer over it is
  deferred like one over its token's window.
- delay_above + delay_secs: a transfer above the threshold is signed only
  delay_secs after the guardian first read it, on its own clock. The
  first-read time is kept in delayed/<chain>/<sequence>.json under the
  guardian's seal; a record that is backdated, unsealed, from the future
  or unreadable starts the wait again. A delayed transfer is listed with
  the deferred ones and holds back no other transfer; if its window is
  full once the delay has passed it queues like any other.

rand-bridge-audit --limits reads each endpoint's per-transfer and daily
release cap per approved backing and Rand's daily mint cap, prints them
in attested units next to the config's [guardian.limits], and exits
non-zero when an enabled backing has an unlimited cap or a bound cannot
be read.

A config without the new keys behaves as before. A build older than this
one refuses a config that has them (the section denies unknown fields),
so a rollback removes the keys first.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@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 and others added 2 commits November 18, 2026 13:15
rand-bridge-audit keeps both --limits and --headroom.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGaYNQ4cvFtg2UmokVgrAN
@dendisuhubdy
dendisuhubdy merged commit 23491df into main Nov 18, 2026
1 check passed
@dendisuhubdy
dendisuhubdy deleted the feat/i4-loss-bounds branch November 18, 2026 07:00
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