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.
GET /eth/v1/beacon/proposer_preferences — retrieval, matching the
convention used by payload_attestations, proposer_slashings, etc.
proposer_preferences SSE event for messages passing gossip validation.
Gloas.ProposerPreferences / Gloas.SignedProposerPreferences types, including
dependent_root (required for gossip dedup and signature anchoring against the
checkpoint state at epoch(proposal_slot) - 1).

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 — the external builder relay flow is
replaced by the in-protocol builder market; 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.

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

nflaig · 2026-05-27T11:19:58Z

+    Deprecated from Gloas onwards in favor of
+    `POST /eth/v1/validator/proposer_preferences`, which supersedes both fee recipient and
+    gas limit preferences. Beacon node support for this endpoint pre-Gloas is REQUIRED;
+    post-Gloas support is OPTIONAL and the endpoint MAY be removed.


I don't think we should keep supporting this endpoint going forward, ideally, we wanna get rid of it in hegota

should i reword this or is this wording fine

nflaig · 2026-05-27T11:21:31Z

@@ -0,0 +1,56 @@
+post:
+  operationId: submitSignedProposerPreferences


do we want the "signed" part in the operation id?

good question will double check other ids

they don't good catch i will remove it

…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.

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

Open

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

		@@ -0,0 +1,56 @@
		post:
		operationId: submitSignedProposerPreferences

Conversation

james-prysm commented May 19, 2026 • edited 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!

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

james-prysm commented May 19, 2026 •

edited

Loading