Clarifications on builder spec

apis/builder/beacon_blocks.yaml

@@ -2,16 +2,18 @@ post:
   operationId: "submitSignedBeaconBlock"
   summary: Submit a signed beacon block with the execution payload bid.
   description: |
-    Submits a `SignedBeaconBlock` to the builder, binding the proposer to the block. 
+    Submits the proposer's `SignedBeaconBlock` to the builder whose bid it
+    commits to.
+
+    This is how the builder learns that its bid won without waiting for the
+    block on gossip. The builder SHOULD help disseminate the block. The proposer
+    gossips the block itself either way, regardless of the response.
 
     A success response (202) indicates that the signed beacon block was
     valid. If the signed beacon block was invalid, then the builder
     must return an error response (400) with a description of the validation
     failure.
 
-    After receiving 202, the proposer takes no further action on the block; the 
-    builder is responsible for publishing the execution payload envelope.
-
     This API is applicable from Gloas fork onwards.
   tags:
     - Builder

apis/builder/builder_preferences.yaml

@@ -2,19 +2,21 @@ post:
   operationId: "submitBuilderPreferences"
   summary: Submit builder preferences for a proposer.
   description: |
-    Submits a proposer's `BuilderPreferencesRequestV1` to the builder, including
+    Submits a proposer's `BuilderPreferencesRequest` to the builder, including
     the `max_execution_payment` that the proposer is willing to accept from this
-    builder, authenticated via a `SignedRequestAuthV1`.
+    builder, authenticated via a `SignedBuilderRequestAuth`.
 
     Validators MAY call this endpoint in the epoch prior to the epoch in
     which they will be proposing, as determined from `state.proposer_lookahead`, so that
     builders have the preferences before the bid request arrives.
 
-    The builder MUST verify the BLS signature in `auth` against
-    `validator_pubkey`, and check that `auth.message.data`
-    matches its own URL. If the signature check fails, the builder MUST
-    return a 401 response. If the URL or slot check fails, the builder MUST
-    return a 400 response.
+    The builder MUST verify the BLS signature in `auth` against the
+    `proposer_pubkey` path parameter, and check that `auth.message.data` matches
+    the value it agreed with the proposer. `auth.message.slot` is the proposal slot the
+    preferences apply to; the builder MUST reject preferences whose slot has
+    already passed. If the signature check fails, the builder MUST return a 401
+    response. If the data or slot check fails, the builder MUST return a 400
+    response.
 
     A success response (202) indicates that the preferences were accepted. If
     the preferences are invalid, then the builder MUST return an error response
@@ -24,31 +26,31 @@ post:
   tags:
     - Builder
   parameters:
-    - name: validator_pubkey
+    - name: proposer_pubkey
       in: path
       required: true
-      description: "The BLS public key of the validator expressing these preferences."
+      description: BLS public key of the proposer.
       schema:
         $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
-    - name: Eth-Consensus-Version
-      in: header
-      required: true
-      description: "The active consensus version to which the request body belongs. Required if the request body is SSZ encoded."
+    - in: header
       schema:
         $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion"
+      required: true
+      name: Eth-Consensus-Version
+      description: "The active consensus version to which the submitted preferences belong."
   requestBody:
-    description: A `BuilderPreferencesRequestV1` containing the proposer's preferences and a `SignedRequestAuthV1` for authentication.
+    description: A `BuilderPreferencesRequest` containing the proposer's preferences and a `SignedBuilderRequestAuth` for authentication.
     required: true
     content:
       application/json:
         schema:
-          $ref: "../../types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequestV1"
+          $ref: "../../types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequest"
         examples:
-          BuilderPreferencesRequestV1:
-            $ref: "../../builder-oapi.yaml#/components/examples/Gloas.BuilderPreferencesRequestV1"
+          BuilderPreferencesRequest:
+            $ref: "../../builder-oapi.yaml#/components/examples/Gloas.BuilderPreferencesRequest"
       application/octet-stream:
         schema:
