MEV-Boost (before Gloas)
This guide is for advanced Prysm users to configure their client for the purposes of extracting MEV. There are risks to using a builder which may result in missed rewards, missed proposals, censored transactions or omitted transactions. The Prysm team does not provide guidance on which builders/relays are recommended but lists are available for you to make a judgment based on your own values.
This page describes block building with builders before the Gloas fork, using relays, MEV-Boost, periodic validator registration, and the --http-mev-relay flag. It applies until your network reaches the fork epoch; after that, none of it is used, and this page will be removed. From the fork onward, builders are configured on the validator client instead; see Configure MEV Builder. Migrating to v2 builder settings now changes nothing on this page: registration, relays, and --http-mev-relay keep working until the fork, and your builder configuration keeps working after it.
Learn about the Builder Lifecycle
Builder lifecycle
Sign a validator registration request: This request contains validator proposer_settings with fields like fee_recipient, gas_limit and the current timestamp to be signed.
Submit signed validator registrations to the builder: call the beacon API endpoint which calls a builder API endpoint on the builder for the registration. Some relays will allow you to query which validators are registered currently.
Validator selected as a block proposer: extracting MEV will only be applicable when your validator has its turn to propose a block.
Check if the builder is configured: The beacon node does a check to see if the builder is properly configured and the proposing validator is registered. You will not be able to retrieve a blinded block if you do not pass the builder configuration check.
Get and verify a blinded block: If the builder is configured, the beacon node will call the builder API to get a payload header which is used to produce the blinded block. There are several steps of verification in this process.
Sign the blinded block: once the blinded block passes internal validation it is signed. At this point, the validator will no longer have the power to propose a block other than the builder's block or risk being slashed as the builder holds the validator's signature.
Submit the blinded block to the builder to get the full execution payload: the signed blinded block is returned to the builder via the builder API for the full payload. When the builder gets the signed blinded block, it broadcasts the signed un-blinded block to the network, then it sends back the signed unblinded block to the proposer.
Unblind the block with the full payload: using the response of the builder, the blinded block can be converted into a full block with the full execution payload.
Broadcast the full block: the full block at this point is broadcasted to the network.
In case of failures in the validator, such as bad connections or incorrect configurations, the beacon node will attempt to fall back to local execution, reconnecting to a regular execution client to ensure proper block processing.
Builder configuration
- Add Builder
- Remove Builder
1. Validator Client: register validator
To register the validator against the builder and enable the use of custom builders, the proposer-settings will need to be configured.
It is recommended to configure with the validator client with the --suggested-fee-recipient and --enable-builder flags. All validators will be registered periodically by using the --enable-builder flag.
note: --proposer-settings-file or --proposer-settings-url flags with builder settings will override values provided from --suggested-fee-recipient and --enable-builderflags.
With v2 proposer settings, a key with a non-empty builders list is registered and a key with an empty list is not, so you don't need --enable-builder; see Running v2 settings before the Gloas fork. The flag only affects registration before the fork, and Prysm warns that it does nothing after it. If you keep it, it registers every key that follows default_config, even when default_config has "builders": []; a key's own builders list still wins.
2. Beacon Node: connect to the builder
To use a builder the beacon node needs to start with the following configuration:
--http-mev-relayflag pointed to any Builder API compatible endpoint. The most common use case is to target a MEV-Boost instance. A less common use case is to directly target a relay (5. Builder: connected via relay URL).
Each relay's URL will correspond to a specific network and will need to be chosen accordingly, i.e., running a beacon node on mainnet will require the mainnet relay.
3. Is builder configured?
When a validator is proposing a block, the following is checked before attempting to use the builder through the relay:
--http-mev-relayflag was provided and is pointed to MEV-Boost or an active relay of the correct network- circuit breaker is not triggered
- validator is registered (beacon API was successfully called and validator registration info is stored in the beacon node's db)
If all checks are satisfied, then we go to Step 5 which will be used to get the execution payload (which contains the transactions) and build a blinded block. However, if the checks do not pass, then the beacon node will proceed to Step 4.
4. Local execution client: kept in sync and up to date
Local execution clients such as Geth or Nethermind must continue to run as usual even while using a builder and will be used in case the builder does not pass the Is Builder Configured? check. The execution client should be synced and running alongside your beacon node, and earnings from the block will be compared to the earnings from the builder's payload. If the local execution payload fails then the entire function will fail.
5. Builder: connected via relay URL
The EthStaker community provides a list of some of the relays that can be used as well as any censorship they may have here. You can also run your own relay locally such as MEV-Boost but each relay on the list will have their own instructions on how to run it. If running your own relay, instead of using a provided URL due to latency, you will simply need to update the --http-mev-relay flag on your beacon node with the appropriate URL for the specific network in use. The relay will connect to a builder which connects to block searchers.
Make sure you are using the correct version that supports the current version of the beacon node. Hard-forks will typically require updates to relays.
1. Validator Client: unregister validator
Update the following configurations and restart the validator client to stop the periodic registration of the validator.
- remove the
--enable-builderflag. - remove the
--suggested-gas-limitflag. It sets the registration gas limit whether or not--enable-builderis set, and from the Gloas fork onward it overrides the network gas limit schedule for every key (see the gas limit warning). - remove all wanted references of the
builderfield from the associated file/json for the validators you no longer want to register within the--proposer-settings-fileand--proposer-settings-urlflag.
With v2 proposer settings, set "builders": [] on the keys you want to unregister. An empty list means the key uses no builders: it isn't registered before the fork and doesn't request bids after it. Deleting the key's builder object instead makes it follow default_config, the settings for every key without an entry of its own, which may still list builders.
2. Beacon Node: remove builder related flags
The following flag should be removed to disable builder use on the beacon node:
--http-mev-relayflag
The register validator Beacon API will also stop working with the removal of the --http-mev-relay flag and will no longer know the URL to MEV-Boost or the active relay.
The following flags will be disabled after this flag is removed, and can safely be removed:
--max-builder-consecutive-missed-slots--max-builder-epoch-missed-slots--local-block-value-boost
3. Is builder configured?
Once the appropriate flags are fully removed this check shouldn't pass and will fall back to local execution.
4. Local execution client: kept the same
The execution client can safely continue to run "as-is" with no changes. Once the validator client and beacon node have their settings updated and restarted without builder changes, blocks will continue to be produced through with the payloads from local execution.
5. Builder: remove relay URL
removing the --http-mev-relay flag from the beacon node will disconnect the builder. Once removed, you can safely turn off your builder related services such as your MEV-Boost or relays.
Advanced Validator Client Configurations
Advanced Validator Registration
There are other ways to configure your validator registrations for more granular control on which validator keys should be registered to use the custom builder and which ones should use local execution.
In these cases you would replace the --suggested-fee-recipient flag with --proposer-settings-file flag or --proposer-settings-url flag.
- If configuring with the
--proposer-settings-fileflag, provide it with a suitable JSON or YAML file. This file should include the builder's required configuration. For detailed guidance and an example, refer to the Proposer settings reference. - If configuring with the
--proposer-settings-urlflag, provide a URL that returns the JSON response with the suitable proposer-settings. A guide and example on this configuration can be found in the Proposer settings reference. - If configuring with the
--proposer-settings-fileor--proposer-settings-urlflag with no builder settings but providing the--enable-builderflag instead. Optionally, you can also add--suggested-gas-limitto adjust the gas limit sent with registrations; it works with or without--enable-builder.--enable-builderonly applies before the Gloas fork (see What replaces what), and after it,--suggested-gas-limitoverrides the gas limit schedule for every key (see the gas limit warning).
Validators updated through the Keymanager-API's fee recipient APIs will take on the default proposer-settings provided.
If the --enable-builder flag is used without providing --suggested-fee-recipient, --proposer-settings-file, or --proposer-settings-url it will override builder settings from the db if proposer settings are saved, or it will set default builder settings and only save to the db if fee-recipient settings are saved through the keymanager APIs.
The validator client utilizes proposer-settings to interact with the beacon node's Beacon API. Subsequently, the beacon node calls the builder by making use of the Builder API.
Registration against the builder will only occur for active validators. Registration for eligible validators occurs at the beginning of the validator clients execution and at the middle of each epoch. It is important to note that the success of the API is not guaranteed, and the client will attempt registration again at the middle of each epoch.
The beacon node must also be configured to enable the builder via the --http-mev-relay flag.
Advanced Beacon Node Configurations
Circuit breaker
The circuit breaker is a safety feature for falling back to local execution when using a builder.
This occurs when the builder or client using the builder endpoints encounters issues that cause missed blocks.
By default, the circuit breaker will be triggered after three slots are consecutively missed or five slots are missed in an epoch, but this can be configured through the --max-builder-consecutive-missed-slots and max-builder-epoch-missed-slots flags.
This circuit breaker and its two flags only apply before the Gloas fork. After the fork, Prysm tracks builders individually, as described in How a Gloas proposal uses builders.
Registration cache
Validator registrations for Builder APIs are stored in a cache by default as of 4.0.7 instead of bolt db when starting the beacon node. The cache will enable:
- in-memory storage of the validator registrations, this clears all validator registrations on restart. This feature solves the unintended issue of wanting some validators unregistered while maintaining MEV-Boost on others. In the future the db used to store registrations will be removed completely and the flag will no longer be required for this feature. Validator settings will be persisted on the validator client side.
--disable-registration-cache flag can be used on the beacon node to fall back onto the using the bolt db.
Values stored in the bolt db will not be cleared and you will not be able to unregister validators unless using the cache and restarting.
Prioritizing local blocks
--local-block-value-boost flag is a uint64 value that provides an additional percentage to multiply the local block value. Use builder block if: builder_bid_value * 100 > local_block_value * (local-block-value-boost + 100). This encourages your setup to use local execution if the value earned is below your threshold, helping mitigate censorship concerns. After the Gloas fork, the equivalent control is the per-key builder_boost_factor in proposer settings.
Frequently asked questions: MEV-Boost
The provided guide offered explanations on configuring the Prysm client to utilize a custom builder through a relay. The relay acts as a middleware that connects validators to block builders. This configuration involves both the validator client and the beacon node. It's important to note this guide does not cover setting up your own relay, builder, or MEV-Boost software.
In the Prysm client, the builder is used through the relay to get transactions that maximize the validator's benefits, prioritizing them over local ones. However, the execution client will still be necessary as a fallback option in case any issues arise while utilizing the builder. The builder will only come into play when there is a validator proposal.
What are the risks of running Prysm with a custom builder instead of using local execution?
The custom builder, whether connected through MEV-Boost or as a relay URL, will need to be updated consistently with Prysm, adding another layer of complexity. Depending on the relay used some rewards may be missed due to the relay's connectivity or any builder bugs. Transactions may be censored under certain conditions.
How do I recover if the circuit breaker is triggered?
Once the circuit breaker is triggered, local execution will continue to be used until both conditions: max consecutive slots missed and slots missed in epoch are no longer true. The beacon node does not need to be restarted.
What happens if the execution client goes down while connected to the builder?
The earnings from the local execution payload will be compared to the bid from the builder payload and will error if local execution is offline or unavailable.
My setup is no longer using the builder. What happened?
There are multiple reasons why this could happen, including an incorrect relay URL, a relay that is offline or outdated compared to your Ethereum node setup, or a possible bug. Additionally, it's possible that the circuit breaker has been activated.
What if the earnings from the builder are lower than from local execution?
The block from local execution will be used. This could also be triggered through --local-block-value-boost if the earnings from the builder don't pass some percentage threshold.