Skip to content

Gloas: external builder API (payload bid selection and block production) - #9757

Draft
ethDreamer wants to merge 13 commits into
sigp:unstablefrom
ethDreamer:gloas-builder-api
Draft

Gloas: external builder API (payload bid selection and block production)#9757
ethDreamer wants to merge 13 commits into
sigp:unstablefrom
ethDreamer:gloas-builder-api

Conversation

@ethDreamer

@ethDreamer ethDreamer commented Aug 6, 2026

Copy link
Copy Markdown
Member

Issue Addressed

Closes #9590.

Adds support for the Gloas (ePBS) external builder API: the flow by which a proposer solicits
execution payload bids from off-protocol builders, ranks them against its local build and
gossip-relayed bids, commits to a winner, and forwards the signed block to the winning builder so it
reveals the execution payload envelope.

Implements the relevant parts of:

  • beacon-APIs #630produceBlockV4, builder-preferences endpoint, Eth-Builder-Url
  • builder-specs #165getExecutionPayloadBid, submitBuilderPreferences, submitSignedBeaconBlock, request auth
  • consensus-specs Gloas p2p / state transition for ExecutionPayloadBid

Proposed Changes

A Gloas proposer now considers three payload sources — its local EL build, gossip bids, and bids
fetched directly from configured builders — selects the most profitable eligible one, and (for a
direct builder) forwards the signed block back for envelope reveal.

The branch is organized as a bottom-up, dependency-ordered stack of commits so it can be reviewed one
layer at a time:

  1. consensus/types — the builder request-auth signing domain
    (compute_domain(DOMAIN_REQUEST_AUTH)) for authenticating Gloas builder-API requests.
  2. builder_types — shared SSZ/JSON wire types (builder config & entries, proposer preferences,
    request auth, builder URL).
  3. eth2 — beacon-node HTTP client methods for produceBlockV4, submitting builder preferences,
    and the Eth-Builder-Url response/echo header.
  4. builder_client — the Gloas Builder API HTTP client and a stateless Builders service that
    fans getExecutionPayloadBid / submitBuilderPreferences / submitSignedBeaconBlock out across
    a proposer's configured builders. The pre-Gloas relay client is relocated here.
  5. execution_layer — adopt the relocated pre-Gloas client; drop dead error variants.
  6. beacon_chain (verification) — direct-builder bid verification and gossip-bid refinements,
    sharing the state-dependent consistency checks.
  7. beacon_chain (selection + production) — a unified BidCandidate /
    BidSource { Local, Gossip, Direct } model and select_payload_bid, wired into Gloas block
    production. All bid value math lives on BidCandidate, computed on demand: ranking is the trusted
    value scaled by builder_boost_factor, in wei, so the local EL block value compares directly and
    builder_boost_factor == u64::MAX ("always prefer") is a plain multiply. min_bid is a ranking
    tier — a below-floor bid wins when it's the only option (e.g. the local build failed) but loses to
    any floor-clearing candidate. Direct-bid BLS verification runs on a blocking thread (off the async
    executor), and gossip bids are re-validated against the production state at selection time so a bid
    that has gone stale since gossip verification can't win selection and then fail block processing.
  8. client — construct the Builders service (honoring --builder-user-agent /
    --builder-disable-ssz) and wire it into the chain.
  9. network — gossip validation and peer scoring for payload bids and proposer preferences.
  10. http_apiproduceBlockV4, POST /eth/v1/validator/builder_preferences, and the
    Eth-Builder-Url publish round-trip. The winning builder's URL travels back to the VC as a
    response header and is echoed on publish, so forwarding the signed block works even when the
    publishing beacon node isn't the one that produced it.
  11. validator_client (signing) — sign builder request-auth and preferences.
  12. validator_client (config) — builder configuration store + docs.
  13. validator_client (services) — the builder-preferences submission service and v4 block
    production / publish.

Additional Info

Best reviewed commit-by-commit: the commits form a bottom-up dependency layering (types → wire types
→ clients → beacon_chain → node / network / API → validator_client), each a coherent per-crate
change.

@ethDreamer
ethDreamer requested a review from jxs as a code owner August 6, 2026 02:03
@ethDreamer ethDreamer added ready-for-review The code is ready for review gloas labels Aug 6, 2026
@mergify

