Skip to content

feat(beacon): select the preset at runtime from PRESET_BASE - #851

Open
MegaRedHand wants to merge 2 commits into
mainfrom
feat/runtime-preset
Open

MegaRedHand wants to merge 2 commits into
mainfrom
feat/runtime-preset

Conversation

@MegaRedHand

Copy link
Copy Markdown
Collaborator

🗒️ Description / Motivation

ethlambda could only run the mainnet preset: every SSZ container bound was a { preset::X } const generic, and the preset-minimal feature that switched them never reached the binary. ethereum-package therefore refused ethlambda on preset: minimal devnets, and the only alternatives were a second -minimal image (Prysm/Nimbus/Grandine style) or shipping two binaries.

This makes the preset a runtime choice, the way Lighthouse and Teku pick theirs: one binary and one image run mainnet and a minimal-preset network alike.

  • ethlambda beacon selects the preset its network's config.yaml names in PRESET_BASE, while resolving --network and before anything is decoded against it.
  • ethlambda validator and voluntary-exit adopt the preset their beacon node reports in /eth/v1/config/spec.

What Changed

  • The active preset (beacon::preset). Preset::select stores it in a process-wide atomic. The first read freezes it, so a later select of the other preset fails instead of mixing container shapes, and a startup path that reads a preset value before selecting one fails loudly.
  • Values both presets share stay constants (preset::MAX_ATTESTATIONS, ...), each compile-asserted equal in mainnet and minimal. If a spec release ever moves one, the build breaks there.
  • The 29 values the presets disagree on are functions: preset::slots_per_epoch() is SLOTS_PER_EPOCH. preset::mainnet::* and preset::minimal::* keep every literal.
  • Containers bounded by a differing value take a Length marker type (preset::SyncCommitteeSize, ...) instead of a const generic:
    • beacon::preset_sized::{PresetList, PresetVector, PresetBitlist, PresetBitvector}: libssz's four collections with N read at runtime. Same encoding and merkleization, and inline bitfield storage like libssz's.
    • ethlambda_ssz_tree::{ListOf, VectorOf}: ssz-tree's persistent trees take a Length. List<T, N> and Vector<T, N> stay as aliases over Const<N>, so existing users are untouched.
  • Anything computed from a differing value is now a function too, since a const context cannot read the preset (max_aggregates_per_slot(), sync_subcommittee_size(), ...). This is a mechanical rename across about 100 files.
  • Startup. select_preset (in bin/ethlambda/src/network) replaces check_preset, and adopt_preset is added to the validator crate. Both the beacon node and the validator client log the preset they run.
  • /eth/v1/config/spec reports the active preset's values.
  • Storage. The data directory's preset byte is checked against the selected preset; the error text now points at reusing a directory across networks.
  • Spec tests. The spec-test binary selects its preset from BEACON_SPEC_PRESET, so make test-beacon-minimal runs off the same build as mainnet. CI's minimal job and the cache key are updated to match.
  • The preset-minimal feature now only sets Preset::DEFAULT, the preset of a process that never selects one (unit tests). The binary never enables it.
  • Docs. CLAUDE.md, docs/beacon_stf.md, docs/cli.md, docs/data_storage.md and docs/rpc.md no longer describe the preset as compile-time.

Correctness / Behavior Guarantees

  • Mainnet behavior is unchanged. Every built-in network declares PRESET_BASE: mainnet, and the mainnet spec suite passes as before.
  • A missing or unknown PRESET_BASE is a hard startup error. That includes gnosis, whose values are not carried.
  • Container shapes are only ever read under one preset per process. ssz-tree computes its bounds at construction, so there is no per-access cost there.

Tests Added / Run

  • Added crates/common/types/tests/runtime_preset.rs, an integration test binary that selects minimal at runtime and checks container shapes. Also added preset_sized unit tests comparing each type against its libssz counterpart, plus tests of the select/freeze rule.
  • make fmt and make lint: clean.
  • make test-beacon-mainnet: 7,493 fixture cases passed, 0 failed.
  • make test-beacon-minimal: 49,577 fixture cases passed, 0 failed, the preset selected at runtime from the same build. That includes 43,297 ssz_static cases, which check every container's encoding and root under minimal. Re-run after merging main.
  • make test: not run locally; CI runs it. The new tests and the machine-edited test files have not been executed yet.
  • Local Kurtosis devnet on preset: minimal. Four pairs: lighthouse BN + lighthouse VC, ethlambda BN + ethlambda VC, lighthouse BN + ethlambda VC, ethlambda BN + lighthouse VC. Package: lambdaclass/ethereum-package branch ethlambda-minimal-preset.
    • /eth/v1/config/spec matches lighthouse's on all 190 shared keys.
    • Every slot through 143 has a block, and every client pair proposed.
    • Finality is one epoch behind, which is normal.
    • Sync-committee participation is 99–100% across the first period change.
    • Assertoor: stability, block proposals and sync checks all pass. No errors in any ethlambda log.
    • An earlier run also stopped one ethlambda node for 80 slots. It resumed its data directory and rejoined lighthouse's head in about 20 s.
  • Not exercised live under minimal: gloas (spec suites only), checkpoint sync, the builder flow. Performance was not measured.

Related Issues / PRs

✅ Verification Checklist

  • Ran make fmt — clean
  • Ran make lint (clippy with -D warnings) — clean
  • Ran make test (test-consensus plus test-node, at release-fast) — all passing

One binary now runs mainnet and minimal-preset networks alike, the way
Lighthouse and Teku do, so ethereum-package can run ethlambda on a minimal
devnet from the same image.

- `ethlambda beacon` selects its network's PRESET_BASE while resolving
  --network, before anything is decoded; the validator client and
  voluntary-exit adopt the preset their beacon node reports. The choice is
  process-wide and frozen by its first read.
- Preset values both presets share stay constants, compile-asserted equal;
  the 29 they disagree on are accessor functions (`preset::slots_per_epoch()`).
- Containers bounded by a differing value take a `Length` marker:
  `preset_sized::{PresetList, PresetVector, PresetBitlist, PresetBitvector}`
  and ssz-tree's new `ListOf`/`VectorOf` (`List`/`Vector` are aliases over
  `Const<N>`).
- /eth/v1/config/spec reports the active preset's values.
- The spec-test binary selects its preset from BEACON_SPEC_PRESET, so both
  suites run off one build; `preset-minimal` now only sets the default of a
  process that never selects one (unit tests).
…-catmull

# Conflicts:
#	crates/blockchain/state_transition/src/beacon/helpers/gloas.rs
#	crates/common/ssz-tree/src/lib.rs
#	crates/storage/src/beacon_state_delta.rs
@MegaRedHand

Copy link
Copy Markdown
Collaborator Author

/review

@github-actions

Copy link
Copy Markdown

AI security review: 0 finding(s) to check

Reviewed by Opus, GPT, Kimi, GLM, DeepSeek. A judge model checked every one of the findings against the code.
Malicious-code check (tests, build and install scripts, hooks, editor tasks, dependency sources): nothing found.

No findings to check.

Pre-existing (real, but already on the base branch): 2
# Finding Category Severity (reported → judged) Found by Where Judge's reason
M1 Minimal preset breaks era replay’s fixed 8192-slot boundaries logic low DeepSeek, GLM (2/5) bin/ethlambda/src/era/replay.rs:36 Confirmed: minimal selects 64 slots, so an 8192-entry era index fails validation, and check_replayable uses incorrect boundaries. However, base already defined SLOTS_PER_ERA from the preset's SLOTS_PER_HISTORICAL_ROOT and supported minimal-feature builds that accepted minimal directories. Runtime selection exposes the existing problem in the default binary.
M2 A minimal-preset network's config.yaml falls back to mainnet values for missing keys on the beacon node, but to minimal consensus/state low Opus (1/5) crates/common/types/src/beacon/config.rs:635 The beacon's mainnet fallback for omitted shard-period/churn keys is real, but base used the identical parser/default and accepted minimal directories when compiled with preset-minimal; it did not reject every minimal network. The validator now has preset-specific defaults, but its own node emits all config fields and the client overrides SHARD_COMMITTEE_PERIOD, so no new operational self-disagree
Housekeeping (not security): 10

