Gloas Builder-API spec updates

apis/builder/beacon_block.yaml

@@ -25,12 +25,7 @@ post:
     content:
       application/json:
         schema:
-          type: object
-          required: [data]
-          properties:
-            data:
-              $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock"
-              description: "The signed beacon block."
+          $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock"
       application/octet-stream:
         schema:
           description: "SSZ serialized `SignedBeaconBlock` bytes. Use content type header to indicate that SSZ data is contained in the request body."

apis/builder/builder_preferences.yaml

@@ -2,18 +2,19 @@ post:
   operationId: "submitBuilderPreferences"
   summary: Submit builder preferences for a proposer.
   description: |
-    Submits a proposer's `BuilderPreferencesRequest` to the builder, including
-    the `max_trusted_bid` that the proposer is willing to accept from this
-    builder, authenticated via a `SignedRequestAuth`.
+    Submits a proposer's `BuilderPreferencesRequestV1` to the builder, including
+    the `max_execution_payment` that the proposer is willing to accept from this
+    builder, authenticated via a `SignedRequestAuthV1`.
 
     Validators MAY call this endpoint in the epoch prior to the epoch in
     which they will be proposing, as determined from `state.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.builder_pubkey`
-    matches its own identity. If either check fails, the builder MUST return a
-    400 response.
+    `validator_pubkey`, and check that `auth.message.builder_url`
+    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.
 
     A success response (202) indicates that the preferences were accepted. If
     the preferences are invalid, then the builder MUST return an error response
@@ -29,18 +30,24 @@ post:
       description: "The BLS public key of the validator expressing these preferences."
       schema:
         $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
+    - name: Eth-Consensus-Version
+      in: header
+      required: false
+      description: "The active consensus version to which the request body belongs. Required if the request body is SSZ encoded."
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion"
   requestBody:
-    description: A `BuilderPreferencesRequest` containing the proposer's preferences and a `SignedRequestAuth` for authentication.
+    description: A `BuilderPreferencesRequestV1` containing the proposer's preferences and a `SignedRequestAuthV1` for authentication.
     required: true
     content:
       application/json:
         schema:
-          $ref: "../../types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequest"
+          $ref: "../../types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequestV1"
       application/octet-stream:
         schema:
-          description: "SSZ serialized `BuilderPreferencesRequest` bytes. Use content type header to indicate that SSZ data is contained in the request body."
+          description: "SSZ serialized `BuilderPreferencesRequestV1` bytes. Use content type header to indicate that SSZ data is contained in the request body."
   responses:
-    "200":
+    "202":
       description: Success response.
     "400":
       description: Error response.
@@ -49,13 +56,28 @@ post:
           schema:
             $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
           examples:
+            SlotMismatch:
+              value:
+                code: 400
+                message: "Invalid SignedRequestAuthV1: auth.message.slot does not match the requested slot"
             WrongBuilder:
               value:
                 code: 400
-                message: "auth.message.builder_pubkey does not match this builder's identity"
+                message: "auth.message.builder_url does not match this builder's URL"
             InvalidPreferences:
               value:
                 code: 400
-                message: "Invalid builder preferences: max_trusted_bid malformed"
+                message: "Invalid builder preferences: max_execution_payment malformed"
+    "401":
+      description: Authentication required.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            SignatureVerificationFailed:
+              value:
+                code: 401
+                message: "Invalid SignedRequestAuthV1: signature verification failed"
     "500":
       $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/execution_payload_bid.yaml

@@ -10,23 +10,21 @@ 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.
-    - The `X-Eth-Max-Trusted-Bid` header carrying the proposer's
-      `max_trusted_bid` (decimal `uint64`, in Gwei) for this request.
-    - Optionally, a `SignedRequestAuth` in the request body that
+    - Optionally, a `SignedRequestAuthV1` in the request body that
       authenticates the request. The body MAY be encoded as JSON
       (`Content-Type: application/json`) or SSZ
       (`Content-Type: application/octet-stream`).
 
-    The `X-Eth-Max-Trusted-Bid` header is optional. A validator MAY send it
-    if they have not already submitted a `SignedBuilderPreferences` to this
-    builder. If both are present, the stored `BuilderPreferences` takes
-    precedence over the header. If neither is present, the builder MUST treat
-    `max_trusted_bid` as `0`.
+    The proposer's `max_execution_payment` is communicated exclusively via the
+    [`submitBuilderPreferences`][submit-builder-preferences-api] 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.
 
-    The `SignedRequestAuth` body is optional. If it is present but malformed
-    or fails signature verification, the builder MAY return a 400 response.
+    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 `SignedRequestAuth` to apply
+    use the presence and validity of the `SignedRequestAuthV1` to apply
     per-validator policy (e.g. rate-limiting, prioritization, or refusing
     unauthenticated requests).
 
@@ -59,12 +57,12 @@ post:
       description: Root of the beacon block the proposer will build on.
       schema:
         $ref: "../../builder-oapi.yaml#/components/schemas/Root"
-    - name: proposer_index
+    - name: proposer_pubkey
       in: path
       required: true
-      description: Index of the proposer.
+      description: BLS public key of the proposer.
       schema:
