Add builder execution requests (EIP-8282) by jtraglia · Pull Request #5359 · ethereum/consensus-specs

jtraglia · 2026-06-11T20:12:28Z

This PR integrates EIP-8282 into Gloas.

Add EIP: Builder Execution Requests EIPs#11760

Note: This was made in collaboration with @ensi321 🙂

The gloas bid and envelope carry an `ExecutionRequests` extended with `builder_deposits` (0x03) and `builder_exits` (0x04) per ethereum/consensus-specs#5359. Using `ssz.electra.ExecutionRequests.hashTreeRoot` in the gloas-only code paths produced a root over the electra-shaped container — wrong even when both builder lists are empty, because the gloas container has two additional zero-hash leaves. Switch the four gloas-only call sites to `ssz.gloas.ExecutionRequests`: * `produceBlockBody.ts` self-build bid construction * `verifyExecutionPayloadEnvelope.ts` bid↔envelope cross-check * `executionPayloadEnvelope.ts` gossip validation * `upgradeStateToGloas.ts` genesis bid default-value root Refs: ethereum/consensus-specs#5359, ethereum/EIPs#11760 🤖 Generated with AI assistance

processBuilderDepositRequest (3 cases): * register on first appearance when PoP verifies * drop silently when PoP fails * top-up an existing builder without re-verifying signature and without rebinding withdrawal credentials (matches validator deposit contract semantics) processBuilderExitRequest (5 cases): * drop for unknown pubkey * drop for inactive builder (`deposit_epoch >= finalized_epoch`) * drop when `source_address` ≠ builder execution address * drop when builder already has pending withdrawal queued * initiate exit on the happy path (sets withdrawableEpoch = currentEpoch + MIN_BUILDER_WITHDRAWABILITY_DELAY) JSON shape (4 cases): * BuilderDepositRequest snake_case round-trip * BuilderExitRequest snake_case round-trip * ExecutionRequests carries builder_deposits / builder_exits alongside the existing deposits/withdrawals/consolidations keys * ExecutionPayloadEnvelope JSON round-trip with builder requests populated Refs: ethereum/consensus-specs#5359, ethereum/EIPs#11760 🤖 Generated with AI assistance

ensi321 · 2026-06-17T00:08:57Z

On a side note, since there is concern about adding a lot of noise in the spec just for the builder onboarding mechanism at the fork. I wonder if we can extract that part from beacon-chain.md cleanly and put it in a separate file, labeling that this mechanism is a one time use only

ensi321 · 2026-06-17T01:41:07Z


 ## Becoming a builder

-### Builder withdrawal credentials


Why is this removed? We still have withdrawal credentials for builders, instead of withdrawal prefix we have builder version for the first byte

I guess we should also point out what the supposedly correct value of builder version should be in gloas, albeit it is not checked or enforced anywhere

Why is this removed? We still have withdrawal credentials for builders, instead of withdrawal prefix we have builder version for the first byte

This section was removed because I believe it's sufficiently covered by the "submit deposit" section.

I guess we should also point out what the supposedly correct value of builder version should be in gloas, albeit it is not checked or enforced anywhere

If this PR is merged, I'm planning to follow up with a PR which states that new builder deposits should use version 0 instead of version 3 (BUILDER_WITHDRAWAL_PREFIX). This change is independent of EIP-8282 and I don't want to overcomplicate this PR. But yes, this will not be enforced by the protocol. It will be possible to create a builder with whatever version. Doing so would be unwise though, as it may restrict future abilities. We want to allow this so that future builder versions can exist at the fork. For example, we may decide to have separate versions for payload builders and proof builders, for when mandatory proofs are a thing.

Just leaving a random thought that version might be an overengineering or a wise forward-thinking decision. No idea at the moment 🤷‍♂️

Yeah 😅 hopefully the latter. Good to have options though I guess.

jtraglia · 2026-06-17T10:12:43Z

On a side note, since there is concern about adding a lot of noise in the spec just for the builder onboarding mechanism at the fork. I wonder if we can extract that part from beacon-chain.md cleanly and put it in a separate file, labeling that this mechanism is a one time use only

