diff --git a/docs/int/quickstart/advanced/quickstart-builder-api.md b/docs/int/quickstart/advanced/quickstart-builder-api.md index 60e1e7c82b..5ba5c7f782 100644 --- a/docs/int/quickstart/advanced/quickstart-builder-api.md +++ b/docs/int/quickstart/advanced/quickstart-builder-api.md @@ -3,15 +3,16 @@ sidebar_position: 2 description: Run a distributed validator cluster with the builder API (MEV-Boost) --- -# Run a cluster with MEV-Boost +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Run a cluster with MEV enabled :::caution Charon is in an alpha state and should be used with caution according to its [Terms of Use](https://obol.tech/terms.pdf). - -Charon's integration with MEV-Boost is also in an alpha state and requires a non-trivial amount of configuration to get working successfully. In the future, this process aims to be much more automated and seamless from a user's perspective. ::: -This quickstart guide focuses on configuring the builder API for Charon and supported Validator clients. +This quickstart guide focuses on configuring the builder API for Charon and supported validator and consensus clients. ## Getting started with Charon & the Builder API @@ -19,21 +20,22 @@ Running a distributed validator cluster with the builder API enabled will give t who work with MEV searchers to produce the most valuable blocks a validator can propose. [MEV-Boost](https://boost.flashbots.net/) is one such product from flashbots that enables you to ask multiple -block relays (who communicate with the "Block Builders") for blocks to propose. The block that pays the largest reward to the validator will be signed and returned to the relay for broadcasting to the wider -network. The end result for the validator is generally an increased APY as they receive some share of the MEV. - -## Run MEV Boost +block relays (who communicate with the "Block Builders") for blocks to propose. The block that pays the largest reward to the validator will be signed and returned to the relay for broadcasting to the wider +network. The end result for the validator is generally an increased APR as they receive some share of the MEV. -Before running MEV-boost please check your cluster version, which can be found inside the cluster-lock.json file. -If you are using cluster-lock version 1.7.0 or higher release verions, Obol seamlessly accommodates all validator client implementations within a mev-enabled distributed validator cluster. +:::info +Before completing this guide, please check your cluster version, which can be found inside the `cluster-lock.json` file. If you are using cluster-lock version `1.7.0` or higher release verions, Obol seamlessly accommodates all validator client implementations within a mev-enabled distributed validator cluster. -Currently, Charon with the builder API enabled, is compatible only with [Teku](https://github.com/ConsenSys/teku) on any cluster-lock versions below 1.7.0. +For clusters with a cluster-lock version `1.6.0` and below, charon is compatible only with [Teku](https://github.com/ConsenSys/teku). Use the version history feature of this documentation to see the instructions for configuring a cluster in that manner (`v0.16.0`). +::: -## Builder API +## Client configuration -If you want to configure Charon and supported Validator clients to support the builder API feature, you can do that as well. +:::note +You need to add CLI flags to your consensus client, charon client, and validator client, to enable the builder API. -Currently, Charon with the builder API enabled, is compatible with all validator client implementations in a mev-enabled distributed validator cluster seamlessly. +You need all operators in the cluster to have their nodes properly configured to use the builder API, or you risk missing a proposal. +::: ### Charon @@ -43,41 +45,119 @@ Charon supports builder API with the `--builder-api` flag. To use builder API, o charon run --builder-api ``` -### Validator Clients - -#### Teku Validator Client - -Configuring the Teku validator client with Charon can be done by following the same process outlined in the [Teku official guide](https://docs.teku.consensys.net/how-to/configure/use-proposer-config-file). - -The validator client must be set up to use the `--validators-proposer-config` [flag](https://docs.teku.consensys.net/reference/cli#validators-proposer-config) with a value equal to `http://$CHARON_ENDPOINT:3600/teku_proposer_config`. +### Consensus Clients + +The following flags need to be configured on your chosen consensus client. A flashbots relay URL is provided for example purposes, you should choose a relay that suits your preferences from [this list](https://github.com/eth-educators/ethstaker-guides/blob/main/MEV-relay-list.md#mev-relay-list-for-mainnet). + + + + Teku can communicate with a single relay directly: + 
+      
+    {String.raw`--builder-endpoint="https://0xac6e77dfe25ecd6110b8e780608cce0dab71fdd5ebea22a16c0205200f2f8e2e3ad3b71d3499c54ad14d6c21b41a37ae@boost-relay.flashbots.net"`}
+      
+
+ Or you can configure it to communicate with a local MEV-boost sidecar to configure multiple relays: + 
+      
+    {String.raw`--builder-endpoint=http://mev-boost:18550`}
+      
+
+ + + Lighthouse can communicate with a single relay directly: + 
+      
+    {String.raw`lighthouse bn --builder "https://0xac6e77dfe25ecd6110b8e780608cce0dab71fdd5ebea22a16c0205200f2f8e2e3ad3b71d3499c54ad14d6c21b41a37ae@boost-relay.flashbots.net"`}
+      
+
+ Or you can configure it to communicate with a local MEV-boost sidecar to configure multiple relays: + 
+      
+    {String.raw`lighthouse bn --builder "http://mev-boost:18550"`}
+      
+
+ + + 
+      
+    {String.raw`prysm beacon-chain --http-mev-relay "https://0xac6e77dfe25ecd6110b8e780608cce0dab71fdd5ebea22a16c0205200f2f8e2e3ad3b71d3499c54ad14d6c21b41a37ae@boost-relay.flashbots.net"`}
+      
+
+ + + 
+      
+        {String.raw`--payload-builder=true --payload-builder-url="https://0xac6e77dfe25ecd6110b8e780608cce0dab71fdd5ebea22a16c0205200f2f8e2e3ad3b71d3499c54ad14d6c21b41a37ae@boost-relay.flashbots.net"`}
+      
+
+ You should also consider adding --local-block-value-boost 3 as a flag, to favour locally built blocks if they are withing 3% in value of the relay block, to improve the chances of a successful proposal. + + + 
+      
+    {String.raw`--builder --builder.urls "https://0xac6e77dfe25ecd6110b8e780608cce0dab71fdd5ebea22a16c0205200f2f8e2e3ad3b71d3499c54ad14d6c21b41a37ae@boost-relay.flashbots.net"`}
+      
+
+ + -Once the flag is set up, Obol distributed validators will be able to register to the builder network, submit blinded beacon blocks and gain a share of the MEV profits. - -#### Lighthouse Validator Client - -For lighthouse, configuring the VC with Charon can be done by following the same process outlined in the [Lighthouse official guide](https://lighthouse-book.sigmaprime.io/builders.html). - -The validator client must be set up to use the `--builder-proposals` [flag](https://lighthouse-book.sigmaprime.io/builders.html#how-to-connect-to-a-builder) with a value equal to `http://$CHARON_ENDPOINT:3600/proposer_config`. +### Validator Clients -Once the flag is set up, Obol distributed validators will be able to register to the builder network, submit blinded beacon blocks and gain a share of the MEV profits. +The following flags need to be configured on your chosen validator client + + + + 
+      
+    {String.raw`teku validator-client --validators-proposer-blinded-blocks-enabled=true `}
+      
+
+ + + + 
+      
+    {String.raw`lighthouse vc --builder-proposals`}
+      
+
+ + + 
+      
+    {String.raw`prysm validator --enable-builder`}
+      
+
+ + + 
+      
+        {String.raw`--payload-builder=true`}
+      
+
+ + + 
+      
+    {String.raw`--builder`}
+      
+
+ + + +## Verify your cluster is correctly configured + +It can be difficult to confirm everything is configured correctly with your cluster until a proposal opportunity arrives, but here are some things you can check. + +When your cluster is running, you should see if charon is logging something like this each epoch: +``` +13:10:47.094 INFO bcast Successfully submitted validator registration to beacon node {"delay": "24913h10m12.094667699s", "pubkey": "84b_713", "duty": "1/builder_registration"} +``` -## Verify MEV Boost is functional +This indicates that your charon node is successfully registering with the relay for a blinded block when the time comes. -Once you have executed the above steps, you can verify if your setup is functional by reviewing your proposed blocks on [beaconcha.in](https://beaconcha.in) dashboards or via the Relay API endpoints. +If you are using the [ultrasound relay](https://relay.ultrasound.money), you can enter your cluster's distributed validator public key(s) into their website, to confirm they also see the validator as correctly registered. -:::caution -Note that the mainnet block in the below description is taken only for representation, and not actually proposed by a distributed validator. -:::caution +You should check that your validator client's logs look healthy, and ensure that you haven't added a `fee-recipient` address that conflicts with what has been selected by your cluster in your cluster-lock file, as that may prevent your validator from producing a signature for the block when the opportunity arises. You should also confirm the same for all of the other peers in your cluster. -As an example, if my validator was the block proposer for block `17370078` on mainnet, I can review the following resources: - -* [Beaconcha.in](https://beaconcha.in): - * Consider this [Mainnet block 17370078](https://beaconcha.in/block/17370078). - * If we check the `Block Extra Data` field under `Execution Payload`, we will see the tag `Illuminate Dmocratize Dstribute` (Hex:`0x496c6c756d696e61746520446d6f63726174697a6520447374726962757465`). - * Relays will generally add a tag to the block. Since this block was submitted via the Flashbots Relay, as a result it has the tag. - * All mainnet flashbots blocks have this tag `Illuminate Dmocratize Dstribute`. -* [Relay API](https://flashbots.github.io/relay-specs/): - * If you navigate to the `Data API` section on the Relay API page, you will see an endpoint labeled `/relay/v1/data/bidtraces/proposer_payload_delivered`. - * You can add a query argument of `block_number` to this call to see if a block was submitted via that Relay. - * [Here](https://boost-relay.flashbots.net/relay/v1/data/bidtraces/proposer_payload_delivered?block_number=17370078) is the query for the example block 17370078. - * Blocks that have not been submitted to the Relay will return an empty array `[]`. +Once a proposal has been made, you should look at the `Block Extra Data` field under `Execution Payload` for the block on [Beaconcha.in](https://beaconcha.in/block/17370078), and confirm there is text present, this generally suggests the block came from a builder, and was not a locally constructed block. \ No newline at end of file