Skip to content

feat(cli): take beacon --bootnodes as a list of ENRs and multiaddrs - #825

Open
MegaRedHand wants to merge 9 commits into
mainfrom
feat/beacon-bootnodes-list
Open

MegaRedHand wants to merge 9 commits into
mainfrom
feat/beacon-bootnodes-list

Conversation

@MegaRedHand

Copy link
Copy Markdown
Collaborator

What

ethlambda beacon --bootnodes now takes a list of bootnodes on the command line instead of a file path, in the shape of Lighthouse's --boot-nodes:

ethlambda beacon --network hoodi \
  --bootnodes enr:-Iq4Q...,/ip4/203.0.113.7/tcp/9000/p2p/16Uiu2HAm... \
  --bootnodes /ip4/203.0.113.8/udp/9000/p2p/16Uiu2HAk...
  • Comma-separated, and the flag can be repeated. Entries are trimmed; empty ones are ignored.
  • An entry starting with / is a multiaddr. Anything else is an ENR, with the enr: prefix optional.
  • Multiaddr transports map onto the same Bootnode an ENR produces:
    • /tcp/<port> is dialed over TCP.
    • /udp/<port>/quic-v1 is dialed over QUIC.
    • A bare /udp/<port> is the discv5 port. That peer seeds discovery and is not dialed, which is how Lighthouse reads a UDP multiaddr too.
  • Added to the network's own list. Entries go in front of the built-in or loaded network's bootnodes and no longer replace them, matching Lighthouse.
  • Bad entries. A command-line entry that does not parse, or that nothing could use (port 0, an ENR with no ports, ...), is a startup error naming it. The network's own list still skips a bad entry with a warning.
  • node is unchanged. node --bootnodes <PATH> still takes a file of ENRs. The field moved out of CommonOptions into LeanOptions/MainnetOptions, since the two sub-commands now read it differently.

Departures from Lighthouse

  • A peer id is required. Every multiaddr needs /p2p/<peer-id>, and the peer id must embed its public key, which every secp256k1 id does. Bootnodes are keyed by peer id for dial merging, skipping our own record and redials, and discv5 is seeded with that key. Lighthouse dials a TCP multiaddr with no peer id anonymously.
  • No DNS. DNS multiaddrs are refused, because the swarm has no DNS transport and Bootnode holds an IP.
  • QUIC multiaddrs are dialed. Lighthouse's multiaddr bootnodes dial TCP only.
  • No ENR round trip. A UDP multiaddr seeds discv5 directly with the key taken from the peer id, rather than through a discv5 request for the ENR.

Breaking: kurtosis launcher

beacon --bootnodes <file> no longer works. A path that names an existing file fails with an error saying the flag now takes a comma-separated list.

The assertoor battery's pinned lambdaclass/ethereum-package launcher (ETHEREUM_PACKAGE_REF 67cb0e02) writes the bootnodes to /tmp/ethlambda-bootnodes.txt and passes that path. It will fail at startup until the launcher passes the list directly and the pin is bumped; that change is being made separately. The same applies to any host launch script that passes beacon a bootnode file.

Review notes

A review pass raised these; they were fixed in this PR:

  • The "no bootnode ENR could be used" warning claimed the node had no bootnodes even when command-line entries existed. It now describes the list it parsed.
  • A value-less --bootnodes (for example, an unset variable in a script) takes the next flag as its value because of allow_hyphen_values. That is now refused as "given no value" instead of being reported as a malformed ENR.

Left as they are, because ENR bootnodes behave the same way today: /ip6 addresses (ENRs fall back to ip6), and unspecified addresses such as 0.0.0.0.

Tests

  • ethlambda-p2p: 14 parser tests: every transport, ENRs with and without the prefix, peer id to key round trip, and each refusal.
  • ethlambda:
    • CLI shapes: comma list plus repeated flag before --network, a prefix-less ENR starting with -, empty values, lean's file path.
    • beacon_bootnodes: order and additivity, empty entries skipped, malformed entry, file hint, missing value, bad network entry skipped.
  • make fmt, workspace clippy with -D warnings, and the ethlambda and ethlambda-p2p test suites pass.

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/<peer-id> 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.
@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

