Skip to content

Update Beacon API for parity with Builder API and KeyManager API #630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JasonVranek wants to merge 20 commits into
base: master
Choose a base branch
from
Open

Update Beacon API for parity with Builder API and KeyManager API #630

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
5daf8a7
Beacon API parity with builder api and keymanager api
JasonVranek Jul 21, 2026
21750d8
Update CHANGES.md
JasonVranek Jul 21, 2026
f8d2943
address review comments
JasonVranek Jul 21, 2026
0ea8a06
address review comments
JasonVranek Jul 21, 2026
adc1ae1
require fully resolved builder entries, add SSZ request bodies, drop
JasonVranek Jul 23, 2026
1028934
address review feedback: trim to beacon-API conventions, fix bid
JasonVranek Jul 25, 2026
657d390
report the payload source, add default bid policy params, fix entry
JasonVranek Jul 27, 2026
727f6b3
remove Eth-Execution-Payload-Source header
JasonVranek Jul 27, 2026
23b5555
scope entry uniqueness by role: request identity vs p2p policy
JasonVranek Jul 27, 2026
3f886eb
A fully resolved body already carries default_min_bid and
JasonVranek Jul 28, 2026
979d038
align the produceBlockV4 description with the BuilderConfig body
JasonVranek Jul 28, 2026
ea9bafb
move max_execution_payment selection semantics to the builder-specs
JasonVranek Jul 28, 2026
bb1e790
batched submitBuilderPreferences call
JasonVranek Jul 31, 2026
bd99f03
Merge branch 'master' into update-produceBlockV4
JasonVranek Aug 1, 2026
91db6c8
address review nits on BuilderConfig and produceBlockV4
JasonVranek Aug 2, 2026
97c1cd9
drop per-builder p2p bid preferences
JasonVranek Aug 3, 2026
f71b1b8
Merge branch 'master' into update-produceBlockV4
JasonVranek Aug 7, 2026
eb752a1
Make BuilderConfig body and fork version header required
JasonVranek Aug 10, 2026
1dda02d
accept bids from a list of builder pubkeys
JasonVranek Aug 10, 2026
71c7315
a zero-length auth data is invalid
JasonVranek Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ There are likely to be descriptions etc outside of the list below, but new query

