Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions daemons/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <chain>:<sequence>` (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
Expand Down
12 changes: 10 additions & 2 deletions daemons/config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -131,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
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-1.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-2.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-3.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-4.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-5.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-6.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-7.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/guardian-8.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
1 change: 1 addition & 0 deletions daemons/mainnet/relayer.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
Expand Down
8 changes: 3 additions & 5 deletions daemons/src/bin/audit.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
67 changes: 63 additions & 4 deletions daemons/src/bin/gov.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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(&current.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<Vec<u8>> = file["pq_guardians"]
Expand Down
65 changes: 60 additions & 5 deletions daemons/src/bin/guardian.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand All @@ -26,6 +27,11 @@ struct Cli {
/// review, then exit: `<chain>:<sequence>`. Needs the guardian's keys.
#[arg(long, value_name = "CHAIN:SEQUENCE")]
release_held: Option<String>,
/// Vouch for one deferred transfer written by a build that did not seal its deferred
/// records (BR-1004), after review, then exit: `<chain>:<sequence>`. 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<String>,
/// List the withheld transfers and exit.
#[arg(long)]
list_held: bool,
Expand Down Expand Up @@ -109,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
Expand All @@ -128,6 +142,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::<u16>().ok()?, s.parse::<u64>().ok()?)))
.ok_or_else(|| anyhow!("--vouch-deferred takes <chain>:<sequence>, 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(':')
Expand Down Expand Up @@ -239,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 {
Expand All @@ -253,23 +295,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! {
Expand Down
Loading
Loading