# 0xbc1p/sui-mev architecture

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

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

## Overview

##### Project Type & Purpose
- Rust-based backend service for MEV (Maximal Extractable Value) in the Sui blockchain ecosystem.
- Two primary binaries:
– **arb**: Main arbitrage bot (collector → indexer → strategy → executor → on-chain).
– **relay**: Optional mempool relay for validator-pushed transactions.

##### High-Level Components
A. External Systems
1. **Sui Blockchain & Validator** (mempool, RPC endpoint)
2. **Mempool Relay** (bin/relay) – optional service receiving validator pushes and forwarding to arb.
B. Core Service
1. **Arbitrage Bot** (bin/arb)
– **Collector Module**: Gathers transaction & event streams from Sui RPC or relay.
– **Indexer (dex-indexer crate)**: Maintains up-to-date pool state from multiple DeFi protocols.
– **Strategy Layer**: Implements arbitrage logic (cache, search, worker).
– **Executor Module**: Builds, signs, and submits transactions via Sui RPC.
2. **Shared Libraries**
– **arb-common**: Shared types & utilities between arb & crates.
– **logger**: Structured logging.
– **object-pool**: Resource pooling for performance.
– **utils**: Coin math, heartbeat, telegram alerts, linking.
– **version**: Build/version info.
3. **Protocol-Specific Crates**
– **dex-indexer**: Protocol parsers (Cetus, BlueMove, etc.), file DB for cursors.
– **shio**: Shio-specific mempool collector/executor.
– **simulator**: Local chain & HTTP simulator for testing strategies.

##### Data Flows & Interactions
– **Relay → Arb Collector**: (optional) P2P push of mempool txs.
– **Arb Collector → Indexer**: Raw event streams → parsed & pooled state.
– **Arb Indexer → Strategy**: Up-to-date pool state passed to strategy.worker.
– **Strategy → Executor**: If arbitrage found, create tx payload.
– **Executor → Sui RPC**: Signed txs submitted on-chain.
– **Simulator**: Hooks into Collector/Executor for offline testing.

##### Architectural Patterns & Principles
– **Modular Crate Architecture**: Each major concern lives in its own crate.
– **Layered Pipeline**: Collector → Indexer → Strategy → Executor.
– **Plugin-style Protocols**: dex-indexer/src/protocols implements a trait per DeFi protocol.
– **Separation of Concerns**: Relay separated from bot core; simulator isolated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    SUI["Sui Blockchain & Validator"]:::external
    SUI_RPC["Sui RPC"]:::external

    %% Relay Service
    RELAY["Mempool Relay (bin/relay)"]:::binary
    click RELAY "https://github.com/0xbc1p/sui-mev/blob/master/bin/relay/src/main.rs"
    SUI -->|mempool| RELAY
    RELAY -->|"forwarded mempool"| COLLECTOR

    %% Arb Binary and Modules
    subgraph "Arbitrage Bot (bin/arb)" 
        direction TB
        ARB["Arb Binary"]:::binary
        click ARB "https://github.com/0xbc1p/sui-mev/blob/master/bin/arb/src/main.rs"
        ARB --> COLLECTOR

        subgraph "Modules"
            direction TB
            COLLECTOR["Collector Module"]:::module
            click COLLECTOR "https://github.com/0xbc1p/sui-mev/blob/master/bin/arb/src/collector.rs"
            COLLECTOR -->|"raw events"| INDEXER

            subgraph "dex-indexer (crates/dex-indexer)" 
                direction TB
                INDEXER["Indexer"]:::module
                click INDEXER "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/lib.rs"
                INDEXER -->|"indexed pools"| STRATEGY

                subgraph "Protocol Plugins"
                    direction TB
                    AF["Aftermath"]:::module
                    click AF "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/aftermath.rs"
                    BM["BlueMove"]:::module
                    click BM "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/blue_move.rs"
                    CE["Cetus"]:::module
                    click CE "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/cetus.rs"
                    DB2["DeepBook V2"]:::module
                    click DB2 "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/deepbook_v2.rs"
                    FXA["FlowX AMM"]:::module
                    click FXA "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/flowx_amm.rs"
                    FXC["FlowX CLMM"]:::module
                    click FXC "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/flowx_clmm.rs"
                    IN["Interest"]:::module
                    click IN "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/interest.rs"
                    KR["Kriya AMM"]:::module
                    click KR "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/kriya_amm.rs"
                    KC["Kriya CLMM"]:::module
                    click KC "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/kriya_clmm.rs"
                    NA["Navi"]:::module
                    click NA "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/navi.rs"
                    SU["Suiswap"]:::module
                    click SU "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/suiswap.rs"
                    TU["Turbos"]:::module
                    click TU "https://github.com/0xbc1p/sui-mev/blob/master/crates/dex-indexer/src/protocols/turbos.rs"
                end
            end

            STRATEGY["Strategy Layer"]:::module
            click STRATEGY "https://github.com/0xbc1p/sui-mev/blob/master/bin/arb/src/strategy/mod.rs"
            STRATEGY -->|"tx request"| EXECUTOR

            EXECUTOR["Executor Module"]:::module
            click EXECUTOR "https://github.com/0xbc1p/sui-mev/blob/master/bin/arb/src/executor.rs"
            EXECUTOR -->|"signed TX"| SUI_RPC
        end
    end

    %% Shared Libraries
    subgraph "Shared Libraries" 
        direction TB
        ARBCOM["arb-common"]:::lib
        click ARBCOM "https://github.com/0xbc1p/sui-mev/blob/master/crates/arb-common/src/lib.rs"
        LOGGER["logger"]:::lib
        click LOGGER "https://github.com/0xbc1p/sui-mev/blob/master/crates/logger/src/lib.rs"
        OBJPOOL["object-pool"]:::lib
        click OBJPOOL "https://github.com/0xbc1p/sui-mev/blob/master/crates/object-pool/src/lib.rs"
        UTILS["utils"]:::lib
        click UTILS "https://github.com/0xbc1p/sui-mev/blob/master/crates/utils/src/lib.rs"
        VERSION["version"]:::lib
        click VERSION "https://github.com/0xbc1p/sui-mev/blob/master/crates/version/src/lib.rs"
    end

    ARBCOM -->|types & utils| COLLECTOR
    LOGGER -->|logging| ARB
    OBJPOOL -->|pooling| INDEXER
    UTILS -->|utilities| STRATEGY
    VERSION -->|build info| ARB

    %% Simulator
    SIM["Simulator (crates/simulator)"]:::binary
    click SIM "https://github.com/0xbc1p/sui-mev/blob/master/crates/simulator/src/lib.rs"
    SIM -.->|"test harness"| COLLECTOR
    SIM -.->|"test harness"| EXECUTOR

    %% Styling
    classDef external fill:#e0f7fa,stroke:#006064,color:#006064
    classDef binary fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef module fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef lib fill:#eceff1,stroke:#546e7a,color:#37474f
```