The changes look solid. Splitting --bootnodes between LeanOptions (file path) and MainnetOptions (additive comma-separated/repeatable ENR and multiaddr list) is clean and well-structured:

  • parse_bootnode and parse_bootnode_multiaddr in crates/net/p2p/src/lib.rs handle prefix-less ENRs, transport validation (tcp, udp/.../quic-v1, bare udp for discv5), inline public key extraction from PeerId, and secp256k1 verification for discv5-only contacts.
  • beacon_bootnodes in bin/ethlambda/src/main.rs has good ergonomics and failure modes for migration (detecting file paths passed to beacon --bootnodes and catching accidental flag swallowing from allow_hyphen_values).
  • Tests and documentation cover all the new behaviors and edge cases.

Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: beacon --bootnodes as an additive ENR/multiaddr list

This is a well-scoped change with thorough tests. Splitting --bootnodes per chain fits the existing Network::Lean / Network::Mainnet design better than a shared Option with two meanings. I found no correctness or security blockers, since all inputs here are operator-supplied CLI values. Notes below, roughly by priority.

Behavioral / correctness

  1. An empty final bootnode set on beacon no longer warns at node level (crates/net/p2p/src/lib.rs, parse_enrs warn; main.rs beacon_bootnodes).

    • The parse_enrs warning was reworded to be list-scoped ("No bootnode ENR in this list could be used"), which is right for the additive case.
    • But nothing now flags the case where both halves end up empty. That happens when there are no CLI entries and every network entry was skipped.
    • The info! line still prints from_command_line=0 from_network=0, but at info level that is easy to miss on a node that otherwise looks healthy.
    • Suggest a warn! in beacon_bootnodes when bootnodes.is_empty() before returning.
    • The same regression applies on node: a file whose every entry is bad used to say "the node starts with no bootnodes". lean_bootnodes could warn on an empty result when the file was non-empty.
  2. Bare /udp/<port> entries reach build_swarm as undialable (merge_bootnode_dial_addrs, around line 2640).

    • A discv5-only multiaddr has no quic_port or tcp_port, so it lands in the undialable counter.
    • If that counter feeds a warning, every documented udp/<port> entry produces noise for an intentional configuration.
    • Worth confirming, and either excluding udp-only bootnodes from that count or wording the log so it is clearly informational.
  3. Unspecified or obviously unroutable IPs are accepted (parse_bootnode_multiaddr).

    • /ip4/0.0.0.0/tcp/9000/p2p/… or /ip6/::/… parses fine and then fails silently at dial time.
    • Since this path is explicitly strict ("a bad one fails startup"), rejecting ip.is_unspecified() would be consistent. Multicast could be rejected the same way.
    • parse_enr presumably has the same gap, but there it only warns.
  4. The -- check is sound. The prefix-less ENR reasoning in beacon_bootnodes holds:

    • An ENR is an RLP long list (≤300 bytes), so its first byte is 0xf8 or 0xf9.
    • Its base64 therefore starts -I… or -Q…/-f…, never --.
    • Consider stating that derivation in the comment, so a future reader does not have to redo it.

Rust / idiom

  1. Avoid the expect on network_source (main.rs, the new bootnodes match). The invariant holds today, but you can make it structural. Resolve both values in the existing network_source match, since the two blocks are adjacent:

    let (network_source, bootnodes) = match &network {
        Network::Lean(lean) => (None, lean_bootnodes(lean.bootnodes.as_deref())?),
        Network::Mainnet { mainnet, .. } => {
            let source = /* resolve */;
            let bootnodes = beacon_bootnodes(&mainnet.bootnodes, source.bootnodes())?;
            (Some(source), bootnodes)
        }
    };

    This removes a panic path and the comment explaining why it cannot fire.

  2. Bootnode has no Debug. Both test helpers (bootnode_refusal, beacon_bootnodes_refusal) hand-roll expect_err because of this. PublicKey, IpAddr and Option<u16> are all Debug, so #[derive(Clone, Debug)] costs nothing and would simplify the tests. It would also help any future ?bootnode log.

  3. parse_bootnode trims, and beacon_bootnodes also trims before calling it. The duplication is harmless, but one of the two comments ("Trimmed and skipped when empty here rather than in parse_bootnode") is now slightly misleading, since parse_bootnode trims too. It only differs in refusing the empty result.

