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 client code will carry signed beacon blocks and execution payload bids once wired into proposing; mistakes in encoding, headers, or error handling could affect block production, but this PR is an isolated library with no production wiring yet.

Overview
Adds a new builder:rest Gradle module that implements an OkHttp-based client for the Staked Builder API (Gloas).

StakedBuilderClient exposes three async operations: fetch execution payload bids (optional signed auth in JSON body vs empty POST), submit builder preferences (JSON), and submit signed beacon blocks (SSZ application/octet-stream). Shared plumbing includes BuilderApiMethod path templates, ResponseHandler status mapping to BuilderClientException, and AbstractBuilderRequest for JSON/empty/octet-stream POSTs with Eth-Consensus-Version headers.

OkHttpStakedBuilderClient delegates to per-endpoint request classes on an AsyncRunner. MockWebServer integration tests cover success paths, request shape, and 4xx/5xx errors. The parent builder project is included in settings.gradle with jar packaging disabled for the aggregator.

^{Reviewed by Cursor Bugbot for commit 246a35a. 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