For the most part, this is already the case. The onboarding function is in fork.md which implies it's only used at the fork. I intend to move some of the helper functions (there are two) which are only used for onboarding from beacon-chain.md to fork.md in a separate PR though.

jihoonsong · 2026-06-18T12:12:08Z

 | Name                     | Value                      |
 | ------------------------ | -------------------------- |
-| `DOMAIN_EXECUTION_PROOF` | `DomainType('0x0E000000')` |
+| `DOMAIN_EXECUTION_PROOF` | `DomainType('0x0F000000')` |


Hmm 0x0F doesn't exist yet here. Since this is based on Gloas, not Heze. But yeah, we can change this optimistically.

If this comes before Heze, the domain in Heze would change instead. If that makes sense.

Either this or Heze's one should be changed. Slightly prefer to change this one to G because it's not entirely scheduled to ship this.

To be clear, since both are currently based off Gloas they do not need to be different right now. After thinking about this for a while, I have just pushed a commit with changes Heze's DOMAIN_INCLUSION_LIST_COMMITTEE to 0x10000000. I changed this instead of DOMAIN_EXECUTION_PROOF because (1) I consider optional proofs to be part of Gloas and (2) I expect optional proofs to go live on mainnet before Heze does.

nflaig · 2026-06-18T13:20:39Z