Minor

  1. The beacon startup info! dropped bootnodes = ?common.bootnodes (around line 685). The replacement "Resolved bootnodes" count line is fine. If you want parity with the old log, consider logging the CLI entries themselves at debug level, so an operator can confirm what was parsed.

  2. The cli.rs test beacon_bootnodes_parses_an_empty_value_and_a_trailing_comma. The .all(String::is_empty) assertion also passes on an empty Vec, so it does not pin whether clap yields [] or [""]. That is fine given that beacon_bootnodes handles both, but the doc comment implies the latter.

  3. Breaking change for launchers. The file-path hint in beacon_bootnodes is a good touch. Since kurtosis is named in the test comment, make sure the ethereum-package launcher is updated in lockstep, or beacon participants there will fail to start.

Tests

Coverage is strong:

  • ENR with and without prefix
  • TCP / QUIC / bare-UDP multiaddrs
  • IPv6
  • refusal of DNS, draft QUIC, port 0, trailing components and hashed peer ids
  • an ed25519 key on UDP
  • ordering and additivity
  • the value-less flag case
  • the file-path hint

One gap: a test where the same peer appears via both a CLI multiaddr and a network ENR. It would confirm the build_swarm merge produces a single dial target with both addresses, since that dedup is now relied on explicitly in beacon_bootnodes' doc comment.

LGTM after Item 1, plus Item 5 if you agree.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. Bootnode parsing and integration look sound, with good coverage of malformed inputs and preserved network defaults. Consensus processing is unchanged.

Tests could not run because rustup attempted to write to a read-only directory.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

Overall this is a clean split of --bootnodes into per-chain flags, with thorough tests and docs. The bootnode parsing stays isolated to config/bootstrap logic; I don’t see consensus-state or fork-choice issues here.

A few issues/improvements worth addressing:

  • bin/ethlambda/src/main.rs — beacon_bootnodes missing-value heuristic is fragile.
    The if entry.starts_with("--") check only catches long flags. If --bootnodes receives no value and is followed by a short flag such as -h or -v, allow_hyphen_values can consume that flag as the value, and it then goes to parse_bootnode, producing a confusing “invalid bootnode entry” error rather than “missing value”. Consider parsing first and only emitting the missing-value error if parsing fails and the entry starts with --, or use clap’s require_equals for this arg.

  • bin/ethlambda/src/main.rs — beacon_bootnodes can silently produce an empty bootnode list.
    For a loaded network directory with no bootstrap_nodes.yaml/.txt, source.bootnodes() returns empty and the function returns Ok(vec![]) without a warning; only an info-level count is logged. A beacon node can then start with no static seeds and no obvious indication. Since lean_bootnodes explicitly warns for the absent-file case, consider warning here too when the final list is empty.

  • bin/ethlambda/src/main.rs — run_node uses expect for an invariant.
    network_source.as_ref().expect("network_source is Some whenever network is Network::Mainnet") is currently correct, but startup code is safer without it. A let Some(source) = network_source.as_ref() else { unreachable!() } or handling the match directly would avoid a panic path if the invariant is ever disturbed.

  • crates/net/p2p/src/lib.rs — multiaddr IP validation is minimal.
    parse_bootnode_multiaddr accepts 0.0.0.0 or :: as the IP. If the intended rule is that unusable bootnodes fail startup, an unspecified address should probably be rejected explicitly, since it cannot name a reachable peer.


Automated review by DeepSeek · deepseek-v4-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No blocking issues found.

  • bin/ethlambda/src/main.rs: chain-specific resolution preserves lean’s file-based behavior while making beacon bootnodes additive. Strict CLI errors versus warn-and-skip handling for network-provided entries is sensible, and the network_source invariant is clear.
  • crates/net/p2p/src/lib.rs: multiaddr parsing correctly rejects unsupported transports, DNS addresses, port zero, missing/non-inline peer IDs, trailing components, and non-secp256k1 discv5 seeds.
  • Tests provide good coverage of ordering, malformed entries, legacy file-path errors, hyphen-prefixed ENRs, empty values, and multiaddr edge cases.

I don’t see correctness, security, or performance regressions in this diff.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

