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 also:

• Builder API specification (Github)
• mev-boost Docker image
• Integration docs (mev-boost wiki)

System diagram

(source)

Request sequence

sequenceDiagram
    participant consensus
    participant mev_boost
    participant relays
    Title: Block Proposal
    Note over consensus: validator starts up
    consensus->>mev_boost: registerValidator
    mev_boost->>relays: registerValidator
    Note over consensus: wait for allocated slot
    consensus->>mev_boost: getHeader
    mev_boost->>relays: getHeader
    relays-->>mev_boost: getHeader response
    Note over mev_boost: verify response matches expected
    Note over mev_boost: select best payload
    mev_boost-->>consensus: getHeader response
    Note over consensus: sign the header
    consensus->>mev_boost: getPayload
    Note over mev_boost: identify payload source
    mev_boost->>relays: getPayload
    Note over relays: validate signature
    relays-->>mev_boost: getPayload response
    Note over mev_boost: verify response matches expected
    mev_boost-->>consensus: getPayload response

Implementation Plan

See https://github.com/flashbots/mev-boost/wiki/The-Plan-(tm)

References:

• Specification: https://github.com/flashbots/mev-boost/blob/main/docs/specification.md
• https://ethresear.ch/t/mev-boost-merge-ready-flashbots-architecture/11177/
• https://hackmd.io/@paulhauner/H1XifIQ_t

Developing

Install required utilities:

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

Build

make build

and then run it with:

./mev-boost

Lint & Test

make test
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 -b v021-upstream 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