gloas proposer preference apis

CHANGES.md

@@ -33,6 +33,11 @@ There are likely to be descriptions etc outside of the list below, but new query
 | [#590](https://github.com/ethereum/beacon-APIs/pull/590) `head_v2 EVENT` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#590](https://github.com/ethereum/beacon-APIs/pull/590) `head EVENT` deprecated         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#598](https://github.com/ethereum/beacon-APIs/pull/598) `fast_confirmation EVENT` added                            |                                                  |                                                   |                                                    |                                                 |                                           |
+| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/proposer_preferences` added         |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `proposer_preferences EVENT` added         |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/prepare_beacon_proposer` deprecated         |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/register_validator` deprecated         |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/beacon_committee_subscriptions` updated         |                                                  |                                                  |                                                    |                                                 |                                           |
 
 The Following are no longer in the Standard API, removed since the latest version.
 

apis/eventstream/index.yaml

@@ -45,6 +45,7 @@ get:
             - execution_payload_bid
             - payload_attestation_message
             - fast_confirmation
+            - proposer_preferences
   responses:
     "200":
       description: Opened SSE stream.
@@ -194,6 +195,11 @@ get:
               value: |
                 event: fast_confirmation
                 data: {"block": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "slot": "1", "current_slot": "2"}
+            proposer_preferences:
+              description: The node has received a `SignedProposerPreferences` (from P2P or API) that passes gossip validation on the `proposer_preferences` topic
+              value: |
+                event: proposer_preferences
+                data: {"version":"gloas", "data":{"message": {"dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "proposal_slot": "32", "validator_index": "123", "fee_recipient": "0x0000000000000000000000000000000000000000", "target_gas_limit": "60000000"}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}}
     "400":
       description: "The topics supplied could not be parsed"
       content:

apis/validator/beacon_committee_subscriptions.yaml

@@ -8,6 +8,13 @@ post:
     If validator `is_aggregator`, beacon node must:
     - announce subnet topic subscription on gossipsub
     - aggregate attestations received on that subnet
+
+    Beacon nodes SHOULD use the set of validators that have submitted subscriptions via this
+    endpoint to determine which validators are using the node for duties and to calculate the
+    node's required custody group count (CGC). Validator clients SHOULD submit one entry per
+    attached active validator per attestation duty, including when multiple validators share
+    the same `(slot, committee_index)`, so the beacon node tracks every attached validator
+    rather than only one per subnet.
   tags:
     - ValidatorRequiredApi
     - Validator

apis/validator/prepare_beacon_proposer.yaml

@@ -1,7 +1,13 @@
 post:
   operationId: "prepareBeaconProposer"
   summary: Provide beacon node with proposals for the given validators.
+  deprecated: true
   description: |
+    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.
+
     Prepares the beacon node for potential proposers by supplying information
     required when proposing blocks for the given validators.  The information
     supplied for each validator index will persist through the epoch in which

apis/validator/proposer_preferences.yaml

@@ -0,0 +1,58 @@
+post:
+  operationId: submitProposerPreferences
+  summary: Submit signed proposer preferences
+  description: |
+    Verifies given signed proposer preferences and publishes them on the `proposer_preferences`
+    gossipsub topic.
+
+    Notes:
+    - 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.
+    - Until the Gloas fork activates, beacon nodes MUST continue to honor fee recipient and gas
+      limit information supplied via `POST /eth/v1/validator/prepare_beacon_proposer` and
+      `POST /eth/v1/validator/register_validator`. From the Gloas fork onwards, signed proposer
+      preferences supersede both endpoints as the source of proposer fee recipient and gas
+      limit preferences.
+    - For validators served by the beacon node, if no signed proposer preferences are available
+      for a given proposal slot, the beacon node SHOULD fall back to the parent block's gas limit
+      when preparing the local payload or accepting bids for that validator. On the p2p network,
+      bids whose fee recipient or gas limit do not match a validator's preferences are rejected at
+      gossip validation, while bids for a slot with no available preferences are ignored; applying
+      sensible defaults reduces missed proposals during the transition.
+  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."
+  tags:
+    - Validator
+    - ValidatorRequiredApi
+  requestBody:
+    description: "Array of `SignedProposerPreferences` objects to be submitted."
+    required: true
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedProposerPreferences"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `List[SignedProposerPreferences, (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH]` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "200":
+      description: "Signed proposer preferences are stored in pool and broadcasted to the network"
+    "400":
+      description: "Errors with one or more signed proposer preferences"
+      content:
+        application/json:
+          schema:
+            $ref: "../../beacon-node-oapi.yaml#/components/schemas/IndexedErrorMessage"
+    "415":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType"
+    "500":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError"

apis/validator/register_validator.yaml

@@ -1,7 +1,13 @@
 post:
   operationId: "registerValidator"
   summary: Provide beacon node with registrations for the given validators to the external builder network.
+  deprecated: true
   description: |
+    Deprecated from Gloas onwards. Under Gloas, proposer fee recipient and gas limit preferences
+    are expressed via `POST /eth/v1/validator/proposer_preferences` instead. Beacon node support
+    for this endpoint pre-Gloas is REQUIRED; post-Gloas support is OPTIONAL and the endpoint
+    MAY be removed.
+
     Prepares the beacon node for engaging with external builders. The
     information must be sent by the beacon node to the builder network. It is
     expected that the validator client will send this information periodically

beacon-node-oapi.yaml

@@ -222,6 +222,8 @@ paths:
     $ref: "./apis/validator/prepare_beacon_proposer.yaml"
   /eth/v1/validator/register_validator:
     $ref: "./apis/validator/register_validator.yaml"
+  /eth/v1/validator/proposer_preferences:
+    $ref: "./apis/validator/proposer_preferences.yaml"
   /eth/v1/validator/liveness/{epoch}:
     $ref: "./apis/validator/liveness.yaml"
   /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}:
@@ -483,6 +485,10 @@ components:
       $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestation"
     Gloas.PayloadAttestationMessage:
       $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestationMessage"
+    Gloas.ProposerPreferences:
+      $ref: "./types/gloas/proposer_preferences.yaml#/Gloas/ProposerPreferences"
+    Gloas.SignedProposerPreferences:
+      $ref: "./types/gloas/proposer_preferences.yaml#/Gloas/SignedProposerPreferences"
     Fulu.BlockContents:
       $ref: "./types/fulu/block_contents.yaml#/Fulu/BlockContents"
     Fulu.SignedBlockContents:

types/gloas/proposer_preferences.yaml

@@ -0,0 +1,31 @@
+Gloas:
+  ProposerPreferences:
+    type: object
+    description: "The [`ProposerPreferences`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/p2p-interface.md#new-proposerpreferences) object from the CL Gloas spec."
+    required: [dependent_root, proposal_slot, validator_index, fee_recipient, target_gas_limit]
+    properties:
+      dependent_root:
+        $ref: "../primitive.yaml#/Root"
+        description: "Shuffling dependent root for the epoch of `proposal_slot`, based on the validator's head."
+      proposal_slot:
+        $ref: "../primitive.yaml#/Uint64"
+        description: "Slot for which the validator is the proposer."
+      validator_index:
+        $ref: "../primitive.yaml#/Uint64"
+        description: "Index of the proposing validator."
+      fee_recipient:
+        $ref: "../primitive.yaml#/ExecutionAddress"
+        description: "Address to receive the builder payment."
+      target_gas_limit:
+        $ref: "../primitive.yaml#/Uint64"
+        description: "Preferred gas limit for the execution payload."
+
+  SignedProposerPreferences:
+    type: object
+    description: "The [`SignedProposerPreferences`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/p2p-interface.md#new-signedproposerpreferences) object from the CL Gloas spec."
+    required: [message, signature]
+    properties:
+      message:
+        $ref: "#/Gloas/ProposerPreferences"
+      signature:
+        $ref: "../primitive.yaml#/Signature"

wordlist.txt

@@ -45,4 +45,5 @@ ptc
 PtcDuty
 produceBlockV
 stateful
+CGC
 RLP