From c4577c629db1010121d4ec722c9230383ea629a1 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:15:53 +0800 Subject: [PATCH 1/6] BR-1001: withdrawFees takes the reentrancy lock, and the comment says what the lock covers A fee withdrawal paid through _push with no nonReentrant, so a token's callback could enter lock and release from it, against the contract's own comment. withdrawFees is now onlyAdmin nonReentrant; three forge tests drive a re-entering token (into lock, release and a nested withdrawFees). Source and tests only: the deployed endpoints' bytecode is unchanged. Co-Authored-By: Claude Fable 5.2 --- evm/src/RandBridgeBase.sol | 19 ++++--- evm/src/interfaces/IRandBridge.sol | 2 +- evm/test/RandBridge.t.sol | 90 ++++++++++++++++++++++++++++++ 3 files changed, 103 insertions(+), 8 deletions(-) diff --git a/evm/src/RandBridgeBase.sol b/evm/src/RandBridgeBase.sol index 62596b2..f2cb33f 100644 --- a/evm/src/RandBridgeBase.sol +++ b/evm/src/RandBridgeBase.sol @@ -32,9 +32,12 @@ interface IERC20Metadata { /// digest is marked consumed and custody/window counters are updated /// *before* any token call, so a token with a callback in its transfer /// hook cannot re-enter into a second release of the same attestation. -/// `lock` and `release` also share a reentrancy lock (`nonReentrant`), so -/// a token call can re-enter neither; that holds even if a later change -/// breaks the ordering or the balance-delta checks. +/// `lock`, `release` and `withdrawFees` — the three functions that call a +/// token to move it — also share a reentrancy lock (`nonReentrant`), so a +/// token call made by any of them can re-enter none of them; that holds +/// even if a later change breaks the ordering or the balance-delta checks. +/// The lock covers nothing else: the admin and pauser functions and +/// `submitGuardianSetUpgrade` move no tokens and are not guarded by it. abstract contract RandBridgeBase is IRandBridge { using SafeTransfer for address; @@ -458,8 +461,8 @@ abstract contract RandBridgeBase is IRandBridge { // roles and configuration // ------------------------------------------------------------------ - /// One `lock` or `release` at a time: a token whose transfer calls back - /// into the bridge is refused `ReentrantCall`. + /// One `lock`, `release` or `withdrawFees` at a time: a token whose + /// transfer calls back into any of the three is refused `ReentrantCall`. modifier nonReentrant() { if (_entered == 2) revert ReentrantCall(); _entered = 2; @@ -532,8 +535,10 @@ abstract contract RandBridgeBase is IRandBridge { /// Pays accrued protocol fees out to `to`. Bounded by `accruedFees`, /// so it can never reach custody; not gated by the pause, which - /// protects custody and has no bearing on fees already earned. - function withdrawFees(address token, address to, uint256 amount) external override onlyAdmin { + /// protects custody and has no bearing on fees already earned. Shares + /// the reentrancy lock with `lock` and `release`, since it calls the + /// token through the same `_push`. + function withdrawFees(address token, address to, uint256 amount) external override onlyAdmin nonReentrant { if (to == address(0) || to == address(this)) revert ZeroAddress(); if (amount > accruedFees[token]) revert InsufficientFees(); accruedFees[token] -= amount; diff --git a/evm/src/interfaces/IRandBridge.sol b/evm/src/interfaces/IRandBridge.sol index e8f7aeb..75ca09d 100644 --- a/evm/src/interfaces/IRandBridge.sol +++ b/evm/src/interfaces/IRandBridge.sol @@ -99,7 +99,7 @@ interface IRandBridge { error InsufficientFees(); /// A guardian set larger than an attestation's one-byte counts can carry. error TooManyGuardians(); - /// A token call re-entered `lock` or `release`. + /// A token call re-entered `lock`, `release` or `withdrawFees`. error ReentrantCall(); function lock(address token, uint256 amount, bytes32 randRecipient, uint256 relayerFee, uint32 nonce) diff --git a/evm/test/RandBridge.t.sol b/evm/test/RandBridge.t.sol index aaf8d63..30befaf 100644 --- a/evm/test/RandBridge.t.sol +++ b/evm/test/RandBridge.t.sol @@ -616,6 +616,76 @@ contract RandBridgeTest is Test { assertEq(bridge.custody(address(evil)), 0, "custody drained by the release alone"); } + // BR-1001: `withdrawFees` pays through the same `_push` as `release`, + // so it holds the same lock. Each test leaves 100 of accrued fees and + // 100_000 of custody in the hooked token, then withdraws 60. + + /// A whitelisted hooked token with 100 of accrued protocol fees (10 bps + /// of a 100_000 release) and 100_000 still in custody. + function _reentrantTokenWithFees() internal returns (ReentrantERC20 evil) { + evil = _reentrantToken(200_000); + _feeOn(); + bridge.release(_fromRand(_releasePayload(address(evil), 100_000, 0))); + assertEq(bridge.accruedFees(address(evil)), 100); + assertEq(bridge.custody(address(evil)), 100_000); + } + + function _assertFeeWithdrawalAlone(ReentrantERC20 evil, address treasury) internal view { + assertEq(evil.balanceOf(treasury), 60, "the outer withdrawal paid once"); + assertEq(bridge.accruedFees(address(evil)), 40, "accrued fees fell by the outer amount only"); + assertEq(bridge.custody(address(evil)), 100_000, "custody untouched"); + } + + function test_withdrawFees_refuses_reentry_into_lock_from_the_token() public { + ReentrantERC20 evil = _reentrantTokenWithFees(); + address treasury = address(0x7EA5); + evil.mint(address(evil), 1000); + evil.selfApprove(address(bridge)); + evil.arm(address(bridge), abi.encodeCall(bridge.lock, (address(evil), 1000, keccak256("inner"), 0, 0))); + + vm.prank(admin); + bridge.withdrawFees(address(evil), treasury, 60); + + _assertReentryRefused(evil); + assertEq(bridge.sequence(), 1, "only the setup lock was published"); + _assertFeeWithdrawalAlone(evil, treasury); + } + + function test_withdrawFees_refuses_reentry_into_release_from_the_token() public { + ReentrantERC20 evil = _reentrantTokenWithFees(); + address treasury = address(0x7EA5); + bytes memory inner = _fromRand(_releasePayload(address(evil), 1000, 0)); + evil.arm(address(bridge), abi.encodeCall(bridge.release, (inner))); + + vm.prank(admin); + bridge.withdrawFees(address(evil), treasury, 60); + + _assertReentryRefused(evil); + assertFalse(bridge.consumed(_digestOf(inner)), "the inner burn stays releasable"); + _assertFeeWithdrawalAlone(evil, treasury); + } + + /// The nested withdrawal has to come from the admin to get past + /// `onlyAdmin`, so the admin here is a contract the token can call (on + /// mainnet the admin is a contract too: the timelock). + function test_withdrawFees_refuses_reentry_into_withdrawFees_from_the_token() public { + ReentrantERC20 evil = _reentrantTokenWithFees(); + address treasury = address(0x7EA5); + ForwardingAdmin fwd = new ForwardingAdmin(address(bridge)); + vm.prank(admin); + bridge.transferAdmin(address(fwd)); + vm.prank(address(fwd)); + bridge.acceptAdmin(); + evil.arm(address(fwd), abi.encodeCall(bridge.withdrawFees, (address(evil), address(0xBAD), 40))); + + vm.prank(address(fwd)); + bridge.withdrawFees(address(evil), treasury, 60); + + _assertReentryRefused(evil); + assertEq(evil.balanceOf(address(0xBAD)), 0, "the nested withdrawal paid nothing"); + _assertFeeWithdrawalAlone(evil, treasury); + } + // ------------------------------------------------------------------ // protocol fee // ------------------------------------------------------------------ @@ -1069,3 +1139,23 @@ contract RandBridgeTest is Test { new EthereumRandBridge(admin, pauser, randEmitter, dup); } } + +/// A bridge admin that forwards any call it receives to the bridge and +/// bubbles the bridge's revert data: the way a token's transfer hook could +/// reach an admin-only function if the admin contract let it. +contract ForwardingAdmin { + address internal immutable BRIDGE; + + constructor(address bridge_) { + BRIDGE = bridge_; + } + + fallback() external { + (bool ok, bytes memory ret) = BRIDGE.call(msg.data); + if (!ok) { + assembly { + revert(add(ret, 32), mload(ret)) + } + } + } +} From a6066b964b4aa1f599816aa4ad26f2c1bf548d6a Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:26:04 +0800 Subject: [PATCH 2/6] BR-846, BR-761, BR-1008: provider numbers are checked, and a refused log range never moves a cursor BR-846: the EVM source's payload offset and length, the safe head, the range end and the sequence count are checked sums; so are the Solana message length, the Rand guardian_set_index, and the relayer submitter's gas estimate, base fee and tip. A value that does not fit is an error. Behind that, each source round and each relay runs under isolate::isolated, so a panic is an error for that source and round, not the daemon's exit. BR-1008: a provider that does not serve eth_getLogs for a range is an error (RangeNotServed) and the cursor stays; sequence() from the same provider is reported to the operator and decides nothing. BR-761: under a quorum a refusing provider is not counted for the range; the cursor moves only when a quorum served it with the same contents, and short of that the chain halts with an error naming the range. The authors' test that asserted the skip now asserts the refusal; the relayer daemon test waits for the log line it reads (it raced on a busy disk). Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01GFs5h2CVCmdBKerZzH2Xrx --- daemons/src/bin/guardian.rs | 22 ++- daemons/src/bin/relayer.rs | 16 +- daemons/src/isolate.rs | 55 ++++++ daemons/src/lib.rs | 1 + daemons/src/sources/evm.rs | 98 +++++----- daemons/src/sources/mod.rs | 67 ++++++- daemons/src/sources/rand.rs | 6 +- daemons/src/sources/solana.rs | 11 +- daemons/src/submit/evm.rs | 16 +- daemons/tests/audit_v14.rs | 338 ++++++++++++++++++++++++++++++++++ daemons/tests/daemons.rs | 7 +- daemons/tests/sources.rs | 33 ++-- 12 files changed, 593 insertions(+), 77 deletions(-) create mode 100644 daemons/src/isolate.rs create mode 100644 daemons/tests/audit_v14.rs diff --git a/daemons/src/bin/guardian.rs b/daemons/src/bin/guardian.rs index 54d1d85..5745866 100644 --- a/daemons/src/bin/guardian.rs +++ b/daemons/src/bin/guardian.rs @@ -4,6 +4,7 @@ use std::time::Duration; use anyhow::{anyhow, Context, Result}; use bridge_daemons::config::Config; use bridge_daemons::crypto::GuardianKey; +use bridge_daemons::isolate::isolated; use bridge_daemons::sources::{self, Source}; use bridge_daemons::store::Store; use bridge_daemons::{api, guardian}; @@ -253,23 +254,36 @@ async fn main() -> Result<()> { tracing::warn!("deferred transfers: {e:#}"); } // A source that fails is retried on the next round; one chain's RPC - // being down must not stop the others from being signed. An + // being down must not stop the others from being signed — and neither + // must a panic on something it answered (BR-846: `isolated`). An // equivocation is the exception: it is fatal by design. for source in &evm { report( source_name(source), - guardian::step_guarded(source, &store, &key, pq.as_ref(), &emitters, &guards).await, + isolated( + source_name(source), + guardian::step_guarded(source, &store, &key, pq.as_ref(), &emitters, &guards), + ) + .await, )?; } if let Some(source) = &solana { report( source_name(source), - guardian::step_guarded(source, &store, &key, pq.as_ref(), &emitters, &guards).await, + isolated( + source_name(source), + guardian::step_guarded(source, &store, &key, pq.as_ref(), &emitters, &guards), + ) + .await, )?; } report( "rand", - guardian::step_guarded(&rand, &store, &key, pq.as_ref(), &emitters, &guards).await, + isolated( + "rand", + guardian::step_guarded(&rand, &store, &key, pq.as_ref(), &emitters, &guards), + ) + .await, )?; tokio::select! { diff --git a/daemons/src/bin/relayer.rs b/daemons/src/bin/relayer.rs index 9ba6ff1..178d691 100644 --- a/daemons/src/bin/relayer.rs +++ b/daemons/src/bin/relayer.rs @@ -13,6 +13,7 @@ use bridge_daemons::config::{address20, hex32, Config, EvmKind, RelayerConfig}; use bridge_daemons::relayer::{ self, Destinations, EndpointSubmitter, GuardianSet, Progress, RegistrationError, }; +use bridge_daemons::isolate::isolated; use bridge_daemons::rpc::JsonRpc; use bridge_daemons::sources::{evm::EvmSource, rand::RandSource, solana::SolanaSource, Source}; use bridge_daemons::store::Store; @@ -214,17 +215,19 @@ async fn main() -> Result<()> { } loop { + // Each source and each relay on its own (BR-846): whatever one provider answers — + // an error, or a panic nothing should be able to cause — the others still run. for source in &evm { - if let Err(e) = relayer::observe(source, &store).await { + if let Err(e) = isolated(source.name(), relayer::observe(source, &store)).await { tracing::warn!("{e:#}"); } } if let Some(source) = &solana { - if let Err(e) = relayer::observe(source, &store).await { + if let Err(e) = isolated(source.name(), relayer::observe(source, &store)).await { tracing::warn!("{e:#}"); } } - if let Err(e) = relayer::observe(&rand, &store).await { + if let Err(e) = isolated("rand", relayer::observe(&rand, &store)).await { tracing::warn!("rand: {e:#}"); } @@ -232,8 +235,11 @@ async fn main() -> Result<()> { Ok(set) => { for message in relayer::pending(&store)? { let (chain, sequence) = (message.emitter_chain, message.sequence); - match relayer::relay_one(&message, &store, &guardians, &set, &destinations) - .await + match isolated( + "relay", + relayer::relay_one(&message, &store, &guardians, &set, &destinations), + ) + .await { Ok(Progress::Done(outcome)) => { tracing::info!(chain, sequence, "relayed: {outcome:?}") diff --git a/daemons/src/isolate.rs b/daemons/src/isolate.rs new file mode 100644 index 0000000..5ed86d2 --- /dev/null +++ b/daemons/src/isolate.rs @@ -0,0 +1,55 @@ +//! Defence in depth behind BR-846: one round of one source, or one relay, run so that a panic +//! inside it is an error for that source and that round, not the end of the daemon. +//! +//! The requirement is that nothing a provider says can panic (checked arithmetic, bounds +//! checks). This is what stands behind it if something still does: the guardian keeps signing +//! for its other chains and keeps serving the signature API. The panic is still printed by the +//! panic hook, and the error is logged by the caller like any other. + +use std::future::Future; +use std::panic::{catch_unwind, AssertUnwindSafe}; +use std::task::Poll; + +use anyhow::{anyhow, Result}; + +/// Runs `fut`; a panic while it is polled becomes `Err`, and the future is dropped unfinished. +/// What it had written is what a crash at that point would have left, which the stores are +/// built for: records are written atomically, and a cursor moves only after what it passes. +pub async fn isolated(what: &str, fut: impl Future>) -> Result { + let mut fut = std::pin::pin!(fut); + std::future::poll_fn(|cx| { + match catch_unwind(AssertUnwindSafe(|| fut.as_mut().poll(cx))) { + Ok(poll) => poll, + Err(panic) => { + let message = panic + .downcast_ref::<&str>() + .map(|s| s.to_string()) + .or_else(|| panic.downcast_ref::().cloned()) + .unwrap_or_else(|| "a panic with no message".into()); + Poll::Ready(Err(anyhow!( + "{what}: PANICKED ({message}); treated as an error for this round — this is a bug, report it" + ))) + } + } + }) + .await +} + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn a_panic_inside_is_an_error_outside_and_a_result_passes_through() { + let overflow = |n: u64| async move { + tokio::task::yield_now().await; + // What BR-846 was: an addition on a provider's number, with overflow checks on. + Ok::(n.checked_add(1).expect("attempt to add with overflow")) + }; + assert_eq!(isolated("eth", overflow(1)).await.unwrap(), 2); + let err = format!("{:#}", isolated("eth", overflow(u64::MAX)).await.unwrap_err()); + assert!(err.contains("eth: PANICKED") && err.contains("overflow"), "{err}"); + let refused = isolated("eth", async { Err::<(), _>(anyhow!("refused")) }).await; + assert_eq!(format!("{:#}", refused.unwrap_err()), "refused"); + } +} diff --git a/daemons/src/lib.rs b/daemons/src/lib.rs index 0194f3b..0388b07 100644 --- a/daemons/src/lib.rs +++ b/daemons/src/lib.rs @@ -14,6 +14,7 @@ pub mod crypto; pub mod gov_audit; pub mod governance; pub mod guardian; +pub mod isolate; pub mod limits; pub mod message; pub mod pq; diff --git a/daemons/src/sources/evm.rs b/daemons/src/sources/evm.rs index c021b4e..e7f26a5 100644 --- a/daemons/src/sources/evm.rs +++ b/daemons/src/sources/evm.rs @@ -9,7 +9,7 @@ use anyhow::{anyhow, bail, Context, Result}; use bridge_codec::Body; use serde_json::{json, Value}; -use super::{Confirm, Cursor, Located, Source}; +use super::{Confirm, Cursor, Located, RangeNotServed, Source}; use crate::config::{address20, EvmConfig, Finality}; use crate::crypto::keccak256; use crate::message::Observed; @@ -141,13 +141,23 @@ impl EvmSource { }; let nonce = small(word(0)?, 4)? as u32; let consistency_level = small(word(1)?, 1)? as u8; - let offset = small(word(2)?, 8)? as usize; + // The offset and the length are the provider's words: every sum on them is checked, + // so a log no contract would emit is an error and never an overflow (BR-846). + let offset = usize::try_from(small(word(2)?, 8)?) + .map_err(|_| anyhow!("payload offset out of range"))?; + let len_end = offset + .checked_add(32) + .ok_or_else(|| anyhow!("payload offset out of range"))?; let len_word = data - .get(offset..offset + 32) + .get(offset..len_end) .ok_or_else(|| anyhow!("payload offset out of range"))?; - let len = small(len_word, 8)? as usize; + let len = usize::try_from(small(len_word, 8)?) + .map_err(|_| anyhow!("payload length out of range"))?; + let end = len_end + .checked_add(len) + .ok_or_else(|| anyhow!("payload length out of range"))?; let payload = data - .get(offset + 32..offset + 32 + len) + .get(len_end..end) .ok_or_else(|| anyhow!("payload length out of range"))? .to_vec(); @@ -198,7 +208,21 @@ impl EvmSource { if cursor.next_block > safe { return Ok((Vec::new(), cursor.clone())); } - let to = safe.min(cursor.next_block + self.cfg.max_log_range.max(1) - 1); + // The head is the provider's word and the cursor came from one: no sum on either may + // overflow (BR-846). + let to = safe.min( + cursor + .next_block + .saturating_add(self.cfg.max_log_range.max(1) - 1), + ); + let after = to.checked_add(1).ok_or_else(|| { + anyhow!( + "{}: the range from block {} ends at block u64::MAX, which no chain has reached; \ + refusing the provider's head", + self.cfg.name, + cursor.next_block + ) + })?; let logs = match self .rpc .call( @@ -213,44 +237,30 @@ impl EvmSource { .await { Ok(logs) => logs, - // The node will not serve this range: a public RPC that calls any - // range older than its log window "archive" (publicnode: HTTP 403 - // past 10 000 blocks behind head, on Ethereum and BSC alike), so a - // daemon stopped for longer than that would otherwise never catch - // up. The endpoint's own counter settles whether the range holds - // anything: `sequence()` at the safe head equal to the sequence the - // cursor is waiting for means nothing was published through that - // block, and the scan may resume past it. Anything else keeps the - // cursor where it is, since a message would be missed. + // The node will not serve this range: a public RPC that calls any range older + // than its log window "archive" (publicnode: HTTP 403 past 10 000 blocks behind + // head, on Ethereum and BSC alike). That is an error and nothing else (BR-1008, + // BR-761): a refusal is not a reading of the range, so it never counts as "empty" + // and never moves the cursor — not even when the endpoint's own `sequence()`, + // answered by the same provider, says nothing was published. The counter is read + // only to tell the operator what this provider claims. Err(refused) => { - let published = match self.published_through(safe).await { - Ok(n) => n, - Err(e) => { - return Err(refused.context(format!( - "{}: and sequence() at block {safe} could not be read: {e:#}", - self.cfg.name - ))) - } + let claim = match self.published_through(safe).await { + Ok(n) => format!( + "this provider's own sequence() at block {safe} is {n} and the cursor \ + expects {}; that is its claim, not a reading of the range", + cursor.next_sequence + ), + Err(e) => format!("its sequence() at block {safe} could not be read: {e:#}"), }; - if published != cursor.next_sequence { - return Err(refused.context(format!( - "{}: blocks [{}, {to}] hold a message this node will not serve (sequence() is {published} at block {safe}, the cursor expects {}); use an RPC that serves that range", - self.cfg.name, cursor.next_block, cursor.next_sequence - ))); + return Err(RangeNotServed { + source_name: self.cfg.name.clone(), + from: cursor.next_block, + to, + cause: format!("{refused:#}"), + claim, } - tracing::warn!( - "{}: eth_getLogs [{}, {to}] refused ({refused:#}); sequence() at block {safe} is still {published}, nothing was published through it — resuming at {}", - self.cfg.name, - cursor.next_block, - safe + 1 - ); - return Ok(( - Vec::new(), - Cursor { - next_block: safe + 1, - next_sequence: cursor.next_sequence, - }, - )); + .into()); } }; let logs = logs @@ -296,7 +306,9 @@ impl EvmSource { observed.sequence ); } - next_sequence += 1; + next_sequence = next_sequence.checked_add(1).ok_or_else(|| { + anyhow!("{}: sequence u64::MAX has no successor", self.cfg.name) + })?; // Re-reading this message means scanning its block again; the // sequence skips what came before it in that block. out.push(Located { @@ -310,7 +322,7 @@ impl EvmSource { Ok(( out, Cursor { - next_block: to + 1, + next_block: after, next_sequence, }, )) diff --git a/daemons/src/sources/mod.rs b/daemons/src/sources/mod.rs index 0861696..88d3196 100644 --- a/daemons/src/sources/mod.rs +++ b/daemons/src/sources/mod.rs @@ -61,6 +61,41 @@ pub trait Source { } } +/// A provider did not serve the logs of a block range (BR-1008, BR-761). Never a reading of +/// the range: it is not "empty", it moves no cursor, and under a quorum the provider is simply +/// not counted for that range. +#[derive(Debug, Clone)] +pub struct RangeNotServed { + pub source_name: String, + pub from: u64, + pub to: u64, + /// What the provider answered instead. + pub cause: String, + /// What the same provider says its endpoint's `sequence()` is: information for the + /// operator, never grounds to pass the range over. + pub claim: String, +} + +impl std::fmt::Display for RangeNotServed { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!( + f, + "{name}: eth_getLogs for blocks [{from}, {to}] was not served ({cause}). A range that \ + is not served is never passed over: the cursor stays at block {from}. Use an RPC \ + that serves that range (an archive provider); or, only after checking on an \ + independent node that no MessagePublished was emitted in the blocks to be passed \ + over, stop the daemon and set next_block in cursors/{name}.json by hand. ({claim})", + name = self.source_name, + from = self.from, + to = self.to, + cause = self.cause, + claim = self.claim, + ) + } +} + +impl std::error::Error for RangeNotServed {} + /// What a provider offers for a quorum read (BR-4). #[allow(async_fn_in_trait)] pub trait Confirm: Source { @@ -175,7 +210,10 @@ impl Source for Quorum { /// Every provider scans the same range — capped at the quorum's safe /// head — and only what a quorum of them report identically is read. A - /// provider that errors agrees with nothing. If a quorum agrees on the + /// provider that errors agrees with nothing, and one that refuses the + /// range (`RangeNotServed`) is an error like any other: the cursor moves + /// over a range only when a quorum positively served it with the same + /// contents, empty or not (BR-761). If a quorum agrees on the /// whole scan, the cursor moves to its end; otherwise to just past the /// longest prefix a quorum agrees on (the lowest block among them), or /// not at all. @@ -194,10 +232,18 @@ impl Source for Quorum { let cap = self.quorum_head().await?; let mut scans = Vec::new(); let mut errors = Vec::new(); + let mut not_served: Option<(u64, u64)> = None; for (i, m) in self.members.iter().enumerate() { match m.poll_capped(cursor, cap).await { Ok(scan) => scans.push(scan), - Err(e) => errors.push(format!("provider {i}: {e:#}")), + // A provider that errors — a refused range among the errors — is not counted + // for this range: it agrees with nothing and advances nothing (BR-761). + Err(e) => { + if let Some(r) = e.downcast_ref::() { + not_served = Some((r.from, r.to)); + } + errors.push(format!("provider {i}: {e:#}")); + } } } let same = |a: &[Located], b: &[Located]| { @@ -238,6 +284,23 @@ impl Source for Quorum { } } if scans.len() < self.quorum { + if let Some((from, to)) = not_served { + // Short of a quorum that can serve the range: the chain halts here, loudly, + // until an operator gives it providers that serve it. It is never skipped. + let e = anyhow!( + "{}: halted at block {from} — blocks [{from}, {to}] were served by {} of {} \ + providers, {} needed. A provider that refuses a range is not counted and \ + the range is not passed over (BR-761): configure enough providers that \ + serve it (archive access), then the daemon catches up on its own: {}", + self.name(), + scans.len(), + self.members.len(), + self.quorum, + errors.join("; ") + ); + tracing::error!("{e:#}"); + return Err(e); + } return Err(anyhow!( "{}: {} of {} providers answered, {} needed: {}", self.name(), diff --git a/daemons/src/sources/rand.rs b/daemons/src/sources/rand.rs index faca932..2031141 100644 --- a/daemons/src/sources/rand.rs +++ b/daemons/src/sources/rand.rs @@ -75,7 +75,9 @@ pub async fn bridge_state(rpc: &JsonRpc) -> Result> { Ok(Some(BridgeState { guardian_set_index: v["guardian_set_index"] .as_u64() - .ok_or_else(|| anyhow!("no guardian_set_index"))? as u32, + .ok_or_else(|| anyhow!("no guardian_set_index"))? + .try_into() + .map_err(|_| anyhow!("guardian_set_index does not fit a u32"))?, guardians, burn_sequence: v["burn_sequence"] .as_u64() @@ -191,7 +193,7 @@ impl Source for RandSource { next_sequence: next, }, }); - next += 1; + next = next.saturating_add(1); // below burn_sequence, so it fits } Ok(( out, diff --git a/daemons/src/sources/solana.rs b/daemons/src/sources/solana.rs index 62bec08..a382dcf 100644 --- a/daemons/src/sources/solana.rs +++ b/daemons/src/sources/solana.rs @@ -148,9 +148,14 @@ fn parse_posted_message(data: &[u8], expect_sequence: u64) -> Result> { .ok_or_else(|| anyhow!("message account too short"))? .try_into() .expect("4"), - ) as usize; + ); + // The length is the node's word (BR-846): no sum on it may overflow, on any target. + let end = usize::try_from(len) + .ok() + .and_then(|len| len.checked_add(13)) + .ok_or_else(|| anyhow!("message body truncated"))?; Ok(data - .get(13..13 + len) + .get(13..end) .ok_or_else(|| anyhow!("message body truncated"))? .to_vec()) } @@ -233,7 +238,7 @@ impl Source for SolanaSource { next_sequence: next, }, }); - next += 1; + next = next.saturating_add(1); // below the program's sequence, so it fits } Ok(( out, diff --git a/daemons/src/submit/evm.rs b/daemons/src/submit/evm.rs index 9667408..26a56eb 100644 --- a/daemons/src/submit/evm.rs +++ b/daemons/src/submit/evm.rs @@ -94,7 +94,11 @@ impl EvmSubmitter { .await .with_context(|| format!("{}: {what} would revert", self.name))?, )?; - let gas = gas + gas / 5; + // The estimate, the tip and the base fee are the node's words (BR-846): a number + // that does not fit is an error and no transaction, never an overflow. + let gas = gas.checked_add(gas / 5).ok_or_else(|| { + anyhow!("{}: eth_estimateGas answered {gas}, which is no gas limit", self.name) + })?; let chain_id = quantity(&self.rpc.call("eth_chainId", json!([])).await?)?; let nonce = quantity( @@ -120,7 +124,15 @@ impl EvmSubmitter { .map(quantity_u128) .transpose()? .unwrap_or(0); - let max_fee = base_fee * 2 + tip; + let max_fee = base_fee + .checked_mul(2) + .and_then(|f| f.checked_add(tip)) + .ok_or_else(|| { + anyhow!( + "{}: base fee {base_fee} and tip {tip} do not make a fee that fits", + self.name + ) + })?; let raw = sign_eip1559( &self.key, diff --git a/daemons/tests/audit_v14.rs b/daemons/tests/audit_v14.rs new file mode 100644 index 0000000..452fc60 --- /dev/null +++ b/daemons/tests/audit_v14.rs @@ -0,0 +1,338 @@ +//! Audit v14 (addendum S7 to S8, 2026-11-16): the bridge rows that are about what a provider +//! or a file on disk can make a daemon do. +//! +//! BR-846 a provider-chosen offset, length, head, gas estimate or fee is an error, never a panic +//! BR-761 under a provider quorum a refused range is not counted; short of a quorum that +//! serves it the chain halts with an error, it is never skipped +//! BR-1008 one provider that refuses a range does not move the cursor, whatever `sequence()` says + +mod common; + +use bridge_codec::{Attestation, Payload, CHAIN_RAND}; +use bridge_daemons::config::{EvmConfig, EvmKind, Finality}; +use bridge_daemons::sources::evm::EvmSource; +use bridge_daemons::sources::{self, Cursor, Source}; +use bridge_daemons::submit::evm::EvmSubmitter; +use common::*; +use serde_json::{json, Value}; + +const CONTRACT: &str = "0x1111111111111111111111111111111111111111"; +const KEY: &str = "0x0000000000000000000000000000000000000000000000000000000000000001"; +const MAX64: &str = "ffffffffffffffff"; + +fn evm_cfg(urls: &[&str], quorum: Option, finality: Finality) -> EvmConfig { + EvmConfig { + name: "eth".into(), + chain: 2, + kind: EvmKind::Evm, + rpc: urls[0].into(), + rpcs: urls[1..].iter().map(|u| u.to_string()).collect(), + rpc_quorum: quorum, + contract: CONTRACT.into(), + finality, + start_block: 7, + max_log_range: 2000, + } +} + +fn payload(amount: u128) -> Vec { + Payload::Transfer(transfer(amount, 0, 2, CHAIN_RAND, [7; 32])).encode() +} + +/// A `MessagePublished` log whose third data word (the payload offset) and whose length word +/// are given as hex, so a test can write what no contract would. +fn raw_log(sequence: u64, offset_hex: &str, len_hex: &str, payload: &[u8], block: u64) -> Value { + let mut data = Vec::new(); + data.extend_from_slice(&word("9")); + data.extend_from_slice(&word("f")); + data.extend_from_slice(&word(offset_hex)); + data.extend_from_slice(&word(len_hex)); + data.extend_from_slice(&pad32(payload)); + json!({ + "address": CONTRACT, + "topics": ["0xabcd", format!("0x{}", hex::encode(word(&format!("{sequence:x}"))))], + "data": format!("0x{}", hex::encode(data)), + "blockNumber": format!("0x{block:x}"), + "removed": false, + }) +} + +fn log(sequence: u64, payload: &[u8], block: u64) -> Value { + raw_log(sequence, "60", &format!("{:x}", payload.len()), payload, block) +} + +fn number(v: &Value) -> u64 { + u64::from_str_radix(v.as_str().unwrap().trim_start_matches("0x"), 16).unwrap() +} + +/// A provider whose head is the hex quantity `head`. `logs`: what it serves, within the range +/// asked for; `None` refuses every `eth_getLogs` the way a public RPC refuses a range behind +/// its log window. `counter`: its answer to `sequence()`. +fn node(head: &str, logs: Option>, counter: Option) -> Fake { + let head = format!("0x{head}"); + rpc(move |m, p| match m { + "eth_blockNumber" => Some(Ok(json!(head))), + "eth_getBlockByNumber" => Some(Ok(json!({ "number": head, "timestamp": "0x6553f100" }))), + "eth_getLogs" => match &logs { + None => Some(Err(json!({ "code": -32602, "message": "Archive requests require a personal token" }))), + Some(logs) => { + let (from, to) = (number(&p[0]["fromBlock"]), number(&p[0]["toBlock"])); + Some(Ok(Value::Array( + logs.iter() + .filter(|l| (from..=to).contains(&number(&l["blockNumber"]))) + .cloned() + .collect(), + ))) + } + }, + "eth_call" => counter.map(|n| Ok(json!(format!("0x{}", hex::encode(word(&format!("{n:x}"))))))), + _ => None, + }) +} + +fn at(next_block: u64, next_sequence: u64) -> Cursor { + Cursor { + next_block, + next_sequence, + } +} + +// ---- BR-846: the EVM source --------------------------------------------------- + +/// The auditor's two logs: a payload offset of 2^64-1 and a payload length of 2^64-1. Each was +/// an addition that overflowed, which the release profile (overflow checks on) and this debug +/// build both turn into a panic; the daemon loop awaits the source inline, so that was an exit. +#[tokio::test] +async fn br846_a_log_whose_offset_or_length_word_is_2_64_minus_1_is_an_error_not_a_panic() { + for (what, bad) in [ + ("offset", raw_log(0, MAX64, "40", &payload(5), 50)), + ("length", raw_log(0, "60", MAX64, &payload(5), 50)), + // Neighbours of the same two sums: an offset that only overflows once 32 is added, and + // a length that only overflows once the offset is. + ("offset", raw_log(0, "ffffffffffffffe0", "40", &payload(5), 50)), + ("length", raw_log(0, "60", "ffffffffffffff80", &payload(5), 50)), + ("offset", raw_log(0, "ffffffffffffffff0000000000000060", "40", &payload(5), 50)), + ] { + let provider = node("64", Some(vec![bad]), Some(1)); + let source = EvmSource::new(&evm_cfg(&[&provider.url], None, Finality::Confirmations(10))).unwrap(); + let err = source.poll(&at(7, 0)).await.expect_err(what); + let text = format!("{err:#}"); + assert!( + text.contains("out of range") || text.contains("wider than its type"), + "{what}: {text}" + ); + } +} + +/// A safe head of u64::MAX, by tag and by confirmation count, from a provider that serves the +/// range and from one that refuses it: `safe + 1` and `cursor + range` are no longer sums that +/// can overflow. +#[tokio::test] +async fn br846_a_safe_head_of_u64_max_is_an_error_not_a_panic() { + for finality in [Finality::Tag("finalized".into()), Finality::Confirmations(0)] { + // Refused, with the counter the cursor expects: the branch that computed `safe + 1`. + let refusing = node(MAX64, None, Some(0)); + let source = EvmSource::new(&evm_cfg(&[&refusing.url], None, finality.clone())).unwrap(); + assert!(source.poll(&at(7, 0)).await.is_err()); + + // Served: a cursor near the top of the range would overflow `cursor + max_log_range` + // and then `to + 1`. + let serving = node(MAX64, Some(vec![]), Some(0)); + let source = EvmSource::new(&evm_cfg(&[&serving.url], None, finality.clone())).unwrap(); + let err = source.poll(&at(u64::MAX - 5, 0)).await.unwrap_err(); + assert!(format!("{err:#}").contains("u64::MAX"), "{err:#}"); + // Far from the top the same head is only a head: one range is read and the cursor steps. + let (none, next) = source.poll(&at(7, 0)).await.unwrap(); + assert!(none.is_empty()); + assert_eq!(next, at(2007, 0)); + } +} + +/// A cursor whose sequence is u64::MAX and a log that carries it: the count past it does not fit. +#[tokio::test] +async fn br846_a_sequence_of_u64_max_is_an_error_not_a_panic() { + let provider = node("64", Some(vec![raw_log(u64::MAX, "60", "53", &payload(5), 50)]), None); + let source = EvmSource::new(&evm_cfg(&[&provider.url], None, Finality::Confirmations(10))).unwrap(); + assert!(source.poll(&at(7, u64::MAX)).await.is_err()); +} + +// ---- BR-846: the relayer's submitter ------------------------------------------- + +fn attestation() -> (Attestation, [u8; 32]) { + let message = burn(0, 2, 50_000_000, 1_000_000); + let signatures = guardian_keys(2) + .iter() + .enumerate() + .map(|(i, k)| k.sign(&message.digest).unwrap().indexed(i as u8)) + .collect(); + ( + Attestation { + guardian_set_index: 0, + signatures, + body: message.decoded(), + }, + message.digest, + ) +} + +/// A destination node that answers a release with `gas`, `tip` and `base_fee` as given. +fn destination(gas: &'static str, tip: &'static str, base_fee: &'static str) -> Fake { + rpc(move |m, _| { + Some(Ok(match m { + "eth_call" => json!(format!("0x{:064x}", 0)), + "eth_estimateGas" => json!(gas), + "eth_chainId" => json!("0x7a69"), + "eth_getTransactionCount" => json!("0x9"), + "eth_maxPriorityFeePerGas" => json!(tip), + "eth_getBlockByNumber" => json!({ "baseFeePerGas": base_fee }), + "eth_sendRawTransaction" => json!("0xabc123"), + "eth_getTransactionReceipt" => json!({ "status": "0x1" }), + _ => return None, + })) + }) +} + +/// The submitter adds a fifth to the estimate and computes `2 * base fee + tip`. A node that +/// answers u64::MAX, u128::MAX or 2^256-1 gets an error back and no transaction: nothing is +/// signed over a number that did not fit. +#[tokio::test] +async fn br846_a_gas_estimate_or_fee_at_the_top_of_its_type_is_an_error_and_nothing_is_sent() { + let u128_max = "0xffffffffffffffffffffffffffffffff"; + let u256_max = "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"; + for (what, gas, tip, base_fee) in [ + ("gas estimate u64::MAX", "0xffffffffffffffff", "0x3b9aca00", "0x64"), + ("gas estimate above u64", "0x10000000000000000", "0x3b9aca00", "0x64"), + ("base fee u128::MAX", "0x186a0", "0x3b9aca00", u128_max), + ("base fee 2^256-1", "0x186a0", "0x3b9aca00", u256_max), + ("base fee whose double overflows", "0x186a0", "0x3b9aca00", "0x80000000000000000000000000000000"), + ("tip u128::MAX", "0x186a0", u128_max, "0x64"), + ("tip 2^256-1", "0x186a0", u256_max, "0x64"), + ] { + let dest = destination(gas, tip, base_fee); + let cfg = evm_cfg(&[&dest.url], None, Finality::Tag("latest".into())); + let submitter = EvmSubmitter::new(&cfg, KEY).unwrap(); + let (attestation, digest) = attestation(); + let result = submitter.release(&attestation, &digest).await; + assert!(result.is_err(), "{what}: {result:?}"); + assert_eq!(dest.count("eth_sendRawTransaction"), 0, "{what}: nothing is sent"); + } + // The ordinary answers still go through. + let dest = destination("0x186a0", "0x3b9aca00", "0x64"); + let cfg = evm_cfg(&[&dest.url], None, Finality::Tag("latest".into())); + let (attestation, digest) = attestation(); + EvmSubmitter::new(&cfg, KEY).unwrap().release(&attestation, &digest).await.unwrap(); + assert_eq!(dest.count("eth_sendRawTransaction"), 1); +} + +// ---- BR-1008: one provider ------------------------------------------------------ + +/// The auditor's stub: it refuses the range and answers the `sequence()` the cursor expects, +/// while block 50 holds lock 0. That used to move the cursor to the safe head, past the lock. +/// A refusal is now an error and the cursor stays; the error says what an operator can do. +#[tokio::test] +async fn br1008_a_provider_that_refuses_a_range_never_moves_the_cursor() { + let refuser = node("4e20", None, Some(0)); // head 20 000, "nothing published" + for cfg in [ + evm_cfg(&[&refuser.url], None, Finality::Confirmations(15)), + evm_cfg(&[&refuser.url], Some(1), Finality::Tag("finalized".into())), + ] { + // The bare source, and the same provider as a quorum of one (what the guardian runs). + let bare = EvmSource::new(&cfg).unwrap(); + let err = format!("{:#}", bare.poll(&at(7, 0)).await.unwrap_err()); + assert!(err.contains("Archive requests") && err.contains("not served"), "{err}"); + let quorum = sources::evm_quorum(&cfg).unwrap(); + let err = format!("{:#}", quorum.poll(&at(7, 0)).await.unwrap_err()); + assert!(err.contains("not served") && err.contains("cursors/eth.json"), "{err}"); + } +} + +/// Through the guardian's own step: the stored cursor is untouched and nothing is signed. +#[tokio::test] +async fn br1008_the_guardians_stored_cursor_does_not_move_on_a_refusal() { + let dir = tempfile::tempdir().unwrap(); + let store = bridge_daemons::store::Store::open(dir.path()).unwrap(); + let refuser = node("4e20", None, Some(0)); + let cfg = evm_cfg(&[&refuser.url], None, Finality::Confirmations(15)); + let source = sources::evm_quorum(&cfg).unwrap(); + store.set_cursor("eth", &at(7, 0)).unwrap(); + let key = &guardian_keys(1)[0]; + let emitters = bridge_daemons::message::Emitters::default(); + assert!(bridge_daemons::guardian::step(&source, &store, key, None, &emitters).await.is_err()); + assert_eq!(store.cursor("eth").unwrap(), Some(at(7, 0))); +} + +// ---- BR-761: a provider quorum ---------------------------------------------------- + +/// The deadlock: the range is empty, one provider refuses it and one serves it. Before, the +/// refuser answered "empty, resume past my safe head" and the server "empty, resume after one +/// range"; the two never agreed, the poll returned Ok with the cursor unchanged, for ever, and +/// said so only at warn level. Now the refuser is not counted for the range, and whether the +/// cursor moves depends only on how many providers served it. +#[tokio::test] +async fn br761_a_refuser_is_not_counted_and_a_quorum_of_servers_catches_up() { + let refuser = node("4e20", None, Some(0)); + let (b, c) = (node("4e20", Some(vec![]), Some(0)), node("4e20", Some(vec![]), Some(0))); + let finality = Finality::Confirmations(15); + + // Two of three serve the empty range and agree: the cursor steps one range, in any order. + for order in [[&refuser, &b, &c], [&b, &refuser, &c], [&b, &c, &refuser]] { + let urls: Vec<&str> = order.iter().map(|f| f.url.as_str()).collect(); + let source = sources::evm_quorum(&evm_cfg(&urls, None, finality.clone())).unwrap(); + let (messages, next) = source.poll(&at(7, 0)).await.unwrap(); + assert!(messages.is_empty()); + assert_eq!(next, at(2007, 0), "one range, as the two that served it say"); + } + + // One of two serves it: short of a quorum. An error that names the range and what to do, + // not a silent Ok — and never the refuser's jump. + for order in [[&refuser, &b], [&b, &refuser]] { + let source = + sources::evm_quorum(&evm_cfg(&[&order[0].url, &order[1].url], None, finality.clone())).unwrap(); + let err = format!("{:#}", source.poll(&at(7, 0)).await.unwrap_err()); + assert!( + err.contains("1 of 2") && err.contains("2 needed") && err.contains("[7, 2006]") && err.contains("halted"), + "{err}" + ); + } +} + +/// The safety case. Block 50 holds lock 0. Refusers that answer the expected `sequence()` can +/// never be the reason the cursor passes it, however many there are. +#[tokio::test] +async fn br761_refusals_and_a_sequence_claim_cannot_skip_a_block_that_holds_a_lock() { + let lock = vec![log(0, &payload(100_000_000), 50)]; + let finality = Finality::Confirmations(15); + let (r1, r2) = (node("4e20", None, Some(0)), node("4e20", None, Some(0))); + let honest = node("4e20", Some(lock.clone()), Some(1)); + + // Two refusers of three, quorum two: before, the two agreed on "empty, resume at 19 986" + // and the cursor jumped past the lock on the strength of two refusals. + for order in [[&r1, &r2, &honest], [&honest, &r1, &r2], [&r1, &honest, &r2]] { + let urls: Vec<&str> = order.iter().map(|f| f.url.as_str()).collect(); + let source = sources::evm_quorum(&evm_cfg(&urls, None, finality.clone())).unwrap(); + let err = format!("{:#}", source.poll(&at(7, 0)).await.unwrap_err()); + assert!(err.contains("1 of 3") && err.contains("halted"), "{err}"); + } + + // One refuser beside the honest provider, quorum two: the same. + let source = sources::evm_quorum(&evm_cfg(&[&r1.url, &honest.url], None, finality.clone())).unwrap(); + assert!(source.poll(&at(7, 0)).await.is_err()); + + // One refuser and two that serve the lock: it is read, and the cursor ends after the range. + let honest2 = node("4e20", Some(lock), Some(1)); + let source = + sources::evm_quorum(&evm_cfg(&[&r1.url, &honest.url, &honest2.url], None, finality.clone())).unwrap(); + let (messages, next) = source.poll(&at(7, 0)).await.unwrap(); + assert_eq!(messages.len(), 1); + assert_eq!(messages[0].sequence, 0); + assert_eq!(next, at(2007, 1)); + + // One refuser, one that serves the lock, one that serves the range as empty: no two agree + // on what the range holds, so nothing is read and nothing is passed over. + let empty = node("4e20", Some(vec![]), Some(0)); + let source = + sources::evm_quorum(&evm_cfg(&[&r1.url, &honest.url, &empty.url], None, finality)).unwrap(); + let (messages, next) = source.poll(&at(7, 0)).await.unwrap(); + assert!(messages.is_empty()); + assert_eq!(next, at(7, 0)); +} diff --git a/daemons/tests/daemons.rs b/daemons/tests/daemons.rs index 435dcad..14efb3b 100644 --- a/daemons/tests/daemons.rs +++ b/daemons/tests/daemons.rs @@ -600,8 +600,11 @@ fn a_relayer_observes_collects_a_quorum_and_records_the_release() { .arg(&config) .env("RELAYER_EVM_KEY", format!("{:064x}", 2)); let mut daemon = Daemon::spawn(cmd, dir.path()); - wait_until("the release recorded", || { - daemon.exited().is_none() && done_exists(dir.path(), 1, 0) + // The record is renamed into place, then its directories are synced, and only then does + // the relayer log the relay: the log line is waited for too, not read the instant the file + // appears (that raced under a busy disk). + wait_until("the release recorded and logged", || { + daemon.exited().is_none() && done_exists(dir.path(), 1, 0) && daemon.log().contains("Done") }); let done: Value = serde_json::from_slice( diff --git a/daemons/tests/sources.rs b/daemons/tests/sources.rs index 28b01e7..b4f043d 100644 --- a/daemons/tests/sources.rs +++ b/daemons/tests/sources.rs @@ -617,8 +617,12 @@ fn refusing_node(head: u64, published: Option) -> Fake { }) } +/// Audit v14, BR-1008: this test used to assert the opposite — that a refused range was passed +/// over, to just after the safe head, when the same provider answered `sequence()` with the +/// number the cursor expected. A stub that refused the range and answered that number moved +/// the cursor past a block holding a lock. A refusal is now an error and the cursor stays. #[tokio::test] -async fn a_refused_log_range_is_passed_when_the_endpoint_published_nothing_in_it() { +async fn a_refused_log_range_is_never_passed_even_when_the_endpoint_says_nothing_was_published() { // Head 20 000, 15 confirmations: the safe head is 19 985. The cursor is // 12 000 blocks behind it, past the RPC's log window. let node = refusing_node(20_000, Some(5)); @@ -629,24 +633,25 @@ async fn a_refused_log_range_is_passed_when_the_endpoint_published_nothing_in_it 1000, )) .unwrap(); - let (messages, next) = source + let err = source .poll(&Cursor { next_block: 7_985, next_sequence: 5, }) .await - .unwrap(); - assert!(messages.is_empty()); - assert_eq!( - next, - Cursor { - next_block: 19_986, - next_sequence: 5 - }, - "resumes right after the safe head whose sequence() was read" + .unwrap_err(); + let refusal = err + .downcast_ref::() + .expect("a typed refusal"); + assert_eq!((refusal.from, refusal.to), (7_985, 8_984)); + let text = format!("{err:#}"); + assert!( + text.contains("403") && text.contains("never passed over") && text.contains("cursors/testnet.json"), + "{text}" ); - // The counter was read at the safe head itself, from the endpoint, with - // the `sequence()` selector. + // The counter is still read at the safe head, from the endpoint, with the `sequence()` + // selector — to tell the operator what the provider claims, and for nothing else. + assert!(text.contains("sequence() at block 19985 is 5"), "{text}"); let call = node .requests() .into_iter() @@ -676,7 +681,7 @@ async fn a_refused_log_range_with_a_message_in_it_stays_an_error() { .unwrap_err(); let text = format!("{err:#}"); assert!( - text.contains("403") && text.contains("sequence() is 6") && text.contains("expects 5"), + text.contains("403") && text.contains("is 6 and the cursor expects 5"), "{text}" ); } From 94a08fb808811d06d166dab479b50dae1a2d9480 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:27:04 +0800 Subject: [PATCH 3/6] BR-1004: a deferred record is re-derived and must carry the guardian's own seal before a retry signs it retry_deferred signed the digest stored beside a deferred record's body. It now decodes the body again, derives the digest, requires the record to sit under the (chain, sequence) its body names, and requires a seal: a MAC under a key derived from the guardian key, written by limits::defer when the daemon itself deferred the message it read from its sources. A record that fails any of these is refused with an error every round and holds nothing back; what passes still goes through the peer check, the signing policy and the caps. rand-guardian --vouch-deferred : seals one record from an earlier build after an operator's review. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01GFs5h2CVCmdBKerZzH2Xrx --- daemons/src/bin/guardian.rs | 27 +++++++ daemons/src/crypto.rs | 15 ++++ daemons/src/guardian.rs | 74 +++++++++++++++++- daemons/src/limits.rs | 27 ++++++- daemons/tests/audit_v14.rs | 145 +++++++++++++++++++++++++++++++++++ daemons/tests/stale_store.rs | 2 +- 6 files changed, 285 insertions(+), 5 deletions(-) diff --git a/daemons/src/bin/guardian.rs b/daemons/src/bin/guardian.rs index 5745866..4b4f0cc 100644 --- a/daemons/src/bin/guardian.rs +++ b/daemons/src/bin/guardian.rs @@ -27,6 +27,11 @@ struct Cli { /// review, then exit: `:`. Needs the guardian's keys. #[arg(long, value_name = "CHAIN:SEQUENCE")] release_held: Option, + /// Vouch for one deferred transfer written by a build that did not seal its deferred + /// records (BR-1004), after review, then exit: `:`. Prints the transfer. + /// Needs the guardian's key. Never use it on a record you cannot account for. + #[arg(long, value_name = "CHAIN:SEQUENCE")] + vouch_deferred: Option, /// List the withheld transfers and exit. #[arg(long)] list_held: bool, @@ -129,6 +134,28 @@ async fn main() -> Result<()> { "no [guardian.limits]: this guardian signs without per-transfer or per-window caps (BRG-1)" ), } + if let Some(target) = &cli.vouch_deferred { + let (chain, sequence) = target + .split_once(':') + .and_then(|(c, s)| Some((c.parse::().ok()?, s.parse::().ok()?))) + .ok_or_else(|| anyhow!("--vouch-deferred takes :, got {target:?}"))?; + let message = guardian::vouch_deferred(&store, &key, chain, sequence)?; + println!("chain {chain} sequence {sequence} vouched for; the next retry checks it like any other"); + println!(" digest 0x{}", hex::encode(message.digest)); + match bridge_codec::Payload::decode(&message.decoded().payload) { + Ok(bridge_codec::Payload::Transfer(t)) => println!( + " amount {:?} (8-decimal units), fee {:?}, token chain {} 0x{}, to chain {} 0x{}", + t.amount_u128(), + t.fee_u128(), + t.token_chain, + hex::encode(t.token_address), + t.to_chain, + hex::encode(t.to) + ), + _ => println!(" not a transfer: the signing policy will refuse it"), + } + return Ok(()); + } if let Some(target) = &cli.release_held { let (chain, sequence) = target .split_once(':') diff --git a/daemons/src/crypto.rs b/daemons/src/crypto.rs index 62f95c3..2d20a6a 100644 --- a/daemons/src/crypto.rs +++ b/daemons/src/crypto.rs @@ -48,6 +48,21 @@ impl GuardianKey { self.address } + /// A keyed tag over one of this guardian's own on-disk records (BR-1004): what the daemon + /// wrote and will later act on without reading the chain again carries it, so a record + /// planted or edited by someone who can write the data directory but does not hold the + /// key is told apart from one this guardian wrote. It is a MAC under a key derived from + /// the signing key, never an ECDSA signature: nothing it produces verifies anywhere. + pub fn seal(&self, domain: &[u8], data: &[u8]) -> [u8; 32] { + let mut k = b"rand-bridge/guardian-record-seal/v1/key".to_vec(); + k.extend_from_slice(&self.key.to_bytes()); + let mut m = keccak256(&k).to_vec(); + m.extend_from_slice(&(domain.len() as u64).to_be_bytes()); + m.extend_from_slice(domain); + m.extend_from_slice(data); + keccak256(&m) + } + /// Signs `mu`. k256 normalises to low-s itself and adjusts the recovery /// id with it; both are asserted rather than assumed, because a high-s /// signature is refused by every verifier. diff --git a/daemons/src/guardian.rs b/daemons/src/guardian.rs index f3ee936..34c14d7 100644 --- a/daemons/src/guardian.rs +++ b/daemons/src/guardian.rs @@ -186,6 +186,7 @@ async fn peers_allow( if *down { limits::defer( store, + key, message, limits::now(), limits::DeferKind::Peers, @@ -216,7 +217,7 @@ async fn peers_allow( message.emitter_chain, message.sequence ); - limits::defer(store, message, limits::now(), limits::DeferKind::Peers, &reason)?; + limits::defer(store, key, message, limits::now(), limits::DeferKind::Peers, &reason)?; Ok(false) } } @@ -290,6 +291,7 @@ pub async fn step_guarded( // Its token already has a transfer waiting: keep sequence order. limits::defer( store, + key, &message, limits::now(), limits::DeferKind::Window, @@ -324,7 +326,7 @@ pub async fn step_guarded( } Err(e) if e.downcast_ref::().is_some() => { tracing::warn!("{}: {e:#}", source.name()); - limits::defer(store, &message, limits::now(), limits::DeferKind::Window, &format!("{e:#}"))?; + limits::defer(store, key, &message, limits::now(), limits::DeferKind::Window, &format!("{e:#}"))?; if let Some(w) = limits::window_of(&message) { waiting.insert(w); } @@ -380,6 +382,25 @@ pub async fn retry_deferred( let Some(d) = store.read_message::(limits::DEFERRED, chain, sequence)? else { continue; }; + // BR-1004: the record is a file, and a file can be planted or edited. Nothing in it is + // taken on trust: the body is decoded again and the digest derived from it, the place + // it was found must be the (chain, sequence) the body names, and it must carry this + // guardian's own seal over exactly that — what `limits::defer` wrote when the daemon + // read the message from its sources. Anything else is refused, loudly, every round, + // and holds nothing else back. What passes goes through the same peer check, signing + // policy and caps as a message read this round. + let d = match checked_deferral(key, chain, sequence, d) { + Ok(d) => d, + Err(e) => { + tracing::error!( + "REFUSED, not signed: deferred/{chain}/{sequence:020}.json: {e:#}. If this \ + record is from before this build, review it and vouch for it with \ + rand-guardian --vouch-deferred {chain}:{sequence}; otherwise remove the \ + file and find out who wrote it (BR-1004)" + ); + continue; + } + }; let window = limits::window_of(&d.message); if window.as_ref().is_some_and(|w| blocked.contains(w)) { continue; // behind an earlier one of its token that still waits @@ -413,6 +434,55 @@ pub async fn retry_deferred( Ok(signed) } +/// A deferred record as far as it can be believed (BR-1004): its message re-derived from the +/// body alone, found where that body says it belongs, and sealed by this guardian. +fn checked_deferral( + key: &GuardianKey, + chain: u16, + sequence: u64, + d: limits::Deferral, +) -> Result { + let message = Observed::new(d.message.body.clone()).context("its body does not decode")?; + if message != d.message { + anyhow::bail!( + "its stored digest, chain or sequence is not what its body gives (the body hashes \ + to {}, the record says {})", + hex::encode(message.digest), + hex::encode(d.message.digest) + ); + } + if (message.emitter_chain, message.sequence) != (chain, sequence) { + anyhow::bail!( + "its body is chain {} sequence {}, not the one it is filed under", + message.emitter_chain, + message.sequence + ); + } + match &d.seal { + Some(seal) if *seal == limits::deferral_seal(key, &message) => {} + Some(_) => anyhow::bail!("its seal is not this guardian's seal over this body"), + None => anyhow::bail!("it carries no seal: this daemon did not write it"), + } + Ok(limits::Deferral { message, ..d }) +} + +/// An operator's act, after review (BR-1004): seals the deferred record of `(chain, +/// sequence)` so the next retry treats it as the daemon's own — for a record deferred by a +/// build that did not seal. The body must still be the one the record's digest and place say. +/// Returns the message vouched for. +pub fn vouch_deferred(store: &Store, key: &GuardianKey, chain: u16, sequence: u64) -> Result { + let d: limits::Deferral = store + .read_message(limits::DEFERRED, chain, sequence)? + .ok_or_else(|| anyhow::anyhow!("chain {chain} sequence {sequence} is not deferred"))?; + let sealed = limits::Deferral { + seal: Some(limits::deferral_seal(key, &Observed::new(d.message.body.clone())?)), + ..d + }; + let d = checked_deferral(key, chain, sequence, sealed)?; + store.write_message(limits::DEFERRED, chain, sequence, &d)?; + Ok(d.message) +} + /// Whether this guardian has a signed record (readable or not) for /// `message`'s `(chain, sequence)`: then `sign_one` decides on its own. fn has_record(store: &Store, message: &Observed) -> bool { diff --git a/daemons/src/limits.rs b/daemons/src/limits.rs index de5d4dd..5964513 100644 --- a/daemons/src/limits.rs +++ b/daemons/src/limits.rs @@ -24,6 +24,7 @@ use anyhow::{anyhow, bail, Context, Result}; use bridge_codec::{Payload, CHAIN_RAND, CHAIN_SOLANA}; use serde::{Deserialize, Serialize}; +use crate::crypto::GuardianKey; use crate::message::Observed; use crate::store::Store; @@ -133,6 +134,19 @@ pub struct Deferral { pub at: u64, pub kind: DeferKind, pub reason: String, + /// This guardian's seal over `(chain, sequence, digest)` (BR-1004): proof that the daemon + /// itself deferred this body after reading it from its sources. A record without a valid + /// one is never signed by a retry. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub seal: Option, +} + +/// The seal a deferred record of `message` carries under `key`. +pub fn deferral_seal(key: &GuardianKey, message: &Observed) -> String { + let mut data = message.emitter_chain.to_be_bytes().to_vec(); + data.extend_from_slice(&message.sequence.to_be_bytes()); + data.extend_from_slice(&message.digest); + hex::encode(key.seal(b"deferred", &data)) } /// The window a transfer counts in: its direction and token, as one name. @@ -169,8 +183,16 @@ pub fn listed(store: &Store, kind_dir: &str) -> Result> { Ok(out) } -/// Records `message` as deferred. -pub fn defer(store: &Store, message: &Observed, now: u64, kind: DeferKind, reason: &str) -> Result<()> { +/// Records `message` as deferred, sealed by `key`: only the daemon, after it read the message +/// from its sources, calls this. +pub fn defer( + store: &Store, + key: &GuardianKey, + message: &Observed, + now: u64, + kind: DeferKind, + reason: &str, +) -> Result<()> { store.write_message( DEFERRED, message.emitter_chain, @@ -180,6 +202,7 @@ pub fn defer(store: &Store, message: &Observed, now: u64, kind: DeferKind, reaso at: now, kind, reason: reason.to_string(), + seal: Some(deferral_seal(key, message)), }, ) } diff --git a/daemons/tests/audit_v14.rs b/daemons/tests/audit_v14.rs index 452fc60..b50a1a1 100644 --- a/daemons/tests/audit_v14.rs +++ b/daemons/tests/audit_v14.rs @@ -336,3 +336,148 @@ async fn br761_refusals_and_a_sequence_claim_cannot_skip_a_block_that_holds_a_lo assert!(messages.is_empty()); assert_eq!(next, at(7, 0)); } + +// ---- BR-1004: a planted deferred record ----------------------------------------- + +mod br1004 { + use super::*; + use bridge_daemons::guardian::{self, Guards}; + use bridge_daemons::limits::{self, Limits, LimitsConfig}; + use bridge_daemons::message::{Emitters, Observed}; + use bridge_daemons::sources::Located; + use bridge_daemons::store::Store; + + const ETH: &str = "0x1111111111111111111111111111111111111111"; + + fn emitters() -> Emitters { + Emitters { + rand: RAND_EMITTER, + endpoints: vec![(2, word(ETH))], + } + } + + fn signed(store: &Store, chain: u16, sequence: u64) -> Option { + store.read_message("signed", chain, sequence).unwrap() + } + + fn plant(store: &Store, chain: u16, sequence: u64, record: Value) { + store.write_message(limits::DEFERRED, chain, sequence, &record).unwrap(); + } + + fn record_of(m: &Observed) -> Value { + json!({ "message": m, "at": 1, "kind": "window", "reason": "planted" }) + } + + /// The auditor's record: the body of a small burn, and beside it the digest of a burn of a + /// million tokens. The retry signed the stored digest — a valid guardian signature over a + /// burn the cap would have held — with no caps and no peers configured. + #[tokio::test] + async fn br1004_a_planted_record_whose_digest_is_not_its_bodys_is_refused() { + let dir = tempfile::tempdir().unwrap(); + let store = Store::open(dir.path()).unwrap(); + let key = &guardian_keys(1)[0]; + let (small, big) = (burn(7, 2, 100_000_000, 0), burn(7, 2, 100_000_000_000_000, 0)); + let mut record = record_of(&small); + record["message"]["digest"] = json!(hex::encode(big.digest)); + plant(&store, 1, 7, record); + + let n = guardian::retry_deferred(&store, key, None, &emitters(), &Guards::default()).await.unwrap(); + assert_eq!(n, 0); + assert!(signed(&store, 1, 7).is_none(), "no signature over the planted digest"); + assert_eq!(limits::listed(&store, limits::DEFERRED).unwrap(), vec![(1, 7)], "left for the operator"); + } + + /// A record that is consistent with itself but that this daemon never wrote — a burn no + /// source ever showed it — and one filed under another sequence than its body's. + #[tokio::test] + async fn br1004_a_planted_record_this_guardian_did_not_seal_is_refused() { + let dir = tempfile::tempdir().unwrap(); + let store = Store::open(dir.path()).unwrap(); + let keys = guardian_keys(2); + let invented = burn(3, 2, 50_000_000, 0); + plant(&store, 1, 3, record_of(&invented)); + // Sealed, but by another guardian's key. + let mut foreign = record_of(&burn(4, 2, 50_000_000, 0)); + foreign["seal"] = json!(limits::deferral_seal(&keys[1], &burn(4, 2, 50_000_000, 0))); + plant(&store, 1, 4, foreign); + // This guardian's seal over sequence 5, moved to sequence 6's place. + let mut moved = record_of(&burn(5, 2, 50_000_000, 0)); + moved["seal"] = json!(limits::deferral_seal(&keys[0], &burn(5, 2, 50_000_000, 0))); + plant(&store, 1, 6, moved); + + let n = guardian::retry_deferred(&store, &keys[0], None, &emitters(), &Guards::default()).await.unwrap(); + assert_eq!(n, 0); + for sequence in [3, 4, 5, 6] { + assert!(signed(&store, 1, sequence).is_none(), "sequence {sequence}"); + } + } + + struct Batch(Vec, Cursor); + + impl Source for Batch { + fn name(&self) -> &str { + "batch" + } + fn start(&self) -> Cursor { + Cursor::default() + } + async fn poll(&self, _: &Cursor) -> anyhow::Result<(Vec, Cursor)> { + Ok((self.0.iter().map(|l| l.message.clone()).collect(), self.1.clone())) + } + } + + /// What the daemon defers itself is still signed once its window has room; the same record + /// edited on disk (another amount, digest recomputed to match) is not; and an unsealed + /// record an operator vouches for goes through the caps like any other. + #[tokio::test] + async fn br1004_the_daemons_own_deferred_record_signs_and_an_edited_one_does_not() { + let dir = tempfile::tempdir().unwrap(); + let store = Store::open(dir.path()).unwrap(); + let key = &guardian_keys(1)[0]; + let caps = Limits::new(&LimitsConfig { + per_transfer: 1_000_000_000, + per_window: 1_000_000_000, + window_secs: 2, + token: vec![], + }) + .unwrap(); + let guards = Guards { limits: Some(&caps), ..Default::default() }; + let burns: Vec = (0..3).map(|s| burn(s, 2, 600_000_000, 0)).collect(); + let source = Batch( + burns.iter().map(|m| Located { message: m.clone(), resume: Cursor::default() }).collect(), + at(0, 3), + ); + assert_eq!(guardian::step_guarded(&source, &store, key, None, &emitters(), &guards).await.unwrap(), 1); + assert_eq!(limits::listed(&store, limits::DEFERRED).unwrap(), vec![(1, 1), (1, 2)]); + + // Sequence 1 is edited in place: ten times the per-transfer cap, digest to match, the + // daemon's seal left as it was. + let mut edited: Value = store.read_message(limits::DEFERRED, 1, 1).unwrap().unwrap(); + assert!(edited["seal"].is_string(), "the daemon seals what it defers"); + edited["message"] = json!(burn(1, 2, 10_000_000_000, 0)); + plant(&store, 1, 1, edited); + + std::thread::sleep(std::time::Duration::from_millis(3100)); + let n = guardian::retry_deferred(&store, key, None, &emitters(), &guards).await.unwrap(); + assert_eq!(n, 1, "sequence 2, the daemon's own record; the edited one holds nothing back"); + assert!(signed(&store, 1, 1).is_none()); + assert_eq!(signed(&store, 1, 2).unwrap()["message"]["digest"], hex::encode(burns[2].digest)); + + // An operator vouches for an unsealed record (one from before this build): it is then + // checked like any other — here, over the per-transfer cap, so held and not signed. + plant(&store, 1, 9, record_of(&burn(9, 2, 10_000_000_000, 0))); + plant(&store, 1, 10, record_of(&burn(10, 2, 100_000_000, 0))); + for sequence in [9, 10] { + guardian::vouch_deferred(&store, key, 1, sequence).unwrap(); + } + std::thread::sleep(std::time::Duration::from_millis(2100)); + guardian::retry_deferred(&store, key, None, &emitters(), &guards).await.unwrap(); + assert!(signed(&store, 1, 9).is_none() && limits::held(&store).unwrap().contains(&(1, 9))); + assert!(signed(&store, 1, 10).is_some()); + // Vouching does not launder a record whose digest is not its body's. + let mut bad = record_of(&burn(11, 2, 100_000_000, 0)); + bad["message"]["digest"] = json!(hex::encode(burns[0].digest)); + plant(&store, 1, 11, bad); + assert!(guardian::vouch_deferred(&store, key, 1, 11).is_err()); + } +} diff --git a/daemons/tests/stale_store.rs b/daemons/tests/stale_store.rs index 4eff4aa..949b37a 100644 --- a/daemons/tests/stale_store.rs +++ b/daemons/tests/stale_store.rs @@ -272,7 +272,7 @@ async fn an_unreachable_peer_set_is_probed_once_per_round() { let mut t = transfer(5, 0, 2, 1, [9; 32]); t.token_address = word(&format!("0x{tok:040x}")); let m = Observed::new(transfer_body(2, word(ETH), seq, t)).unwrap(); - limits::defer(&me, &m, 1, limits::DeferKind::Peers, "test").unwrap(); + limits::defer(&me, &keys[1], &m, 1, limits::DeferKind::Peers, "test").unwrap(); } let peers = [GuardianClient::new(&url)]; let guards = Guards { peers: &peers, ..Default::default() }; From 60899262fe817459f14956631dc3149b382f8c7a Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:34:42 +0800 Subject: [PATCH 4/6] BR-1005, BR-1006: a guardian names its Rand chain by id and genesis hash and checks both on every poll; an undecodable PQ key is an error BR-1005: rand.genesis_hash joins rand.chain_id in [rand]. rand-guardian does not start without both (RandConfig::chain_binding); check_startup reads the genesis hash too; and every RandSource poll asks its node for rand_chainId and rand_getGenesisHash before it reads a burn and again before it hands burns on, so a node switched to another chain under a running daemon yields an error and nothing to sign. The eight mainnet guardian configs and the relayer's carry chain 21's recorded genesis hash. No signed body or wire format changes: the body still names no Rand chain. BR-1006: bridge_state refuses a pq_guardians entry that is not a hex string, naming its index, as it refuses an undecodable ECDSA guardian; the authors' fake and assertion that held the silent drop are updated. README: what an operator must set or check before this build is rolled. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01GFs5h2CVCmdBKerZzH2Xrx --- daemons/README.md | 28 +++++ daemons/config.example.toml | 7 ++ daemons/mainnet/guardian-1.toml | 1 + daemons/mainnet/guardian-2.toml | 1 + daemons/mainnet/guardian-3.toml | 1 + daemons/mainnet/guardian-4.toml | 1 + daemons/mainnet/guardian-5.toml | 1 + daemons/mainnet/guardian-6.toml | 1 + daemons/mainnet/guardian-7.toml | 1 + daemons/mainnet/guardian-8.toml | 1 + daemons/mainnet/relayer.toml | 1 + daemons/src/bin/guardian.rs | 16 ++- daemons/src/bin/relayer.rs | 15 ++- daemons/src/config.rs | 39 +++++++ daemons/src/sources/rand.rs | 106 +++++++++++++++--- daemons/tests/audit_v14.rs | 183 ++++++++++++++++++++++++++++++++ daemons/tests/daemons.rs | 101 +++++++++++++++--- daemons/tests/rpc_quorum.rs | 2 + daemons/tests/sources.rs | 29 +++-- 19 files changed, 496 insertions(+), 39 deletions(-) diff --git a/daemons/README.md b/daemons/README.md index 191d235..816e4ef 100644 --- a/daemons/README.md +++ b/daemons/README.md @@ -79,6 +79,34 @@ relayer ◀──GET /v1/signature/{emitter_chain}/{sequence}────── guardian index: `mu` covers the body only, so after a rotation the same signature is simply assembled under the new set's indices. That is all "re-signing under the current set" takes. +### What an operator must know before rolling this build (audit v14) + +Nothing here is deployed by merging it. Before a guardian host gets a binary built from it: + +- **`rand.genesis_hash` is mandatory for `rand-guardian`, with `rand.chain_id` (BR-1005).** A + guardian whose `/etc/rand-guardian.toml` lacks either stops at startup with an error that names + the missing line. Add `genesis_hash = "<64 hex>"` under `[rand]` on every guardian host *before* + the binary is replaced; the value is the chain's genesis hash from its cut record (chain 21: + `daemons/mainnet/guardian-*.toml`), not something copied from the node. Both are checked against + every Rand node at startup and on every poll; a node on another chain yields no burn and an + error (`NOT SIGNING FOR RAND`) each round, while locks from the other chains are still signed. + A cut to a new chain changes both lines (the `cut-chain*.sh` scripts so far edit `chain_id` only). + The signed body still names no Rand chain: binding it there is a wire-format change for a cut. +- **A log range a provider will not serve is never passed over (BR-1008, BR-761).** A guardian + stopped for longer than its provider's log window used to resume on its own when the same + provider's `sequence()` matched the cursor. It now stays where it is and logs the range, every + round, until it has a provider that serves it (or, under `rpcs`, a quorum of them) or an + operator moves the cursor by hand as `docs/guardian-hosts.md` describes. Keep restarts shorter + than the window (publicnode: about an hour on BSC), or give the guardians archive-capable RPCs. +- **Deferred records are sealed (BR-1004).** A transfer deferred by this build carries the + guardian's seal and is retried as before. A record in `deferred/` written by an earlier build has + none and is refused, with an error every round, until it is reviewed and vouched for: + `rand-guardian --config … --vouch-deferred :` (needs the key). Check + `deferred/` on each host before the roll; empty means nothing to do. A seal is tied to the + guardian key, so a key change needs the same step. +- **`rand_getBridgeState` with an undecodable `pq_guardians` entry is an error (BR-1006)**, where + it used to be read as a shorter list. + ## Relayer - Watches the same sources itself, so it trusts no guardian about what was said on a chain: a diff --git a/daemons/config.example.toml b/daemons/config.example.toml index da2708b..62116d8 100644 --- a/daemons/config.example.toml +++ b/daemons/config.example.toml @@ -17,6 +17,13 @@ start_sequence = 0 # At startup the node at `rpc` must answer and serve this chain, and the stored Rand # cursor must not be past the chain's burn_sequence (BR-401); otherwise the daemon stops. # chain_id = 21 +# The chain's genesis hash (what `rand_getGenesisHash` serves on it), from the chain's cut +# record — not copied from the node this daemon reads. With chain_id it names the one Rand +# chain this daemon works for (BR-1005): both are checked against every Rand node at startup +# and again on every poll, before a burn is read and before it is handed on to be signed, so +# a node switched to another chain yields nothing to sign. rand-guardian does NOT START +# without both lines; rand-relayer warns. A cut to a new chain changes both. +# genesis_hash = "<64 hex: the chain's genesis hash>" # ---- source endpoints ------------------------------------------------------ # `finality` is what the guardian waits for before it signs. A signature diff --git a/daemons/mainnet/guardian-1.toml b/daemons/mainnet/guardian-1.toml index 3130cfd..7b8a7b1 100644 --- a/daemons/mainnet/guardian-1.toml +++ b/daemons/mainnet/guardian-1.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-2.toml b/daemons/mainnet/guardian-2.toml index 2f7afa0..65a6a7c 100644 --- a/daemons/mainnet/guardian-2.toml +++ b/daemons/mainnet/guardian-2.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-3.toml b/daemons/mainnet/guardian-3.toml index 4964b7d..bd822cd 100644 --- a/daemons/mainnet/guardian-3.toml +++ b/daemons/mainnet/guardian-3.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-4.toml b/daemons/mainnet/guardian-4.toml index 34aad78..523469c 100644 --- a/daemons/mainnet/guardian-4.toml +++ b/daemons/mainnet/guardian-4.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-5.toml b/daemons/mainnet/guardian-5.toml index 3fba68b..d4c20fb 100644 --- a/daemons/mainnet/guardian-5.toml +++ b/daemons/mainnet/guardian-5.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-6.toml b/daemons/mainnet/guardian-6.toml index 43b48ec..29e6793 100644 --- a/daemons/mainnet/guardian-6.toml +++ b/daemons/mainnet/guardian-6.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-7.toml b/daemons/mainnet/guardian-7.toml index 6b2f7e1..1dd176e 100644 --- a/daemons/mainnet/guardian-7.toml +++ b/daemons/mainnet/guardian-7.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/guardian-8.toml b/daemons/mainnet/guardian-8.toml index e0fdbe4..a350618 100644 --- a/daemons/mainnet/guardian-8.toml +++ b/daemons/mainnet/guardian-8.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/mainnet/relayer.toml b/daemons/mainnet/relayer.toml index 738d26f..977f489 100644 --- a/daemons/mainnet/relayer.toml +++ b/daemons/mainnet/relayer.toml @@ -5,6 +5,7 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut chain_id = 21 # part of every PQ co-signature and governance message (spec/PQ-COSIGNATURE.md §9) +genesis_hash = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a" # chain 21 (spec/PQ-COSIGNATURE.md); with chain_id, checked against the node at start and on every poll (BR-1005) — a cut changes BOTH lines emitter = "c02df6ba70c2457a7406780da97492a6acb57dc40751e6279f003a570559d15f" [[evm]] diff --git a/daemons/src/bin/guardian.rs b/daemons/src/bin/guardian.rs index 4b4f0cc..202dac1 100644 --- a/daemons/src/bin/guardian.rs +++ b/daemons/src/bin/guardian.rs @@ -115,6 +115,14 @@ async fn main() -> Result<()> { None } }; + // BR-1005: which Rand chain this guardian signs burns of — its id and its genesis hash — + // is configuration, and mandatory: without both the daemon stops here, before it holds a + // store or a socket. Both are checked against the node below and again on every poll. + let (rand_chain_id, rand_genesis) = config.rand.chain_binding()?; + tracing::info!( + "signing burns of Rand chain {rand_chain_id}, genesis {}", + hex::encode(rand_genesis) + ); let store = Store::open(&config.data_dir)?; let emitters = config.emitters()?; let limits = section @@ -267,7 +275,13 @@ async fn main() -> Result<()> { { let rpc = bridge_daemons::rpc::JsonRpc::new(&config.rand.rpc); let cursor = store.cursor(rand.name())?.unwrap_or_else(|| rand.start()); - bridge_daemons::sources::rand::check_startup(&rpc, config.rand.chain_id, &cursor).await?; + bridge_daemons::sources::rand::check_startup( + &rpc, + Some(rand_chain_id), + Some(rand_genesis), + &cursor, + ) + .await?; } loop { diff --git a/daemons/src/bin/relayer.rs b/daemons/src/bin/relayer.rs index 178d691..a80f205 100644 --- a/daemons/src/bin/relayer.rs +++ b/daemons/src/bin/relayer.rs @@ -210,8 +210,19 @@ async fn main() -> Result<()> { // chain or polling a cursor the chain can never reach. { let cursor = store.cursor(rand.name())?.unwrap_or_else(|| rand.start()); - bridge_daemons::sources::rand::check_startup(&rand_rpc, config.rand.chain_id, &cursor) - .await?; + if config.rand.chain_id.is_none() || config.rand.genesis_hash.is_none() { + tracing::warn!( + "rand.chain_id and rand.genesis_hash are not both set: this relayer cannot tell \ + a Rand node switched to another chain from its own (BR-1005)" + ); + } + bridge_daemons::sources::rand::check_startup( + &rand_rpc, + config.rand.chain_id, + config.rand.genesis()?, + &cursor, + ) + .await?; } loop { diff --git a/daemons/src/config.rs b/daemons/src/config.rs index c657122..0a41302 100644 --- a/daemons/src/config.rs +++ b/daemons/src/config.rs @@ -55,6 +55,44 @@ pub struct RandConfig { /// (`spec/PQ-COSIGNATURE.md`): it is part of what the co-signature is /// over, and the guardian must know it without trusting an RPC node. pub chain_id: Option, + /// The Rand chain's genesis hash (`rand_getGenesisHash`), 64 hex, from the chain's cut + /// record — never copied from the node it is meant to check. With `chain_id` it says + /// which Rand chain this daemon works for (BR-1005): every poll of a Rand node checks + /// both before a burn is read, so a node switched to another chain yields nothing to + /// sign. `rand-guardian` does not start without both. + #[serde(default)] + pub genesis_hash: Option, +} + +impl RandConfig { + /// The configured genesis hash, decoded. + pub fn genesis(&self) -> Result> { + self.genesis_hash + .as_deref() + .map(|g| { + hex32(g).with_context(|| { + format!("rand.genesis_hash must be the chain's 32-byte genesis hash as 64 hex, got {g:?} (BR-1005)") + }) + }) + .transpose() + } + + /// The Rand chain this configuration is for, by id and genesis hash — or the reason a + /// guardian must not start (BR-1005): a daemon that signs burns has to know which chain's + /// burns, from its own configuration, and fails closed without it. + pub fn chain_binding(&self) -> Result<(u64, [u8; 32])> { + let missing = |field: &str| { + anyhow!( + "{field} is not set. rand-guardian signs burns of one Rand chain only and does \ + not start without rand.chain_id and rand.genesis_hash under [rand] (BR-1005): \ + set both from the chain's cut record (genesis_hash is what rand_getGenesisHash \ + serves on that chain, 64 hex), not from the node this daemon reads" + ) + }; + let chain_id = self.chain_id.ok_or_else(|| missing("rand.chain_id"))?; + let genesis = self.genesis()?.ok_or_else(|| missing("rand.genesis_hash"))?; + Ok((chain_id, genesis)) + } } #[derive(Clone, Debug, Deserialize)] @@ -362,6 +400,7 @@ impl Config { fn validate(&self) -> Result<()> { hex32(&self.rand.emitter).context("rand.emitter")?; + self.rand.genesis()?; check_providers( "rand", &self.rand.rpc, diff --git a/daemons/src/sources/rand.rs b/daemons/src/sources/rand.rs index 2031141..cc16e91 100644 --- a/daemons/src/sources/rand.rs +++ b/daemons/src/sources/rand.rs @@ -33,6 +33,21 @@ impl RandSource { } } +impl RandSource { + /// This provider against the configured chain; an error is logged loudly, since it means + /// no burn of this node is read until an operator has looked. + async fn check_chain(&self) -> Result<()> { + let result = match self.cfg.genesis() { + Ok(genesis) => check_chain(&self.rpc, self.cfg.chain_id, genesis).await, + Err(e) => Err(e), + }; + if let Err(e) = &result { + tracing::error!("rand: NOT SIGNING FOR RAND: {e:#}"); + } + result + } +} + /// The bridge's public state, as far as the daemons need it. pub struct BridgeState { pub guardian_set_index: u32, @@ -82,17 +97,69 @@ pub async fn bridge_state(rpc: &JsonRpc) -> Result> { burn_sequence: v["burn_sequence"] .as_u64() .ok_or_else(|| anyhow!("no burn_sequence"))?, - pq_guardians: v["pq_guardians"] - .as_array() - .map(|keys| { - keys.iter() - .filter_map(|k| hex::decode(k.as_str()?).ok()) - .collect() - }) - .unwrap_or_default(), + pq_guardians: pq_guardians(&v["pq_guardians"])?, })) } +/// The post-quantum keys, index-aligned with the guardians. An entry that does not decode is +/// an error that names its index (BR-1006), as an undecodable ECDSA guardian is: dropping it +/// would move every later key down one index and leave the set one key short, in silence. +fn pq_guardians(v: &serde_json::Value) -> Result>> { + if v.is_null() { + return Ok(Vec::new()); // a chain that does not require the co-signature + } + v.as_array() + .ok_or_else(|| anyhow!("rand_getBridgeState: pq_guardians is not a list"))? + .iter() + .enumerate() + .map(|(i, k)| { + k.as_str() + .and_then(|k| hex::decode(k.trim_start_matches("0x")).ok()) + .ok_or_else(|| anyhow!("rand_getBridgeState: pq_guardians[{i}] is not a hex string")) + }) + .collect() +} + +/// Whether the node behind `rpc` serves the Rand chain this daemon is configured for +/// (BR-1005): its `rand_chainId` and its `rand_getGenesisHash` against the configured ones, +/// each when configured. A node that does not answer is an error, not a pass. +pub async fn check_chain( + rpc: &JsonRpc, + chain_id_expected: Option, + genesis_expected: Option<[u8; 32]>, +) -> Result<()> { + if let Some(expected) = chain_id_expected { + let served = chain_id(rpc).await.context( + "the Rand node did not answer rand_chainId; nothing is read from a node whose \ + chain is not confirmed", + )?; + if served != expected { + bail!( + "rand.chain_id is {expected} but the node at {} serves chain {served}: this is \ + not the chain this daemon works for, and none of its burns is read or signed", + rpc.shown() + ); + } + } + if let Some(expected) = genesis_expected { + let served = genesis_hash(rpc).await.context( + "the Rand node did not answer rand_getGenesisHash; nothing is read from a node \ + whose chain is not confirmed", + )?; + if served != expected { + bail!( + "rand.genesis_hash is {} but the node at {} serves a chain whose genesis hash \ + is {}: this is not the chain this daemon works for, and none of its burns is \ + read or signed", + hex::encode(expected), + rpc.shown(), + hex::encode(served) + ); + } + } + Ok(()) +} + /// The message for a Rand cursor past the chain: a cursor kept from another chain, or a node /// on another chain than the cursor was made for. Named in full so an operator can act on it. fn ahead(cursor: &Cursor, burn_sequence: u64) -> anyhow::Error { @@ -105,13 +172,15 @@ fn ahead(cursor: &Cursor, burn_sequence: u64) -> anyhow::Error { ) } -/// What a daemon settles with its Rand node before it reads anything (BR-401): the node answers -/// and serves the configured chain (`rand.chain_id`, when set), and the Rand cursor it would -/// resume from is not past the chain's `burn_sequence`. Every failure is an error — a node that -/// does not answer is not skipped over, a cursor ahead of the chain is not polled in silence. +/// What a daemon settles with its Rand node before it reads anything (BR-401, BR-1005): the +/// node answers and serves the configured chain (`rand.chain_id` and `rand.genesis_hash`, each +/// when set), and the Rand cursor it would resume from is not past the chain's `burn_sequence`. +/// Every failure is an error — a node that does not answer is not skipped over, a cursor ahead +/// of the chain is not polled in silence. The same chain check runs again on every poll. pub async fn check_startup( rpc: &JsonRpc, configured_chain_id: Option, + configured_genesis: Option<[u8; 32]>, cursor: &Cursor, ) -> Result<()> { if let Some(expected) = configured_chain_id { @@ -123,6 +192,9 @@ pub async fn check_startup( bail!("rand.chain_id is {expected} but the node at rand.rpc serves chain {served}"); } } + check_chain(rpc, None, configured_genesis) + .await + .context("a daemon does not start without confirming its chain (rand.genesis_hash)")?; let state = bridge_state(rpc).await.context( "the Rand node at rand.rpc did not serve rand_getBridgeState; the Rand cursor cannot be \ checked against the chain", @@ -153,6 +225,11 @@ impl Source for RandSource { } async fn poll_located(&self, cursor: &Cursor) -> Result<(Vec, Cursor)> { + // BR-1005: which chain this node serves is asked on every poll, not once at startup. + // A node switched to another Rand chain under a running daemon — a cut, a wrong data + // directory, a tunnel repointed — serves that chain's burns under the same sequence + // numbers, and the body a guardian signs names no Rand chain. + self.check_chain().await?; let Some(state) = bridge_state(&self.rpc).await? else { return Ok((Vec::new(), cursor.clone())); // a chain without a bridge }; @@ -195,6 +272,11 @@ impl Source for RandSource { }); next = next.saturating_add(1); // below burn_sequence, so it fits } + // And once more after the burns were read, before any of them is handed on to be + // signed: a node switched in between is caught here and what it served is dropped. + if !out.is_empty() { + self.check_chain().await?; + } Ok(( out, Cursor { diff --git a/daemons/tests/audit_v14.rs b/daemons/tests/audit_v14.rs index b50a1a1..12ff09d 100644 --- a/daemons/tests/audit_v14.rs +++ b/daemons/tests/audit_v14.rs @@ -481,3 +481,186 @@ mod br1004 { assert!(guardian::vouch_deferred(&store, key, 1, 11).is_err()); } } + +// ---- BR-1005: the Rand chain a guardian signs burns of --------------------------- +// ---- BR-1006: an undecodable post-quantum guardian key --------------------------- + +mod br1005 { + use super::*; + use bridge_daemons::config::RandConfig; + use bridge_daemons::rpc::JsonRpc; + use bridge_daemons::sources::rand::{self, RandSource}; + use std::sync::atomic::{AtomicBool, AtomicU64, Ordering::SeqCst}; + use std::sync::Arc; + + /// Chain 21's genesis hash, as the repository records it (AGENTS.md, spec/PQ-COSIGNATURE.md). + const CHAIN21: &str = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a"; + const OTHER: &str = "1111111111111111111111111111111111111111111111111111111111111111"; + + fn cfg(url: &str, chain_id: Option, genesis: Option<&str>) -> RandConfig { + RandConfig { + rpc: url.into(), + emitter: hex::encode(RAND_EMITTER), + start_sequence: 0, + chain_id, + genesis_hash: genesis.map(str::to_string), + rpcs: Vec::new(), + rpc_quorum: None, + } + } + + struct Node { + chain_id: AtomicU64, + other_genesis: AtomicBool, + /// Switch to chain 22 the moment a burn is served: a node restarted mid-poll. + flip_on_burn: AtomicBool, + } + + /// A Rand node with one burn, whose chain an operator can switch under the guardian. + fn node() -> (Fake, Arc) { + let state = Arc::new(Node { + chain_id: AtomicU64::new(21), + other_genesis: AtomicBool::new(false), + flip_on_burn: AtomicBool::new(false), + }); + let s = state.clone(); + let burn = burn(0, 2, 50_000_000, 0); + let fake = rpc(move |m, _| match m { + "rand_chainId" => Some(Ok(json!(s.chain_id.load(SeqCst)))), + "rand_getGenesisHash" => Some(Ok(json!(if s.other_genesis.load(SeqCst) { OTHER } else { CHAIN21 }))), + "rand_getBridgeState" => Some(Ok(json!({ + "enabled": true, "guardian_set_index": 1, "guardians": [], + "burn_sequence": 1, "pq_guardians": [], + }))), + "rand_getBridgeBurn" => { + if s.flip_on_burn.load(SeqCst) { + s.chain_id.store(22, SeqCst); + } + Some(Ok(json!({ "body_hex": hex::encode(&burn.body), "digest": hex::encode(burn.digest) }))) + } + _ => None, + }); + (fake, state) + } + + /// The auditor's sequence: a guardian started on chain 21, its node switched to chain 22. + /// Every poll asks the node which chain it serves, by id and by genesis hash, before it + /// reads a burn; a node on another chain yields an error and no burn. + #[tokio::test] + async fn br1005_a_node_switched_to_another_chain_yields_no_burn_to_sign() { + let (fake, state) = node(); + let source = RandSource::new(&cfg(&fake.url, Some(21), Some(CHAIN21))); + let (burns, next) = source.poll(&at(0, 0)).await.unwrap(); + assert_eq!((burns.len(), next), (1, at(0, 1)), "on its own chain the burn is read"); + + // The node is switched to chain 22 (another id; chain 22's burn 0 is another burn). + state.chain_id.store(22, SeqCst); + let err = format!("{:#}", source.poll(&at(0, 0)).await.unwrap_err()); + assert!(err.contains("serves chain 22") && err.contains("rand.chain_id is 21"), "{err}"); + + // The same id over another genesis: a re-cut chain, or a node made to answer 21. + state.chain_id.store(21, SeqCst); + state.other_genesis.store(true, SeqCst); + let err = format!("{:#}", source.poll(&at(0, 0)).await.unwrap_err()); + assert!(err.contains("genesis") && err.contains(OTHER) && err.contains(CHAIN21), "{err}"); + + // Switched between the check and the read: the check after the burns catches it, and + // the burn read in between is not returned. + state.other_genesis.store(false, SeqCst); + state.flip_on_burn.store(true, SeqCst); + let err = format!("{:#}", source.poll(&at(0, 0)).await.unwrap_err()); + assert!(err.contains("serves chain 22"), "{err}"); + assert!(fake.count("rand_getBridgeBurn") >= 2, "the burn was served and then dropped"); + } + + /// Through the guardian's own step, as a quorum of one: nothing is signed, the cursor stays. + #[tokio::test] + async fn br1005_the_guardian_signs_no_burn_of_a_switched_node() { + let (fake, state) = node(); + let dir = tempfile::tempdir().unwrap(); + let store = bridge_daemons::store::Store::open(dir.path()).unwrap(); + let source = sources::rand_quorum(&cfg(&fake.url, Some(21), Some(CHAIN21))).unwrap(); + let key = &guardian_keys(1)[0]; + let emitters = bridge_daemons::message::Emitters { rand: RAND_EMITTER, endpoints: vec![] }; + state.chain_id.store(22, SeqCst); + let err = bridge_daemons::guardian::step(&source, &store, key, None, &emitters).await.unwrap_err(); + assert!(format!("{err:#}").contains("serves chain 22"), "{err:#}"); + assert!(store.read_message::("signed", 1, 0).unwrap().is_none()); + assert_eq!(store.cursor("rand").unwrap(), None); + // Back on chain 21 it signs. + state.chain_id.store(21, SeqCst); + assert_eq!(bridge_daemons::guardian::step(&source, &store, key, None, &emitters).await.unwrap(), 1); + } + + /// The startup check reads the genesis hash too, and a guardian's configuration must name + /// both: `chain_binding` is what rand-guardian refuses to start without. + #[tokio::test] + async fn br1005_startup_checks_the_genesis_hash_and_a_guardian_must_configure_both() { + let (fake, state) = node(); + let client = JsonRpc::new(&fake.url); + let g = bridge_daemons::config::hex32(CHAIN21).unwrap(); + rand::check_startup(&client, Some(21), Some(g), &at(0, 0)).await.unwrap(); + state.other_genesis.store(true, SeqCst); + let err = format!("{:#}", rand::check_startup(&client, Some(21), Some(g), &at(0, 0)).await.unwrap_err()); + assert!(err.contains("rand.genesis_hash") && err.contains(OTHER), "{err}"); + + assert_eq!(cfg("http://x", Some(21), Some(CHAIN21)).chain_binding().unwrap(), (21, g)); + for (chain_id, genesis, names) in [ + (None, Some(CHAIN21), "rand.chain_id"), + (Some(21), None, "rand.genesis_hash"), + (None, None, "rand.chain_id"), + (Some(21), Some("ca76"), "rand.genesis_hash"), + (Some(21), Some(""), "rand.genesis_hash"), + ] { + let err = format!("{:#}", cfg("http://x", chain_id, genesis).chain_binding().unwrap_err()); + assert!(err.contains(names) && err.contains("BR-1005"), "{err}"); + } + } + + /// The mainnet configs in the repository carry chain 21 and its recorded genesis hash. + #[test] + fn br1005_the_mainnet_configs_name_chain_21_and_its_genesis_hash() { + let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("mainnet"); + let mut seen = 0; + for entry in std::fs::read_dir(&dir).unwrap() { + let path = entry.unwrap().path(); + if path.extension().and_then(|e| e.to_str()) != Some("toml") { + continue; + } + let config = bridge_daemons::config::Config::load(&path).unwrap(); + let (chain_id, genesis) = config.rand.chain_binding().unwrap_or_else(|e| panic!("{}: {e:#}", path.display())); + assert_eq!((chain_id, hex::encode(genesis).as_str()), (21, CHAIN21), "{}", path.display()); + seen += 1; + } + assert_eq!(seen, 9, "eight guardians and the relayer"); + } + + /// BR-1006: an entry of `pq_guardians` that is not hex was dropped in silence, which moved + /// every later key down one index; an undecodable ECDSA guardian was already an error. + #[tokio::test] + async fn br1006_an_undecodable_pq_guardian_key_is_an_error_that_names_its_index() { + for (keys, why) in [ + (json!(["0a0b", "zz", "0c"]), "pq_guardians[1]"), + (json!(["0a0b", 7]), "pq_guardians[1]"), + (json!([null]), "pq_guardians[0]"), + (json!("0a0b"), "pq_guardians is not a list"), + ] { + let node = rpc(move |_, _| { + Some(Ok(json!({ "enabled": true, "guardian_set_index": 1, "guardians": [], + "burn_sequence": 0, "pq_guardians": keys.clone() }))) + }); + let err = match rand::bridge_state(&JsonRpc::new(&node.url)).await { + Err(e) => format!("{e:#}"), + Ok(_) => panic!("{why}: accepted"), + }; + assert!(err.contains(why), "{why}: {err}"); + } + // Hex with a 0x prefix, and no list at all, are still read. + let node = rpc(|_, _| { + Some(Ok(json!({ "enabled": true, "guardian_set_index": 1, "guardians": [], + "burn_sequence": 0, "pq_guardians": ["0x0a0b", "0c"] }))) + }); + let state = rand::bridge_state(&JsonRpc::new(&node.url)).await.unwrap().unwrap(); + assert_eq!(state.pq_guardians, vec![vec![0x0a, 0x0b], vec![0x0c]]); + } +} diff --git a/daemons/tests/daemons.rs b/daemons/tests/daemons.rs index 14efb3b..73232cf 100644 --- a/daemons/tests/daemons.rs +++ b/daemons/tests/daemons.rs @@ -158,7 +158,7 @@ fn a_guardian_needs_a_valid_key_chain_id_and_listen_address() { &base( dir.path(), "http://127.0.0.1:1", - "chain_id = 14\n[guardian]\nlisten = \"127.0.0.1:0\"", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[guardian]\nlisten = \"127.0.0.1:0\"", ), ); assert!(run_failing( @@ -174,13 +174,81 @@ fn a_guardian_needs_a_valid_key_chain_id_and_listen_address() { &base( dir.path(), "http://127.0.0.1:1", - "[guardian]\nlisten = \"999.1.1.1:1\"", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[guardian]\nlisten = \"999.1.1.1:1\"", ), ); assert!( run_failing(guardian_cmd().env("GUARDIAN_KEY", &key), &bad_listen) .contains("binding 999.1.1.1:1") ); + + // BR-1005: a guardian does not start without both rand.chain_id and rand.genesis_hash — + // with a valid key and no PQ seed, before it opens its store or binds its port. + for (extra, names) in [ + ("", "rand.chain_id is not set"), + ("chain_id = 14\n", "rand.genesis_hash is not set"), + ("genesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n", "rand.chain_id is not set"), + ("chain_id = 14\ngenesis_hash = \"\"\n", "rand.genesis_hash must be"), + ] { + let dir = tempfile::tempdir().unwrap(); + let config = write_config( + dir.path(), + &base(dir.path(), "http://127.0.0.1:1", &format!("{extra}[guardian]\nlisten = \"127.0.0.1:0\"")), + ); + let text = run_failing(guardian_cmd().env("GUARDIAN_KEY", &key), &config); + assert!(text.contains(names) && text.contains("BR-1005"), "{names}: {text}"); + assert!(!dir.path().join("data").exists(), "{names}: stopped before the store was opened"); + } +} + +/// BR-1005, the running daemon: a guardian started on its chain keeps running when its node is +/// switched to another one, signs none of that chain's burns, and says so at error level. +#[test] +fn a_running_guardian_signs_no_burn_once_its_node_serves_another_chain() { + use std::sync::atomic::{AtomicU64, Ordering::SeqCst}; + let dir = tempfile::tempdir().unwrap(); + let burn = burn(0, 2, 50_000_000, 0); + let served = std::sync::Arc::new(AtomicU64::new(14)); + let burns = std::sync::Arc::new(AtomicU64::new(0)); + let (chain, count, body) = (served.clone(), burns.clone(), burn.clone()); + let rand = rpc(move |m, _| match m { + "rand_chainId" => Some(Ok(json!(chain.load(SeqCst)))), + "rand_getGenesisHash" => Some(Ok(json!("ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a"))), + "rand_getBridgeState" => Some(Ok(json!({ + "enabled": true, "guardian_set_index": 0, "guardians": [], + "burn_sequence": count.load(SeqCst), "pq_guardians": [], + }))), + "rand_getBridgeBurn" => Some(Ok(json!({ "body_hex": hex::encode(&body.body), "digest": hex::encode(body.digest) }))), + _ => None, + }); + let launch = |port: u16| { + let config = write_config( + dir.path(), + &base( + dir.path(), + &rand.url, + &format!("chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[guardian]\nlisten = \"127.0.0.1:{port}\"\n"), + ), + ); + let mut cmd = guardian_cmd(); + cmd.arg("--config").arg(&config).env("GUARDIAN_KEY", format!("{:064x}", 1)); + cmd + }; + let (daemon, _port) = start_daemon(dir.path(), launch); + // The node is switched to chain 15, and that chain has a burn at sequence 0. + served.store(15, SeqCst); + burns.store(1, SeqCst); + wait_until("the guardian says it is not signing", || { + daemon.log().contains("NOT SIGNING FOR RAND") && daemon.log().contains("serves chain 15") + }); + std::thread::sleep(std::time::Duration::from_millis(2500)); // two more rounds + assert!(!dir.path().join("data/signed/1").exists(), "{}", daemon.log()); + // Switched back, the burn of its own chain is signed. + served.store(14, SeqCst); + wait_until("the burn signed", || dir.path().join(format!("data/signed/1/{:020}.json", 0)).exists()); + // The daemon listens for SIGINT only between rounds; let the round that signed finish. + std::thread::sleep(std::time::Duration::from_millis(400)); + assert!(daemon.stop().success()); } #[test] @@ -192,7 +260,7 @@ fn a_guardian_refuses_a_chain_id_the_node_contradicts() { &base( dir.path(), &node.url, - "chain_id = 14\n[guardian]\nlisten = \"127.0.0.1:0\"", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[guardian]\nlisten = \"127.0.0.1:0\"", ), ); let text = run_failing( @@ -221,7 +289,7 @@ fn a_guardian_refuses_to_start_when_its_rand_node_does_not_answer() { &base( dir.path(), url, - "chain_id = 14\n[guardian]\nlisten = \"127.0.0.1:0\"", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[guardian]\nlisten = \"127.0.0.1:0\"", ), ); let text = run_failing( @@ -230,7 +298,8 @@ fn a_guardian_refuses_to_start_when_its_rand_node_does_not_answer() { ); assert!(text.contains(expect), "{text}"); } - // Without a chain id there is nothing to compare, but the bridge state must still answer. + // Without a chain id a guardian no longer reaches the node at all (audit v14, BR-1005: it + // used to start and compare nothing): it stops on its configuration. let config = write_config( dir.path(), &base( @@ -243,7 +312,7 @@ fn a_guardian_refuses_to_start_when_its_rand_node_does_not_answer() { guardian_cmd().env("GUARDIAN_KEY", format!("{:064x}", 1)), &config, ); - assert!(text.contains("rand_getBridgeState"), "{text}"); + assert!(text.contains("rand.chain_id is not set"), "{text}"); } #[test] @@ -255,7 +324,7 @@ fn a_relayer_refuses_a_chain_id_the_node_contradicts_or_does_not_confirm() { &base( dir.path(), &node.url, - "chain_id = 14\n[relayer]\nguardians = []", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[relayer]\nguardians = []", ), ); let text = run_failing(&mut relayer_cmd(), &config); @@ -269,7 +338,7 @@ fn a_relayer_refuses_a_chain_id_the_node_contradicts_or_does_not_confirm() { &base( dir.path(), &mute.url, - "chain_id = 14\n[relayer]\nguardians = []", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[relayer]\nguardians = []", ), ); let text = run_failing(&mut relayer_cmd(), &config); @@ -284,12 +353,12 @@ fn a_rand_cursor_ahead_of_the_chain_stops_either_daemon_at_startup() { ( "guardian", guardian_cmd(), - "chain_id = 14\n[guardian]\nlisten = \"127.0.0.1:0\"", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[guardian]\nlisten = \"127.0.0.1:0\"", ), ( "relayer", relayer_cmd(), - "chain_id = 14\n[relayer]\nguardians = []", + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[relayer]\nguardians = []", ), ] { let dir = tempfile::tempdir().unwrap(); @@ -372,6 +441,7 @@ fn rand_node(burns: Vec, chain_id: u64, guardians: &[GuardianKey]) -> .collect(); rpc(move |m, p| match m { "rand_chainId" => Some(Ok(json!(chain_id))), + "rand_getGenesisHash" => Some(Ok(json!("ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a"))), "rand_getBridgeState" => Some(Ok(json!({ "enabled": true, "guardian_set_index": 0, "guardians": addresses, "burn_sequence": burns.len(), "pq_guardians": [], @@ -432,7 +502,7 @@ fn a_guardian_signs_what_it_watches_and_serves_it_until_interrupted() { dir.path(), &rand.url, &format!( - "chain_id = 14\n\n[[evm]]\nname = \"eth\"\nchain = 2\nkind = \"evm\"\nrpc = {:?}\ncontract = {CONTRACT:?}\nfinality = 0\n\n\ + "chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n\n[[evm]]\nname = \"eth\"\nchain = 2\nkind = \"evm\"\nrpc = {:?}\ncontract = {CONTRACT:?}\nfinality = 0\n\n\ [solana]\nrpc = {:?}\nprogram = \"11111111111111111111111111111111\"\n\n[guardian]\nlisten = \"127.0.0.1:{port}\"\n", eth.url, sol.url ), @@ -501,14 +571,19 @@ fn a_guardian_with_no_pq_seed_warns_and_signs_classically() { let deposit = eth_lock(0, [9; 32]); let eth = evm_node(vec![evm_log(CONTRACT, &deposit, 50)], false); // A Rand node without a bridge: the source has nothing to offer and says so. - let rand = rpc(|m, _| (m == "rand_getBridgeState").then(|| Ok(json!({ "enabled": false })))); + let rand = rpc(|m, _| match m { + "rand_getBridgeState" => Some(Ok(json!({ "enabled": false }))), + "rand_chainId" => Some(Ok(json!(14))), + "rand_getGenesisHash" => Some(Ok(json!("ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a"))), + _ => None, + }); let launch = |port: u16| { let config = write_config( dir.path(), &base( dir.path(), &rand.url, - &format!("[[evm]]\nname = \"eth\"\nchain = 2\nkind = \"evm\"\nrpc = {:?}\ncontract = {CONTRACT:?}\nfinality = \"latest\"\n\n[guardian]\nlisten = \"127.0.0.1:{port}\"\n", eth.url), + &format!("chain_id = 14\ngenesis_hash = \"ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a\"\n[[evm]]\nname = \"eth\"\nchain = 2\nkind = \"evm\"\nrpc = {:?}\ncontract = {CONTRACT:?}\nfinality = \"latest\"\n\n[guardian]\nlisten = \"127.0.0.1:{port}\"\n", eth.url), ), ); let mut cmd = guardian_cmd(); diff --git a/daemons/tests/rpc_quorum.rs b/daemons/tests/rpc_quorum.rs index ee42bb2..7c85a62 100644 --- a/daemons/tests/rpc_quorum.rs +++ b/daemons/tests/rpc_quorum.rs @@ -210,6 +210,7 @@ async fn rand_burns_need_the_same_body_from_a_quorum_of_nodes() { "burn_sequence": 1, "pq_guardians": [], }))), "rand_getBridgeBurn" => Some(Ok(r(p[0].as_u64().unwrap()))), + "rand_chainId" => Some(Ok(json!(21))), _ => None, }) }; @@ -220,6 +221,7 @@ async fn rand_burns_need_the_same_body_from_a_quorum_of_nodes() { emitter: hex::encode(RAND_EMITTER), start_sequence: 0, chain_id: Some(21), + genesis_hash: None, }; let (a, b, liar) = (node(50_000_000), node(50_000_000), node(90_000_000_000)); let agree = sources::rand_quorum(&cfg(&[&a.url, &b.url])).unwrap(); diff --git a/daemons/tests/sources.rs b/daemons/tests/sources.rs index b4f043d..05d2350 100644 --- a/daemons/tests/sources.rs +++ b/daemons/tests/sources.rs @@ -732,6 +732,7 @@ fn rand_cfg(url: &str, start: u64) -> RandConfig { emitter: hex::encode(RAND_EMITTER), start_sequence: start, chain_id: Some(14), + genesis_hash: None, } } @@ -747,7 +748,7 @@ fn rand_node(burn_sequence: u64, row: impl Fn(u64) -> Value + Send + Sync + 'sta "guardian_set_index": 1, "guardians": [CONTRACT, "0x2222222222222222222222222222222222222222"], "burn_sequence": burn_sequence, - "pq_guardians": ["0a0b", "zz", "0c"], + "pq_guardians": ["0a0b", "0c"], }))), "rand_getBridgeBurn" => Some(Ok(row(p[0].as_u64().unwrap()))), "rand_chainId" => Some(Ok(json!(14))), @@ -770,7 +771,8 @@ async fn the_bridge_state_and_chain_id_are_read_from_the_node() { assert_eq!( state.pq_guardians, vec![vec![0x0a, 0x0b], vec![0x0c]], - "an undecodable key is dropped" + "index-aligned with the guardians; an undecodable one is an error (audit v14, BR-1006: \ + this fake used to carry a \"zz\" entry and this test asserted it was dropped)" ); assert_eq!(rand::chain_id(&client).await.unwrap(), 14); assert_eq!( @@ -886,7 +888,12 @@ async fn a_poll_takes_at_most_a_batch_of_64() { #[tokio::test] async fn a_node_with_no_bridge_or_a_missing_burn_yields_nothing() { - let off = rpc(|m, _| (m == "rand_getBridgeState").then(|| Ok(json!({ "enabled": false })))); + // (It answers rand_chainId: since audit v14, BR-1005, every poll confirms the chain first.) + let off = rpc(|m, _| match m { + "rand_getBridgeState" => Some(Ok(json!({ "enabled": false }))), + "rand_chainId" => Some(Ok(json!(14))), + _ => None, + }); let source = RandSource::new(&rand_cfg(&off.url, 0)); let (messages, next) = source .poll(&Cursor { @@ -919,17 +926,17 @@ async fn a_cursor_ahead_of_the_chain_is_refused_at_startup_and_on_every_poll() { next_sequence: n, }; // At or behind the chain: fine. - rand::check_startup(&client, Some(14), &at(3)) + rand::check_startup(&client, Some(14), None, &at(3)) .await .unwrap(); - rand::check_startup(&client, Some(14), &at(0)) + rand::check_startup(&client, Some(14), None, &at(0)) .await .unwrap(); - rand::check_startup(&client, None, &at(3)).await.unwrap(); + rand::check_startup(&client, None, None, &at(3)).await.unwrap(); // Ahead: refused, naming both numbers. let err = format!( "{:#}", - rand::check_startup(&client, Some(14), &at(4)) + rand::check_startup(&client, Some(14), None, &at(4)) .await .unwrap_err() ); @@ -950,7 +957,7 @@ async fn a_cursor_ahead_of_the_chain_is_refused_at_startup_and_on_every_poll() { // answer, stops the daemon rather than being skipped. let err = format!( "{:#}", - rand::check_startup(&client, Some(15), &at(0)) + rand::check_startup(&client, Some(15), None, &at(0)) .await .unwrap_err() ); @@ -961,7 +968,7 @@ async fn a_cursor_ahead_of_the_chain_is_refused_at_startup_and_on_every_poll() { let mute = rpc(|_, _| None); let err = format!( "{:#}", - rand::check_startup(&JsonRpc::new(&mute.url), Some(14), &at(0)) + rand::check_startup(&JsonRpc::new(&mute.url), Some(14), None, &at(0)) .await .unwrap_err() ); @@ -970,14 +977,14 @@ async fn a_cursor_ahead_of_the_chain_is_refused_at_startup_and_on_every_poll() { // answer so the cursor can be checked. let err = format!( "{:#}", - rand::check_startup(&JsonRpc::new(&mute.url), None, &at(0)) + rand::check_startup(&JsonRpc::new(&mute.url), None, None, &at(0)) .await .unwrap_err() ); assert!(err.contains("rand_getBridgeState"), "{err}"); // A chain without a bridge has no burn sequence to be ahead of. let off = rpc(|m, _| (m == "rand_getBridgeState").then(|| Ok(json!({ "enabled": false })))); - rand::check_startup(&JsonRpc::new(&off.url), None, &at(9)) + rand::check_startup(&JsonRpc::new(&off.url), None, None, &at(9)) .await .unwrap(); } From 42ab807777b3230cbab5dc351ccaf468241d4b21 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:37:03 +0800 Subject: [PATCH 5/6] BR-1002, BR-1007: cosign prints, verifies and asks before it signs; the rotation quorum rule has a test of its own BR-1002: rand-bridge-gov cosign digested the body of whatever envelope it was given and signed it with the PQ seeds. It now decodes and prints the whole attestation (governance::describe), verifies it against the current guardian set before a seed is read (governance::verify_for_cosign: verify_rotation for a rotation; for a deposit to Rand a canonical attestation carrying the current set's quorum, and only with --allow-transfer), refuses anything else, and needs a confirmation: the digest's first 8 hex typed at a terminal, or --yes without one. cosign now takes --current-index and --current-guardians like verify. BR-1007 (withdrawn as a finding; the test gap stands): four signatures of a set of six are refused by verify_rotation, on an attestation assembled by hand so that only the verifier's quorum rule can refuse it. With the check_indices call removed this test fails and none of the authors' tests in the governance suites does (the new cosign test, which shares the rule, fails too). Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01GFs5h2CVCmdBKerZzH2Xrx --- daemons/src/bin/gov.rs | 67 +++++++++++++++- daemons/src/governance.rs | 130 +++++++++++++++++++++++++++++-- daemons/tests/gov_bin.rs | 147 ++++++++++++++++++++++++++++++++++++ daemons/tests/governance.rs | 46 +++++++++++ 4 files changed, 380 insertions(+), 10 deletions(-) diff --git a/daemons/src/bin/gov.rs b/daemons/src/bin/gov.rs index debe020..01c16be 100644 --- a/daemons/src/bin/gov.rs +++ b/daemons/src/bin/gov.rs @@ -251,7 +251,23 @@ enum Command { /// Dilithium2 co-signatures over an attestation, for its submission to Rand /// (`spec/PQ-COSIGNATURE.md`): a rotation needs them like any other BridgeAttest. /// Writes `[{"index", "signature"}]`, what `rand bridge-mint --pq @file` reads. + /// + /// The attestation is decoded and printed in full, then verified against the CURRENT + /// guardian set exactly as `verify` does (BR-1002); anything that fails is refused before + /// a seed is read. A rotation is what this is for; a deposit needs `--allow-transfer`. + /// Signing needs a confirmation: typed at the prompt, or `--yes` when there is no terminal. Cosign { + #[command(flatten)] + current: CurrentSet, + /// Co-sign a deposit (a transfer to Rand that carries the current set's quorum) + /// instead of a rotation. The guardian daemons co-sign deposits themselves; by hand + /// is for a deposit they signed without a PQ key. + #[arg(long)] + allow_transfer: bool, + /// Sign without asking: you have read the body this command prints. Required when + /// standard input is not a terminal. + #[arg(long)] + yes: bool, #[arg(long)] attestation_file: PathBuf, /// The Rand chain id the co-signatures name. @@ -677,18 +693,61 @@ async fn main() -> Result<()> { } } Command::Cosign { + current, + allow_transfer, + yes, attestation_file, rand_chain_id, pq_guardians_file, seed_envs, out, } => { + use bridge_daemons::governance::{describe, verify_for_cosign, Cosignable}; use bridge_daemons::pq; + use std::io::IsTerminal; let attestation = read_attestation(&attestation_file)?; - let mu = bridge_daemons::crypto::digest( - bridge_codec::Attestation::body_bytes(&attestation) - .map_err(|e| anyhow!("{e:?}"))?, - ); + // BR-1002: what is about to be signed, in words, before anything else — then the + // same verification `verify` runs. No seed is read until both are done. + println!("About to co-sign, for Rand chain {rand_chain_id}:\n"); + print!("{}", describe(&attestation)?); + println!(); + let checked = verify_for_cosign( + &attestation, + current.current_index, + &addresses(¤t.current_guardians)?, + ) + .context("REFUSED: this attestation does not verify against the current guardian set, so it is not co-signed")?; + match &checked { + Cosignable::Rotation(r) => println!( + "verified: a rotation from set {} to set {}, signed by current guardians {:?}", + current.current_index, r.new_index, r.signer_indices + ), + Cosignable::Deposit { signer_indices, .. } => { + println!("verified: a deposit to Rand, signed by current guardians {signer_indices:?}"); + if !allow_transfer { + bail!( + "REFUSED: this is a deposit, not a rotation. The guardian daemons \ + co-sign deposits; pass --allow-transfer to do it by hand" + ); + } + } + } + let mu = checked.digest(); + if !yes { + if !std::io::stdin().is_terminal() { + bail!( + "REFUSED: not confirmed. Read the body above, then pass --yes \ + (standard input is not a terminal, so there is no prompt)" + ); + } + let short = &hex::encode(mu)[..8]; + println!("To co-sign exactly this, type the first 8 hex digits of its digest ({short}…):"); + let mut typed = String::new(); + std::io::stdin().read_line(&mut typed)?; + if typed.trim().trim_start_matches("0x") != short { + bail!("REFUSED: not confirmed"); + } + } let file: serde_json::Value = serde_json::from_str(&std::fs::read_to_string(&pq_guardians_file)?)?; let pq_guardians: Vec> = file["pq_guardians"] diff --git a/daemons/src/governance.rs b/daemons/src/governance.rs index e10625f..89d324e 100644 --- a/daemons/src/governance.rs +++ b/daemons/src/governance.rs @@ -161,6 +161,23 @@ pub fn verify_rotation( } check_new_keys(&upgrade.keys)?; + let digest = check_signatures(attestation, &decoded, current_set)?; + Ok(Rotation { + digest, + new_index: upgrade.new_index, + new_keys: upgrade.keys, + signer_indices: decoded.signatures.iter().map(|s| s.index).collect(), + }) +} + +/// The signature rules every verifier applies, on the bytes as given: a quorum of the set +/// (`bridge_codec::check_indices`: indices in range, strictly ascending, at least +/// `n * 2 / 3 + 1` of them), each recovering to the guardian at its index. Returns the digest. +fn check_signatures( + attestation: &[u8], + decoded: &Attestation, + current_set: &[[u8; 20]], +) -> Result<[u8; 32]> { bridge_codec::check_indices(&decoded.signatures, current_set.len()) .map_err(|e| anyhow!("signatures: {e:?}"))?; let body_bytes = Attestation::body_bytes(attestation).map_err(|e| anyhow!("{e:?}"))?; @@ -180,12 +197,113 @@ pub fn verify_rotation( ); } } - Ok(Rotation { - digest, - new_index: upgrade.new_index, - new_keys: upgrade.keys, - signer_indices: decoded.signatures.iter().map(|s| s.index).collect(), - }) + Ok(digest) +} + +/// An attestation in words, for the person about to sign something over it (BR-1002): every +/// field of the envelope and the body, and the payload decoded. Says so when it cannot decode. +pub fn describe(attestation: &[u8]) -> Result { + use std::fmt::Write; + let a = Attestation::decode(attestation).map_err(|e| anyhow!("undecodable attestation: {e:?}"))?; + let body_bytes = Attestation::body_bytes(attestation).map_err(|e| anyhow!("{e:?}"))?; + let mut t = String::new(); + let _ = writeln!(t, "attestation {} bytes, digest 0x{}", attestation.len(), hex::encode(crypto::digest(body_bytes))); + let _ = writeln!( + t, + "signed by guardian set {}, {} signature(s), indices {:?}", + a.guardian_set_index, + a.signatures.len(), + a.signatures.iter().map(|s| s.index).collect::>() + ); + let b = &a.body; + let _ = writeln!(t, "timestamp {}", b.timestamp); + let _ = writeln!(t, "nonce {}", b.nonce); + let _ = writeln!(t, "emitter chain {} address 0x{}", b.emitter_chain, hex::encode(b.emitter_address)); + let _ = writeln!(t, "sequence {}", b.sequence); + let _ = writeln!(t, "consistency {}", b.consistency_level); + match Payload::decode(&b.payload) { + Ok(Payload::GuardianSetUpgrade(u)) => { + let _ = writeln!(t, "payload GUARDIAN-SET UPGRADE to set {} with {} key(s)", u.new_index, u.keys.len()); + for (i, k) in u.keys.iter().enumerate() { + let _ = writeln!(t, " new [{i}] 0x{}", hex::encode(k)); + } + } + Ok(Payload::Transfer(x)) => { + let _ = writeln!(t, "payload TRANSFER"); + let amount = |v: Option| v.map(|n| n.to_string()).unwrap_or_else(|| "above u128".into()); + let _ = writeln!(t, " amount {} (8-decimal units), fee {}", amount(x.amount_u128()), amount(x.fee_u128())); + let _ = writeln!(t, " token chain {} address 0x{}", x.token_chain, hex::encode(x.token_address)); + let _ = writeln!(t, " recipient chain {} address 0x{}", x.to_chain, hex::encode(x.to)); + } + Err(e) => { + let _ = writeln!(t, "payload UNDECODABLE ({e:?}): 0x{}", hex::encode(&b.payload)); + } + } + Ok(t) +} + +/// What `verify_for_cosign` found the attestation to be. +#[derive(Debug, PartialEq, Eq)] +pub enum Cosignable { + Rotation(Rotation), + /// A deposit: a transfer from a source chain to Rand, carrying the current set's quorum. + Deposit { digest: [u8; 32], signer_indices: Vec }, +} + +impl Cosignable { + pub fn digest(&self) -> [u8; 32] { + match self { + Cosignable::Rotation(r) => r.digest, + Cosignable::Deposit { digest, .. } => *digest, + } + } +} + +/// What must hold before a post-quantum key signs over an attestation by hand (BR-1002). A +/// rotation passes every rule of [`verify_rotation`]. Anything else must be a canonical +/// attestation of a transfer to Rand from another chain that already carries a quorum of the +/// current set's signatures, each recovering to its guardian — what Rand itself would check of +/// the classical half. An unsigned body, a body signed by another set, a release, a payload +/// that does not decode: all refused. +pub fn verify_for_cosign( + attestation: &[u8], + current_index: u32, + current_set: &[[u8; 20]], +) -> Result { + let decoded = + Attestation::decode(attestation).map_err(|e| anyhow!("undecodable attestation: {e:?}"))?; + match Payload::decode(&decoded.body.payload) { + Ok(Payload::GuardianSetUpgrade(_)) => { + verify_rotation(attestation, current_index, current_set).map(Cosignable::Rotation) + } + Ok(Payload::Transfer(transfer)) => { + if decoded.encode() != attestation { + bail!("attestation is not canonically encoded"); + } + if decoded.guardian_set_index != current_index { + bail!( + "signed by set {}, not the current set {current_index}", + decoded.guardian_set_index + ); + } + if decoded.body.emitter_chain == CHAIN_RAND || transfer.to_chain != CHAIN_RAND { + bail!( + "a transfer from chain {} to chain {}: only a deposit to Rand is co-signed", + decoded.body.emitter_chain, + transfer.to_chain + ); + } + if transfer.amount_u128() == Some(0) { + bail!("zero amount"); + } + let digest = check_signatures(attestation, &decoded, current_set)?; + Ok(Cosignable::Deposit { + digest, + signer_indices: decoded.signatures.iter().map(|s| s.index).collect(), + }) + } + Err(e) => bail!("the payload is neither a rotation nor a transfer: {e:?}"), + } } /// `submitGuardianSetUpgrade(bytes)` calldata for the EVM-family endpoints. diff --git a/daemons/tests/gov_bin.rs b/daemons/tests/gov_bin.rs index 4735a94..492260f 100644 --- a/daemons/tests/gov_bin.rs +++ b/daemons/tests/gov_bin.rs @@ -330,6 +330,11 @@ fn cosign_writes_a_pq_quorum_that_the_ledger_rules_accept() { let mut c = gov(); c.args([ "cosign", + "--current-index", + "0", + "--current-guardians", + ¤t(), + "--yes", "--rand-chain-id", "14", "--seed-envs", @@ -371,6 +376,11 @@ fn cosign_refuses_a_seed_that_is_not_a_guardian_and_a_short_quorum() { let mut c = gov(); c.args([ "cosign", + "--current-index", + "0", + "--current-guardians", + ¤t(), + "--yes", "--rand-chain-id", "14", "--seed-envs", @@ -1150,3 +1160,140 @@ fn submit_tron_reads_consumed_from_the_node() { assert!(o.status.success(), "{}", err(&o)); assert_eq!(out(&o).trim(), "AlreadyDone"); } + +// ---- audit v14, BR-1002: cosign reads, verifies and asks before it signs --------------- + +/// `cosign` over `file`, with PQ1..PQ3 set, against the three current guardians. +fn cosign(dir: &Path, file: &Path, extra: &[&str]) -> Output { + let pq_file = pq_set(dir, &[1, 2, 3]); + let mut c = gov(); + c.args(["cosign", "--current-index", "0", "--current-guardians", ¤t()]) + .args(["--rand-chain-id", "21", "--seed-envs", "PQ1,PQ2,PQ3", "--attestation-file"]) + .arg(file) + .arg("--pq-guardians-file") + .arg(&pq_file) + .arg("--out") + .arg(dir.join("pq-sigs.json")) + .args(extra) + .stdin(std::process::Stdio::null()); + with_seeds(&mut c, &[1, 2, 3]); + c.output().unwrap() +} + +/// A deposit of 1.00000000 from Ethereum to Rand, signed by the current guardians in `signers`. +fn deposit_file(dir: &Path, name: &str, signers: &[u8]) -> std::path::PathBuf { + let message = lock(2, word("0x1111111111111111111111111111111111111111"), 5, [9; 32]); + let attestation = bridge_codec::Attestation { + guardian_set_index: 0, + signatures: signers.iter().map(|&i| key(i).sign(&message.digest).unwrap().indexed(i - 1)).collect(), + body: message.decoded(), + }; + let path = dir.join(name); + std::fs::write(&path, hex::encode(attestation.encode())).unwrap(); + path +} + +/// The auditor's case: an unsigned deposit body in an envelope. `cosign` wrote a post-quantum +/// quorum over it, identical to a mint co-signature. It now prints what it was given, finds no +/// quorum of the current set on it, and signs nothing — whatever flags it is given. +#[test] +fn cosign_refuses_an_envelope_the_current_set_did_not_sign() { + let dir = tempfile::tempdir().unwrap(); + let sigs = dir.path().join("pq-sigs.json"); + let unsigned = deposit_file(dir.path(), "unsigned.hex", &[]); + for flags in [&["--yes"][..], &["--yes", "--allow-transfer"]] { + let o = cosign(dir.path(), &unsigned, flags); + assert!(!o.status.success()); + assert!(out(&o).contains("TRANSFER") && out(&o).contains("amount 100000000"), "{}", out(&o)); + assert!(err(&o).contains("REFUSED") && err(&o).contains("NoQuorum"), "{}", err(&o)); + assert!(!sigs.exists(), "nothing was signed"); + } + // Two of three is short of the quorum of three; a signature by a key outside the set. + let short = deposit_file(dir.path(), "short.hex", &[1, 2]); + assert!(err(&cosign(dir.path(), &short, &["--yes", "--allow-transfer"])).contains("NoQuorum")); + // A rotation verified against another set than the one that signed it. + assert!(rotate(dir.path(), &[]).status.success()); + let rotation = dir.path().join("rotation.hex"); + let pq_file = pq_set(dir.path(), &[1, 2, 3]); + let mut c = gov(); + c.args(["cosign", "--yes", "--current-index", "0", "--current-guardians"]) + .arg(format!("{},{},{}", addr(2), addr(1), addr(3))) + .args(["--rand-chain-id", "21", "--seed-envs", "PQ1,PQ2,PQ3", "--attestation-file"]) + .arg(&rotation) + .arg("--pq-guardians-file") + .arg(&pq_file) + .arg("--out") + .arg(&sigs); + with_seeds(&mut c, &[1, 2, 3]); + let o = c.output().unwrap(); + assert!(err(&o).contains("REFUSED") && err(&o).contains("does not recover to guardian"), "{}", err(&o)); + // …and against the wrong current index. + let mut c = gov(); + c.args(["cosign", "--yes", "--current-index", "4", "--current-guardians", ¤t()]) + .args(["--rand-chain-id", "21", "--seed-envs", "PQ1,PQ2,PQ3", "--attestation-file"]) + .arg(&rotation) + .arg("--pq-guardians-file") + .arg(&pq_file) + .arg("--out") + .arg(&sigs); + with_seeds(&mut c, &[1, 2, 3]); + assert!(err(&c.output().unwrap()).contains("must be signed by the current set 4")); + assert!(!sigs.exists()); +} + +/// A good rotation: the whole body is printed before anything is signed, and without a +/// confirmation (no terminal, no --yes) nothing is. +#[test] +fn cosign_prints_the_body_and_needs_a_confirmation() { + let dir = tempfile::tempdir().unwrap(); + assert!(rotate(dir.path(), &[]).status.success()); + let rotation = dir.path().join("rotation.hex"); + let sigs = dir.path().join("pq-sigs.json"); + + let o = cosign(dir.path(), &rotation, &[]); + assert!(!o.status.success()); + let text = out(&o); + for shown in [ + "About to co-sign, for Rand chain 21", + "signed by guardian set 0, 3 signature(s), indices [0, 1, 2]", + "timestamp 1800000000", + "emitter chain 1 address 0x", + "GUARDIAN-SET UPGRADE to set 1 with 2 key(s)", + &format!("new [0] {}", addr(7)), + &format!("new [1] {}", addr(8)), + "verified: a rotation from set 0 to set 1", + ] { + assert!(text.contains(shown), "{shown}\n{text}"); + } + assert!(err(&o).contains("not confirmed") && err(&o).contains("--yes"), "{}", err(&o)); + assert!(!sigs.exists(), "nothing is signed without the confirmation"); + + let o = cosign(dir.path(), &rotation, &["--yes"]); + assert!(o.status.success(), "{}", err(&o)); + assert!(sigs.exists()); +} + +/// A deposit that does carry the current set's quorum is still not what `cosign` is for: it +/// takes --allow-transfer, and a release (a burn on Rand) is refused even then. +#[test] +fn cosign_takes_a_signed_deposit_only_when_told_to() { + let dir = tempfile::tempdir().unwrap(); + let sigs = dir.path().join("pq-sigs.json"); + let deposit = deposit_file(dir.path(), "deposit.hex", &[1, 2, 3]); + let o = cosign(dir.path(), &deposit, &["--yes"]); + assert!(err(&o).contains("this is a deposit, not a rotation") && !sigs.exists(), "{}", err(&o)); + let o = cosign(dir.path(), &deposit, &["--yes", "--allow-transfer"]); + assert!(o.status.success() && sigs.exists(), "{}", err(&o)); + std::fs::remove_file(&sigs).unwrap(); + + let release = burn(0, 2, 50_000_000, 0); + let attestation = bridge_codec::Attestation { + guardian_set_index: 0, + signatures: (1..=3u8).map(|i| key(i).sign(&release.digest).unwrap().indexed(i - 1)).collect(), + body: release.decoded(), + }; + let path = dir.path().join("release.hex"); + std::fs::write(&path, hex::encode(attestation.encode())).unwrap(); + let o = cosign(dir.path(), &path, &["--yes", "--allow-transfer"]); + assert!(err(&o).contains("only a deposit to Rand is co-signed") && !sigs.exists(), "{}", err(&o)); +} diff --git a/daemons/tests/governance.rs b/daemons/tests/governance.rs index 20d5bd8..d8a3639 100644 --- a/daemons/tests/governance.rs +++ b/daemons/tests/governance.rs @@ -341,3 +341,49 @@ fn verifying_refuses_a_set_above_the_solana_bound() { let err = sign_rotation(&body, 0, ¤t, &guardians).unwrap_err(); assert!(err.to_string().contains("got 11"), "{err}"); } + +// ---- audit v14, BR-1007 (survivor): the quorum rule of a rotation, pinned ------------ + +/// `verify_rotation` applies the quorum rule through `bridge_codec::check_indices`, and no test +/// in this repository's governance suites failed with that call taken out: every negative above +/// is stopped by `sign_rotation`'s own count first, or by another rule. Here the attestation is +/// assembled by hand, so only the verifier stands between four signatures and a set of six. +#[test] +fn four_signatures_of_a_set_of_six_are_refused() { + let guardians: Vec = (1..=6u8) + .map(|i| GuardianKey::from_hex(&format!("{i:064x}")).unwrap()) + .collect(); + let current: Vec<[u8; 20]> = guardians.iter().map(|k| k.address()).collect(); + let body = rotation_body(0, &[[7u8; 20], [8u8; 20]], 1_800_000_000, 0, 1).unwrap(); + let mu = bridge_daemons::crypto::digest(&body.encode()); + let signed_by = |indices: &[usize]| { + Attestation { + guardian_set_index: 0, + signatures: indices + .iter() + .map(|&i| guardians[i].sign(&mu).unwrap().indexed(i as u8)) + .collect(), + body: body.clone(), + } + .encode() + }; + + // Six guardians need 6 * 2 / 3 + 1 = 5. Four valid signatures, each from a guardian of the + // set, in order, are not a rotation — whichever four. + for four in [[0usize, 1, 2, 3], [2, 3, 4, 5], [0, 2, 3, 5]] { + let err = verify_rotation(&signed_by(&four), 0, ¤t).unwrap_err(); + assert!(format!("{err:#}").contains("NoQuorum"), "{four:?}: {err:#}"); + } + for fewer in [&[][..], &[0], &[0, 1, 2]] { + assert!(verify_rotation(&signed_by(fewer), 0, ¤t).is_err(), "{fewer:?}"); + } + // Five are, and so are all six. + let checked = verify_rotation(&signed_by(&[0, 1, 2, 3, 4]), 0, ¤t).unwrap(); + assert_eq!(checked.signer_indices, vec![0, 1, 2, 3, 4]); + verify_rotation(&signed_by(&[0, 1, 2, 3, 4, 5]), 0, ¤t).unwrap(); + // The same four are a quorum of a set of five (5 * 2 / 3 + 1 = 4): it is the set's size + // that refused them above, nothing about the signatures. + verify_rotation(&signed_by(&[0, 1, 2, 3]), 0, ¤t[..5]).unwrap(); + // And the tool's own cosign check refuses the four as well. + assert!(bridge_daemons::governance::verify_for_cosign(&signed_by(&[0, 1, 2, 3]), 0, ¤t).is_err()); +} From 1e5530f8c7be2dca8c3fc22f21f63e3546031822 Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:38:21 +0800 Subject: [PATCH 6/6] BR-1009: the Tron pauser must be a multi-signature account, and the two documents that disagree on Tron permissions say so rand-bridge-audit --governance passed Tron rule 13 for any pauser address with code: one byte of code and a one-signature account permission was a PASS. The pauser is now held to the admin multisig's rule, as docs/governance.md describes it: an account whose owner and active permissions need at least min_threshold signatures; a contract fails, and the account's permissions are read whether or not the address has code. The authors' test that asserted a contract passes now asserts the weak cases fail. docs/governance.md says the Tron multi-signature permissions are still to do; docs/mainnet-deployment.md records them as done on 2026-09-26. Both places now carry an UNRECONCILED note; neither was changed otherwise, since only a read of the chain can say which is right. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01GFs5h2CVCmdBKerZzH2Xrx --- daemons/config.example.toml | 5 ++- daemons/src/bin/audit.rs | 8 ++-- daemons/src/gov_audit.rs | 84 ++++++++++++++++++++++--------------- docs/governance.md | 9 ++++ docs/mainnet-deployment.md | 13 ++++++ 5 files changed, 79 insertions(+), 40 deletions(-) diff --git a/daemons/config.example.toml b/daemons/config.example.toml index 62116d8..d5af3c9 100644 --- a/daemons/config.example.toml +++ b/daemons/config.example.toml @@ -138,8 +138,9 @@ listen = "127.0.0.1:7080" # POST /v1/recipients {recipient_hash, addr # singleton, fallback handler not the Safe itself, no enabled module, getThreshold() >= min_threshold, at least # that many owners (Tron: an account whose owner and active permissions each # need >= min_threshold keys); -# pauser() — != admin(), != admin_multisig; a Safe as above (Tron: a -# contract, or an account needing >= min_threshold signatures); +# pauser() — != admin(), != admin_multisig; a Safe as above (Tron: like the +# admin multisig, an account whose owner and active permissions each need +# >= min_threshold signatures; an address with code is NOT enough, BR-1009); # pendingAdmin() — zero; # Solana — Config.admin is the vault ["multisig", solana_multisig, "vault", # solana_vault_index] of Squads v4; no pending_admin; the multisig is diff --git a/daemons/src/bin/audit.rs b/daemons/src/bin/audit.rs index 709ba5b..b764583 100644 --- a/daemons/src/bin/audit.rs +++ b/daemons/src/bin/audit.rs @@ -516,11 +516,9 @@ async fn evm_governance(endpoint: &EvmConfig, policy: &GovernanceConfig) -> Resu Flavor::Evm => (SafeReads::not_asked("no code"), None), Flavor::Tron => ( SafeReads::not_asked("not asked on Tron"), - if pauser_code.is_empty() { - tron_signers(&endpoint.rpc, &pauser20).await - } else { - None - }, + // Read whether or not the address has code (BR-1009): code is no longer a pass, + // and the rule reports what the account's permissions are either way. + tron_signers(&endpoint.rpc, &pauser20).await, ), }; let reads = EvmReads { diff --git a/daemons/src/gov_audit.rs b/daemons/src/gov_audit.rs index 460f8a9..20d9de8 100644 --- a/daemons/src/gov_audit.rs +++ b/daemons/src/gov_audit.rs @@ -17,7 +17,8 @@ //! singleton, no module, `getThreshold() >= min_threshold`, at least that //! many owners) on EVM, or a Tron account needing that many signatures. //! - EVM / Tron pauser: `!= admin`, `!=` the admin multisig; a Safe as above -//! (EVM) or a contract / multi-signature account (Tron). +//! (EVM) or, like the admin multisig, a Tron account needing that many +//! signatures — never merely an address with code (BR-1009). //! `pendingAdmin()` is zero. //! - Solana: `Config::admin` is the configured Squads v4 vault; no //! `pending_admin`; the multisig is autonomous (`config_authority` default), @@ -1085,18 +1086,25 @@ pub fn evm_rules(reads: &EvmReads, flavor: Flavor, policy: &GovernanceConfig) -> flavor, policy, ), - Flavor::Tron => { - let name = "pauser is a contract or a multi-signature account".to_string(); - if !reads.pauser_code.is_empty() { - rule( - name, - true, - format!("contract ({} bytes)", reads.pauser_code.len()), - ) - } else { - signers_rule(name, &shown(pauser), reads.tron_pauser_signers, policy) - } - } + // BR-1009: on Tron the pauser is held to the rule the admin multisig is — a native + // multi-signature account whose owner and active permissions each need at least + // `min_threshold` signatures (docs/governance.md). Having code is not that: there is + // no pinned multisig contract on Tron to compare a contract with, so a contract + // pauser — one byte of code used to be a PASS — fails, as it does for the admin + // multisig. + Flavor::Tron => multisig_rule( + format!( + "pauser is a multi-signature account needing >= {} signatures", + policy.min_threshold + ), + &format!("pauser {}", shown(pauser)), + pauser, + &reads.pauser_code, + &reads.pauser_safe, + reads.tron_pauser_signers, + flavor, + policy, + ), }); // 14. No admin transfer in flight. @@ -2178,6 +2186,9 @@ mod tests { r.admin_multisig_safe = SafeReads::not_asked("not asked on Tron"); r.tron_admin_multisig_signers = Some(3); r.pauser_safe = SafeReads::not_asked("not asked on Tron"); + // The pause account: no code, owner 3 of 5 and active 2 of 5 need two signatures. + r.pauser_code.clear(); + r.tron_pauser_signers = Some(2); r } @@ -2203,31 +2214,38 @@ mod tests { only_fails(&r, Flavor::Tron, NO_PROXY); } + /// Audit v14, BR-1009. This test was `tron_accepts_a_contract_or_a_multisignature_pauser` + /// and its first assertion was that any pauser with code passes. One byte of code with a + /// one-signature account permission was a PASS. #[test] - fn tron_accepts_a_contract_or_a_multisignature_pauser() { + fn tron_accepts_only_a_multisignature_account_as_pauser() { use Status::*; let p = policy(); + let pauser = |code: &[u8], signers: Option| { + let mut r = tron_compliant(); + r.pauser_code = code.to_vec(); + r.tron_pauser_signers = signers; + evm_rules(&r, Flavor::Tron, &p) + }; + assert_eq!(pauser(&[], Some(2))[PAUSER_MS].status, Pass, "a 2-of-n account"); + assert_eq!(pauser(&[], Some(3))[PAUSER_MS].status, Pass, "a 3-of-n account"); + assert!(pauser(&[], Some(2))[PAUSER_MS].name.contains("needing >= 2 signatures")); + // The auditor's weak cases. + let rules = pauser(&[0x00], Some(1)); + assert_eq!(rules[PAUSER_MS].status, Fail, "one byte of code, one signature"); + assert!(rules[PAUSER_MS].observed.contains("is a contract"), "{:?}", rules[PAUSER_MS]); + assert_eq!(failures(&rules), 1); + assert_eq!(pauser(&[0x00], None)[PAUSER_MS].status, Fail, "one byte of code, unread"); + assert_eq!(pauser(&[0x60; 4000], Some(5))[PAUSER_MS].status, Fail, "any contract"); + assert_eq!(pauser(&[], Some(1))[PAUSER_MS].status, Fail, "a single key"); + assert_eq!(pauser(&[], Some(0))[PAUSER_MS].status, Fail); + // A threshold the policy raises is the pauser's too. + let mut strict = policy(); + strict.min_threshold = 3; let mut r = tron_compliant(); - assert_eq!( - statuses(&evm_rules(&r, Flavor::Tron, &p))[PAUSER_MS], - Pass, - "a contract" - ); - r.pauser_code.clear(); r.tron_pauser_signers = Some(2); - assert_eq!( - statuses(&evm_rules(&r, Flavor::Tron, &p))[PAUSER_MS], - Pass, - "2-of-n account" - ); - r.tron_pauser_signers = Some(1); - assert_eq!( - statuses(&evm_rules(&r, Flavor::Tron, &p))[PAUSER_MS], - Fail, - "a single key" - ); - r.tron_pauser_signers = None; - let rules = evm_rules(&r, Flavor::Tron, &p); + assert_eq!(evm_rules(&r, Flavor::Tron, &strict)[PAUSER_MS].status, Fail, "2 where 3 are asked"); + let rules = pauser(&[], None); assert_eq!( rules[PAUSER_MS].status, Unknown, "the RPC does not serve wallet/getaccount" diff --git a/docs/governance.md b/docs/governance.md index 538dffb..a03187c 100644 --- a/docs/governance.md +++ b/docs/governance.md @@ -4,6 +4,15 @@ What this closes: security-report finding **BR-3** (High), "multisig and timeloc contracts; Solana upgrade authority". Design and rationale: `docs/superpowers/specs/2026-09-25-br3-governance-design.md`. +> **UNRECONCILED — needs on-chain check (audit v14, BR-1009).** The paragraph below says the Tron +> multi-signature account permissions "are still to do". `docs/mainnet-deployment.md` (section on +> the Tron governance accounts) records them as done on 2026-09-26 — admin account owner 3 of 5 +> and active 3 of 5, pause account owner 3 of 5 and active 2 of 5, each with an +> `AccountPermissionUpdate` transaction id — and strikes that step out. Both cannot be right, and +> nothing in this repository settles it. Until someone reads `wallet/getaccount` for the two +> accounts on Tron mainnet (or runs `rand-bridge-audit --governance`, whose Tron rules 10 and 13 +> read exactly that) and corrects whichever document is wrong, treat neither statement as fact. + **Tron steps 0–3 ran on mainnet on 2026-09-26** (timelock `TKmds8i5UPQDaV3YghCVJUMomHeQzJzV7k`, pauser and pending admin set; `docs/mainnet-deployment.md`); the multi-signature account permissions and the accept are still to do. **No other on-chain step below has been run.** They move control of live custody and are irreversible once a timelock or multisig accepts. Run them in the order given, one chain at a time, and check each with the audit (§5) before the next. diff --git a/docs/mainnet-deployment.md b/docs/mainnet-deployment.md index 1e42b9d..4ef4918 100644 --- a/docs/mainnet-deployment.md +++ b/docs/mainnet-deployment.md @@ -137,6 +137,16 @@ The two multi-signature accounts are children of one xpub (`TRON_MSIG_XPUB` in ` | pause multisig account (the bridge `pauser()`) | /1 | `TCimv6fBNmPNi16QvrGgUjJWQYTnmpLG58` | | signers 1–5 | /2–/6 | `TCCm5ui5kHeqxgYF69pmb7GF8RcdP5fccG`, `TWk2QEXwM42qAQ5TFKwWo66eg5G2m9v82P`, `TYbQ16vcbRY34gLN5AN25miEZJR29pCqme`, `TBqXBmWnUKeat3Fpgx8e8YKNEVSXXgWe6F`, `TW4M3My781kRpUFZwYBUQfkd1FqEMq3Xrn` | +> **UNRECONCILED — needs on-chain check (audit v14, BR-1009).** This section records the Tron +> account permissions as set on 2026-09-26 (below: admin owner 3/5 and active 3/5, pause owner 3/5 +> and active 2/5, with transaction ids; and step 2 of the list struck out as done). +> `docs/governance.md` (its opening status paragraph) says of the same date that "the +> multi-signature account permissions and the accept are still to do". Both cannot be right, and +> nothing in this repository settles it. Until someone reads `wallet/getaccount` for +> `TXbkkfTiCAJWsTZcBnyemQZsgfKJr2SRjp` and `TCimv6fBNmPNi16QvrGgUjJWQYTnmpLG58` on Tron mainnet +> (or runs `rand-bridge-audit --governance`, whose Tron rules 10 and 13 read exactly that) and +> corrects whichever document is wrong, treat neither statement as fact. + Multi-signature since 2026-09-26 (funded 110 TRX each from the deployer, `2ff489dc…af20`, `f2bb477e…bc22`; each `AccountPermissionUpdate` signed by the account's own key and burning 100 TRX): admin `TXbkkf…Rjp` owner 3/5, active id 2 3/5 (TriggerSmartContract only), tx @@ -147,6 +157,9 @@ owner 3/5, active id 2 2/5, tx `8675613036534d4903a86492716abf2af8417d76d69314e4 **All of them share one seed**, so the Tron multisigs are nominal (one key in substance) until the signers move to separate people and devices (BR-4). Not done yet, in order: +(Step 2 below is marked done here and "still to do" in `docs/governance.md`: **UNRECONCILED — +needs on-chain check**, see the note above.) + 1. ~~Fund `/0` and `/1`~~ (done). 2. ~~`node deploy/tron-ops.js multisig-permissions --signers --owner-threshold 3 --active-threshold 3` (pause account: `--active-threshold 2`) writes the unsigned