-        $ref: "../../builder-oapi.yaml#/components/schemas/Uint64"
+        $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
     - name: Date-Milliseconds
       in: header
       required: false
@@ -92,50 +90,33 @@ post:
       in: header
       required: false
       description: |
-        The active consensus version to which the `SignedRequestAuth` in the
+        The active consensus version to which the `SignedRequestAuthV1` in the
         request body belongs. Required if the request body is SSZ encoded.
       schema:
         $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion"
-    - name: X-Eth-Max-Trusted-Bid
-      in: header
-      required: false
-      description: |
-        Optional decimal `uint64` (in Gwei) carrying the proposer's
-        `max_trusted_bid` for this request. MAY be sent if the validator has
-        not already submitted a `SignedBuilderPreferences` to this builder.
-        If a stored `BuilderPreferences` exists for this proposer, it takes
-        precedence over this header. If no `BuilderPreferences` has been
-        submitted, `bid.execution_payment` MUST NOT exceed this value.
-        A value of `0` indicates that the proposer does not accept any trusted
-        payments from this builder. A value of `2**64 - 1` (`MAX_TRUSTED_BID`)
-        indicates that the proposer accepts any trusted payment amount.
-      schema:
-        type: integer
-        format: uint64
-        example: 1000000000
   requestBody:
     description: |
-      Optional `SignedRequestAuth` authenticating the request. If provided,
+      Optional `SignedRequestAuthV1` authenticating the request. If provided,
       the builder MAY verify the BLS signature against the validator pubkey
-      resolved from the `proposer_index` path parameter, and check that
-      `builder_pubkey` matches its own identity and that `slot` matches the
+      resolved from the `proposer_pubkey` path parameter, and check that
+      `builder_url` 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
     content:
       application/json:
         schema:
-          $ref: "../../types/gloas/request_auth.yaml#/Gloas/SignedRequestAuth"
+          $ref: "../../types/gloas/request_auth.yaml#/Gloas/SignedRequestAuthV1"
       application/octet-stream:
         schema:
-          description: "SSZ serialized `SignedRequestAuth` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body. The `Eth-Consensus-Version` header MUST also be set."
+          description: "SSZ serialized `SignedRequestAuthV1` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body. The `Eth-Consensus-Version` header MUST also be set."
   responses:
     "200":
       description: Success response.
       headers:
         Eth-Consensus-Version:
           $ref: "../../builder-oapi.yaml#/components/headers/Eth-Consensus-Version"
-          required: false
+          required: true
       content:
         application/json:
           schema:
@@ -165,10 +146,14 @@ post:
               value:
                 code: 400
                 message: "Unknown hash: missing parent hash"
-            InvalidAuth:
+            SlotMismatch:
+              value:
+                code: 400
+                message: "Invalid SignedRequestAuthV1: auth.message.slot does not match the requested slot"
+            WrongBuilder:
               value:
                 code: 400
-                message: "Invalid SignedRequestAuth: signature verification failed"
+                message: "Invalid SignedRequestAuthV1: auth.message.builder_url does not match this builder's URL"
     "401":
       description: Authentication required.
       content:
@@ -179,7 +164,11 @@ post:
             MissingAuth:
               value:
                 code: 401
-                message: "Missing SignedRequestAuth: this builder requires authenticated requests"
+                message: "Missing SignedRequestAuthV1: this builder requires authenticated requests"
+            InvalidAuth:
+              value:
+                code: 401
+                message: "Invalid SignedRequestAuthV1: signature verification failed"
     "406":
       $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
     "415":

builder-oapi.yaml

@@ -53,7 +53,7 @@ paths:
     $ref: "./apis/builder/validators.yaml"
   /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey}:
     $ref: "./apis/builder/header.yaml"
-  /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{parent_root}/{proposer_index}:
+  /eth/v1/builder/execution_payload_bid/{slot}/{parent_hash}/{parent_root}/{proposer_pubkey}:
     $ref: "./apis/builder/execution_payload_bid.yaml"
   /eth/v1/builder/beacon_block:
     $ref: "./apis/builder/beacon_block.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.RequestAuth:
-      $ref: "./types/gloas/request_auth.yaml#/Gloas/RequestAuth"
-    Gloas.SignedRequestAuth:
-      $ref: "./types/gloas/request_auth.yaml#/Gloas/SignedRequestAuth"
-    Gloas.BuilderPreferences:
-      $ref: "./types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferences"
-    Gloas.BuilderPreferencesRequest:
-      $ref: "./types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequest"
+    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"
 
   responses:
     InternalError:
@@ -165,5 +165,5 @@ components:
       $ref: "./examples/fulu/signed_blinded_beacon_block.json"
     Fulu.SignedBuilderBid:
       $ref: "./examples/fulu/signed_builder_bid.json"
-    Gloas.SignedRequestAuth:
+    Gloas.SignedRequestAuthV1:
       $ref: "./examples/gloas/signed_request_auth.json"

examples/gloas/signed_request_auth.json

@@ -1,7 +1,7 @@
 {
   "value": {
     "message": {
-      "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+      "builder_url": "https://builder.example.com",
       "slot": "1"
     },
     "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"