diff --git a/daemons/README.md b/daemons/README.md index 816e4ef..4c65ead 100644 --- a/daemons/README.md +++ b/daemons/README.md @@ -30,7 +30,12 @@ relayer ◀──GET /v1/signature/{emitter_chain}/{sequence}────── the cursor moves to the range's end only on full agreement, else just past the longest agreed 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 cursor past a real one. One `rpc` alone still works on a devnet, with a startup warning. + On a public Rand chain (id 14 and up, or none configured) the guardian **refuses to start** + without at least two providers at a quorum of at least two on every watched chain, a non-empty + `guardian.peers` and `[guardian.limits]` (BR-601; `--check-config`, and the emergency-only + `--unsafe-skip-mainnet-guards`: `docs/guardian-hosts.md`, "The mainnet guard"). A provider URL + that carries an API key is written as a `${NAME}` placeholder and filled from the environment. - 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, @@ -49,7 +54,7 @@ relayer ◀──GET /v1/signature/{emitter_chain}/{sequence}────── signed on its own once its window has room, in sequence order per token; later transfers of the same token wait behind it, and the source's cursor moves on for everything else. Nothing pauses signing automatically; `--pause-signing ` and `--resume-signing` are the operator's global brake. This bounds loss without any contract change; - a guardian without the section warns at startup. + a guardian without the section warns at startup on a devnet, and does not start on a public chain (BR-601). - Persists the signature before it advances its cursor, and refuses — fatally — to sign a second body under an `(emitter chain, sequence)` it has already signed. - **Asks its peers before a first signature** (BR-502, `guardian.peers`): replay protection on @@ -62,7 +67,7 @@ relayer ◀──GET /v1/signature/{emitter_chain}/{sequence}────── ignored, so no other guardian can block a transfer. If no peer answers, the transfer is deferred (`deferred/`) and retried every round — never skipped. List among the peers any API that keeps this guardian's past signatures (another guardian that mirrors them, or a copy of this one's - `signed/`). At startup it reports how many peers answer, or warns that none are configured. + `signed/`). At startup it reports how many peers answer, or warns that none are configured (on a public chain it refuses to start, BR-601). - Every record under `data_dir` is written durably (BR-951): a temp file, fsynced, renamed over the record, then the directory fsynced. A record that is still unreadable (zero-length, truncated, not JSON) fails that `(emitter chain, sequence)` alone: the guardian signs nothing diff --git a/daemons/mainnet/guardian-1.toml b/daemons/mainnet/guardian-1.toml index 7b8a7b1..3c87a5f 100644 --- a/daemons/mainnet/guardian-1.toml +++ b/daemons/mainnet/guardian-1.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block, 1 h before the cut); cursors start at sequence 1 @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1 @@ -39,12 +47,23 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7071" key_env = "GUARDIAN1_PRIV_KEY" pq_seed_env = "GUARDIAN1_PQ_SEED" +# BR-502: the other droplet guardians, each through this host's peer forward 127.0.0.1:717 -> +# guardian j's 127.0.0.1:7071 (docs/guardian-hosts.md, "Peers"). Guardians 7 and 8 are offline (BR-402). +peers = [ + "http://127.0.0.1:7172", + "http://127.0.0.1:7173", + "http://127.0.0.1:7174", + "http://127.0.0.1:7175", + "http://127.0.0.1:7176", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-2.toml b/daemons/mainnet/guardian-2.toml index 65a6a7c..4ad5ca2 100644 --- a/daemons/mainnet/guardian-2.toml +++ b/daemons/mainnet/guardian-2.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block, 1 h before the cut); cursors start at sequence 1 @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1 @@ -39,12 +47,23 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7072" key_env = "GUARDIAN2_PRIV_KEY" pq_seed_env = "GUARDIAN2_PQ_SEED" +# BR-502: the other droplet guardians, each through this host's peer forward 127.0.0.1:717 -> +# guardian j's 127.0.0.1:7071 (docs/guardian-hosts.md, "Peers"). Guardians 7 and 8 are offline (BR-402). +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7173", + "http://127.0.0.1:7174", + "http://127.0.0.1:7175", + "http://127.0.0.1:7176", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-3.toml b/daemons/mainnet/guardian-3.toml index bd822cd..0f3627b 100644 --- a/daemons/mainnet/guardian-3.toml +++ b/daemons/mainnet/guardian-3.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block, 1 h before the cut); cursors start at sequence 1 @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1 @@ -39,12 +47,23 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7073" key_env = "GUARDIAN3_PRIV_KEY" pq_seed_env = "GUARDIAN3_PQ_SEED" +# BR-502: the other droplet guardians, each through this host's peer forward 127.0.0.1:717 -> +# guardian j's 127.0.0.1:7071 (docs/guardian-hosts.md, "Peers"). Guardians 7 and 8 are offline (BR-402). +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7172", + "http://127.0.0.1:7174", + "http://127.0.0.1:7175", + "http://127.0.0.1:7176", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-4.toml b/daemons/mainnet/guardian-4.toml index 523469c..95e5bfb 100644 --- a/daemons/mainnet/guardian-4.toml +++ b/daemons/mainnet/guardian-4.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block, 1 h before the cut); cursors start at sequence 1 @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1 @@ -39,12 +47,23 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7074" key_env = "GUARDIAN4_PRIV_KEY" pq_seed_env = "GUARDIAN4_PQ_SEED" +# BR-502: the other droplet guardians, each through this host's peer forward 127.0.0.1:717 -> +# guardian j's 127.0.0.1:7071 (docs/guardian-hosts.md, "Peers"). Guardians 7 and 8 are offline (BR-402). +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7172", + "http://127.0.0.1:7173", + "http://127.0.0.1:7175", + "http://127.0.0.1:7176", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-5.toml b/daemons/mainnet/guardian-5.toml index d4c20fb..5f04848 100644 --- a/daemons/mainnet/guardian-5.toml +++ b/daemons/mainnet/guardian-5.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block, 1 h before the cut); cursors start at sequence 1 @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1 @@ -39,12 +47,23 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7075" key_env = "GUARDIAN5_PRIV_KEY" pq_seed_env = "GUARDIAN5_PQ_SEED" +# BR-502: the other droplet guardians, each through this host's peer forward 127.0.0.1:717 -> +# guardian j's 127.0.0.1:7071 (docs/guardian-hosts.md, "Peers"). Guardians 7 and 8 are offline (BR-402). +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7172", + "http://127.0.0.1:7173", + "http://127.0.0.1:7174", + "http://127.0.0.1:7176", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-6.toml b/daemons/mainnet/guardian-6.toml index 29e6793..8f034f6 100644 --- a/daemons/mainnet/guardian-6.toml +++ b/daemons/mainnet/guardian-6.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block, 1 h before the cut); cursors start at sequence 1 @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block); cursors start at sequence 1 @@ -39,12 +47,23 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7076" key_env = "GUARDIAN6_PRIV_KEY" pq_seed_env = "GUARDIAN6_PQ_SEED" +# BR-502: the other droplet guardians, each through this host's peer forward 127.0.0.1:717 -> +# guardian j's 127.0.0.1:7071 (docs/guardian-hosts.md, "Peers"). Guardians 7 and 8 are offline (BR-402). +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7172", + "http://127.0.0.1:7173", + "http://127.0.0.1:7174", + "http://127.0.0.1:7175", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-7.toml b/daemons/mainnet/guardian-7.toml index 1dd176e..e5058d4 100644 --- a/daemons/mainnet/guardian-7.toml +++ b/daemons/mainnet/guardian-7.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block; BSC: 1 h before the cut); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block; BSC: 1 h before the cut); cursors start at sequence 1, past the consume-step lock @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block; BSC: 1 h before the cut); cursors start at sequence 1, past the consume-step lock @@ -39,12 +47,24 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7077" key_env = "GUARDIAN7_PRIV_KEY" pq_seed_env = "GUARDIAN7_PQ_SEED" # unset: the PQ quorum comes from the droplets +# BR-502: the droplet guardians through guardian-tunnels.sh (127.0.0.1:7171-7176), and the other laptop guardian. +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7172", + "http://127.0.0.1:7173", + "http://127.0.0.1:7174", + "http://127.0.0.1:7175", + "http://127.0.0.1:7176", + "http://127.0.0.1:7078", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/guardian-8.toml b/daemons/mainnet/guardian-8.toml index a350618..a8e03ee 100644 --- a/daemons/mainnet/guardian-8.toml +++ b/daemons/mainnet/guardian-8.toml @@ -4,6 +4,8 @@ poll_secs = 15 [rand] rpc = "http://127.0.0.1:8545" # the bridged Rand chain's node, once it is cut +rpcs = ["${GUARDIAN_RPC_RAND}"] # BR-4/BR-601: a second Rand node, not this host's (docs/guardian-hosts.md, "Providers") +rpc_quorum = 2 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" @@ -13,6 +15,8 @@ name = "ethereum" chain = 2 kind = "evm" rpc = "https://ethereum-rpc.publicnode.com" +rpcs = ["https://rpc.mevblocker.io", "${GUARDIAN_RPC_ETHEREUM}"] # three operators; the keyed one from the env +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = "finalized" start_block = 26090266 # the 2026-09-30 endpoint (deploy block; BSC: 1 h before the cut); cursors start at sequence 1, past the consume-step lock @@ -22,6 +26,8 @@ name = "bsc" chain = 3 kind = "evm" rpc = "https://bsc-rpc.publicnode.com" +rpcs = ["${GUARDIAN_RPC_BSC}"] # no second keyless BSC provider serves eth_getLogs over 1,000 blocks +rpc_quorum = 2 contract = "0x7aF6b17047C1db6cB54347FdEa45cF9179075bfA" finality = 15 start_block = 125030322 # the 2026-09-30 endpoint (deploy block; BSC: 1 h before the cut); cursors start at sequence 1, past the consume-step lock @@ -32,6 +38,8 @@ name = "tron" chain = 4 kind = "tron" rpc = "https://tron-rpc.publicnode.com" # TronGrid rate-limits one IP without an API key +rpcs = ["https://api.trongrid.io", "${GUARDIAN_RPC_TRON}"] +rpc_quorum = 2 contract = "0x6410797df959987a5baf65b5fab97edeb34d5163" # TK6JJv55CCkFjNHq7WwoU91GKaZEiC93me finality = 19 start_block = 86699346 # the 2026-09-30 endpoint (deploy block; BSC: 1 h before the cut); cursors start at sequence 1, past the consume-step lock @@ -39,12 +47,24 @@ max_log_range = 1000 [solana] rpc = "https://api.mainnet-beta.solana.com" +rpcs = ["https://solana-rpc.publicnode.com", "${GUARDIAN_RPC_SOLANA}"] +rpc_quorum = 2 program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" [guardian] listen = "127.0.0.1:7078" key_env = "GUARDIAN8_PRIV_KEY" pq_seed_env = "GUARDIAN8_PQ_SEED" # unset: the PQ quorum comes from the droplets +# BR-502: the droplet guardians through guardian-tunnels.sh (127.0.0.1:7171-7176), and the other laptop guardian. +peers = [ + "http://127.0.0.1:7171", + "http://127.0.0.1:7172", + "http://127.0.0.1:7173", + "http://127.0.0.1:7174", + "http://127.0.0.1:7175", + "http://127.0.0.1:7176", + "http://127.0.0.1:7077", +] # BRG-1: the published caps (100 per transfer, 1,000 per day, every token), in attested 8-decimal # units, held by this guardian before it signs. A transfer over per_transfer is withheld until diff --git a/daemons/mainnet/run-guardians-set1.sh b/daemons/mainnet/run-guardians-set1.sh index 8a4542b..d305b90 100755 --- a/daemons/mainnet/run-guardians-set1.sh +++ b/daemons/mainnet/run-guardians-set1.sh @@ -8,6 +8,16 @@ cd "$(dirname "${BASH_SOURCE[0]}")/.." bin=target/release/rand-guardian [[ -x "$bin" ]] || cargo build --release --bin rand-guardian mkdir -p data/mainnet/logs +# BR-601: the configs name their second providers as ${GUARDIAN_RPC_*} placeholders (provider API +# keys stay out of this repository). They come from ~/.rand-bridge/mainnet-set1/rpc.env (mode 600, +# lines NAME=VALUE); a guardian on chain 21 refuses to start while one is unset. +rpcenv="$HOME/.rand-bridge/mainnet-set1/rpc.env" +rpc=() +if [[ -s "$rpcenv" ]]; then + while IFS= read -r line; do + [[ "$line" =~ ^GUARDIAN_RPC_[A-Z0-9_]+= ]] && rpc+=("$line") + done <"$rpcenv" +fi for i in 7 8; do keyfile="$HOME/.rand-bridge/mainnet-set1/guardian-$i.key" [[ -s "$keyfile" ]] || { echo "error: $keyfile is missing" >&2; exit 1; } @@ -17,7 +27,7 @@ for i in 7 8; do if [[ "${GUARDIAN_PQ_FROM_NEXT:-0}" == 1 ]]; then pq=("GUARDIAN${i}_PQ_SEED=$(tr -d '\n ' < "$HOME/.rand-bridge/mainnet-set1/pq-next-$i.seed")") fi - env -i PATH="$PATH" HOME="$HOME" "GUARDIAN${i}_PRIV_KEY=$(<"$keyfile")" "${pq[@]}" \ + env -i PATH="$PATH" HOME="$HOME" "GUARDIAN${i}_PRIV_KEY=$(<"$keyfile")" "${pq[@]}" "${rpc[@]}" \ nohup "$bin" --config "mainnet/guardian-$i.toml" >>"data/mainnet/logs/guardian-$i.log" 2>&1 & echo "guardian $i: pid $! (log data/mainnet/logs/guardian-$i.log)" done diff --git a/daemons/src/bin/guardian.rs b/daemons/src/bin/guardian.rs index 202dac1..0c4a639 100644 --- a/daemons/src/bin/guardian.rs +++ b/daemons/src/bin/guardian.rs @@ -1,7 +1,7 @@ use std::path::PathBuf; use std::time::Duration; -use anyhow::{anyhow, Context, Result}; +use anyhow::{anyhow, bail, Context, Result}; use bridge_daemons::config::Config; use bridge_daemons::crypto::GuardianKey; use bridge_daemons::isolate::isolated; @@ -35,6 +35,21 @@ struct Cli { /// List the withheld transfers and exit. #[arg(long)] list_held: bool, + /// Check the config against the mainnet guard (BR-601) with this + /// environment's `${NAME}` values, print what it lacks, and exit: 0 when + /// the guardian would start. Needs no key. + #[arg(long)] + check_config: bool, + /// UNSAFE, for an emergency or a dev run only: start on a public Rand + /// chain (id 14 and up, or none configured) even though the config lacks + /// the multi-provider RPC quorum, `guardian.peers` or `[guardian.limits]` + /// (BR-601). Every missing control is logged at error level on start. + #[arg( + long, + env = "RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS", + value_parser = clap::builder::BoolishValueParser::new() + )] + unsafe_skip_mainnet_guards: bool, } #[tokio::main] @@ -50,6 +65,11 @@ async fn main() -> Result<()> { .guardian .clone() .ok_or_else(|| anyhow!("the config has no [guardian] section"))?; + if cli.check_config { + mainnet_guard(&config, false)?; + println!("config OK for Rand chain {}", chain_label(&config)); + 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)?; @@ -75,6 +95,10 @@ async fn main() -> Result<()> { return Ok(()); } + // BR-601: on a public chain the controls below are required, not opt-in. + // Checked before the key is read; the operator commands above need none. + mainnet_guard(&config, cli.unsafe_skip_mainnet_guards)?; + // The key comes from the environment only, and leaves it at once so no // child process or crash dump of the environment carries it. let secret = @@ -334,6 +358,46 @@ async fn main() -> Result<()> { } } +fn chain_label(config: &Config) -> String { + config + .rand + .chain_id + .map_or_else(|| "(none configured)".to_string(), |id| id.to_string()) +} + +/// Refuses a guardian on a public Rand chain whose config lacks the +/// multi-provider quorum, the peers or the caps (BR-601), unless the operator +/// overrides it explicitly — then every gap is logged at error level. +fn mainnet_guard(config: &Config, unsafe_override: bool) -> Result<()> { + let chain = chain_label(config); + if !bridge_daemons::config::is_public_rand_chain(config.rand.chain_id) { + tracing::info!("Rand chain {chain} is a devnet: the mainnet guard (BR-601) does not apply"); + return Ok(()); + } + let gaps = config.mainnet_guardian_gaps(); + if gaps.is_empty() { + return Ok(()); + } + if unsafe_override { + for gap in &gaps { + tracing::error!("UNSAFE (--unsafe-skip-mainnet-guards): {gap}"); + } + tracing::error!( + "UNSAFE: signing on public Rand chain {chain} without {} mainnet control(s) (BR-601); \ + remove the override as soon as the config is fixed", + gaps.len() + ); + return Ok(()); + } + bail!( + "BR-601: refusing to start on public Rand chain {chain}; the config lacks:\n - {}\n\ + Fix the config (daemons/mainnet/guardian-.toml shows every control), or, for an \ + emergency or a dev run only, pass --unsafe-skip-mainnet-guards \ + (RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS=1)", + gaps.join("\n - ") + ) +} + fn source_name(s: &S) -> &str { s.name() } diff --git a/daemons/src/config.rs b/daemons/src/config.rs index 0a41302..d62f6f6 100644 --- a/daemons/src/config.rs +++ b/daemons/src/config.rs @@ -1,8 +1,10 @@ //! One TOML file configures either daemon; each reads the sections it needs. //! Secrets are never in the file: a section names the *environment variable* -//! that holds its key. +//! that holds its key, and an RPC URL or peer that carries one (a provider's +//! API key) is written with a `${NAME}` placeholder, filled from the +//! environment at load ([`Config::load_with`]). -use std::collections::BTreeMap; +use std::collections::{BTreeMap, BTreeSet}; use std::path::{Path, PathBuf}; use anyhow::{anyhow, bail, Context, Result}; @@ -28,6 +30,24 @@ pub struct Config { /// The policy `rand-bridge-audit --governance` holds the endpoints to /// (BR-3). Optional: absent, the defaults below apply. pub governance: Option, + /// `${NAME}` placeholders the environment did not fill, as + /// `(field, NAME)`. Each is left as written; a guardian on a public + /// chain refuses to start while any remains ([`Config::mainnet_guardian_gaps`]). + #[serde(skip)] + pub unresolved: Vec<(String, String)>, +} + +/// The first public Rand chain id. Chains 14–19 bind governance to the chain +/// id, 20 onward to the genesis hash (BRG-901, `pq_gov::CHAIN_ID_BINDING_CHAIN_IDS`); +/// both are public chains whose bridge moves real value. Ids below are +/// devnets and retired testnets. +pub const FIRST_PUBLIC_RAND_CHAIN_ID: u64 = 14; + +/// Whether a guardian configured for `chain_id` is held to the mainnet guard +/// (BR-601). A config that names no chain is: nothing ties it to a test chain, +/// since the node's id is compared at startup only when one is configured. +pub fn is_public_rand_chain(chain_id: Option) -> bool { + chain_id.is_none_or(|id| id >= FIRST_PUBLIC_RAND_CHAIN_ID) } fn default_poll_secs() -> u64 { @@ -389,15 +409,115 @@ impl Config { self.governance.clone().unwrap_or_default() } + /// [`Config::load_with`] the process environment. pub fn load(path: &Path) -> Result { + Config::load_with(path, |name| std::env::var(name).ok()) + } + + /// Reads, fills and checks a config. Every `${NAME}` in an RPC URL + /// (`rpc`, `rpcs`) or a guardian peer is replaced by `lookup(NAME)`; one + /// that is unset or empty stays as written and is recorded in + /// [`Config::unresolved`] — the file still loads, so the operator commands + /// (`--pause-signing`) work without the provider secrets. Values are never + /// logged or echoed in errors. + pub fn load_with(path: &Path, lookup: impl Fn(&str) -> Option) -> Result { let text = std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?; - let config: Config = + let mut config: Config = toml::from_str(&text).with_context(|| format!("parsing {}", path.display()))?; + config + .fill_placeholders(&lookup) + .with_context(|| format!("parsing {}", path.display()))?; config.validate()?; Ok(config) } + fn fill_placeholders(&mut self, lookup: &dyn Fn(&str) -> Option) -> Result<()> { + let mut unresolved = Vec::new(); + let mut fill = |field: String, value: &mut String| -> Result<()> { + let (filled, missing) = expand(value, lookup).with_context(|| field.clone())?; + *value = filled; + unresolved.extend(missing.into_iter().map(|name| (field.clone(), name))); + Ok(()) + }; + fill("rand.rpc".into(), &mut self.rand.rpc)?; + for url in &mut self.rand.rpcs { + fill("rand.rpcs".into(), url)?; + } + for e in &mut self.evm { + fill(format!("evm.{}.rpc", e.name), &mut e.rpc)?; + for url in &mut e.rpcs { + fill(format!("evm.{}.rpcs", e.name), url)?; + } + } + if let Some(s) = &mut self.solana { + fill("solana.rpc".into(), &mut s.rpc)?; + for url in &mut s.rpcs { + fill("solana.rpcs".into(), url)?; + } + } + if let Some(g) = &mut self.guardian { + for peer in &mut g.peers { + fill("guardian.peers".into(), peer)?; + } + } + self.unresolved = unresolved; + Ok(()) + } + + /// The names of the placeholders the environment did not fill. + pub fn unresolved_vars(&self) -> BTreeSet { + self.unresolved.iter().map(|(_, name)| name.clone()).collect() + } + + /// What this config lacks to run a guardian on a public chain (BR-601), + /// one line each; empty when nothing is missing. Required: every watched + /// chain (Rand, each `[[evm]]`, `[solana]`) read through at least two + /// distinct providers at an `rpc_quorum` of at least two (BR-4), a + /// non-empty `guardian.peers` (BR-502), a `[guardian.limits]` section + /// (BRG-1), and every `${NAME}` placeholder filled. An unfilled provider + /// or peer does not count. + pub fn mainnet_guardian_gaps(&self) -> Vec { + let mut gaps: Vec = self + .unresolved + .iter() + .map(|(field, name)| format!("{field}: ${{{name}}} is not set in the environment")) + .collect(); + let mut chain = |what: &str, (urls, quorum): (Vec, usize)| { + let n = urls.iter().filter(|u| !has_placeholder(u)).count(); + if n < 2 || quorum < 2 { + gaps.push(format!( + "{what}: {n} provider(s) at rpc_quorum {quorum}; a public chain needs at least 2 independent providers (rpcs) at an rpc_quorum of at least 2 (BR-4)" + )); + } + }; + chain("rand", self.rand.providers()); + for e in &self.evm { + chain(&format!("evm.{}", e.name), e.providers()); + } + if let Some(s) = &self.solana { + chain("solana", s.providers()); + } + match &self.guardian { + None => gaps.push("no [guardian] section".into()), + Some(g) => { + if !g.peers.iter().any(|p| !p.trim().is_empty() && !has_placeholder(p)) { + gaps.push( + "guardian.peers is empty: a first signature is checked against this guardian's own store only (BR-502)" + .into(), + ); + } + if g.limits.is_none() { + gaps.push( + "no [guardian.limits]: signing would be uncapped per transfer and per window (BRG-1)" + .into(), + ); + } + } + } + gaps + } + fn validate(&self) -> Result<()> { hex32(&self.rand.emitter).context("rand.emitter")?; self.rand.genesis()?; @@ -458,6 +578,45 @@ impl Config { } } +fn has_placeholder(s: &str) -> bool { + s.contains("${") +} + +/// `value` with each `${NAME}` (NAME: a letter or `_`, then letters, digits, +/// `_`) replaced by `lookup(NAME)`, and the names left unfilled (unset or +/// empty; written back as they were). A malformed placeholder is an error. +fn expand(value: &str, lookup: &dyn Fn(&str) -> Option) -> Result<(String, Vec)> { + let mut out = String::with_capacity(value.len()); + let mut missing = Vec::new(); + let mut rest = value; + while let Some(start) = rest.find("${") { + out.push_str(&rest[..start]); + let after = &rest[start + 2..]; + let end = after + .find('}') + .ok_or_else(|| anyhow!("an unterminated ${{…}} placeholder"))?; + let name = &after[..end]; + let valid = name + .chars() + .next() + .is_some_and(|c| c.is_ascii_alphabetic() || c == '_') + && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '_'); + if !valid { + bail!("a placeholder must be ${{NAME}} with NAME of letters, digits and _, got ${{{name}}}"); + } + match lookup(name).filter(|v| !v.is_empty()) { + Some(v) => out.push_str(&v), + None => { + out.push_str(&rest[start..start + 2 + end + 1]); + missing.push(name.to_string()); + } + } + rest = &after[end + 1..]; + } + out.push_str(rest); + Ok((out, missing)) +} + /// `[rpc] + rpcs`, without repeats, in order, and the quorum over them. pub fn providers(rpc: &str, rpcs: &[String], quorum: Option) -> (Vec, usize) { let mut list: Vec = Vec::new(); diff --git a/daemons/src/rpc.rs b/daemons/src/rpc.rs index b195fc7..fd62b8b 100644 --- a/daemons/src/rpc.rs +++ b/daemons/src/rpc.rs @@ -37,8 +37,12 @@ impl JsonRpc { .json(&request) .send() .await + // The URL may carry a provider's API key (a `${NAME}` placeholder, + // filled at load): errors name the host only. + .map_err(reqwest::Error::without_url) .with_context(|| format!("{method} to {}", self.shown()))? .error_for_status() + .map_err(reqwest::Error::without_url) .with_context(|| format!("{method} to {}", self.shown()))? .json() .await diff --git a/daemons/tests/daemons.rs b/daemons/tests/daemons.rs index 73232cf..2fa63eb 100644 --- a/daemons/tests/daemons.rs +++ b/daemons/tests/daemons.rs @@ -20,11 +20,22 @@ const CONTRACT: &str = "0x1111111111111111111111111111111111111111"; const REAL_ADDRESS: &str = include_str!("fixtures/rand-address.txt"); const REAL_HASH: &str = "58bbaf413a0a303a1740c286673f0ce74199c7b64d035a7a6772468bac66b972"; +/// The guardian with the BR-601 mainnet guard overridden: these tests exercise the other startup +/// checks and the signing loop on one-provider configs. The guard itself is tested through +/// [`strict_guardian_cmd`]. fn guardian_cmd() -> Command { + let mut c = strict_guardian_cmd(); + c.env("RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS", "1"); + c +} + +/// The guardian as an operator runs it: no override of the mainnet guard (BR-601). +fn strict_guardian_cmd() -> Command { let mut c = Command::new(env!("CARGO_BIN_EXE_rand-guardian")); c.env_remove("GUARDIAN_KEY") .env_remove("GUARDIAN_PQ_SEED") - .env_remove("RAND_BRIDGE_CONFIG"); + .env_remove("RAND_BRIDGE_CONFIG") + .env_remove("RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS"); c } @@ -432,6 +443,153 @@ fn a_relayer_cannot_bind_a_taken_registration_port() { assert!(run_failing(&mut relayer_cmd(), &config).contains(&format!("binding {listen}"))); } +// ---- the mainnet guard (BR-601) ------------------------------------------------ + +/// A guardian config on Rand chain `chain_id` (none: `""`) whose Rand node does not answer, with +/// every BR-601 control in place, less the ones named in `drop` ("rpcs", "peers", "limits"). +fn guard_config(dir: &Path, chain_id: &str, drop: &[&str]) -> std::path::PathBuf { + let rand_rpcs = if drop.contains(&"rpcs") { "" } else { "rpcs = [\"http://127.0.0.1:2\"]\nrpc_quorum = 2\n" }; + let eth_rpcs = if drop.contains(&"rpcs") { "" } else { "rpcs = [\"http://127.0.0.1:4\"]\n" }; + let peers = if drop.contains(&"peers") { "" } else { "peers = [\"http://127.0.0.1:5\"]\n" }; + let limits = if drop.contains(&"limits") { + "" + } else { + "[guardian.limits]\nper_transfer = 10000000000\nper_window = 100000000000\n" + }; + // BR-1005: a guardian that names its chain names its genesis hash too. + let chain_id = if chain_id.is_empty() { + String::new() + } else { + format!("{chain_id}\ngenesis_hash = \"{}\"", "ca".repeat(32)) + }; + write_config( + dir, + &format!( + "data_dir = {data:?}\npoll_secs = 1\n[rand]\nrpc = \"http://127.0.0.1:1\"\n{rand_rpcs}{chain_id}\nemitter = {emitter:?}\n\n\ + [[evm]]\nname = \"ethereum\"\nchain = 2\nkind = \"evm\"\nrpc = \"http://127.0.0.1:3\"\n{eth_rpcs}contract = {CONTRACT:?}\nfinality = 0\n\n\ + [guardian]\nlisten = \"127.0.0.1:0\"\n{peers}\n{limits}", + data = dir.join("data"), + emitter = hex::encode(RAND_EMITTER), + ), + ) +} + +/// What the guardian printed, run to its first failure with a valid key. +fn failure(mut c: Command, config: &Path) -> String { + run_failing(c.env("GUARDIAN_KEY", format!("{:064x}", 1)), config) +} + +/// Refused by the guard: the node was never asked for its chain id. +fn refused(text: &str) -> bool { + text.contains("BR-601") && text.contains("refusing to start") && !text.contains("rand_chainId") +} + +/// Past the guard: the next startup check (the Rand node, which does not answer) stopped it. +fn past_the_guard(text: &str) -> bool { + !text.contains("refusing to start") && text.contains("rand_chainId") +} + +#[test] +fn a_guardian_on_a_public_chain_refuses_to_start_without_its_guards() { + let dir = tempfile::tempdir().unwrap(); + let config = guard_config(dir.path(), "chain_id = 21", &["rpcs", "peers", "limits"]); + let text = failure(strict_guardian_cmd(), &config); + assert!(refused(&text), "{text}"); + for gap in ["rand: 1 provider", "evm.ethereum: 1 provider", "guardian.peers", "[guardian.limits]"] { + assert!(text.contains(gap), "{gap} not named: {text}"); + } + assert!(text.contains("--unsafe-skip-mainnet-guards"), "the override is named: {text}"); +} + +#[test] +fn each_missing_guard_alone_stops_a_public_chain_guardian() { + for (drop, named) in [ + ("rpcs", "evm.ethereum: 1 provider"), + ("peers", "guardian.peers"), + ("limits", "[guardian.limits]"), + ] { + let dir = tempfile::tempdir().unwrap(); + let text = failure(strict_guardian_cmd(), &guard_config(dir.path(), "chain_id = 21", &[drop])); + assert!(refused(&text) && text.contains(named), "{drop}: {text}"); + } + // A config that names no chain is not exempt. + let dir = tempfile::tempdir().unwrap(); + let text = failure(strict_guardian_cmd(), &guard_config(dir.path(), "", &["peers"])); + assert!(refused(&text) && text.contains("guardian.peers"), "{text}"); + // An unset provider placeholder is a gap, named by its variable. + let dir = tempfile::tempdir().unwrap(); + let config = guard_config(dir.path(), "chain_id = 21", &[]); + let text = std::fs::read_to_string(&config).unwrap().replace("http://127.0.0.1:4", "${GUARDIAN_RPC_TEST_UNSET}"); + std::fs::write(&config, text).unwrap(); + let text = failure(strict_guardian_cmd(), &config); + assert!(refused(&text) && text.contains("GUARDIAN_RPC_TEST_UNSET"), "{text}"); +} + +#[test] +fn a_fully_guarded_public_chain_guardian_and_a_devnet_guardian_start() { + let dir = tempfile::tempdir().unwrap(); + let text = failure(strict_guardian_cmd(), &guard_config(dir.path(), "chain_id = 21", &[])); + assert!(past_the_guard(&text), "{text}"); + // A devnet (chain ids under 14) is not held to the guard; the node check still applies. + let text = failure(strict_guardian_cmd(), &guard_config(dir.path(), "chain_id = 7", &["rpcs", "peers", "limits"])); + assert!(past_the_guard(&text), "{text}"); +} + +#[test] +fn the_unsafe_override_starts_an_unguarded_guardian_and_says_so() { + let dir = tempfile::tempdir().unwrap(); + let config = guard_config(dir.path(), "chain_id = 21", &["rpcs", "peers", "limits"]); + let mut flag = strict_guardian_cmd(); + flag.arg("--unsafe-skip-mainnet-guards"); + let mut env = strict_guardian_cmd(); + env.env("RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS", "1"); + for c in [flag, env] { + let text = failure(c, &config); + assert!(past_the_guard(&text), "{text}"); + assert!(text.contains("UNSAFE") && text.contains("guardian.peers"), "the gaps are logged: {text}"); + } + // A false value is no override. + for off in ["0", "false"] { + let mut c = strict_guardian_cmd(); + c.env("RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS", off); + let text = failure(c, &config); + assert!(refused(&text), "{off}: {text}"); + } +} + +#[test] +fn check_config_reports_the_gaps_without_a_key() { + let dir = tempfile::tempdir().unwrap(); + let bad = guard_config(dir.path(), "chain_id = 21", &["peers"]); + let o = strict_guardian_cmd().arg("--config").arg(&bad).arg("--check-config").output().unwrap(); + let text = String::from_utf8_lossy(&o.stderr); + assert!(!o.status.success() && text.contains("BR-601") && text.contains("guardian.peers"), "{text}"); + // The override does not make a bad config pass the check. + let o = guardian_cmd().arg("--config").arg(&bad).arg("--check-config").output().unwrap(); + assert!(!o.status.success()); + let dir = tempfile::tempdir().unwrap(); + let good = guard_config(dir.path(), "chain_id = 21", &[]); + let o = strict_guardian_cmd().arg("--config").arg(&good).arg("--check-config").output().unwrap(); + assert!(o.status.success(), "{}", String::from_utf8_lossy(&o.stderr)); + assert!(String::from_utf8_lossy(&o.stdout).contains("config OK for Rand chain 21")); +} + +#[test] +fn the_operator_commands_work_on_an_unguarded_config() { + // Pausing is the emergency brake: it must not wait on the provider secrets or the guard. + let dir = tempfile::tempdir().unwrap(); + let config = guard_config(dir.path(), "chain_id = 21", &["rpcs", "peers", "limits"]); + let o = strict_guardian_cmd() + .arg("--config") + .arg(&config) + .args(["--pause-signing", "drill"]) + .output() + .unwrap(); + assert!(o.status.success(), "{}", String::from_utf8_lossy(&o.stderr)); + let o = strict_guardian_cmd().arg("--config").arg(&config).arg("--resume-signing").output().unwrap(); + assert!(o.status.success(), "{}", String::from_utf8_lossy(&o.stderr)); +} + // ---- a guardian that runs ------------------------------------------------------ fn rand_node(burns: Vec, chain_id: u64, guardians: &[GuardianKey]) -> Fake { diff --git a/daemons/tests/mainnet_guard.rs b/daemons/tests/mainnet_guard.rs new file mode 100644 index 0000000..1439207 --- /dev/null +++ b/daemons/tests/mainnet_guard.rs @@ -0,0 +1,225 @@ +//! BR-601: on a public Rand chain a guardian's multi-provider quorum (BR-4), peer check (BR-502) +//! and caps (BRG-1) are required, not opt-in. `Config::mainnet_guardian_gaps` lists what a config +//! lacks; `rand-guardian` refuses to start on a non-empty list (tests/daemons.rs). Provider URLs +//! that carry API keys come from the environment through `${NAME}` placeholders. + +use std::collections::{BTreeMap, BTreeSet}; + +use bridge_daemons::config::{is_public_rand_chain, Config, FIRST_PUBLIC_RAND_CHAIN_ID}; + +const CONTRACT: &str = "0x1111111111111111111111111111111111111111"; + +/// A guardian config on chain 21 with every BR-601 control in place. +fn hardened() -> String { + format!( + r#" +data_dir = "./data" +[rand] +rpc = "http://127.0.0.1:8545" +rpcs = ["http://127.0.0.1:8645"] +rpc_quorum = 2 +chain_id = 21 +emitter = "{emitter}" + +[[evm]] +name = "ethereum" +chain = 2 +kind = "evm" +rpc = "https://one.example" +rpcs = ["https://two.example", "https://three.example"] +rpc_quorum = 2 +contract = "{CONTRACT}" +finality = "finalized" + +[solana] +rpc = "https://sol-one.example" +rpcs = ["https://sol-two.example"] +program = "FGA3kY3RjfDKjUszJESMYtYXAbsnkFhhoxM3Mb34vycu" + +[guardian] +listen = "127.0.0.1:7071" +peers = ["http://127.0.0.1:7172"] + +[guardian.limits] +per_transfer = 10000000000 +per_window = 100000000000 +"#, + emitter = "aa".repeat(32) + ) +} + +fn load_with(text: &str, env: &[(&str, &str)]) -> anyhow::Result { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("c.toml"); + std::fs::write(&path, text).unwrap(); + let env: BTreeMap = env.iter().map(|(k, v)| (k.to_string(), v.to_string())).collect(); + Config::load_with(&path, |name| env.get(name).cloned()) +} + +fn gaps(text: &str) -> Vec { + load_with(text, &[]).unwrap().mainnet_guardian_gaps() +} + +fn has(gaps: &[String], needle: &str) -> bool { + gaps.iter().any(|g| g.contains(needle)) +} + +#[test] +fn public_chains_are_14_and_up_and_an_unnamed_chain_counts_as_public() { + // BRG-901: chains 14-19 bind the chain id, 20 onward the genesis; both are public. Ids below + // 14 are devnets and retired testnets. A config that names no chain is not exempt: nothing + // then ties it to a test chain (the node's id is compared only when one is configured). + assert_eq!(FIRST_PUBLIC_RAND_CHAIN_ID, 14); + for id in [14, 19, 20, 21, 22, 1_000] { + assert!(is_public_rand_chain(Some(id)), "{id}"); + } + for id in [0, 5, 7, 13] { + assert!(!is_public_rand_chain(Some(id)), "{id}"); + } + assert!(is_public_rand_chain(None)); +} + +#[test] +fn a_hardened_config_has_no_gaps() { + assert_eq!(gaps(&hardened()), Vec::::new()); +} + +#[test] +fn one_provider_on_any_watched_chain_is_a_gap() { + let text = hardened().replace("rpcs = [\"https://two.example\", \"https://three.example\"]\nrpc_quorum = 2\n", ""); + let g = gaps(&text); + assert!(has(&g, "evm.ethereum") && has(&g, "BR-4"), "{g:?}"); + assert_eq!(g.len(), 1, "{g:?}"); + + let text = hardened().replace("rpcs = [\"http://127.0.0.1:8645\"]\nrpc_quorum = 2\n", ""); + let g = gaps(&text); + assert!(has(&g, "rand:"), "{g:?}"); + + let text = hardened().replace("rpcs = [\"https://sol-two.example\"]\n", ""); + let g = gaps(&text); + assert!(has(&g, "solana:"), "{g:?}"); + + // A repeated provider is one provider. + let text = hardened().replace("[\"https://sol-two.example\"]", "[\"https://SOL-ONE.example/\"]"); + assert!(has(&gaps(&text), "solana:")); +} + +#[test] +fn a_quorum_of_one_over_several_providers_is_a_gap() { + let text = hardened().replace( + "rpcs = [\"https://two.example\", \"https://three.example\"]\nrpc_quorum = 2", + "rpcs = [\"https://two.example\", \"https://three.example\"]\nrpc_quorum = 1", + ); + let g = gaps(&text); + assert!(has(&g, "evm.ethereum") && has(&g, "rpc_quorum 1"), "{g:?}"); +} + +#[test] +fn no_peers_is_a_gap() { + let g = gaps(&hardened().replace("peers = [\"http://127.0.0.1:7172\"]\n", "")); + assert!(has(&g, "guardian.peers") && has(&g, "BR-502"), "{g:?}"); + assert_eq!(g.len(), 1, "{g:?}"); +} + +#[test] +fn no_limits_is_a_gap() { + let text = hardened(); + let cut = text.find("[guardian.limits]").unwrap(); + let g = gaps(&text[..cut]); + assert!(has(&g, "[guardian.limits]") && has(&g, "BRG-1"), "{g:?}"); + assert_eq!(g.len(), 1, "{g:?}"); +} + +#[test] +fn no_guardian_section_is_a_gap() { + let text = hardened(); + let cut = text.find("[guardian]").unwrap(); + assert!(has(&gaps(&text[..cut]), "[guardian]")); +} + +#[test] +fn placeholders_are_filled_from_the_environment() { + let text = hardened().replace("https://three.example", "https://three.example/v2/${TEST_KEY}"); + let config = load_with(&text, &[("TEST_KEY", "s3cret")]).unwrap(); + assert!(config.evm[0].rpcs.contains(&"https://three.example/v2/s3cret".to_string())); + assert!(config.unresolved.is_empty()); + assert_eq!(config.mainnet_guardian_gaps(), Vec::::new()); + + // Unset (or empty), the placeholder stays as written and is a gap naming the variable, never + // its value; the file still loads, so --pause-signing works without the provider secrets. + for env in [&[][..], &[("TEST_KEY", "")][..]] { + let config = load_with(&text, env).unwrap(); + assert_eq!(config.unresolved_vars(), BTreeSet::from(["TEST_KEY".to_string()])); + let g = config.mainnet_guardian_gaps(); + assert!(has(&g, "TEST_KEY") && has(&g, "evm.ethereum.rpcs"), "{g:?}"); + } + + // An unresolved provider does not count toward the quorum. + let text = hardened().replace("\"http://127.0.0.1:8645\"", "\"${RAND_TWO}\""); + let g = load_with(&text, &[]).unwrap().mainnet_guardian_gaps(); + assert!(has(&g, "RAND_TWO") && has(&g, "rand: 1 provider"), "{g:?}"); + + // Peers take placeholders too. + let text = hardened().replace("\"http://127.0.0.1:7172\"", "\"${PEER}\""); + let g = load_with(&text, &[]).unwrap().mainnet_guardian_gaps(); + assert!(has(&g, "PEER") && has(&g, "guardian.peers"), "{g:?}"); + let config = load_with(&text, &[("PEER", "http://10.0.0.2:7071")]).unwrap(); + assert_eq!(config.guardian.unwrap().peers, vec!["http://10.0.0.2:7071".to_string()]); + + // A malformed placeholder is a load error. + for bad in ["https://x.example/${KEY", "https://x.example/${}", "https://x.example/${9X}", "https://x.example/${A-B}"] { + let err = load_with(&hardened().replace("https://three.example", bad), &[]).unwrap_err(); + assert!(format!("{err:#}").contains("placeholder"), "{bad}: {err:#}"); + } +} + +/// The variables the repository's mainnet guardian configs leave to each host's environment. +const MAINNET_VARS: [&str; 5] = [ + "GUARDIAN_RPC_BSC", + "GUARDIAN_RPC_ETHEREUM", + "GUARDIAN_RPC_RAND", + "GUARDIAN_RPC_SOLANA", + "GUARDIAN_RPC_TRON", +]; + +fn mainnet_guardian(i: usize, env: &BTreeMap) -> Config { + let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(format!("mainnet/guardian-{i}.toml")); + Config::load_with(&path, |name| env.get(name).cloned()).unwrap_or_else(|e| panic!("guardian-{i}: {e:#}")) +} + +#[test] +fn every_mainnet_guardian_config_passes_the_guard_once_its_environment_is_set() { + let env: BTreeMap = MAINNET_VARS + .iter() + .map(|v| (v.to_string(), format!("https://{}.provider.example/key", v.to_lowercase()))) + .collect(); + for i in 1..=8 { + let config = mainnet_guardian(i, &env); + assert!(is_public_rand_chain(config.rand.chain_id), "guardian-{i}"); + assert_eq!(config.mainnet_guardian_gaps(), Vec::::new(), "guardian-{i}"); + // Every watched chain at a quorum of 2 over at least 2 providers, and the peers are the + // other guardians, never this one. + let guardian = config.guardian.as_ref().unwrap(); + assert!(!guardian.peers.is_empty(), "guardian-{i}"); + let own = format!("http://127.0.0.1:717{i}"); + assert!(!guardian.peers.contains(&own), "guardian-{i} lists itself"); + assert!( + !guardian.peers.iter().any(|p| p.ends_with(&guardian.listen)), + "guardian-{i} lists its own listen address" + ); + } +} + +#[test] +fn without_their_environment_the_mainnet_configs_name_exactly_the_missing_variables() { + let empty = BTreeMap::new(); + let expected: BTreeSet = MAINNET_VARS.iter().map(|v| v.to_string()).collect(); + for i in 1..=8 { + let config = mainnet_guardian(i, &empty); + assert_eq!(config.unresolved_vars(), expected, "guardian-{i}"); + let g = config.mainnet_guardian_gaps(); + for v in MAINNET_VARS { + assert!(has(&g, v), "guardian-{i}: {v} not reported in {g:?}"); + } + } +} diff --git a/docs/guardian-hosts.md b/docs/guardian-hosts.md index e85214c..38712a6 100644 --- a/docs/guardian-hosts.md +++ b/docs/guardian-hosts.md @@ -40,9 +40,125 @@ To update the guardian binary on a host: build it (`cargo build --release --lock `install -m 755` it to `/usr/local/bin/` and `systemctl restart rand-guardian`. Do one host at a time, because the quorum tolerates two down. -Configure each guardian with more than one independent RPC per chain (`rpcs`, `rpc_quorum`; BR-4) -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. +## The mainnet guard (BR-601) + +On a public Rand chain (`rand.chain_id` 14 or higher, or none configured) `rand-guardian` refuses to +start unless its config has all three controls: + +- every watched chain (Rand, each `[[evm]]`, `[solana]`) read through **at least two distinct + providers** (`rpc` + `rpcs`) at an **`rpc_quorum` of at least 2** (BR-4); +- a non-empty **`guardian.peers`** (BR-502); +- a **`[guardian.limits]`** section (BRG-1). + +The error lists every missing control. `rand-guardian --config --check-config` runs the same +check and exits (0 when the guardian would start); it needs no key. `--unsafe-skip-mainnet-guards` +(or `RAND_GUARDIAN_UNSAFE_SKIP_MAINNET_GUARDS=1`) starts the guardian anyway, logging every missing +control at error level on each start. It is for an emergency or a dev run only, never a standing +setting. `--pause-signing`, `--resume-signing` and `--list-held` work without the check. + +### Providers + +`daemons/mainnet/guardian-.toml` lists the keyless providers verified on 2026-11-04 (each answered +`eth_getLogs` over 1,000 blocks on the endpoint contract, or `getAccountInfo` on the program), plus +one `${NAME}` placeholder per chain for a provider whose URL carries an API key. The placeholders are +filled from the guardian's environment when the config is loaded (`Config::load_with`). An unset or +empty one stays as written and counts as a missing control. RPC errors name the host only, never the +URL, so a key in a path does not reach the log. + +| chain | providers in the repo config | from the environment | quorum | +|---|---|---|---| +| Rand | `127.0.0.1:8545` (this host's node) | `GUARDIAN_RPC_RAND`: a Rand node on another host | 2 of 2 | +| Ethereum | publicnode, `rpc.mevblocker.io` | `GUARDIAN_RPC_ETHEREUM` | 2 of 3 | +| BSC | publicnode | `GUARDIAN_RPC_BSC` | 2 of 2 | +| Tron | publicnode, `api.trongrid.io` | `GUARDIAN_RPC_TRON` (origin; `/jsonrpc` is appended) | 2 of 3 | +| Solana | `api.mainnet-beta.solana.com`, publicnode | `GUARDIAN_RPC_SOLANA` | 2 of 3 | + +Choose providers run by different companies from the keyless ones above. With 2 of 2 (Rand, BSC), +one provider being down defers signing on that chain until it is back. Nothing is skipped, but on +this set every deferral stops transfers (BR-402). A third BSC provider removes that: add it to +`rpcs`. On a droplet the values go in `/etc/rand-guardian/env` (mode 600, read by systemd) next to +the keys. On the laptop, `run-guardians-set1.sh` reads `GUARDIAN_RPC_*` lines from +`~/.rand-bridge/mainnet-set1/rpc.env`. + +`GUARDIAN_RPC_RAND` must reach a Rand node that does not share this host. The public RPC +(`randscan.org/rpc`) refuses the bridge methods. Options: another guardian host's node, through an +SSH forward like the peers' below (its `tunnel` entry then also needs +`permitopen="127.0.0.1:8545"`), or a validator run by another operator. + +### Peers + +The droplet guardian APIs listen on loopback only. Guardian i's config names the other droplets as +`http://127.0.0.1:717`, so each droplet needs one SSH local forward per peer, the same way the +relayer host has them: `127.0.0.1:717` goes to guardian j's `127.0.0.1:7071`, as guardian j's +`tunnel` user. Give each host its own forwarding key. Its entry in every other host's +`~tunnel/.ssh/authorized_keys` reads `restrict,port-forwarding,permitopen="127.0.0.1:7071" `, so +a compromised host can only read the others' signature APIs. Run the forwards as a systemd template +unit (`rand-guardian-peer@.service`, restarting on drop). Host addresses stay in operator-local +files, as for `guardian-tunnels.sh`. Guardians 7 and 8 name the droplets through +`guardian-tunnels.sh` (7171-7176) and each other. + +A peer answers with its **own** signature only. The peer check catches this guardian's forgotten +signature only when some peer keeps a copy of it (`daemons/README.md`, Guardian), and no API serves +such a copy today. Pointing the peers at the other guardians satisfies the guard and adds the +liveness check (no peer answering defers the transfer), but it is not yet the restored-store +protection that BR-502 describes. + +### Rolling the guarded config to the live guardians + +The config needs the binary that has this guard, because an older binary would treat `${NAME}` as a +URL. That breaks Rand and BSC, whose quorum is 2 of 2. Roll the binary and the config together, one +host at a time. + +**Quorum during the roll (BR-402).** Set 1 needs 6 of 8 ECDSA signatures, and chain 21 needs 6 of 8 +Dilithium2 co-signatures on every mint. Guardians 7 and 8 are offline, so all six droplets must sign. +While any one droplet restarts, nothing is signed: no mint and no release. Nothing is lost. Locks and +burns stay on their chains, and each guardian signs from its cursor once it is back. Two ways to +roll: + +1. **Preferred: bring guardians 7 and 8 up first** (`run-guardians-set1.sh` with `rpc.env`, + `guardian-tunnels.sh`, `guardian-reverse-tunnel.sh`), on the new binary and config, and confirm + that the relayer reaches 7077 and 7078. Then seven of eight sign while each droplet restarts, and + releases keep flowing. Mints keep flowing only if 7 and 8 also hold their chain-21 Dilithium2 + seeds (`GUARDIAN7_PQ_SEED`, `GUARDIAN8_PQ_SEED`). Without the seeds, the PQ quorum still needs all + six droplets. +2. **Otherwise: one host at a time inside an announced window** with no transfer in flight (on the relayer host, + every entry under `data/observed/` has its match under `data/done/`). Each restart is a + short bridge-wide stop. The order among the six does not matter for quorum. Start with the host + whose provider and peer forwards were checked first. + +Never take two droplets down at once while 7 and 8 are offline. + +**Before the first host:** + +1. Build and checksum the binary (above). The owner fills the values below into each host's + `/etc/rand-guardian/env`; they are not in this repository. +2. On every droplet, install the peer forwards and the `tunnel` entries. Check that + `curl -s http://127.0.0.1:717/v1/health` answers for every j ≠ i. This touches no running + guardian. + +**Per host (i = 1..6), one at a time:** + +1. Back up: `cp -a /etc/rand-guardian.toml /etc/rand-guardian.toml.pre-br601-$(date +%F)`, and the + same for `/usr/local/bin/rand-guardian` and `/etc/rand-guardian/env`. +2. Write `/etc/rand-guardian.toml.new` as the host's current file (keep its `data_dir`, `key_env`, + `pq_seed_env`, `listen` and start blocks) plus the `rpcs`/`rpc_quorum` lines, `peers` and + `[guardian.limits]` from `daemons/mainnet/guardian-.toml`. The binary this guard ships in + also refuses a `[rand]` section without `genesis_hash` next to `chain_id` (BR-1005, + `daemons/README.md`): the 22 Oct host files predate that line, so copy it from the repository + config too. +3. Check it with the new binary, passing only the provider variables: + `env $(grep '^GUARDIAN_RPC_' /etc/rand-guardian/env | xargs) /usr/local/bin/rand-guardian.new --config /etc/rand-guardian.toml.new --check-config`. + It must print `config OK for Rand chain 21`. Stop here if it does not. +4. Swap: `install -m 755 rand-guardian.new /usr/local/bin/rand-guardian`, + `mv /etc/rand-guardian.toml.new /etc/rand-guardian.toml`, `systemctl restart rand-guardian`. +5. Verify within a minute in `journalctl -u rand-guardian`: no `refusing to start` and no `UNSAFE`; + `: 2 of RPCs must agree before signing` for every chain; ` of 5 peers answer` with n ≥ 1; a `caps:` line; and + the signature API answering through the relayer's forward. Then wait for this guardian's signature + on the next transfer, or for its cursors to reach the chain heads, before the next host. +6. Rollback if any check fails: restore the three backups and `systemctl restart rand-guardian`. + +Afterwards, record the roll (BR-602): date, host, binary sha256, config sha256, and the +`--check-config` output. Then take a fleet snapshot. **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