updates to api

Author: bharath-123

apis/builder/execution_payload_bid.yaml

@@ -10,7 +10,7 @@ post:
     - The hash of the execution layer block the proposer will build on.
     - The root of the beacon block the proposer will build on.
     - The index of the proposer.
-    - A signed bid request auth using the builder's on-chain index to authenticate the request.
+    - A signed request auth containing the builder's public key and slot to authenticate the request.
 
     The builder responds with a 200 response containing an execution payload bid if it can provide one.
 

apis/builder/preferences.yaml

@@ -21,18 +21,15 @@ post:
     - Builder
   requestBody:
     description: |
-      Signed per-builder preferences, along with signed request authentication.
+      Signed per-builder preferences.
     required: true
     content:
       application/json:
         schema:
           type: object
           required:
-            - signed_request_auth
             - preferences
           properties:
-            signed_request_auth:
-              $ref: "../../builder-oapi.yaml#/components/schemas/Gloas.SignedRequestAuth"
             preferences:
               type: array
               items:
@@ -41,7 +38,7 @@ post:
           $ref: "../../builder-oapi.yaml#/components/examples/Gloas.SignedBuilderPreferences"
       application/octet-stream:
         schema:
-          description: "SSZ serialized `Container[SignedRequestAuth, List[SignedBuilderPreferences, VALIDATOR_REGISTRY_LIMIT]]` bytes. Use content type header to indicate that SSZ data is contained in the request body."
+          description: "SSZ serialized `List[SignedBuilderPreferences, VALIDATOR_REGISTRY_LIMIT]` bytes. Use content type header to indicate that SSZ data is contained in the request body."
   responses:
     "200":
       description: Success response.

examples/gloas/signed_builder_preferences.json

