Add Builder API schema

.github/workflows/spellcheck.yaml

@@ -0,0 +1,11 @@
+name: Spellcheck
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  build:
+    name: Spellcheck
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - uses: rojopolis/spellcheck-github-actions@0.16.0
+      name: Spellcheck

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 merging pull requests.
 
-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 necessary 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,73 @@
+get:
+  operationId: "getHeader"
+  summary: Get an execution payload header.
+  description: |
+    Requests a builder node to produce a valid execution payload header, which
+    can be integrated into a blinded beacon block and signed.
+
+    Builder must immediately return the header that is able to pay the
+    proposer's registered `fee_recipient` 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 possible, 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/Bellatrix.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,36 @@
+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
+    successful announcement must error. Requests with `timestamp` more than 10
+    seconds in the future must error.
+  tags:
+    - Builder
+  requestBody:
+    description: |
+      A signed declaration of a validator's block building preferences.
+    required: true
+    content:
+      application/json:
+        schema:
+            $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"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"