feat: implement gloas builder api - #9832
Merged
Merged
Conversation
Contributor
Performance Report✔️ no performance regression detected Full benchmark results
|
tomekmb-glitch
approved these changes
Aug 15, 2026
This reverts commit adc7843.
github-project-automation
Bot
moved this from In Progress
to Done
in Lodestar Team Coordination
Member
|
🎉 This PR is included in v1.47.0 🎉 |
nflaig
pushed a commit
that referenced
this pull request
Sep 9, 2026
## Motivation The Builder readiness, genesis polling, identity, and cancellation paths still lacked focused regression coverage after the initial Builder implementation. This PR adds that coverage without changing runtime behavior. ## Changes - Cover syncing, EL-offline, non-ok, unreachable, optimistic, and eventual-ready transitions. - Prove cancellation during readiness and genesis polling stops further requests and timers. - Keep node-version lookup failure non-fatal. - Cover expected not-found genesis responses and unexpected genesis failures without noisy stack traces. - Distinguish an empty successful Builder lookup, a non-active Builder status, and a failed beacon node response. - Preserve useful typed API error detail on status lookup failure. - Cover cancellation while waiting for an unknown Builder to appear. - Extend the Builder API stub with `getGenesis` and `getNodeVersionV2`. This is a test-only change. It does not alter polling intervals, logs, API contracts, public exports, or Builder runtime behavior. Historical validation base: `f22c5ce63e`, including merged #9832 and #9964. Reviewed head on 2026-09-07: `9898d54ca9` (source unchanged in this pass). Project issue: [krisoshea-eth#45](krisoshea-eth#45). ## Testing Previously recorded validation with Node 24.13.0 and pnpm 11.0.0: - 29 focused readiness, genesis, and identity tests - all 40 Builder unit tests - 8 existing Builder CLI and fee-recipient parser tests - Builder package type-check - Builder package lint - `git diff --check` The Builder coverage comprises 7 readiness tests, 3 genesis tests, 19 identity tests, 5 `BuilderStatusTracker` tests, and 6 signer tests. Existing CLI tests continue to cover zero fee-recipient and unscheduled Gloas validation. Earlier CI results belong to their recorded heads. See the Checks tab for runs on the current head; absent runs or runs awaiting approval must not be treated as passing. This review did not refresh the branch from `unstable`.
nflaig
pushed a commit
that referenced
this pull request
Sep 10, 2026
## Motivation The Lodestar Builder needs a source beacon node API path for learning whether its bid was selected without joining libp2p. This PR implements the standard `block` SSE topic plus `getBlockV2` as a bounded compatibility path. Beacon APIs #630 and merged Lodestar #9832 also forward the signed winning block directly to the selected external Builder. The main purpose of that flow is to let the Builder help disseminate the block, with timely win notification as an additional benefit. Maintainer input is requested on whether this observer should remain as a compatibility fallback alongside direct delivery. ## Changes - Subscribe only to the standard `block` SSE topic. - Deduplicate roots before asynchronous work and retain a FIFO window of 256 roots. - Skip locally pre-Gloas slots and retrieve each new post-Gloas block by root with `getBlockV2`. - Use the Builder abort signal for both the SSE stream and block requests. - Retry 404, server, timeout, and non-input transport failures for up to six attempts with five 200 ms delays. Other 4xx responses, cancellation, decoding failures, input fetch errors, and structural failures are terminal. - Treat response version metadata as fork authority, require a Gloas-compatible body, and verify the returned slot against the event. - Preserve the exact signed bid, including later-fork fields, exact-width values, and `BUILDER_INDEX_SELF_BUILD`. - Dispatch observations concurrently through isolated `runOnBlock` callbacks. The existing API-client request timeout is unchanged. This PR bounds attempts and explicit retry delays, not total wall-clock or slot-relative time. Selection and reveal code will own deadline policy. The observer starts after the existing genesis, configuration, readiness, Gloas, and Builder identity gates. It joins the clock and `BuilderStatusTracker` as a long-lived Builder background service and shares their abort controller. This PR does not add p2p, `block_gossip`, canonical-chain filtering, local-bid matching, reveal behavior, metrics, reconnect, replay, restart recovery, multi-BN failover, or a new API endpoint. The observer intentionally evaluates blocks before SELECT-01 registers its first production consumer so this compatibility path remains active and evidenced. Event-time `executionOptimistic` comes from the triggering event, while the response metadata is authoritative for the fork. Terminally failed roots remain consumed until FIFO eviction; REL-01 owns controlled reconciliation. Aggregate retrieval concurrency, observer-specific metrics, and block-root recomputation before financial decisions are tracked in SEC-01, QA-01, and SELECT-01 respectively. ## API behavior and compatibility The standard `block` event contains the slot, beacon block root, and execution optimism. `getBlockV2` supplies the signed fork-correct block and `Eth-Consensus-Version` metadata. Imported non-head blocks remain valid observations, so `head` and `head_v2` are not substitutes. Lodestar emits `block` after state transition and fork-choice import. Root lookup checks fork choice for presence, then serves the block from the seen-block input cache or database. This ordering provides no expected Lodestar event-before-block window, but the Beacon API does not require equivalent ordering across clients, so bounded 404 retry remains a cross-client precaution. The implementation audit is recorded in merged [Builder docs PR #13](krisoshea-eth/lodestar-eip-7732-builder-docs#13). The provisional direct-Engine planning reconciliation is recorded in merged [Builder docs PR #18](krisoshea-eth/lodestar-eip-7732-builder-docs#18), the reproducible real-BN and shutdown evidence in merged [Builder docs PR #19](krisoshea-eth/lodestar-eip-7732-builder-docs#19), and the recent upstream PR audit in merged [Builder docs PR #20](krisoshea-eth/lodestar-eip-7732-builder-docs#20). Implementation evidence was posted to [beacon-APIs #599](ethereum/beacon-APIs#599 (comment)). Marco's open Lodestar PoCs [#9854](#9854), [#9875](#9875), [#9876](#9876), and [#9896](#9896) explore optional event improvements separately. The API-02 diff is limited to five Builder files. The latest review fixes build on Nico's updated branch at `09ea035863a5712eb417949f71e31c9d0f97f0fb`; no additional `unstable` merge was made for these fixes. Historical validation base: `f22c5ce63e`. Historical specification baseline: consensus-specs `v1.7.0-alpha.14`. Project issue: [krisoshea-eth#12](krisoshea-eth#12). ## Testing Validated locally on 2026-09-10 at `d74cf21de82d8ef4a8ad4b65627d2df131b42a16`, with Node 24.13.0 and pnpm 11.0.0: - 58 targeted tests across the observer, Builder lifecycle, identity, readiness and payload store. - Ordinary Builder package type-check. - Changed-file Biome. - Builder package build and module import check. - `git diff --check`. Dependencies were installed from this branch's lockfile and the Builder dependency packages were rebuilt in an isolated checkout. The new startup-log and warning regressions failed before the source changes and passed afterward. Coverage includes SSE wiring, cancellation, Gloas and Heze output, signed-bid preservation, slot consistency, duplicate suppression, bounded retry, decoding failures, FIFO eviction, self-builds, stream failures and callback isolation. These are local results, not a fresh CI or real-BN/EL run. The earlier real-BN and shutdown evidence remains in Builder docs PR #19. ## AI assistance disclosure - [x] External Contributors: I have read the contributor guidelines and disclosed my usage of AI below. > AI assistance was used for codebase research, implementation, testing, and review. I reviewed and revised the submitted code and PR text, made manual edits and technical decisions, and take responsibility for the final result.
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 13, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
Minhal128
pushed a commit
to Minhal128/lodestar
that referenced
this pull request
Sep 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implement the Gloas builder API flow end to end so validators can source execution payload bids directly from builders post-ePBS, as specified in:
Builder configuration is owned by the validator client, the beacon node requests and validates bids on its behalf and ranks builder api and p2p bids uniformly during selection.
produceBlockV4is now aPOSTwith a requiredBuilderConfigbody, one bid request per builder entry plus top-levelmin_bidandbuilder_boost_factorgoverning p2p bidsBuilderRequestAuthfor each proposal-slot/auth-data pair ahead of time; bid requests authenticate with the data agreed with the builder, defaulting to the UTF-8 bytes of the builder URLgetExecutionPayloadBidrequests with a fixed 500ms deadline, validates bids against proposer preferences and the entry config with the execution payment counted up to the configured cap, and ranks bids by their boosted counted total. The p2p bid is selected after the same deadline so bids received over gossip have time to bid upEth-Builder-Urlto the winning builder so it can help disseminate the block and promptly learn that its bid won; only previously authenticated builder clients are eligible and redirects are disabledsubmitBuilderPreferencesbeacon api/eth/v1/validator/{pubkey}/builder_configendpoints allow per-key configuration with per-builder overrides--builder.urls(auth data can be appended as a hex fragment),--builder.minBidand--builder.maxExecutionPayment, configuring a max execution payment above0requires the explicit--allowDangerousTrustedPaymentsopt-in as trusted payments are only backed by the builder's promise to paylodestar_builder_api_*metricsThe beacon and builder openapi spec tests still ignore the new endpoints until builder-specs and beacon-APIs cut a release, keymanager is already checked against
v1.2.0-alpha.0.Closes #6242
Closes #6602
Closes #9298
Closes #9918