Staked Builder API for Glamsterdam #138

bharath-123 · 2025-11-28T16:00:00Z

This PR begins work and discussions on the builder-spec for ePBS for staked builders.

ePBS introduces the following protocol upgrades:

Enshrining of builders into the protocol by allowing them to stake collateral(used for trustless payments)
Decoupling BeaconBlock validation and ExecutionPayload validation.

A high level description of the design is available at: https://hackmd.io/J24hFHFvRl2DOZijvocukg?view

We introduce 2 new APIs(we have room for bikeshedding these names):

getExecutionPayloadBid: GET /eth/v1/builder/execution_payload_bid
This API is called by the proposer to the builder/relay. The proposer sends the fee_recipient as a header along with the request. The builder/relay returns an execution payload bid with the execution_payment directed to the sent fee_recipient.
submitSignedBeaconBlock: POST /eth/v1/builder/beacon_block
This API is called by the proposer to the builder/relay when the proposer commits to the bid received from getExecutionPayloadBid. The proposer sends the signed beacon block with the execution payload bid embedded to it.

We introduce ValidatorRegistrationV2 which contains the following new fields:

builder_index: This is the index of the builder to which the registration is being sent.
validator_index: This is the index of the validator to which the registration is being sent.
builder_preferences: This contains the per builder preferences per validator. Currently the only builder preference supported is execution_payment_accepted.
proposal_slot: This slot in which this validator will be proposing.

In gloas, All the validators will not send validator registrations every epoch like how it worked till Fulu. A validator will send it's registration in the epoch prior to which it will propose.
e.g, let's say a validator will propose in epoch E+1, it will send it's validator registrations at epoch E.

This spec is based on: ethereum/consensus-specs#4788 which is not yet merged.

Closes: #137

bharath-123 · 2025-12-12T09:13:09Z

Open questions:

How is the fee_recipient communicated to the builder? Do we keep ValidatorRegistrations or do we send the fee_recipient along as a header while receiving the bid. Or we can use the ProposerPreferences gossip topic as specified in: Add specs for proposer preferences consensus-specs#4777
The API currently assumes all builders are staked. do we have to also support builders who choose to not stake?

bharath-123 · 2025-12-12T09:13:27Z

specs/gloas/validator.md

@@ -0,0 +1,38 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->


What else can we spec out here?

bharath-123 · 2025-12-12T09:13:33Z

specs/gloas/builder.md

@@ -0,0 +1,34 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->


What else can we spec out here?

bharath-123 · 2025-12-12T09:15:41Z

apis/builder/execution_payload_bid.yaml

+    This API is applicable from Glamsterdam fork onwards.
+  tags:
+    - Builder
+  parameters:


We are no longer passing in the slot, parent_hash and pubkey as params in the path. I am unsure if we need to submit that data anymore since the validator already checks if the latest slot and parent_hash match from state while processing the ExecutionPayloadBid

bharath-123 · 2025-12-12T09:16:02Z

apis/builder/execution_payload_bid.yaml

+      required: false
+      description: |
+        Optional header containing the proposer's timeout for the request in milliseconds. 
+        Relays should use this header to adjust the amount of time by which they delay getBid 


Suggested change

Relays should use this header to adjust the amount of time by which they delay getBid

Builders should use this header to adjust the amount of time by which they delay getBid

bharath-123 · 2025-12-12T09:21:50Z

apis/builder/execution_payload_bid.yaml

+        type: integer
+        format: int64
+        example: 10000
+    - name: X-Fee-Recipient


Currently speccing it out to support sending the fee_recipient while sending the request to get the bid

bharath-123 · 2025-12-12T10:17:24Z

Spellcheck fixes are trivial and shuoldn't block any feedback.

bharath-123 · 2025-12-12T10:49:20Z

specs/gloas/builder.md

+
+This document documents the builder behaviour with the Builder-API.
+
+### `ValidatorRegistrationV1` are deprecated


Do we want to deprecate ValidatorRegistrationV1 going forward for gloas? or do builders want to keep it?

There might be value keeping validator registrations for validators to communicate per builder preference.

bharath-123 · 2025-12-15T05:42:35Z

Note: We want the response to the get the bid to be signed by the validator on the builder pub key and slot. This is so that the builder won't get spammed by other builders to reveal their bid.

bharath-123 · 2025-12-16T10:15:34Z

specs/gloas/builder.md

+    timestamp: uint64
+    pubkey: BLSPubkey
+    can_accept_trusted_payment: bool
+    proposal_epoch: Epoch


we now suggest validator to send the registration only if they will be proposing in the upcoming epoch. This might be useful information to have?

bharath-123 · 2025-12-16T10:16:18Z

specs/gloas/builder.md

