diff --git a/CLAUDE.md b/CLAUDE.md index 5b40153de..e69648649 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -423,17 +423,19 @@ into one `cli::Options { common, network }`, where `network` is `Network::Lean(LeanOptions)` or `Network::Mainnet { mainnet, execution }`. Each variant carries that chain's own flags, so a flag one chain does not take is unreachable on the other's path by construction rather than by an `Option` -nobody unwraps. `MainnetOptions` holds the three flags `beacon` has of its own: -`--custody-group-count`, `--safe-slots-to-import-optimistically`, and -`--network` (default `mainnet`). The last is carried unresolved: `run_node` is -where a bad value is reported. +nobody unwraps. `MainnetOptions` holds the flags `beacon` has of its own, among +them `--custody-group-count`, `--safe-slots-to-import-optimistically`, the +`--builder*` flags, `--bootnodes` (a list here; `LeanOptions` has `node`'s +file), and `--network` (default `mainnet`). The last is carried unresolved: +`run_node` is where a bad value is reported. `run_node` owns everything that is not chain-specific, in order: the discv5 port check, metrics registration, the banner and version log, the `RLIMIT_NOFILE` raise, the `HIVE_LEAN_TEST_DRIVER` early return (lean-only, and it must still precede key loading), resolving `--network` into a -`NetworkSource` (mainnet only; must precede the next step, since a loaded -network's own bootnode list is part of its fallback), reading `--bootnodes`, +`NetworkSource` (mainnet only; must precede the next step, since `beacon`'s +`--bootnodes` entries are added to the network's own bootnode list), reading +`--bootnodes` (`node`: a file of ENRs; `beacon`: an ENR/multiaddr list), building the aggregator, sync-status and event handles, opening `--data-dir`'s RocksDB backend, and `--node-key` resolution. That last one comes after the open because, without `--node-key`, the identity is `/node.key`, @@ -446,8 +448,9 @@ It then branches **once**, on `network`, both arms inline, each evaluating to a `ChainActor` saying what to spawn this chain's actor with (lean's validator keys and `BlockChainConfig`, or beacon's `Beacon` marker). The rest of the discv5 configuration is the node key, the ports, the bootnodes and the peer -target, which are operator input and identical either way, so `run_node` fills -those in once below the match rather than having each arm repeat them. +target, which are operator input (the bootnodes resolved per chain, but above +the match), so `run_node` fills those in once below the match rather than +having each arm repeat them. Everything after that match is shared again: one `build_swarm`, one `P2P::spawn`, one `start_rpc_server`, and one chain actor, since `ChainActor` selects between `BlockChain::spawn` and `BlockChain::spawn_beacon` rather than @@ -972,7 +975,7 @@ GENESIS_VALIDATORS: - All genesis state fields (checkpoints, justified_slots, etc.) initialize to zero/empty defaults - Matches Ream/Zeam format — no extra state fields in the config file -**Bootnodes:** ENR records (Base64-encoded, RLP decoded for the `quic`/`tcp`/`udp` ports + secp256k1 pubkey). A `0` port means absent everywhere, on read and on write. `build_swarm` dedups by `PeerId`: two entries naming one key merge into a single dial +**Bootnodes:** ENR records (Base64-encoded, RLP decoded for the `quic`/`tcp`/`udp` ports + secp256k1 pubkey). A `0` port means absent everywhere, on read and on write. `build_swarm` dedups by `PeerId`: two entries naming one key merge into a single dial. `node --bootnodes` names a file of them; `beacon --bootnodes` is instead a comma-separated, repeatable list of ENRs and `/ip4|ip6///p2p/` multiaddrs (Lighthouse's `--boot-nodes`: `tcp/` and `udp//quic-v1` are dialed, a bare `udp/` only seeds discv5, and is refused under `/ip6` since discovery binds IPv4 only). Its entries are added to the network's own list rather than replacing it, and a bad one fails startup where the network's own bad entries are skipped with a warning (see `docs/cli.md`) ## Testing diff --git a/bin/ethlambda/src/cli.rs b/bin/ethlambda/src/cli.rs index 5710f91ba..719b6a1f8 100644 --- a/bin/ethlambda/src/cli.rs +++ b/bin/ethlambda/src/cli.rs @@ -7,11 +7,15 @@ use std::path::PathBuf; /// Flags every sub-command takes, with the same meaning on each. /// -/// `--node-key`, `--bootnodes` and `--checkpoint-sync-url` used to be declared -/// once per sub-command because each was required on one and optional on the -/// other, and a flattened struct has one requiredness. They are optional on -/// both now, which is what lets one declaration serve both: each sub-command -/// decides what an absent value means, and says so on the field below. +/// `--node-key` and `--checkpoint-sync-url` used to be declared once per +/// sub-command because each was required on one and optional on the other, and +/// a flattened struct has one requiredness. They are optional on both now, +/// which is what lets one declaration serve both: each sub-command decides what +/// an absent value means, and says so on the field below. +/// +/// `--bootnodes` is not here: it names a file on `node` and is a list on +/// `beacon`, so each chain declares its own ([`LeanOptions::bootnodes`], +/// [`MainnetOptions::bootnodes`]). /// /// The `--discovery.*` tuning flags are here too, in one [`DiscoveryConfig`], /// and mean the same thing on both whenever discv5 runs: on @@ -52,16 +56,6 @@ pub(crate) struct CommonOptions { /// and ENR stay the same across restarts until the directory is wiped. #[arg(long)] pub(crate) node_key: Option, - /// Path to a bootnode list: ENRs, one per YAML entry. - /// - /// Optional on both sub-commands, but an absent file means different - /// things. `beacon` falls back to whatever `--network` resolved to: a - /// built-in network's own ENR list, or a loaded directory's own - /// `bootstrap_nodes.yaml`/`.txt` (empty if the directory has neither). - /// `node` has no built-in list for a lean network, so it starts with no - /// bootnodes and reaches peers only through discv5, if that is enabled. - #[arg(long)] - pub(crate) bootnodes: Option, /// Base URL(s) of the peer API servers to take a checkpoint from, e.g. /// `http://peer:5052`. /// @@ -308,6 +302,30 @@ pub(crate) struct MainnetOptions { #[arg(long, default_value = crate::network::DEFAULT_NETWORK)] pub(crate) network: String, + /// Extra bootnodes: ENRs (with or without `enr:`) and + /// `/ip4|ip6///p2p/` multiaddrs, comma-separated; + /// the flag may be repeated. + /// + /// Added to the resolved network's own bootnode list, never replacing it, + /// as Lighthouse's `--boot-nodes` is. Unlike Lighthouse, a multiaddr must + /// end in `/p2p/` and DNS multiaddrs are refused. Unlike an entry + /// in the network's list, a bad one here is a startup error, and a file + /// path is no longer accepted. See `docs/cli.md#bootnodes-on-beacon`. + // + // `allow_hyphen_values` because an ENR written without its `enr:` prefix + // can start with `-`, which clap would otherwise read as a flag. Each + // occurrence takes one value, so a list never swallows the flag after it, + // but a `--bootnodes` given no value (an unset variable in a launch + // script) takes the next flag as its value; `beacon_bootnodes` refuses + // such an entry by name. + #[arg( + long, + value_name = "ENR/MULTIADDR LIST", + value_delimiter = ',', + allow_hyphen_values = true + )] + pub(crate) bootnodes: Vec, + /// Base URL of a builder API endpoint, normally MEV-Boost (for example /// `http://127.0.0.1:18550`) or a relay directly. Without it every block /// is built locally, and `register_validator` answers 500 so a validator @@ -380,6 +398,13 @@ pub(crate) struct LeanOptions { /// The node ID to look up in annotated_validators.yaml (e.g., "ethlambda_0") #[arg(long)] pub(crate) node_id: String, + /// Path to a bootnode list: ENRs, one per YAML entry. + /// + /// Optional. A lean network has no built-in list, so without it the node + /// starts with no bootnodes and reaches peers only through discv5, if + /// that is enabled, or by being dialed. + #[arg(long)] + pub(crate) bootnodes: Option, /// Whether this node acts as a committee aggregator. /// /// Seeds the initial value of the live aggregator flag shared by the @@ -886,8 +911,8 @@ mod tests { ["https://checkpointz.example"] ); assert_eq!(options.common.node_key, Some(PathBuf::from("node.key"))); - // No flag given, so the built-in mainnet ENR list applies. - assert_eq!(options.common.bootnodes, None); + // No flag given, so the built-in mainnet ENR list applies alone. + assert!(options.mainnet.bootnodes.is_empty()); } /// Drop `flag` and the value after it from an argv. @@ -901,24 +926,80 @@ mod tests { args } - /// The three flags that moved into [`CommonOptions`] are optional on both - /// sub-commands, so clap accepts an argv carrying none of them. What an - /// absent value *means* is each sub-command's own decision, made at - /// startup in `main`; the two tests after this one pin the answers that - /// are not simply "carry on with nothing". + /// The flags that moved into [`CommonOptions`] are optional on both + /// sub-commands, and so is each chain's own `--bootnodes`, so clap accepts + /// an argv carrying none of them. What an absent value *means* is each + /// sub-command's own decision, made at startup in `main`; the two tests + /// after this one pin the answers that are not simply "carry on with + /// nothing". #[test] fn the_shared_flags_are_optional_on_both_sub_commands() { let node = parse_node(without(&without(&base_args(), "--node-key"), "--bootnodes")); assert_eq!(node.common.node_key, None); - assert_eq!(node.common.bootnodes, None); + assert_eq!(node.lean.bootnodes, None); assert!(node.common.checkpoint_sync_url.is_empty()); let beacon = parse_beacon(vec!["ethlambda", "beacon"]); assert_eq!(beacon.common.node_key, None); - assert_eq!(beacon.common.bootnodes, None); + assert!(beacon.mainnet.bootnodes.is_empty()); assert!(beacon.common.checkpoint_sync_url.is_empty()); } + /// Commas split one occurrence and repeated occurrences add up, in order. + /// The trailing `--network` is the point: `allow_hyphen_values` must not + /// let a list swallow the flag after it. + #[test] + fn beacon_bootnodes_combines_commas_and_repeats_in_order() { + let mut args = beacon_args(); + args.extend([ + "--bootnodes", + "enr:a,/ip4/1.2.3.4/tcp/9000/p2p/b", + "--bootnodes", + "enr:c", + "--network", + "sepolia", + ]); + let beacon = parse_beacon(args); + assert_eq!( + beacon.mainnet.bootnodes, + ["enr:a", "/ip4/1.2.3.4/tcp/9000/p2p/b", "enr:c"] + ); + assert_eq!(beacon.mainnet.network, "sepolia"); + } + + /// An ENR written without its `enr:` prefix can start with `-`, which clap + /// would read as a flag without `allow_hyphen_values`. + #[test] + fn beacon_bootnodes_accepts_a_prefixless_enr_starting_with_a_hyphen() { + let enr = "-IW4QGGifTt9ypyMtChDISUNX3z4z5iPdiEPOmBoILvnDuWIKbWVmKXxZERPnw0piQyaBNCENFEPoIi-vxsnsrBig9MBgmlkgnY0gmlwhH8AAAGEcXVpY4IjKYlzZWNwMjU2azGhAhMMnGF1rmIPQ9tWgqfkNmvsG-aIyc9EJU5JFo3Tegys"; + let mut args = beacon_args(); + args.extend(["--bootnodes", enr]); + assert_eq!(parse_beacon(args).mainnet.bootnodes, [enr]); + } + + /// An empty value and a trailing comma parse, and refusing them is not + /// clap's job: any empty entry they leave is skipped at startup + /// (`main::beacon_bootnodes`). Neither assertion pins how many empty + /// entries clap leaves (none or one), since startup handles both. + #[test] + fn beacon_bootnodes_parses_an_empty_value_and_a_trailing_comma() { + let mut args = beacon_args(); + args.extend(["--bootnodes", ""]); + assert!( + parse_beacon(args) + .mainnet + .bootnodes + .iter() + .all(String::is_empty) + ); + + let mut args = beacon_args(); + args.extend(["--bootnodes", "enr:a,"]); + let bootnodes = parse_beacon(args).mainnet.bootnodes; + assert_eq!(bootnodes.first().map(String::as_str), Some("enr:a")); + assert!(bootnodes[1..].iter().all(String::is_empty), "{bootnodes:?}"); + } + #[test] fn beacon_needs_no_checkpoint_sync_url() { // `--checkpoint-sync-url` was once `required = true` here, because the diff --git a/bin/ethlambda/src/command.rs b/bin/ethlambda/src/command.rs index 0b9199b1f..1ec8c25ad 100644 --- a/bin/ethlambda/src/command.rs +++ b/bin/ethlambda/src/command.rs @@ -262,6 +262,8 @@ mod tests { assert_eq!(options.lean.node_id, "ethlambda_0"); assert_eq!(options.common.gossipsub_port, 9001); assert!(options.lean.is_aggregator); + // Still one file path: only `beacon`'s `--bootnodes` became a list. + assert_eq!(options.lean.bootnodes, Some(PathBuf::from("nodes.yaml"))); } #[test] diff --git a/bin/ethlambda/src/main.rs b/bin/ethlambda/src/main.rs index ad76bf4eb..bad3ba0a1 100644 --- a/bin/ethlambda/src/main.rs +++ b/bin/ethlambda/src/main.rs @@ -55,8 +55,9 @@ use ethlambda_network_api::{ ToRpcToP2PRef, }; use ethlambda_p2p::{ - LeanWireConfig, P2P, PeerId, SwarmConfig, WireConfig, attestation_subscription_subnets, - build_swarm, discovery::DiscoverySpawnConfig, parse_enrs, + Bootnode, LeanWireConfig, P2P, PeerId, SwarmConfig, WireConfig, + attestation_subscription_subnets, build_swarm, discovery::DiscoverySpawnConfig, parse_bootnode, + parse_enrs, }; use ethlambda_state_transition::beacon::fork_choice; use ethlambda_types::primitives::{H256, HashTreeRoot as _}; @@ -262,9 +263,10 @@ struct RunningNode { /// /// Split out of [`DiscoverySpawnConfig`] because the other eight fields there /// are the node key, the ports, the bootnodes and the peer target: operator -/// input, identical on either chain. Writing the whole config in each arm meant -/// typing those eight out twice, where the compiler could not tell if the two -/// copies drifted. +/// input, filled in the same way on either chain (the bootnodes are resolved +/// per chain, but before the chain match). Writing the whole config in each arm +/// meant typing those eight out twice, where the compiler could not tell if the +/// two copies drifted. struct DiscoveryWireEntries { subscription_subnets: HashSet, attestation_committee_count: u64, @@ -312,8 +314,9 @@ struct ChainSetup { wire: WireConfig, /// The ENR entries that describe the wire above: the only part of the discv5 /// configuration the two chains disagree about. Everything else in - /// [`DiscoverySpawnConfig`] is operator-supplied and identical either way, - /// so it is filled in once, below the match. + /// [`DiscoverySpawnConfig`] is operator-supplied, the bootnodes included + /// (resolved per chain above the match), so it is filled in once, below + /// the match. discovery: DiscoveryWireEntries, /// Backs the req/resp handlers on both chains. Both start from the /// checkpoint anchor `fetch_initial_state`/`fetch_initial_beacon_state` @@ -428,30 +431,24 @@ async fn run_node(options: Options) -> eyre::Result<()> { let p2p_socket = SocketAddr::new(IpAddr::from([0, 0, 0, 0]), common.gossipsub_port); - // Resolved once, here, above the bootnode fallback below that reads it: - // `default_bootnodes` needs the loaded network's own bootnode list, and - // loading a directory decodes a multi-megabyte genesis state, so this must - // not run twice for one process. `network` is matched by reference so it - // is still available, below, to be matched by value into `ChainSetup`. - let network_source = match &network { - Network::Lean(_) => None, + // The network and the bootnodes, each resolved once, here, for the swarm + // and discv5 below. The network comes first: `beacon`'s `--bootnodes` + // entries are added to its own list, and loading a directory decodes a + // multi-megabyte genesis state, so it must not run twice for one process. + // `--bootnodes` means a different thing on each chain: a file of ENRs on + // `node`, a list added to the network's own on `beacon`. `network` is + // matched by reference so it is still available, below, to be matched by + // value into `ChainSetup`. + let (network_source, bootnodes) = match &network { + Network::Lean(lean) => (None, lean_bootnodes(lean.bootnodes.as_deref())?), Network::Mainnet { mainnet, .. } => { let spec = network::NetworkSpec::parse(&mainnet.network)?; - Some(network::NetworkSource::resolve(&spec)?) + let source = network::NetworkSource::resolve(&spec)?; + let bootnodes = beacon_bootnodes(&mainnet.bootnodes, source.bootnodes())?; + (Some(source), bootnodes) } }; - // The `--bootnodes` file, read and parsed once. An absent flag is not an - // empty list: `default_bootnodes` is what each chain falls back to. - let bootnodes = parse_enrs( - common - .bootnodes - .as_deref() - .map(read_bootnode_strings) - .transpose()? - .unwrap_or_else(|| default_bootnodes(network_source.as_ref())), - ); - // Shared, runtime-mutable aggregator flag, seeded from the CLI flag only // `node` takes: mainnet has no aggregation duty. Threaded into both the // blockchain actor, which reads it on every tick, and the API server, whose @@ -684,7 +681,6 @@ async fn run_node(options: Options) -> eyre::Result<()> { info!( network = %source.name(), - bootnodes = ?common.bootnodes, gossipsub_port = common.gossipsub_port, http_address = %common.http_address, metrics_port = common.metrics_port, @@ -780,9 +776,10 @@ async fn run_node(options: Options) -> eyre::Result<()> { } }; - // The operator-supplied half of the discv5 configuration, which neither - // chain varies. Built before `build_swarm` because that moves the node key - // and the bootnode list. `None` on a lean node without `--discovery.enable`, + // The operator-supplied half of the discv5 configuration, which the chain + // match does not vary (the bootnodes were resolved per chain above it). + // Built before `build_swarm` because that moves the node key and the + // bootnode list. `None` on a lean node without `--discovery.enable`, // which then peers from the bootnode list alone. let discovery = discovery_enabled.then(|| DiscoverySpawnConfig { node_key: node_p2p_key.clone(), @@ -1065,32 +1062,133 @@ async fn wait_for_shutdown(node: RunningNode) { info!("Shutdown complete"); } -/// The ENRs to start from when `--bootnodes` was not given. +/// `node`'s bootnodes: the ENRs in its `--bootnodes` file, if one was given. /// -/// A resolved network (built-in mainnet, or a loaded directory) publishes its -/// own bootnode list, so an absent flag means "use it". A lean network's ENRs -/// are per-deployment, so there is nothing to default to and an absent flag -/// means this node reaches peers only through discv5, which a lean node runs -/// only with `--discovery.enable`, or by being dialed. That case warns, because -/// a node that then finds nobody is islanded and otherwise looks healthy. -fn default_bootnodes(source: Option<&network::NetworkSource>) -> Vec { - match source { +/// A lean network's ENRs are per-deployment, so there is no list to default to +/// and an absent flag means this node reaches peers only through discv5, which +/// a lean node runs only with `--discovery.enable`, or by being dialed. That +/// case warns, and so does a file that yields no usable ENR, because a node +/// that then finds nobody is islanded and otherwise looks healthy. A file that +/// was named and cannot be read is an error, so a typo does not look like "no +/// peers". +fn lean_bootnodes(file: Option<&Path>) -> eyre::Result> { + match file { + Some(path) => { + let bootnodes = parse_enrs(read_bootnode_strings(path)?); + // `parse_enrs` words its own warning for the list, since `beacon` + // adds to its result; here the file is the node's whole list. + if bootnodes.is_empty() { + warn!( + file = %path.display(), + "The --bootnodes file gave no usable bootnode: starting with no bootnodes." + ); + } + Ok(bootnodes) + } None => { warn!( "No --bootnodes file supplied: starting with no bootnodes. This node can \ only find peers via discv5 (--discovery.enable) or by being dialed." ); - Vec::new() + Ok(Vec::new()) + } + } +} + +/// `beacon`'s bootnodes: its `--bootnodes` entries, then the resolved +/// network's own list. +/// +/// Additive, as Lighthouse's `--boot-nodes` is, so naming one extra peer never +/// costs the node the network's published seeds. The two halves fail +/// differently on purpose. A command-line entry was typed to reach that peer, +/// so one that does not parse aborts startup rather than leave the node on a +/// list it was not given; the network's list keeps [`parse_enrs`]' rule and +/// skips a bad entry with a warning. Duplicates are left for `build_swarm`, +/// which merges bootnodes by peer id. +/// +/// Logs the two counts once: the network's half can shrink silently through +/// skipped entries, and the line is what shows how much of the list the +/// command line contributed. Warns when the result is empty, which leaves +/// discv5 with no seed. +fn beacon_bootnodes( + cli_entries: &[String], + network_entries: Vec, +) -> eyre::Result> { + let mut bootnodes = Vec::new(); + // A blank entry is skipped here, where `parse_bootnode` would refuse it: + // `--bootnodes ""` and a trailing comma both leave one, and mean + // "nothing". + for entry in cli_entries.iter().map(|entry| entry.trim()) { + if entry.is_empty() { + continue; + } + // `allow_hyphen_values` lets a value-less `--bootnodes` take the next + // flag as its value. No ENR starts with `--`, so this is that flag, + // not a bootnode. An ENR is an RLP list whose payload is over 55 bytes + // (the signature alone is 64) and at most 300, so its first byte is + // 0xf8 or 0xf9. In base64 that byte's top six bits (111110) make the + // first character `-`, and its low two bits (00 or 01) put the second + // character in A-Z or a-f, never `-`. + if entry.starts_with("--") { + eyre::bail!( + "--bootnodes was given no value: it took the flag \"{entry}\" as its value" + ); } - Some(source) => source.bootnodes(), + let bootnode = parse_bootnode(entry).map_err(|reason| { + // `--bootnodes` named a file on `beacon` until it became a list, + // and launch scripts still pass one. Checked only after a parse + // failure, so no entry that parses is ever read from disk. A + // bootnode file's usual extensions count too, so a path that does + // not exist (a typo, or a file the launcher stopped writing) gets + // the same hint rather than a decoding error. + let path = Path::new(entry); + let file_like = path.is_file() + || matches!( + path.extension().and_then(|ext| ext.to_str()), + Some("yaml" | "yml" | "txt") + ); + if file_like { + eyre::eyre!( + "--bootnodes entry \"{entry}\" looks like a file: beacon --bootnodes \ + now takes a comma-separated list of ENRs and multiaddrs, not a file. \ + Pass the records themselves, joined with commas, without a YAML \ + list's \"- \" markers or any comments. They are added to the \ + network's own bootnodes, not put in their place; a network loaded \ + from a directory can list them in its bootstrap_nodes.yaml instead" + ) + } else { + eyre::eyre!("invalid --bootnodes entry \"{entry}\": {reason}") + } + })?; + bootnodes.push(bootnode); } + let from_command_line = bootnodes.len(); + + let from_network = parse_enrs(network_entries); + info!( + from_command_line, + from_network = from_network.len(), + "Resolved bootnodes" + ); + bootnodes.extend(from_network); + // `parse_enrs` warns about its own list only, and only when that list + // named entries; a network directory with no bootnode file names none. + if bootnodes.is_empty() { + warn!( + "No bootnodes: neither --bootnodes nor the network's own list gave one. \ + discv5 has no seed, so this node finds peers only when one reaches it first." + ); + } + Ok(bootnodes) } /// Read a bootnode file into one ENR string per entry. /// -/// Shared by both chains: [`run_node`] reads the file once and hands the result -/// to [`parse_enrs`], which skips an unusable record with a warning rather than -/// failing startup, and warns again if that leaves the list empty. +/// Reads `node`'s `--bootnodes` file and a loaded network directory's +/// `bootstrap_nodes.yaml`/`.txt` (`network::dir`); each result goes to +/// [`parse_enrs`], which skips an unusable record with a warning rather than +/// failing startup, and warns again if that leaves the list empty. `beacon`'s +/// own `--bootnodes` is a list, not a file, and never comes through here. /// /// YAML first, then a line-oriented fallback. The two sub-commands arrived /// with different readers: `node` required a strict YAML sequence, `beacon` @@ -3651,25 +3749,173 @@ validators: #[test] fn an_unreadable_bootnode_file_is_an_error_but_an_absent_one_is_not() { - // The flag is optional on both chains, so no flag is not an error; - // what an absent list *means* is each chain's own decision, made in - // `default_bootnodes`. A path that was supplied and cannot be read is - // still a hard failure: the operator named a file, so a typo must not - // look like "no peers". - let absent: Option<&Path> = None; + // The flag is optional on `node`, so no flag is not an error, just no + // bootnodes (warned about in `lean_bootnodes`). A path that was + // supplied and cannot be read is still a hard failure: the operator + // named a file, so a typo must not look like "no peers". assert!( - absent - .map(read_bootnode_strings) - .transpose() + lean_bootnodes(None) .expect("no flag is not an error") - .is_none() + .is_empty() ); let missing = std::env::temp_dir().join("ethlambda-test-enrs-does-not-exist.yaml"); assert!(read_bootnode_strings(&missing).is_err()); + assert!(lean_bootnodes(Some(&missing)).is_err()); + } + + /// A real ENR (`ethlambda-p2p`'s `parse_enrs_extracts_ip_port_and_public_key` + /// record: localhost, `quic` 9001), standing in for one typed on the + /// command line. + const LOCALHOST_ENR: &str = "enr:-IW4QGGifTt9ypyMtChDISUNX3z4z5iPdiEPOmBoILvnDuWIKbWVmKXxZERPnw0piQyaBNCENFEPoIi-vxsnsrBig9MBgmlkgnY0gmlwhH8AAAGEcXVpY4IjKYlzZWNwMjU2azGhAhMMnGF1rmIPQ9tWgqfkNmvsG-aIyc9EJU5JFo3Tegys"; + + fn peer_ids(bootnodes: &[Bootnode]) -> Vec { + bootnodes.iter().map(Bootnode::peer_id).collect() } - /// The two chains read the same absent flag in opposite directions, so an - /// arm that starts answering like the other one is a silent peering change: + /// A secp256k1 peer id from a fixed secret, so a test can write a + /// multiaddr bootnode and recognize it in the result. + fn seeded_peer_id(seed: u8) -> PeerId { + let keys = HashMap::from([(String::new(), H256([seed; 32]))]); + ethlambda_p2p::derive_peer_ids(keys) + .into_keys() + .next() + .expect("a valid secp256k1 secret") + } + + /// Why `beacon_bootnodes` refuses `cli_entries`, panicking if it accepts + /// them. + fn beacon_bootnodes_refusal(cli_entries: &[&str]) -> String { + let entries: Vec = cli_entries.iter().map(|entry| entry.to_string()).collect(); + let err = beacon_bootnodes(&entries, Vec::new()).expect_err("the entries must be refused"); + format!("{err:#}") + } + + /// Additive, as Lighthouse's `--boot-nodes` is: the command line's entries + /// come first, in the order given, and the network's whole list follows. + #[test] + fn beacon_bootnodes_puts_the_command_line_first_and_keeps_the_network_list() { + let tcp_peer = seeded_peer_id(1); + let udp_peer = seeded_peer_id(2); + let cli_entries = [ + format!("/ip4/203.0.113.7/tcp/9000/p2p/{tcp_peer}"), + LOCALHOST_ENR.to_string(), + format!("/ip4/203.0.113.8/udp/9000/p2p/{udp_peer}"), + ]; + let network_entries = network::NetworkSource::built_in_mainnet() + .unwrap() + .bootnodes(); + let network_peers = peer_ids(&parse_enrs(network_entries.clone())); + assert!(!network_peers.is_empty()); + + let bootnodes = + beacon_bootnodes(&cli_entries, network_entries).expect("every entry is valid"); + + let enr_peer = parse_bootnode(LOCALHOST_ENR).unwrap().peer_id(); + let mut expected = vec![tcp_peer, enr_peer, udp_peer]; + expected.extend(network_peers); + assert_eq!(peer_ids(&bootnodes), expected); + } + + /// `--bootnodes ""` and a trailing comma reach `beacon_bootnodes` as empty + /// entries, and a list split on commas may leave spaces around each one. + #[test] + fn beacon_bootnodes_skips_empty_and_blank_entries() { + let peer = seeded_peer_id(3); + let cli_entries = [ + String::new(), + " ".to_string(), + format!(" /ip4/203.0.113.7/tcp/9000/p2p/{peer} "), + String::new(), + ]; + + let bootnodes = + beacon_bootnodes(&cli_entries, Vec::new()).expect("blank entries are skipped"); + + assert_eq!(peer_ids(&bootnodes), [peer]); + } + + /// A typed entry that does not parse fails startup, naming the entry and + /// the parser's reason, even when the entries around it are fine. + #[test] + fn a_malformed_beacon_bootnode_is_a_startup_error_naming_it() { + let peer = seeded_peer_id(4); + let valid = format!("/ip4/203.0.113.7/tcp/9000/p2p/{peer}"); + for (entry, reason) in [ + ("1.2.3.4:9000", "neither a multiaddr"), + ("/ip4/1.2.3.4/tcp/9000", "missing /p2p"), + ("enr:not-a-record", "invalid ENR"), + ] { + let refusal = beacon_bootnodes_refusal(&[&valid, entry]); + assert!(refusal.contains(&format!("\"{entry}\"")), "{refusal}"); + assert!(refusal.contains(reason), "{refusal}"); + assert!(!refusal.contains("not a file"), "{refusal}"); + } + } + + /// `allow_hyphen_values` lets a value-less `--bootnodes` (an unset variable + /// in a launch script) take the next flag as its value. The error must name + /// the missing value, not report the flag as a malformed ENR. + #[test] + fn a_bootnode_flag_with_no_value_is_refused_as_such() { + let refusal = beacon_bootnodes_refusal(&["--builder-follow-redirects"]); + assert!(refusal.contains("was given no value"), "{refusal}"); + assert!(refusal.contains("--builder-follow-redirects"), "{refusal}"); + } + + /// `beacon --bootnodes` used to name a file, and launchers still pass one + /// (kurtosis: `--bootnodes=/tmp/ethlambda-bootnodes.txt`). That fails as a + /// multiaddr, but the error has to say why the flag changed rather than + /// report a multiaddr syntax error. + #[test] + fn a_bootnode_file_on_beacon_is_refused_with_a_hint() { + let file = tempfile::NamedTempFile::new().expect("temp file"); + std::fs::write(file.path(), format!("- {LOCALHOST_ENR}\n")).expect("writes"); + let path = file.path().to_str().expect("utf-8 temp path"); + + let refusal = beacon_bootnodes_refusal(&[path]); + + assert!(refusal.contains(path), "{refusal}"); + assert!( + refusal.contains("now takes a comma-separated list of ENRs and multiaddrs, not a file"), + "{refusal}" + ); + assert!(refusal.contains("joined with commas"), "{refusal}"); + // The file above is a YAML list; joining its lines as they are would + // keep the markers and fail again, as an ENR. + assert!(refusal.contains("\"- \" markers"), "{refusal}"); + } + + /// A launcher whose bootnode file is missing (a typo, or a file it stopped + /// writing) passes a path that is not a file at all. Its extension still + /// earns the hint, rather than an ENR or multiaddr decoding error. + #[test] + fn a_missing_bootnode_file_on_beacon_gets_the_same_hint() { + for path in ["/no/such/dir/bootnodes.yaml", "bootnodes.txt"] { + let refusal = beacon_bootnodes_refusal(&[path]); + assert!(refusal.contains(path), "{refusal}"); + assert!(refusal.contains("not a file"), "{refusal}"); + } + } + + /// The network's own list keeps `parse_enrs`' rule: a bad entry there is + /// skipped with a warning, since the operator did not type it. + #[test] + fn a_bad_network_bootnode_is_skipped_not_refused() { + let good = network::NetworkSource::built_in_mainnet() + .unwrap() + .bootnodes() + .remove(0); + let good_peer = parse_bootnode(&good).unwrap().peer_id(); + let network_entries = vec!["enr:not-a-record".to_string(), good]; + + let bootnodes = + beacon_bootnodes(&[], network_entries).expect("a bad network entry is not an error"); + + assert_eq!(peer_ids(&bootnodes), [good_peer]); + } + + /// The two chains read an absent flag in opposite directions, so an arm + /// that starts answering like the other one is a silent peering change: /// mainnet with no seeds cannot bootstrap, and a lean node handed mainnet's /// ENRs dials peers that will reject it. #[test] @@ -3691,13 +3937,21 @@ validators: let Command::Node(node) = try_parse_from(argv).expect("`node` parses") else { panic!("`node` must resolve to the node sub-command"); }; - assert!(matches!(Options::from(node).network, Network::Lean(_))); - assert!(default_bootnodes(None).is_empty()); + let Network::Lean(lean) = Options::from(node).network else { + panic!("`node` must carry the lean network"); + }; + assert!( + lean_bootnodes(lean.bootnodes.as_deref()) + .unwrap() + .is_empty() + ); - let mainnet_source = network::NetworkSource::built_in_mainnet().unwrap(); - let fallback = default_bootnodes(Some(&mainnet_source)); + let network_entries = network::NetworkSource::built_in_mainnet() + .unwrap() + .bootnodes(); + let fallback = beacon_bootnodes(&[], network_entries.clone()).unwrap(); assert!(!fallback.is_empty()); - assert_eq!(fallback, mainnet_source.bootnodes()); + assert_eq!(peer_ids(&fallback), peer_ids(&parse_enrs(network_entries))); } } diff --git a/bin/ethlambda/src/network/dir.rs b/bin/ethlambda/src/network/dir.rs index 05a4d0243..110ad309b 100644 --- a/bin/ethlambda/src/network/dir.rs +++ b/bin/ethlambda/src/network/dir.rs @@ -142,9 +142,10 @@ impl NetworkDir { /// Read the first bootnode file present, preferring the YAML spelling. /// /// Both spellings appear: `eth-clients` publishes `bootstrap_nodes.yaml` and -/// kurtosis ships that plus `bootstrap_nodes.txt`. The existing `--bootnodes` -/// parser (`read_bootnode_strings`, in `main.rs`) already accepts either -/// shape, so this only picks a file and reuses it rather than re-parsing. +/// kurtosis ships that plus `bootstrap_nodes.txt`. The reader for `node`'s +/// `--bootnodes` file (`read_bootnode_strings`, in `main.rs`) already accepts +/// either shape, so this only picks a file and reuses it rather than +/// re-parsing. fn read_bootnodes(base: &Path) -> Result, NetworkDirError> { for name in [BOOTNODES_YAML, BOOTNODES_TXT] { let path = base.join(name); diff --git a/bin/ethlambda/src/network/mod.rs b/bin/ethlambda/src/network/mod.rs index 8ff79eaf9..e235470cf 100644 --- a/bin/ethlambda/src/network/mod.rs +++ b/bin/ethlambda/src/network/mod.rs @@ -336,7 +336,8 @@ impl NetworkSource { } } - /// The bootnodes this network ships, before `--bootnodes` overrides them. + /// The bootnodes this network ships, which `beacon`'s `--bootnodes` + /// entries are added to (never replace). pub(crate) fn bootnodes(&self) -> Vec { match self { Self::BuiltIn(built_in) => built_in.bootnodes.clone(), diff --git a/crates/net/p2p/src/lib.rs b/crates/net/p2p/src/lib.rs index 83e22d945..a431d6743 100644 --- a/crates/net/p2p/src/lib.rs +++ b/crates/net/p2p/src/lib.rs @@ -2413,24 +2413,27 @@ pub fn derive_peer_ids(names_and_privkeys: HashMap) -> HashMap/quic-v1` multiaddr. /// /// `None` for a record that does not advertise one. See /// [`Bootnode::tcp_port`] for the other transport that can still make such /// a record dialable: every beacon-chain bootnode published today is /// exactly that case, `tcp` and `udp` but no `quic`. pub(crate) quic_port: Option, - /// The libp2p TCP port, when the ENR advertises one. + /// The libp2p TCP port, when the ENR advertises one or the bootnode is a + /// `/tcp/` multiaddr. /// /// `None` for the ENRs lean-quickstart generates today, which carry only /// `ip`/`quic`/`secp256k1`. Every published mainnet beacon-chain bootnode /// carries this instead of `quic`, which is what makes them statically /// dialable now that the swarm speaks both transports. pub(crate) tcp_port: Option, - /// The discv5 UDP port, when the ENR advertises one. + /// The discv5 UDP port, when the ENR advertises one or the bootnode is a + /// bare `/udp/` multiaddr. /// /// `None` for the ENRs lean-quickstart generates today, which carry only /// `ip`/`quic`/`secp256k1`. Such a bootnode is still dialed statically over @@ -2440,12 +2443,17 @@ pub struct Bootnode { } impl Bootnode { - /// This bootnode as a discv5 seed, or `None` when its ENR advertises no - /// `udp` port and it therefore cannot be reached by discovery. + /// The peer id this bootnode is dialed and merged under. + pub fn peer_id(&self) -> PeerId { + PeerId::from_public_key(&self.public_key) + } + + /// This bootnode as a discv5 seed, or `None` when it has no `udp` port (or + /// a key discv5 cannot use) and therefore cannot be reached by discovery. /// - /// `tcp_port` carries this bootnode's real advertised TCP port when it has - /// one, now that ethlambda dials TCP too; it is `0` only when the ENR - /// advertises none, which ethrex reads as "no TCP listener". + /// `tcp_port` carries this bootnode's real TCP port when it has one, now + /// that ethlambda dials TCP too; it is `0` only when the bootnode has none, + /// which ethrex reads as "no TCP listener". pub(crate) fn as_discovery_node(&self) -> Option { let udp_port = self.udp_port?; // libp2p and ethrex hold the same key in different representations: @@ -2488,14 +2496,13 @@ pub fn parse_enrs(enrs: Vec) -> Vec { .ok() }) .collect(); - // Each rejection above already warned, but a file where *every* entry is - // unusable boots a node with an empty bootnode list, which otherwise looks - // identical to having configured none at all. + // Each rejection above already warned, but a list where *every* entry is + // unusable contributes nothing, which otherwise looks identical to having + // configured none at all. Worded for the list, not the node: `beacon` adds + // its own `--bootnodes` entries to this one, so an empty result here need + // not leave the node with no bootnodes. if bootnodes.is_empty() && configured > 0 { - warn!( - configured, - "No bootnode ENR could be used; the node starts with no bootnodes" - ); + warn!(configured, "No bootnode ENR in this list could be used"); } bootnodes } @@ -2544,6 +2551,181 @@ fn parse_enr(enr_str: &str) -> Result { }) } +/// Read one `--bootnodes` entry: an ENR, with or without its `enr:` prefix, or +/// a libp2p multiaddr, the two forms Lighthouse's `--boot-nodes` takes. ENRs +/// are URL-safe base64 and never contain `/`, so a leading `/` is what tells +/// the two apart. +/// +/// A multiaddr names one transport, so it sets one port: `/tcp/` is a +/// TCP dial target, `/udp//quic-v1` a QUIC one, and a bare `/udp/` +/// a discv5 contact, which is how Lighthouse reads a UDP multiaddr. Lighthouse +/// asks that contact for its ENR before using it; here the key in the peer id +/// is all discv5 needs, so it is seeded directly, with no round trip. +/// +/// Two departures from Lighthouse, both deliberate: +/// - `/p2p/` is required. Lighthouse dials a TCP multiaddr without one +/// anonymously, but a bootnode here is keyed by its peer id (merging its dial +/// addresses, skipping our own entry, redialing it) and seeds discv5 with the +/// key the id embeds, so an anonymous entry has no place to go. +/// - QUIC multiaddrs are dialed. Lighthouse's multiaddr bootnodes dial TCP only; +/// this node prefers QUIC wherever a peer offers it. +/// +/// `/dns*` is refused: a [`Bootnode`] holds an address, and the swarm has no +/// DNS transport to resolve a name with. So is an IPv6 entry, of either form, +/// that is only a discv5 contact, since discovery listens on IPv4. Unlike +/// [`parse_enrs`], a bad entry is an error rather than a warning, since an +/// operator typed it on the command line. +pub fn parse_bootnode(entry: &str) -> Result { + let entry = entry.trim(); + if entry.is_empty() { + return Err("empty bootnode entry".to_string()); + } + let bootnode = if entry.starts_with('/') { + parse_bootnode_multiaddr(entry)? + } else if entry.starts_with("enr:") { + parse_enr(entry).map_err(|reason| format!("invalid ENR: {reason}"))? + } else { + // Without the prefix the entry could equally be a mistyped address + // (say `1.2.3.4:9000`), so say both readings failed rather than report + // a bare RLP error for an entry that was never meant as an ENR. + parse_enr(&format!("enr:{entry}")).map_err(|reason| { + format!("neither a multiaddr (those start with /) nor a valid ENR: {reason}") + })? + }; + + // A discv5 contact and nothing else, at an IPv6 address, could never be + // reached: discovery listens on the IPv4 wildcard (`run_node` binds + // `0.0.0.0`), and an IPv4 socket cannot send to an IPv6 address. Refused + // for the reason a non-secp256k1 discv5 contact is (see + // `parse_bootnode_multiaddr`): nothing could use it. An IPv6 entry with a + // QUIC or TCP port is kept, since the swarm dials it, not the discovery + // socket. + if bootnode.ip.is_ipv6() && bootnode.quic_port.is_none() && bootnode.tcp_port.is_none() { + return Err( + "an IPv6 bootnode with only a discv5 (udp) port cannot be reached: discovery \ + listens on IPv4 only, so give its IPv4 address" + .to_string(), + ); + } + Ok(bootnode) +} + +/// The multiaddr half of [`parse_bootnode`], walked component by component so +/// that anything after the one transport and the peer id is refused rather +/// than ignored. +fn parse_bootnode_multiaddr(entry: &str) -> Result { + const EXPECTED_TRANSPORT: &str = "expected /tcp/, /udp//quic-v1 or /udp/"; + + enum Transport { + Quic, + Tcp, + Discv5, + } + + let addr: Multiaddr = entry + .parse() + .map_err(|err| format!("invalid multiaddr: {err}"))?; + let mut components = addr.iter().peekable(); + + let ip = match components.next() { + Some(Protocol::Ip4(ip)) => IpAddr::V4(ip), + Some(Protocol::Ip6(ip)) => IpAddr::V6(ip), + Some(Protocol::Dns(_) | Protocol::Dns4(_) | Protocol::Dns6(_) | Protocol::Dnsaddr(_)) => { + return Err("DNS multiaddrs are not supported, use /ip4 or /ip6".to_string()); + } + Some(other) => { + return Err(format!( + "multiaddr must start with /ip4 or /ip6, not {other}" + )); + } + None => return Err("empty multiaddr".to_string()), + }; + + let (transport, port) = match components.next() { + Some(Protocol::Tcp(port)) => (Transport::Tcp, port), + Some(Protocol::Udp(port)) => match components.peek() { + Some(Protocol::QuicV1) => { + components.next(); + (Transport::Quic, port) + } + Some(Protocol::Quic) => { + return Err("draft-29 QUIC (/quic) is not spoken, use /quic-v1".to_string()); + } + _ => (Transport::Discv5, port), + }, + Some(Protocol::P2p(_)) | None => { + return Err(format!( + "multiaddr names no transport; {EXPECTED_TRANSPORT}" + )); + } + Some(other) => { + return Err(format!( + "unsupported transport {other}; {EXPECTED_TRANSPORT}" + )); + } + }; + let port = dialable_port(port).ok_or_else(|| "port 0 is not dialable".to_string())?; + + let peer_id = match components.next() { + Some(Protocol::P2p(peer_id)) => peer_id, + Some(other) => { + return Err(format!( + "unsupported {other} after the transport; expected /p2p/" + )); + } + None => { + return Err( + "missing /p2p/: a bootnode is keyed by its peer id and \ + seeds discv5 with the public key in it, so an address without one is refused" + .to_string(), + ); + } + }; + if let Some(extra) = components.next() { + return Err(format!("unexpected {extra} after /p2p/")); + } + + let mut bootnode = Bootnode { + ip, + quic_port: None, + tcp_port: None, + udp_port: None, + public_key: embedded_public_key(&peer_id)?, + }; + match transport { + Transport::Quic => bootnode.quic_port = Some(port), + Transport::Tcp => bootnode.tcp_port = Some(port), + Transport::Discv5 => bootnode.udp_port = Some(port), + } + + // A bare UDP address is only a discv5 contact, and discv5 takes secp256k1 + // keys alone: with any other key nothing could use the entry, and + // `parse_enr` likewise drops a record nothing can use. + if bootnode.udp_port.is_some() && bootnode.as_discovery_node().is_none() { + return Err( + "a /udp/ bootnode is a discv5 contact and needs a secp256k1 peer id".to_string(), + ); + } + Ok(bootnode) +} + +/// The public key a peer id carries inline. +/// +/// libp2p inlines a key of up to 42 encoded bytes (secp256k1, ed25519) under +/// the identity multihash and hashes a longer one (RSA) with sha256, which +/// keeps no key to read back. +fn embedded_public_key(peer_id: &PeerId) -> Result { + const IDENTITY_MULTIHASH_CODE: u64 = 0; + let multihash: &libp2p::multihash::Multihash<64> = peer_id.as_ref(); + if multihash.code() != IDENTITY_MULTIHASH_CODE { + return Err( + "peer id does not embed its public key (it is a hash, as for an RSA key)".to_string(), + ); + } + PublicKey::try_decode_protobuf(multihash.digest()) + .map_err(|err| format!("peer id embeds no decodable public key: {err}")) +} + // --- Utility functions --- /// Every address worth trying for one peer, from whichever of its two ports are @@ -2601,7 +2783,7 @@ fn merge_bootnode_dial_addrs( let mut merged: HashMap> = HashMap::new(); let mut undialable = 0usize; for bootnode in bootnodes { - let peer_id = PeerId::from_public_key(&bootnode.public_key); + let peer_id = bootnode.peer_id(); if peer_id == local_peer_id { continue; } @@ -4397,6 +4579,249 @@ mod tests { assert_eq!(bootnodes[0].quic_port, Some(9001)); } + /// A secp256k1 peer id, the kind every lean and beacon node runs with. + fn secp256k1_peer_id() -> PeerId { + PeerId::from_public_key(&Keypair::generate_secp256k1().public()) + } + + /// The reason `parse_bootnode` refuses `entry`, panicking if it accepts it. + fn bootnode_refusal(entry: &str) -> String { + parse_bootnode(entry).expect_err("the entry must be refused") + } + + #[test] + fn parse_bootnode_reads_an_enr_with_or_without_its_prefix() { + // Reused from `parse_enrs_extracts_ip_port_and_public_key`. + let enr = "enr:-IW4QGGifTt9ypyMtChDISUNX3z4z5iPdiEPOmBoILvnDuWIKbWVmKXxZERPnw0piQyaBNCENFEPoIi-vxsnsrBig9MBgmlkgnY0gmlwhH8AAAGEcXVpY4IjKYlzZWNwMjU2azGhAhMMnGF1rmIPQ9tWgqfkNmvsG-aIyc9EJU5JFo3Tegys"; + + let prefixed = parse_bootnode(enr).unwrap(); + assert_eq!(prefixed.ip, IpAddr::from(Ipv4Addr::LOCALHOST)); + assert_eq!(prefixed.quic_port, Some(9001)); + + let bare = parse_bootnode(enr.strip_prefix("enr:").unwrap()).unwrap(); + assert_eq!(bare.ip, prefixed.ip); + assert_eq!(bare.quic_port, prefixed.quic_port); + assert_eq!(bare.tcp_port, prefixed.tcp_port); + assert_eq!(bare.udp_port, prefixed.udp_port); + assert_eq!(bare.public_key, prefixed.public_key); + } + + #[test] + fn parse_bootnode_reads_a_tcp_multiaddr_as_a_tcp_dial_target() { + let peer_id = secp256k1_peer_id(); + // Surrounding whitespace, as a comma-separated list leaves it, is trimmed. + let entry = format!(" /ip4/1.2.3.4/tcp/9000/p2p/{peer_id} "); + + let bootnode = parse_bootnode(&entry).unwrap(); + + assert_eq!(bootnode.ip, IpAddr::from(Ipv4Addr::new(1, 2, 3, 4))); + assert_eq!(bootnode.tcp_port, Some(9000)); + assert_eq!(bootnode.quic_port, None); + assert_eq!(bootnode.udp_port, None); + } + + #[test] + fn parse_bootnode_reads_a_quic_v1_multiaddr_as_a_quic_dial_target() { + let peer_id = secp256k1_peer_id(); + let entry = format!("/ip4/1.2.3.4/udp/9001/quic-v1/p2p/{peer_id}"); + + let bootnode = parse_bootnode(&entry).unwrap(); + + assert_eq!(bootnode.quic_port, Some(9001)); + assert_eq!(bootnode.tcp_port, None); + assert_eq!(bootnode.udp_port, None); + } + + #[test] + fn parse_bootnode_reads_a_bare_udp_multiaddr_as_a_discv5_seed() { + let peer_id = secp256k1_peer_id(); + let entry = format!("/ip4/1.2.3.4/udp/9000/p2p/{peer_id}"); + + let bootnode = parse_bootnode(&entry).unwrap(); + + assert_eq!(bootnode.udp_port, Some(9000)); + assert_eq!(bootnode.quic_port, None); + assert_eq!(bootnode.tcp_port, None); + let node = bootnode + .as_discovery_node() + .expect("a secp256k1 UDP bootnode must seed discv5"); + assert_eq!(node.udp_port, 9000); + } + + #[test] + fn parse_bootnode_reads_an_ip6_multiaddr() { + let peer_id = secp256k1_peer_id(); + let entry = format!("/ip6/2001:db8::1/tcp/9000/p2p/{peer_id}"); + + let bootnode = parse_bootnode(&entry).unwrap(); + + assert_eq!(bootnode.ip, "2001:db8::1".parse::().unwrap()); + assert_eq!(bootnode.tcp_port, Some(9000)); + } + + /// The swarm dials an IPv6 address, but discovery listens on IPv4 only, so + /// an IPv6 entry that is only a discv5 contact could never be reached. + #[test] + fn parse_bootnode_refuses_an_ip6_discv5_contact() { + let peer_id = secp256k1_peer_id(); + + let quic = parse_bootnode(&format!("/ip6/2001:db8::1/udp/9001/quic-v1/p2p/{peer_id}")) + .expect("an IPv6 QUIC entry is dialed by the swarm"); + assert_eq!(quic.quic_port, Some(9001)); + + let reason = bootnode_refusal(&format!("/ip6/2001:db8::1/udp/9000/p2p/{peer_id}")); + assert!(reason.contains("IPv6"), "{reason}"); + assert!(reason.contains("IPv4"), "{reason}"); + } + + #[test] + fn parse_bootnode_takes_the_public_key_from_the_peer_id() { + let peer_id = secp256k1_peer_id(); + let entry = format!("/ip4/1.2.3.4/tcp/9000/p2p/{peer_id}"); + + let bootnode = parse_bootnode(&entry).unwrap(); + + assert_eq!(PeerId::from_public_key(&bootnode.public_key), peer_id); + } + + /// `beacon` adds its `--bootnodes` entries to the network's ENR list and + /// leaves duplicates to this merge, so a multiaddr typed for a peer the + /// network also lists must land in that peer's one dial: the two parse paths + /// have to key the peer alike. + #[test] + fn a_multiaddr_and_an_enr_for_one_peer_merge_into_one_dial() { + // Reused from `parse_enrs_extracts_ip_port_and_public_key`: localhost, + // `quic` 9001, no `tcp`. + let enr = parse_bootnode("enr:-IW4QGGifTt9ypyMtChDISUNX3z4z5iPdiEPOmBoILvnDuWIKbWVmKXxZERPnw0piQyaBNCENFEPoIi-vxsnsrBig9MBgmlkgnY0gmlwhH8AAAGEcXVpY4IjKYlzZWNwMjU2azGhAhMMnGF1rmIPQ9tWgqfkNmvsG-aIyc9EJU5JFo3Tegys").unwrap(); + let peer_id = enr.peer_id(); + let typed = parse_bootnode(&format!("/ip4/203.0.113.7/tcp/9000/p2p/{peer_id}")).unwrap(); + assert_eq!(typed.peer_id(), peer_id); + + let (merged, undialable) = merge_bootnode_dial_addrs(vec![typed, enr], random_peer()); + + assert_eq!(undialable, 0); + assert_eq!(merged.len(), 1, "the two entries name one peer"); + let addrs = merged + .get(&peer_id) + .expect("the peer is keyed by its peer id"); + let expected: HashSet = HashSet::from([ + tcp_multiaddr(IpAddr::from(Ipv4Addr::new(203, 0, 113, 7)), 9000, peer_id), + quic_multiaddr(IpAddr::from(Ipv4Addr::LOCALHOST), 9001, peer_id), + ]); + assert_eq!(addrs.iter().cloned().collect::>(), expected); + } + + #[test] + fn parse_bootnode_refuses_a_multiaddr_without_a_peer_id() { + for entry in [ + "/ip4/1.2.3.4/tcp/9000", + "/ip4/1.2.3.4/udp/9001/quic-v1", + "/ip4/1.2.3.4/udp/9000", + ] { + let reason = bootnode_refusal(entry); + assert!(reason.contains("missing /p2p"), "{entry}: {reason}"); + } + } + + #[test] + fn parse_bootnode_refuses_a_dns_multiaddr() { + let peer_id = secp256k1_peer_id(); + let reason = bootnode_refusal(&format!("/dns4/boot.example.com/tcp/9000/p2p/{peer_id}")); + assert!(reason.contains("DNS"), "{reason}"); + } + + #[test] + fn parse_bootnode_refuses_draft_quic() { + let peer_id = secp256k1_peer_id(); + let reason = bootnode_refusal(&format!("/ip4/1.2.3.4/udp/9001/quic/p2p/{peer_id}")); + assert!(reason.contains("quic-v1"), "{reason}"); + } + + #[test] + fn parse_bootnode_refuses_port_zero() { + let peer_id = secp256k1_peer_id(); + for entry in [ + format!("/ip4/1.2.3.4/tcp/0/p2p/{peer_id}"), + format!("/ip4/1.2.3.4/udp/0/quic-v1/p2p/{peer_id}"), + format!("/ip4/1.2.3.4/udp/0/p2p/{peer_id}"), + ] { + let reason = bootnode_refusal(&entry); + assert!(reason.contains("port 0"), "{entry}: {reason}"); + } + } + + #[test] + fn parse_bootnode_refuses_transports_it_does_not_speak() { + let peer_id = secp256k1_peer_id(); + for (entry, expected) in [ + ( + format!("/ip4/1.2.3.4/tcp/9000/ws/p2p/{peer_id}"), + "unsupported /ws", + ), + ( + format!("/ip4/1.2.3.4/tcp/9000/wss/p2p/{peer_id}"), + "unsupported /wss", + ), + ( + format!("/ip4/1.2.3.4/udp/9001/quic-v1/webtransport/p2p/{peer_id}"), + "unsupported /webtransport", + ), + ( + format!("/ip4/1.2.3.4/tcp/9000/p2p/{peer_id}/p2p-circuit"), + "unexpected /p2p-circuit", + ), + ( + format!("/ip4/1.2.3.4/tcp/9000/tcp/9001/p2p/{peer_id}"), + "unsupported /tcp", + ), + (format!("/ip4/1.2.3.4/p2p/{peer_id}"), "names no transport"), + ( + format!("/ip4/1.2.3.4/sctp/9000/p2p/{peer_id}"), + "unsupported transport", + ), + ] { + let reason = bootnode_refusal(&entry); + assert!(reason.contains(expected), "{entry}: {reason}"); + } + } + + #[test] + fn parse_bootnode_refuses_garbage_an_empty_entry_and_a_malformed_enr() { + assert!(bootnode_refusal("").contains("empty")); + assert!(bootnode_refusal(" ").contains("empty")); + assert!(bootnode_refusal("1.2.3.4:9000").contains("neither a multiaddr")); + assert!(bootnode_refusal("enr:not valid base64!!!").contains("invalid ENR")); + assert!(bootnode_refusal("/not/a/multiaddr").contains("invalid multiaddr")); + } + + #[test] + fn parse_bootnode_refuses_a_peer_id_that_hashes_its_key() { + // An RSA key is too long to inline, so its peer id is a sha256 digest + // and there is no key to read back. Any digest stands in for one here. + const SHA2_256_MULTIHASH_CODE: u64 = 0x12; + let digest = + libp2p::multihash::Multihash::<64>::wrap(SHA2_256_MULTIHASH_CODE, &[7; 32]).unwrap(); + let peer_id = PeerId::from_multihash(digest).unwrap(); + + let reason = bootnode_refusal(&format!("/ip4/1.2.3.4/tcp/9000/p2p/{peer_id}")); + + assert!(reason.contains("does not embed its public key"), "{reason}"); + } + + #[test] + fn parse_bootnode_refuses_a_bare_udp_multiaddr_with_a_key_discv5_cannot_use() { + let peer_id = PeerId::from_public_key(&Keypair::generate_ed25519().public()); + + // Dialable transports take any key libp2p can authenticate. + let tcp = parse_bootnode(&format!("/ip4/1.2.3.4/tcp/9000/p2p/{peer_id}")).unwrap(); + assert_eq!(tcp.tcp_port, Some(9000)); + + // A discv5 contact cannot: discv5 speaks secp256k1 only, so nothing + // could use this entry at all. + let reason = bootnode_refusal(&format!("/ip4/1.2.3.4/udp/9000/p2p/{peer_id}")); + assert!(reason.contains("secp256k1"), "{reason}"); + } + /// A connection the limits refuse must leave no trace in any /// request/response field. /// diff --git a/docs/beacon_wire.md b/docs/beacon_wire.md index e88914c25..e6b5565be 100644 --- a/docs/beacon_wire.md +++ b/docs/beacon_wire.md @@ -985,7 +985,9 @@ sync committee messages, blocks with their columns, operations), plus relayed validated gossip. `seeds=17` proves the built-in list parsed; a lower number means a bootnode -ENR was skipped with a warning. `topics=17` proves the subscription set: the 7 +ENR was skipped with a warning. That holds for a run without `--bootnodes`, +whose entries are counted on top (in `seeds` only when they carry a discv5 +port). `topics=17` proves the subscription set: the 7 global topics, the 8 column subnets this run's (randomly generated) node id selected, and the 2 attestation subnets the same id selected; `columns=8` and `attestation_subnets=[…]` confirm the two families directly. diff --git a/docs/checkpoint_sync.md b/docs/checkpoint_sync.md index 53569364e..d6673683e 100644 --- a/docs/checkpoint_sync.md +++ b/docs/checkpoint_sync.md @@ -32,7 +32,7 @@ State already on disk takes precedence over both checkpoint sync and genesis: if ### `ethlambda beacon` -`beacon` takes no genesis config, validator registry, or bootnode file of its own: it takes `--network` instead, naming a built-in network or a directory of published network files (see [`cli.md`](cli.md)). `genesis_time`, `genesis_validators_root`, and the bootnode list all come from whichever network `--network` resolves to; for the built-in networks (`mainnet`, the default, plus `sepolia`, `hoodi` and `plataberget`), they are built into the binary (see `CLAUDE.md`'s "Built-in networks"). +`beacon` takes no genesis config, validator registry, or bootnode file of its own: it takes `--network` instead, naming a built-in network or a directory of published network files (see [`cli.md`](cli.md)). `genesis_time`, `genesis_validators_root`, and the bootnode list all come from whichever network `--network` resolves to, plus, for the bootnode list, any entries `--bootnodes` adds to it (a list of ENRs and multiaddrs, not a file; see [`cli.md`](cli.md#bootnodes-on-beacon)). For the built-in networks (`mainnet`, the default, plus `sepolia`, `hoodi` and `plataberget`), the network's own values are built into the binary (see `CLAUDE.md`'s "Built-in networks"). ```bash ethlambda beacon --network --checkpoint-sync-url diff --git a/docs/cli.md b/docs/cli.md index 320dd1ad0..3bce748b9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -62,22 +62,25 @@ one `CommonOptions` struct flattened into each. | `--api-port` | `5052` | API server port. `beacon` binds it too, off its own anchored store rather than an empty one; the lean-shaped `/lean/v0` routes still don't answer for it (see [`beacon` flags](#beacon-flags) below) | | `--metrics-port` | `5054` | Metrics and debug server port. Equal to `--api-port` merges the routers onto one listener | | `--node-key` | `/node.key` | Hex file holding the secp256k1 key that is this node's libp2p and discv5 identity. When omitted, the key stored in `--data-dir` as `node.key` is used, generated and stored there (mode `0600`) on the directory's first start, so the PeerId and ENR stay the same across restarts until the directory is wiped | -| `--bootnodes` | see below | Bootnode ENR list: one `enr:...` per line, as a YAML block sequence, a YAML flow sequence, or a plain list (`#` comments and leading `- ` are both tolerated) | | `--checkpoint-sync-url` | see below | API base URLs, tried in order until one answers. Supplies `node`'s starting state on the lean API, and `beacon`'s anchor on a standard Beacon API; required on a fresh `beacon` data directory only for a built-in network, since a loaded network anchors at its own `genesis.ssz` instead. See [`checkpoint_sync.md`](checkpoint_sync.md) | | `--discovery.port` | `9000` | discv5 UDP port; must differ from `--gossipsub-port`. See [Peer discovery](./discovery.md) | | `--discovery.advertise-ip` | bind address | IP published in the ENR | | `--discovery.target-peers` | `200` | Connected-peer count above which discovery stops dialing | -Three of those have no clap default, because the two chains answer them +Two of those have no clap default, because the two chains answer them differently. A single `default_value` can only say one thing, so the flag carries none and each chain resolves an absent value itself: | Flag | Absent on `node` | Absent on `beacon` | |---|---|---| | `--node-key` | `/node.key`, generated on the directory's first start | same | -| `--bootnodes` | no bootnodes: peers only via discv5 (with `--discovery.enable`) or by being dialed, warned about | falls back to the resolved network's own bootnode list: a built-in network's embedded list, or a loaded directory's `bootstrap_nodes.yaml`/`.txt` | | `--checkpoint-sync-url` | start from a resumable DB, else from genesis | start from a resumable DB, else anchor at the resolved network's own genesis (loaded network only), else abort | +`--bootnodes` is taken by both too, but not with one meaning, so it is listed +under each sub-command instead: on `node` it names a file of ENRs, and on +`beacon` it is a list of ENRs and multiaddrs added to the network's own +bootnodes. + Whether discv5 runs is not a common flag. `beacon` always runs it, since published mainnet bootnode ENRs carry no `quic` entry and so are not statically dialable; `node` runs it only with `--discovery.enable` (see below). Where it @@ -100,6 +103,7 @@ On top of the common flags above. | `--hash-sig-keys-dir` | required | Directory of per-validator XMSS keys | | `--node-id` | required | The key in `annotated_validators.yaml` naming this node, e.g. `ethlambda_0` | | `--is-aggregator` | `false` | Seed the runtime aggregator flag | +| `--bootnodes` | none, warned about | Path to a bootnode ENR file: one `enr:...` per line, as a YAML block sequence, a YAML flow sequence, or a plain list (`#` comments and leading `- ` are both tolerated). An unusable entry is skipped with a warning. Without the flag the node starts with no bootnodes, since a lean network has no built-in list, and reaches peers only via discv5 (with `--discovery.enable`) or by being dialed | | `--discovery.enable` | `false` | Run discv5 peer discovery; off, the node peers from `--bootnodes` alone. See [Peer discovery](./discovery.md) | | `--aggregate-subnet-ids` | this node's subnets | Subnets to aggregate on; requires `--is-aggregator` | | `--attestation-committee-count` | from `validator-config.yaml`, else `1` | Committees per slot | @@ -151,12 +155,13 @@ Engine API endpoint always requires authentication. See [the execution layer pairing](./beacon_engine.md) for what each verdict does and for the limitations that go with the retry ladder. -`beacon` takes one more flag of its own, and two common flags also mean +`beacon` takes two more flags of its own, and two common flags also mean something specific here. | Flag | Default | Meaning | |---|---|---| | `--network` | `mainnet` | A built-in network name (`mainnet`, `sepolia`, `hoodi` or `plataberget`), or a path to a directory of published network files. A value containing a slash is always a path, so `mainnet` is the built-in and `./mainnet` is a directory. The directory must hold `config.yaml` and `genesis.ssz`, and may hold `bootstrap_nodes.yaml` or `bootstrap_nodes.txt` | +| `--bootnodes` | none: the network's own list alone | Extra bootnodes: ENRs and multiaddrs, comma-separated, and the flag may be repeated. Added to the resolved network's own list, never replacing it. A bad entry is a startup error, and a file path is no longer accepted. See [Bootnodes on `beacon`](#bootnodes-on-beacon) | `genesis_validators_root` and `genesis_time`, which the fork digest that keys every gossip topic, the ENR `eth2` entry and discv5 admission is computed from, @@ -174,8 +179,10 @@ wrong chain. `beacon` therefore takes no genesis config, validator registry, or bootnode file of its own the way `node` does: those are read off the resolved network instead -of being separate operator input. A `config.yaml` (a directory's, or a built-in -network's embedded one) is read permissively: absent keys fall back to mainnet's values, +of being separate operator input, and `beacon`'s `--bootnodes` only adds entries +to the network's list (see [Bootnodes on `beacon`](#bootnodes-on-beacon)). A +`config.yaml` (a directory's, or a built-in network's embedded one) is read +permissively: absent keys fall back to mainnet's values, numbers are accepted quoted or bare, and unrecognised keys (on a current config, the heze schedule this build does not claim) are dropped with one warning line naming each. Its `PRESET_BASE` is checked against the @@ -218,6 +225,63 @@ site serves both chains, but it picks the router by the store's chain, so a `beacon` run serves the Beacon API under `/eth/v1` and `/eth/v2` and answers a `/lean/v0/...` path with a 404. See [`rpc.md`](./rpc.md). +### Bootnodes on `beacon` + +`beacon`'s `--bootnodes` is a list, not a file, modeled on Lighthouse's +`--boot-nodes`. Entries are comma-separated and the flag may be repeated, all +of its values combined; each entry is trimmed, and an empty one is ignored. An +entry is either an ENR, written with or without its `enr:` prefix, or a +multiaddr, which starts with `/`: + +```sh +ethlambda beacon --network hoodi --checkpoint-sync-url \ + --bootnodes enr:-Iq4Q…,/ip4/203.0.113.7/tcp/9000/p2p/16Uiu2HAm… \ + --bootnodes /ip4/203.0.113.8/udp/9000/p2p/16Uiu2HAk… +``` + +A multiaddr is `/ip4/` or `/ip6/`, then one transport, then +`/p2p/`. The transport decides what the entry is used for: + +| Transport | The peer is | +|---|---| +| `tcp/` | dialed over TCP | +| `udp//quic-v1` | dialed over QUIC | +| `udp/` | not dialed directly: the port is the peer's discv5 port, so the entry seeds discovery, which is how Lighthouse reads a UDP multiaddr too | + +QUIC is `quic-v1` only; the older draft `/quic` is refused. The +`/p2p/` is required, and DNS multiaddrs (`/dns`, `/dns4`, `/dns6`, +`/dnsaddr`) are refused, so write the address as `/ip4` or `/ip6`. Those two are +departures from Lighthouse; [Peer discovery](./discovery.md#multiaddrs) lists +them with the rest. + +The entries are added to the resolved network's own list (a built-in network's +embedded one, or a loaded directory's `bootstrap_nodes.yaml`/`.txt`), never put +in its place, which is Lighthouse's behavior too. Giving the flag used to +replace that list; now the network's bootnodes are always used, and the flag +only adds to them. Nothing turns them off: each one with a QUIC or TCP port is +dialed at startup and redialed 12 seconds after every failed dial or +disconnect, even on a host that cannot reach it. To run on other bootnodes +alone, load the network from a directory whose `bootstrap_nodes.yaml` lists +only those. + +An IPv6 entry is dialed like an IPv4 one, but discv5 listens on IPv4 only, so +an IPv6 entry that is only a discv5 contact (`/ip6//udp/`, or an ENR +whose only address is `ip6` and whose only port is `udp`) is refused. + +Every entry is checked at startup. One that does not parse, or that is +unusable (an ENR with no `quic`, `tcp` or `udp` port, a port of `0`, and so +on), is a startup error naming the entry: an operator who typed it meant to +reach that peer, and skipping it would leave the node running on a list it was +not given. The network's own list keeps the old rule, a bad entry there being +skipped with a warning, as `node` skips one in its file. + +**A file path is no longer accepted.** Startup fails on one, with a hint that +`--bootnodes` now takes a list; so does a missing path ending in `.yaml`, +`.yml` or `.txt`. A launch script that passed `beacon` a bootnode file must +pass the records it lists joined with commas instead (without a YAML list's +`- ` markers or any comments), or, for a network loaded from a directory, list +them in that directory's `bootstrap_nodes.yaml`. + ## What `ethlambda beacon` does today It follows the resolved network as a non-validating follower. It anchors a @@ -241,7 +305,7 @@ not chain-specific, branches once, and shares the shutdown: | raise `RLIMIT_NOFILE` | shared | shared | | `HIVE_LEAN_TEST_DRIVER` early return | yes | no: those endpoints are lean's | | resolve `--network` into a `NetworkSource` | n/a: lean has no `--network` | classify the value (built-in name vs. directory); parse the `config.yaml` (embedded, or the directory's) and check `PRESET_BASE` against the compiled preset and the constant-backed keys against their constants; for a directory, then decode `genesis.ssz` | -| read `--bootnodes` (falls back to the chain's default list; see the table above) | shared | shared | +| read `--bootnodes` | a file of ENRs; absent means no bootnodes, warned about | a comma-separated list of ENRs and multiaddrs, added to the resolved network's own list; a bad entry is a startup error (see [Bootnodes on `beacon`](#bootnodes-on-beacon)) | | build the aggregator, sync-status and event handles | shared | shared | | open `--data-dir`'s RocksDB backend | shared | shared | | resolve `--node-key`, else load `/node.key`, generating it on first start (after the open, so RocksDB's lock covers the write) | shared | shared | diff --git a/docs/discovery.md b/docs/discovery.md index 3040ea64a..bfd7ea68f 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -189,6 +189,13 @@ mainnet bootnode list is close to the mirror image, `udp` and no `quic`, and a discv5 seed only: four of the seventeen carry one. A record missing an `ip` or a `secp256k1` key is dropped regardless of its transports. +Dropped means skipped with a warning for an entry in `node`'s `--bootnodes` +file or in a network's own list, built-in or loaded. An entry given to +`beacon`'s `--bootnodes` is held to a stricter rule: one that does not parse, +or would be dropped here, is a startup error naming it, since the operator +typed it to reach that peer (see +[the CLI reference](./cli.md#bootnodes-on-beacon)). + The ENR a node logs at startup is only useful to a peer if that node was started with a real `--discovery.advertise-ip`. Copying an ENR built from the default `0.0.0.0` into another node's bootnode @@ -197,6 +204,44 @@ names no reachable host. Set `--discovery.advertise-ip` before pointing other nodes at this one's ENR: `127.0.0.1` on a local devnet, or the host's public address otherwise. +### Multiaddrs + +`beacon`'s `--bootnodes` also takes multiaddrs, `/ip4/` or `/ip6/` +followed by one transport and `/p2p/`. A multiaddr names a single +transport, so it fills exactly one of the three entries above, the IP and the +key coming from the address and the peer id: + +| Transport | Entry it fills | The peer is | +| --- | --- | --- | +| `tcp/` | `tcp` | dialed over TCP | +| `udp//quic-v1` | `quic` | dialed over QUIC | +| `udp/` | `udp` | seeded into discv5, not dialed directly | + +A UDP multiaddr names the peer's discovery port, not a libp2p listener, which +is how Lighthouse reads one too. A peer reachable more than one way takes one +entry per transport, and the entries are merged under its peer id. An `/ip6` +UDP multiaddr is refused: discovery binds the IPv4 wildcard, and an IPv4 +socket cannot reach an IPv6 address. `/ip6` with `tcp` or `quic-v1` is dialed +by the swarm and accepted. + +The form follows Lighthouse's `--boot-nodes`, with four deliberate departures: + +- **`/p2p/` is required**, and the peer id must embed its public key, + which every secp256k1 peer id does. Every bootnode is keyed by its peer id + (its dial addresses are merged under it, and it is how this node skips its + own entry and redials the others), and discv5 is seeded with that key, so an + anonymous entry has no place to go. Lighthouse dials a TCP multiaddr with no peer id + anonymously. +- **DNS multiaddrs are refused** (`/dns`, `/dns4`, `/dns6`, `/dnsaddr`): a + bootnode holds an address, and the swarm has no DNS transport to resolve a + name with. Write the address as `/ip4` or `/ip6`. +- **QUIC multiaddrs are dialed.** Lighthouse dials only TCP multiaddr + bootnodes; this node prefers QUIC wherever a peer offers it (see + [Which peers get dialed](#which-peers-get-dialed)). +- **A UDP multiaddr seeds discv5 directly**, with the key taken from the peer + id, rather than through a discv5 ENR request. The outcome is the same: + discovery learns the peer's record on first contact. + ## Known limitations ### Static bootnodes bypass admission and are redialed indefinitely @@ -204,8 +249,10 @@ address otherwise. Everything under [Which peers get dialed](#which-peers-get-dialed) applies to *discovered* peers. A static bootnode reaches the swarm by a different path: `parse_enr` reads `ip`, `secp256k1` and the three port entries and never looks at -`eth2`, so a `--bootnodes` list is dialed as given. Now that a `tcp`-only record -is dialable, a beacon-chain ENR is a valid static target, and the noise+yamux +`eth2`, so a bootnode list is dialed as given: `node`'s `--bootnodes` file, or +on `beacon` the network's own list plus any `--bootnodes` entries, whose +multiaddrs carry no `eth2` to look at in the first place. Now that a `tcp`-only +record is dialable, a beacon-chain ENR is a valid static target, and the noise+yamux handshake to a lighthouse node succeeds: the peer occupies a `--discovery.target-peers` slot, contributes no attestation subnets, and is eventually dropped by the remote for sharing no protocols. Each drop re-arms the