gloas proposer preference apis by james-prysm · Pull Request #608 · ethereum/beacon-APIs

james-prysm · 2026-05-19T21:11:34Z

Supersedes #593 with ethereum/consensus-specs#5196, ethereum/consensus-specs#5236 added

Adds the proposer preferences API for Gloas, deprecates the legacy
fee-recipient/gas-limit endpoints, and tightens beacon_committee_subscriptions for
CGC bookkeeping.

Added

POST /eth/v1/validator/proposer_preferences — VC submission of signed
preferences and publishes them on the proposer_preferences gossipsub topic.
proposer_preferences SSE event for messages passing gossip validation.
Gloas.ProposerPreferences / Gloas.SignedProposerPreferences types, including
dependent_root (used for gossip dedup and validation).

Deprecated

POST /eth/v1/validator/prepare_beacon_proposer — superseded by signed proposer
preferences. Pre-Gloas support is REQUIRED; post-Gloas the endpoint MAY be a no-op
or removed.
POST /eth/v1/validator/register_validator — fee recipient and gas limit move to
signed proposer preferences. Same pre/post-Gloas support rules apply.

Updated

POST /eth/v1/validator/beacon_committee_subscriptions — from Gloas onwards, BNs
use the subscription set to identify which validators are using the node and to
size the node's custody group count (CGC). VCs SHOULD submit one entry per
attached active validator per attestation duty, including when multiple
validators share the same (slot, committee_index), so the BN tracks every
attached validator rather than only one per subnet.

Fixes #570

…ferences

james-prysm · 2026-05-19T21:12:51Z

+            properties:
+              version:
+                type: string
+                enum: [gloas]


maybe fulu should be available too?

is there any reason not to include fulu?

the proposer preferences concept doesn't exist or make sense for Fulu, does it?

There is no fulu type for SignedProposerPreferences, so I'd just keep gloas here

yeah was just thinking from perspective of having to submit proposer preferences while still in fulu and having the ability to get what you submitted?

while the clock slot is still fulu, the proposal_slot would be in gloas, we would use the message slot anyways to determine the fork? I guess the same question exists in gossip, which uses the gloas fork digest even if messages are broadcast before the fork (at least in lodestar)

the same question exists if we wanna extend the proposer preferences in the future but I think we should always use the message slot

bharath-123 · 2026-05-21T05:51:59Z

Awesome! I ll close my PR!

rolfyone · 2026-05-25T22:26:21Z

+    From the Gloas fork onwards, beacon nodes use the set of validators that have submitted
+    subscriptions via this endpoint to identify which validators are using the node for duties,
+    and adjust the node's custody group count (CGC) accordingly. Validator clients SHOULD


historically CGC was up only, this implies it might be able to be reduced now?

No I can try to reword it. I'm just implying that we should use this as a replacement to prepare beacon proposer endpoint for cgc purposes.

rolfyone · 2026-05-25T22:29:44Z

+    - For validators served by the beacon node, if no signed proposer preferences are available
+      for a given proposal slot, the beacon node MAY fall back to its configured default fee
+      recipient and target gas limit when constructing or accepting bids for that validator.
+      Bids whose fee recipient or gas limit do not match a validator's preferences will be
+      rejected at gossip validation, so applying sensible local defaults reduces missed
+      proposals during the transition.


should (vs may) fall back? what would be the alternative?

zeroed out i guess, in a sense that is also a local default so i'll change it to should

rolfyone · 2026-05-25T22:31:32Z

 produceBlockV
 stateful
+CGC
+dedup


dedup is a horrible horrible word, can we just spell de-duplicate out instead?

michaelsproul · 2026-05-26T01:00:39Z

@@ -0,0 +1,47 @@
+get:
+  operationId: getPoolProposerPreferences


A bit pedantic of me, but I find it strange that there is a pool API for a message type that is not included in blocks. In my mind the /pool APIs are for messages that can be packed into blocks like attestations, payload attestations, sync committee messages, etc.

Separately, why do beacon nodes have to store these messages at all? My understanding is that they exist mainly for the sake of builders, so there is limited value in a beacon node keeping track of them after validation (aside from the minimal amount of data that is required to be tracked to detect duplicates).

I guess builders mostly use the SSE event, but also load from this pool to catch up on any events that happened in the recent past prior to their subscription starting?

Yeah the SSE event is the most important one. I guess its not so important to catch up on any events cause the preferences are gossiped every epoch. So in the worse case a builder would have to wait 2 epochs before building their blocks which I think is fine?

should i remove it from the pool namespace? i can do that. i just didn't think it should be under validator, the original proposal from bharath was under pool.

waiting for some more opinions here I can remove the endpoint in general if not very useful

Separately, why do beacon nodes have to store these messages at all?

we do need to store them to be able to validate bids against target gas limit and fee recipient of the proposer

A bit pedantic of me, but I find it strange that there is a pool API for a message type that is not included in blocks.

in lodestar we currently call this ProposerPreferencesPool, but we can think about renaming this if we wanna keep that notion to only use pool for messages that are included in blocks

for now i removed it from the pools namespace as suggested