| Endpoint | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) |
|---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------|
| [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) `GET /eth/v4/validator/blocks/{slot}` added | | | | | |
| [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) / [#630](https://github.com/ethereum/beacon-APIs/pull/630) `POST /eth/v4/validator/blocks/{slot}` added | | | | | |
| [#630](https://github.com/ethereum/beacon-APIs/pull/630) `POST /eth/v1/validator/builder_preferences/{pubkey}` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}` added | | | | | |
| [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) `GET /eth/v1/validator/execution_payload_envelopes/{slot}/{beacon_block_root}` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/payload_attestation_data/{slot}` added | | | | | |
Expand All @@ -20,7 +21,7 @@ There are likely to be descriptions etc outside of the list below, but new query
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | |
| [#614](https://github.com/ethereum/beacon-APIs/pull/614) `POST /eth/v1/beacon/states/{state_id}/builders` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v2/beacon/blocks/{block_id}` updated | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) / [#630](https://github.com/ethereum/beacon-APIs/pull/630) `POST /eth/v2/beacon/blocks` updated | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `execution_payload_available EVENT` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `execution_payload_bid EVENT` added | | | | | |
| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `payload_attestation_message EVENT` added | | | | | |
Expand Down
14 changes: 14 additions & 0 deletions apis/beacon/blocks/blocks.v2.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,20 @@ post:
required: true
name: Eth-Consensus-Version
description: "The active consensus version to which the block being submitted belongs."
- name: Eth-Builder-Url

@nflaig nflaig Jul 25, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we really need this header? if I understand correctly the sole purpose of this is so that the beacon node knows where to submit it via submitSignedBeaconBlock but the beacon node should know this anyways, since it got the bid from that builder via api

the only case where the beacon node doesn't know this is if it's a different node (eg. in a multi-node setup) if the primary node that sourced the bid from the builder via api went offline during the proposal flow but this seems like an edge case and even then, publishing only via p2p is a fine fallback behavior that is sufficient anyways most of the time

that said, we can keep the header if people wanna have it, just questionable to me if it's useful enough

@JasonVranek JasonVranek Jul 25, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this was solely for the multi-node support, not opinionated on it but it seemed like DVT teams wanted. Will leave for now and address most of the fat trimming comments

@nflaig nflaig Jul 29, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not feel strongly about removing it, also I think when I commented there was in addition a Eth-Proxy-Url header which is now gone, so this single header, if useful for DVT teams, might be worth keeping

in: header
required: false
description: |

@james-prysm james-prysm Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's required false but maybe we should specify that we must echo this and eth-builder-proxy when available if returned by produceBlockv4 just to be explicit

The `url` of the winning builder, as returned by `POST /eth/v4/validator/blocks/{slot}`.
When that endpoint returns this header the validator client MUST echo it here, so the beacon
node can forward the signed block to the same builder and the builder can release the
payload without waiting for gossip. The echo is what lets a beacon node that did not serve
the block-production request still forward it. Omitted for a self-built block or a block won
by a p2p bid.
schema:
type: string
format: uri
example: "https://builder.example.com"
requestBody:
description: "The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced by beacon node) and validator signature."
required: true
Expand Down
144 changes: 83 additions & 61 deletions apis/validator/block.v4.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,45 @@
get:
post:
tags:
- Validator
- ValidatorRequiredApi
operationId: "produceBlockV4"
summary: "Produce a new block, without signature."
description: |
Requests a beacon node to produce a valid block, which can then be signed by a validator.
Requests a beacon node to produce a valid block, which the validator then signs.

Post-Gloas, proposers submit execution payload bids rather than full execution payloads,
so there is no longer a concept of blinded or unblinded blocks. Builders release the
payload later. This endpoint is specific to the post-Gloas forks and is not backwards compatible
with previous forks.
The beacon node always builds a local payload and MAY consider a p2p bid, so a block is returned
even when no bid is available. The validator client optionally supplies a `BuilderConfig` in the

@eserilev eserilev Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: there are several places where we mention bid (i.e. here "no bid is available"). in the local build case a bid is still constructed. It might be useful instead to specify builder bid, for example

Suggested change
even when no bid is available. The validator client optionally supplies a `BuilderConfig` in the
even when no builder bid is available. The validator client optionally supplies a `BuilderConfig` in the

there are multiple places in the PR where "bid" is assumed to be a builder bid. it might make things a bit clearer if we just explicitly say builder bid in those cases

@nflaig nflaig Aug 7, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not disagreeing with adding "builder" here as suggested but referring to local payload as "local bid" or similar is really confusing, during block proposal you either use a bid from a builder or you commit to a local payload, the fact that the ExecutionPayloadBid is overloaded and used for both is mostly spec limitation, ideally this should be something like Union[ExecutionPayloadBid, ExecutionPayloadCommitment] where the commitment type used when self-building drops anything that is unnecessary for local payloads like builder_index, fee_recipient and value

@eserilev eserilev Aug 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah i totally agree with not using the term local bid

request body: a list of `BuilderEntry` objects in its `builders` field, one per builder, plus a
top-level `min_bid` and `builder_boost_factor` that apply to a bid matching no entry. Each entry
contains `url`, `builder_pubkey`, or both:
- `url` only: a bid is requested from that address, and this entry applies to the bid it
returns.
- `builder_pubkey` only: no bid is requested, and this entry applies to that builder's p2p bids.
- both: a bid is requested and this entry applies to the bid it returns, which MUST NOT be
accepted unless signed by `builder_pubkey`.

When self-building (local execution payload), the response includes the full block contents
(beacon block, execution payload envelope, blobs, and KZG proofs) if `include_payload` is
set to `true`, otherwise only the `BeaconBlock` is returned.
When using an external builder bid, only the `BeaconBlock` is returned as the beacon node
does not have access to the builder's execution payload.
p2p policy comes only from entries with no `url`.

The `Eth-Execution-Payload-Included` header and `execution_payload_included` response field
indicate which response type was returned.
A bid is rejected if its total payment falls below the `min_bid` that applies to it. Every
surviving bid is then boosted by the `builder_boost_factor` that applies to it, and the highest
boosted bid competes with the local build in Gwei. The local build wins a tie.

A p2p bid is matched to an entry with no `url` by resolving its `builder_index` through the
builder registry. A bid matching no entry takes its `min_bid` and `builder_boost_factor` from
the body's top-level `min_bid` and `builder_boost_factor`.

The response carries the full block contents only when the beacon node self-built the block and
`include_payload` is `true`; in every other case, including any bid win, it carries only the
`BeaconBlock`.

Every block is published via `POST /eth/v2/beacon/blocks`. A self-built block carries
`BUILDER_INDEX_SELF_BUILD` as its `builder_index`, and the validator client publishes its
execution payload envelope via `POST /eth/v1/beacon/execution_payload_envelopes`. When a bid
won, the winning builder releases the envelope instead, and the validator client echoes
`Eth-Builder-Url` if one was returned.

This endpoint is specific to the post-Gloas forks and is not backwards compatible with previous
forks.
parameters:
- name: slot
in: path
Expand All @@ -45,59 +65,47 @@ get:
in: query
required: true
description: |
Controls whether the execution payload envelope and blobs are included in the response
when self-building (using local execution payload).
Whether a self-built block's response carries the execution payload inline, or omits it for
the beacon node to cache and the validator client to retrieve separately.

When `true`, the response includes the full block contents: beacon block,
execution payload envelope, blobs, and KZG proofs. This enables stateless operation
where the validator client can use multiple beacon nodes (multi-BN setups, distributed validators, failover).
When `true`, a self-built response includes the full block contents (beacon block, execution
payload envelope, blobs, and KZG proofs) and reports `Eth-Execution-Payload-Included: true`.
The validator client holds the whole payload, so it can sign and publish the envelope through
any beacon node (stateless operation: multi-BN setups, distributed validators, failover).

When `false`, only the beacon block is returned and the beacon node caches the execution
payload envelope and blobs internally. The validator client must then fetch them separately
via `GET /eth/v1/validator/execution_payload_envelopes/{slot}/{beacon_block_root}`. This saves
bandwidth but requires the validator client to publish via the same beacon node that
produced the block (stateful operation).
When `false`, a self-built response returns only the beacon block, reporting
`Eth-Execution-Payload-Included: false`; the beacon node caches the execution payload
envelope and blobs. The validator client retrieves the envelope via
`GET /eth/v1/validator/execution_payload_envelopes/{slot}/{beacon_block_root}`, signs it, and
publishes it via `POST /eth/v1/beacon/execution_payload_envelopes`, and the producing beacon
node attaches its cached blobs and KZG proofs before broadcasting. This sends fewer bytes but
ties publishing to that one beacon node (stateful operation).

This parameter only affects self-building scenarios. When using an external builder's bid,
only the beacon block is returned regardless of this parameter (the beacon node does not
have access to the builder's execution payload).
This parameter affects the self-built case only. When a bid wins, the beacon node does not
hold that payload, so it returns only the beacon block regardless of this parameter.

@nflaig nflaig Aug 2, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what exactly changed here?

This parameter affects the self-built case only. When a bid wins, the beacon node does not
hold that payload, so it returns only the beacon block regardless of this parameter.

this note seems useful

but also previously there was

included in the response when self-building

so if block includes a builder bid, this flag is ignored anyways

schema:
type: boolean
- name: builder_boost_factor
in: query
required: false
description: |
Percentage multiplier to apply to the builder's bid value when choosing between a
builder bid and payload from the paired execution node. This parameter is only relevant
if the beacon node has at least one viable builder `ExecutionPayloadBid` available and
receives a valid response from the paired execution node. When these preconditions are
met, the server MUST act as follows:

* if `exec_node_payload_value >= builder_boost_factor * (builder_bid_value // 100)`
for the highest builder bid known to the beacon node, then return a block committing
to the local execution node payload (with the payload itself included if
`include_payload` is set to true).
* otherwise, return a block committing to the builder bid (without execution payload,
as it is not yet available).

Servers must support the following values of the boost factor which encode common
preferences:

* `builder_boost_factor=0`: prefer the local execution node payload unless an error makes
it unviable.
* `builder_boost_factor=100`: profit maximization mode; choose whichever of the local
execution node payload and the builder bid pays more.
* `builder_boost_factor=2**64 - 1`: prefer the builder bid unless an error or beacon node
health check makes it unviable.

Servers should use saturating arithmetic or another technique to ensure that large values
of the `builder_boost_factor` do not trigger overflows or errors. If this parameter is
provided and no builder bid is available, the beacon node MUST respond with a block
committing to the local execution node payload, which the caller can choose to reject if
it wishes. If the value is provided but out of range for a 64-bit unsigned integer, then
an error response with status code 400 MUST be returned.
schema:
$ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"
requestBody:
required: false

@nflaig nflaig Aug 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while this request body is not required, we should make the Eth-Consensus-Version header required, it's completely missing from the request right now

arguably it's only needed if BuilderConfig is passed in the request body, but I would make the header always required

also worth considering making passing BuilderConfig since it also applies to p2p bids, I don't see a good reason to omit this?

description: |
A `BuilderConfig` for this request: the builder entries to solicit bids from, plus the
top-level `min_bid` and `builder_boost_factor` that apply to a p2p bid matching no entry.
When an entry contains an `auth`, its `auth.message.slot` is the `slot` this request is for;
the builder rejects a mismatch, so an entry naming a different slot is one the beacon node
does not use for a bid request. A body that cannot be decoded is invalid and MUST fail with a
400. Every other failure is per entry: an entry the beacon node rejects, or whose builder does
not answer, yields no bid and MUST NOT fail the request, so one bad entry never costs the
proposer its slot. An entry with no `url` requests no bid by design but supplies policy
for its builder's p2p bids. When the body is omitted the validator client has supplied no
builder config, so the beacon node requests no bids and returns its locally built block. A
client that wants a bid considered, over the builder API or p2p, supplies a `BuilderConfig`.
content:
application/json:

@james-prysm james-prysm Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wait we should also allow ssz

schema:
$ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BuilderConfig"
application/octet-stream:
schema:
description: "SSZ serialized `BuilderConfigV1` bytes (see the `BuilderConfig` type description for the container and constants). Use Content-Type header to indicate that SSZ data is contained in the request body."
responses:
"200":
description: Success response
Expand All @@ -108,6 +116,18 @@ get:
$ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Block-Value'
Eth-Execution-Payload-Included:
$ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Included'
Eth-Builder-Url:
description: |
When the winning bid came through the builder-API channel, the `url` of that builder.
The validator echoes this value in the `Eth-Builder-Url` request header when publishing
the signed block, so the beacon node can forward the block to the same builder via the
builder-API `submitSignedBeaconBlock`. Absent when the block was self-built or the
winning bid came from the p2p network.
required: false
schema:
type: string
format: uri
example: "https://builder.example.com"
content:
application/json:
schema:
Expand Down Expand Up @@ -151,6 +171,8 @@ get:
message: "Invalid request to produce a block"
"406":
$ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
"415":
$ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType"
"500":
$ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
"503":
Expand Down
Loading
Loading