The bootnode split is sound: chain-specific flags, CLI entries fail closed, network ENRs still warn-and-skip, and multiaddr parsing rejects DNS, draft QUIC, missing /p2p, and trailing components. No fork-choice, attestation, finalization, or SSZ changes. A few startup-path issues:

  1. File-path hint drops the old replace semantics (beacon_bootnodes in bin/ethlambda/src/main.rs, the Path::new(entry).is_file() branch). Kurtosis-style --bootnodes=/tmp/...txt used to replace the network list; the error only says to comma-join the file. Following that hint now also dials bootstrap_nodes.yaml / the built-in list. That can undo a deliberate isolation override (private peers, bad published seeds). Say in the error that the flag is additive, and that replacing the list means editing the network directory's bootnode file, not passing --bootnodes.

  2. -- rejection runs before parse (same function, entry.starts_with("--")). A value-less --bootnodes should still be a clear error, but the comment overclaims: URL-safe base64 can start with --. Parse first; if it fails and the token starts with --, then emit the "given no value" error. A flag is never a valid ENR, so the message stays accurate without rejecting a prefix-less record.

  3. is_file() is a broad heuristic. Any failed token that happens to be an existing path (/etc/passwd, a relative path in the cwd) gets the migration hint and hides the parser reason. Narrow it (for example path separator, not starting with /ip or enr:, and a bootnode-file suffix) so real multiaddr/ENR failures keep {reason}.

  4. CLI ENR usability is only as strict as parse_enr. Multiaddrs explicitly reject port 0 and a bare UDP peer id discv5 cannot use. parse_bootnode returns parse_enr's Ok unchanged. If that still yields a Bootnode with no quic/tcp/udp (port 0 stored as absent), a typed ENR is kept and the node starts without that peer, which contradicts docs/cli.md and docs/discovery.md. Add a guard (or a test) that an ENR with no usable port fails parse_bootnode.

  5. New tests may not build as written. seeded_peer_id uses HashMap with no new import in main.rs's test module, and a_bootnode_file_on_beacon_is_refused_with_a_hint calls tempfile::NamedTempFile with no Cargo.toml change. Confirm both are already in scope for bin/ethlambda tests.

Minor: the network_source.as_ref().expect(...) in run_node is a second match on Network::Mainnet that can drift; resolving bootnodes in the same arm as resolve would make the Some invariant structural. Duplicate peer ids are intentionally left to build_swarm — worth one test that a CLI TCP multiaddr and a network ENR for the same key union dial addresses rather than last-wins, since network entries are appended after the CLI.


Automated review by Grok (xAI) · grok-4.7 · custom prompt

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.
- 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.
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round one (the automated review of ab725fa). Fixed in 12e9fac and 713a639.

Verification: make fmt and make lint clean. Tests were not run locally; CI runs them.

Fixed

  • Claude 1, DeepSeek 2: an empty bootnode list did not warn.
    • beacon now warns when neither --bootnodes nor the network's own list gives a bootnode, since discv5 then has no seed. A network directory with no bootnode file used to start that way with only an info-level count.
    • node now warns when its --bootnodes file gives no usable bootnode. parse_enrs' own warning is worded for one list, so it no longer says that.
    • The no-flag path on node already warned and is unchanged. There is no test for the log lines.
  • Claude 5, DeepSeek 3, Grok: the expect on network_source. The network and the bootnodes are resolved in one match, so beacon's arm has the resolved network in hand.
  • Claude 6: Bootnode derives Debug. Both refusal helpers use expect_err.
  • Claude and Grok: one peer as a typed multiaddr and as a network ENR. New test a_multiaddr_and_an_enr_for_one_peer_merge_into_one_dial (p2p) parses one of each for the same key and checks they merge into one dial target holding both addresses.
  • Grok 1: the file hint. --bootnodes used to replace the network's list. The error now says the entries are added to the network's own bootnodes, not put in their place.
  • Claude 4: the -- check. The comment now derives why no ENR starts with --: the first byte is 0xf8 or 0xf9, so the second base64 character is in A-f.
  • Claude 7: the blank-entry comment no longer suggests parse_bootnode does not trim.
  • Claude 9: the empty-value CLI test. Its doc now says the assertion holds whether clap yields no entry or one empty entry, since startup skips both.

