Home

Awesome

MEV-Boost Relay

Goreport status Test status Docker hub

MEV-Boost Relay for Ethereum proposer/builder separation (PBS).

Currently live at:

Alternatives (not audited or endorsed): blocknative/dreamboat, manifold/mev-freelay

See also

Components

The relay consists of three main components, which are designed to run and scale independently, and to be as simple as possible:

  1. API: Services that provide APIs for (a) proposers, (b) block builders, (c) data.
  2. Website: Serving the website requests (information is pulled from Redis and database).
  3. Housekeeper: Updates known validators, proposer duties, and more in the background. Only a single instance of this should run.

Dependencies

  1. Redis
  2. PostgreSQL
  3. one or more beacon nodes
  4. block submission validation nodes
  5. [optional] Memcached

Beacon nodes / CL clients

Relays are strongly advised to run multiple beacon nodes!

Security

A security assessment for the relay was conducted on 2022-08-22 by lotusbumi. Additional information can be found in the Security section of this repository.

If you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net.

Background

MEV is a centralizing force on Ethereum. Unattended, the competition for MEV opportunities leads to consensus security instability and permissioned communication infrastructure between traders and block producers. This erodes neutrality, transparency, decentralization, and permissionlessness.

Flashbots is a research and development organization working on mitigating the negative externalities of MEV. Flashbots started as a builder specializing in MEV extraction in proof-of-work Ethereum to democratize access to MEV and make the most profitable blocks available to all miners. >90% of miners are outsourcing some of their block construction to Flashbots today.

The mev-boost relay is a trusted mediator between block producers and block builders. It enables all Ethereum proof-of-stake validators to offer their blockspace to not just Flashbots but other builders as well. This opens up the market to more builders and creates competition between them, leading to more revenue and choice for validators, and better censorship-resistance for Ethereum.

In the future, proposer/builder separation will be enshrined in the Ethereum protocol itself to further harden its trust model.

Read more in Why run mev-boost? and in the Frequently Asked Questions.

Usage

Running Postgres, Redis and Memcached

# Start PostgreSQL & Redis individually:
docker run -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres
docker run -d -p 6379:6379 redis

# [optional] Start Memcached
docker run -d -p 11211:11211 memcached

# Or with docker-compose:
docker-compose up

Note: docker-compose also runs an Adminer (a web frontend for Postgres) on http://localhost:8093/?username=postgres (db: postgres, username: postgres, password: postgres)

Now start the services:

# The housekeeper sets up the validators, and does various housekeeping
go run . housekeeper --network sepolia --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable

# Run APIs for sepolia (using a dummy BLS secret key)
go run . api --network sepolia --secret-key 0x607a11b45a7219cc61a3d9c5fd08c7eebd602a6a19a977f8d3771d5711a550f2 --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable

# Run Website for sepolia
go run . website --network sepolia --db postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable

# Query status
curl localhost:9062/eth/v1/builder/status

# Send test validator registrations
curl -X POST -H'Content-Encoding: gzip' localhost:9062/eth/v1/builder/validators --data-binary @testdata/valreg2.json.gz

# Delete previous registrations
redis-cli DEL boost-relay/sepolia:validators-registration boost-relay/sepolia:validators-registration-timestamp

Environment variables

General

Feature Flags

Development Environment Variables

Redis Tuning

Website

Updating the website

This builds a local copy of the template and saves it in website-index.html

The website is using:

Technical Notes

See ARCHITECTURE.md and Running MEV-Boost-Relay at scale for more technical details!

Storing execution payloads and redundant data availability

By default, the execution payloads for all block submission are stored in Redis and also in the Postgres database, to provide redundant data availability for getPayload responses. But the database table is not pruned automatically, because it takes a lot of resources to rebuild the indexes (and a better option is using TRUNCATE).

Storing all the payloads in the database can lead to terabytes of data in this particular table. Now it's also possible to use memcached as a second data availability layer. Using memcached is optional and disabled by default.

To enable memcached, you just need to supply the memcached URIs either via environment variable (i.e. MEMCACHED_URIS=localhost:11211) or through command line flag (--memcached-uris).

You can disable storing the execution payloads in the database with this environment variable: DISABLE_PAYLOAD_DATABASE_STORAGE=1.

Builder submission validation nodes

You can use the builder project to validate block builder submissions: https://github.com/flashbots/builder

Here's an example systemd config:

