Staked Builder API for Glamsterdam

apis/builder/beacon_block.yaml

@@ -0,0 +1,47 @@
+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. 
+
+    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.
+
+    This API is applicable from Gloas fork onwards.
+  tags:
+    - Builder
+  parameters:
+    - in: header
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/ConsensusVersion"
+      required: false
+      name: Eth-Consensus-Version
+      description: "The active consensus version to which the block being submitted belongs. Required if request is SSZ encoded."
+  requestBody:
+    description: A `SignedBeaconBlock`.
+    required: true
+    content:
+      application/json:
+        schema:
+          $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."
+  responses:
+    "202":
+      description: Success response.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "Invalid signed beacon block: missing signature"
+    "415":
+      $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/builder_preferences.yaml

@@ -0,0 +1,83 @@
+post:
+  operationId: "submitBuilderPreferences"
+  summary: Submit builder preferences for a proposer.
+  description: |
+    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_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
+    (400) with a description of the validation failure.
+
+    This API is applicable from Gloas fork onwards.
+  tags:
+    - Builder
+  parameters:
+    - name: validator_pubkey
+      in: path
+      required: true
+      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 `BuilderPreferencesRequestV1` containing the proposer's preferences and a `SignedRequestAuthV1` for authentication.
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "../../types/gloas/builder_preferences.yaml#/Gloas/BuilderPreferencesRequestV1"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `BuilderPreferencesRequestV1` bytes. Use content type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "202":
+      description: Success response.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          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_url does not match this builder's URL"
+            InvalidPreferences:
+              value:
+                code: 400
+                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

@@ -0,0 +1,177 @@
+post:
+  operationId: "getExecutionPayloadBid"
+  summary: Get an execution payload bid.
+  description: |
+    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 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
+      (`Content-Type: application/json`) or SSZ
+      (`Content-Type: application/octet-stream`).
+
+    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 `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 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.
+
+    This API is applicable from Gloas fork onwards.
+  tags:
+    - Builder
+  parameters:
+    - name: slot
+      in: path
+      required: true
+      description: The slot for which the block should be proposed.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Uint64"
+    - name: parent_hash
+      in: path
+      required: true
+      description: Hash of execution layer block the proposer will build on.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Root"
+    - name: parent_root
+      in: path
+      required: true
+      description: Root of the beacon block the proposer will build on.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Root"
+    - name: proposer_pubkey
+      in: path
+      required: true
+      description: BLS public key of the proposer.
+      schema:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
+    - name: Date-Milliseconds
+      in: header
+      required: false
+      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.
+      schema:
+        type: integer
+        format: int64
+        example: 1710338135000
+    - name: X-Timeout-Ms
+      in: header
+      required: false
+      description: |
+        Optional header containing the proposer's timeout for the request in milliseconds.
+        Builders should use this header to adjust the amount of time by which they delay the
+        requests to maximise block rewards. Otherwise, requests will timeout and the proposer
+        will not receive the header in time.
+      schema:
+        type: integer
+        format: int64
+        example: 10000
+    - name: Eth-Consensus-Version
+      in: header
+      required: false
+      description: |
+        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"
+  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
+      `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/SignedRequestAuthV1"
+      application/octet-stream:
+        schema:
+          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: true
+      content:
+        application/json:
+          schema:
+            title: GetExecutionPayloadBidResponse
+            type: object
+            required: [version, data]
+            properties:
+              version:
+                type: string
+                enum: [ gloas ]
+                example: "gloas"
+              data:
+                $ref: "../../beacon-apis/types/gloas/execution_payload_bid.yaml#/Gloas/SignedExecutionPayloadBid"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `SignedExecutionPayloadBid` bytes. Use Accept header to choose this response type"
+    "204":
+      description: No bid is available.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidHash:
+              value:
+                code: 400
+                message: "Unknown hash: missing parent hash"
+            SlotMismatch:
+              value:
+                code: 400
+                message: "Invalid SignedRequestAuthV1: auth.message.slot does not match the requested slot"
+            WrongBuilder:
+              value:
+                code: 400
+                message: "Invalid SignedRequestAuthV1: auth.message.builder_url does not match this builder's URL"
+    "401":
+      description: Authentication required.
+      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"
+    "406":
+      $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
+    "415":
+      $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

builder-oapi.yaml

@@ -53,10 +53,16 @@ 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_pubkey}:
+    $ref: "./apis/builder/execution_payload_bid.yaml"
+  /eth/v1/builder/beacon_block:
+    $ref: "./apis/builder/beacon_block.yaml"
   /eth/v1/builder/blinded_blocks:
     $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}:
+    $ref: "./apis/builder/builder_preferences.yaml"
   /eth/v1/builder/status:
     $ref: "./apis/builder/status.yaml"
 
@@ -72,7 +78,7 @@ components:
       $ref: "./beacon-apis/types/http.yaml#/ErrorMessage"
     ConsensusVersion:
       $ref: "./beacon-apis/beacon-node-oapi.yaml#/components/schemas/ConsensusVersion"
-      enum: [bellatrix, capella, deneb, electra, fulu]
+      enum: [bellatrix, capella, deneb, electra, fulu, gloas]
       example: "bellatrix"
     Bellatrix.ExecutionPayload:
       $ref: "./beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload"
@@ -102,7 +108,15 @@ 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"
+
   responses:
     InternalError:
       $ref: "./types/http.yaml#/InternalError"
@@ -151,3 +165,5 @@ 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"

examples/gloas/signed_request_auth.json

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