mev-boost

mev-boost

A service that allows Ethereum Consensus Layer (CL) clients to outsource block construction to third party block builders in addition to execution clients. See ethresearch post for the high level architecture and docs/specification.md for the specification and implementation details.

v0.2 request flow:

sequenceDiagram
    participant consensus
    participant mev_boost
    participant relays
    Title: Block Proposal
    Note over consensus: sign fee recipient announcement
    consensus->>mev_boost: builder_setFeeRecipient
    mev_boost->>relays: builder_setFeeRecipient
    Note over consensus: wait for allocated slot
    consensus->>mev_boost: builder_getHeader
    mev_boost->>relays: builder_getHeader
    relays-->>mev_boost: builder_getHeader response
    Note over mev_boost: verify response matches expected
    Note over mev_boost: select best payload
    mev_boost-->>consensus: builder_getHeader response
    Note over consensus: sign the block
    consensus->>mev_boost: builder_getPayload
    Note over mev_boost: identify payload source
    mev_boost->>relays: builder_getPayload
    Note over relays: validate signature
    relays-->>mev_boost: builder_getPayload response
    Note over mev_boost: verify response matches expected
    mev_boost-->>consensus: builder_getPayload response

Table of Contents

• Implementation Plan
• Build
• Test
• Lint

Implementation Plan

A summary of consensus client changes can be found here.

Version 0.1 (current, milestone 1, running on Kiln testnet)

simple sidecar logic with minimal consensus client changes, simple networking, no authentication, and manual safety mechanism

Specification: https://github.com/flashbots/mev-boost/blob/main/docs/specification.md

Version 1.0 (next, milestone 2, the merge)

security, authentication & reputation

• mev-boost requests authenticated feeRecipient message from consensus client and gossips over p2p at regular interval
• add module for verifying previous relay payload validity and accuracy with hard or statistical blacklist (may require modifications to execution client)
• add module for subscribing to 3rd party relay monitoring service

required client modifications

• in event of middleware crash, consensus client must be able to bypass the middleware to reach a local or remote execution client
• consensus client must implement Proposal Promises

Version 2.0 - privacy (optional)

add p2p comms mechanisms to prevent validator deanonymization

• mev-boost gossips signed block + initial payload header over p2p

required client modifications

• consensus client must implement New Gossipsub Topics

Version 3.0 - configurations (optional)

add optional configurations to provide alternative guarantees

• consider adding direct relay_forkchoiceUpdatedV1 call to relay for syncing state
• consider returning full payload directly to validator as optimization
• consider adding merkle proof of payment to shift verification requirements to the relay

Build

make build

and then run it with:

./mev-boost

Test

make test

Lint

We use revive as a linter and staticcheck. You need to install them with

go install github.com/mgechev/revive@latest
go install honnef.co/go/tools/cmd/staticcheck@master

Lint and check the project:

make lint

Running with mergemock

We are currently testing using a forked version of mergemock, see https://github.com/flashbots/mergemock

Make sure you've setup and built mergemock first, refer to its README but here's a quick setup guide:

git clone https://github.com/flashbots/mergemock.git
cd mergemock
go build . mergemock
wget https://gist.githubusercontent.com/lightclient/799c727e826483a2804fc5013d0d3e3d/raw/2e8824fa8d9d9b040f351b86b75c66868fb9b115/genesis.json

Then you can run an integration test with mergemock, spawning both a mergemock execution engine and a mergemock consensus client as well as mev-boost:

cd mev-boost
make run-mergemock-integration

The path to the mergemock repo is assumed to be ../mergemock, you can override like so:

make MERGEMOCK_DIR=/PATH-TO-MERGEMOCK-REPO run-mergemock-integration

to run mergemock in dev mode:

make MERGEMOCK_BIN='go run .' run-mergemock-integration