# fuzzland/sui-mev architecture

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

- Interactive diagram: https://gitdiagram.com/fuzzland/sui-mev
- Repository: https://github.com/fuzzland/sui-mev

## Overview

##### Main Components
- Arbitrage Bot Service: Represented by the bin/arb package. This is the core module that collects, analyzes, and executes arbitrage strategies. The source files indicate components such as collectors, various protocol-specific modules (under src/defi), configuration management, strategy modules, execution logic, and pool identification.
- Relay Service: The bin/relay package. This service acts as an intermediary: it accepts mempool transactions pushed by validators and forwards them to the bot.
- Dex Indexer: A separate crate (crates/dex-indexer) that aggregates data about DEX pool data from various supported protocols. It also preprocesses and stores pool data and protocol-specific information that the arbitrage bot uses.
- Shared Libraries: Crates like arb-common, logger, object-pool, shio, simulator, utils, and version provide common functionality for logging, performance, connections, simulations, and utility functions.
- External Sui Network Components:
- Sui Nodes: External nodes of the Sui blockchain are key to obtaining mempool information, blockchain state, and submitting transactions.

##### Relationships and Interactions
- The Arbitrage Bot (bin/arb) communicates internally with its strategy, executor, and collector modules to gather market data, analyze arbitrage opportunities, and send transaction requests.
- Simultaneously, it relies on the DEX Indexer to fetch and update pool states across multiple protocols, ensuring it always has up-to-date data.
- The Relay Service (bin/relay) connects externally with validators or Sui nodes. Validators push mempool transactions to this component, which then routes the transaction information to the Arbitrage Bot for further action.
- Underpinning all these modules, shared libraries (e.g., arb-common, logger, utils) provide cross-cutting concerns such as logging, configuration, and utility functions.
- Most importantly—the connection to Sui Nodes should be explicitly represented. This connection is shown as a bidirectional (or directional) link between the external Sui network (nodes and validators) and both the Relay Service and the Arbitrage Bot. This indicates that the system is actively monitoring the network (i.e., mempool data or contract state) via Sui nodes for opportunities and eventually sending transactions back to the network.

##### Architectural Patterns & Design Principles
- Modular and Layered Architecture: Separation into distinct binaries and shared crates supports modularity.
- Data Flow Driven by External Events: The mempool transaction flow starts at Sui nodes (via validators) then to the Relay Service and finally integrated within the arbitrage bot’s decision engine.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Sui Network
    subgraph "Sui Network"
        SN_NODES["Sui Nodes"]:::external
        SN_VALID["Validators"]:::external
    end

    %% Relay Service
    RS["Relay Service"]:::service

    %% Arbitrage Bot Service with internal modules
    subgraph "Arbitrage Bot (bin/arb)"
        AB_CORE["Arbitrage Core"]:::internal
        AB_COLL["Collector Module"]:::internal
        AB_CONFIG["Config Management"]:::internal
        AB_EXEC["Executor Module"]:::internal
        AB_STRAT["Strategy Modules"]:::internal
        AB_DEFI["Defi Protocol Modules"]:::internal
    end

    %% DEX Indexer
    DI["DEX Indexer"]:::service

    %% Shared Libraries
    subgraph "Shared Libraries"
        CL_ARB["Arb Common"]:::library
        CL_LOG["Logger"]:::library
        CL_OBJ["Object Pool"]:::library
        CL_SHIO["Shio"]:::library
        CL_SIM["Simulator"]:::library
        CL_UTIL["Utilities"]:::library
        CL_VER["Version"]:::library
    end

    %% External Connections
    SN_VALID -->|"push_mempool"| RS
    SN_NODES -->|"query_submit"| AB_CORE

    %% Relay to Arbitrage Bot Connection
    RS -->|"relay_transaction"| AB_CORE

    %% Arbitrage Bot to DEX Indexer
    AB_CORE -->|"fetch_pool_data"| DI

    %% Internal communications within Arbitrage Bot
    AB_CORE -->|"call"| AB_COLL
    AB_CORE -->|"call"| AB_CONFIG
    AB_CORE -->|"call"| AB_EXEC
    AB_CORE -->|"call"| AB_STRAT
    AB_CORE -->|"call"| AB_DEFI

    %% Shared Library usage by Arbitrage Bot
    AB_CORE -->|"use_lib"| CL_ARB
    AB_CORE -->|"use_lib"| CL_LOG
    AB_CORE -->|"use_lib"| CL_OBJ
    AB_CORE -->|"use_lib"| CL_SHIO
    AB_CORE -->|"use_lib"| CL_SIM
    AB_CORE -->|"use_lib"| CL_UTIL
    AB_CORE -->|"use_lib"| CL_VER

    %% Shared library usage by DEX Indexer (representative)
    DI -->|"use_lib"| CL_ARB

    %% Click Events
    click AB_CORE "https://github.com/fuzzland/sui-mev/blob/master/bin/arb/src/arb.rs"
    click AB_COLL "https://github.com/fuzzland/sui-mev/blob/master/bin/arb/src/collector.rs"
    click AB_CONFIG "https://github.com/fuzzland/sui-mev/blob/master/bin/arb/src/config.rs"
    click AB_EXEC "https://github.com/fuzzland/sui-mev/blob/master/bin/arb/src/executor.rs"
    click AB_STRAT "https://github.com/fuzzland/sui-mev/tree/master/bin/arb/src/strategy/"
    click AB_DEFI "https://github.com/fuzzland/sui-mev/tree/master/bin/arb/src/defi/"
    click RS "https://github.com/fuzzland/sui-mev/blob/master/bin/relay/src/main.rs"
    click DI "https://github.com/fuzzland/sui-mev/tree/master/crates/dex-indexer/src/"
    click CL_ARB "https://github.com/fuzzland/sui-mev/blob/master/crates/arb-common/src/lib.rs"
    click CL_LOG "https://github.com/fuzzland/sui-mev/blob/master/crates/logger/src/lib.rs"
    click CL_OBJ "https://github.com/fuzzland/sui-mev/blob/master/crates/object-pool/src/lib.rs"
    click CL_SHIO "https://github.com/fuzzland/sui-mev/blob/master/crates/shio/src/lib.rs"
    click CL_SIM "https://github.com/fuzzland/sui-mev/blob/master/crates/simulator/src/lib.rs"
    click CL_UTIL "https://github.com/fuzzland/sui-mev/blob/master/crates/utils/src/lib.rs"
    click CL_VER "https://github.com/fuzzland/sui-mev/blob/master/crates/version/src/lib.rs"

    %% Styles
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef service fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef internal fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef library fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
