# flashbots/mev-boost architecture

> Architecture diagram of the GitHub repository flashbots/mev-boost, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flashbots/mev-boost
- Repository: https://github.com/flashbots/mev-boost

## Overview

##### Project Overview & Purpose
- MEV-Boost is middleware for Ethereum proof-of-stake (PoS) validators. It implements proposer-builder separation (PBS) by acting as a sidecar to beacon nodes, querying a network of block builders, and selecting the most profitable block submissions via multiple relays.
- Its core function is to serve as an intermediary between beacon/consensus clients and a competitive marketplace of block builders/relays, ensuring that validators receive optimized block proposals.

##### Analyzing the File Structure
- Top-Level Directories:
- cli, cmd: Command-line utilities and executable entry points (e.g., “mev-boost” and “test-cli”) indicating separate tools for production use vs. testing.
- server: Contains core logic for processing requests (like get_header, get_payload, validator registrations) and handling communication with relays.
- common & config: Contains shared utilities and configuration variables across different parts of the project.
- docs: Includes audit notes and guides indicating integration and configuration best practices.
- Additional files (Dockerfile, Makefile, scripts, etc.) indicate deployment and automation support.
- This organization shows modular design; the application splits responsibilities between network communication (server), command-line interfaces, and common shared code.

##### Identifying Main Components and Interactions
a. Core Components:
- Consensus Client / Beacon Node: Represents the external clients (validators) interfacing with MEV-Boost.
- MEV-Boost Service (Server):
- Processes API calls like registerValidator, getHeader, and submitBlindedBlock.
- Implements the Builder API as per the specification, which is reflected in the server directory’s multiple files handling header retrieval, payload processing, and mock components used in tests.
- Block Builders & Relays:
- External services that provide block proposals.
- MEV-Boost issues developer-specified “-relay” flags to connect to multiple relays.
- CLI Tools:
- “cli” and “cmd” directories offer both production (mev-boost) and testing (test-cli) interfaces to launch and interact with the service.
- Configuration & Utilities:
- Config (vars) and common logic support the service orchestration.

b. Interactions:
- Validators (via Beacon Node) initiate calls (e.g., getHeader and submitBlindedBlock) to the MEV-Boost service.
- The service forwards these requests to multiple relays (as per CLI flags/configuration), aggregates responses, and returns the optimal candidate back to the consensus client.

##### Architectural Patterns & Design Principles
- Sidecar Pattern: MEV-Boost runs parallel to the Beacon Node, ensuring decoupling between consensus operations and relay communication.
- Modular Separation: Clear segregation between CLI interfaces, core server processing, and utility/configuration packages.
- Extensibility & Multi-relay Support: Designed to allow adding multiple relays, options (like mainnet, testnets such as Sepolia, Holesky, Hoodi), and easily adjustable bidding parameters (via -min-bid).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    BN["Beacon Node/Validator Clients"]:::external
    ER["External Block Builders/Relays"]:::external

    %% CLI Interfaces
    subgraph "CLI Interfaces"
        CLI1["mev-boost CLI"]:::cli
        CLI2["test-cli"]:::cli
    end

    %% Deployment & Automation Tools
    subgraph "Deployment & Automation"
        Docker["Dockerfile & .env"]:::deploy
        Make["Makefile"]:::deploy
        Scripts["Automation Scripts"]:::deploy
    end

    %% MEV-Boost Service Components
    subgraph "MEV-Boost Service"
        API["API Endpoints: registerValidator, getHeader, submitBlindedBlock"]:::internal
        RM["Relay Manager"]:::internal
        subgraph "Utilities"
            Config["Config Module"]:::internal
            Common["Common Module"]:::internal
        end
    end

    %% Connections - External interactions
    BN -->|"registerValidator,getHeader,submitBlindedBlock"| API
    API -->|"relay-request"| RM
    RM -->|"fetchProposal"| ER
    ER -->|"bestProposal"| RM

    %% CLI Tools interactions
    CLI1 -->|"start service"| API
    CLI2 -->|"start service"| API

    %% Utilities support
    Config ---|"provides config"| API
    Common ---|"provides utils"| API

    %% Deployment tools (supporting environment)
    Docker ---|"build/deploy"| API
    Make ---|"build automation"| API
    Scripts ---|"integration tests"| API

    %% Click Events for MEV-Boost Service components
    click API "https://github.com/flashbots/mev-boost/blob/develop/server/get_header.go"
    click RM "https://github.com/flashbots/mev-boost/blob/develop/server/mock/mock_relay.go"
    click Config "https://github.com/flashbots/mev-boost/blob/develop/config/vars.go"
    click Common "https://github.com/flashbots/mev-boost/blob/develop/common/common.go"

    %% Click Events for CLI Tools
    click CLI1 "https://github.com/flashbots/mev-boost/blob/develop/cli/main.go"
    click CLI2 "https://github.com/flashbots/mev-boost/blob/develop/cmd/test-cli/main.go"

    %% Click Events for Deployment Tools
    click Docker "https://github.com/flashbots/mev-boost/tree/develop/Dockerfile"
    click Make "https://github.com/flashbots/mev-boost/tree/develop/Makefile"
    click Scripts "https://github.com/flashbots/mev-boost/blob/develop/scripts/run_mergemock_integration.sh"

    %% Additional click events for Server directory files
    %% (as additional documentation for internal server files)
    click API "https://github.com/flashbots/mev-boost/blob/develop/server/register_validator.go"
    click API "https://github.com/flashbots/mev-boost/blob/develop/server/get_payload.go"

classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px
classDef internal fill:#ccffcc,stroke:#006600,stroke-width:2px
classDef cli fill:#ccf2ff,stroke:#003366,stroke-width:2px
classDef deploy fill:#ffffcc,stroke:#999900,stroke-width:2px
```
