Skip to main content

Configure MEV Builder

caution

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​

Builder lifecycle
  1. 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.
  2. 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.
  3. Validator selected as a block proposer: extracting MEV will only be applicable when your validator has its turn to propose a block.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. 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​

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.

2. Beacon Node: connect to the builder​

To use a builder the beacon node needs to start with the following configuration:

  • --http-mev-relay flag 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-relay flag 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.

info

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.

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-file flag 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-url flag 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-file or --proposer-settings-url flag with no builder settings but providing the --enable-builder flag instead. Optionally, you can also add the --suggested-gas-limit to adjust the default gas limit for the builder, this only applies with --enable-builder.
info

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 3 slots are consecutively missed or 5 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.

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

Parallel execution​

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.

info

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.