90 lines
5.5 KiB
Markdown
90 lines
5.5 KiB
Markdown
# 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.** |
|
|
| `tests/backtest/` | **New:** Professional Backtesting & Optimization Framework. |
|
|
| `tools/` | Utility scripts, including the Git Agent for auto-backups. |
|
|
| `logs/` | Detailed logs for all processes. |
|
|
|
|
## Backtesting Framework (Jan 2026 Update)
|
|
A robust simulation engine has been implemented to validate strategies before capital commitment.
|
|
|
|
### Components
|
|
* **`tests/backtest/backtester.py`**: Event-driven engine mocking Web3/Hyperliquid interactions.
|
|
* **`tests/backtest/mocks.py`**: Stateful simulator handling balance tracking, V3 tick math, and fee accrual.
|
|
* **`tests/backtest/grid_search.py`**: Optimization runner to test parameter combinations (Range Width, Hedging Threshold).
|
|
* **`tests/backtest/analyze_results.py`**: Helper to interpret simulation CSV results.
|
|
|
|
### Progress Status (Jan 1, 2026)
|
|
* **Completed:**
|
|
* Simulation loop runs end-to-end (Mint -> Accrue Fees -> Close).
|
|
* Fixed Mock Pricing logic (handling inverted T0/T1 pairs like USDT/WBNB).
|
|
* Implemented realistic Fee Accrual based on Trade Volume + Market Share.
|
|
* Verified "In Range" detection and position lifecycle.
|
|
* **Pending / Next Steps:**
|
|
* **Hedger PnL Verification:** Simulation showed 0.0 Hedging Fees because the price volatility in the 1-day sample was too low to trigger the 10% rebalance threshold. We are lowering thresholds to 1% to force activity and verify costs.
|
|
* **NAV Calculation:** Refine "Total PnL" to include Unrealized PnL from both LP and Hedge to handle Impermanent Loss correctly.
|
|
* **Final Optimization:** Run the `grid_search.py` with the corrected Market Share (0.02%) and lower thresholds to find the profitable "Sweet Spot".
|
|
|
|
## 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. |