Unstaked Builder API

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/block_and_envelope.yaml

@@ -0,0 +1,82 @@
+post:
+  operationId: "submitBlockAndEnvelope"
+  summary: Submit a signed beacon block and blinded execution payload envelope.
+  description: |
+    Submits a `SignedBeaconBlock` and a `SignedBlindedExecutionPayloadEnvelope` to an
+    unstaked builder, binding the proposer to the block.
+
+    The validator sends the following:
+    - A `SignedBeaconBlock` containing the `ExecutionPayloadBid` from the builder
+    - A `SignedBlindedExecutionPayloadEnvelope` with:
+      - `beacon_block_root`: The root of the signed beacon block
+      - `payload_root`: The root of the execution payload
+      - `execution_requests_root`: The root of the execution requests
+      - `blob_kzg_commitments_root`: The root of the blob KZG commitments
+      - `builder_index`: Set to `BUILDER_INDEX_SELF_BUILD`
+      - `slot`: The slot of the block
+      - `state_root`: The post-state root
+
+    A success response (202) indicates that the submission was valid. The builder will:
+    1. Validate the beacon block and blinded envelope
+    2. Construct the full `SignedExecutionPayloadEnvelope` by unblinding the payload
+    3. Broadcast the `SignedExecutionPayloadEnvelope` to the PTC committee
+
+    If the submission 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 for unstaked builders.
+  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` and `SignedBlindedExecutionPayloadEnvelope`.
+    required: true
+    content:
+      application/json:
+        schema:
+          title: BlockAndBlindedEnvelopeRequest
+          type: object
+          required: [signed_beacon_block, signed_blinded_envelope]
+          properties:
+            signed_beacon_block:
+              $ref: "../../beacon-apis/types/gloas/block.yaml#/Gloas/SignedBeaconBlock"
+              description: "The signed beacon block containing the ExecutionPayloadBid."
+            signed_blinded_envelope:
+              $ref: "../../types/gloas/blinded_envelope.yaml#/Gloas/SignedBlindedExecutionPayloadEnvelope"
+              description: "The signed blinded execution payload envelope."
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `BlockAndBlindedEnvelope` bytes. Use content type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "202":
+      description: Success response. The builder will construct and broadcast the SignedExecutionPayloadEnvelope to the PTC committee.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidBlock:
+              value:
+                code: 400
+                message: "Invalid block: missing signature"
+            InvalidEnvelope:
+              value:
+                code: 400
+                message: "Invalid envelope: beacon_block_root mismatch"
+            BidMismatch:
+              value:
+                code: 400
+                message: "Bid mismatch: ExecutionPayloadBid does not match provided bid"
+    "415":
+      $ref: "../../builder-oapi.yaml#/components/responses/UnsupportedMediaType"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"
+

apis/builder/builder_bid.yaml

@@ -0,0 +1,117 @@
+get:
+  operationId: "getBuilderBid"
+  summary: Get an execution payload bid from an unstaked builder.
+  description: |
+    Requests an unstaked builder node to produce a valid builder bid containing an
+    execution payload header and a `SignedExecutionPayloadBid`. This endpoint is used
+    for unstaked builders who provide full block contents to validators.
+
+    The validator sends a GET request with the following path parameters:
+    - 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 validator's BLS public key.
+
+    The builder responds with a 200 response containing a `SignedBuilderBid` if it can
+    provide one. The bid includes:
+    - An `ExecutionPayloadHeader` for the proposed block
+    - Blob KZG commitments for any associated blobs
+    - Execution requests (deposits, withdrawals, etc.)
+    - A `SignedExecutionPayloadBid` with `builder_index` set to `BUILDER_INDEX_SELF_BUILD`
+
+    If the builder is unable to produce a valid 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 for unstaked builders.
+  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: pubkey
+      in: path
+      required: true
+      description: The validator's BLS public key.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/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 
+        requests to maximise block rewards. Otherwise, requests will timeout and the proposer 
+        will not receive the bid 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: GetBuilderBidResponse
+            type: object
+            required: [version, data]
+            properties:
+              version:
+                type: string
+                enum: [ gloas ]
+                example: "gloas"
+              data:
+                $ref: "../../types/gloas/builder_bid.yaml#/Gloas/SignedBuilderBid"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `SignedBuilderBid` 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:
+            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/execution_payload_bid.yaml

@@ -0,0 +1,126 @@
+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 blinded 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.
+    - A signed bid request auth using a builder-specific salt to authenticate the request. Proposers are required
+    to set the salt to the URL provided by the whitelisted builder.
+
+    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. If the SignedBidRequestAuth is invalid, the builder MUST return a 400 response.
+
+    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 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
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "../../types/gloas/bid_request_auth.yaml#/Gloas/SignedBidRequestAuth"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `SignedBidRequestAuth` bytes."
+  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 SignedBidRequestAuth: signature verification failed"
+    "406":
+      $ref: "../../builder-oapi.yaml#/components/responses/NotAcceptable"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"