update proposerConfig related sections (#409)

Consensys · Dec 2, 2022 · 7ceb45d · 7ceb45d
1 parent 06b21dd
commit 7ceb45d
Show file tree

Hide file tree

Showing 7 changed files with 407 additions and 178 deletions.
diff --git a/docs/Concepts/Builder-Network.md b/docs/Concepts/Builder-Network.md
@@ -4,18 +4,21 @@ description: Builder network and MEV-Boost
 
 # Builder network and MEV-Boost
 
-When [The Merge](Merge.md) completes, [consensus clients](Merge.md#consensus-clients)
-will be responsible for proposing blocks containing an execution payload obtained
-from their local [execution clients](Merge.md#execution-clients) via the Engine API.
+[Consensus clients](Merge.md#consensus-clients) are responsible for proposing blocks containing an
+execution payload obtained from their local [execution clients](Merge.md#execution-clients) via the
+Engine API.
 
-A consensus client can optionally configure an external builder and
-delegate the execution payload construction to it, instead of using the execution client.
+A consensus client can optionally configure an external builder and delegate the execution payload
+construction to it, instead of using the execution client.
 
 ## MEV-Boost
 
-The most common builder deployment is to run a specialised external software such as [MEV-Boost](https://github.com/flashbots/mev-boost).
-MEV-Boost works by requesting a payload proposal from several entities (called relays), and selecting the best bid
-in order to improve validator rewards and increase the maximal extractable value (MEV).
+The most common builder deployment is to run a specialized external software such as [MEV-Boost](https://github.com/flashbots/mev-boost).
+MEV-Boost works by requesting a payload proposal from several entities (called relays), and
+selecting the best bid in order to improve validator rewards and increase the maximal extractable
+value (MEV).
 
-Teku allows you to [configure the beacon node to use a builder network](../HowTo/Builder-Network.md) to generate execution payloads.
-In case of failures or non-timely responses, Teku will fall back to the payload produced by the local execution client specified with [`ee-endpoint`](../Reference/CLI/CLI-Syntax.md#ee-endpoint).
+Teku allows you to [configure the beacon node to use a builder network](../HowTo/Configure/Builder-Network.md)
+to generate execution payloads.
+In case of failures or non-timely responses, Teku falls back to the payload produced by the local
+execution client specified using [`ee-endpoint`](../Reference/CLI/CLI-Syntax.md#ee-endpoint).
diff --git a/docs/HowTo/Builder-Network.md b/docs/HowTo/Builder-Network.md
diff --git a/docs/HowTo/Configure/Builder-Network.md b/docs/HowTo/Configure/Builder-Network.md
@@ -0,0 +1,140 @@
+---
+description: How to connect to a builder network
+---
+
+# Configure Teku to use a builder network
+
+You can connect to a [builder network](../../Concepts/Builder-Network.md) to generate execution
+payloads for the [consensus client](../../Concepts/Merge.md#consensus-clients).
+
+The builder recommends new blocks that are validated by the consensus client.
+If the builder goes down, the local execution client proposes a block instead.
+
+To configure Teku to use a builder network:
+
+1. [Enable blinded block production.](#1-enable-blinded-block-production)
+1. [Specify the builder endpoint.](#2-specify-the-builder-endpoint)
+1. [Register the validator.](#3-register-the-validator)
+
+## 1. Enable blinded block production
+
+Enable blinded block production using the [`--validators-proposer-blinded-blocks-enabled`](../../Reference/CLI/CLI-Syntax.md#validators-proposer-blinded-blocks-enabled)
+command line option.
+
+!!! note
+
+    If [--validators-builder-registration-default-enabled](../../Reference/CLI/CLI-Syntax.md#validators-builder-registration-default-enabled)
+    is set to `true`, then `--validators-proposer-blinded-blocks-enabled` is automatically enabled.
+
+## 2. Specify the builder endpoint
+
+Specify the builder endpoint using the [`--builder-endpoint`](../../Reference/CLI/CLI-Syntax.md#builder-endpoint)
+command line option.
+
+!!! example
+
+    ```bash
+    --builder-endpoint="https://builder-relay-sepolia.flashbots.net/"
+    ```
+
+View the [list of relay endpoints](https://github.com/flashbots/mev-boost#usage) for available endpoints.
+
+You can also use external software such as [MEV-Boost](https://github.com/flashbots/mev-boost) to
+connect to multiple relays.
+
+!!! example
+
+    ```bash
+    --builder-endpoint=http://127.0.0.1:18550
+    ```
+
+## 3. Register the validator
+
+You must register your validator with the builder before proposing a block.
+Enable registration for all validators using the [`--validators-builder-registration-default-enabled`](../../Reference/CLI/CLI-Syntax.md#validators-builder-registration-default-enabled)
+command line option.
+
+To enable registration for specific validators only, use the
+[`--validators-proposal-config`](../../Reference/CLI/CLI-Syntax.md#validators-proposer-config) option
+and specify the enabled validators in the `proposer_config` field of the [proposer configuration file](Proposer-Configuration.md).
+
+!!! example "`proposerConfig.json`"
+
+    ```json
+    {
+      "proposer_config": {
+        "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
+          "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
+          "builder": {
+            "enabled": true,
+            "gas_limit": "12345654321"
+          }
+        }
+      },
+      "default_config": {
+        "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
+        "builder": {
+          "enabled": false
+        }
+      }
+    }
+    ```
+
+    In this example, validator `0xa057816...` is registered with the builder,
+    but any validator using the default configuration isn't.
+
+!!! note
+
+    If you use a proposer configuration, you must enable blinded block production using
+    [`--validators-proposer-blinded-blocks-enabled`](../../Reference/CLI/CLI-Syntax.md#validators-proposer-blinded-blocks-enabled).
+
+## Example builder configurations
+
+!!! example "Validator client and beacon node in a single process"
+
+    ```bash
+    teku \
+        --validators-proposer-default-fee-recipient="0x6e35733c5af9B61374A128e6F85f553aF09ff89A" \
+        --ee-endpoint="http://127.0.0.1:8551"                  \
+        --ee-jwt-secret-file="/etc/jwt-secret.hex"             \
+        --validators-builder-registration-default-enabled=true \
+        --builder-endpoint="http://127.0.0.1:18550"
+    ```
+
+!!! example "Validator client and beacon node in separate processes"
+
+    Validator client parameters:
+
+    ```bash
+    teku validator-client \
+        --validators-proposer-blinded-blocks-enabled=true \
+        --validators-proposer-config="/etc/teku/proposerConfig.json"
+    ```
+
+    Proposer configuration:
+
+    ```json
+    {
+      "proposer_config": {
+        "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
+          "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
+        }
+      },
+      "default_config": {
+        "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
+        "builder": {
+          "enabled": true
+        }
+      }
+    }
+    ```
+
+    Beacon node paramaters:
+
+    ```bash
+    teku \
+        --validators-proposer-default-fee-recipient="0x6e35733c5af9B61374A128e6F85f553aF09ff89A" \
+        --ee-endpoint="http://127.0.0.1:8551" \
+        --ee-jwt-secret-file="/etc/jwt-secret.hex" \
+        --builder-endpoint="http://127.0.0.1:18550"
+    ```