Staked Builder API REST Client

[StefanBratanov]

PR Description

Client for the builder rest api as per ethereum/builder-specs#138 . There is a repetition but I found it difficult to create a generic rest client implementation that both the VC client and builder client can use.

Fixed Issue(s)

related to #10822

Documentation

• I thought about documentation and added the doc-change-required label to this PR if updates are required.

Changelog

• I thought about adding a changelog entry, and added one if I deemed necessary.

---

Note

Medium Risk
New outbound client for execution payload bids and block submission on the proposing path; additive and isolated in this PR but correctness will matter once wired into the validator client.

Overview
Adds a new builder:rest Gradle module with an OkHttp-based Staked Builder API client aligned with builder-specs#138.

StakedBuilderClient exposes three async operations: fetch execution payload bids (optional SignedRequestAuth JSON body vs empty POST), submit builder preferences (JSON), and submit signed beacon blocks (SSZ application/octet-stream). Shared plumbing includes BuilderApiMethod path templates, AbstractBuilderRequest for JSON/empty/octet-stream POSTs, ResponseHandler for status codes (200/202/204 vs 4xx/5xx → BuilderClientException), and Eth-Consensus-Version headers from the spec milestone.

OkHttpStakedBuilderClient wraps the per-endpoint handlers on an AsyncRunner. Gloas-milestone MockWebServer integration tests cover success paths, request shape, and error handling. The parent builder module is included in settings.gradle with jar packaging disabled.

^{Reviewed by Cursor Bugbot for commit 26c5540. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 68b3483. Configure here.}

[tbenr]

• Missing Eth-Consensus-Version request header on two endpoints. The spec marks this header required: true on both getExecutionPayloadBid and submitBuilderPreferences (the description qualifies it as "Required
  if the request body is SSZ encoded", but the OpenAPI declares it required unconditionally). The client sends it only for submitSignedBeaconBlock. A builder validating strictly against the OpenAPI schema would
  reject the other two requests. Since the milestone is trivially available, I'd send it on all three (it also future-proofs the JSON body across forks).

• ResponseHandler.VOID is a shared mutable singleton. withHandler() is public and mutates the internal Int2ObjectOpenHashMap, which is not thread-safe. Any future caller doing
  ResponseHandler.VOID.withHandler(...) would mutate global state visible to all concurrent requests. Either make withHandler copy-on-write, drop it from the shared instance, or replace VOID with a factory method
  (ResponseHandler.voidHandler()).

• All three central names already exist in the codebase for the legacy MEV-Boost Builder API. When this gets wired into ExecutionLayerManager (which already imports the old BuilderClient), both interfaces will coexist in the same call sites and imports will be genuinely confusing. Suggest
  StakedBuilderClient / StakedBuilderApiMethod or similar. Also note the old enum uses :param placeholders while the new one uses {param} — if both survive, converging on one convention would help.

• AbstractBuilderRequestTestBase is named Abstract... but declared as a plain public class — declare it abstract.

• getErrorMessage reads the full error body unbounded; a broken/hostile builder could return a huge payload that ends up in an exception message and log. Consider truncating (e.g. body.source().readUtf8(MAX)).

  Test coverage

  • shouldIncludeSignedRequestAuthInBodyWhenPresent only asserts body.size() > 0 — it should assert Content-Type: application/json and ideally round-trip the body back to the SignedRequestAuth to prove the schema
    used is the right one.
  • No test for the unknownResponseCodeHandler path (e.g. a 418) or for 503, and no test for a malformed 200 JSON body on the bid endpoint.

[rolfyone]

would be good to add the references like OpenApiIntegrationTest does so that we can easily see the api definitions...

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit b1cde23. Configure here.}

[StefanBratanov]

@tbenr fixed the 5 points, will tackle testing one separately

[StefanBratanov]

would be good to add the references like OpenApiIntegrationTest does so that we can easily see the api definitions...

They will show eventually anyways when we pipe them through the Beacon API.

[tbenr]

just one minor thing: Eth-Consensus-Version presence is not tested in all methods

[StefanBratanov]

just one minor thing: Eth-Consensus-Version presence is not tested in all methods

Done