builder-oapi.yaml

openapi: "3.0.3"

info:
  title: Builder API
  description: |
    API specification for external builder nodes. This interface 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 send and receive data in the SSZ format.  The header
    "Content-Type: application/octet-stream" should be set in requests that contain SSZ data; a preference to receive SSZ data in
    response can be indicated by setting the "Accept: application/octet-stream;q=1.0,application/json;q=0.9" header.  Note that
    only a subset of requests can respond with data in SSZ format; these are noted in each individual request.

    When handling requests, the server should return a 415 status code if the "Content-Type" header in the request specifies a format
    that is not supported.  Similarly, it should return a 406 status code if it cannot produce a response in the format accepted by
    the client as specified in the "Accept" header; if no "Accept" header is provided then it is assumed to be "application/json".
    In any case, the server should indicate the format of the response by setting the corresponding "Content-Type" header.

    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. 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-specs/issues
  license:
    name: "CC0-1.0"
    url: "https://creativecommons.org/publicdomain/zero/1.0/"

servers:
  - url: "{server_url}"
    variables:
      server_url:
        description: "Builder node URL"
        default: "http://localhost:18550"

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/header/{slot}/{parent_hash}/{pubkey}:
    $ref: "./apis/builder/header.yaml"
  /eth/v1/builder/blinded_blocks:
    $ref: "./apis/builder/blinded_blocks.yaml"
  /eth/v1/builder/status:
    $ref: "./apis/builder/status.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"
    ConsensusVersion:
      $ref: "./beacon-apis/beacon-node-oapi.yaml#/components/schemas/ConsensusVersion"
      enum: [ bellatrix, capella, deneb, electra ]
      example: "bellatrix"
    Bellatrix.ExecutionPayload:
      $ref: "./beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload"
    Bellatrix.SignedBlindedBeaconBlock:
      $ref: "./beacon-apis/types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock"
    Bellatrix.SignedBuilderBid:
      $ref: "./types/bellatrix/bid.yaml#/Bellatrix/SignedBuilderBid"
    Capella.ExecutionPayload:
      $ref: "./beacon-apis/types/capella/execution_payload.yaml#/Capella/ExecutionPayload"
    Capella.SignedBlindedBeaconBlock:
      $ref: "./beacon-apis/types/capella/block.yaml#/Capella/SignedBlindedBeaconBlock"
    Capella.SignedBuilderBid:
      $ref: "./types/capella/bid.yaml#/Capella/SignedBuilderBid"
    Deneb.SignedBlindedBeaconBlock:
      $ref: "./beacon-apis/types/deneb/block.yaml#/Deneb/SignedBlindedBeaconBlock"
    Deneb.SignedBuilderBid:
      $ref: "./types/deneb/bid.yaml#/Deneb/SignedBuilderBid"
    Deneb.ExecutionPayloadAndBlobsBundle:
      $ref: "./types/deneb/execution_payload_and_blobs_bundle.yaml#/Deneb/ExecutionPayloadAndBlobsBundle"
    SignedValidatorRegistration:
      $ref: "./beacon-apis/types/registration.yaml#/SignedValidatorRegistration"
    Electra.SignedBlindedBeaconBlock:
      $ref: "./beacon-apis/types/electra/block.yaml#/Electra/SignedBlindedBeaconBlock"
    Electra.SignedBuilderBid:
      $ref: "./types/electra/bid.yaml#/Electra/SignedBuilderBid"

  responses:
    InternalError:
      $ref: "./types/http.yaml#/InternalError"
    NotAcceptable:
      $ref: "./types/http.yaml#/NotAcceptable"
    UnsupportedMediaType:
      $ref: "./types/http.yaml#/UnsupportedMediaType"

  headers:
    Eth-Consensus-Version:
      $ref: "./beacon-apis/beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version"
      schema:
        $ref: "#/components/schemas/ConsensusVersion"

  examples:
    Bellatrix.SignedBlindedBeaconBlock:
      $ref: "./examples/bellatrix/signed_blinded_beacon_block.json"
    Bellatrix.ExecutionPayload:
      $ref: "./examples/bellatrix/execution_payload.json"
    Bellatrix.SignedBuilderBid:
      $ref: "./examples/bellatrix/signed_builder_bid.json"
    Capella.SignedBlindedBeaconBlock:
      $ref: "./examples/capella/signed_blinded_beacon_block.json"
    Capella.ExecutionPayload:
      $ref: "./examples/capella/execution_payload.json"
    Capella.SignedBuilderBid:
      $ref: "./examples/capella/signed_builder_bid.json"
    Deneb.SignedBlindedBeaconBlock:
      $ref: "./examples/deneb/signed_blinded_beacon_block.json"
    Deneb.ExecutionPayloadAndBlobsBundle:
      $ref: "./examples/deneb/execution_payload_and_blobs_bundle.json"
    Deneb.SignedBuilderBid:
      $ref: "./examples/deneb/signed_builder_bid.json"
    Electra.SignedBlindedBeaconBlock:
      $ref: "./examples/electra/signed_blinded_beacon_block.json"
    Electra.SignedBuilderBid:
      $ref: "./examples/electra/signed_builder_bid.json"