How 50shadesofgwei/funding-rate-arbitrage works
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.