Flashbots

Skill based on mev-boost (flashbots/mev-boost), generated at 2026-02-24.

MEV-Boost is open-source middleware run by validators to access a competitive block-building market. It implements out-of-protocol proposer-builder separation (PBS): relays aggregate blocks from builders, and MEV-Boost selects the highest bid for the consensus client.

Core References

Features

Best Practices

Advanced

Generation Info

• Source: sources/flashbots (https://github.com/flashbots/mev-boost)
• Git SHA: bb0297401b2bab531d56012ea2581c1b3cb487cd
• Generated: 2026-02-24

test-cli

test-cli is a utility to run proposer flows against MEV-Boost + relay (generate validator data, register, getHeader, getPayload). Use it for integration testing or local debugging.

Build

From the mev-boost repo:

make build-testcli

Commands

Environment and defaults

• Validator data file: -vd-file or VALIDATOR_DATA_FILE (default ./validator_data.json).
• MEV-Boost: -mev-boost or MEV_BOOST_ENDPOINT (default http://127.0.0.1:18550).
• Beacon node: -bn or BEACON_ENDPOINT (e.g. http://localhost:5052) — required for getHeader/getPayload unless using mergemock.
• Execution node: -en (e.g. http://localhost:8545) — used for pre-Bellatrix or when using mergemock (-mm).
• Network fork version: -genesis-fork-version (e.g. mainnet 0x00000000, Sepolia 0x90000069).

Typical workflow

1. Start MEV-Boost (e.g. Hoodi + one relay):

   ./mev-boost -hoodi -relay-check -relay "URL-OF-TRUSTED-RELAY"

2. Generate validator data (optional; or supply your own validator data file):

   ./test-cli generate [-gas-limit 30000000] [-fee-recipient 0x...]

3. Register validator:

   ./test-cli register -genesis-fork-version 0x90000069 [-mev-boost http://127.0.0.1:18550]

4. Test getHeader (beacon node required unless -mm):

   ./test-cli getHeader -genesis-fork-version 0x90000069 [-mev-boost] [-bn BEACON_ENDPOINT] [-en ENGINE_ENDPOINT] [-mm]

5. Test getPayload:

   ./test-cli getPayload [-mev-boost] [-bn BEACON_ENDPOINT] [-en ENGINE_ENDPOINT] [-mm]

Use -mm for mergemock mode: use execution for block hash and fake slot; no need for a real beacon node.

<!-- Source references:

• cmd/test-cli/README.md
• sources/flashbots/cmd/test-cli/

-->

Validator and Relay Best Practices

Trust and relay selection

• Relays are trusted: Validators (and MEV-Boost) assume relays do not send blocks that could cause slashing, do not exceed the registered gas limit, and do not lie about bid values. Only connect to relays you trust.
• Use multiple relays for redundancy and competition; MEV-Boost will choose the highest bid among them.
• Relay lists are maintained by the community (e.g. Ethstaker, Lido); use such lists to discover relays and verify URLs.

Consensus and beacon configuration

• Configure your beacon node to use MEV-Boost (builder endpoint). How to do this depends on the consensus client; see the MEV-Boost site for client-specific guides.
• Ensure validator registration (fee recipient, gas limit) is what you intend; MEV-Boost forwards registration to all configured relays.

Minimum bid and fallback

• Use -min-bid if you want to avoid accepting low-value builder bids and prefer local block production when bids are below the threshold.
• If no relay returns a bid (or all are below -min-bid), MEV-Boost returns nothing and the consensus client builds a block locally.

Timing and proposer boost

• Proposer boost favors blocks proposed early in the slot (e.g. within ~4 seconds). Keep relay and getHeader/getPayload timeouts aligned with your consensus client’s deadlines so you don’t miss the window.
• If using timing games, set late_in_slot_time_ms and timeout_get_header_ms so that MEV-Boost does not request headers so late that the block cannot be proposed in time.

Security

• Run MEV-Boost in a trusted environment; it communicates with execution and consensus clients. Restrict network access so only your beacon node can reach MEV-Boost.
• For security issues or vulnerabilities, refer to the repository’s SECURITY.md and the documented audit (e.g. docs/audit-20220620.md).

<!-- Source references:

• README.md (Usage, Who can run, Security)
• docs/audit-20220620.md (Trust Assumptions)
• https://boost.flashbots.net

-->

MEV-Boost API

MEV-Boost implements the Builder API as a proxy: the consensus client talks to MEV-Boost; MEV-Boost talks to relays.

Endpoints (paths)

Request flow (block proposal)

1. registerValidator — On startup / validator load, consensus client sends signed validator registration (fee recipient, gas limit, etc.) to MEV-Boost; MEV-Boost forwards to each relay. 2. getHeader — For a given slot, parent_hash, pubkey, MEV-Boost requests headers from every relay, verifies and compares bids, returns the single best header to the consensus client. 3. getPayload (submitBlindedBlock) — Consensus client sends the signed blinded beacon block; MEV-Boost identifies which relay had that bid, requests the full payload from that relay, verifies and returns it.

Implementation notes for agents

• When simulating or testing the flow, use the same request/response shapes as the Builder Spec (JSON, specific field names).
• Relays are identified by URL; format is typically https://<pubkey>@<host>.
• Timeouts: getHeader and getPayload have configurable timeouts (defaults 950 ms and 4000 ms respectively); ensure consensus client deadlines are compatible.

<!-- Source references:

• https://github.com/flashbots/mev-boost (README.md, API section)
• https://ethereum.github.io/builder-specs
• sources/flashbots/server/params/paths.go

-->

MEV-Boost and Proposer-Builder Separation

MEV-Boost is middleware that lets validators outsource block building to a competitive builder market. It implements out-of-protocol proposer-builder separation (PBS) for PoS Ethereum.

Roles

• Validators / Consensus clients: Propose blocks; connect to MEV-Boost to receive block headers from relays.
• MEV-Boost: Sidecar for the beacon node; queries relays, aggregates bids, returns the best header to the consensus client.
• Relays: Aggregate blocks from multiple builders; expose headers and bids to MEV-Boost. One MEV-Boost instance can connect to multiple relays.
• Builders: Build full blocks (including MEV); submit blocks and bids to relays.

Flow

1. Validator registers with relays via MEV-Boost (registerValidator). 2. When a slot is assigned, consensus client requests a header from MEV-Boost (getHeader). 3. MEV-Boost requests headers from all configured relays and selects the highest bid. 4. Consensus client signs the chosen header and sends it to MEV-Boost (submitBlindedBlock / getPayload). 5. MEV-Boost forwards to the relay that provided that bid; relay returns the full payload. 6. Consensus client receives the full block and proposes it.

When to use

• Use MEV-Boost when you run a PoS Ethereum node (solo or staking provider) and want to receive MEV-boosted blocks from builders instead of building locally.
• One MEV-Boost instance can serve multiple beacon nodes; default listen address is localhost:18550.

<!-- Source references:

• https://github.com/flashbots/mev-boost (README.md)
• https://ethresear.ch/t/proposer-block-builder-separation-friendly-fee-market-designs/9725

-->

YAML Configuration

Advanced options (relay list, timing games, global timeouts) are driven by a YAML config file.

Usage

./mev-boost -config config.yaml
# Hot reload: apply config changes without restart
./mev-boost -config config.yaml -watch-config

Config is optional. Relays can be supplied only via CLI (-relay / -relays); if both config and CLI provide relays, they are merged.

Top-level keys

Relay entry structure

Each item under relays is an object with:

Example (see config.example.yaml in the repo for a full sample):

timeout_get_header_ms: 950
late_in_slot_time_ms: 2000

relays:
  - url: "https://0x...@relay1.net"
    enable_timing_games: true
    target_first_request_ms: 200
    frequency_get_header_ms: 100
  - url: "https://0x...@relay2.com"
    enable_timing_games: false

Environment

Config path can be overridden via CONFIG_FILE when the CLI reads it from the -config flag’s env source.

<!-- Source references:

• config.example.yaml
• docs/timing-games.md
• sources/flashbots/cli/flags.go (relayConfigFlag, watchConfigFlag)

-->

Relays and Run Configuration

Specifying relays

Two equivalent ways to pass relay URLs:

# Comma-separated list
./mev-boost -relays "https://relay1.example.com,https://relay2.example.com"

# Multiple -relay flags
./mev-boost -relay "https://relay1.example.com" -relay "https://relay2.example.com"

Relay URL format is typically scheme://pubkey@host. Relays can also be defined in the YAML config file (see features-config-yaml); CLI and config relays are merged.

Network selection

Example for Sepolia:

./mev-boost -sepolia -relay-check -relay "https://relay.example.com"

Minimum bid

-min-bid <eth>: If no relay returns a bid of at least this value (in ETH), MEV-Boost does not return a bid to the consensus client; the node falls back to local block production.

./mev-boost -min-bid 0.06 -relay "https://relay.example.com"

Relay health check

-relay-check: Check relay status on startup and when the status API is called. Use this to avoid starting with unreachable relays.

./mev-boost -relay-check -relay "https://relay1.example.com" -relay "https://relay2.example.com"

Request timeouts (CLI / env)

Listen address and metrics

• -addr: Listen address for the MEV-Boost server (default localhost:18550).
• -metrics: Enable Prometheus metrics server (default off).
• -metrics-addr: Metrics server address (default localhost:18551).

<!-- Source references:

• https://github.com/flashbots/mev-boost (README.md, Usage, mev-boost cli arguments)
• sources/flashbots/cli/flags.go

-->

Timing Games

Timing games optimize block proposal by when and how often MEV-Boost sends getHeader requests to relays. Instead of one request at the start of the slot, MEV-Boost can wait and send multiple requests to capture later, often higher bids before the proposal deadline.

Enabling timing games

• Timing games are configured per relay in the YAML config file.
• You must pass the config file with -config; there is no CLI-only way to enable timing games.

./mev-boost -config config.yaml
# Optional: hot-reload config changes without restart
./mev-boost -config config.yaml -watch-config

Global settings (YAML)

Per-relay settings (under relays[].url)

Behavior

1. When the consensus client calls getHeader, MEV-Boost computes budget: min(timeout_get_header_ms, late_in_slot_time_ms - ms_into_slot). 2. If timing games are enabled and target_first_request_ms is set, MEV-Boost waits until that time into the slot before the first request. 3. Then it sends getHeader requests every frequency_get_header_ms until the budget is used. 4. From each relay it keeps the most recently received bid; across relays it returns the highest value bid.

Example YAML (excerpt)

timeout_get_header_ms: 950
late_in_slot_time_ms: 2000

relays:
  - url: "https://0x...@relay.example.com"
    enable_timing_games: true
    target_first_request_ms: 200
    frequency_get_header_ms: 100

Note: Intended for advanced users; set parameters with care to avoid missed slots.

<!-- Source references:

• docs/timing-games.md
• config.example.yaml

-->