Staked Builder API for Glamsterdam

apis/builder/beacon_block.yaml

@@ -0,0 +1,50 @@
+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 (200) 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.
+  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:
+          type: object
+          required: [data]
+          properties:
+            data:
+              $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock"
+              description: "The signed beacon block."
+      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/execution_payload_bid.yaml

@@ -0,0 +1,188 @@
+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.
+    - 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
+      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 required. If it is missing or
+    malformed, the builder MUST NOT serve a bid for the proposer and MUST
+    return a 400 response.
+
+    The `SignedRequestAuth` body is optional. If it is present but malformed
+    or fails signature verification, the builder MAY return a 400 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
+    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_index
+      in: path
+      required: true
+      description: Index of the proposer.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Uint64"
+    - 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 `SignedRequestAuth` 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: true
+      description: |
+        Decimal `uint64` (in Gwei) carrying the proposer's `max_trusted_bid`
+        for this request. `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. If the header is missing or malformed, the builder
+        MUST return a 400 response.
+      schema:
+        type: integer
+        format: uint64
+        example: 1000000000
+  requestBody:
+    description: |
+      Optional `SignedRequestAuth` 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
+      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"
+      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."
+  responses:
+    "200":
+      description: Success response.
+      headers:
+        Eth-Consensus-Version:
+          $ref: "../../builder-oapi.yaml#/components/headers/Eth-Consensus-Version"
+          required: false
+      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"
+            InvalidAuth:
+              value:
+                code: 400
+                message: "Invalid SignedRequestAuth: signature verification failed"
+            MissingMaxTrustedBid:
+              value:
+                code: 400
+                message: "Missing X-Eth-Max-Trusted-Bid header"
+    "401":
+      description: Authentication required.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            MissingAuth:
+              value:
+                code: 401
+                message: "Missing SignedRequestAuth: this builder requires authenticated requests"
+    "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,6 +53,10 @@ 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}:
+    $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:
@@ -72,7 +76,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 +106,11 @@ 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"
+
   responses:
     InternalError:
       $ref: "./types/http.yaml#/InternalError"
@@ -151,3 +159,5 @@ components:
       $ref: "./examples/fulu/signed_blinded_beacon_block.json"
     Fulu.SignedBuilderBid:
       $ref: "./examples/fulu/signed_builder_bid.json"
+    Gloas.SignedRequestAuth:
+      $ref: "./examples/gloas/signed_request_auth.json"

examples/gloas/signed_request_auth.json

@@ -0,0 +1,9 @@
+{
+  "value": {
+    "message": {
+      "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+      "slot": "1"
+    },
+    "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
+  }
+}