Add Builder API schema

apis/builder/blinded_blocks.yaml

@@ -0,0 +1,42 @@
+post:
+  tags:
+    - Builder
+  operationId: "submitBlindedBlock"
+  summary: Submit a signed blinded block.
+  description: |
+    Submits a `SignedBlindedBeaconBlock` to the builder, binding them to the
+    block. The builder is now able to unblind the transactions in the
+    `ExecutionPayloadHeader` without the possibility of the validator modifying
+    them.
+  requestBody:
+    description: |
+      The `SignedBlindedBeaconBlock` object composed of `BlindedBeaconBlock`
+      object (produced by beacon node with `ExecutionPayloadHeader` from
+      external builder) and validator signature.
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+           - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock"
+  responses:
+    "200":
+      description: |
+        The block was validated successfully and has been sent to the builder.
+      content:
+        application/json:
+          schema:
+            oneOf:
+              - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.ExecutionPayload"
+    "400":
+      description: The `SignedBeaconBlock` object is invalid
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+              - example:
+                  code: 400
+                  message: "Invalid block: missing signature"
+    "500":
+      $ref: '../../builder-oapi.yaml#/components/responses/InternalError'

apis/builder/header.yaml

@@ -0,0 +1,58 @@
+get:
+  tags:
+    - Builder
+  operationId: "getHeader"
+  summary: Get an ExecutionPayloadHeader.
+  description: |
+    Requests a builder node to produce a valid execution payload header, which can integrated into a blinded beacon block and signed.
+
+    Metadata in the response indicates the type of block produced, and the supported types of block
+    will be added to as forks progress.
+  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 use as the proposal's parent."
+      schema:
+        $ref: '../../builder-oapi.yaml#/components/schemas/Root'
+    - name: pubkey
+      in: query
+      required: true
+      description: "The validator's BLS public key."
+      schema:
+        $ref: '../../builder-oapi.yaml#/components/schemas/Pubkey'
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: ProduceBlockV2Response
+            type: object
+            properties:
+              version:
+                type: string
+                enum: [ phase0, altair, bellatrix ]
+                example: "phase0"
+              data:
+                oneOf:
+                 - $ref: '../../builder-oapi.yaml#/components/schemas/Bellatrix.ExecutionPayloadHeader'
+    "400":
+      description: "Invalid block production request"
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Invalid request to produce a block"
+    "500":
+      $ref: '../../builder-oapi.yaml#/components/responses/InternalError'

apis/builder/validators.yaml

@@ -0,0 +1,32 @@
+post:
+  tags:
+    - Builder
+  operationId: "registerValidator"
+  summary: Register or update a validator's block building preferences.
+  description: |
+    Registers a validator's preferred fee recipient and gas limit target.
+  requestBody:
+    description: |
+      The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced
+      by beacon node) and validator signature.
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+           - $ref: '../../builder-oapi.yaml#/components/schemas/SignedValidatorRegistration'
+  responses:
+    "200":
+      description: Success response
+    "400":
+      description: The `SignedValidatorRegistration` is invalid.
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+              - example:
+                  code: 400
+                  message: "Unknown validator: 0x933ad9491b62059dd065b560d256d8957a8c402cc6e8d8ee7290ae11e8f7329267a8811c397529dac52ae1342ba58c95"
+    "500":
+      $ref: '../../builder-oapi.yaml#/components/responses/InternalError'

builder-oapi.yaml

@@ -0,0 +1,74 @@
+openapi: "3.0.3"
+
+info:
+  title: "Builder API"
+  description: |
+    API specification for external builder clients, which enables validators to delegate block building duties.
+
+    All requests by default send and receive JSON, and as such should have either or both of the "Content-Type: application/json"
+    and "Accept: application/json" headers. In addition, some requests can return data in the SSZ format. To indicate that SSZ
+    data is required in response to a request the header "Accept: application/octet-stream" should be sent. Note that only a subset
+    of requests can respond with data in SSZ format; these are noted in each individual request.
+
+    API endpoints are individually versioned.  As such, there is no direct relationship between all v1 endpoints, all v2 endpoints,
+    _etc._ and no such relationship should be inferred.  All JSON responses return the requested data under a `data` key in the top
+    level of their response.  Additional metadata may or may not be present in other keys at the top level of the response, dependent
+    on the endpoint.  The rules that require an increase in version number are as follows:
+
+      - no field that is listed in an endpoint shall be removed without an increase in the version number
+      - no field that is listed in an endpoint shall be altered in terms of format (_e.g._ from a string to an array) without an
+        increase in the version number
+
+    Note that it is possible for a field to be added to an endpoint's data or metadata without an increase in the version number.
+
+  version: "dev"
+  contact:
+    name: Ethereum Github
+    url: https://github.com/ethereum/builder-apis/issues
+  license:
+    name: "Apache 2.0"
+    url: "https://www.apache.org/licenses/LICENSE-2.0.html"
+
+servers:
+  - url: "{server_url}"
+    variables:
+      server_url:
+        description: "Builder node API url"
+        default: "???"
+
+tags:
+  - name: Builder
+    description: Set of endpoints to interact with an external block builder.
+paths:
+
+  /eth/v1/builder/validators:
+    $ref: "./apis/builder/validators.yaml"
+  /eth/v1/builder/{slot}/{parent_hash}/header:
+    $ref: "./apis/builder/header.yaml"
+  /eth/v1/builder/blinded_blocks:
+    $ref: "./apis/builder/blinded_blocks.yaml"
+
+
+components:
+  schemas:
+    Uint64:
+      $ref: './beacon-apis/types/primitive.yaml#/Uint64'
+    Root:
+      $ref: './beacon-apis/types/primitive.yaml#/Root'
+    Pubkey:
+      $ref: './beacon-apis/types/primitive.yaml#/Pubkey'
+    ErrorMessage:
+      $ref: './beacon-apis/types/http.yaml#/ErrorMessage'
+    Bellatrix.ExecutionPayload:
+      $ref: './beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload'
+    Bellatrix.ExecutionPayloadHeader:
+      $ref: './beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayloadHeader'
+    Bellatrix.SignedBlindedBeaconBlock:
+      $ref: './beacon-apis/types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock'
+
+    SignedValidatorRegistration:
+      $ref: './types/registration.yaml#/SignedValidatorRegistration'
+
+  responses:
+    InternalError:
+      $ref: './beacon-apis/types/http.yaml#/InternalError'

types/registration.yaml

@@ -0,0 +1,29 @@
+ValidatorRegistration:
+  type: object
+  description: "The [`ValidatorRegistration`]() object from the Builder API spec."
+  properties:
+    fee_recipient:
+      allOf:
+        - $ref: '../beacon-apis/types/primitive.yaml#/ExecutionAddress'
+        - description: "Address to receive fees from the block."
+    gas_limit:
+      allOf:
+        - $ref: "../beacon-apis/types/primitive.yaml#/Uint64"
+        - description: "Gas limit the validator desires to target."
+    timestamp:
+      allOf:
+        - $ref: '../beacon-apis/types/primitive.yaml#/Uint64'
+        - description: "Unix timestamp of registration."
+    pubkey:
+      allOf:
+        - $ref: '../beacon-apis/types/primitive.yaml#/Pubkey'
+        - description: "BLS public key of validator."
+
+SignedValidatorRegistration:
+  type: object
+  description: "The [`SignedValidatorRegistration`]() object from the Builder API spec."
+  properties:
+    message:
+      $ref: "#/ValidatorRegistration"
+    signature:
+      $ref: "../beacon-apis/types/primitive.yaml#/Signature"