Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: re-implement validator config page with builder.boostFactor notes #6295

Merged
merged 14 commits into from
Jan 16, 2024
Merged

docs: re-implement validator config page with builder.boostFactor notes #6295

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
cd42b37
Change docs nav titles and include vc config
philknows Jan 15, 2024
145a5d6
Rename and re-include config with builder boost
philknows Jan 15, 2024
e92bd99
refactor builderboostFactor from comments
philknows Jan 15, 2024
ea37016
add clarification to maxprofit
philknows Jan 15, 2024
433815a
clarification on intro
philknows Jan 15, 2024
8f6ea7c
address additional comments
philknows Jan 15, 2024
047732b
Remove redundancies in navigation menu
nflaig Jan 15, 2024
d2400be
Just formatting changes
nflaig Jan 15, 2024
8852649
Update wordlist
nflaig Jan 15, 2024
3b98d63
Use term "beacon node", more consistent with text above
nflaig Jan 15, 2024
3e95e21
Apply some feedback from Gajinder
nflaig Jan 15, 2024
84172e3
fix builder boost factor math example
philknows Jan 15, 2024
5491e1d
Use integer value in Example 1
nflaig Jan 15, 2024
9e329d4
Update executiononly description
nflaig Jan 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .wordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Chai
ChainSafe
Customizations
DPoS
DVs
Discv
DockerHub
Dockerized
Expand Down
9 changes: 5 additions & 4 deletions docs/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
- 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
- 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
- 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:
Expand Down
38 changes: 32 additions & 6 deletions ...idator-management/validator-management.md → .../validator-management/vc-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]

Expand All @@ -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 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The term wallet here might be a bit outdated, maybe should use term keystores, or we use same wording as deposit cli introduction.

Maybe "keystores and corresponding deposit data" but since the whole section is about "Create a wallet" maybe better to revise that part in a separate PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will follow up in another PR with the best way to align this. TBH, I'm still kinda wondering if we need this as generally, most go through the Ethereum launchpad which provides all these instructions for them already. This whole section has been around for a long time when Lodestar had these features and before the existence of a lot of this tooling + other references.

Expand Down Expand Up @@ -88,11 +88,37 @@ 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 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 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` 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.
- `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_.

#### Calculating builder boost factor with examples

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.
```
10000/(100+20) = 83.3
```
Therefore, `--builder.boostFactor=83.3`.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bad news, we don't support floating point numbers (must be integer)

✖ SyntaxError: Cannot convert 83.3 to a BigInt

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

Please use the official tools to perform your deposits
Please use the official Ethereum Launchpad to perform your deposits

- `staking-deposit-cli`: <https://github.com/ethereum/staking-deposit-cli>
- Ethereum Foundation launchpad: <https://launchpad.ethereum.org>

## Run the validator
Expand All @@ -105,7 +131,7 @@ To start a Lodestar validator run the command:

You should see confirmation that modules have started.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sh should stay in here

"```sh"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those are logs, bash syntax highlighting looks wrong

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't really benefit the docs if it doesn't look similar to what you would actually even see in your terminal. Just leaving as txt should be fine

```bash
```
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
Expand Down
Loading