Skip to content
Open
21 changes: 12 additions & 9 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<data-dir>/node.key`,
Expand All @@ -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
Expand Down Expand Up @@ -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/<ip>/<transport>/p2p/<peer-id>` multiaddrs (Lighthouse's `--boot-nodes`: `tcp/<port>` and `udp/<port>/quic-v1` are dialed, a bare `udp/<port>` 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

Expand Down
129 changes: 105 additions & 24 deletions bin/ethlambda/src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<PathBuf>,
/// 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<PathBuf>,
/// Base URL(s) of the peer API servers to take a checkpoint from, e.g.
/// `http://peer:5052`.
///
Expand Down Expand Up @@ -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/<ip>/<transport>/p2p/<peer-id>` 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/<peer-id>` 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<String>,

/// 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
Expand Down Expand Up @@ -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<PathBuf>,
/// Whether this node acts as a committee aggregator.
///
/// Seeds the initial value of the live aggregator flag shared by the
Expand Down Expand Up @@ -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.
Expand All @@ -901,24 +926,80 @@ mod tests {
args
}

/// The three flags that moved into [`CommonOptions`] are optional on both
/// sub-commands, so clap accepts an argv carrying none of them. What an
/// absent value *means* is each sub-command's own decision, made at
/// startup in `main`; the two tests after this one pin the answers that
/// are not simply "carry on with nothing".
/// The flags that moved into [`CommonOptions`] are optional on both
/// sub-commands, and so is each chain's own `--bootnodes`, so clap accepts
/// an argv carrying none of them. What an absent value *means* is each
/// sub-command's own decision, made at startup in `main`; the two tests
/// after this one pin the answers that are not simply "carry on with
/// nothing".
#[test]
fn the_shared_flags_are_optional_on_both_sub_commands() {
let node = parse_node(without(&without(&base_args(), "--node-key"), "--bootnodes"));
assert_eq!(node.common.node_key, None);
assert_eq!(node.common.bootnodes, None);
assert_eq!(node.lean.bootnodes, None);
assert!(node.common.checkpoint_sync_url.is_empty());

let beacon = parse_beacon(vec!["ethlambda", "beacon"]);
assert_eq!(beacon.common.node_key, None);
assert_eq!(beacon.common.bootnodes, None);
assert!(beacon.mainnet.bootnodes.is_empty());
assert!(beacon.common.checkpoint_sync_url.is_empty());
}

/// Commas split one occurrence and repeated occurrences add up, in order.
/// The trailing `--network` is the point: `allow_hyphen_values` must not
/// let a list swallow the flag after it.
#[test]
fn beacon_bootnodes_combines_commas_and_repeats_in_order() {
let mut args = beacon_args();
args.extend([
"--bootnodes",
"enr:a,/ip4/1.2.3.4/tcp/9000/p2p/b",
"--bootnodes",
"enr:c",
"--network",
"sepolia",
]);
let beacon = parse_beacon(args);
assert_eq!(
beacon.mainnet.bootnodes,
["enr:a", "/ip4/1.2.3.4/tcp/9000/p2p/b", "enr:c"]
);
assert_eq!(beacon.mainnet.network, "sepolia");
}

/// An ENR written without its `enr:` prefix can start with `-`, which clap
/// would read as a flag without `allow_hyphen_values`.
#[test]
fn beacon_bootnodes_accepts_a_prefixless_enr_starting_with_a_hyphen() {
let enr = "-IW4QGGifTt9ypyMtChDISUNX3z4z5iPdiEPOmBoILvnDuWIKbWVmKXxZERPnw0piQyaBNCENFEPoIi-vxsnsrBig9MBgmlkgnY0gmlwhH8AAAGEcXVpY4IjKYlzZWNwMjU2azGhAhMMnGF1rmIPQ9tWgqfkNmvsG-aIyc9EJU5JFo3Tegys";
let mut args = beacon_args();
args.extend(["--bootnodes", enr]);
assert_eq!(parse_beacon(args).mainnet.bootnodes, [enr]);
}

/// An empty value and a trailing comma parse, and refusing them is not
/// clap's job: any empty entry they leave is skipped at startup
/// (`main::beacon_bootnodes`). Neither assertion pins how many empty
/// entries clap leaves (none or one), since startup handles both.
#[test]
fn beacon_bootnodes_parses_an_empty_value_and_a_trailing_comma() {
let mut args = beacon_args();
args.extend(["--bootnodes", ""]);
assert!(
parse_beacon(args)
.mainnet
.bootnodes
.iter()
.all(String::is_empty)
);

let mut args = beacon_args();
args.extend(["--bootnodes", "enr:a,"]);
let bootnodes = parse_beacon(args).mainnet.bootnodes;
assert_eq!(bootnodes.first().map(String::as_str), Some("enr:a"));
assert!(bootnodes[1..].iter().all(String::is_empty), "{bootnodes:?}");
}

#[test]
fn beacon_needs_no_checkpoint_sync_url() {
// `--checkpoint-sync-url` was once `required = true` here, because the
Expand Down
2 changes: 2 additions & 0 deletions bin/ethlambda/src/command.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down
Loading
Loading