Not changed

  • Grok 2: "base64 can start with --". Not for an ENR, as derived above, so the check never refuses a record.
  • Claude 2: bare /udp entries as noise. The undialable count warns only when nothing at all is dialable, and then the warning is accurate.
  • Claude 3, DeepSeek 4: unspecified IPs. Left as the PR description says: ENR bootnodes take them the same way today.
  • Claude 8: the dropped bootnodes log field. It printed the old file path. The counts line replaces it, and a bad entry fails startup by name.
  • Claude 10: launchers. Covered in the PR description; the launcher change is separate.
  • DeepSeek 1: short flags. beacon has none of its own. A single - can start a prefix-less ENR, so it cannot be refused before parsing, and the parse error names the entry.
  • Grok 3: is_file(). It runs only after both parsers failed, when a file path is what the entry is.
  • Grok 4: a typed ENR with no usable port. parse_enr refuses one with no quic, tcp or udp, and reads port 0 as absent, so startup fails on it.
  • Grok 5: HashMap, tempfile. Both are in scope: tempfile is a dev-dependency, and make lint builds every test target.

Gemini, Codex and Kimi found nothing to change.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

🤖 Gemini Code Review

This PR looks good. The split of --bootnodes between LeanOptions (file path) and MainnetOptions (additive comma-separated/repeatable list of ENRs and multiaddrs) is clean, well-documented, and thoroughly tested—including edge cases like prefixless ENRs starting with -, swallowed flags under allow_hyphen_values, and helpful migration errors when a file path is passed to beacon --bootnodes.


Automated review by Gemini · gemini-4-argon · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Codex Code Review

No actionable findings. The new bootnode parser validates transport structure, ports, and embedded public keys, and correctly routes entries to static dialing or discv5 discovery. Consensus logic is unchanged.

Tests could not run because rustup attempted to write to a read-only toolchain directory.


Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Claude Code Review

Review: beacon --bootnodes as an additive ENR/multiaddr list

The PR is well scoped and well tested. The split between strict CLI entries and lenient network entries is sensible. Lean semantics are unchanged, and the -- heuristic in beacon_bootnodes is justified correctly: an ENR's first byte is 0xf8/0xf9, which encodes as - followed by [A-Za-f]. A few points follow.

Correctness / behavior

  1. /ip6/.../udp/<port> discv5 seeds may be unreachable (crates/net/p2p/src/lib.rs, parse_bootnode_multiaddr).

    • p2p_socket binds 0.0.0.0 in main.rs. If the discv5 socket is also IPv4-only, an IPv6 UDP seed is accepted at startup but can never be contacted.
    • That contradicts the "a bad entry is a startup error" promise in the docs.
    • Fix: either refuse /ip6 for the Discv5 transport (and arguably for QUIC/TCP if the swarm has no v6 listener), or warn.
    • At minimum, parse_bootnode_reads_an_ip6_multiaddr should not suggest IPv6 is fully supported.
  2. Duplicate dial addresses are not deduplicated.

    • merge_bootnode_dial_addrs collects into Vec<Multiaddr>. The new test a_multiaddr_and_an_enr_for_one_peer_merge_into_one_dial compares via HashSet, which hides duplicates.
    • Duplicates are now easy to produce: the same multiaddr typed twice, or a CLI ENR that is also in the network list.
    • Consider deduplicating inside the merge, or asserting on the Vec length in the test.
  3. discv5 seeding has the same duplicate problem.

    • A peer can be given as both a CLI udp multiaddr and a network ENR with a different IP. That produces two ethrex_p2p::types::Node entries with the same node id.
    • Worth confirming that ethrex keeps the first (CLI) entry rather than erroring or flapping.
  4. Operator-typed ENRs are not signature-checked.

    • parse_enr (pre-existing) never verifies the record signature.
    • For network lists this is tolerable. For a strict CLI path whose stated purpose is "fail loudly on a bad entry", verifying the signature is cheap and catches truncated or edited records that still RLP-decode.
    • Low priority.
  5. Breaking change: the network list can no longer be replaced.

    • It is documented and matches Lighthouse.
    • However, there is no longer a way to run a built-in network with only custom seeds, for example for isolated testing against a private mirror.
    • If that use case matters, a --disable-network-bootnodes-style escape hatch is a small follow-up. Otherwise, fine as is.

