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.
Learn about the 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.
- Add Builder
- Remove Builder
1. Validator Client: register validator
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
--enable-builder flags. All validators will be registered periodically by using the
--proposer-settings-url flags with builder settings will override values provided from
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 5. Builder: connected via relay URL 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 fall back to 4. Local Execution Client.
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
- remove the
--suggested-gas-limitflag, though it should already be disabled once removing the
- remove all wanted references of the
builderfield from the associated file/json for the validators you no longer want to register within the
2. Beacon Node: remove builder related flags
The following flag should be removed to disable builder use on the beacon node:
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:
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
--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
- if configuring with the
--proposer-settings-fileflag and provide it with a suitable JSON or YAML file. This file should include the necessary configuration for the builder. For detailed guidance and an example of this configuration, refer to the MEV Builder and Gas Limit configuration guide.
- 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 here.
- if configuring with the
--proposer-settings-urlflag with no builder settings but providing the
--enable-builderflag instead. Optionally, you can also add the
--suggested-gas-limitto adjust the default gas limit for the builder, this only applies with
Validators updated through the Keymanager-API's fee recipient APIs will take on the default
--enable-builder flag is used without providing
--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.
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
Advanced Beacon Node Configurations
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 3 slots are consecutively missed or 5 slots are missed in an epoch, but this can be configured through the
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. note: 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.
By default the beacon node will construct the consensus and execution portions of the beacon block in parallel to improve speed and efficiency.
--disable-build-block-parallel flag can be added to prevent node from building in parallel and will build sequentially.
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 will encourage your setup to use the local execution if the value earned is not above your threshold, helping to mitigate censorship concerns.
Frequently asked questions
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.
Q: What are the risks of running Prysm with a custom builder instead of using local execution?
A: 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.
Q: Do I need to run my execution client while using a custom builder?
A: Yes, the execution client will perform standard tasks and also be the fallback mechanism if the builder is not working correctly.
Q: How do I recover if the circuit breaker is triggered?
A: 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.
Q: What happens if the execution client goes down while connected to the builder?
A: 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.
Q: My setup is no longer using the builder. What happened?
A: 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.
Q: What if the earnings from the builder are lower than from local execution?
A: 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.