From 00e441a37f9035fa0264490442fc532ce9b1704a Mon Sep 17 00:00:00 2001 From: Dendi Suhubdy <4477337+dendisuhubdy@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:37:34 +0800 Subject: [PATCH] BR-4: a quorum one operator can meet does not load, and --check-providers asks each provider its chain Main reads each chain through several providers and signs only what a quorum report identically. Nothing checked that the providers are different parties: two URLs of one operator at rpc_quorum 2 loaded and gave the protection of one. With an rpc_quorum of two or more, a config in which one operator's URLs are enough to meet the quorum is now refused at load. The operator is the URL's host reduced to its last two labels, or host:port for an IP address or a single-label host. A quorum of one is not judged (it still warns at startup), so the configs the live guardians run load as before. rand-guardian --check-providers makes one read-only identity call per provider (eth_chainId, getGenesisHash, rand_chainId + rand_getGenesisHash) and exits 0 only when, on every watched chain, a quorum of providers from at least two operators name the same chain, and the Rand nodes name the configured chain id and genesis hash. It needs no key and opens no data directory. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01YGaYNQ4cvFtg2UmokVgrAN --- daemons/README.md | 8 ++ daemons/config.example.toml | 3 + daemons/src/bin/guardian.rs | 14 +++ daemons/src/config.rs | 4 + daemons/src/lib.rs | 1 + daemons/src/providers.rs | 235 ++++++++++++++++++++++++++++++++++++ daemons/tests/providers.rs | 187 ++++++++++++++++++++++++++++ docs/guardian-hosts.md | 20 +++ 8 files changed, 472 insertions(+) create mode 100644 daemons/src/providers.rs create mode 100644 daemons/tests/providers.rs diff --git a/daemons/README.md b/daemons/README.md index 816e4ef..4749972 100644 --- a/daemons/README.md +++ b/daemons/README.md @@ -31,6 +31,14 @@ relayer ◀──GET /v1/signature/{emitter_chain}/{sequence}────── prefix (the lowest block among the agreeing providers), else not at all. A provider that errors agrees with nothing. So one provider can neither get an invented or altered lock signed nor move the cursor past a real one. One `rpc` alone still works, with a startup warning. + **The providers must be different parties** (`src/providers.rs`): with an `rpc_quorum` of two or + more, a config in which one operator's URLs are enough to meet the quorum does not load. The + operator is read from the URL's host: a named host by its last two labels (two `publicnode.com` + endpoints count once), an IP address or `localhost` with its port. `rand-guardian --config + --check-providers` asks every provider which chain it serves (`eth_chainId`, `getGenesisHash`, + `rand_chainId` + `rand_getGenesisHash`; read-only, no key) and exits 0 only when, on every + chain, a quorum of providers from different operators name the same chain, and for Rand the + configured one. Run it before a config goes live and after any provider change. - Rebuilds the body from the event plus the block timestamp, the emitter chain id and the emitter address (`spec/ATTESTATION.md` §3.2), checks it re-encodes canonically, and signs it only if the destination would accept it: registered emitter, `to_chain` / `token_chain` rules, diff --git a/daemons/config.example.toml b/daemons/config.example.toml index d5af3c9..34f3e9c 100644 --- a/daemons/config.example.toml +++ b/daemons/config.example.toml @@ -38,6 +38,9 @@ start_sequence = 0 # startup that a single provider can get a message signed. # rpcs = ["https://", "https://"] # rpc_quorum = 2 +# With rpc_quorum >= 2 the providers must be different operators (by host: the last two labels of +# a name, or host:port for an IP): a config whose quorum one operator's URLs meet does not load. +# `rand-guardian --config --check-providers` asks each which chain it serves (read-only). [[evm]] name = "ethereum" diff --git a/daemons/src/bin/guardian.rs b/daemons/src/bin/guardian.rs index 202dac1..dffd725 100644 --- a/daemons/src/bin/guardian.rs +++ b/daemons/src/bin/guardian.rs @@ -16,6 +16,12 @@ struct Cli { /// The TOML configuration file (see daemons/config.example.toml). #[arg(long, env = "RAND_BRIDGE_CONFIG")] config: PathBuf, + /// Ask every configured provider which chain it serves and exit (BR-4): 0 + /// only when, on every watched chain, a quorum of providers from different + /// operators name the same chain (for Rand, the configured one). Read-only; + /// needs no key and no data directory. + #[arg(long)] + check_providers: bool, /// Pause all signing (an operator's act; nothing pauses on its own), then /// exit. Needs no key. #[arg(long, value_name = "REASON")] @@ -50,6 +56,14 @@ async fn main() -> Result<()> { .guardian .clone() .ok_or_else(|| anyhow!("the config has no [guardian] section"))?; + if cli.check_providers { + let (text, ok) = bridge_daemons::providers::render(&bridge_daemons::providers::probe(&config).await); + print!("{text}"); + if !ok { + return Err(anyhow!("at least one chain's providers do not agree on the chain they serve (BR-4)")); + } + return Ok(()); + } if let Some(reason) = &cli.pause_signing { let store = Store::open(&config.data_dir)?; bridge_daemons::limits::pause(&store, bridge_daemons::limits::now(), reason)?; diff --git a/daemons/src/config.rs b/daemons/src/config.rs index 0a41302..ba86c2c 100644 --- a/daemons/src/config.rs +++ b/daemons/src/config.rs @@ -485,6 +485,10 @@ fn check_providers(what: &str, rpc: &str, rpcs: &[String], quorum: Option list.len() ); } + // BR-4: a quorum that one operator's URLs can meet alone is a quorum of one. + if let Some(gap) = crate::providers::independence_gap(what, &list, q) { + bail!("{gap}"); + } Ok(()) } diff --git a/daemons/src/lib.rs b/daemons/src/lib.rs index 0388b07..269a5a6 100644 --- a/daemons/src/lib.rs +++ b/daemons/src/lib.rs @@ -19,6 +19,7 @@ pub mod limits; pub mod message; pub mod pq; pub mod pq_gov; +pub mod providers; pub mod relayer; pub mod rpc; pub mod sources; diff --git a/daemons/src/providers.rs b/daemons/src/providers.rs new file mode 100644 index 0000000..9fb7e4c --- /dev/null +++ b/daemons/src/providers.rs @@ -0,0 +1,235 @@ +//! Whether the providers a chain is read through are independent (BR-4). +//! +//! The quorum read ([`crate::sources::Quorum`]) signs nothing one provider +//! alone reports. That holds only if the providers are different parties on +//! the same chain. Two URLs of one operator are one party, and a provider +//! that serves another network agrees with nobody. Two checks: +//! +//! - **Static, at config load** ([`independence_gap`]): with an `rpc_quorum` +//! of two or more, no single operator's URLs may be enough to meet it. The +//! operator of a URL is taken from its host ([`operator_of`]). +//! - **Live, on request** ([`probe`], `rand-guardian --check-providers`): each +//! provider is asked which chain it serves, and the chain passes only when +//! a quorum of providers, from at least two operators when the quorum is +//! two or more, name the same chain — and, for Rand, the configured one. +//! Read-only: one identity call per provider. + +use std::collections::BTreeMap; + +use anyhow::{anyhow, Result}; +use serde_json::json; + +use crate::config::{Config, EvmKind}; +use crate::rpc::JsonRpc; + +/// The party behind an RPC URL, as far as its host tells. +/// +/// A named host is reduced to its last two labels (`ethereum-rpc.publicnode.com` +/// and `bsc-rpc.publicnode.com` are both `publicnode.com`), so two endpoints of +/// one provider count once. This is not the public-suffix list: under a +/// two-label suffix (`example.co.uk`) different parties share an operator name +/// here, which errs towards refusing. An IP address, `localhost` or a +/// single-label host is taken with its port: these are local processes and +/// forwards, each configured on purpose. +pub fn operator_of(url: &str) -> String { + let rest = url.split("://").nth(1).unwrap_or(url); + let authority = rest.split(['/', '?', '#']).next().unwrap_or(rest); + let hostport = authority.rsplit('@').next().unwrap_or(authority).to_ascii_lowercase(); + // [v6]:port, host:port, host + let host = if let Some(end) = hostport.find(']') { + &hostport[..=end] + } else { + hostport.split(':').next().unwrap_or(&hostport) + }; + let is_ip = host.starts_with('[') || host.split('.').all(|l| !l.is_empty() && l.bytes().all(|b| b.is_ascii_digit())); + let labels: Vec<&str> = host.trim_end_matches('.').split('.').collect(); + if is_ip || labels.len() < 2 { + return hostport; + } + labels[labels.len() - 2..].join(".") +} + +/// Why `urls` at `quorum` do not make a single lying operator harmless, or +/// `None` when they do. A quorum of one makes no such claim and is not +/// judged here (the guardian warns about it at startup). +pub fn independence_gap(what: &str, urls: &[String], quorum: usize) -> Option { + if quorum < 2 { + return None; + } + let mut by_operator: BTreeMap = BTreeMap::new(); + for u in urls { + *by_operator.entry(operator_of(u)).or_default() += 1; + } + let (operator, most) = by_operator.iter().max_by_key(|(_, n)| **n)?; + if *most >= quorum { + return Some(format!( + "{what}: {most} of the {} RPCs are {operator}'s, enough to meet rpc_quorum {quorum} on \ + their own; a quorum must need at least two operators (BR-4). List providers run by \ + different parties, or raise rpc_quorum above {most}", + urls.len() + )); + } + None +} + +/// What one provider said about the chain it serves. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Answer { + /// The provider's host (never the URL: it may carry an API key). + pub shown: String, + pub operator: String, + /// The chain it names, or why it did not. + pub identity: Result, +} + +/// One chain's providers, asked. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ChainReport { + pub name: String, + pub quorum: usize, + pub answers: Vec, + /// The chain the config says this is, when it says (Rand). + pub expected: Option, +} + +impl ChainReport { + /// `Ok(identity)` when a quorum of providers name the same chain — from + /// at least two operators when the quorum is two or more — and it is the + /// expected one. `Err` says what is short. + pub fn verdict(&self) -> Result { + let mut groups: BTreeMap<&str, Vec<&Answer>> = BTreeMap::new(); + for a in &self.answers { + if let Ok(id) = &a.identity { + groups.entry(id.as_str()).or_default().push(a); + } + } + let Some((id, agreeing)) = groups.iter().max_by_key(|(_, v)| v.len()) else { + return Err(format!("no provider answered; {} needed", self.quorum)); + }; + if agreeing.len() < self.quorum { + return Err(format!( + "{} of {} providers name chain {id}; {} needed{}", + agreeing.len(), + self.answers.len(), + self.quorum, + if groups.len() > 1 { " (the providers name different chains)" } else { "" } + )); + } + let operators: std::collections::BTreeSet<&str> = agreeing.iter().map(|a| a.operator.as_str()).collect(); + if self.quorum >= 2 && operators.len() < 2 { + return Err(format!("the providers that agree on chain {id} are one operator ({})", agreeing[0].operator)); + } + if let Some(expected) = &self.expected { + if expected != id { + return Err(format!("the providers serve chain {id}; the config names {expected}")); + } + } + Ok(id.to_string()) + } +} + +async fn evm_identity(rpc: &JsonRpc) -> Result { + let v = rpc.call("eth_chainId", json!([])).await?; + Ok(format!("eip155:{}", crate::rpc::quantity(&v)?)) +} + +async fn solana_identity(rpc: &JsonRpc) -> Result { + let v = rpc.call("getGenesisHash", json!([])).await?; + Ok(format!("solana:{}", v.as_str().ok_or_else(|| anyhow!("getGenesisHash: not a string"))?)) +} + +async fn rand_identity(rpc: &JsonRpc) -> Result { + let id = crate::sources::rand::chain_id(rpc).await?; + let genesis = crate::sources::rand::genesis_hash(rpc).await?; + Ok(format!("rand:{id}:{}", hex::encode(genesis))) +} + +fn answer(url: &str, identity: Result) -> Answer { + Answer { + shown: JsonRpc::new(url).shown(), + operator: operator_of(url), + identity: identity.map_err(|e| format!("{e:#}")), + } +} + +/// Asks every configured provider of every watched chain which chain it +/// serves. One read-only call per provider (two for Rand). +pub async fn probe(config: &Config) -> Vec { + let mut out = Vec::new(); + { + let (urls, quorum) = config.rand.providers(); + let mut answers = Vec::new(); + for u in &urls { + answers.push(answer(u, rand_identity(&JsonRpc::new(u)).await)); + } + let expected = match (config.rand.chain_id, config.rand.genesis().ok().flatten()) { + (Some(id), Some(g)) => Some(format!("rand:{id}:{}", hex::encode(g))), + _ => None, + }; + out.push(ChainReport { name: "rand".into(), quorum, answers, expected }); + } + for e in &config.evm { + let (urls, quorum) = e.providers(); + let mut answers = Vec::new(); + for u in &urls { + let url = match e.kind { + EvmKind::Evm => u.clone(), + EvmKind::Tron => format!("{}/jsonrpc", u.trim_end_matches('/')), + }; + answers.push(answer(u, evm_identity(&JsonRpc::new(&url)).await)); + } + out.push(ChainReport { name: e.name.clone(), quorum, answers, expected: None }); + } + if let Some(s) = &config.solana { + let (urls, quorum) = s.providers(); + let mut answers = Vec::new(); + for u in &urls { + answers.push(answer(u, solana_identity(&JsonRpc::new(u)).await)); + } + out.push(ChainReport { name: "solana".into(), quorum, answers, expected: None }); + } + out +} + +/// The well-known public networks, to say in the report which one a chain is. +pub fn network_name(identity: &str) -> Option<&'static str> { + match identity { + "eip155:1" => Some("Ethereum mainnet"), + "eip155:56" => Some("BNB Smart Chain mainnet"), + "eip155:728126428" => Some("Tron mainnet"), + "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d" => Some("Solana mainnet-beta"), + _ => None, + } +} + +/// The report as text, and whether every chain passed. +pub fn render(reports: &[ChainReport]) -> (String, bool) { + let mut text = String::new(); + let mut ok = true; + for r in reports { + text.push_str(&format!("== {} ({} of {} must agree) ==\n", r.name, r.quorum, r.answers.len())); + for a in &r.answers { + let said = match &a.identity { + Ok(id) => id.clone(), + Err(e) => format!("no answer: {e}"), + }; + text.push_str(&format!(" {:<40} operator {:<28} {said}\n", a.shown, a.operator)); + } + match r.verdict() { + Ok(id) => { + let named = network_name(&id).map(|n| format!(" ({n})")).unwrap_or_default(); + let single = if r.quorum < 2 { + "; a quorum of 1: a single provider can get a message signed (BR-4)" + } else { + "" + }; + text.push_str(&format!(" PASS: chain {id}{named}{single}\n")); + } + Err(why) => { + ok = false; + text.push_str(&format!(" FAIL: {why}\n")); + } + } + } + (text, ok) +} diff --git a/daemons/tests/providers.rs b/daemons/tests/providers.rs new file mode 100644 index 0000000..cee7252 --- /dev/null +++ b/daemons/tests/providers.rs @@ -0,0 +1,187 @@ +//! BR-4: the providers a chain is read through must be different parties on +//! the same chain — checked from the config, and by asking them. + +mod common; + +use std::process::Command; + +use bridge_daemons::config::Config; +use bridge_daemons::providers::{self, independence_gap, operator_of}; +use common::*; +use serde_json::json; + +const GENESIS: &str = "ca76c2766ed6090ac6ba5dad86b724dd5d2b80c0edfaed287cd8b129e663ca9a"; + +#[test] +fn the_operator_of_a_url_is_its_site_or_its_local_endpoint() { + for (url, operator) in [ + ("https://ethereum-rpc.publicnode.com", "publicnode.com"), + ("https://bsc-rpc.publicnode.com/", "publicnode.com"), + ("https://eth-mainnet.g.alchemy.com/v2/SECRETKEY", "alchemy.com"), + ("https://user:pass@RPC.Example.ORG:8443/path?x=1", "example.org"), + ("https://api.trongrid.io", "trongrid.io"), + ("http://127.0.0.1:8545", "127.0.0.1:8545"), + ("http://127.0.0.1:8546/", "127.0.0.1:8546"), + ("http://localhost:8545", "localhost:8545"), + ("http://[::1]:8545", "[::1]:8545"), + ("http://node-a:8545/rpc", "node-a:8545"), + ] { + assert_eq!(operator_of(url), operator, "{url}"); + } + assert!(!operator_of("https://eth-mainnet.g.alchemy.com/v2/SECRETKEY").contains("SECRET")); +} + +fn urls(list: &[&str]) -> Vec { + list.iter().map(|u| u.to_string()).collect() +} + +#[test] +fn a_quorum_one_operator_can_meet_alone_is_a_gap() { + let same = urls(&["https://ethereum-rpc.publicnode.com", "https://ethereum.publicnode.com"]); + let gap = independence_gap("evm.eth", &same, 2).expect("two URLs of one operator"); + assert!(gap.contains("publicnode.com") && gap.contains("BR-4"), "{gap}"); + // Two of three from one operator still meet a quorum of two; three are needed. + let mixed = urls(&["https://a.publicnode.com", "https://b.publicnode.com", "https://rpc.mevblocker.io"]); + assert!(independence_gap("evm.eth", &mixed, 2).is_some()); + assert!(independence_gap("evm.eth", &mixed, 3).is_none()); + // Different operators; local endpoints on different ports are different. + assert!(independence_gap("evm.eth", &urls(&["https://a.publicnode.com", "https://rpc.mevblocker.io"]), 2).is_none()); + assert!(independence_gap("rand", &urls(&["http://127.0.0.1:8545", "http://127.0.0.1:8546"]), 2).is_none()); + // A quorum of one claims nothing, so it is not judged here. + assert!(independence_gap("evm.eth", &same, 1).is_none()); +} + +fn config_text(dir: &std::path::Path, rand: &[&str], eth: &[&str], quorum: usize) -> std::path::PathBuf { + let list = |u: &[&str]| u[1..].iter().map(|x| format!("{x:?}")).collect::>().join(", "); + let path = dir.join("config.toml"); + std::fs::write( + &path, + format!( + "data_dir = {:?}\n[rand]\nrpc = {:?}\nrpcs = [{}]\nrpc_quorum = {quorum}\nchain_id = 21\ngenesis_hash = {GENESIS:?}\nemitter = {:?}\n\ + [[evm]]\nname = \"ethereum\"\nchain = 2\nkind = \"evm\"\nrpc = {:?}\nrpcs = [{}]\nrpc_quorum = {quorum}\ncontract = \"0x1111111111111111111111111111111111111111\"\nfinality = 0\n\ + [guardian]\nlisten = \"127.0.0.1:0\"\n", + dir.join("data"), + rand[0], + list(rand), + hex::encode(RAND_EMITTER), + eth[0], + list(eth), + ), + ) + .unwrap(); + path +} + +#[test] +fn a_config_whose_quorum_one_operator_meets_does_not_load() { + let dir = tempfile::tempdir().unwrap(); + let rand = ["http://127.0.0.1:1", "http://127.0.0.1:2"]; + let bad = config_text(dir.path(), &rand, &["https://ethereum-rpc.publicnode.com", "https://ethereum.publicnode.com"], 2); + let err = format!("{:#}", Config::load(&bad).unwrap_err()); + assert!(err.contains("evm.ethereum") && err.contains("publicnode.com") && err.contains("BR-4"), "{err}"); + let good = config_text(dir.path(), &rand, &["https://ethereum-rpc.publicnode.com", "https://rpc.mevblocker.io"], 2); + Config::load(&good).unwrap(); + // The same two URLs at a quorum of one load as before: nothing running today changes. + let dir = tempfile::tempdir().unwrap(); + let one = config_text(dir.path(), &rand, &["https://ethereum-rpc.publicnode.com", "https://ethereum.publicnode.com"], 1); + Config::load(&one).unwrap(); +} + +#[test] +fn the_repository_mainnet_configs_still_load() { + let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("mainnet"); + for i in 1..=8 { + Config::load(&dir.join(format!("guardian-{i}.toml"))).unwrap_or_else(|e| panic!("guardian-{i}: {e:#}")); + } + Config::load(&dir.join("relayer.toml")).unwrap(); +} + +fn rand_node(chain_id: u64, genesis: &'static str) -> Fake { + rpc(move |m, _| match m { + "rand_chainId" => Some(Ok(json!(chain_id))), + "rand_getGenesisHash" => Some(Ok(json!(genesis))), + _ => None, + }) +} + +fn eth_node(chain_id: u64) -> Fake { + rpc(move |m, _| match m { + "eth_chainId" => Some(Ok(json!(format!("0x{chain_id:x}")))), + _ => None, + }) +} + +fn guardian() -> Command { + let mut c = Command::new(env!("CARGO_BIN_EXE_rand-guardian")); + c.env_remove("RAND_BRIDGE_CONFIG"); + c +} + +fn check(config: &std::path::Path) -> (bool, String, String) { + let o = guardian().arg("--config").arg(config).arg("--check-providers").output().unwrap(); + (o.status.success(), String::from_utf8_lossy(&o.stdout).into(), String::from_utf8_lossy(&o.stderr).into()) +} + +#[test] +fn check_providers_passes_when_a_quorum_of_operators_name_the_configured_chain() { + let (r1, r2, e1, e2) = (rand_node(21, GENESIS), rand_node(21, GENESIS), eth_node(1), eth_node(1)); + let dir = tempfile::tempdir().unwrap(); + let cfg = config_text(dir.path(), &[&r1.url, &r2.url], &[&e1.url, &e2.url], 2); + let (ok, out, err) = check(&cfg); + assert!(ok, "{out}\n{err}"); + assert_eq!(out.matches("PASS").count(), 2, "{out}"); + assert!(out.contains("eip155:1 (Ethereum mainnet)") && out.contains(&format!("rand:21:{GENESIS}")), "{out}"); + // One identity call per provider, and nothing else: no logs, no state, no key asked for. + assert_eq!(e1.rpc_methods(), vec!["eth_chainId"]); + assert_eq!(r1.rpc_methods(), vec!["rand_chainId", "rand_getGenesisHash"]); + assert!(!dir.path().join("data").exists(), "the check opens no data directory"); +} + +#[test] +fn check_providers_fails_when_providers_name_different_chains_or_too_few_answer() { + // One Ethereum provider serves another network. + let (r1, r2, e1, e2) = (rand_node(21, GENESIS), rand_node(21, GENESIS), eth_node(1), eth_node(11155111)); + let dir = tempfile::tempdir().unwrap(); + let (ok, out, err) = check(&config_text(dir.path(), &[&r1.url, &r2.url], &[&e1.url, &e2.url], 2)); + assert!(!ok && err.contains("BR-4"), "{out}\n{err}"); + assert!(out.contains("FAIL: 1 of 2 providers name chain") && out.contains("different chains"), "{out}"); + // One Ethereum provider is down: a quorum of two cannot be met. + let down = rpc(|_, _| None); + let dir = tempfile::tempdir().unwrap(); + let (ok, out, _) = check(&config_text(dir.path(), &[&r1.url, &r2.url], &[&e1.url, &down.url], 2)); + assert!(!ok && out.contains("no answer") && out.contains("FAIL: 1 of 2"), "{out}"); +} + +#[test] +fn check_providers_fails_when_the_rand_nodes_agree_on_a_chain_the_config_does_not_name() { + const OTHER: &str = "6210cf07000000000000000000000000000000000000000000000000000051350"; + let other: &'static str = &OTHER[..64]; + let (r1, r2, e1, e2) = (rand_node(20, other), rand_node(20, other), eth_node(1), eth_node(1)); + let dir = tempfile::tempdir().unwrap(); + let (ok, out, _) = check(&config_text(dir.path(), &[&r1.url, &r2.url], &[&e1.url, &e2.url], 2)); + assert!(!ok, "{out}"); + assert!(out.contains("the config names rand:21:"), "{out}"); +} + +#[test] +fn a_quorum_of_one_passes_the_check_and_is_called_what_it_is() { + let (r1, e1) = (rand_node(21, GENESIS), eth_node(1)); + let dir = tempfile::tempdir().unwrap(); + let (ok, out, err) = check(&config_text(dir.path(), &[&r1.url], &[&e1.url], 1)); + assert!(ok, "{out}\n{err}"); + assert_eq!(out.matches("a single provider can get a message signed").count(), 2, "{out}"); +} + +#[tokio::test] +async fn agreeing_providers_of_one_operator_do_not_pass() { + // Built by hand: the config check refuses this shape, so a report is the only way to see + // the rule. + let a = |shown: &str, op: &str, id: &str| providers::Answer { shown: shown.into(), operator: op.into(), identity: Ok(id.into()) }; + let r = providers::ChainReport { + name: "ethereum".into(), + quorum: 2, + answers: vec![a("a.example.com", "example.com", "eip155:1"), a("b.example.com", "example.com", "eip155:1")], + expected: None, + }; + assert!(r.verdict().unwrap_err().contains("one operator")); +} diff --git a/docs/guardian-hosts.md b/docs/guardian-hosts.md index e85214c..c0ab47c 100644 --- a/docs/guardian-hosts.md +++ b/docs/guardian-hosts.md @@ -44,6 +44,26 @@ Configure each guardian with more than one independent RPC per chain (`rpcs`, `r and with its peers (`guardian.peers`; BR-502). The repository's configs carry one RPC per chain and no peers; the hosts' configs are where these are set. +"Independent" is checked (BR-4). A config whose `rpc_quorum` (two or more) one operator's URLs can +meet alone does not load; the operator is the URL's site (`publicnode.com`), or host and port for +a local endpoint. Before a changed config goes live, on the host, with the provider variables but +no key: + +``` +rand-guardian --config /etc/rand-guardian.toml.new --check-providers +``` + +It makes one read-only identity call per provider and prints, per chain, what each provider +answered and PASS or FAIL. It exits 0 only when a quorum of providers from different operators +name the same chain on every watched chain, and the Rand nodes name the configured chain id and +genesis hash. A PASS at a quorum of 1 is marked as such: one provider can still get a message +signed. The check cannot see who owns a provider behind its name, or whether two providers share +an upstream node; choosing providers that do not is the operator's part. + +Key custody is the other half of BR-4 and is not code: each guardian's ECDSA key and Dilithium2 +seed on a host only that guardian's operator controls, and the Rand pause key apart from all of +them. Keys move by rotation (`docs/pq-rotation.md`, `rand-bridge-gov rotate`), never by copying. + **Public RPC trap.** `bsc-rpc.publicnode.com` only serves logs from about the last hour (8,000 BSC blocks), and Ethereum's window is about a day. A guardian stopped for longer than that stalls on 403 and must have its cursor moved forward: stop it, check that the endpoint's `sequence()` still equals