-          description: "SSZ serialized `BuilderPreferencesRequestV1` bytes. Use content type header to indicate that SSZ data is contained in the request body."
+          description: "SSZ serialized `BuilderPreferencesRequest` bytes. Use content type header to indicate that SSZ data is contained in the request body."
   responses:
     "202":
       description: Success response.
@@ -62,25 +64,27 @@ post:
             SlotMismatch:
               value:
                 code: 400
-                message: "Invalid SignedRequestAuthV1: auth.message.slot does not match the requested slot"
-            WrongBuilder:
+                message: "Invalid SignedBuilderRequestAuth: auth.message.slot has already passed"
+            DataMismatch:
               value:
                 code: 400
-                message: "auth.message.data does not match this builder's URL"
+                message: "Invalid SignedBuilderRequestAuth: auth.message.data does not match the value agreed with this builder"
             InvalidPreferences:
               value:
                 code: 400
                 message: "Invalid builder preferences: max_execution_payment malformed"
     "401":
-      description: Authentication required.
+      description: Authentication failed.
       content:
         application/json:
           schema:
             $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
           examples:
-            SignatureVerificationFailed:
+            InvalidAuth:
               value:
                 code: 401
-                message: "Invalid SignedRequestAuthV1: signature verification failed"
+                message: "Invalid SignedBuilderRequestAuth: signature verification failed"
+    "415":
+      $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType"
     "500":
       $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/execution_payload_bid.yaml

@@ -5,32 +5,37 @@ post:
     Requests a builder node to produce a valid execution payload bid, which
     can be integrated into a beacon block and signed.
 
-    The proposer sends a POST request to the builder with the following information:
+    The proposer's beacon node sends a POST request to the builder with the following information:
     - The slot for which the block should be proposed.
     - 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.
-    - Optionally, a `SignedRequestAuthV1` in the request body that
-      authenticates the request. The body MAY be encoded as JSON or SSZ.
+    - The public key of the proposer.
+    - A `SignedBuilderRequestAuth` in the request body that authenticates the
+      request.
+    - A `Date-Milliseconds` header with the send time and an `X-Timeout-Ms`
+      header with the proposer's timeout for the request.
 
     The proposer's `max_execution_payment` is communicated exclusively via the
-    `submitBuilderPreferences` endpoint. If no `BuilderPreferencesV1` have been 
-    submitted for the proposer, the builder MUST treat `max_execution_payment` as `0` 
-    and MUST NOT include an execution layer payment in the bid.
+    `submitBuilderPreferences` endpoint. Any bid the builder serves MUST honor
+    the `max_execution_payment` cap from stored preferences. Without stored
+    preferences the builder MAY serve a bid with any `execution_payment`; the
+    proposer's locally configured per-builder limits are the backstop: the
+    proposer values a bid at its `value` plus `min(execution_payment,
+    max_execution_payment)`, so payment above the cap adds nothing to the
+    bid's chances.
 
-    The `SignedRequestAuthV1` body is optional. If it is present but malformed
-    or fails signature verification, the builder MAY return a 401 response.
-    If it is absent, the builder MAY still serve a bid, but builders MAY
-    use the presence and validity of the `SignedRequestAuthV1` to apply
-    per-validator policy (e.g. rate-limiting, prioritization, or refusing
-    unauthenticated requests).
+    The `SignedBuilderRequestAuth` body is required. If the body is missing or
+    malformed, the request is invalid and the builder MUST return a 400
+    response. If its `auth.message.data` or `auth.message.slot` does not match,
+    the builder MUST return a 400 response; if its signature fails to verify,
+    the builder MUST return a 401 response. Builders MAY use the authenticated
+    identity to apply per-validator policy (e.g. rate-limiting).
 
     The builder responds with a 200 response containing an execution payload bid if it can provide one.
 