I'm not sure I see the utility of it either.

I removed it

nflaig

just some initial comments, haven't done an in-depth review yet

nflaig · 2026-05-27T11:05:08Z

+            properties:
+              version:
+                type: string
+                enum: [gloas]


There is no fulu type for SignedProposerPreferences, so I'd just keep gloas here

nflaig · 2026-05-27T11:14:46Z

+                  $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedProposerPreferences"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `List[SignedProposerPreferences]` bytes. Use Accept header to choose this response type"


List requires a limit, need to think more about what the right limit here is, technically you can have proposer preferences from different branches, so 2 * SLOTS_PER_EPOCH might not be sufficient

nflaig · 2026-05-27T11:16:55Z

@@ -0,0 +1,47 @@
+get:
+  operationId: getPoolProposerPreferences


Separately, why do beacon nodes have to store these messages at all?

we do need to store them to be able to validate bids against target gas limit and fee recipient of the proposer

A bit pedantic of me, but I find it strange that there is a pool API for a message type that is not included in blocks.

in lodestar we currently call this ProposerPreferencesPool, but we can think about renaming this if we wanna keep that notion to only use pool for messages that are included in blocks

…n-APIs into proposer-preferences-apis

james-prysm · 2026-05-28T16:55:27Z

updated wording to fall back to parent gas limit

syjn99 · 2026-06-02T12:06:19Z

+  parameters:
+    - in: header
+      schema:
+        $ref: "../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion"
+      required: true
+      name: Eth-Consensus-Version
+      description: "The active consensus version to which the signed proposer preferences being submitted belongs."


Do we need to enforce the consensus version here?

that's required to make the endpoint forward compatible, otherwise if SignedProposerPreferences format changes in the future (eg. in heze) you cannot signal to the receiver what's the data format you are sending (required by receiver to decode the data), the receiver could always compute it from the current clock slot in the case here, but since proposer preferences should be send 1 epoch before the fork (due to epoch lookahead), that's not a good option either.

… contention

…n-APIs into proposer-preferences-apis

**What type of PR is this?** Feature **What does this PR do? Why is it needed?** - adding /eth/v1/validator/proposer_preferences POST endpoint, also hooks up validator client - adding `proposer_preferences` SSE event topic on /eth/v1/events kurtosis setup ``` participants: - el_type: ethrex el_image: ethpandaops/ethrex:glamsterdam-devnet-4 el_extra_params: - --http.api=eth,net,web3,admin cl_type: prysm cl_image: gcr.io/offchainlabs/prysm/beacon-chain:latest vc_image: gcr.io/offchainlabs/prysm/validator:latest supernode: true count: 2 cl_extra_params: - --subscribe-all-subnets - --verbosity=debug vc_extra_params: - --enable-beacon-rest-api - --verbosity=debug - el_type: ethrex el_image: ethpandaops/ethrex:glamsterdam-devnet-4 el_extra_params: - --http.api=eth,net,web3,admin cl_type: prysm cl_image: gcr.io/offchainlabs/prysm/beacon-chain:latest vc_image: gcr.io/offchainlabs/prysm/validator:latest validator_count: 63 cl_extra_params: - --verbosity=debug vc_extra_params: - --enable-beacon-rest-api - --verbosity=debug network_params: fulu_fork_epoch: 0 gloas_fork_epoch: 2 seconds_per_slot: 6 genesis_delay: 40 additional_services: - dora global_log_level: debug ``` depends on OffchainLabs#16421 + adding some connection changes for ptc duties for more perfect run otherwise you will see some orphans **Which issues(s) does this PR fix?** implements ethereum/beacon-APIs#608 changes note: this pr does not implement deprecation or the get proposer preferences endpoint **Other notes for review** **Acknowledgements** - [x] I have read [CONTRIBUTING.md](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md). - [x] I have included a uniquely named [changelog fragment file](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md#maintaining-changelogmd). - [x] I have added a description with sufficient context for reviewers to understand this PR. - [x] I have tested that my changes work as expected and I added a testing plan to the PR description (if applicable). --------- Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com>

nflaig

LGTM, I really like all the notes for implementers, great work, thanks @james-prysm

**What type of PR is this?** Feature **What does this PR do? Why is it needed?** adds missed ssz support from ethereum/beacon-APIs#608 pr, and defaults validator client to use ssz for proposer preferences **Which issue(s) does this PR fix?** addresses partially ethereum/beacon-APIs#608 **Other notes for review** **Acknowledgements** - [x] I have read [CONTRIBUTING.md](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md). - [x] I have included a uniquely named [changelog fragment file](https://github.com/prysmaticlabs/prysm/blob/develop/CONTRIBUTING.md#maintaining-changelogmd). - [x] I have added a description with sufficient context for reviewers to understand this PR. - [ ] I have tested that my changes work as expected and I added a testing plan to the PR description (if applicable). --------- Co-authored-by: Jun Song <87601811+syjn99@users.noreply.github.com>

