Teku

MEV Boost\Builder API (Teku)

This document is deprecated. Please refer to https://docs.teku.consensys.net/en/latest/HowTo/Builder-Network/ for the official documentation.

#Useful Links

https://github.com/flashbots/mev-boost/wiki https://ethereum.github.io/builder-specs/

#Table of Contents

• Setup
• Logging

#Setup

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
• Specify Builder endpoint
• Validator Registration

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

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

The following builder relay endpoints are live and can be used for testing.

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
• Validator registration overrides
• Fee Recipient
• Batch sending of validator registrations

#Enabling Validator Registration

There are couple of ways to enable validator registration.

• CLI Arguments
• Proposer Configuration

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