feat: add florida module for unified hedging and monitoring
This commit is contained in:
137
florida/GEMINI.md
Normal file
137
florida/GEMINI.md
Normal file
@ -0,0 +1,137 @@
|
||||
# Uniswap Auto CLP & Delta-Neutral Hedger
|
||||
|
||||
## Project Overview
|
||||
This project is an automated high-frequency trading system designed to provide **Concentrated Liquidity (CLP)** on Uniswap V3 (and forks) while simultaneously **hedging delta exposure** on Hyperliquid.
|
||||
|
||||
The goal is to capture trading fees from the Liquidity Pool (LP) while neutralizing the price risk of the underlying assets (Impermanent Loss protection). The system operates as a **Delta-Zero Scalper**, effectively farming yields with reduced market exposure.
|
||||
|
||||
## Architecture
|
||||
The system consists of three independent Python processes that coordinate via shared JSON state files.
|
||||
|
||||
### 1. Position Manager (`clp_manager.py`)
|
||||
* **Role:** Active Liquidity Provision.
|
||||
* **Functionality:**
|
||||
* Connects to EVM chains (Arbitrum, BNB Chain, Base) via Web3.
|
||||
* Monitors `{TARGET_DEX}_status.json` and on-chain pool state.
|
||||
* **Auto-Entry:** Detects when no position exists, calculates optimal tick ranges based on `RANGE_WIDTH_PCT`, and mints a new NFT position.
|
||||
* **Auto-Wrap:** Automatically wraps native tokens (ETH -> WETH) if balances are insufficient.
|
||||
* **Auto-Exit:** Detects out-of-range positions, removes liquidity, and collects fees (`CLOSE_POSITION_ENABLED`).
|
||||
* **State Sync:** Updates `{TARGET_DEX}_status.json` with entry price, amounts, and token IDs for the Hedger.
|
||||
|
||||
### 2. Delta Hedger (`clp_hedger.py`)
|
||||
* **Role:** Delta Neutralization (Risk Management).
|
||||
* **Functionality:**
|
||||
* Connects to Hyperliquid (Perp DEX).
|
||||
* Reads `{TARGET_DEX}_status.json` to understand the current LP position's delta profile.
|
||||
* **Dynamic Hedging:** Calculates the precise `Gamma` (rate of change of delta) and rebalances the short position to keep Net Delta close to zero.
|
||||
* **Scalping:** Uses "Fishing Orders" (Maker orders) and volatility-adjusted thresholds to profit from hedging rebalances rather than just paying taker fees.
|
||||
* **Safety:** Includes emergency closures, edge protection logic (to avoid hedging at max loss points), and disconnect protection.
|
||||
|
||||
### 3. Monitoring (`telegram_monitor.py`)
|
||||
* **Role:** Alerting.
|
||||
* **Functionality:**
|
||||
* Watches `{TARGET_DEX}_status.json` for state transitions (OPEN -> CLOSED).
|
||||
* Sends real-time notifications to Telegram with PnL summaries, duration, and fees collected.
|
||||
|
||||
## Key Files & Directories
|
||||
|
||||
| File/Dir | Description |
|
||||
| :--- | :--- |
|
||||
| `clp_manager.py` | Main logic for Uniswap V3 interaction (Mint/Burn/Collect). |
|
||||
| `clp_hedger.py` | Main logic for Hyperliquid hedging (Open/Close/Rebalance). |
|
||||
| `clp_config.py` | Configuration profiles (Chain IDs, Contract Addresses) and Strategy settings. |
|
||||
| `telegram_monitor.py` | Telegram bot for notifications. |
|
||||
| `{TARGET_DEX}_status.json` | **Critical:** Shared state file acting as the database between Manager and Hedger. |
|
||||
| `.env` | Stores secrets (Private Keys, RPCs). **Do not commit.** |
|
||||
| `tools/` | Utility scripts, including the Git Agent for auto-backups. |
|
||||
| `logs/` | Detailed logs for all processes. |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables (`.env`)
|
||||
Required variables for operation:
|
||||
```env
|
||||
# Blockchain
|
||||
MAINNET_RPC_URL=... # Arbitrum
|
||||
BNB_RPC_URL=... # BNB Chain
|
||||
BASE_RPC_URL=... # Base
|
||||
MAIN_WALLET_PRIVATE_KEY=...
|
||||
MAIN_WALLET_ADDRESS=...
|
||||
|
||||
# Hyperliquid
|
||||
HEDGER_PRIVATE_KEY=... # Usually same as Main Wallet or specialized sub-account
|
||||
|
||||
# Telegram
|
||||
TELEGRAM_BOT_TOKEN=...
|
||||
TELEGRAM_CHAT_ID=...
|
||||
TELEGRAM_MONITOR_ENABLED=True
|
||||
```
|
||||
|
||||
### Strategy Config (`clp_config.py`)
|
||||
Key parameters controlling the bot's behavior:
|
||||
* `TARGET_DEX`: Selects the active chain/profile (e.g., "UNISWAP_V3", "PANCAKESWAP_BNB").
|
||||
* `RANGE_WIDTH_PCT`: Width of the LP position (e.g., `0.05` for +/- 5%).
|
||||
* `TARGET_INVESTMENT_AMOUNT`: Notional size of the position in USD.
|
||||
* `SLIPPAGE_TOLERANCE`: Max slippage for minting/swapping.
|
||||
|
||||
## Usage
|
||||
|
||||
The system is designed to run continuously. It is recommended to use a process manager like `pm2` or `systemd`, or simply run in separate terminal tabs.
|
||||
|
||||
1. **Start the Manager:**
|
||||
```bash
|
||||
python clp_manager.py
|
||||
```
|
||||
* *Action:* Will check for existing positions. If none, it prepares to open one based on config.
|
||||
|
||||
2. **Start the Hedger:**
|
||||
```bash
|
||||
python clp_hedger.py
|
||||
```
|
||||
* *Action:* Will read the position created by the Manager and open a corresponding short on Hyperliquid.
|
||||
|
||||
3. **Start Monitoring (Optional):**
|
||||
```bash
|
||||
python telegram_monitor.py
|
||||
```
|
||||
|
||||
## Development & Git Agent
|
||||
|
||||
This project uses a custom **Git Agent** (`tools/git_agent.py`) for automated version control and backups.
|
||||
|
||||
* **Auto-Backup:** Runs hourly (if configured) to create backup branches (e.g., `backup-2025-01-01-12`).
|
||||
* **Manual Commit:**
|
||||
```bash
|
||||
python tools/git_agent.py --backup
|
||||
```
|
||||
* **Status:**
|
||||
```bash
|
||||
python tools/git_agent.py --status
|
||||
```
|
||||
* **Restoration:**
|
||||
To restore a file from a backup branch:
|
||||
```bash
|
||||
git checkout backup-BRANCH-NAME -- path/to/file.py
|
||||
```
|
||||
|
||||
## Logic Details
|
||||
|
||||
### Hedging Mathematics
|
||||
The hedger calculates the **Pool Delta** derived from the V3 liquidity math:
|
||||
$$ \Delta_{LP} = L \times (\frac{1}{\sqrt{P}} - \frac{1}{\sqrt{P_{upper}}}) $$
|
||||
(For Token0/Token1 where we hedge Token0).
|
||||
|
||||
It then maintains a Short Position ($S$) such that:
|
||||
$$ S \approx \Delta_{LP} $$
|
||||
|
||||
### Rebalancing
|
||||
Rebalancing is triggered when:
|
||||
1. **Delta Drift:** $|S - \Delta_{LP}| > Threshold$
|
||||
2. **Volatility:** Thresholds expand during high volatility to reduce churn (fees).
|
||||
3. **Edge Proximity:** Hedging logic changes when price approaches the range boundaries to prevent "buying high/selling low" behavior at the edges.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
* **Logs:** Check `logs/clp_manager.log` and `logs/clp_hedger.log` first.
|
||||
* **Stuck Position:** If a position is closed on-chain but `{TARGET_DEX}_status.json` says `OPEN`, manually edit the JSON status to `CLOSED` or delete the entry (with caution).
|
||||
* **RPC Errors:** Ensure your RPC URLs in `.env` are active and have sufficient rate limits.
|
||||
Reference in New Issue
Block a user