4.4.2.Builder API

External builder flow before ePBS

Validator registration

The validator submits a list of signed registrations. Each registration binds:

• the validator public key;
• its preferred execution fee recipient;
• its preferred gas limit; and
• a timestamp.

The service returns 200 only after the registrations pass validation and must apply accepted policy to later blocks. Invalid registration returns 400.

Header request

The proposer requests a header for one slot, execution parent hash, and validator public key. It can send a request timestamp and timeout hint.

200 returns a versioned SignedBuilderBid. 204 means that no header is available.

Before selection, the proposer checks:

• the builder BLS signature and allowed builder;
• slot, parent hash, and proposer public key;
• non-zero value and any local value policy;
• timestamp, fee recipient, gas-limit relation, and block hash;
• every withdrawal, execution-request, and auxiliary-data field that the active fork uses;
• transaction root and every other fork-specific payload-header field; and
• the count and values of blob commitments when the active fork carries them.

Only then can it compare the bid with another bid or a local execution payload.

Blinded block reveal

The proposer signs a blinded beacon block and submits it. The signed block binds the proposer to the selected header.

The proposer recomputes the header from the returned payload. It checks the block hash, transactions root, and all active-fork header, request, commitment, and proof fields against its signed block. A mismatch makes the response unusable.

Failure boundary

A proposer may keep a local payload build active while it waits for headers. A timeout or 204 lets it use that local path. After it signs the blinded block, it cannot safely switch payloads. A bad or missing reveal can therefore cause a missed slot.

Builder API with ePBS

The bid and reveal contracts use consensus-native objects. The Builder API remains a direct path between a proposer and builder.

Slot-scoped preferences

The proposer submits BuilderPreferencesRequestV1, including its maximum execution payment, and SignedRequestAuthV1.

The authentication message binds the slot and service URL. The builder checks the BLS signature against the path validator public key. It returns:

• 202 for accepted preferences;
• 400 for bad slot, URL, or preference values;
• 401 for a bad signature; or
• 500 for an internal failure.

A validator may submit preferences during the prior epoch when proposer lookahead already names its slot.

Bid request

The request names the slot, execution parent hash, beacon parent root, and proposer public key. It may carry signed request authentication.

The builder gets max_execution_payment only from the preference endpoint. If it has no accepted preferences, it treats that value as zero and does not add an execution payment to the bid.

200 returns a Gloas SignedExecutionPayloadBid. 204 means no bid. A builder can require authentication and return 401; otherwise the body is optional.

A valid direct response can enter the same local validation and selection path as a bid learned from consensus gossip. The HTTP route does not bypass consensus bid rules.

The pinned sources disagree on nonzero execution payments. The Builder API allows preferences and bids to carry them, while the consensus p2p validation rejects a bid whose execution_payment is nonzero. Until those sources align, a nonzero payment is not an interoperable Glamsterdam path. The ePBS bids page records the conflict in detail.

Signed beacon block submission

After it includes the selected bid and signs the beacon block, the proposer can submit the full signed beacon block to the builder. 202 means the builder accepted it. The builder then publishes the execution payload envelope. The proposer does not submit a blinded block and does not wait for an HTTP payload reveal.