<details> <summary><code>/etc/systemd/system/geth.service</code></summary> 
[Unit]
Description=mev-boost
Wants=network-online.target
After=network-online.target

[Service]
User=ubuntu
Group=ubuntu
Environment=HOME=/home/ubuntu
Type=simple
KillMode=mixed
KillSignal=SIGINT
TimeoutStopSec=90
Restart=on-failure
RestartSec=10s
ExecStart=/home/ubuntu/builder/build/bin/geth \
    --syncmode=snap \
    --datadir /var/lib/goethereum \
    --metrics \
    --metrics.expensive \
    --http \
    --http.api="engine,eth,web3,net,debug,flashbots" \
    --http.corsdomain "*" \
    --http.addr "0.0.0.0" \
    --http.port 8545 \
    --http.vhosts '*' \
    --ws \
    --ws.api="engine,eth,web3,net,debug" \
    --ws.addr 0.0.0.0 \
    --ws.port 8546 \
    --ws.api engine,eth,net,web3 \
    --ws.origins '*' \
    --graphql \
    --graphql.corsdomain '*' \
    --graphql.vhosts '*' \
    --authrpc.addr="0.0.0.0" \
    --authrpc.jwtsecret=/var/lib/goethereum/jwtsecret \
    --authrpc.vhosts '*' \
    --cache=8192

[Install]
WantedBy=multi-user.target
</details>

Sending blocks to the validation node:

Beacon node setup

Lighthouse

Here's a quick guide for setting up Lighthouse.

Here's an example Lighthouse systemd config:

<details> <summary><code>/etc/systemd/system/lighthouse.service</code></summary> 
[Unit]
Description=Lighthouse
After=network.target
Wants=network.target

[Service]
User=ubuntu
Group=ubuntu
Type=simple
Restart=always
RestartSec=5
TimeoutStopSec=180
ExecStart=/home/ubuntu/.cargo/bin/lighthouse bn \
        --network mainnet \
        --checkpoint-sync-url=https://mainnet-checkpoint-sync.attestant.io \
        --eth1 \
        --http \
        --http-address "0.0.0.0" \
        --http-port 3500 \
        --datadir=/mnt/data/lighthouse \
        --http-allow-sync-stalled \
        --execution-endpoints=http://localhost:8551 \
        --jwt-secrets=/var/lib/goethereum/jwtsecret \
        --disable-deposit-contract-sync \
        --always-prepare-payload \
        --prepare-payload-lookahead 12000

[Install]
WantedBy=default.target
</details>

Prysm

Here's an example Prysm systemd config:

<details> <summary><code>/etc/systemd/system/prysm.service</code></summary> 
[Unit]
Description=Prysm
After=network.target
Wants=network.target

[Service]
User=ubuntu
Group=ubuntu
Type=simple
Restart=always
RestartSec=5
TimeoutStopSec=180
ExecStart=/home/ubuntu/prysm/bazel-bin/cmd/beacon-chain/beacon-chain_/beacon-chain \
        --accept-terms-of-use \
        --enable-debug-rpc-endpoints \
        --checkpoint-sync-url=https://mainnet-checkpoint-sync.attestant.io \
        --genesis-beacon-api-url=https://mainnet-checkpoint-sync.attestant.io \
        --grpc-gateway-host "0.0.0.0" \
        --datadir=/mnt/data/prysm \
        --p2p-max-peers 100 \
        --execution-endpoint=http://localhost:8551 \
        --jwt-secret=/var/lib/goethereum/jwtsecret \
        --min-sync-peers=1 \
        --grpc-max-msg-size 104857600 \
        --prepare-all-payloads \
        --disable-reorg-late-blocks

[Install]
WantedBy=default.target
</details>

Bid Cancellations

Block builders can opt into cancellations by submitting blocks to /relay/v1/builder/blocks?cancellations=1. This may incur a performance penalty (i.e. validation of submissions taking significantly longer). See also https://github.com/flashbots/mev-boost-relay/issues/348

Maintainers

Contributing

Flashbots is a research and development collective working on mitigating the negative externalities of decentralized economies. We contribute with the larger free software community to illuminate the dark forest.

You are welcome here <3.

Security

If you find a security vulnerability on this project or any other initiative related to Flashbots, please let us know sending an email to security@flashbots.net.

Audits

License

The code in this project is free software under the AGPL License version 3 or later.

Made with ☀️ by the ⚡🤖 collective.