From 74c66c114c6e108daead93775bc49aebea711b19 Mon Sep 17 00:00:00 2001 From: "lightclient@protonmail.com" Date: Sat, 7 May 2022 20:03:26 +0200 Subject: [PATCH] add more explanation in readme --- README.md | 82 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 65 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index cc03461..158bcbb 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,65 @@ -# 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: +* [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. +[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. + +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). + +#### Builder software + +Users will typically connect thier 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] + +## Render API Schema + +To render spec in browser, you will simply need a HTTP server to load +the `index.html` file in root of the repo. + +For example: ``` python -m http.server 8080 ``` -And api spec will render on [http://localhost:8080](http://localhost: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. +Local changes will be observable if "dev" is selected in the "Select a +definition" drop-down in the web UI. -Users may need to tick the "Disable Cache" box in their browser's developer tools to see changes after modifying the source. +It may be neccessary to tick the "Disable Cache" box in their browser's +developer tools to see changes after modifying the source. ## Contributing @@ -38,14 +77,23 @@ spectral lint builder-oapi.yaml ## 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 `` +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 `` with real tag name from step 1.): ```javascript - {url: "https://github.com/ethereum/builder-apis/releases/download//builder-oapi.yaml", name: ""}, +{url: "https://github.com/ethereum/builder-apis/releases/download//builder-oapi.yaml", name: ""}, ``` + +[ci]: https://ethresear.ch/t/mev-boost-merge-ready-flashbots-architecture/11177 +[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