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.

    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"
    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"

  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"