# jito-labs/mev-bot architecture

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

- Interactive diagram: https://gitdiagram.com/jito-labs/mev-bot
- Repository: https://github.com/jito-labs/mev-bot

## Overview

##### Project Type and Purpose
- This is a specialized, single‐purpose MEV (miner/executor value) arb bot built in Node.js/TypeScript for the Solana ecosystem.
- It monitors the Solana mempool to spot large pending trades on DEXs (Raydium, Orca, etc.), calculates circular arbitrage routes, and executes backrun transactions via Jito bundles and flashloans.

##### File Structure
- Top level: configuration files (.env, Dockerfile, tsconfig.json), an `analyze/` notebook, a pool‐update script, and the `src/` directory.
- src/clients/: connectors for Solana RPC, Jito block engine, and Geyser plugin.
- src/markets/: DEX‐specific adapters (Raydium, Orca, etc.), each with its own initialization and pool metadata.
- Core modules:
- bot.ts – process orchestration (entry point)
- mempool.ts – mempool subscription & incoming‐tx filtering
- lookup‐table‐provider.ts – lookup table caching for bundle size reduction
- calculate‐arb.ts / simulation.ts – route calculation and profitability simulation
- pre‐simulation-filter.ts / post‐simulation-filter.ts – filter out uninteresting or unprofitable opportunities
- send-bundle.ts – bundle construction and submission (flashloan, swaps, repayment)
- worker-pool.ts – multi‐threaded pool for parallel arb calculation
- Utilities/config: logger.ts, constants.ts, config.ts, utils.ts, types.ts.

##### Extract Architecture Insights from the README
- Three‐phase pipeline:
1. **Detect** – subscribe to mempool via Geyser, resolve lookup tables
2. **Compute** – simulate potential arbitrage routes across DEX adapters, pick the best route
3. **Execute** – assemble flashloan + multi‐hop swap bundle (via Jupiter), submit to Solana through Jito block engine, then log results
- External dependencies: Solana JSON‐RPC, Jito Geyser plugin, Block Engine, Jupiter SDK, Solend flashloan program, CSV file for metrics.

##### Main Components & Their Interactions
a. **Mempool Monitor**
- Inputs: Solana RPC + Geyser plugin
- Output: stream of pending transactions matching DEX vault addresses
b. **Lookup Table Provider**
- Caches on‐chain lookup tables encountered in pending txns
- Feeds the transaction resolver in the simulation
c. **Pre‐Simulation Filter**
- Discards transactions that do not touch target pool vaults or are too small
d. **Worker Pool & Simulation Engine**
- Spawns N worker threads, each with a set of Amm calculator objects (from Jupiter SDK) loaded with Geyser‐pushed pool data
- Simulates 2‐hop & 3‐hop routes for profitability in discrete steps
e. **Route Selection**
- Picks the most profitable route (highest expected return)
f. **Bundle Constructor & Executor**
- Constructs a Solend flashloan + Jupiter multi‐swap + flashloan repayment + validator tip transaction
- Uses cached lookup tables to reduce transaction size
- Submits the bundle via Jito Block Engine RPC
g. **Post‐Execution Logging**
- Waits ~30s, fetches on‐chain result, writes trade details to CSV
h. **Auxiliary**
- update-pool-lists.sh – refreshes the list of pool account addresses
- /trades.ipynb – Jupyter notebook for offline results analysis

##### Architectural Patterns and Principles
- **Pipeline Pattern**: Data flows through detection → filtering → simulation → execution → logging.
- **Worker Pool**: Parallelizes heavy compute across threads for route simulation.
- **Adapter Pattern**: One adapter per DEX under src/markets.
- **Caching Layer**: lookup‐table‐provider reduces RPC overhead and bundle size.
- **Event‐Driven**: Reacts to mempool events, not timed polls.

