mev-boost Relay

Flashbots mev-boost relay for proposer/builder separation in Ethereum.

Provides the builder-specs API for Ethereum proof-of-stake validators, an API for block builders to submit blocks, as well as a data API, as running for Goerli and the other test networks.

The relay consists of several components that are designed to run and scale independently and to be as simple as possible:

1. Housekeeper: update known validators, proposer duties.
2. API: for proposer, block builder, data.
3. Website: handles the root website requests (information is pulled from Redis and database).

This software is currently in alpha state, and slowly stabilizing. There may still be significant changes.

See also:

• Relay API docs
• Docker images
• Mainnet relay
• mev-boost

---

Table of contents

• Background
• Usage
• Technical notes
• Maintainers
• Contributing
• Security
• License

---

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

# Start PostgreSQL & Redis in Docker
docker-compose up

# Or start services individually:
docker run -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=postgres postgres
docker run -p 6379:6379 redis

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

The services need access to a beacon node for event subscriptions. You can also specify multiple beacon nodes by providing a comma separated list of beacon node URIs. The beacon API by default is using localhost:3500 (the Prysm default beacon-API port). You can proxy the port from a server like this:

ssh -L 3500:localhost:3500 your_server

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 localhost:9062/eth/v1/builder/validators -d @testdata/valreg2.json

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

Environment variables

• DB_TABLE_PREFIX - prefix to use for db tables (default uses dev)
• DB_DONT_APPLY_SCHEMA - disable applying DB schema on startup (useful for connecting data API to read-only replica)
• BLOCKSIM_MAX_CONCURRENT - maximum number of concurrent block-sim requests (0 for no maximum)
• FORCE_GET_HEADER_204 - force 204 as getHeader response
• DISABLE_BLOCK_PUBLISHING - disable publishing blocks to the beacon node at the end of getPayload
• DISABLE_LOWPRIO_BUILDERS - reject block submissions by low-prio builders
• DISABLE_BID_MEMORY_CACHE - disable bids to go through in-memory cache. forces to go through redis/db
• NUM_ACTIVE_VALIDATOR_PROCESSORS - proposer API - number of goroutines to listen to the active validators channel
• NUM_VALIDATOR_REG_PROCESSORS - proposer API - number of goroutines to listen to the validator registration channel
• ACTIVE_VALIDATOR_HOURS - number of hours to track active proposers in redis (default: 3)
• GETPAYLOAD_RETRY_TIMEOUT_MS - getPayload retry getting a payload if first try failed (default: 100)

Updating the website

• Edit the HTML in services/website/website.html
• Edit template values in testdata/website-htmldata.json
• Generate a static version of the website with go run scripts/website-staticgen/main.go

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

The website is using:

• PureCSS
• Font Awesome icons

---

Technical Notes

System startup sequence (housekeeper)

First the housekeeper updates Redis with the main information for the API:

1. Update known validators in Redis (source: beacon node)
2. Update proposer duties in Redis (source: beacon node (duties) + Redis (validator registrations))
3. Update validator registrations in Redis (source: database)
4. Update builder status in Redis (source: database)

Then the API can start and function.

Aftwareds, there's important ongoing, regular housekeeper tasks:

1. Update known validators and proposer duties in Redis
2. Update active validators in database (source: Redis)

Tradeoffs

• Validator registrations in are only saved to the database if feeRecipient changes. If a registration has a newer timestamp but same feeRecipient it is not saved, to avoid filling up the database with unnecessary data. (Some CL clients create a new validator registration every epoch, not just if the feeRecipient changes, as was the original idea).

---

Maintainers

• @metachris

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.

• If you have a question, feedback or a bug report for this project, please open a new Issue.
• If you would like to contribute with code, check the CONTRIBUTING file for further info about the development environment.
• We just ask you to be nice. Read our code of conduct.

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.

License

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

---

Made with ☀️ by the ⚡🤖 collective.