# flashbots/rbuilder architecture

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

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

## Overview

##### Main Components

a. Core Components:
- Block Building Engine
- Order Processing System
- Simulation Engine
- MEV-Boost Integration
- Telemetry System

b. External Interfaces:
- Reth Node Connection
- Consensus Layer (CL) Node
- MEV-Boost Relays
- Bundle/Transaction Sources

##### Component Relationships

Layer 1 - External Interfaces:
**[CL Node] -- [MEV-Boost Relays] -- [Bundle Sources] -- [Reth Node]**

Layer 2 - Core Processing:
**[Order Input System] -- [Block Building Engine] -- [Block Output System]**

Layer 3 - Supporting Systems:
**[Simulation Engine] -- [Telemetry & Metrics] -- [State Management]**

##### Specific Component Details

a. Order Input System:
- Transaction Pool Fetcher
- Bundle Processing
- Order Replacement Manager
- RPC Server Interface

b. Block Building Engine:
- Parallel Builder
- Order Conflict Resolution
- Block Building Helper
- Simulation Cache

c. Block Output System:
- Bid Value Source
- Relay Submission
- Block Sealing
- Wallet Balance Management

##### Data Flow Indicators

- Incoming transactions/bundles from sources
- Block building pipeline flow
- Relay submission path
- State updates and queries
- Metrics and telemetry data flow

##### Additional Elements

- Backtesting components
- Configuration management
- Error handling systems
- Monitoring endpoints

##### Technical Details to Note

Annotations for:
- Rust-specific implementations
- Performance-critical paths
- Integration points with Reth
- MEV-Boost protocol interfaces

##### Implementation Notes

- The parallel processing nature of the builder
- Multiple algorithm support
- Bundle merging capabilities
- Nonce management system
- Integration with external systems

##### Optimization Points

Areas where:
- Parallel processing occurs
- Caching is implemented
- State prefetching happens
- Performance optimizations exist

Remember to include version information and note that this is a production-grade system running at Flashbots, with both stable releases and development branches available.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Layer"]
        CL[Consensus Layer Node]:::external
        RELAY[MEV-Boost Relays]:::external
        BUNDLE[Bundle Sources]:::external
        RETH[Reth Node]:::external
    end

    subgraph Core["Core Processing Layer"]
        subgraph OIS["Order Input System"]
            TXPOOL["Transaction Pool Fetcher"]:::core
            BUNDLE_PROC["Bundle Processing"]:::core
            ORM["Order Replacement Manager"]:::core
            RPC["RPC Server Interface"]:::core
        end

        subgraph BBE["Block Building Engine"]
            PB["Parallel Builder"]:::core
            OCR["Order Conflict Resolution"]:::core
            BBH["Block Building Helper"]:::core
            SC["Simulation Cache"]:::core
        end

        subgraph BOS["Block Output System"]
            BVS["Bid Value Source"]:::core
            RS["Relay Submission"]:::core
            BS["Block Sealing"]:::core
            WBM["Wallet Balance Management"]:::core
        end
    end

    subgraph Support["Supporting Systems Layer"]
        subgraph SE["Simulation Engine"]
            SW["Simulation Worker"]:::support
            SJ["Simulation Job"]:::support
        end

        subgraph TM["Telemetry & Metrics"]
            M["Metrics"]:::telemetry
            DL["Dynamic Logs"]:::telemetry
            TS["Telemetry Servers"]:::telemetry
        end

        subgraph SM["State Management"]
            TI["Trie Implementation"]:::state
            CSM["Change Set Management"]:::state
        end
    end

    %% External Layer Connections
    CL --> RELAY
    RELAY --> BUNDLE
    BUNDLE --> RETH

    %% Core Layer Connections
    RETH --> TXPOOL
    BUNDLE --> BUNDLE_PROC
    TXPOOL --> ORM
    BUNDLE_PROC --> ORM
    ORM --> PB
    RPC --> PB
    
    PB --> OCR
    OCR --> BBH
    BBH --> SC
    
    SC --> BVS
    BVS --> RS
    RS --> BS
    BS --> WBM

    %% Support Layer Connections
    BBH --> SW
    SW --> SJ
    PB --> M
    RS --> DL
    BS --> TS
    OCR --> CSM
    BBH --> TI

    %% Click Events
    click TXPOOL "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/order_input/txpool_fetcher.rs"
    click ORM "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/order_input/order_replacement_manager.rs"
    click RPC "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/order_input/rpc_server.rs"
    click PB "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/building/builders/parallel_builder/mod.rs"
    click BBH "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/building/builders/block_building_helper.rs"
    click SW "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/simulation/sim_worker.rs"
    click SJ "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/simulation/simulation_job.rs"
    click M "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/telemetry/metrics.rs"
    click DL "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/telemetry/dynamic_logs.rs"
    click TS "https://github.com/flashbots/rbuilder/tree/develop/crates/rbuilder/src/telemetry/servers/"
    click BVS "https://github.com/flashbots/rbuilder/tree/develop/crates/rbuilder/src/live_builder/block_output/bid_value_source/"
    click RS "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/block_output/relay_submit.rs"
    click BS "https://github.com/flashbots/rbuilder/blob/develop/crates/rbuilder/src/live_builder/block_output/block_sealing_bidder_factory.rs"
    click TI "https://github.com/flashbots/rbuilder/tree/develop/crates/eth-sparse-mpt/src/sparse_mpt/"
    click CSM "https://github.com/flashbots/rbuilder/blob/develop/crates/eth-sparse-mpt/src/reth_sparse_trie/change_set.rs"

    %% Styling
    classDef external fill:#3498db,stroke:#2980b9,color:white
    classDef core fill:#2ecc71,stroke:#27ae60,color:white
    classDef support fill:#f1c40f,stroke:#f39c12,color:black
    classDef telemetry fill:#e67e22,stroke:#d35400,color:white
    classDef state fill:#e74c3c,stroke:#c0392b,color:white
```
