Add Builder API schema

README.md

@@ -1,51 +1,99 @@
-# Ethereum Builder Specification
+# Ethereum Builder API Specification
 
-![CI](https://github.com/ethereum/builder-specs/workflows/CI/badge.svg)
+![CI][ci]
 
-Collection of RESTful APIs provided by external builder nodes.
+The Builder API is an interface for consensus layer clients to source blocks
+built by external entities.
 
-## Render 
+In this repository:
+* [API specification][oas-spec]
+* [Additional definitions][spec]
 
-To render spec in browser you will need any http server to load `index.html` file
-in root of the repo.
+### Why?
 
-##### Python
+Block building is a specialized activity that requires high fixed costs to be
+an efficient validator. This creates an advantage for staking pools as they can
+effectively distribute the cost across many validators.
 
-```
-python -m http.server 8080
-```
-And api spec will render on [http://localhost:8080](http://localhost:8080).
+[Proposer-builder separation][pbs] (PBS) fixes this by spliting the roles of a
+validator into block proposing and block building. However, PBS requires
+modifications to the Beacon chain and will therefore not be possible at the
+time of the merge.
 
-### Usage
+The Builder API is a temporary solution that requires higher trust assumptions
+than PBS, but can be fully implemented without modification to the base
+protocol. This is done by providing the proposer with a "blind" execution layer
+header to incorporate into a block and a "value" amount which will be
+transferred to the proposer once they create a block with the aforementioned
+header. Once the proposer signs a block with the header, they are bound to the
+choice (or risk being slashed due to equivocation). That allows the builder to
+reveal the blinded transactions without the possibility of the proposer
+tampering with them.
+
+This design is based on the original proposal for trusted external builders:
+["MEV-Boost: Merge ready Flashbots Architecture"](mev-boost-ethr).
 
-Local changes will be observable if "dev" is selected in the "Select a definition" drop-down in the web UI.
+#### Builder software
 
-Users may need to tick the "Disable Cache" box in their browser's developer tools to see changes after modifying the source. 
+Users will typically connect their CL clients to builders with builder
+multiplexers. Please see their respective repositories for more information:
+
+* [`mev-boost`][mev-boost]
+* [`mev-boost-rs`][mev-boost-rs]
 
 ## Contributing
 
-API spec is checked for lint errors before merge. 
+The API specification is checked for lint errors before merge. 
 
-To run lint locally, install linter with
-```
+To run the linter locally, install it with:
+```console
 npm install -g @stoplight/spectral-cli@6.2.1
 ```
-and run lint with
-```
+and then run it:
+```console
 spectral lint builder-oapi.yaml
 ```
 
+### Render API Specification
+
+To render spec in browser, you will simply need an HTTP server to load the
+`index.html` file in root of the repo.
+
+For example:
+```console
+python -m http.server 8080
+```
+
+The spec will render at [http://localhost:8080](http://localhost:8080).
+
+### Usage
+
+Local changes will be observable if "dev" is selected in the "Select a
+definition" drop-down in the web UI.
+
+It may be neccessary to tick the "Disable Cache" box in their browser's
+developer tools to see changes after modifying the source. 
+
 ## Releasing
 
 1. Create and push tag
+   - Make sure `info.version` in `builder-oapi.yaml` file is updated before
+     tagging.
+   - CI will create a github release and upload bundled spec file
+2. Add release entrypoint in `index.html`
 
-   - Make sure info.version in builder-oapi.yaml file is updated before tagging.
-   - CD will create github release and upload bundled spec file
+In `SwaggerUIBundle` configuration (inside `index.html` file), add another
+entry in `urls` field. Entry should be in following format (replace `<tag>`
+with real tag name from step 1.):
 
-2. Add release entrypoint in index.html
-
-In SwaggerUIBundle configuration (inside index.html file), add another entry in "urls" field (SwaggerUI will load first item as default).
-Entry should be in following format(replace `<tag>` with real tag name from step 1.):
 ```javascript
-         {url: "https://github.com/ethereum/builder-apis/releases/download/<tag>/builder-oapi.yaml", name: "<tag>"},
+{url: "https://github.com/ethereum/builder-apis/releases/download/<tag>/builder-oapi.yaml", name: "<tag>"},
 ```
+
+[ci]: https://github.com/ethereum/builder-specs/workflows/CI/badge.svg
+[oas-spec]: https://ethereum.github.io/builder-specs/
+[spec]: specs/README.md
+[pbs]: https://ethresear.ch/t/proposer-block-builder-separation-friendly-fee-market-designs/9725
+[mev-boost-ethr]: https://ethresear.ch/t/mev-boost-merge-ready-flashbots-architecture/11177
+[mev-boost]: https://github.com/flashbots/mev-boost
+[mev-boost-rs]: https://github.com/ralexstokes/mev-boost-rs

apis/builder/blinded_blocks.yaml

@@ -0,0 +1,56 @@
+post:
+  operationId: "submitBlindedBlock"
+  summary: Submit a signed blinded block and get unblinded execution payload.
+  description: |
+    Submits a `SignedBlindedBeaconBlock` to the builder, binding the proposer
+    to the block. The builder is now able to unblind the transactions in
+    `ExecutionPayloadHeader` without the possibility of the validator modifying
+    them.
+
+    If the builder is not able to unblind the corresponding
+    `ExecutionPayloadHeader`, it must error.
+  tags:
+    - Builder
+  requestBody:
+    description: A `SignedBlindedBeaconBlock`.
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock"
+        examples:
+          bellatrix:
+            $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.SignedBlindedBeaconBlock"
+
+  responses:
+    "200":
+      description: Success response.
+      content:
+        application/json:
+          schema:
+            title: SubmitBlindedBlockResponse
+            type: object
+            properties:
+              version:
+                type: string
+                enum: [ bellatrix ]
+                example: "bellatrix"
+              data:
+                oneOf:
+                  - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.ExecutionPayload"
+          examples:
+            bellatrix:
+              $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.ExecutionPayload"
+    "400":
+      description: Error response.
+      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,72 @@
+get:
+  operationId: "getHeader"
+  summary: Get an execution payload header.
+  description: |
+    Requests a builder node to produce a valid execution payload header, which
+    can integrated into a blinded beacon block and signed.
+
+    Builder must immediately return the header that is able to pay
+    `feeRecipient` the most. If the builder is unaware of `parent_hash`, it
+    must error. If `pubkey` does not match the builder's expected proposer
+    `pubkey` for `slot`, it must error. If the builder has not received a
+    validator registration associated with `pubkey`, it must error.
+
+    When possibe, the builder must return a header with `gas_limit` equal to
+    proposer's registered value. If this isn't possible due to the large
+    difference between `parent.gas_limit` and the preferred `gas_limit`, the
+    builder must return a header that moves `gas_limit` the maximum amount
+    allowed under the rules of consensus (currently `parent.gas_limit +/-
+    parent.gas_limit / 1024`).
+  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: pubkey
+      in: path
+      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: GetHeaderResponse
+            type: object
+            properties:
+              version:
+                type: string
+                enum: [ bellatrix ]
+                example: "bellatrix"
+              data:
+                oneOf:
+                 - $ref: "../../builder-oapi.yaml#/components/schemas/SignedBuilderBid"
+          examples:
+            bellatrix:
+              $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.SignedBuilderBid"
+    "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"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/status.yaml

@@ -0,0 +1,11 @@
+get:
+  operationId: "status"
+  summary: Check if builder is healthy.
+  description: Checks if builder can respond to requests normally.
+  tags:
+    - Builder
+  responses:
+    "200":
+      description: Success response.
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/validators.yaml

@@ -0,0 +1,37 @@
+post:
+  operationId: "registerValidator"
+  summary: Register or update a validator's block building preferences.
+  description: |
+    Registers a validator's preferred fee recipient and gas limit.
+
+    Builders should verify that `pubkey` corresponds to an active or pending
+    validator, and that `signature` is valid under `pubkey`. Otherwise, builder
+    must error. Requests with `timestamp` less than or equal to the previous
+    announcement must error. Requests with `timestamp` more than 10 seconds in
+    the future must error.
+  tags:
+    - Builder
+  requestBody:
+    description: An array of signed validator block building preferences.
+    required: true
+    content:
+      application/json:
+        schema:
+          type: array
+          items:
+            $ref: "../../builder-oapi.yaml#/components/schemas/SignedValidatorRegistration"
+  responses:
+    "200":
+      description: Success response.
+    "400":
+      description: Error response.
+      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,84 @@
+openapi: "3.0.3"
+
+info:
+  title: Builder API
+  description: |
+    API specification for external builder nodes. This interface enables
+    validators to delegate block building duties, while allowing for
+    attribution in the case of most faults (e.g. producing an invalid block).
+
+    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: "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"
+
+    SignedValidatorRegistration:
+      $ref: "./types/registration.yaml#/SignedValidatorRegistration"
+    SignedBuilderBid:
+      $ref: "./types/bid.yaml#/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"