From d7e9c334ac71efc353bca05eb0f9bc3cc054d26a Mon Sep 17 00:00:00 2001 From: tersec Date: Mon, 29 Aug 2022 09:59:12 +0000 Subject: [PATCH] document external block builder configuration (#4032) * document external block builder configuration * Update docs/the_nimbus_book/src/external-block-builder.md Co-authored-by: Jacek Sieka * unhide external payload builder options * clarify builder API incentive misalignment Co-authored-by: Jacek Sieka --- beacon_chain/conf.nim | 2 -- docs/the_nimbus_book/mkdocs.yml | 1 + .../src/external-block-builder.md | 24 +++++++++++++++++++ .../src/suggested-fee-recipient.md | 2 +- 4 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 docs/the_nimbus_book/src/external-block-builder.md diff --git a/beacon_chain/conf.nim b/beacon_chain/conf.nim index 11d13e26b..3bdb89e6d 100644 --- a/beacon_chain/conf.nim +++ b/beacon_chain/conf.nim @@ -548,13 +548,11 @@ type name: "suggested-fee-recipient" .}: Option[Address] payloadBuilderEnable* {. - hidden desc: "Enable external payload builder" defaultValue: false name: "payload-builder" .}: bool payloadBuilderUrl* {. - hidden desc: "Payload builder URL" defaultValue: "" name: "payload-builder-url" .}: string diff --git a/docs/the_nimbus_book/mkdocs.yml b/docs/the_nimbus_book/mkdocs.yml index 46d61c686..cf57bd85b 100644 --- a/docs/the_nimbus_book/mkdocs.yml +++ b/docs/the_nimbus_book/mkdocs.yml @@ -64,6 +64,7 @@ nav: - 'connect-eth2.md' - 'graffiti.md' - 'suggested-fee-recipient.md' + - 'external-block-builder.md' - 'keep-an-eye.md' - 'voluntary-exit.md' - 'more-keys.md' diff --git a/docs/the_nimbus_book/src/external-block-builder.md b/docs/the_nimbus_book/src/external-block-builder.md new file mode 100644 index 000000000..a48214a23 --- /dev/null +++ b/docs/the_nimbus_book/src/external-block-builder.md @@ -0,0 +1,24 @@ +# Set up block builders + +[Maximal extractable value](https://ethereum.org/en/developers/docs/mev/) involves consensus clients contacting an external block builder which might maximize profit or some other defined metric in ways hindered for a purely local consensus and execution client setup. This external builder network uses the [builder API](https://ethereum.github.io/builder-specs/) which consensus clients use to access external block builder bundles found by searchers. In exchange, such searchers and builders might choose to retain some of the profit gained from such bundles. A builder API relay provides access to multiple searchers via a single URL. + +Nimbus supports this API to access these external block builders. If one is configured, the block production flow becomes modified: +1. attempt to use the specified external block builder relay or builder to create an execution payload +2. if the external block builder builder or relay doesn't function, and Nimbus has not signed a blinded beacon block, then fall back to existing local execution client to produce a block + +There exists a failure mode, intrinsic to the builder API, wherein the consensus client has signed a blinded proposal and therefore even if the external block builder relay or builder doesn't provide a full block, a consensus client such as Nimbus cannot safely proceed with step 2 and fall back on its local execution client. + +!!! note + By default, [priority and maximum gas fees](https://eips.ethereum.org/EIPS/eip-1559#abstract) determine transaction inclusion in blocks, but external block builders may use other strategies for transaction selection, which might involve regulatory constraints and extracted value. For further information, check the documentation of the block builder. + +## Command line option + +=== "Mainnet" + ```sh + ./run-mainnet-beacon-node.sh --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/ + ``` + +=== "Prater" + ```sh + ./run-prater-beacon-node.sh --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/ + ``` diff --git a/docs/the_nimbus_book/src/suggested-fee-recipient.md b/docs/the_nimbus_book/src/suggested-fee-recipient.md index 8324532ab..9b27e0970 100644 --- a/docs/the_nimbus_book/src/suggested-fee-recipient.md +++ b/docs/the_nimbus_book/src/suggested-fee-recipient.md @@ -21,5 +21,5 @@ For example, `nimbus_beacon_node --suggested-fee-recipient=0x70E47C843E0F6ab0991 === "Prater" ```sh - ./run-mainnet-beacon-node.sh --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842 + ./run-prater-beacon-node.sh --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842 ```