From cd42b3711fab3b9d1b3cb9ec1734b610d451a1bd Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sun, 14 Jan 2024 19:00:16 -0500 Subject: [PATCH 01/14] Change docs nav titles and include vc config --- docs/mkdocs.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 270a01b311de..87150ca1610e 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -81,20 +81,21 @@ nav: - Starting a Node: getting-started/starting-a-node.md - Data Retention: data-retention.md - Beacon Node: - - Configuration: beacon-management/beacon-cli.md + - Beacon CLI Reference: beacon-management/beacon-cli.md - Networking: beacon-management/networking.md - MEV and Builder Integration: beacon-management/mev-and-builder-integration.md - Syncing: beacon-management/syncing.md - Validator: - - Configuration: validator-management/validator-cli.md + - Configuration: validator-management/vc-configuration.md + - Validator CLI Reference: validator-management/validator-cli.md # - Key Management: validator-management/key-management.md # - Withdrawals: validator-management/withdrawals.md # - Multiple and Fall-Back Validation: validator-management/multiple-and-fallback-validation.md - Bootnode: - - Configuration: bootnode/bootnode-cli.md + - Bootnode CLI Reference: bootnode/bootnode-cli.md - Light Client and Prover: - Light Client: lightclient-prover/lightclient.md - - Light Client Configuration: lightclient-prover/lightclient-cli.md + - Light Client CLI Reference: lightclient-prover/lightclient-cli.md - Prover: lightclient-prover/prover.md # - Prover Configuration: lightclient-prover/prover-cli.md - Logging and Metrics: From 145a5d6e6bcba35427c68ace89d7c0754d574a98 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Sun, 14 Jan 2024 19:01:24 -0500 Subject: [PATCH 02/14] Rename and re-include config with builder boost --- ...ator-management.md => vc-configuration.md} | 23 ++++++++++++++----- 1 file changed, 17 insertions(+), 6 deletions(-) rename docs/pages/validator-management/{validator-management.md => vc-configuration.md} (77%) diff --git a/docs/pages/validator-management/validator-management.md b/docs/pages/validator-management/vc-configuration.md similarity index 77% rename from docs/pages/validator-management/validator-management.md rename to docs/pages/validator-management/vc-configuration.md index 7bd0b719ee61..67aaa99783d0 100644 --- a/docs/pages/validator-management/validator-management.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -1,6 +1,6 @@ -# Validator management +# Validator Configuration -The following instructions are required for stakers utilizing Lodestar. +The following instructions are for stakers utilizing the Lodestar validator client. [TOC] @@ -17,7 +17,7 @@ The mnemonic is randomly generated during wallet creation and printed out to the ### Create a wallet -Lodestar is deprecating its functionality to create wallets. +Lodestar has deprecated its functionality to create wallets. To create a wallet, we recommend using the official [`staking-deposit-cli`](https://github.com/ethereum/staking-deposit-cli/releases) from the Ethereum Foundation for users comfortable with command line interfaces. @@ -88,11 +88,22 @@ Configure your validator client's fee recipient address by using the `--suggeste You may choose to use the `--strictFeeRecipientCheck` flag to enable a strict check of the fee recipient address with the one returned by the beacon node for added reassurance. +### Configure your builder selection and/or builder boost factor + +If you are running Lodestar with connected builder relays, you may use this configuration to determine which block to propose. With produceBlockV3, the `builder.boostFactor` allows you to set a percentage multiplier to compare against the local engine block reward versus the builder block's reward from the relays (if the beacon node is connected to builder relays). + +This is similar to our previous `builder.selection` options for how the validator chooses which block to propose in its production flow. With produceBlockV3 (enabled automatically after the Deneb hard fork), the `builder.boostFactor` will be available and maintained as part of `consensus-specs/apis/validator/block.v3.yaml` for a more fine-tuned selection strategy. The `builder.selection` options of `maxprofit` | `executiononly` | `builderonly` | `builderalways` is still available for use. + +Examples comparing `builder.boostFactor` to our previous `builder.selection` implementation, setting a `builder.boostFactor` of `0` is the same as signaling `builder.selection executiononly` where the validator will always select the local execution block if available. + +Setting a `builder.boostFactor` of `100` is the same as signaling `builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. + +Otherwise, custom setting `builder.boostFactor` of `80` as an example, allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. + ### Submit a validator deposit -Please use the official tools to perform your deposits +Please use the official Ethereum Launchpad to perform your deposits -- `staking-deposit-cli`: - Ethereum Foundation launchpad: ## Run the validator @@ -105,7 +116,7 @@ To start a Lodestar validator run the command: You should see confirmation that modules have started. -```bash +```ts Nov-29 10:47:13.647[] info: Lodestar network=sepolia, version=v1.2.2/f093b46, commit=f093b468ec3ab0dbbe8e2d2c8175f52ad88aa35f Nov-29 10:47:13.649[] info: Connecting to LevelDB database path=/home/user/.local/share/lodestar/sepolia/validator-db Nov-29 10:47:51.732[] info: 3 local keystores From e92bd997065c97231b050d89258a6fd6297ae2f1 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 10:42:27 -0500 Subject: [PATCH 03/14] refactor builderboostFactor from comments --- .../validator-management/vc-configuration.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index 67aaa99783d0..978379cc1901 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -17,7 +17,7 @@ The mnemonic is randomly generated during wallet creation and printed out to the ### Create a wallet -Lodestar has deprecated its functionality to create wallets. +Lodestar has removed its functionality to create wallets. To create a wallet, we recommend using the official [`staking-deposit-cli`](https://github.com/ethereum/staking-deposit-cli/releases) from the Ethereum Foundation for users comfortable with command line interfaces. @@ -90,15 +90,22 @@ You may choose to use the `--strictFeeRecipientCheck` flag to enable a strict ch ### Configure your builder selection and/or builder boost factor -If you are running Lodestar with connected builder relays, you may use this configuration to determine which block to propose. With produceBlockV3, the `builder.boostFactor` allows you to set a percentage multiplier to compare against the local engine block reward versus the builder block's reward from the relays (if the beacon node is connected to builder relays). +If you are running a Lodestar beacon with connected builder relays, you may use these validator configurations to signal which block (builder vs. local execution) for the beacon node to propose. -This is similar to our previous `builder.selection` options for how the validator chooses which block to propose in its production flow. With produceBlockV3 (enabled automatically after the Deneb hard fork), the `builder.boostFactor` will be available and maintained as part of `consensus-specs/apis/validator/block.v3.yaml` for a more fine-tuned selection strategy. The `builder.selection` options of `maxprofit` | `executiononly` | `builderonly` | `builderalways` is still available for use. +With produceBlockV3 (enabled automatically after the Deneb hard fork), the `builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). -Examples comparing `builder.boostFactor` to our previous `builder.selection` implementation, setting a `builder.boostFactor` of `0` is the same as signaling `builder.selection executiononly` where the validator will always select the local execution block if available. +With Lodestar's `--builder.selection` options, you can select: +- `maxprofit`: Default setting for Lodestar set at `builder.boostFactor=100`. Using this option, you may customize your `builder.boostFactor` to your preference. Examples of its usage are below. +- `executiononly`: Validator will not trigger builder block production even if builder relays are configured on the beacon. This will always select the local execution block. +- `builderalways`: An alias of `builder.boostFactor=18446744073709551615`, which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response. +- `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and *no block will be produced*. -Setting a `builder.boostFactor` of `100` is the same as signaling `builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. +#### Examples using custom `builder.boostFactor` +Example 1: Setting a `builder.boostFactor` of `0` is the same as signaling `builder.selection executiononly` where the validator will always select the local execution block if available. -Otherwise, custom setting `builder.boostFactor` of `80` as an example, allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. +Example 2: Setting a `builder.boostFactor` of `100` is the same as signaling `builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. + +Example 3: Setting `builder.boostFactor` of `80` allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. ### Submit a validator deposit @@ -116,7 +123,7 @@ To start a Lodestar validator run the command: You should see confirmation that modules have started. -```ts +``` Nov-29 10:47:13.647[] info: Lodestar network=sepolia, version=v1.2.2/f093b46, commit=f093b468ec3ab0dbbe8e2d2c8175f52ad88aa35f Nov-29 10:47:13.649[] info: Connecting to LevelDB database path=/home/user/.local/share/lodestar/sepolia/validator-db Nov-29 10:47:51.732[] info: 3 local keystores From ea370166f15818f4ecca9466f18aa822e2aa4bf7 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 10:45:25 -0500 Subject: [PATCH 04/14] add clarification to maxprofit --- docs/pages/validator-management/vc-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index 978379cc1901..8979ac28e6b7 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -95,7 +95,7 @@ If you are running a Lodestar beacon with connected builder relays, you may use With produceBlockV3 (enabled automatically after the Deneb hard fork), the `builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). With Lodestar's `--builder.selection` options, you can select: -- `maxprofit`: Default setting for Lodestar set at `builder.boostFactor=100`. Using this option, you may customize your `builder.boostFactor` to your preference. Examples of its usage are below. +- `maxprofit`: Default setting for Lodestar set at `builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `builder.boostFactor` to your preference. Examples of its usage are below. - `executiononly`: Validator will not trigger builder block production even if builder relays are configured on the beacon. This will always select the local execution block. - `builderalways`: An alias of `builder.boostFactor=18446744073709551615`, which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response. - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and *no block will be produced*. From 433815ab48d8512f0cec0977533ea289e94e4f20 Mon Sep 17 00:00:00 2001 From: Phil Ngo <58080811+philknows@users.noreply.github.com> Date: Mon, 15 Jan 2024 11:36:27 -0500 Subject: [PATCH 05/14] clarification on intro Co-authored-by: Nico Flaig --- docs/pages/validator-management/vc-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index 8979ac28e6b7..ea6bfeadfeea 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -90,7 +90,7 @@ You may choose to use the `--strictFeeRecipientCheck` flag to enable a strict ch ### Configure your builder selection and/or builder boost factor -If you are running a Lodestar beacon with connected builder relays, you may use these validator configurations to signal which block (builder vs. local execution) for the beacon node to propose. +If you are running a beacon node with connected builder relays, you may use these validator configurations to signal which block (builder vs. local execution) the beacon node should produce. With produceBlockV3 (enabled automatically after the Deneb hard fork), the `builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). From 8f6ea7c38c65b9f80d0d3421a938e94ae2789763 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 12:43:47 -0500 Subject: [PATCH 06/14] address additional comments --- .../validator-management/vc-configuration.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index ea6bfeadfeea..b0a92d66ccef 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -92,20 +92,20 @@ You may choose to use the `--strictFeeRecipientCheck` flag to enable a strict ch If you are running a beacon node with connected builder relays, you may use these validator configurations to signal which block (builder vs. local execution) the beacon node should produce. -With produceBlockV3 (enabled automatically after the Deneb hard fork), the `builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). +With produceBlockV3 (enabled automatically after the Deneb hard fork), the `--builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). With Lodestar's `--builder.selection` options, you can select: -- `maxprofit`: Default setting for Lodestar set at `builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `builder.boostFactor` to your preference. Examples of its usage are below. -- `executiononly`: Validator will not trigger builder block production even if builder relays are configured on the beacon. This will always select the local execution block. -- `builderalways`: An alias of `builder.boostFactor=18446744073709551615`, which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response. +- `maxprofit`: Default setting for Lodestar set at `--builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `--builder.boostFactor` to your preference. Examples of its usage are below. +- `executiononly`: Validator will not select the builder block even if builder relays are configured on the beacon. This option will always select the local execution block. +- `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via shouldOverrideBuilder from the execution payload response. - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and *no block will be produced*. -#### Examples using custom `builder.boostFactor` -Example 1: Setting a `builder.boostFactor` of `0` is the same as signaling `builder.selection executiononly` where the validator will always select the local execution block if available. +#### Examples using builder boost factor +Example 1: Setting a `--builder.boostFactor=0` will always prefer the local execution block, but will produce an available builder block if the local execution block fails. -Example 2: Setting a `builder.boostFactor` of `100` is the same as signaling `builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. +Example 2: Setting a `--builder.boostFactor=100` is the same as signaling `--builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. -Example 3: Setting `builder.boostFactor` of `80` allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. +Example 3: Setting `--builder.boostFactor=80` allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. ### Submit a validator deposit From 047732bad5e98a84f98cd6870589571daf0971a9 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 19:18:49 +0100 Subject: [PATCH 07/14] Remove redundancies in navigation menu --- docs/mkdocs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 87150ca1610e..c26b849e98b9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -81,18 +81,18 @@ nav: - Starting a Node: getting-started/starting-a-node.md - Data Retention: data-retention.md - Beacon Node: - - Beacon CLI Reference: beacon-management/beacon-cli.md + - CLI Reference: beacon-management/beacon-cli.md - Networking: beacon-management/networking.md - MEV and Builder Integration: beacon-management/mev-and-builder-integration.md - Syncing: beacon-management/syncing.md - Validator: - Configuration: validator-management/vc-configuration.md - - Validator CLI Reference: validator-management/validator-cli.md + - CLI Reference: validator-management/validator-cli.md # - Key Management: validator-management/key-management.md # - Withdrawals: validator-management/withdrawals.md # - Multiple and Fall-Back Validation: validator-management/multiple-and-fallback-validation.md - Bootnode: - - Bootnode CLI Reference: bootnode/bootnode-cli.md + - CLI Reference: bootnode/bootnode-cli.md - Light Client and Prover: - Light Client: lightclient-prover/lightclient.md - Light Client CLI Reference: lightclient-prover/lightclient-cli.md From d2400be504a4d7c72864158e13d8be40a8e90052 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 19:24:43 +0100 Subject: [PATCH 08/14] Just formatting changes --- docs/pages/validator-management/vc-configuration.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index b0a92d66ccef..9e4547211005 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -95,17 +95,19 @@ If you are running a beacon node with connected builder relays, you may use thes With produceBlockV3 (enabled automatically after the Deneb hard fork), the `--builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). With Lodestar's `--builder.selection` options, you can select: + - `maxprofit`: Default setting for Lodestar set at `--builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `--builder.boostFactor` to your preference. Examples of its usage are below. - `executiononly`: Validator will not select the builder block even if builder relays are configured on the beacon. This option will always select the local execution block. - `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via shouldOverrideBuilder from the execution payload response. -- `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and *no block will be produced*. +- `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and _no block will be produced_. #### Examples using builder boost factor + Example 1: Setting a `--builder.boostFactor=0` will always prefer the local execution block, but will produce an available builder block if the local execution block fails. Example 2: Setting a `--builder.boostFactor=100` is the same as signaling `--builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. -Example 3: Setting `--builder.boostFactor=80` allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. +Example 3: Setting `--builder.boostFactor=80` allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. ### Submit a validator deposit From 885264992d069d2ec4cdfe4a97ffd3ab82da7472 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 19:24:56 +0100 Subject: [PATCH 09/14] Update wordlist --- .wordlist.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index 634ab95ab62e..21e5dee68b55 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -14,6 +14,7 @@ Chai ChainSafe Customizations DPoS +DVs Discv DockerHub Dockerized @@ -173,6 +174,7 @@ scalability secp sepolia sharding +shouldOverrideBuilder ssz stakers subnet From 3b98d63863b99add2eb38655bbc706e01d612b99 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 19:28:00 +0100 Subject: [PATCH 10/14] Use term "beacon node", more consistent with text above --- docs/pages/validator-management/vc-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index 9e4547211005..c46485d25699 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -97,7 +97,7 @@ With produceBlockV3 (enabled automatically after the Deneb hard fork), the `--bu With Lodestar's `--builder.selection` options, you can select: - `maxprofit`: Default setting for Lodestar set at `--builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `--builder.boostFactor` to your preference. Examples of its usage are below. -- `executiononly`: Validator will not select the builder block even if builder relays are configured on the beacon. This option will always select the local execution block. +- `executiononly`: Validator will not select the builder block even if builder relays are configured on the beacon node. This option will always select the local execution block. - `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via shouldOverrideBuilder from the execution payload response. - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and _no block will be produced_. From 3e95e21dfd043d2e6e27dd19f0ab7c55b9e518ab Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 19:44:06 +0100 Subject: [PATCH 11/14] Apply some feedback from Gajinder --- .wordlist.txt | 1 - docs/pages/validator-management/vc-configuration.md | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.wordlist.txt b/.wordlist.txt index 21e5dee68b55..5982de7b50dc 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -174,7 +174,6 @@ scalability secp sepolia sharding -shouldOverrideBuilder ssz stakers subnet diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index c46485d25699..f5642e7ff600 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -92,13 +92,13 @@ You may choose to use the `--strictFeeRecipientCheck` flag to enable a strict ch If you are running a beacon node with connected builder relays, you may use these validator configurations to signal which block (builder vs. local execution) the beacon node should produce. -With produceBlockV3 (enabled automatically after the Deneb hard fork), the `--builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). +With produceBlockV3 (enabled automatically after the Deneb hard fork), the `--builder.boostFactor` is a percentage multiplier the block producing beacon node must apply to boost (>100) or dampen (<100) builder block value for selection against execution block. The multiplier is ignored if `--builder.selection` is set to anything other than `maxprofit`. Even though this is set on the validator client, the calculation is requested and applied on the beacon node itself. For more information, see the [produceBlockV3 Beacon API](https://ethereum.github.io/beacon-APIs/#/ValidatorRequiredApi/produceBlockV3). -With Lodestar's `--builder.selection` options, you can select: +With Lodestar's `--builder.selection` validator options, you can select: - `maxprofit`: Default setting for Lodestar set at `--builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `--builder.boostFactor` to your preference. Examples of its usage are below. - `executiononly`: Validator will not select the builder block even if builder relays are configured on the beacon node. This option will always select the local execution block. -- `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via shouldOverrideBuilder from the execution payload response. +- `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response. - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and _no block will be produced_. #### Examples using builder boost factor From 84172e3e137d20f664173c216bb6bbdc12acc823 Mon Sep 17 00:00:00 2001 From: Phil Ngo Date: Mon, 15 Jan 2024 14:18:32 -0500 Subject: [PATCH 12/14] fix builder boost factor math example --- .../pages/validator-management/vc-configuration.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index f5642e7ff600..bcac57f88981 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -101,13 +101,19 @@ With Lodestar's `--builder.selection` validator options, you can select: - `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response. - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and _no block will be produced_. -#### Examples using builder boost factor +#### Calculating builder boost factor with examples -Example 1: Setting a `--builder.boostFactor=0` will always prefer the local execution block, but will produce an available builder block if the local execution block fails. +To calculate the builder boost factor setting, you need to know what percentage you will accept a builder block for against a local execution block using the following formula: `100*100/(100+percentage)`. -Example 2: Setting a `--builder.boostFactor=100` is the same as signaling `--builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. +Example 1: I will only accept a builder block with 20% more value than the local execution block. +``` +10000/(100+20) = 83.3 +``` +Therefore, `--builder.boostFactor=83.3`. + +Example 2: Setting a `--builder.boostFactor=0` will always prefer the local execution block, but will produce an available builder block if the local execution block fails. -Example 3: Setting `--builder.boostFactor=80` allows you to signal that your builder block bid needs 20% more in value comparatively to your local execution block to be selected. +Example 3: Setting a `--builder.boostFactor=100` is the same as signaling `--builder.selection maxprofit` where the validator will always select the most profitable block between the local execution engine and the builder block from the relay. ### Submit a validator deposit From 5491e1dee6e83632ab189702d5e2c433d366c28a Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 20:42:48 +0100 Subject: [PATCH 13/14] Use integer value in Example 1 --- docs/pages/validator-management/vc-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index bcac57f88981..daea28698e35 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -105,11 +105,11 @@ With Lodestar's `--builder.selection` validator options, you can select: To calculate the builder boost factor setting, you need to know what percentage you will accept a builder block for against a local execution block using the following formula: `100*100/(100+percentage)`. -Example 1: I will only accept a builder block with 20% more value than the local execution block. +Example 1: I will only accept a builder block with 25% more value than the local execution block. ``` -10000/(100+20) = 83.3 +10000/(100+25) = 80 ``` -Therefore, `--builder.boostFactor=83.3`. +Therefore, `--builder.boostFactor=80`. Example 2: Setting a `--builder.boostFactor=0` will always prefer the local execution block, but will produce an available builder block if the local execution block fails. From 9e329d45bab7db8f9ea707de1fc8a146642adae1 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 15 Jan 2024 20:59:44 +0100 Subject: [PATCH 14/14] Update executiononly description --- docs/pages/validator-management/vc-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/validator-management/vc-configuration.md b/docs/pages/validator-management/vc-configuration.md index daea28698e35..cf8f3acae060 100644 --- a/docs/pages/validator-management/vc-configuration.md +++ b/docs/pages/validator-management/vc-configuration.md @@ -97,7 +97,7 @@ With produceBlockV3 (enabled automatically after the Deneb hard fork), the `--bu With Lodestar's `--builder.selection` validator options, you can select: - `maxprofit`: Default setting for Lodestar set at `--builder.boostFactor=100`. This default setting will always choose the more profitable block. Using this option, you may customize your `--builder.boostFactor` to your preference. Examples of its usage are below. -- `executiononly`: Validator will not select the builder block even if builder relays are configured on the beacon node. This option will always select the local execution block. +- `executiononly`: Beacon node will be requested to produce local execution block even if builder relays are configured. This option will always select the local execution block and will error if it couldn't produce one. - `builderalways`: An alias of `--builder.boostFactor=18446744073709551615` (2**64 - 1), which will select the builder block, unless the builder block fails to produce. The builder block may fail to produce if it's not available, not timely or there is an indication of censorship via `shouldOverrideBuilder` from the execution payload response. - `builderonly`: Generally used for distributed validators (DVs). No execution block production will be triggered. Therefore, if a builder block is not produced, the API will fail and _no block will be produced_.