+
+```python
+class ValidatorRegistrationV2(Container):
+    builder_pubkey: BLSPubkey ## is this needed? 


primary use of validator registrations with gloas is to indicate per builder preferences. Maybe this can be helpful for the builder to identify if the registration is indeed indicated for them.

bharath-123 · 2025-12-16T10:17:29Z

specs/gloas/validator.md

+This specification suggests validators re-submit registrations only if they will be proposing in the upcoming epoch(E+1). 
+This is to avoid sending a lot of `ValidatorRegistrations` every epoch. This can potentially help reduce the load 
+Validators are expected to perform this check at every epoch boundary. Validators can send their registrations even though
+they won't be proposing in the upcoming epoch.


we don't want to have a very strong enforcement on validators to send registrations only when they are proposing in epoch E+1 but we recommend them to do this.

bharath-123 · 2025-12-23T16:26:58Z

specs/gloas/builder.md

+def verify_registration_signature(state: BeaconState, signed_registration: SignedValidatorRegistrationV2) -> bool:
+    validator = state.validators[signed_registration.message.validator_index]
+    pubkey = validator.pubkey
+    domain = compute_domain(DOMAIN_APPLICATION_BUILDER)


Do we need to update the domain as we are introducing a new type of registration?

bharath-123 · 2025-12-23T16:37:57Z

specs/gloas/builder.md

+
+```python
+class BuilderPreferences(Container):
+    execution_payment_accepted: boolean


Can we allow validators to express arbitrary preferences here? That might be useful for proposers and builders alike. But the proposer and builders will have to agree on the scheme for preferences ahead of time. And on the other hand, hard coding preferences into BuilderPreferences will have to involve a co-ordinated rollout amongst clients.

bharath-123 · 2025-12-23T16:49:51Z

specs/gloas/validator.md

+    assert signed_bid.prev_randao == get_randao_mix(state, get_current_epoch(state))
+    assert is_builder(state, builder.pubkey)
+
+    if signed_bid.value > 0:


it might not be necessary for a builder to use the execution_payment field to pay the bid even through the builder-api.

bharath-123 · 2025-12-23T17:34:00Z

specs/gloas/builder.md

+
+```python
+def is_eligible_for_bid(state: BeaconState,
+                        registrations: Dict[BLSPubkey, ValidatorRegistrationV2],


I guess it shouldn't be relevant to use whether registrations are a Dict from BLSPubKey -> ValidatorRegistrationV2 or ValidatorIndex -> ValidatorRegistrationV2? or maybe it does?

bharath-123 · 2025-12-23T17:44:28Z

apis/builder/execution_payload_bid.yaml

+      description: Root of the beacon block the proposer will build on.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Root"
+    - name: proposer_index


should we stick with the proposer pubkey or use proposer index?

bharath-123 changed the title ~~Builder API updates for Glamsterdam~~ Off-Protocol Builder API updates for Glamsterdam Dec 3, 2025

bharath-123 changed the title ~~Off-Protocol Builder API updates for Glamsterdam~~ Builder API updates for Glamsterdam Dec 3, 2025

bharath-123 force-pushed the epbs-updates branch from 01bb9e6 to 0cf7078 Compare December 12, 2025 09:07

bharath-123 commented Dec 12, 2025

View reviewed changes

bharath-123 changed the title ~~Builder API updates for Glamsterdam~~ Staked Builder API for Glamsterdam Dec 15, 2025

bharath-123 marked this pull request as ready for review December 16, 2025 09:58

bharath-123 commented Dec 16, 2025

View reviewed changes

bharath-123 added 8 commits December 17, 2025 19:11

initial builder-api for gloas

3f58cfb

updates

c1255e3

pass in params while querying execution payload bid

8719a35

introduce validator registrations v2

ffdc228

run doctoc

05db388

update validator registration v2

49adb85

add more specs

c5eadb1

run lint

9bd69ae

bharath-123 force-pushed the epbs-updates branch from 1a37a61 to 9bd69ae Compare December 17, 2025 13:49

bharath-123 added 4 commits December 17, 2025 22:24

updates

a047abb

abstract execution_payment_accepted to a BuilderPreferences struct

dc342d6

minor fixes

7e12901

run doctoc

4ef6a82

bharath-123 added 2 commits December 19, 2025 15:53

use correct method to check if builder is active

b8ad2f8

save

5e0cd76

bharath-123 commented Dec 23, 2025

View reviewed changes

bharath-123 added 2 commits December 23, 2025 22:49

updates

f222e70

add information for bidding

1992f10

bharath-123 commented Dec 23, 2025

View reviewed changes

update

a693a28

		@@ -0,0 +1,38 @@
		<!-- START doctoc generated TOC please keep comment here to allow auto update -->

		@@ -0,0 +1,34 @@
		<!-- START doctoc generated TOC please keep comment here to allow auto update -->

	Relays should use this header to adjust the amount of time by which they delay getBid
	Builders should use this header to adjust the amount of time by which they delay getBid


		This document documents the builder behaviour with the Builder-API.

		### `ValidatorRegistrationV1` are deprecated

Staked Builder API for Glamsterdam #138

Are you sure you want to change the base?

Staked Builder API for Glamsterdam #138

Uh oh!

Conversation

bharath-123 commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bharath-123 commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bharath-123 commented Dec 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bharath-123 commented Dec 15, 2025

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bharath-123 commented Nov 28, 2025 •

edited

Loading

bharath-123 commented Dec 12, 2025 •

edited

Loading