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 Clarifications on builder spec ethereum/builder-specs#165 drop the V1 suffix; Rust keeps *V1 to match other builder_api containers. Wire format follows Clarifications on builder spec 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

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?

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-13T15:38:18Z

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


why won't check slot like get_execution_payload_bid does?

Done in e5ba389
auth.message.slot is treated as the proposal slot and rejected if it has already passed.

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?

Done in 0e01a9c. JSON/SSZ decoding was extracted into decode_ssz_or_json_response and reused. parse_response remains a wrapper for legacy builder responses because it also updates the separate supports_block_ssz cache.

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

Fixed in a5867d4. The signed-block notification now uses the fixed request timeout instead of the attestation-interval deadline.

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

Done in 25b73d3
The bid request is bounded by the remaining time before the next interval, capped at one second.

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

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


Done in same 25b73d3. X-Timeout-Ms and the reqwest timeout use the same computed millisecond value.

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

Done for bids in e049bac, then extended across all Gloas POST bodies in 0e01a9c. A 415 retries once as JSON; 400 and other client errors are not retried.

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

…inguish skipped bids from 204 Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

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

NikhilSharmaWe · 2026-08-20T13:43:26Z

@hangleang, I have resolved the reviews. Let me know if there are any issues or improvements required.

NikhilSharmaWe mentioned this pull request Jul 20, 2026

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

Draft

hangleang reviewed Aug 13, 2026

View reviewed changes

NikhilSharmaWe added 13 commits August 14, 2026 13:26

builder_api: add Gloas Staked Builder API client

0fc5298

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

builder_api: rustfmt test asserts

98efcb5

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

builder_api: align Gloas client with builder-specs#165

ec340af

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

builder_api: drop V1 suffix from Gloas containers

7293d08

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

builder_api: move MaxDataSize to consts

9dd626b

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

builder_api: move GetExecutionPayloadBidResponse to combined

298ce3b

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

builder_api: check bid slot and parents against request

f98ab29

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

builder_api: validate preferences auth slot and proposal-slot phase

e5ba389

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

builder_api: reject pre-Gloas blocks on submit_signed_beacon_block

ba9600c

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

builder_api: use fixed timeout for submit_signed_beacon_block

a5867d4

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

builder_api: bound bid fetch by next interval and X-Timeout-Ms

25b73d3

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

builder_api: fall back to JSON when bid SSZ is rejected with 415

e049bac

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

builder_api: extend SSZ 415 JSON fallback across Gloas POSTs and dist…

0e01a9c

…inguish skipped bids from 204 Signed-off-by: Nikhil Sharma <nikhilsharma230303@gmail.com>

NikhilSharmaWe force-pushed the gloas-builder-api-client branch from 42285f3 to 0e01a9c Compare August 14, 2026 07:59

NikhilSharmaWe requested a review from hangleang August 14, 2026 11:58

NikhilSharmaWe added 2 commits August 14, 2026 17:33

builder_api: acknowledge bid request argument count

52e18a8

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

builder_api: use explicit Phase0 default in test

da8cd98

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

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!

Uh oh!

Uh oh!

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!

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

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!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

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

NikhilSharmaWe Aug 14, 2026 •

edited

Loading

NikhilSharmaWe Aug 14, 2026 •

edited

Loading

NikhilSharmaWe commented Aug 20, 2026 •

edited

Loading