# 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.