Rust / API

  1. String errors on a public API. parse_bootnode and embedded_public_key return Result<_, String>. This is consistent with parse_enr, but since parse_bootnode is now pub and matched on by callers (tests grep message substrings), a small thiserror enum would make the tests less brittle.

  2. Redundant trimming. beacon_bootnodes trims each entry, and parse_bootnode trims again. This is harmless, but one owner is cleaner. Since parse_bootnode is public, keep it there and drop the .map(|e| e.trim()) in main.rs; the empty check can use entry.trim().is_empty().

  3. Path::new(entry).is_file() hint (main.rs). Running it only after a parse failure is the right call.

    • A path containing a comma would already have been split by clap, so the hint will not fire for it. This is an edge case and acceptable.
    • A nonexistent path (a typo) yields "invalid multiaddr" with no hint. Consider also hinting when the entry ends in .yaml/.txt.

Tests

  1. beacon_bootnodes_parses_an_empty_value_and_a_trailing_comma pins clap's behavior of turning "enr:a," into ["enr:a", ""]. That is fine, but it is fragile across clap upgrades. The startup-side test (beacon_bootnodes_skips_empty_and_blank_entries) already covers the semantics, so the clap-side assertion could be relaxed to .contains("enr:a").

Docs

The docs are thorough. CLAUDE.md and docs/cli.md correctly describe the reordering: network resolution now precedes bootnode resolution.