+            add_builder_to_registry(
+                state,
+                request.pubkey,
+                uint8(request.withdrawal_credentials[0]),


can't this be set to any arbitrary value between 0x00 and 0xFF?

Yes it can. And that's intentional. This would work the same as validators do today. For instance, there's nothing stopping you from creating a validator with a 0x04 withdrawal credential. Do you think we should restrict this to some value? It would make it difficult/impossible to have another builder version at the fork. For example say builders v0 are for execution payloads and builders v1 are for block proofs. At the fork for mandatory proofs, we may want v1 builders to exist in the registry already.

yeah we have the same for validators today, I don't see any harm, not right now anyways since version is unused. seems reasonable to keep the door open to have new type of builders before the actual fork, but would be good then if we can ensure that tooling will set the version to 0x00 in gloas

Yup will ensure tooling uses 0x00 for builders.

I believe it's better to constrain this value, it's fine if you want to have it configurable in a range. But allowing any value to be used now would preclude us from actually enforcing behavior on a version if we need to in the future. Eg. Suppose we want to force in the future that all builders of type 0xEF must have execution address potuz.eth. Some builder can frontrun and prevent that behavior right now by sending an 0xEF builder right now. It would be better to at least reserve an unused section right now, eg for example assert request.withdrawal_credentials[0] & 0xF0 == 0x00.

@potuz let's debate this later. I'm not strongly opposed to reserving those versions just in case, but I don't believe there will be a situation in which it would be necessary. As said on discord, I believe such checks should exist elsewhere, not when deciding if the builder should be added to the registry.

nflaig · 2026-06-19T10:05:27Z

 @with_gloas_and_later
 @spec_state_test
-def test_process_parent_execution_payload__builder_deposit_after_pending_validator(spec, state):
+def test_process_parent_execution_payload__builder_credential_deposits_queued(spec, state):


test case(s) for builder exit requests are missing

What kind of tests do you have in mind here? Feel free to commit some. To be clear, we do have builder exit requests here but these are not with process_parent_execution_payload.

if I comment out L1211 does any test catch this?

https://github.com/jtraglia/consensus-specs/blob/c15bd91e3693b3006f050fd1c9048019f47f3a9f/specs/gloas/beacon-chain.md?plain=1#L1210-L1211

the tests you referenced are calling process_builder_exit_request directly but not if it's wired up correctly in process_parent_execution_payload, I might be missing a test that catches this

I'm pretty sure the answer is no, that would not be caught with the current tests. We should add a test for this. I'm a bit busy at the moment. Would you have time to add a test for this?

yes I can push a test for that, currently running the existing tests against lodestar to make sure we are passing them

pushed a test for this c84f2e4, this will catch if process_parent_execution_payload is incomplete and doesn't call process_builder_exit_request

potuz · 2026-06-19T11:30:08Z

+# 2**8 (= 256) builder deposit requests
+MAX_BUILDER_DEPOSIT_REQUESTS_PER_PAYLOAD: 256
+# 2**4 (= 16) builder exit requests
+MAX_BUILDER_EXIT_REQUESTS_PER_PAYLOAD: 16


This may be very costly, but with these numbers assymmetric, someone could make a ton of deposits and then withdraw all of them and take the whole churn for a long time.

I don't think there is a good reason to use such a low value for exits as they are generally cheap to process

Staying in the target of 2 exit requests per payload, it would require locking up 14,400 ETH ($30m) to delay the builder exit queue by one day. This doesn't feel like a realistic concern.

no, not a concern imo, we have a really high MIN_BUILDER_WITHDRAWABILITY_DELAY so this would be way too expensive, and exiting builders isn't actually time sensitive and already takes a long time

potuz · 2026-06-19T11:32:05Z


 ### Withdrawal prefixes

+*Note*: `BUILDER_WITHDRAWAL_PREFIX` is a temporary constant which is only used


A postteriori it would've been cooler to have this one be 0x0B or 0xBB

We still can do this btw. I would support this.

potuz · 2026-06-19T11:36:35Z

+```python
+class BuilderExitRequest(Container):
+    source_address: ExecutionAddress
+    pubkey: BLSPubkey


For validators, this entry is called validator_pubkey, perhaps this one should be called builder_pubkey for symmetry.

Eh I would prefer not to change this, but not strongly opposed.

WithdrawalRequest (which you're comparing it to) uses validator_pubkey but I would argue that it's necessary there because the structure name does not contain "validator". This is unlike BuilderExitRequest in which it's explicit that the pubkey is associated with a builder.

pubkey is used in BuilderDepositRequest, so if we change this we would have to change that too, and then it's non-symmetric with DepositRequest which also uses pubkey.

potuz · 2026-06-19T11:51:18Z

+            add_builder_to_registry(
+                state,
+                request.pubkey,
+                uint8(request.withdrawal_credentials[0]),


I believe it's better to constrain this value, it's fine if you want to have it configurable in a range. But allowing any value to be used now would preclude us from actually enforcing behavior on a version if we need to in the future. Eg. Suppose we want to force in the future that all builders of type 0xEF must have execution address potuz.eth. Some builder can frontrun and prevent that behavior right now by sending an 0xEF builder right now. It would be better to at least reserve an unused section right now, eg for example assert request.withdrawal_credentials[0] & 0xF0 == 0x00.

nflaig

LGTM

terencechain

Lgtm

implements the following spec changes required to pass `v1.7.0-alpha.11` spec tests - ethereum/consensus-specs#5359 - ethereum/consensus-specs#5377 - ethereum/consensus-specs#5373 - ethereum/consensus-specs#5365 - ethereum/consensus-specs#5364 - ethereum/consensus-specs#5368 --------- Co-authored-by: NC <17676176+ensi321@users.noreply.github.com>

Add EIP-8282 to Gloas

20d292f

github-actions Bot added testing CI, actions, tests, testing infra gloas heze eip8148 Custom sweep threshold labels Jun 11, 2026

jihoonsong reviewed Jun 12, 2026

View reviewed changes

Comment thread specs/gloas/fork.md Outdated

jtraglia added 2 commits June 12, 2026 12:13

Go back to using withdrawal_credentials

be0f335

Sign builder deposits with DOMAIN_BUILDER_DEPOSIT

c90980c

github-actions Bot added the eip8025 Optional Execution Proofs label Jun 12, 2026

jtraglia and others added 5 commits June 12, 2026 13:58

Move BUILDER_WITHDRAWAL_PREFIX back to beacon-chain.md

f1e91b9

Onboarded builders have a version of zero

5483667

Move helper functions back to beacon-chain.md

b78e143

Keep version from withdrawal credentials for now

a9077f3

Merge branch 'master' into eip8282

76e9c40

lodekeeper mentioned this pull request Jun 12, 2026

feat: eip-8282 builder execution requests scaffolding ChainSafe/lodestar#9507

Closed

5 tasks

nflaig mentioned this pull request Jun 15, 2026

All Core Devs - Testing (ACDT) #83, June 15, 2026 ethereum/pm#2116

Closed

4 tasks

Set MAX_BUILDER_DEPOSIT_REQUESTS_PER_PAYLOAD to 256

4ac8251

twoeths reviewed Jun 16, 2026

View reviewed changes

Comment thread specs/gloas/validator.md Outdated

ensi321 reviewed Jun 17, 2026

View reviewed changes

StefanBratanov mentioned this pull request Jun 17, 2026

New/Modified Containers and config (EIP-8282) Consensys-Incorporated/teku#10845

Merged

2 tasks

pk910 mentioned this pull request Jun 17, 2026

glamsterdam devnet 6 (spec v1.7.0-alpha.11) ethpandaops/dora#746

Merged

StefanBratanov mentioned this pull request Jun 17, 2026

EIP-8282 Add builder execution requests Consensys-Incorporated/teku#10849

Merged

2 tasks

Merge branch 'master' into eip8282

f089bde

jtraglia mentioned this pull request Jun 18, 2026

Reset withdrawable epoch when depositing to an exited builder #5373

Merged

jihoonsong reviewed Jun 18, 2026

View reviewed changes

nflaig reviewed Jun 18, 2026

View reviewed changes

Comment thread tests/infra/helpers/deposit_requests.py Outdated

jtraglia marked this pull request as ready for review June 18, 2026 14:41

jtraglia added 2 commits June 18, 2026 20:06

Merge remote-tracking branch 'upstream/master' into eip8282

7049710

Cast index to BuilderIndex

ec21b6e

ethereum deleted a comment from jihoonsong Jun 18, 2026

jtraglia added 3 commits June 18, 2026 22:19

Update operations test format

347f9b7

Update DOMAIN_INCLUSION_LIST_COMMITTEE

8a73ad0

Improve testing

c15bd91

nflaig reviewed Jun 19, 2026

View reviewed changes

Comment thread specs/gloas/builder.md Outdated

Comment thread specs/gloas/builder.md Outdated

Comment thread specs/gloas/validator.md Outdated

Comment thread specs/gloas/builder.md

Apply feedback from nflaig

ed960f1

jtraglia requested a review from nflaig June 19, 2026 09:46

nflaig reviewed Jun 19, 2026

View reviewed changes

potuz reviewed Jun 19, 2026

View reviewed changes

add test for builder exit request

c84f2e4

bharath-123 mentioned this pull request Jun 19, 2026

EIP-8282: Support builder deposits and builder exits ethpandaops/buildoor#103

Merged

nflaig approved these changes Jun 19, 2026

View reviewed changes

terencechain approved these changes Jun 19, 2026

View reviewed changes

Merge branch 'master' into eip8282

bb5e31e

jtraglia merged commit bc8470b into ethereum:master Jun 19, 2026
16 checks passed

jtraglia deleted the eip8282 branch June 19, 2026 14:07

nflaig mentioned this pull request Jun 21, 2026

feat: upgrade to v1.7.0-alpha.11 spec ChainSafe/lodestar#9541

Merged

jtraglia mentioned this pull request Jul 2, 2026

Set BUILDER_WITHDRAWAL_PREFIX to 0xB0 #5416

Merged

	\| `DOMAIN_EXECUTION_PROOF` \| `DomainType('0x0F000000')` \|
	\| `DOMAIN_EXECUTION_PROOF` \| `DomainType('0x0G000000')` \|


		### Withdrawal prefixes

		Note: `BUILDER_WITHDRAWAL_PREFIX` is a temporary constant which is only used

Uh oh!

Conversation

jtraglia commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ensi321 commented Jun 17, 2026

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!

jtraglia commented Jun 17, 2026

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!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

jtraglia Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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

jtraglia commented Jun 11, 2026 •

edited

Loading

jtraglia Jun 19, 2026 •

edited

Loading