From ab725fa170c9c50a47fcb65ba76a291cc20e2949 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:37:10 -0300 Subject: [PATCH 1/6] feat(cli): take beacon --bootnodes as a list of ENRs and multiaddrs beacon --bootnodes now takes a comma-separated, repeatable list in the shape of Lighthouse's --boot-nodes: each entry an ENR (enr: prefix optional) or a /ip4|ip6/.../{tcp|udp/quic-v1|udp}/.../p2p/ multiaddr. The entries are added in front of the network's own bootnode list instead of replacing it. A command-line entry that does not parse is a startup error naming it; a file path is refused with a hint, since the flag used to take one. node --bootnodes keeps taking a file of ENRs. --- CLAUDE.md | 21 +- bin/ethlambda/src/cli.rs | 125 ++++++++-- bin/ethlambda/src/command.rs | 2 + bin/ethlambda/src/main.rs | 329 ++++++++++++++++++++----- bin/ethlambda/src/network/dir.rs | 7 +- bin/ethlambda/src/network/mod.rs | 3 +- crates/net/p2p/src/lib.rs | 401 +++++++++++++++++++++++++++++-- docs/beacon_wire.md | 4 +- docs/checkpoint_sync.md | 2 +- docs/cli.md | 68 +++++- docs/discovery.md | 48 +++- 11 files changed, 889 insertions(+), 121 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4b4afa4b4..b0cd259f7 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). 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..9bf1d41b5 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,76 @@ 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; the empty entries they leave + /// are skipped at startup (`main::beacon_bootnodes`), not refused here. + #[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,"]); + assert_eq!(parse_beacon(args).mainnet.bootnodes, ["enr:a", ""]); + } + #[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 6eaead20e..394782808 100644 --- a/bin/ethlambda/src/main.rs +++ b/bin/ethlambda/src/main.rs @@ -53,8 +53,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 _}; @@ -259,9 +260,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, @@ -309,8 +311,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` @@ -424,11 +427,11 @@ 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`. + // Resolved once, here, above the bootnode resolution below that reads it: + // `beacon`'s `--bootnodes` entries are added to the network's own 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, Network::Mainnet { mainnet, .. } => { @@ -437,16 +440,18 @@ async fn run_node(options: Options) -> eyre::Result<()> { } }; - // 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())), - ); + // Resolved once, here, for the swarm and discv5 below. `--bootnodes` means + // a different thing on each chain: a file of ENRs on `node`, a list added + // to the network's own on `beacon`. + let bootnodes = match &network { + Network::Lean(lean) => lean_bootnodes(lean.bootnodes.as_deref())?, + Network::Mainnet { mainnet, .. } => { + let source = network_source + .as_ref() + .expect("network_source is Some whenever network is Network::Mainnet"); + beacon_bootnodes(&mainnet.bootnodes, source.bootnodes())? + } + }; // Shared, runtime-mutable aggregator flag, seeded from the CLI flag only // `node` takes: mainnet has no aggregation duty. Threaded into both the @@ -680,7 +685,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, @@ -776,9 +780,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(), @@ -1064,32 +1069,96 @@ 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, 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) => Ok(parse_enrs(read_bootnode_strings(path)?)), 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()) } - Some(source) => source.bootnodes(), } } +/// `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. +fn beacon_bootnodes( + cli_entries: &[String], + network_entries: Vec, +) -> eyre::Result> { + let mut bootnodes = Vec::new(); + // Trimmed and skipped when empty here rather than in `parse_bootnode`, + // which refuses an empty entry: `--bootnodes ""` and a trailing comma + // both reach this point as an empty string 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 `--` (a prefix-less one starts + // with a single `-`), so this is that flag, not a bootnode. + if entry.starts_with("--") { + eyre::bail!( + "--bootnodes was given no value: it took the flag \"{entry}\" as its value" + ); + } + 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. + if Path::new(entry).is_file() { + eyre::eyre!( + "--bootnodes entry \"{entry}\" is a file: beacon --bootnodes now \ + takes a comma-separated list of ENRs and multiaddrs, not a file. \ + Pass the file's entries joined with commas 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); + 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` @@ -3642,25 +3711,163 @@ 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. `Bootnode` has no `Debug`, so `expect_err` is not available. + fn beacon_bootnodes_refusal(cli_entries: &[&str]) -> String { + let entries: Vec = cli_entries.iter().map(|entry| entry.to_string()).collect(); + match beacon_bootnodes(&entries, Vec::new()) { + Ok(bootnodes) => panic!( + "{cli_entries:?} was accepted as {} bootnodes", + bootnodes.len() + ), + Err(err) => 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 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] @@ -3682,13 +3889,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 cc9ca2bd1..558bf7e35 100644 --- a/crates/net/p2p/src/lib.rs +++ b/crates/net/p2p/src/lib.rs @@ -2290,21 +2290,24 @@ 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 @@ -2314,12 +2317,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: @@ -2362,14 +2370,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 } @@ -2418,6 +2425,164 @@ 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. 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()); + } + if entry.starts_with('/') { + return parse_bootnode_multiaddr(entry); + } + if entry.starts_with("enr:") { + return parse_enr(entry).map_err(|reason| format!("invalid ENR: {reason}")); + } + // 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}") + }) +} + +/// 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 @@ -2475,7 +2640,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; } @@ -4171,6 +4336,210 @@ 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 { + match parse_bootnode(entry) { + Ok(bootnode) => panic!("{entry:?} was accepted as a bootnode at {}", bootnode.ip), + Err(reason) => reason, + } + } + + #[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)); + } + + #[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); + } + + #[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 2cef98120..765f16bbe 100644 --- a/docs/beacon_wire.md +++ b/docs/beacon_wire.md @@ -926,7 +926,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 b04b4d89e..02f054a3c 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,53 @@ 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. + +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. A launch script that passed `beacon` a bootnode +file must pass its entries joined with commas instead, 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 +295,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..ba1c89b12 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,41 @@ 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. + +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 +246,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 From 12e9facb51094156b3234a77af06e24074a52c10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 19 Nov 2026 18:02:44 -0300 Subject: [PATCH 2/6] test(p2p): a multiaddr and an ENR for one peer merge into one dial beacon adds its --bootnodes entries to the network's ENR list and leaves duplicates to build_swarm's merge, so a peer typed as a multiaddr and also listed by the network must reach one dial with both addresses. The new test parses one of each for the same key and checks the merge. Bootnode now derives Debug, so the refusal helper uses expect_err. --- crates/net/p2p/src/lib.rs | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/crates/net/p2p/src/lib.rs b/crates/net/p2p/src/lib.rs index 558bf7e35..2c11cbfe7 100644 --- a/crates/net/p2p/src/lib.rs +++ b/crates/net/p2p/src/lib.rs @@ -2287,7 +2287,7 @@ pub fn derive_peer_ids(names_and_privkeys: HashMap) -> HashMap String { - match parse_bootnode(entry) { - Ok(bootnode) => panic!("{entry:?} was accepted as a bootnode at {}", bootnode.ip), - Err(reason) => reason, - } + parse_bootnode(entry).expect_err("the entry must be refused") } #[test] @@ -4429,6 +4426,33 @@ mod tests { 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 [ From 713a6399c345484f709d7d439389c4df929230f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 19 Nov 2026 18:02:44 -0300 Subject: [PATCH 3/6] fix(cli): warn when the bootnode list ends up empty - beacon warns when neither --bootnodes nor the network's own list gives a bootnode, which leaves discv5 with no seed. A network directory with no bootnode file used to start that way with only an info-level count. - node warns when its --bootnodes file gives no usable bootnode. parse_enrs's own warning is worded for one list now that beacon adds to its result, so it no longer says the node starts with none. - The network and the bootnodes are resolved in one match, so beacon's arm has the NetworkSource in hand and no expect is needed. - The file-path error says the entries are added to the network's own list, not put in its place, since --bootnodes used to replace it. - The comment on the -- check derives why no ENR starts with --, and the blank-entry comment no longer implies parse_bootnode does not trim. - The empty-value CLI test's doc says its assertion holds whether clap yields no entry or one empty entry. --- bin/ethlambda/src/cli.rs | 6 ++- bin/ethlambda/src/main.rs | 93 ++++++++++++++++++++++----------------- 2 files changed, 57 insertions(+), 42 deletions(-) diff --git a/bin/ethlambda/src/cli.rs b/bin/ethlambda/src/cli.rs index 9bf1d41b5..5cb59680f 100644 --- a/bin/ethlambda/src/cli.rs +++ b/bin/ethlambda/src/cli.rs @@ -977,8 +977,10 @@ mod tests { assert_eq!(parse_beacon(args).mainnet.bootnodes, [enr]); } - /// An empty value and a trailing comma parse; the empty entries they leave - /// are skipped at startup (`main::beacon_bootnodes`), not refused here. + /// 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`). The first assertion holds whether clap + /// turns `""` into no entry or one empty entry, since startup handles both. #[test] fn beacon_bootnodes_parses_an_empty_value_and_a_trailing_comma() { let mut args = beacon_args(); diff --git a/bin/ethlambda/src/main.rs b/bin/ethlambda/src/main.rs index 394782808..92020d6bc 100644 --- a/bin/ethlambda/src/main.rs +++ b/bin/ethlambda/src/main.rs @@ -427,29 +427,21 @@ 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 resolution below that reads it: - // `beacon`'s `--bootnodes` entries are added to the network's own 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)?) - } - }; - - // Resolved once, here, for the swarm and discv5 below. `--bootnodes` means - // a different thing on each chain: a file of ENRs on `node`, a list added - // to the network's own on `beacon`. - let bootnodes = match &network { - Network::Lean(lean) => lean_bootnodes(lean.bootnodes.as_deref())?, - Network::Mainnet { mainnet, .. } => { - let source = network_source - .as_ref() - .expect("network_source is Some whenever network is Network::Mainnet"); - beacon_bootnodes(&mainnet.bootnodes, source.bootnodes())? + let source = network::NetworkSource::resolve(&spec)?; + let bootnodes = beacon_bootnodes(&mainnet.bootnodes, source.bootnodes())?; + (Some(source), bootnodes) } }; @@ -1074,12 +1066,24 @@ async fn wait_for_shutdown(node: RunningNode) { /// 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, 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". +/// 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) => Ok(parse_enrs(read_bootnode_strings(path)?)), + 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 \ @@ -1103,22 +1107,27 @@ fn lean_bootnodes(file: Option<&Path>) -> eyre::Result> { /// /// 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. +/// 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(); - // Trimmed and skipped when empty here rather than in `parse_bootnode`, - // which refuses an empty entry: `--bootnodes ""` and a trailing comma - // both reach this point as an empty string and mean "nothing". + // 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 `--` (a prefix-less one starts - // with a single `-`), so this is that flag, not a bootnode. + // 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" @@ -1132,7 +1141,8 @@ fn beacon_bootnodes( eyre::eyre!( "--bootnodes entry \"{entry}\" is a file: beacon --bootnodes now \ takes a comma-separated list of ENRs and multiaddrs, not a file. \ - Pass the file's entries joined with commas instead" + Pass the file's entries joined with commas instead. They are added \ + to the network's own bootnodes, not put in their place" ) } else { eyre::eyre!("invalid --bootnodes entry \"{entry}\": {reason}") @@ -1149,6 +1159,14 @@ fn beacon_bootnodes( "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) } @@ -3745,16 +3763,11 @@ validators: } /// Why `beacon_bootnodes` refuses `cli_entries`, panicking if it accepts - /// them. `Bootnode` has no `Debug`, so `expect_err` is not available. + /// them. fn beacon_bootnodes_refusal(cli_entries: &[&str]) -> String { let entries: Vec = cli_entries.iter().map(|entry| entry.to_string()).collect(); - match beacon_bootnodes(&entries, Vec::new()) { - Ok(bootnodes) => panic!( - "{cli_entries:?} was accepted as {} bootnodes", - bootnodes.len() - ), - Err(err) => format!("{err:#}"), - } + 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 From 155878dbef3836a1ac6361b2b60adbc529e8f90f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:12:48 -0300 Subject: [PATCH 4/6] fix(p2p): refuse an IPv6 bootnode that is only a discv5 contact run_node binds discovery to the IPv4 wildcard, and an IPv4 UDP socket cannot send to an IPv6 address. A --bootnodes entry such as /ip6//udp//p2p/, or an ENR whose only address is ip6 and whose only port is udp, was therefore accepted at startup and never contacted. That is the case the parser already refuses for a discv5 contact with a non-secp256k1 key: nothing could use the entry. parse_bootnode now refuses it for either form. An IPv6 entry with a QUIC or TCP port is kept, since the swarm dials it rather than the discovery socket. A new test checks both sides. The network's own list keeps its lenient rule, as it did. docs/cli.md, docs/discovery.md and CLAUDE.md say so. --- CLAUDE.md | 2 +- crates/net/p2p/src/lib.rs | 60 ++++++++++++++++++++++++++++++--------- docs/cli.md | 4 +++ docs/discovery.md | 5 +++- 4 files changed, 55 insertions(+), 16 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9121af9b2..e69648649 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -975,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. `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). 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`) +**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/crates/net/p2p/src/lib.rs b/crates/net/p2p/src/lib.rs index 6311ad955..a431d6743 100644 --- a/crates/net/p2p/src/lib.rs +++ b/crates/net/p2p/src/lib.rs @@ -2571,26 +2571,43 @@ fn parse_enr(enr_str: &str) -> Result { /// 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. Unlike [`parse_enrs`], a bad entry is -/// an error rather than a warning, since an operator typed it on the command -/// line. +/// 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()); } - if entry.starts_with('/') { - return parse_bootnode_multiaddr(entry); - } - if entry.starts_with("enr:") { - return parse_enr(entry).map_err(|reason| format!("invalid ENR: {reason}")); + 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(), + ); } - // 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}") - }) + Ok(bootnode) } /// The multiaddr half of [`parse_bootnode`], walked component by component so @@ -4642,6 +4659,21 @@ mod tests { 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(); diff --git a/docs/cli.md b/docs/cli.md index d1feb693b..e4a2d92ba 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -260,6 +260,10 @@ 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. +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 diff --git a/docs/discovery.md b/docs/discovery.md index ba1c89b12..bfd7ea68f 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -219,7 +219,10 @@ key coming from the address and the peer id: 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. +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: From 923f04e1c40e51304dc9f22113aada41a274f572 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:12:57 -0300 Subject: [PATCH 5/6] fix(cli): point a missing bootnode file at the list form, and drop YAML markers The hint for a file passed to beacon --bootnodes said to join the file's entries with commas. A bootnode file is usually a YAML list, so joining its lines as they are keeps the "- " markers and comments, and the next start fails as an invalid ENR without the hint. It now says to pass the records themselves, without markers or comments, and that a directory network can list them in its bootstrap_nodes.yaml instead. The hint fired only for a path that exists. A launcher whose bootnode file is missing got an ENR or multiaddr decoding error. A path ending in .yaml, .yml or .txt now gets the hint too. Tests: the existing file test checks the marker advice, and a new one passes a missing absolute path and a missing relative one. docs/cli.md says the same, and adds that nothing turns the network's bootnodes off: each dialable one is dialed at startup and redialed 12 s after every failed dial or disconnect, so running on other bootnodes alone means a directory network listing only those. --- bin/ethlambda/src/main.rs | 38 ++++++++++++++++++++++++++++++++------ docs/cli.md | 14 ++++++++++---- 2 files changed, 42 insertions(+), 10 deletions(-) diff --git a/bin/ethlambda/src/main.rs b/bin/ethlambda/src/main.rs index 6cf78e853..bad3ba0a1 100644 --- a/bin/ethlambda/src/main.rs +++ b/bin/ethlambda/src/main.rs @@ -1137,13 +1137,24 @@ fn beacon_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. - if Path::new(entry).is_file() { + // 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}\" is a file: beacon --bootnodes now \ - takes a comma-separated list of ENRs and multiaddrs, not a file. \ - Pass the file's entries joined with commas instead. They are added \ - to the network's own bootnodes, not put in their place" + "--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}") @@ -3869,6 +3880,21 @@ validators: "{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 diff --git a/docs/cli.md b/docs/cli.md index e4a2d92ba..3bce748b9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -258,7 +258,11 @@ 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. +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 @@ -272,9 +276,11 @@ 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. A launch script that passed `beacon` a bootnode -file must pass its entries joined with commas instead, or, for a network loaded -from a directory, list them in that directory's `bootstrap_nodes.yaml`. +`--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 From b867a34861d884e12ea4269d7ba475a4d10bebae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1s=20Gr=C3=BCner?= <47506558+MegaRedHand@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:14:06 -0300 Subject: [PATCH 6/6] test(cli): stop pinning how many empty entries clap leaves for a trailing comma The trailing-comma half of the empty-value test asserted clap's exact output, ["enr:a", ""], so a clap release that dropped the empty entry would fail it, though startup skips empty entries either way. It now checks that "enr:a" comes first and that anything after it is empty, as the first half already did for "". --- bin/ethlambda/src/cli.rs | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/bin/ethlambda/src/cli.rs b/bin/ethlambda/src/cli.rs index 5cb59680f..719b6a1f8 100644 --- a/bin/ethlambda/src/cli.rs +++ b/bin/ethlambda/src/cli.rs @@ -979,8 +979,8 @@ mod tests { /// 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`). The first assertion holds whether clap - /// turns `""` into no entry or one empty entry, since startup handles both. + /// (`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(); @@ -995,7 +995,9 @@ mod tests { let mut args = beacon_args(); args.extend(["--bootnodes", "enr:a,"]); - assert_eq!(parse_beacon(args).mainnet.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]