Overall this is good to merge once Item 1 is addressed (refuse or warn on IPv6 entries the node can't use). The other items are optional.


Automated review by Claude · claude-opus-5-5 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Kimi Code Review

No blocking correctness, security, or performance issues found in the supplied diff.

The implementation looks sound:

  • crates/net/p2p/src/lib.rs: multiaddr parsing rejects trailing components, unsupported transports, port zero, DNS addresses, hashed peer IDs, and non-secp256k1 discv5 contacts. Deriving the public key from identity-multihash peer IDs is consistent with Bootnode::peer_id() and dial-address merging.
  • bin/ethlambda/src/main.rs: network resolution still happens once, CLI and network bootnodes retain their intentionally different failure policies, and lean behavior remains unchanged apart from clearer warnings.
  • bin/ethlambda/src/cli.rs: the hyphen-value handling and explicit rejection of accidentally consumed flags address the main clap edge cases.
  • Test coverage is particularly thorough, including ENR/multiaddr equivalence, peer merging, malformed entries, legacy file paths, and additive network bootnodes.

The operator-facing breaking change is also clearly documented with a targeted startup-error hint for legacy file-based launch scripts.


Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 Grok Code Review

The bootnode split is sound: lean stays a file, beacon adds ENRs/multiaddrs on top of the network list, bad CLI entries fail startup, and network entries still warn-and-skip. No fork-choice, attestation, finalization, STF, XMSS, or SSZ changes. The -- heuristic is right (a real prefixless ENR is - plus A–f, never --), and flag-swallowing is tested.

  1. Migration hint will produce entries that still fail to parse. In beacon_bootnodes (bin/ethlambda/src/main.rs around the Path::new(entry).is_file() branch), the error tells operators to join the file with commas. The old reader accepted YAML block lists (- enr:…), comments, and blank lines. A raw join keeps those prefixes, so the next startup fails with invalid ENR and the file hint is gone. Say to pass the ENR/multiaddr strings only (strip - and comments), and mention bootstrap_nodes.yaml for a loaded network. Also keep {reason} in that error so a non-bootnode path that happens to be a file is not diagnosed only as the flag change.

  2. Bare-UDP key check is coupled to discv5 conversion. In parse_bootnode_multiaddr (crates/net/p2p/src/lib.rs, udp_port.is_some() && as_discovery_node().is_none()), None is treated as “not secp256k1”. Any other conversion failure (key encoding ethrex will not take, future None reasons) is reported as a key-type error and refuses a contact that might still be valid. Match on the libp2p key type, and reject a non-round-trip in embedded_public_key (PeerId::from_public_key must equal the /p2p/ id). Dial addresses are rebuilt from the decoded key, not the original multiaddr, so a non-canonical id fails closed but with a confusing dial miss.

  3. Additive lists plus indefinite redial. Replacing the network list is no longer possible, which is the safer mainnet default (a CLI override cannot eclipse the published seeds). Combined with static bootnodes being redialed forever and skipping eth2 admission, a custom or firewalled run still hammers every published seed and cannot turn that off. Worth one explicit line in docs/cli.md next to the “never replacing” note, especially for directory networks whose bootstrap_nodes.* entries are dead.

Nit: a lean file whose ENRs all fail now warns twice (parse_enrs and lean_bootnodes around the empty-list warn!). The second line is the one that says the node has no seeds; the first is leftover from the beacon wording change.


Automated review by Grok (xAI) · grok-4.7 · custom prompt

@github-actions

Copy link
Copy Markdown

🤖 DeepSeek Code Review

⚠️ Review failed: DeepSeek returned an empty content field (finish_reason=length, reasoning_content present=yes). Raise max_tokens or lower reasoning_effort ('none' disables thinking).


Automated review by DeepSeek

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/<ip>/udp/<port>/p2p/<id>, 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.
…ML 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.
…ling 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 "".
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round two (the automated review of 713a639). Fixed in 155878d, 923f04e and b867a34. The head these sit on, bdc9bbe, is 713a639 with main merged and no other change, so every point was judged there. make fmt and make lint are clean. Tests were not run locally; CI runs them.

Fixed

  • Claude 1, an IPv6 discv5 seed nothing can reach. run_node binds discovery to 0.0.0.0, and an IPv4 socket cannot send to an IPv6 address. parse_bootnode now refuses an IPv6 entry that is only a discv5 contact, in either form: /ip6/<ip>/udp/<port>/p2p/<id>, or an ENR whose only address is ip6 and whose only port is udp. This is the rule the parser already applies to a discv5 contact with a non-secp256k1 key: nothing could use the entry. An IPv6 entry with a QUIC or TCP port is kept, since the swarm dials it, not the discovery socket. Test: parse_bootnode_refuses_an_ip6_discv5_contact, which checks both sides. The network's own list keeps its lenient rule, as on main. Such a record there is a seed that never answers. docs/cli.md, docs/discovery.md and CLAUDE.md say so.
  • Grok 1, Claude 8, the file hint.
    • It now says to pass the records themselves, without a YAML list's - markers or comments, and that a directory network can list them in its bootstrap_nodes.yaml instead. Joining the lines as they are would have failed again as an invalid ENR, without the hint.
    • A missing path ending in .yaml, .yml or .txt now gets the hint too, rather than a decoding error.
    • Tests: a_bootnode_file_on_beacon_is_refused_with_a_hint checks the marker advice, and the new a_missing_bootnode_file_on_beacon_gets_the_same_hint passes a missing absolute path and a missing relative one.
  • Claude 9, the clap-side test. Round one made only the "" half independent of how many empty entries clap leaves. The trailing-comma half still pinned ["enr:a", ""]. It now checks that enr:a comes first and that anything after it is empty.
  • Grok 3, Claude 5, the published seeds cannot be turned off. docs/cli.md now says so next to the "never replacing" note: each dialable network bootnode is dialed at startup and redialed 12 s after every failed dial or disconnect. To run on other bootnodes alone, load the network from a directory whose bootstrap_nodes.yaml lists only those.

Not changed

  • Claude 2, duplicate dial addresses. merge_bootnode_dial_addrs pushes an address only when the peer's list does not hold it yet (crates/net/p2p/src/lib.rs:2807), and one bootnode yields at most one QUIC and one TCP address. A repeated multiaddr, or a typed ENR the network also lists, therefore adds nothing.
  • Claude 3, one node id seeded twice. ethrex's do_new_contacts (v25.0.0, peer_table.rs) keeps the first contact for a node id; a later one only adds a protocol. insert_to_connection_pool also returns early on a known id. beacon_bootnodes puts the command line's entries first, so the typed entry is the one kept.
  • Claude 4, ENR signatures. parse_enr checks no signature on any path: network lists, node's file, or the command line. Checking them is a change to all three, not to this PR.
  • Claude 6, String errors. Kept, the same as parse_enr. The tests match the text an operator reads.
  • Claude 7, trimming twice. beacon_bootnodes trims because its own checks read the entry (the -- check, the file hint, the error text), and parse_bootnode trims because it is public.
  • Grok 1, keeping {reason} in the hint. The hint runs only after both parsers failed on a path, so the reason is a decoding error that adds nothing to it.
  • Grok 2, the bare-UDP key check.
    • With a udp port present, as_discovery_node returns None only when the key is not secp256k1 (self.udp_port?, then try_into_secp256k1().ok()?, lib.rs:2458-2465).
    • A peer id that does not round-trip still dials the right peer. The bootnode is keyed by the key the id embeds, and the remote presents the canonical id of that same key, which is the id the dial uses.
  • Grok nit, two warnings for a lean file with no usable ENR. Deliberate since round one. The first says that list's entries were all unusable; the second says the node starts with no bootnodes.

Gemini, Codex and Kimi found nothing to change. DeepSeek's job returned an empty response.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

AI security review: 1 finding(s) to check

Reviewed by Opus, GPT, Kimi, GLM, DeepSeek. A judge model checked every one of the findings against the code.

# Finding Severity Status Found by Where
M1 Kurtosis still launches beacon with the removed bootnode file interface (also M2, M3) low Suspected Opus, GPT, GLM (3/5) .github/workflows/kurtosis_assertoor.yml:35
Details

M1. Kurtosis still launches beacon with the removed bootnode file interface (low, logic)

  • Trigger: After this PR merges, the Kurtosis Assertoor workflow runs on push to main and fetches the launcher pinned at 67cb0e02; that launcher starts the ethlambda beacon participant using the old --bootnodes file-path form.
  • Mechanism: The new BeaconOptions.bootnodes is a Vec<String> parsed as ENR/multiaddr entries. beacon_bootnodes sends each entry to parse_bootnode, and a path ending in .txt is deliberately reported as a file-path startup error. The workflow was not updated to a launcher that passes the records directly, so the pinned launcher’s file path can no longer start the beacon node.
  • Impact: The Assertoor devnet fails during client startup on main, so the integration workflow is broken until the ethereum-package pin is bumped to the compatible launcher.
  • Judge: The workflow retains the stated pin, and passing a bootnode file now aborts beacon startup. However, the pinned external launcher's source is absent, so its actual arguments—and therefore the claimed CI failure—cannot be confirmed. The test comment supports the report but does not verify that revision.
Duplicates folded into another finding: 2
# Same as Finding Found by Where
M2 M1 Update the pinned Kurtosis launcher alongside the CLI change GPT bin/ethlambda/src/main.rs:1137
M3 M1 Merging breaks the pinned kurtosis/assertoor launcher, which still passes beacon --bootnodes ‹file› Opus bin/ethlambda/src/main.rs:1151

Cost of this review: ~$3.36 of a $30 budget (estimated from token counts).

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

Round three (the review of b867a34). Nothing changed in this round.

Not changed

  • M1 (with M2 and M3), the kurtosis launcher. Confirmed. At the pinned commit, 67cb0e02, lambdaclass/ethereum-package's src/cl/ethlambda/ethlambda_launcher.star writes the bootnodes to /tmp/ethlambda-bootnodes.txt and passes --bootnodes=<that path>, which beacon now refuses at startup. The PR description lists this under "Breaking: kurtosis launcher". The launcher fix exists: 1aec42f3fd on the fork's add-ethlambda branch passes the list instead. I left the pin bump for a follow-up, Bump the kurtosis battery's ethereum-package pin to a launcher that passes beacon --bootnodes as a list #850.
    • On a pull request, kurtosis_assertoor.yml tests ghcr.io/lambdaclass/ethlambda:unstable, which is main's image.
    • So if this PR bumped the pin, the run it triggers would give the new launcher a binary that still reads a file, and fail.
    • Bumped right after this merges, the run tests a binary that takes the list.
  • IPv6 dialing, from round two. docs/cli.md says an IPv6 QUIC or TCP entry is dialed even though the swarm listens on 0.0.0.0, and I have now checked that against the libp2p fork (lambdaclass/rust-libp2p 2f14d0ec).
    • QUIC: with no IPv6 listener, a dial uses a per-family dialer endpoint bound to [::]:0 (transports/quic/src/transport.rs, dial and bound_socket).
    • TCP: each dial opens a socket of the address's own family, and port reuse binds it only to a listener of that family (transports/tcp/src/lib.rs, dial and local_dial_addr).

make fmt and make lint were not run, since nothing changed.

@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

The review loop stops here: the last round raised nothing left to address. Its one finding, the kurtosis launcher pin, is a follow-up that only works once this PR is on main: #850.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant