# 50shadesofgwei/funding-rate-arbitrage architecture

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

- Interactive diagram: https://gitdiagram.com/50shadesofgwei/funding-rate-arbitrage
- Repository: https://github.com/50shadesofgwei/funding-rate-arbitrage

## Overview

##### Project Type & Purpose
- This is a specialized financial/arbitrage bot designed for delta-neutral arbitrage between various perpetual markets.
- It integrates different API caller modules, backtesting capabilities, matching engines, position monitors, and trade execution controllers.
- The README explains that the Main class instantiates several core components (MasterCaller, MatchingEngine, MasterPositionMonitor, MasterPositionController, TradeLogger) with an event-driven communication pattern.

##### Major Components
- APICaller Module:
- Subcomponents for each exchange (Binance, ByBit, GMX, HMX, OKX, Perennial, Synthetix).
- A “MasterCaller” that aggregates these submodules to provide unified access to funding rate and price data.
- Backtesting Module:
- Includes separate backtest utilities for different exchanges (e.g., Backtesting/Binance, Backtesting/Synthetix, MasterBacktester with historical JSON data).
- Functions to simulate trades and assess strategy performance.
- MatchingEngine Module:
- Responsible for computing trade opportunities.
- Contains profitability checks and uses market information (including funding velocity) gathered from GlobalUtils/MarketDirectories.
- PositionMonitor Module:
- Monitors active positions across exchanges.
- Tracks status and logs trade data (with submodules per exchange).
- TxExecution Module:
- Contains trade execution controllers per exchange.
- Handles instruction flow for opening, monitoring, and closing positions.
- GlobalUtils:
- Provides common resources (like ABIs, event emitters/listeners, logger, helper utilities).
- Main Module:
- Serves as the project’s entry point that ties together the Master components.
- Instantiates and starts the bot's lifecycle and integrates all modules.
- Additional Components:
- Assets (for static images that might be used in documentation or UI aspects later).
- Contributors, configuration files, and setup scripts (setup.py, requirements.txt, example.env) for deployment/configuration.

##### Relationships & Interactions
- Data flow starts at the Main module, which instantiates the core components:
→ Main class creates instances of MasterCaller (APICaller aggregator), MatchingEngine, PositionMonitor, and TxExecution controllers.
- The APICaller module interacts with external APIs to gather real-time funding rates and market data and sends this data (or emits events) to the MatchingEngine.
- The MatchingEngine processes this data, checking for profitable arbitrage opportunities, then emits events to both the PositionMonitor and TxExecution modules.
- PositionMonitor listens for updates on open positions and uses GlobalUtils for logging and storing trade data.
- TxExecution receives trade signals and, based on configuration (market orders on exchanges like Binance and Synthetix), executes trades. It is closely aligned with APICaller and PositionMonitor to ensure consistency.
- Backtesting is a parallel module that leverages historical JSON data (under Backtesting folder) to simulate the behavior of the MatchingEngine and trade execution process. It can be seen as an environment that mirrors or feeds data to many of the same components.
- GlobalUtils acts as the “glue” that provides shared resources (event broadcasting, common logging, ABIs, etc.) across modules.

##### Key Architectural Patterns & Principles
- Modularity: Each exchange-specific logic (within APICaller, PositionMonitor, and TxExecution) is neatly separated, allowing for plug-and-play or independent updates.
- Event-driven Communication: Cross-module communication uses events and listeners (for instance, trade signals, status updates) ensuring decoupling.
- Separation of Concerns: API calling, trade decision-making (MatchingEngine), position monitoring and execution are split clearly.
- Extensibility: The design (with token and exchange targeting arrays) makes it easy to adjust or incorporate new tokens/exchanges.
- Reusability: Global utilities (e.g., logger, common utility functions, market directories) are provided centrally to be used by multiple modules.

##### Elements
- “Main” as the central node.
- “APICaller” with child nodes for each exchange.
- “MatchingEngine”
- “PositionMonitor”
- “TxExecution”
- “Backtesting”
- “GlobalUtils” (as a shared dependency)
- Another for decision-making components (MatchingEngine).
- Another for execution components (PositionMonitor, TxExecution).
- A distinct highlight for the Backtesting module to showcase its simulation role.

##### Additional Advice
- Don’t hesitate to include notes on common shared components (e.g., GlobalUtils) that are used by many parts of the application.
- Given that the project emphasizes configuration and extensibility (as seen in token/exchange arrays in MasterUtils.py), include annotations to remind viewers that many components are configurable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Orchestrator
    subgraph "Core Orchestrator"
        Main["Main (Entry Point)"]:::main
    end

    %% Modules
    subgraph "Modules"
        direction TB
        APICaller["APICaller"]:::api
        MatchingEngine["MatchingEngine"]:::matching
        PositionMonitor["PositionMonitor"]:::monitor
        TxExecution["TxExecution"]:::execution
        Backtesting["Backtesting"]:::backtesting
        GlobalUtils["GlobalUtils"]:::utils
    end

    %% External Exchanges
    subgraph "External Exchanges"
        direction TB
        Binance["Binance"]:::exchange
        ByBit["ByBit"]:::exchange
        GMX["GMX"]:::exchange
        HMX["HMX"]:::exchange
        OKX["OKX"]:::exchange
        Perennial["Perennial"]:::exchange
        Synthetix["Synthetix"]:::exchange
    end

    %% Documentation & Assets
    subgraph "Documentation & Assets"
        direction TB
        Assets["Assets"]:::doc
        Contributors["Contributors"]:::doc
    end

    %% Relationships
    Main --> APICaller
    Main --> MatchingEngine
    Main --> PositionMonitor
    Main --> TxExecution
    Main --> Backtesting
    Main --> GlobalUtils

    APICaller -->|"funding_data"| MatchingEngine
    MatchingEngine -->|"trade_signals"| PositionMonitor
    MatchingEngine -->|"trade_signals"| TxExecution

    APICaller -->|"api_calls"| Binance
    APICaller -->|"api_calls"| ByBit
    APICaller -->|"api_calls"| GMX
    APICaller -->|"api_calls"| HMX
    APICaller -->|"api_calls"| OKX
    APICaller -->|"api_calls"| Perennial
    APICaller -->|"api_calls"| Synthetix

    MatchingEngine -.->|"utilizes"| GlobalUtils
    PositionMonitor -.->|"logs_via"| GlobalUtils
    TxExecution -.->|"executes_using"| GlobalUtils

    %% Click Events
    click Main "https://github.com/50shadesofgwei/funding-rate-arbitrage/blob/main/Main/main_class.py"
    click APICaller "https://github.com/50shadesofgwei/funding-rate-arbitrage/blob/main/APICaller/master/MasterCaller.py"
    click Binance "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/Binance/"
    click ByBit "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/ByBit/"
    click GMX "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/GMX/"
    click HMX "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/HMX/"
    click OKX "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/Okx/"
    click Perennial "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/Perennial/"
    click Synthetix "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/APICaller/Synthetix/"
    click Backtesting "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/Backtesting/"
    click MatchingEngine "https://github.com/50shadesofgwei/funding-rate-arbitrage/blob/main/MatchingEngine/MatchingEngine.py"
    click PositionMonitor "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/PositionMonitor/"
    click TxExecution "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/TxExecution/"
    click GlobalUtils "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/GlobalUtils/"
    click Assets "https://github.com/50shadesofgwei/funding-rate-arbitrage/tree/main/Assets/"
    click Contributors "https://github.com/50shadesofgwei/funding-rate-arbitrage/blob/main/Contributors/README.md"

    %% Styles
    classDef main fill:#FFD700,stroke:#DAA520,stroke-width:2px
    classDef api fill:#ADD8E6,stroke:#0000FF,stroke-width:2px
    classDef matching fill:#FFFF99,stroke:#FFD700,stroke-width:2px
    classDef monitor fill:#FFA07A,stroke:#FF4500,stroke-width:2px
    classDef execution fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px
    classDef backtesting fill:#D8BFD8,stroke:#DA70D6,stroke-width:2px
    classDef utils fill:#90EE90,stroke:#32CD32,stroke-width:2px
    classDef exchange fill:#E6E6FA,stroke:#8A2BE2,stroke-width:2px
    classDef doc fill:#F0E68C,stroke:#BDB76B,stroke-width:2px
```
