Expose additional builder booster related flags in the vc (#5086)

* expose builder booster flags in vc, enable options in validator endpoints, update tests * resolve failing test * fix issues related to CreateConfig and MoveConfig * remove unneeded val, change how boost factor flag logic in the vc, add some additional documentation * fix typos * fix typos * assume builder-proosals flag if one of other two vc builder flags are present * fmt * typo * typo * Fix CLI help text * Prioritise per validator builder boost configurations over CLI flags. * Add http test for builder boost factor with process defaults. * Fix issue with PATCH request * Add prefer builder proposals * Add more builder boost factor tests. --------- Co-authored-by: Mac L <mjladson@pm.me> Co-authored-by: Jimmy Chen <jchen.tc@gmail.com> Co-authored-by: Paul Hauner <paul@paulhauner.com>
2026-04-29 02:33:48 +00:00 · 2024-01-25 00:09:47 +02:00
parent 612eaf2d41
commit f9e36c94ed
28 changed files with 715 additions and 21 deletions
--- a/book/src/api-vc-endpoints.md
+++ b/book/src/api-vc-endpoints.md
@@ -427,7 +427,7 @@ Example Response Body

 ## `PATCH /lighthouse/validators/:voting_pubkey`

-Update some values for the validator with `voting_pubkey`. Possible fields: `enabled`, `gas_limit`, `builder_proposals`, 
+Update some values for the validator with `voting_pubkey`. Possible fields: `enabled`, `gas_limit`, `builder_proposals`, `builder_boost_factor`, `prefer_builder_proposals`
 and `graffiti`.  The following example updates a validator from `enabled: true` to `enabled: false`.

 ### HTTP Specification
--- a/book/src/builders.md
+++ b/book/src/builders.md
@@ -31,6 +31,18 @@ blinded blocks, you should use the following flag:
 lighthouse vc --builder-proposals
 ```
 With the `--builder-proposals` flag, the validator client will ask for blinded blocks for all validators it manages.
+
+```
+lighthouse vc --prefer-builder-proposals
+```
+With the `--prefer-builder-proposals` flag, the validator client will always prefer blinded blocks, regardless of the payload value, for all validators it manages.
+
+```
+lighthouse vc --builder-boost-factor <INTEGER>
+```
+With the `--builder-boost-factor` flag, a percentage multiplier is applied to the builder's payload value when choosing between a
+builder payload header and payload from the paired execution node.
+
 In order to configure whether a validator queries for blinded blocks check out [this section.](#validator-client-configuration)

 ## Multiple builders
@@ -46,9 +58,9 @@ relays, run one of the following services and configure lighthouse to use it wit
 In the validator client you can configure gas limit and fee recipient on a per-validator basis. If no gas limit is
 configured, Lighthouse will use a default gas limit of 30,000,000, which is the current default value used in execution
 engines.  You can also enable or disable use of external builders on a per-validator basis rather than using
-`--builder-proposals`, which enables external builders for all validators. In order to manage these configurations
-per-validator, you can either make updates to the `validator_definitions.yml` file or you can use the HTTP requests
-described below.
+`--builder-proposals`, `--builder-boost-factor` or `--prefer-builder-proposals`, which apply builder related preferences for all validators.
+In order to manage these configurations per-validator, you can either make updates to the `validator_definitions.yml` file
+or you can use the HTTP requests described below.

 Both the gas limit and fee recipient will be passed along as suggestions to connected builders. If there is a discrepancy
 in either, it will *not* keep you from proposing a block with the builder. This is because the bounds on gas limit are
--- a/book/src/help_vc.md
+++ b/book/src/help_vc.md
@@ -56,6 +56,9 @@ FLAGS:
            machine. Note that logs can often contain sensitive information about your validator and so this flag should
            be used with caution. For Windows users, the log file permissions will be inherited from the parent folder.
        --metrics                                Enable the Prometheus metrics HTTP server. Disabled by default.
+        --prefer-builder-proposals
+            If this flag is set, Lighthouse will always prefer blocks constructed by builders, regardless of payload
+            value.
        --produce-block-v3
            Enable block production via the block v3 endpoint for this validator client. This should only be enabled
            when paired with a beacon node that has this endpoint implemented. This flag will be enabled by default in
@@ -80,6 +83,9 @@ OPTIONS:
            Comma-separated list of beacon API topics to broadcast to all beacon nodes. Possible values are: none,
            attestations, blocks, subscriptions, sync-committee. Default (when flag is omitted) is to broadcast
            subscriptions only.
+        --builder-boost-factor <UINT64>
+            Defines the boost factor, a percentage multiplier to apply to the builder's payload value when choosing
+            between a builder payload header and payload from the local execution node.
        --builder-registration-timestamp-override <builder-registration-timestamp-override>
            This flag takes a unix timestamp value that will be used to override the timestamp used in the builder api
            registration
--- a/book/src/help_vm_create.md
+++ b/book/src/help_vm_create.md
@@ -42,6 +42,9 @@ OPTIONS:
            A HTTP(S) address of a beacon node using the beacon-API. If this value is provided, an error will be raised
            if any validator key here is already known as a validator by that beacon node. This helps prevent the same
            validator being created twice and therefore slashable conditions.
+        --builder-boost-factor <UINT64>
+            Defines the boost factor, a percentage multiplier to apply to the builder's payload value when choosing
+            between a builder payload header and payload from the local execution node.
        --builder-proposals <builder-proposals>
            When provided, all created validators will attempt to create blocks via builder rather than the local EL.
            [possible values: true, false]
@@ -93,13 +96,18 @@ OPTIONS:
        --logfile-max-size <SIZE>
            The maximum size (in MB) each log file can grow to before rotating. If set to 0, background file logging is
            disabled. [default: 200]
-        --mnemonic-path <MNEMONIC_PATH>                         If present, the mnemonic will be read in from this file.
+        --mnemonic-path <MNEMONIC_PATH>
+            If present, the mnemonic will be read in from this file.
+
        --network <network>
            Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis,
            chiado, sepolia, holesky]
        --output-path <DIRECTORY>
            The path to a directory where the validator and (optionally) deposits files will be created. The directory
            will be created if it does not exist.
+        --prefer-builder-proposals <prefer-builder-proposals>
+            If this flag is set, Lighthouse will always prefer blocks constructed by builders, regardless of payload
+            value. [possible values: true, false]
        --safe-slots-to-import-optimistically <INTEGER>
            Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should
            only be used if the user has a clear understanding that the broad Ethereum community has elected to override
--- a/book/src/help_vm_move.md
+++ b/book/src/help_vm_move.md
@@ -26,10 +26,13 @@ FLAGS:
    -V, --version                        Prints version information

 OPTIONS:
+        --builder-boost-factor <UINT64>
+            Defines the boost factor, a percentage multiplier to apply to the builder's payload value when choosing
+            between a builder payload header and payload from the local execution node.
        --builder-proposals <builder-proposals>
            When provided, all created validators will attempt to create blocks via builder rather than the local EL.
            [possible values: true, false]
-        --count <VALIDATOR_COUNT>                               The number of validators to move.
+        --count <VALIDATOR_COUNT>                                The number of validators to move.
    -d, --datadir <DIR>
            Used to specify a custom root data directory for lighthouse keys and databases. Defaults to
            $HOME/.lighthouse/{network} where network is the value of the `network` flag Note: Users should specify
@@ -75,6 +78,9 @@ OPTIONS:
        --network <network>
            Name of the Eth2 chain Lighthouse will sync and follow. [possible values: mainnet, prater, goerli, gnosis,
            chiado, sepolia, holesky]
+        --prefer-builder-proposals <prefer-builder-proposals>
+            If this flag is set, Lighthouse will always prefer blocks constructed by builders, regardless of payload
+            value. [possible values: true, false]
        --safe-slots-to-import-optimistically <INTEGER>
            Used to coordinate manual overrides of the SAFE_SLOTS_TO_IMPORT_OPTIMISTICALLY parameter. This flag should
            only be used if the user has a clear understanding that the broad Ethereum community has elected to override