@@ -1,15 +1,10 @@
 {
     "value": {
-      "signed_request_auth": {
-        "message": {
-          "builder_index": "0x2a"
-        },
-        "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
-      },
       "preferences": [
         {
           "message": {
             "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+            "slot": "32",
             "max_trusted_bid": "1000000000000000000"
           },
           "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"

examples/gloas/signed_request_auth.json

@@ -1,7 +1,8 @@
 {
   "value": {
     "message": {
-      "builder_index": "0x2a"
+      "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+      "slot": "1"
     },
     "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
   }

specs/gloas/builder.md

@@ -31,8 +31,8 @@ describes how builders interact with validators through
 
 ## Constants
 
-| Name | Value |
-| ----------------------------------------- | ------------------ |
+| Name              | Value       |
+| ----------------- | ----------- |
 | `MAX_TRUSTED_BID` | `2**64 - 1` |
 
 ## Containers
@@ -44,6 +44,7 @@ describes how builders interact with validators through
 ```python
 class BuilderPreferences(Container):
     builder_pubkey: BLSPubkey
+    slot: Slot
     max_trusted_bid: uint64
 ```
 
@@ -62,7 +63,9 @@ class SignedBuilderPreferences(Container):
 
 ```python
 def verify_builder_preferences_signature(
-    state: BeaconState, signed_preferences: SignedBuilderPreferences, validator_index: ValidatorIndex
+    state: BeaconState,
+    signed_preferences: SignedBuilderPreferences,
+    validator_index: ValidatorIndex,
 ) -> bool:
     validator = state.validators[validator_index]
     pubkey = validator.pubkey
@@ -117,14 +120,14 @@ def is_eligible_for_bid(
 
 Validators send per-builder preferences directly to the builder via the
 [`submitBuilderPreferences`][submit-builder-preferences-api] API call. This
-allows a proposer to express trust preferences for a specific builder. Currently,
-the only preference that is supported is:
+allows a proposer to express trust preferences for a specific builder.
+Currently, the only preference that is supported is:
 
 - `max_trusted_bid`: Specifies the maximum value (in Gwei) that a proposer is
   willing to accept as a trusted execution layer payment from the builder. A
   value of `0` indicates that the proposer does not accept any trusted payments
-  from the builder, requiring all payments to be cryptographically verifiable
-  on-chain. A value of `MAX_TRUSTED_BID` indicates that the proposer will accept
+  from the builder, requiring all payments to use the on-chain trustless payments mechanism.
+  A value of `MAX_TRUSTED_BID` indicates that the proposer will accept
   any trusted payment amount from the builder. Proposers may adjust this
   parameter based on their level of trust in the builder's reliability and
   reputation.
@@ -134,12 +137,14 @@ for.
 
 ## Proposer Preferences (Deprecation of Validator Registrations)
 
-*Note*: `ValidatorRegistrationV2` is **deprecated** in favour of
+*Note*: `ValidatorRegistrationV1` is **deprecated** in favour of
 [`ProposerPreferences`][proposer-preferences] from the consensus specs.
 
-Builders SHOULD subscribe to the [`proposer_preferences`][proposer-preferences-topic]
-gossip topic to learn about a validator's general preferences for upcoming
-proposal slots. The `ProposerPreferences` message contains:
+Builders SHOULD subscribe to the
+[`proposer_preferences`][proposer-preferences-topic] gossip topic to learn about
+a validator's general preferences. Validators broadcast these messages at the
+beginning of each epoch for their proposal slots in the next epoch. The
+`ProposerPreferences` message contains:
 
 - `validator_index`: The index of the validator proposing.
 - `fee_recipient`: The execution layer address where fees should go.
@@ -177,7 +182,9 @@ def process_builder_preferences(
     # (implementation specific check)
 
     # Verify builder preferences signature
-    assert verify_builder_preferences_signature(state, signed_preferences, validator_index)
+    assert verify_builder_preferences_signature(
+        state, signed_preferences, validator_index
+    )
 ```
 
 ## Constructing a `SignedExecutionPayloadBid`

specs/gloas/validator.md

@@ -33,7 +33,7 @@ Validators request a [`SignedExecutionPayloadBid`][signed-execution-payload-bid]
 from the external builder network to put it in their `SignedBeaconBlock`. The
 external builder network broadcasts the
 [`SignedExecutionPayloadEnvelope`][signed-execution-payload-envelope]
-corresponding to the bid to the PTC committee.
+corresponding to the included bid to the PTC committee.
 
 ## Containers
 
@@ -46,7 +46,8 @@ that other builders do not DDOS or run replay attacks on the builder.
 
 ```python
 class RequestAuth(Container):
-    builder_index: BuilderIndex
+    builder_pubkey: BLSPubkey
+    slot: Slot
 ```
 
 #### `SignedRequestAuth`
@@ -63,43 +64,42 @@ class SignedRequestAuth(Container):
 
 To construct the `RequestAuth`, we need to fill the following information:
 
-- `builder_index`: This is the on-chain index associated with the builder.
+- `builder_pubkey`: The BLS public key of the builder the request is intended for.
+- `slot`: The slot for which the bid is being requested.
 
 The validator constructs the `SignedRequestAuth` by signing the `RequestAuth`.
 It sends the `SignedRequestAuth` in the request body along with the request to
 get the bid in the [`getExecutionPayloadBid`][get-execution-payload-bid-api] API
-call. It also sends the `SignedRequestAuth` in the
-[`submitBuilderPreferences`][submit-builder-preferences-api] to avoid replay
-attacks. A builder could send the preferences to another builder and make them do
-unnecessary work.
+call.
 
 ## Proposer Preferences
 
-*Note*: Validator registrations (`ValidatorRegistrationV2`) are **deprecated** in
-favour of [`ProposerPreferences`][proposer-preferences] from the consensus specs.
+*Note*: Validator registrations (`ValidatorRegistrationV1`) are **deprecated**
+in favour of [`ProposerPreferences`][proposer-preferences] from the consensus
+specs.
 
 General validator preferences are now communicated via the
 [`proposer_preferences`][proposer-preferences-topic] gossip topic defined in the
-[Gloas consensus specs][gloas-consensus-specs]. Validators broadcast
-[`SignedProposerPreferences`][proposer-preferences] messages at the beginning of
-each epoch containing:
+[Gloas consensus specs][gloas-consensus-specs]. At the beginning of each epoch,
+validators broadcast [`SignedProposerPreferences`][proposer-preferences] messages
+for their proposal slots in the next epoch containing:
 
 - `fee_recipient`: An execution layer address where fees for the validator
   should go.
 - `gas_limit`: The value a validator prefers for the execution block gas limit.
 - `validator_index`: The validator's index.
-- `proposal_slot`: The slot in which the validator will be proposing. This can be
-  looked up in `state.proposer_lookahead`.
+- `proposal_slot`: The slot in which the validator will be proposing. This can
+  be looked up in `state.proposer_lookahead`.
 
 Builders SHOULD subscribe to this gossip topic to learn about proposer
 preferences for upcoming slots.
 
 ## Builder Preferences
 
 For per-builder preferences that cannot be communicated via a global gossip
-topic, validators send [`SignedBuilderPreferences`][builder-preferences] directly
-to the builder via the [`submitBuilderPreferences`][submit-builder-preferences-api]
-API call.
+topic, validators send [`SignedBuilderPreferences`][builder-preferences]
+directly to the builder via the
+[`submitBuilderPreferences`][submit-builder-preferences-api] API call.
 
 ### Constructing the `BuilderPreferences`
 
@@ -108,23 +108,28 @@ To construct the `BuilderPreferences`, the validator client assembles a
 
 - `builder_pubkey`: The BLS public key of the builder that these preferences are
   intended for.
+- `slot`: The proposal slot of the validator. This can be looked up in
+  `state.proposer_lookahead`.
 - `max_trusted_bid`: The amount (in Gwei) the proposer is willing to accept as a
   trusted execution layer payment from the builder.
 
 ### Builder Preferences dissemination
 
 Validators send builder preferences to each builder they wish to interact with
-for their upcoming proposal slots. Validators run
-`create_builder_preferences` at every epoch boundary to create builder
-preferences for all the builders they trust.
+for their upcoming proposal slots. Validators run `create_builder_preferences`
+in the epoch prior to the epoch in which the validator will become a proposer,
+using the `proposer_lookahead` in the beacon state to determine their proposal
+slots.
 
 ```python
 def create_builder_preferences(
     builder_pubkey: BLSPubkey,
+    slot: Slot,
     max_trusted_bid: uint64,
 ) -> BuilderPreferences:
     return BuilderPreferences(
         builder_pubkey=builder_pubkey,
+        slot=slot,
         max_trusted_bid=max_trusted_bid,
     )
 ```
@@ -175,9 +180,9 @@ builder pays the validator via execution layer payments, we require that the
 bid's fee recipient matches the validators expected fee recipient and not the
 builder's fee recipient.
 
-To express per-builder preferences we need validators to remember which
-builder preferences they have sent to each builder, so that they can validate
-whether the bid conforms to the preferences expressed by the validators.
+To express per-builder preferences we need validators to remember which builder
+preferences they have sent to each builder, so that they can validate whether
+the bid conforms to the preferences expressed by the validators.
 
 ## Block proposal
 
@@ -200,10 +205,8 @@ block on top of a beacon `state` must take the following actions:
 3. The proposer returns the `SignedBeaconBlock` back to the upstream block
    building software via [`submitSignedBeaconBlock`][submit-signed-beacon-block]
    API call.
-4. The upstream block building software constructs the
-   [`SignedExecutionPayloadEnvelope`][signed-execution-payload-envelope]
-   corresponding to the
-   [`SignedExecutionPayloadBid`][signed-execution-payload-bid] and broadcasts it
+4. The upstream block building software constructs the corresponding
+   [`SignedExecutionPayloadEnvelope`][signed-execution-payload-envelope] and broadcasts it
    to the PTC committee.
 
 ## Liveness failsafe

types/gloas/preferences.yaml

@@ -2,11 +2,14 @@ Gloas:
   BuilderPreferences:
     type: object
     description: "Per-builder preferences that a validator can express to a specific builder."
-    required: [builder_pubkey, max_trusted_bid]
+    required: [builder_pubkey, slot, max_trusted_bid]
     properties:
       builder_pubkey:
         $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
         description: "The BLS public key of the builder that these preferences are intended for."
+      slot:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Uint64"
+        description: "The proposal slot of the validator."
       max_trusted_bid:
         $ref: "../../beacon-apis/types/primitive.yaml#/Uint64"
         description: "Indicates the maximum amount that a proposer is willing to accept as a trusted payment amount from the builder."

types/gloas/request_auth.yaml

@@ -1,12 +1,14 @@
 Gloas:
   RequestAuth:
     type: object
-    required: [builder_index]
+    required: [builder_pubkey, slot]
     properties:
-      builder_index:
-        type: string
-        pattern: "^0x[a-fA-F0-9]{1,16}$"
-        description: "The on-chain index associated with the builder, represented as a hex string."
+      builder_pubkey:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
+        description: "The BLS public key of the builder the request is intended for."
+      slot:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Uint64"
+        description: "The slot for which the bid is being requested."
   SignedRequestAuth:
     type: object
     required: [message, signature]