# coltonc3/mev-bots architecture

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

- Interactive diagram: https://gitdiagram.com/coltonc3/mev-bots
- Repository: https://github.com/coltonc3/mev-bots

## Overview

##### Main Components
- Bot Orchestrator: The entry point is the main.py module, which likely coordinates the activities of the bot.
- Mempool Monitor: Represented by mempool.py, which likely listens to pending transactions or blockchain events.
- Arbitrage Calculation Engine: Modules like calculate.py and swaps.py indicate the logic for analyzing and calculating arbitrage opportunities.
- State Updater: update_reserves.py and query_contract_info.py are used to fetch or update on-chain data (pool reserves, contract states, etc.).
- Transaction Creator: create_tx.py and route.py are in charge of crafting and sending the transactions.
- Messaging/Utility: messages.py might be handling logging, notifications, or other communication-related functionalities.
- Configuration & External Contracts: contracts.json stores contract addresses and parameters required for interacting with the DEXes.
- Dependencies: The requirements.txt outlines external libraries that the project depends on (likely including blockchain interaction, networking, and maybe cryptography frameworks).

##### Relationships and Data Flow
- The bot starts with main.py as the central controller.
- mempool.py feeds live transaction data into main.py or directly into the arbitrage logic.
- When new opportunities or conditions are detected, calculate.py (and swaps.py) perform the heavy lifting of identifying profitable opportunities.
- For current contract states or DEX pool reserves, update_reserves.py and query_contract_info.py gather real-time data from the blockchain, referring to the contracts in contracts.json.
- Once an opportunity is confirmed, create_tx.py builds the transaction bundle or order, and route.py is used to send/sign the bundle as per the Skip protocol integration.
- messages.py may be used across these modules for effective logging or inter-module communication.

##### Architectural Patterns and Design Principles
- Modular Design: The separation of concerns is clear—the code is organized into distinct modules handling specific tasks such as monitoring, calculation, transaction creation, and state update.
- Pipeline Flow: Data flows from blockchain monitoring (mempool), through analytical processing (calculation and swaps), to transaction creation and execution.
- External Integration: The bot integrates with external blockchain services and APIs (for DEX pools and the Skip protocol) to perform its functions.
- Configurability: External JSON configuration (contracts.json) allows for easy updates as contract addresses or parameters change.

##### Technologies and Frameworks
- Python is the primary language.
- Likely web3 or similar libraries for blockchain interactions.
- The Skip protocol is a core component of the external execution layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        MEM["mempool.py"]:::input
    end

    %% Processing Layer
    subgraph "Processing Layer"
        MAIN["main.py"]:::orchestrator
        CALC["calculate.py"]:::processing
        SWAPS["swaps.py"]:::processing
        UPDATE["update_reserves.py"]:::processing
        QUERY["query_contract_info.py"]:::processing
    end

    %% Output Layer
    subgraph "Output Layer"
        CREATE["create_tx.py"]:::output
        ROUTE["route.py"]:::output
    end

    %% Utilities & Config
    subgraph "Utilities & Config"
        MSG["messages.py"]:::utility
        CONTRACTS["contracts.json"]:::config
        DEPS["requirements.txt"]:::dependencies
    end

    %% External Services
    subgraph "External Services"
        SKIP["Skip Protocol"]:::external
        JUNO["JunoSwap"]:::external
        LOOP["Loop DEX"]:::external
    end

    %% Connections: Input to Processing
    MEM -->|"blockchain_data"| MAIN

    %% Processing Flow from Orchestrator to Calculation & State Updaters
    MAIN -->|"trigger_calculation"| CALC
    MAIN -->|"trigger_calculation"| SWAPS
    MAIN -->|"fetch_chain_data"| UPDATE
    MAIN -->|"fetch_chain_data"| QUERY

    %% External DEX Data Flow to Processing Components
    JUNO ---|"price_feed"| CALC
    JUNO ---|"price_feed"| SWAPS
    LOOP ---|"price_feed"| CALC
    LOOP ---|"price_feed"| SWAPS

    %% Processing to Output Flow
    CALC -->|"arbitrage_opportunity"| CREATE
    SWAPS -->|"arbitrage_opportunity"| CREATE
    UPDATE -->|"chain_state"| CREATE
    QUERY -->|"chain_state"| CREATE

    %% Output to External Execution
    CREATE -->|"builds_transaction"| ROUTE
    ROUTE -->|"executes_tx"| SKIP

    %% Configuration Feeding Data to State Updaters
    CONTRACTS -->|"config_data"| UPDATE
    CONTRACTS -->|"config_data"| QUERY

    %% Messaging used across modules (dotted arrows for logging/notifications)
    MAIN ---|".logs to"| MSG
    CALC ---|".logs to"| MSG
    SWAPS ---|".logs to"| MSG
    UPDATE ---|".logs to"| MSG
    QUERY ---|".logs to"| MSG
    CREATE ---|".logs to"| MSG
    ROUTE ---|".logs to"| MSG

    %% Click Events
    click MAIN "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/main.py"
    click MEM "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/mempool.py"
    click CALC "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/calculate.py"
    click SWAPS "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/swaps.py"
    click UPDATE "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/update_reserves.py"
    click QUERY "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/query_contract_info.py"
    click CREATE "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/create_tx.py"
    click ROUTE "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/route.py"
    click MSG "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/messages.py"
    click CONTRACTS "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/contracts.json"
    click DEPS "https://github.com/coltonc3/mev-bots/blob/main/juno-arb/requirements.txt"

    %% Class Definitions for Colors
    classDef input fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef orchestrator fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef processing fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
    classDef output fill:#F9E79F,stroke:#D68910,stroke-width:2px;
    classDef utility fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef dependencies fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#AF601A,stroke-width:2px;
```