As per ethereum/beacon-APIs#608 > Validator clients SHOULD begin submitting signed proposer preferences one epoch before the Gloas fork activates, so the proposer preference caches kept by both beacon nodes and builders are warm at the fork boundary, letting builders prepare valid bids for the first Gloas slots. Also related to ethereum/consensus-specs#4947 but we already do this since we subscribe to new gossip topics 2 epochs before the fork (`SUBSCRIPTIONS_LOOKAHEAD_EPOCHS = 2`).

adding new endpoints and deprecating old ones related to proposer pre…

16e1fcb

…ferences

james-prysm added the Gloas api's needed in Gloas fork. label May 19, 2026

james-prysm commented May 19, 2026

View reviewed changes

james-prysm added 2 commits May 19, 2026 16:15

adding to word list for spell checker

73f359b

changing gas limit field name due to ethereum/consensus-specs#5236

1e03e0b

bharath-123 mentioned this pull request May 21, 2026

add proposer preferences related api specifications #593

Closed

james-prysm mentioned this pull request May 22, 2026

proposer preference rest OffchainLabs/prysm#16835

Merged

4 tasks

rolfyone reviewed May 25, 2026

View reviewed changes

michaelsproul reviewed May 26, 2026

View reviewed changes

paul's suggestions

d14f893

nflaig reviewed May 27, 2026

View reviewed changes

james-prysm and others added 5 commits May 27, 2026 11:30

removed signed naming

53f7a71

removing proposer preferences from pool namespace

1a70969

Merge branch 'master' into proposer-preferences-apis

c99125d

fall back to parent gas limit instead of local default

d21bb6c

Merge branch 'proposer-preferences-apis' of github.com:ethereum/beaco…

a61176d

…n-APIs into proposer-preferences-apis

syjn99 reviewed Jun 2, 2026

View reviewed changes

rolfyone and others added 3 commits June 8, 2026 10:07

Merge branch 'master' into proposer-preferences-apis

83ee090

removing get proposer preferences endpoint for now as it's a point of…

2660727

… contention

Merge branch 'proposer-preferences-apis' of github.com:ethereum/beaco…

4fc204a

…n-APIs into proposer-preferences-apis

james-prysm mentioned this pull request Jun 9, 2026

All Core Devs - Consensus (ACDC) #180, June 11 2026 ethereum/pm#2113

Closed

4 tasks

zilm13 mentioned this pull request Jun 10, 2026

Gloas proposer preference APIs Consensys/teku#10819

Open

6 tasks

Merge branch 'master' into proposer-preferences-apis

2190cc5

james-prysm requested review from nflaig and tersec June 16, 2026 02:23

nflaig added 4 commits June 28, 2026 06:36

update descriptions of type

8000110

update prepare beacon committee subnet note

add85ae

should --> SHOULD

a30e246

remove changelog entry

f267c92

nflaig reviewed Jun 28, 2026

View reviewed changes

target_gas_limit example nit

eeaad77

nflaig reviewed Jun 28, 2026

View reviewed changes

Comment thread apis/validator/proposer_preferences.yaml Outdated

james-prysm and others added 11 commits June 28, 2026 20:27

small nit for wording

ed61b2b

fixing minor wording issues

6cb794b

clarifying p2p fallback notes

8b3235e

Merge branch 'master' into proposer-preferences-apis

40f7045

formatting

1061e7b

move description below

b762015

update register validator deprecation note

300692f

adding further clarification

a1bf8d2

formatting

2924c4d

Merge branch 'master' into proposer-preferences-apis

a6031e7

re-add beacon_committee_subscriptions updated changelog

524923e

nflaig approved these changes Jun 29, 2026

View reviewed changes

nflaig merged commit 31140d7 into master Jun 29, 2026
3 checks passed

nflaig deleted the proposer-preferences-apis branch June 29, 2026 16:31

nflaig mentioned this pull request Jun 29, 2026

Deprecate prepareBeaconProposer, consolidate on registerValidator. #435

Open

lodekeeper mentioned this pull request Jun 29, 2026

feat: add proposer preferences API spec for Gloas (ePBS) lodekeeper/beacon-APIs#1

Closed

james-prysm mentioned this pull request Jun 29, 2026

adding ssz support for proposer preferences OffchainLabs/prysm#17054

Merged

4 tasks

This was referenced Jun 30, 2026

feat: align proposer preferences api with latest spec ChainSafe/lodestar#9570

Open

feat: broadcast proposer preferences before the gloas fork ChainSafe/lodestar#9571

Merged

Zyra-V21 mentioned this pull request Jul 2, 2026

Add SSZ response support for validator_balances endpoints #622

Merged

Tomi-3-0 mentioned this pull request Jul 3, 2026

add proposer preferences SSE event and submission endpoint status-im/nimbus-eth2#8696

Merged

Uh oh!

Conversation

james-prysm commented May 19, 2026 • edited by nflaig Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Added

Deprecated

Updated

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!

bharath-123 commented May 21, 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!

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!

Choose a reason for hiding this comment

Uh oh!

nflaig left a comment

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!

james-prysm commented May 28, 2026

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!

nflaig left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

james-prysm commented May 19, 2026 •

edited by nflaig

Loading