##### Final Recommendations
- Be **granular**: Break src/markets into sub-components if needed to show each DEX adapter.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        SolRPC["Solana JSON-RPC"]:::external
        RPCClient["RPC Client"]:::external
        GeyserClient["Geyser Plugin Client"]:::external
        JupiterSDK["Jupiter SDK"]:::sdk
        Solend["Solend Flashloan Program"]:::external
        JitoBE["Jito Block Engine"]:::external
    end

    %% Internal Pipeline
    Bot["Bot Entry Point"]:::internal
    Mempool["Mempool Monitor"]:::internal
    Prefilter["Pre-Simulation Filter"]:::internal
    LookupTable["Lookup Table Provider"]:::internal
    subgraph "Worker Pool & Simulation Engine"
        WorkerPool["Worker Pool"]:::internal
        SimulationEngine["Simulation Engine"]:::internal
        AMMWorker["AMM Calculation Worker"]:::internal
    end
    Postfilter["Post-Simulation Filter"]:::internal
    ArbCalc["Arbitrage Calculator / Route Selector"]:::internal
    subgraph "Bundle Construction & Execution"
        BuildBundle["Bundle Constructor"]:::internal
        SendBundle["Bundle Executor"]:::internal
    end
    Logger["Post-Execution Logger"]:::internal
    CSV["Trade CSV Log"]:::data

    %% External Integrations
    SolRPC -->|"getAccountInfo RPC"| Mempool
    RPCClient -->|calls| Mempool
    GeyserClient -->|"programSubscribe events"| Mempool

    Mempool -->|"stream txns"| LookupTable
    LookupTable -->|"enriched txns"| Prefilter
    Prefilter -->|"filtered txns"| WorkerPool

    WorkerPool -->|"spawn threads"| SimulationEngine
    SimulationEngine -->|"use AMM calculators"| AMMWorker
    AMMWorker -->|"simulateTransaction"| JupiterSDK

    SimulationEngine -->|results| Postfilter
    Postfilter -->|profitable txns| ArbCalc
    ArbCalc -->|best route| BuildBundle

    BuildBundle -->|bundle data| SendBundle
    SendBundle -->|flashloan + swaps| Solend
    SendBundle -->|submit bundle| JitoBE
    SendBundle -->|finalize tx| SolRPC
    SendBundle -->|tx signature| Logger
    Logger -->|"append"| CSV

    %% Side Components
    subgraph "Adapters & Market Metadata"
        DEXIndex["Markets Index"]:::internal
        Raydium["Raydium Adapter"]:::internal
        RaydiumCLMM["Raydium CLMM Adapter"]:::internal
        Orca["Orca Adapter"]:::internal
        OrcaWhirlpool["Orca Whirlpool Adapter"]:::internal
        MarketGraph["Market Graph"]:::internal
        MarketUtils["Markets Utils"]:::internal
        MarketTypes["Markets Types"]:::internal
    end

    DEXIndex --> Raydium
    DEXIndex --> RaydiumCLMM
    DEXIndex --> Orca
    DEXIndex --> OrcaWhirlpool

    %% Config & Utilities
    subgraph "Configuration & Utilities"
        Config["Config"]:::internal
        Constants["Constants"]:::internal
        Utils["Utilities"]:::internal
        LoggerUtil["Logger (util)"]:::internal
        Types["Types"]:::internal
    end

    %% Offline Analysis & Scripts
    Notebook["Offline Analysis Notebook"]:::data
    PoolScript["Pool List Update Script"]:::internal

    %% Click Events
    click Bot "https://github.com/jito-labs/mev-bot/blob/master/src/bot.ts"
    click Mempool "https://github.com/jito-labs/mev-bot/blob/master/src/mempool.ts"
    click RPCClient "https://github.com/jito-labs/mev-bot/blob/master/src/clients/rpc.ts"
    click GeyserClient "https://github.com/jito-labs/mev-bot/blob/master/src/clients/geyser.ts"
    click LookupTable "https://github.com/jito-labs/mev-bot/blob/master/src/lookup-table-provider.ts"
    click Prefilter "https://github.com/jito-labs/mev-bot/blob/master/src/pre-simulation-filter.ts"
    click Postfilter "https://github.com/jito-labs/mev-bot/blob/master/src/post-simulation-filter.ts"
    click WorkerPool "https://github.com/jito-labs/mev-bot/blob/master/src/worker-pool.ts"
    click SimulationEngine "https://github.com/jito-labs/mev-bot/blob/master/src/simulation.ts"
    click AMMWorker "https://github.com/jito-labs/mev-bot/blob/master/src/markets/amm-calc-worker.ts"
    click ArbCalc "https://github.com/jito-labs/mev-bot/blob/master/src/calculate-arb.ts"
    click BuildBundle "https://github.com/jito-labs/mev-bot/blob/master/src/build-bundle.ts"
    click SendBundle "https://github.com/jito-labs/mev-bot/blob/master/src/send-bundle.ts"
    click DEXIndex "https://github.com/jito-labs/mev-bot/blob/master/src/markets/index.ts"
    click Raydium "https://github.com/jito-labs/mev-bot/blob/master/src/markets/raydium/index.ts"
    click RaydiumCLMM "https://github.com/jito-labs/mev-bot/blob/master/src/markets/raydium-clmm/index.ts"
    click Orca "https://github.com/jito-labs/mev-bot/blob/master/src/markets/orca/index.ts"
    click OrcaWhirlpool "https://github.com/jito-labs/mev-bot/blob/master/src/markets/orca-whirlpool/index.ts"
    click MarketGraph "https://github.com/jito-labs/mev-bot/blob/master/src/markets/market-graph.ts"
    click MarketUtils "https://github.com/jito-labs/mev-bot/blob/master/src/markets/utils.ts"
    click MarketTypes "https://github.com/jito-labs/mev-bot/blob/master/src/markets/types.ts"
    click JitoBE "https://github.com/jito-labs/mev-bot/blob/master/src/clients/jito.ts"
    click Config "https://github.com/jito-labs/mev-bot/blob/master/src/config.ts"
    click Constants "https://github.com/jito-labs/mev-bot/blob/master/src/constants.ts"
    click Utils "https://github.com/jito-labs/mev-bot/blob/master/src/utils.ts"
    click LoggerUtil "https://github.com/jito-labs/mev-bot/blob/master/src/logger.ts"
    click Types "https://github.com/jito-labs/mev-bot/blob/master/src/types.ts"
    click Notebook "https://github.com/jito-labs/mev-bot/blob/master/analyze/trades.ipynb"
    click PoolScript "https://github.com/jito-labs/mev-bot/blob/master/update-pool-lists.sh"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000;
    classDef internal fill:#90EE90,stroke:#000;
    classDef sdk fill:#FFA500,stroke:#000;
    classDef data fill:#FFE4B5,stroke:#000;
```