-    If the builder is unable to produce a valid execution payload bid, then
-    the builder MUST return a 204 response. If the request is invalid, then the
-    builder MUST return an error response (400) with a description of the
-    validation failure.
+    A builder that does not serve a bid MUST return a 204 response. If the
+    request is invalid, then the builder MUST return an error response (400)
+    with a description of the validation failure.
 
     This API is applicable from Gloas fork onwards.
   tags:
@@ -62,48 +67,48 @@ post:
         $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
     - name: Date-Milliseconds
       in: header
-      required: false
+      required: true
       description: |
-        Optional header containing a Unix timestamp in milliseconds representing
-        the point-in-time the request was sent. This header can be used to measure
-        latency.
+        Unix timestamp in milliseconds at which the request was sent. The
+        builder compares it with its own receive time to estimate the transit
+        delay from proposer to builder.
       schema:
         type: integer
         format: int64
         example: 1710338135000
     - name: X-Timeout-Ms
       in: header
-      required: false
+      required: true
       description: |
-        Optional header containing the proposer's timeout for the request in milliseconds.
+        The proposer's timeout for the request in milliseconds, measured from
+        `Date-Milliseconds`: the builder MUST respond by `Date-Milliseconds`
+        plus `X-Timeout-Ms`, and the proposer discards later responses.
       schema:
         type: integer
         format: int64
         example: 10000
-    - name: Eth-Consensus-Version
-      in: header
-      required: true
-      description: |
-        The active consensus version to which the `SignedRequestAuthV1` in the
-        request body belongs. Required if the request body is SSZ encoded.
+    - in: header
       schema:
         $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion"
+      required: true
+      name: Eth-Consensus-Version
+      description: "The active consensus version to which the request body belongs."
   requestBody:
     description: |
-      Optional `SignedRequestAuthV1` authenticating the request. If provided,
-      the builder MAY verify the BLS signature against the validator pubkey
-      resolved from the `proposer_pubkey` path parameter, and check that
-      `data` matches its own URL and that `slot` matches the
-      requested slot. If absent, the builder MAY still serve a bid subject
-      to its own policy.
-    required: false
+      A `SignedBuilderRequestAuth` authenticating the request. The builder MUST
+      verify the BLS signature against the validator pubkey resolved from the
+      `proposer_pubkey` path parameter, and MUST check that `auth.message.data`
+      matches the value it agreed with the proposer and that
+      `auth.message.slot` matches the `slot` path parameter (the proposal
+      slot).
+    required: true
     content:
       application/json:
         schema:
-          $ref: "../../types/gloas/request_auth.yaml#/Gloas/SignedRequestAuthV1"
+          $ref: "../../types/gloas/request_auth.yaml#/Gloas/SignedBuilderRequestAuth"
       application/octet-stream:
         schema:
-          description: "SSZ serialized `SignedRequestAuthV1` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body."
+          description: "SSZ serialized `SignedBuilderRequestAuth` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body."
   responses:
     "200":
       description: Success response.
@@ -143,26 +148,30 @@ post:
             SlotMismatch:
               value:
                 code: 400
-                message: "Invalid SignedRequestAuthV1: auth.message.slot does not match the requested slot"
-            WrongBuilder:
+                message: "Invalid SignedBuilderRequestAuth: auth.message.slot does not match the proposal slot in the request path"
+            DataMismatch:
               value:
                 code: 400
-                message: "Invalid SignedRequestAuthV1: auth.message.data does not match this builder's URL"
+                message: "Invalid SignedBuilderRequestAuth: auth.message.data does not match the value agreed with this builder"
+            MissingBody:
+              value:
+                code: 400
+                message: "Invalid request: SignedBuilderRequestAuth body is required"
+            MissingHeader:
+              value:
+                code: 400
+                message: "Invalid request: Date-Milliseconds and X-Timeout-Ms headers are required"
     "401":
