Staked Builder API for Glamsterdam

README.md

@@ -45,8 +45,8 @@ multiplexers. Please see their respective repositories for more information:
 
 The API specification is checked for lint errors before merging pull requests.
 
-Install `uv` via curl (recommended over a pip-install as it can
-self-update and manage Python versions):
+Install `uv` via curl (recommended over a pip-install as it can self-update and
+manage Python versions):
 
 ```console
 curl -LsSf https://astral.sh/uv/install.sh | sh

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,103 @@
+get:
+  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 blinded beacon block and signed.
+
+    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 Glamsterdam 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 getBid 
+        requests to maximise block rewards. Otherwise, getBid requests will timeout and the proposer 
+        will not receive the header in time.
+      schema:
+        type: integer
+        format: int64
+        example: 10000
+  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/ExecutionPayloadBid"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `ExecutionPayloadBid` bytes. Use Accept header to choose this response type"
+    "204":
+      description: No header is available.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Unknown hash: missing parent hash"
+    "406":
+      $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/validators_v2.yaml

@@ -0,0 +1,45 @@
+post:
+  operationId: "registerValidatorV2"
+  summary: Register or update a validator's block building preferences for Gloas.
+  description: |
+    Registers a validator's preferred fee recipient, gas limit and preferences.
+
+    A success response (200) indicates that the registration was valid. If the
+    registration passes validation, then the builder MUST integrate the
+    registration into its state, such that future blocks built for the
+    validator conform to the preferences expressed in the registration. If the
+    registration is invalid, then the builder MUST return an error response
+    (400) with a description of the validation failure.
+  tags:
+    - Builder
+  requestBody:
+    description: |
+      A signed declaration of a validator's block building preferences.
+    required: true
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: "../../builder-oapi.yaml#/components/schemas/SignedValidatorRegistrationV2"
+        example:
+          $ref: "../../builder-oapi.yaml#/components/examples/SignedValidatorRegistrations/value"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `List[SignedValidatorRegistrationV2, VALIDATOR_REGISTRY_LIMIT]` bytes. Use content type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "200":
+      description: Success response.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          example:
+            code: 400
+            message: "unknown validator"
+    "415":
+      $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

builder-oapi.yaml

@@ -51,8 +51,14 @@ tags:
 paths:
   /eth/v1/builder/validators:
     $ref: "./apis/builder/validators.yaml"
+  /eth/v2/builder/validators:
+    $ref: "./apis/builder/validators_v2.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 +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"
@@ -94,6 +100,8 @@ components:
       $ref: "./types/deneb/execution_payload_and_blobs_bundle.yaml#/Deneb/ExecutionPayloadAndBlobsBundle"
     SignedValidatorRegistration:
       $ref: "./beacon-apis/types/registration.yaml#/SignedValidatorRegistration"
+    SignedValidatorRegistrationV2:
+      $ref: "./beacon-apis/types/registration.yaml#/SignedValidatorRegistrationV2"
     Electra.SignedBlindedBeaconBlock:
       $ref: "./beacon-apis/types/electra/block.yaml#/Electra/SignedBlindedBeaconBlock"
     Electra.SignedBuilderBid: