Skip to main content

MEV Boost & Builder API (Teku)

Connect to the SecureRpc Builder Network​

You can connect to a builder network to generate execution payloads for the consensus client

The builder recommends new blocks that are validated by the consensus client. If the builder goes down, the local execution client proposes a block instead.

The guide below is for the Teku client

Configure an endpoint​

To configure a builder endpoint:

Enable blinded block production​

Enable blinded block production using the --validators-proposer-blinded-blocks-enabled command line option.

Specify the builder endpoint using --builder-endpoint

--builder-endpoint="https://builder-relay-sepolia.flashbots.net/"

View the list of relay endpoints

--builder-endpoint=http://127.0.0.1:18550

Register the validator​

You must register your validator with the builder before proposing a block. Enable registration for all validators using --validators-builder-registration-default-enabled

To enable registration for specific validators only, use the –validators-proposal-config option and specify the enabled validators in the proposer_config of the proposer configuration JSON file.

Note the default_config applies to all validators who don’t have their own proposer configuration.

proposerConfig.json

{
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "builder": {
        "enabled": true,
        "gas_limit": "12345654321"
      }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": {
      "enabled": false
    }
  }
}

In this example, validator 0xa057816... is registered with the builder, but any validator using the default configuration is not.

Example builder configurations​

Validator client and beacon node in a single process

teku --validators-proposer-default-fee-recipient="0xA0766B65A4f7B1da79a1AF79aC695456eFa28644" --ee-endpoint="http://127.0.0.1:8551" --ee-jwt-secret-file="/etc/jwt-secret.hex" --validators-builder-registration-default-enabled=true --builder-endpoint="http://127.0.0.1:18550"

Validator client and beacon node in separate processes

Validator client parameters

teku validator-client --validators-proposer-blinded-blocks-enabled=true --validators-proposer-config="/etc/teku/proposerConfig.json"

Proposer configuration

{
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0xA0766B65A4f7B1da79a1AF79aC695456eFa28644",
    }
  },
  "default_config": {
    "fee_recipient": "0xA0766B65A4f7B1da79a1AF79aC695456eFa28644",
    "builder": {
      "enabled": true
    }
  }
}

Beacon node paramaters

teku --validators-proposer-default-fee-recipient="0xA0766B65A4f7B1da79a1AF79aC695456eFa28644" --ee-endpoint="http://127.0.0.1:8551" --ee-jwt-secret-file="/etc/jwt-secret.hex" --builder-endpoint="http://127.0.0.1:18550"

https://docs.teku.consensys.net/en/latest/HowTo/Builder-Network/ for the official documentation.**

The following steps need to be taken in order to enable mev boost (builder flow) in Teku. If everything is setup correctly, new blocks will be recommended by the builder and the proposers (validators) will start receiving MEV Rewards.

Enable blinded blocks​

Blinded block production must be enabled.

--validators-proposer-blinded-blocks-enabled=true

Note​

If --validators-builder-registration-default-enabled is set to true, then --validators-proposer-blinded-blocks-enabled automatically will default to true, so no need to set it explicitly.

Specify Builder endpoint​

A builder endpoint must be specified.

To use multiple relays, a middleware like mev-boost can be used.

--builder-endpoint="http://127.0.0.1:18550 "

For testing purpose Mergemock can be used to set up a local builder relay.

--builder-endpoint="http://127.0.0.1:28545 "

Validator Registration​

https://github.com/ethereum/builder-specs/blob/main/specs/validator.md#validator-registration

Validators must be registered with the builder prior to proposing a block.

Enabling Validator Registration​

There are couple of ways to enable validator registration.

CLI Arguments​

This will enable registration for all validators. The default value is false.

--validators-builder-registration-default-enabled=true

Enabling this option will automatically enable --validators-proposer-blinded-blocks-enabled=true.

Also, the default gas limit for the registrations can be changed. The default is 30 million.

--Xvalidators-builder-registration-default-gas-limit=29000000

In case a more fine-grained configuration is needed, a proposer configuration must be used.

Proposer Configuration​

The proposer configuration is a json, which can be either loaded from URL or from a file.

--validators-proposer-config=/etc/teku/proposerConfig.json

An example of a proposer config is:

{
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "builder": {
        "enabled": true,
        "gas_limit": "12345654321"
      }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": {
      "enabled": false
    }
  }
}

In this example, the validator 0xa057816... is eligible for registering, since it has specified a builder with enabled set to true in the proposer_config. The builder also allows a custom gas limit value. In case there is no builder the values in the default_config would be used. In case there is no builder both in the proposer_config and in the default_config, then the CLI values are used.

Validator registration overrides​

It is possible to override validator registration values. It is an useful feature in deployments where validator keys are shared between multiple nodes (Obol, SSV or similar), where nodes require to register using the exact same registration message.

You can override timestamp and public key registration values using CLI options:

  • --Xvalidators-builder-registration-timestamp-override
  • --Xvalidators-builder-registration-public-key-override

These values could also be overriden via registration_overrides field in the proposer config:

{
  "proposer_config": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
      "fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
      "builder": {
        "enabled": true,
        "registration_overrides": {
          "timestamp": "1234",
          "public_key": "0xb53d21a4cfd562c469cc81514d4ce5a6b577d8403d32a394dc265dd190b47fa9f829fdd7963afdf972e5e77854051f6f"
        }
      }
    }
  },
  "default_config": {
    "fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
    "builder": {
      "enabled": false,
      "registration_overrides": {
        "timestamp": "1235",
        "public_key": "0xa491d1b0ecd9bb917989f0e74f0dea0422eac4a873e5e2644f368dffb9a6e20fd6e10c1b77654d067c0618f6e5a7f79a"
      }
    }
  }
}

In case the proposer config is used, it will take precendence over the CLI options.

Fee Recipient​

Currently, the same fee recipient is used in both the normal flow and the builder flow for a given validator.

You can look at https://docs.teku.consensys.net/en/latest/HowTo/Prepare-for-The-Merge/#configure-the-fee-recipient for how to configure the fee recipient in Teku.

Batch sending of validator registrations​

Currently, the validator registrations are sent in batches of 100 registrations when sent to the Beacon Node (which then forwards them to mev-boost/relay). This value is configurable by setting --Xvalidators-builder-registration-sending-batch-size

Simple setup example (solo staker, VC and BN in sigle process)​

--validators-proposer-default-fee-recipient="0x6e35733c5af9B61374A128e6F85f553aF09ff89A "--ee-endpoint="http://127.0.0.1:8551 "#points to local EL
--ee-jwt-secret-file="/etc/jwt-secret.hex "#jwt authentication againts local EL
--validators-builder-registration-default-enabled=true #all validators will be using MEV
--builder-endpoint="http://127.0.0.1:18550 "#points to local mev-boost

Complex setup example (VC and BN in separate process)​

VC params​

--validators-proposer-blinded-blocks-enabled=true
--validators-proposer-config="/etc/teku/proposerConfig.json "```

Let 's enable MEV by default, and keep it disabled for a specific key.
```json
{
  "proposer_config ": {
    "0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a ": {
      "fee_recipient ": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3 ",
      "builder ": {
        "enabled ": false
      }
    }
  },
  "default_config ": {
    "fee_recipient ": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A ",
    "builder ": {
      "enabled ": true
    }
  }
}

BN params​

--validators-proposer-default-fee-recipient="0x6e35733c5af9B61374A128e6F85f553aF09ff89A "# fallback fee recipient
--ee-endpoint="http://127.0.0.1:8551 "#points to local EL
--ee-jwt-secret-file="/etc/jwt-secret.hex "#jwt authentication againts local EL
--builder-endpoint="http://127.0.0.1:18550 "#points to local mev-boost

Logging​

  • Whenever the beacon node receives a BuilderBid, it will be logged.
INFO  | ExecutionLayerManagerImpl | Received Builder Bid (Block Number = 622344, Block Hash = 0x7bfb24a2c4f54524e41af074557684e0ab17391af425ef23268640dace637954, MEV Reward (wei) = 105000000147000, Gas Limit = 29999972, Gas Used = 21000)
  • If the builder goes down while Teku is running, a warning would be logged. If the builder is still down during proposing, block production duty would fallback to the EL.
WARN  | teku-event-log | The execution builder is offline: <error-message >. Block production will fallback to the execution engine.
  • In the beginning of every epoch, the VC will send validator registrations to the BN, which will forward them to the builder network.
INFO | validator-async-0 | 2500 out of 2500 validator(s) registrations were successfully sent to the Beacon Node.
  • In case of error during registration, the error will be logged. Keep in mind, some registrations may still have succeeded, because they are sent in batches.
INFO | validator-async-3 | 500 out of 2500 validator(s) registrations were successfully sent to the Beacon Node.
ERROR | validator-async-3 | Validator   *** Failed to send validator registrations to Beacon Node
java.util.concurrent.CompletionException:java.util.concurrent.CompletionException...............

source: https://hackmd.io/@StefanBratanov/BkMlo1RO9