mergify Bot commented Aug 7, 2026

Copy link
Copy Markdown

Some required checks have failed. Could you please take a look @ethDreamer? 🙏

@mergify mergify Bot added waiting-on-author The reviewer has suggested changes and awaits thier implementation. ready-for-review The code is ready for review and removed ready-for-review The code is ready for review waiting-on-author The reviewer has suggested changes and awaits thier implementation. labels Aug 7, 2026
@eserilev

eserilev commented Aug 9, 2026

Copy link
Copy Markdown
Member

thanks for breaking it up into commits like this! im wondering if you would be willing to convert this into stacked PRs?

We did this here: #9764

I think it makes reviewing big PRs much easier and hopefully more maintainable for the author. Lmk what you think

Comment thread beacon_node/http_api/src/publish_blocks.rs
Comment thread book/src/gloas_builder_config.md Outdated
Comment thread beacon_node/http_api/src/validator/mod.rs
Comment thread beacon_node/beacon_chain/src/block_production/bid_selection.rs
Comment thread validator_client/builder_store/src/lib.rs Outdated
Comment thread beacon_node/builder_client/src/builders.rs Outdated
Comment thread beacon_node/beacon_chain/src/block_production/gloas.rs Outdated
@mergify

mergify Bot commented Aug 13, 2026

Copy link
Copy Markdown

This pull request has merge conflicts. Could you please resolve them @ethDreamer? 🙏

@mergify mergify Bot added waiting-on-author The reviewer has suggested changes and awaits thier implementation. and removed ready-for-review The code is ready for review labels Aug 13, 2026
@mergify mergify Bot added ready-for-review The code is ready for review and removed waiting-on-author The reviewer has suggested changes and awaits thier implementation. labels Aug 13, 2026
@ethDreamer
ethDreamer marked this pull request as draft August 13, 2026 20:15
@ethDreamer

Copy link
Copy Markdown
Member Author

This PR has been split into a 5-PR Mergify stack for review, merging bottom-up into unstable:

  1. Add builder API types, request-auth domain, and eth2 client methods (Gloas builder API 1/5) #9803 — builder API wire types, request-auth signing domain, and eth2 client methods
  2. Add Gloas Builder API client and adapt execution layer (Gloas builder API 2/5) #9804 — Gloas Builder API client (builder_client) and execution-layer adaptation
  3. Add Gloas bid selection, block production, and bid gossip processing (Gloas builder API 3/5) #9805 — beacon-chain bid selection, Gloas block production, and bid gossip processing
  4. Convert produceBlockV4 to POST and round-trip Eth-Builder-Url (Gloas builder API 4/5) #9806 — produceBlockV4 POST conversion, builder_preferences endpoint, and Eth-Builder-Url round-trip
  5. Migrate the validator client to the Gloas builder API (Gloas builder API 5/5) #9807 — validator-client migration, builder configuration store, and docs

The combined diff of the stack is identical to this PR's diff. This PR is now a draft serving as the end-to-end tracking view; review comments should go on the individual stack PRs. Unresolved feedback from reviews here will be re-raised on the relevant stack PR.

@ethDreamer

Copy link
Copy Markdown
Member Author

@eserilev done! 🎉 See the stack linked in the comment above: #9803#9804#9805#9806#9807 (Mergify stack, merging bottom-up into unstable).

A couple of notes on how it was cut:

  • The original per-crate commits didn't all compile independently, so the stack is regrouped into 5 layers where every prefix compiles — verified with cargo check --workspace --all-targets plus a release-mode check at each boundary (the http_api test harness is cfg(not(debug_assertions)), so dev checks alone miss it).
  • To make the layers self-contained, the legacy GET produceBlockV4 client methods stay alive through the middle of the stack and are removed in the final PR, once the VC has migrated to POST.
  • The combined diff of the stack is byte-identical to this PR, so nothing was lost in the split.

Bottom-up review order is #9803 first — it's the smallest and unblocks the rest. This PR stays as a draft tracking view until the stack drains.

@ethDreamer ethDreamer removed the ready-for-review The code is ready for review label Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants