builder_api: add Gloas Staked Builder API client by NikhilSharmaWe · Pull Request #819 · grandinetech/grandine

NikhilSharmaWe · 2026-07-17T18:33:38Z

Part of #769. Client side of the Gloas Staked Builder API (ethereum/builder-specs#138), aligned with the clarifications in ethereum/builder-specs#165 (ACDT CL guidance: implement before merge).

Changes

Add DOMAIN_REQUEST_AUTH (0x0B000001) and the Gloas builder containers (RequestAuthV1, SignedRequestAuthV1, BuilderPreferencesV1, BuilderPreferencesRequestV1) to builder_api
Add three HTTP client methods:
- get_execution_payload_bid — POST /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{parent_root}/{proposer_pubkey} with a required SignedRequestAuthV1 body (JSON or SSZ), required Date-Milliseconds and X-Timeout-Ms headers (timeout matches the reqwest timeout), and always Eth-Consensus-Version. 200 returns a bid, 204 means no bid. Gloas+ only; rejects earlier phases and auth.message.slot ≠ path slot before the request.
- submit_builder_preferences — POST /eth/v1/builder/builder_preferences/{validator_pubkey} with BuilderPreferencesRequestV1 (SSZ field order: auth then preferences), expects 202
- submit_signed_beacon_block — POST /eth/v1/builder/beacon_blocks, expects 202
Signing support for RequestAuthV1 (SignForAllForks, genesis fork + zero genesis validators root, per spec compute_domain(DOMAIN_REQUEST_AUTH))
Prometheus histograms for the three calls

Notes

Client only. Wiring into block production is a follow-up (block production: wire Gloas builder bid fetch and notify #822).
Builder bid signature verification is deferred to the caller (needs beacon state / state.builders() by builder_index).
After a 202 from submitSignedBeaconBlock the proposer must still gossip the beacon block; the builder publishes the payload envelope.
Spec type names in Fix/request-auth-clarifications ethereum/builder-specs#165 drop the V1 suffix; Rust keeps *V1 to match other builder_api containers. Wire format follows Fix/request-auth-clarifications ethereum/builder-specs#165.

Tests

cargo test -p builder_api --features blst — httpmock coverage for all three endpoints (200/204/400/500, required auth body + timing / consensus-version headers, auth slot mismatch, non-2xx handling, pre-Gloas rejection), DOMAIN_REQUEST_AUTH signing-root check, and SSZ field-order lock for BuilderPreferencesRequestV1

Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

NikhilSharmaWe · 2026-07-29T15:09:20Z

cc @hangleang

hangleang · 2026-07-29T15:24:44Z

cc @hangleang

Thanks for the contributions, I was occupy by other urgent tasks so I won't be able to review within this week or two

hangleang · 2026-08-06T08:22:02Z

FYI: clients have agreed to implement the spec PR ethereum/builder-specs#165 even it still unmerged (see https://forkcast.org/calls/acdt/090/?breakout=cl#t=70 on decisions), could you update the PR accordingly?

Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

NikhilSharmaWe · 2026-08-06T13:09:16Z

@hangleang Updated with ethereum/builder-specs#165 as requested:

Required SignedRequestAuth on bid fetch
Required Date-Milliseconds and X-Timeout-Ms
Always send Eth-Consensus-Version
BuilderPreferencesRequest SSZ order: auth then preferences

Tests updated; cargo test -p builder_api --features blst passes.

hangleang · 2026-08-13T11:46:27Z

just cosmetic, all new containers name has been removed the version suffix

hangleang · 2026-08-13T12:05:26Z

+/// [`MAX_DATA_SIZE`] from `builder-specs` (Gloas).
+///
+/// [`MAX_DATA_SIZE`]: https://github.com/ethereum/builder-specs/blob/main/specs/gloas/builder.md#constants
+pub type MaxDataSize = U4096;


it should be put in consts.rs i believe

hangleang · 2026-08-13T12:06:52Z

+    tag = "version",
+    content = "data"
+)]
+pub enum GetExecutionPayloadBidResponse<P: Preset> {


this response type and its implementations should be put in combined.rs

hangleang · 2026-08-13T12:30:08Z

+            .parse_gloas_response::<GetExecutionPayloadBidResponse<P>>(response)
+            .await?;
+
+        let bid = bid_response.into_bid();


returned bid isn't checked against request slot, parent_hash, parent_root as specified in https://github.com/ethereum/builder-specs/blob/main/specs/gloas/validator.md#validating-a-signedexecutionpayloadbid

hangleang · 2026-08-13T15:38:18Z

+                .builder_submit_builder_preferences_times
+                .start_timer()
+        });
+


why won't check slot like get_execution_payload_bid does?

hangleang · 2026-08-13T15:54:06Z

+        })
+    }
+
+    async fn parse_gloas_response<T: DeserializeOwned + SszRead<Phase>>(


this function almost identical to parse_response below, can we reuse the function?

hangleang · 2026-08-13T16:06:57Z

+        let request = self
+            .client
+            .post(url.into_url())
+            .timeout(remaining_time)


this might be the wrong deadline for this endpoint. I guess this is copied from post_blinded_block pre-Gloas path which proposer require builder to response before attestation deadline, so it has the payload to construct and publish beacon block before deadline. but now builder is responsible to publish their payload, and this endpoint is just notify them to publish payload envelope by themselves through beacon node

hangleang · 2026-08-13T16:19:35Z

+        let request = self
+            .client
+            .post(url.into_url())
+            .timeout(REQUEST_TIMEOUT)


the interval timeout should be put on this endpoint instead, as now proposer request bid from builder to choose on proposal hot path

hangleang · 2026-08-13T16:19:51Z

+            .header(DATE_MS_HEADER, format!("{date_ms}"))
+            .header(
+                X_TIMEOUT_MS_HEADER,
+                format!("{}", REQUEST_TIMEOUT.as_millis()),


hangleang · 2026-08-13T16:23:29Z

+            "/eth/v1/builder/execution_payload_bid/{slot}/{parent_hash:?}/{parent_root:?}/{pubkey:?}"
+        ))?;
+
+        let use_json = self.config.builder_api_format == BuilderApiFormat::Json;


should have fallback to json format if builder doesn't support SSZ, same as other two endpoints

builder_api: add Gloas Staked Builder API client

ed38da3

Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

NikhilSharmaWe mentioned this pull request Jul 20, 2026

block production: wire Gloas builder bid fetch and notify #822

Draft

builder_api: rustfmt test asserts

5f8755b

Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

builder_api: align Gloas client with builder-specs#165

42285f3

Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

hangleang reviewed Aug 13, 2026

View reviewed changes

Uh oh!

Conversation

NikhilSharmaWe commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Notes

Tests

Uh oh!

NikhilSharmaWe commented Jul 29, 2026

Uh oh!

hangleang commented Jul 29, 2026

Uh oh!

hangleang commented Aug 6, 2026

Uh oh!

NikhilSharmaWe commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

NikhilSharmaWe commented Jul 17, 2026 •

edited

Loading

NikhilSharmaWe commented Aug 6, 2026 •

edited

Loading