# zacholme7/basebuster architecture

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

- Interactive diagram: https://gitdiagram.com/zacholme7/basebuster
- Repository: https://github.com/zacholme7/basebuster

## Overview

##### Main Components
a. Smart Contracts Layer:
- Located in the contracts directory.
- Contains Solidity contracts (using Foundry, indicated by foundry.toml and various solidity libraries like openzeppelin-contracts, aave-v3-core, etc.).
- This layer is responsible for on-chain operations, potentially including execution of arbitrage, flash loans, or settlement operations.

b. Core Arbiter Engine (Rust Application):
- The primary entry is in src/main.rs.
- Modules responsible for arbitrage signal processing, estimation, and simulation (e.g., estimator.rs, simulator.rs, quoter.rs, swap.rs, gas_station.rs, tx_sender.rs).
- Calculation modules (src/calculation folder) specific to different protocols (uniswap.rs, balancer.rs, curve.rs, etc.) suggesting that the bot calculates potential profit opportunities using protocol-specific logic.
- The state_db component (src/state_db) for storing and retrieving blockchain or market state information.

c. Data and Utility Layers:
- Graph, event logging (src/graph.rs, src/events.rs, src/tracing.rs) modules for monitoring and debugging.
- Caching (src/cache.rs) and a database layer (src/history_db.rs) to maintain historical data that may inform arbitrage decisions.
- ABI decoding/access from the src/abi folder and bytecode handling from src/bytecode.rs to interact with deployed contracts on the blockchain.

d. Testing and Simulation:
- Extensive tests and helper modules (under src/tests and src/tests/helpers) to validate the bot’s strategies and ensure reliability.

##### Configure the Relationships and Interactions
a. Off-chain Components (Rust Code):
- The main application orchestrates data fetching (from blockchains, state_db, etc.), processes market data through calculation modules, and simulates arbitrage strategies.
- It then communicates with the smart contracts deployed on-chain (located in contracts/) via transaction sending and possibly event listening (hinted by modules like tx_sender.rs and stream.rs).

b. On-chain Components (Smart Contracts):
- The contracts layer should be represented with its relationships to the Rust engine; pointing out that when an arbitrage opportunity is detected, the off-chain system can invoke on-chain contracts to execute a trade.

c. Inter-module Communications:
- How the Rust modules link with each other: for instance, how the gas_station module is linked to tx_sender to compute the required gas fees before executing a transaction.
- Directional flows between the calculation modules (protocol-specific calculations) feeding into the quoter module, which in turn informs the decision to execute a swap.

##### Important Architectural Patterns and Technologies
- Modular Design: The Rust source is separated into clear modules (calculation, state_db, simulation, etc.), implementing separation of concerns.
- Testing First: The extensive test suite ensures reliability before any execution in a live blockchain environment.
- Hybrid Architecture: Combining off-chain computation (Rust backend) with on-chain smart contracts.
- Build/Deployment Automation: Presence of CI/CD workflows in the contracts directory (see .github/workflows) indicates automated testing/deployment practices for on-chain components.
- Use of popular blockchain libraries: openzeppelin-contracts, forge-std, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-Chain Layer
    subgraph "On-Chain Layer"
        SC["Smart Contracts Layer (Solidity)"]:::onChain
        FC["Foundry & Libraries"]:::onChain
    end

    %% Off-Chain Engine Layer
    subgraph "Off-Chain Engine Layer"
        %% Core Arbiter Engine
        subgraph "Core Arbiter Engine (Rust)"
            M1["Main.rs"]:::engine
            M2["Estimator"]:::engine
            M3["Simulator"]:::engine
            M4["Quoter"]:::engine
            M5["Swap"]:::engine
            M6["Tx_Sender"]:::engine
            M7["Gas_Station"]:::engine
        end

        %% Calculation Modules
        subgraph "Calculation Modules (Rust)"
            C1["Uniswap"]:::calc
            C2["Balancer"]:::calc
            C3["Curve"]:::calc
        end

        %% State Database
        subgraph "State Database (Rust)"
            SD1["Blockstate/v2/v3"]:::db
        end

        %% Data and Utility Layers
        subgraph "Data & Utility Layers"
            DU1["ABI Processing"]:::utility
            DU2["Bytecode Handling"]:::utility
            DU3["Caching"]:::utility
            DU4["Historical Data"]:::utility
            DU5["Graph"]:::utility
            DU6["Events"]:::utility
            DU7["Tracing"]:::utility
        end

        %% Testing and Simulation
        subgraph "Testing & Simulation"
            T1["Tests & Helpers"]:::test
        end
    end

    %% Interactions & Data Flow
    M1 --> M2
    M2 -->|"calls"| C1
    M2 -->|"calls"| C2
    M2 -->|"calls"| C3
    C1 --> M4
    C2 --> M4
    C3 --> M4
    M4 --> M5
    M5 --> M6
    M7 --> M6
    M6 -->|"executes"| SC

    DU1 --> M2
    DU2 --> M2
    DU3 --> DU4
    DU5 --> SD1
    DU6 --> SD1
    DU7 --> SD1
    SD1 --> M2
    T1 --> M3

    %% Click Events
    click SC "https://github.com/zacholme7/basebuster/tree/main/contracts/"
    click M1 "https://github.com/zacholme7/basebuster/blob/main/src/main.rs"
    click M2 "https://github.com/zacholme7/basebuster/blob/main/src/estimator.rs"
    click M3 "https://github.com/zacholme7/basebuster/blob/main/src/simulator.rs"
    click M4 "https://github.com/zacholme7/basebuster/blob/main/src/quoter.rs"
    click M5 "https://github.com/zacholme7/basebuster/blob/main/src/swap.rs"
    click M6 "https://github.com/zacholme7/basebuster/blob/main/src/tx_sender.rs"
    click M7 "https://github.com/zacholme7/basebuster/blob/main/src/gas_station.rs"
    click C1 "https://github.com/zacholme7/basebuster/tree/main/src/calculation/"
    click C2 "https://github.com/zacholme7/basebuster/tree/main/src/calculation/"
    click C3 "https://github.com/zacholme7/basebuster/tree/main/src/calculation/"
    click SD1 "https://github.com/zacholme7/basebuster/tree/main/src/state_db/"
    click DU1 "https://github.com/zacholme7/basebuster/tree/main/src/abi/"
    click DU2 "https://github.com/zacholme7/basebuster/blob/main/src/bytecode.rs"
    click DU3 "https://github.com/zacholme7/basebuster/blob/main/src/cache.rs"
    click DU4 "https://github.com/zacholme7/basebuster/blob/main/src/history_db.rs"
    click DU5 "https://github.com/zacholme7/basebuster/blob/main/src/graph.rs"
    click DU6 "https://github.com/zacholme7/basebuster/blob/main/src/events.rs"
    click DU7 "https://github.com/zacholme7/basebuster/blob/main/src/tracing.rs"
    click T1 "https://github.com/zacholme7/basebuster/tree/main/src/tests/"

    %% Styles
    classDef onChain fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef engine fill:#C8E6C9,stroke:#000,stroke-width:2px;
    classDef calc fill:#FFF59D,stroke:#000,stroke-width:2px;
    classDef db fill:#B3E5FC,stroke:#000,stroke-width:2px;
    classDef utility fill:#D7CCC8,stroke:#000,stroke-width:2px;
    classDef test fill:#E1BEE7,stroke:#000,stroke-width:2px;
```