-      description: Authentication required.
+      description: Authentication failed.
       content:
         application/json:
           schema:
             $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
           examples:
-            MissingAuth:
-              value:
-                code: 401
-                message: "Missing SignedRequestAuthV1: this builder requires authenticated requests"
             InvalidAuth:
               value:
                 code: 401
-                message: "Invalid SignedRequestAuthV1: signature verification failed"
+                message: "Invalid SignedBuilderRequestAuth: signature verification failed"
     "406":
       $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
     "415":

builder-oapi.yaml

@@ -61,7 +61,7 @@ paths:
     $ref: "./apis/builder/blinded_blocks.yaml"
   /eth/v2/builder/blinded_blocks:
     $ref: "./apis/builder/blinded_blocks_v2.yaml"
-  /eth/v1/builder/builder_preferences/{validator_pubkey}:
+  /eth/v1/builder/builder_preferences/{proposer_pubkey}:
     $ref: "./apis/builder/builder_preferences.yaml"
   /eth/v1/builder/status:
     $ref: "./apis/builder/status.yaml"
@@ -108,14 +108,14 @@ components:
       $ref: "./types/fulu/blobs_bundle.yaml#/Fulu/BlobsBundle"
     Fulu.ExecutionPayloadAndBlobsBundle:
       $ref: "./types/fulu/execution_payload_and_blobs_bundle.yaml#/Fulu/ExecutionPayloadAndBlobsBundle"
-    Gloas.RequestAuthV1:
-      $ref: "./types/gloas/request_auth.yaml#/Gloas/RequestAuthV1"
-    Gloas.SignedRequestAuthV1:
-      $ref: "./types/gloas/request_auth.yaml#/Gloas/SignedRequestAuthV1"
-    Gloas.BuilderPreferencesV1:
-      $ref: "./types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesV1"
-    Gloas.BuilderPreferencesRequestV1:
-      $ref: "./types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequestV1"
+    Gloas.BuilderRequestAuth:
+      $ref: "./types/gloas/request_auth.yaml#/Gloas/BuilderRequestAuth"
+    Gloas.SignedBuilderRequestAuth:
+      $ref: "./types/gloas/request_auth.yaml#/Gloas/SignedBuilderRequestAuth"
+    Gloas.BuilderPreferences:
+      $ref: "./types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferences"
+    Gloas.BuilderPreferencesRequest:
+      $ref: "./types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequest"
 
   responses:
     InternalError:
@@ -165,9 +165,9 @@ components:
       $ref: "./examples/fulu/signed_blinded_beacon_block.json"
     Fulu.SignedBuilderBid:
       $ref: "./examples/fulu/signed_builder_bid.json"
-    Gloas.SignedRequestAuthV1:
-      $ref: "./examples/gloas/signed_request_auth.json"
-    Gloas.BuilderPreferencesV1:
+    Gloas.SignedBuilderRequestAuth:
+      $ref: "./examples/gloas/signed_builder_request_auth.json"
+    Gloas.BuilderPreferences:
       $ref: "./examples/gloas/builder_preferences.json"
-    Gloas.BuilderPreferencesRequestV1:
+    Gloas.BuilderPreferencesRequest:
       $ref: "./examples/gloas/builder_preferences_request.json"

examples/gloas/builder_preferences_request.json

@@ -5,7 +5,7 @@
     },
     "auth": {
       "message": {
-        "data": "0x68747470733a2f2f6275696c6465722e6578616d706c652e636f6d",
+        "data": "0x1234567890abcdef",
         "slot": "1"
       },
       "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"

examples/gloas/signed_request_auth.json → examples/gloas/signed_builder_request_auth.json

@@ -1,7 +1,7 @@
 {
   "value": {
     "message": {
-      "data": "0x68747470733a2f2f6275696c6465722e6578616d706c652e636f6d",
+      "data": "0x1234567890abcdef",
       "slot": "1"
     },
     "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"