Stale docs, missing tests, leftovers and inconsistencies, from a separate cheap model. Not checked by the judge.

Kind Item Where Fix
stale-docs beacon_aggregates.rs doc comment references aggregate::MAX_AGGREGATES_PER_SLOT crates/blockchain/src/beacon_aggregates.rs:29 Change to [aggregate::max_aggregates_per_slot](ethlambda_state_transition::beacon::aggregate::max_aggregates_per_slot).
stale-docs aggregate.rs doc comment references MAX_AGGREGATES_PER_SLOT as a constant crates/blockchain/state_transition/src/beacon/aggregate.rs:12 Change [MAX_AGGREGATES_PER_SLOT] to [max_aggregates_per_slot].
stale-docs helpers/fulu.rs doc comment references preset::PROPOSER_LOOKAHEAD_LENGTH crates/blockchain/state_transition/src/beacon/helpers/fulu.rs:207 Change [preset::PROPOSER_LOOKAHEAD_LENGTH] to [preset::proposer_lookahead_length()].
stale-docs helpers/gloas.rs doc comment references preset::PTC_SIZE crates/blockchain/state_transition/src/beacon/helpers/gloas.rs:496 Change [preset::PTC_SIZE] to [preset::ptc_size()].
stale-docs altair.rs process_sync_aggregate doc references preset::SYNC_COMMITTEE_SIZE and preset::SLOTS_PER_EPOCH crates/blockchain/state_transition/src/beacon/stf/altair.rs:322 Change to [preset::sync_committee_size()] and [preset::slots_per_epoch()].
stale-docs stf/capella.rs doc comment references preset::MAX_VALIDATORS_PER_WITHDRAWALS_SWEEP and preset::MAX_WITHDRAWALS_PER_PAYLO crates/blockchain/state_transition/src/beacon/stf/capella.rs:129 Change to [preset::max_validators_per_withdrawals_sweep()] and [preset::max_withdrawals_per_payload()].
stale-docs stf/epoch/altair.rs doc comment references preset::EPOCHS_PER_SYNC_COMMITTEE_PERIOD crates/blockchain/state_transition/src/beacon/stf/epoch/altair.rs:413 Change [preset::EPOCHS_PER_SYNC_COMMITTEE_PERIOD] to [preset::epochs_per_sync_committee_period()].
stale-docs stf/epoch/fulu.rs doc comment references preset::PROPOSER_LOOKAHEAD_LENGTH crates/blockchain/state_transition/src/beacon/stf/epoch/fulu.rs:141 Change [preset::PROPOSER_LOOKAHEAD_LENGTH] to [preset::proposer_lookahead_length()].
stale-docs upgrade.rs doc comment references preset::PTC_SIZE crates/blockchain/state_transition/src/beacon/upgrade.rs:823 Change [preset::PTC_SIZE] to [preset::ptc_size()].
stale-docs p2p lib.rs doc comment references MAX_AGGREGATES_PER_SLOT crates/net/p2p/src/lib.rs:320 Change [MAX_AGGREGATES_PER_SLOT] to [max_aggregates_per_slot].
Leads from a script (not checked): 1

Found without a model, from the lines this PR adds. Some can be wrong, e.g. a path created at runtime or a name used through reflection.

  • ssz-types/src/hash_tree_root.rs does not exist in the repository (referenced at crates/common/types/src/beacon/preset_sized.rs:18)

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

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