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 <jacek@status.im>

* unhide external payload builder options

* clarify builder API incentive misalignment

Co-authored-by: Jacek Sieka <jacek@status.im>

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

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'

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}/
+    ```

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