Repository navigation
feat(validator): propose builder blocks (fulu) - #705
Conversation
🤖 Kimi Code ReviewI'll review this PR for the builder proposals feature in ethlambda. This is a substantial change adding MEV-Boost style builder block proposals to the validator client. Security & CorrectnessCritical: Blinded block publish isolation is correct but fragile
Critical:
|
🤖 Codex Code ReviewLooks good overall. The validator-side builder flow is careful about proposer-safety: the slot is recorded at signing time, blinded publishes are isolated onto a background task, and the timeout path no longer misclassifies a slow relay as a missed proposal.
Minor nits only:
If you want, I can also do a second pass on the beacon-node / RPC-side builder changes from the same PR for spec conformance and edge cases. Automated review by OpenAI Codex · gpt-5.4 · custom prompt |
🤖 Claude Code ReviewReview of PR 705 (validator client: builder proposals and blinded publish)I read the diff through the end of the HTTP client changes, including the CLI flags, the fallback node, The design is sound. The main safety properties hold:
Minor points and questions
Tests. Coverage is good. It includes status mapping, the connect-failure case, fallback routing and no-failover, a registration JSON round trip, and end-to-end tests against the real router with a mock relay. Moving the builder test world into Overall: LGTM on what I read. The points above are minor, with Point 1 the most worth a doc tweak. Automated review by Claude (Anthropic) · sonnet · custom prompt |
1b1125c to
a940907
Compare
a940907 to
353fb90
Compare
Registrations and builder bids are signed under builder-specs' DOMAIN_APPLICATION_BUILDER, an application domain outside the specification's own. The mask's doc said this crate never uses one; it now does, so the doc names it.
A blinded block carries the header of a payload this node never sees, and blinding a locally built block needs the same conversion. The header also needs Deserialize now, since bids and blinded blocks arrive as JSON.
Real encodings to decode against, so the builder containers are checked against what relays and other clients send rather than only against themselves.
Only the bid is a response; the registrations and the blinded block are request bodies, and the `value` key is OpenAPI's example wrapper. Record the full commit, since nothing else in the repo pins it. The header's JSON round trip moves beside the other round-trip tests.
The builder API's domain and gloas's in-protocol builder domain share a name and nothing else. Copying an existing get_domain call for the builder API would sign under the wrong one, and the only symptom is a relay rejecting every signature.
What a validator client signs and its beacon node forwards to relays through registerValidator, checked against builder-specs' example in both encodings.
The signed offer getHeader returns: a payload header, the blob commitments and execution requests that go into the body with it, and the value paid to the proposer.
The block a validator signs when a relay supplies the payload. Its root equals the full block's because a payload header's root is the payload's, which is what lets one signature serve both; the tests pin that, and builder-specs' example pins the encoding.
The root-equality test used a mostly empty body, and empty lists with the same limit share a root, so swapping two of them still passed under the minimal preset. Build it from the fully populated JSON test block instead. The example tests now also check the JSON this node would send a relay, not only the JSON it reads.
Registrations and bids are signed over their own roots, relays reject an older registration rather than requiring an unchanged one, and from_parts copies a state root its caller must recompute.
A blinded block needs the same body, framing and process_block run as a full one, then patches the post-state before taking its root. No behavior change.
The state transition takes full payloads only. Rather than thread a payload abstraction through it, run it on a stand-in payload built from the builder's header and patch the two post-state fields that depend on the payload itself. Safe because fulu, the last fork with blinded blocks, is final; the guard test fails on any drift.
The stand-in payload is what makes process_block's parent hash, prev_randao, timestamp and blob checks apply to a builder's header, and only if it copies the right fields. One test per check, plus the withdrawals root and the fork gate, which this path checks itself.
Both block paths pass a constant execution engine, so on the blinded path no one checks the builder's header beyond the fields the stand-in copies. That is right for the state root but easy to mistake for bid validation, so the doc now says the caller owns the rest.
The guard's state had no withdrawal due and its body no execution request, so the withdrawals root was only ever checked against the empty list and the "identical" rows of the doc's table were argued rather than tested. Six payload fields the stand-in leaves empty were empty in the test payload too.
They were single lines past the width the rest of the file wraps at.
The stand-in-and-patch approach is unusual (every other client threads a payload abstraction through its STF), so the next person to touch fulu's process_block should find the reason before the guard test does.
fulu_state's doc named a field it deliberately does not cover and a step that has since been written. assemble_blinded_block's list of what the caller must still check was short, and A2 codes against it. The rest are small accuracy fixes found reviewing the branch whole.
Registrations and bids are signed under DOMAIN_APPLICATION_BUILDER at the genesis fork version and a zero validators root, the way deposits are. The known-answer test pins mainnet's value, so a call that used get_domain's current fork and real validators root instead would fail here rather than at every relay.
🤖 Claude Code ReviewPR 705 review: validator-client builder proposals (blinded blocks and registrations)This is a careful, well-tested PR. The core safety properties hold:
Most of what follows is verification items and design nits rather than bugs. Correctness / things to verify
Design / API
Robustness
Nits
Overall: approve once item 1 is confirmed. The rest are optional follow-ups. Automated review by Claude · claude-opus-5-5 · custom prompt |
🤖 Gemini Code ReviewThis PR is well-designed and thoroughly tested. The implementation of builder proposals and validator registrations in the validator client handles the subtle edge cases cleanly:
LGTM! Automated review by Gemini · gemini-4-argon · custom prompt |
🤖 DeepSeek Code ReviewThe PR is well-structured and heavily tested; the design around
No consensus-layer correctness issues were found in this PR; the changes are confined to the validator client and its interaction with builder APIs. Automated review by DeepSeek · deepseek-v4-pro · custom prompt |
🤖 Grok Code ReviewThe builder-proposal path is carefully built: blinded blocks stay on the producing node, the slot is recorded before signing, and a blinded answer is refused before that record when proposals are off. A few gaps are still worth fixing.
Minor: an ethlambda node applies fee recipients in arrival order, ignoring timestamps. The Log sanitization in Automated review by Grok (xAI) · grok-4.7 · custom prompt |
🤖 Kimi Code ReviewNo blocking findings. The security-sensitive paths look carefully handled:
The remaining trade-offs—heuristic 5xx classification, stale registration possibilities after partial fan-out, and documented reporting edges for dropped or panicked publish tasks—are explicit and do not introduce slashing risk. The accompanying documentation and test coverage are notably thorough. Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt |
Claude (seventh review): a registration newer_than signs more than ten seconds ahead of the clock (after a backward clock step) makes the flashbots relay refuse its whole batch until the clock catches up, and nothing said so. It is now warned at signing, naming the key, the timestamp and the clock. Also notes in one_line that an escape's char count is its byte count, since escape_default writes ASCII only (DeepSeek; Grok in the sixth review).
|
/review |
🤖 Claude Code ReviewReview: PR 705 — validator client builder proposals (blinded blocks and registrations)This is a carefully built PR. The core consensus-safety properties are correct:
The items below are mostly things to verify or minor improvements. Correctness
HTTP / error handling
Performance
Readability
Overall this looks good to merge, once Item 1 is confirmed. Automated review by Claude · claude-opus-5-5 · custom prompt |
🤖 Codex Code ReviewNo actionable findings in the reviewed diff. Blinded-block signing preserves slashing protection, publication stays pinned to the producing node, and registration failures remain isolated from validator duties. Tests could not run: the pinned Rust toolchain was unavailable, and the installed toolchain’s offline run lacked the Automated review by OpenAI Codex · gpt-6.1-sol · custom prompt |
🤖 Gemini Code ReviewThis PR looks great. The builder proposal and validator registration flows are well-designed and thoroughly tested:
No issues found — LGTM! Automated review by Gemini · gemini-4-argon · custom prompt |
🤖 Grok Code ReviewThe builder-proposal path is carefully structured. I am checking a few consensus-sensitive spots in the existing code before concluding. Automated review by Grok (xAI) · grok-4.7 · custom prompt |
🤖 DeepSeek Code ReviewAutomated review by DeepSeek |
🤖 Kimi Code ReviewNo blocking issues found in the normal One non-blocking API correctness issue:
Automated review by Kimi (Moonshot AI) · kimi-k3.1-pro · custom prompt |
Kimi (eighth review), Claude (seventh): the fallback hands its node Producer::default(), so a fallback of fallbacks would send every blinded block to its inner list's first node. The doc now says so; the client builds one level only.
# Conflicts: # docs/cli.md
# Conflicts: # crates/net/rpc/src/beacon/builder_client/mod.rs # crates/net/rpc/src/beacon/builder_client/tests.rs # crates/net/rpc/src/beacon/proposal.rs # crates/net/rpc/src/beacon/validator_client_tests.rs # crates/validator/src/beacon_node/mod.rs # crates/validator/src/lib.rs # crates/validator/src/proposal.rs
Brings the validator client work that landed on main (durable EIP-3076 slashing protection #734, its import and export #736, the review follow-ups #789, voluntary exits #779, builder blocks #705 and proposer preferences #707) along with the builder PRs they stack on (#694, #695, #696, #704), the generated node key (#726) and #787, #793. Conflicts resolved by keeping both sides: the engine client's getBlobsV2 timeout next to main's one-attempt getPayload timeout, and their wire tests; nightly's batched block_signature_set next to main's verify_proposer_signature (the blinded block's check); gloas_proposal.rs importing both EventBus and the sync status.
…s limit in validator_definitions.yml (#780) The keymanager API's feerecipient, graffiti and gas_limit routes overrode one validator's settings in memory only, so a restart put every validator back on the command line's defaults. They are now written onto the validator's entry in validator_definitions.yml, in Lighthouse's layout (suggested_fee_recipient, graffiti, gas_limit), before memory changes, and seeded from the file at startup. A re-import keeps an entry's values, an import that enables a disabled entry loads and validates the values it carries, and keystore and password files are flushed before the entry that names them is saved. Resolved against main, which this PR predates (slashing protection #734, #736, #789 and the builder flow #705, #707): - The definitions file is saved through main's write_private_durably, which already flushes the file and its directory, so the PR's own rename plus sync_dir is dropped. The settings routes save through save_definitions, keeping definitions_unflushed accurate, and treat Error::Unflushed as written (memory follows the file, with a warning), as the PR's logged directory flush did. The import seeds the settings in both the Ok and the Unflushed arm and returns main's Overwritten. - write_private and write_private_no_symlink keep the PR's flush, the latter staying public for the node key. - Overrides keeps main's registered() next to the PR's apply(), so seeding and every route still bump the generation the builder registrations cache on. - A gas_limit of zero in the file is refused, as --gas-limit and POST gas_limit refuse it since #707 signs it into proposer preferences. - Main's newer tests build ValidatorDefinition with the three fields as None.
Fifth step of MEV-Boost builder support: the validator client side. With
--builder-proposals, the client registers its validators with the beacon node's builder and accepts a blinded block when the builder's bid wins. It signs the blinded block and publishes it back to the node that produced it. Stacked on #704.Scope:
produceBlockV4keeps its self-build configuration, and registrations stop at the gloas fork. The gloas builder API comes in phase B.Flags
--builder-proposalsbuilder_boost_factorwith every pre-gloas block request--builder-boost-factor <u64>100. Requires--builder-proposals--prefer-builder-proposalsu64::MAX, so the builder wins whenever there is a valid bid, unless the node's execution client setsshouldOverrideBuilder. Requires--builder-proposals; conflicts with--builder-boost-factorWithout
--builder-proposals, nothing changes: the client sendsbuilder_boost_factor=0and refuses a blinded answer, as before.What it adds
ValidatorRegistrationV1per validator the node resolved, signed under the builder domain (genesis fork version, zero validators root). The signature and timestamp are cached until the validator's fee recipient or gas limit changes, and a re-signed one is always newer than the last (max(now, last + 1)). The full set is sent after each epoch refresh and changed keys every slot, on spawned tasks with signing off the async runtime, in batches of 500 to every configured node, each node working through its own batches beside the others; a node that cannot be reached is sent no more batches that round. One send runs at a time, and each reads the cache only once the previous one was answered, so an older copy does not arrive after a newer one: a per-slot send that finds another running skips and a later slot sends the change, a full send waits for a per-slot one, and a full send that finds the last full one still running skips its epoch. A per-slot send no node accepts is sent again, as signed, every slot until a node takes it or the next full send ends the retry. Validators with no fee recipient are skipped with one warning, and a zero--suggested-fee-recipientis reported at error at startupProducedBlockgains a blinded variant. Its root is the full block's, so the signing path is unchanged, and its slot goes into the durable EIP-3076 slashing-protection record (#734) before it is signed, like a full block's. Slot and proposer are checked as for a full block. The fee-recipient check is skipped, since the header names the builder's addressPOST /eth/v2/beacon/blinded_blocks, SSZ, only on the node that produced the block, with no failover: only that node's builder holds the payload, and only that node claimed the slot. The produced block carries its producer (Producer, filled in by the fallback), and the proposal path sends the signed block back to that node. A blinded answer is refused before signing when builder proposals are off. The request runs on a spawned task, so the proposal budget cannot cut it offProposalService::propose_by, which returns aProposedoutcome: past the budget a signed blinded block comes back asStillPublishing, and whichever of the duty loop and the publish task ends up holding the outcome (decided by a oneshot channel) reports itethlambda_validator_builder_registrations_sent_total,..._builder_registration_failures_total,..._blinded_blocks_proposed_total,..._blinded_blocks_unconfirmed_totalKnown limitations
PATCHroute) are out of scope; the flags apply to the whole process.Tests
make lintpasses, as do the validator lib, rpc lib and binary tests.