# GEMINI Project Context: Uniswap Auto CLP & Hedger

**Last Updated:** January 6, 2026
**Project:** Uniswap V3 Automated Concentrated Liquidity (CLP) & Delta-Neutral Hedger
**Operating System:** Windows (win32)

## 1. Project Overview
This project is an automated high-frequency trading system designed to:
1.  **Provide Concentrated Liquidity (CLP):** Automatically manages positions on Uniswap V3 and its forks (Aerodrome, PancakeSwap) to capture trading fees.
2.  **Hedge Delta Exposure:** Simultaneously executes delta-neutral hedges on Hyperliquid (Perp DEX) to neutralize the price risk of the underlying assets (Impermanent Loss protection).

The system operates as a **Delta-Zero Yield Farmer**, effectively capturing LP fees with reduced market exposure.

## 2. System Architecture
The system consists of two main independent Python processes that coordinate via a shared JSON state file.

```mermaid
graph TD
    A[clp_manager.py] -- Reads/Writes --> C{status.json}
    B[clp_hedger.py] -- Reads --> C
    A -- On-Chain Tx --> D[EVM Chain (Base/Arb)]
    B -- API Calls --> E[Hyperliquid Perp]
    F[telegram_monitor.py] -- Reads --> C
    F -- Alerts --> G[Telegram]
```

### Components
*   **`clp_manager.py` (The Strategist):**
    *   **Role:** Active Liquidity Provision on EVM chains.
    *   **Actions:** Mints new positions, monitors ranges, auto-closes out-of-range positions, collects fees, and handles auto-wrapping/swapping.
    *   **State:** Updates `{TARGET_DEX}_status.json` with entry price, token amounts, and range details.

*   **`clp_hedger.py` (The Guardian):**
    *   **Role:** Delta Neutralization on Hyperliquid.
    *   **Actions:** Calculates the LP's real-time delta. Executes short/long trades to maintain `Net Delta ≈ 0`.
    *   **Features:**
        *   **Dynamic Thresholds:** Adjusts rebalance sensitivity based on market volatility (StdDev).
        *   **Fishing Orders:** Places passive maker orders to capture spread and rebates.
        *   **Edge Protection:** Reduces hedging logic near range edges to prevent "buying high/selling low".

*   **`clp_config.py`:** Centralized configuration. Uses `TARGET_DEX` env var to switch between profiles (e.g., `UNISWAP_V3`, `AERODROME_BASE_CL`).

## 3. Key Files & Directories

| File/Directory | Description |
| :--- | :--- |
| **`clp_manager.py`** | Main entry point for the LP Manager. |
| **`clp_hedger.py`** | Main entry point for the Delta Hedger. |
| **`clp_config.py`** | Configuration profiles and strategy settings. |
| **`requirements.txt`** | Python dependencies (`web3`, `hyperliquid-python-sdk`, `dotenv`). |
| **`doc/`** | Extensive documentation (`CHANGELOG.md`, `UNISWAP_MANAGER_WORKFLOW.md`). |
| **`florida/`** | A secondary deployment or research directory containing specific strategy configurations. |
| **`tools/`** | Utility scripts (e.g., `git_agent.py`, `universal_swapper.py`). |
| **`logs/`** | Runtime logs. |
| **`*_status.json`** | The shared state file (IPC). Specific name depends on `TARGET_DEX`. |

## 4. Setup & Usage

### Prerequisites
*   Python 3.10+
*   Hyperliquid Account & API Key (in `.env`)
*   EVM Wallet Private Key (in `.env`)
*   RPC URLs (in `.env`)

### Installation
```bash
pip install -r requirements.txt
```

### Configuration
1.  Create a `.env` file (see `.env.example` in `tools/`).
2.  Edit `clp_config.py` or set `TARGET_DEX` environment variable to choose a profile (e.g., `AERODROME_WETH-USDC_008`).

### Running the System
You typically run the Manager and Hedger in separate terminals:

**Terminal 1 (Manager):**
```bash
python clp_manager.py
```

**Terminal 2 (Hedger):**
```bash
python clp_hedger.py
```

## 5. Recent Developments (Jan 2026)
*   **Low Volatility Optimization:** Increased base rebalance thresholds (from 5% to 8%) to reduce churn in sideways markets.
*   **Fishing Orders:** Implemented passive limit orders to profit from rebalancing.
*   **Shadow Logging:** The system now logs "Shadow" trades to simulate maker order performance vs taker execution.
*   **Dynamic Edge Proximity:** Safety buffers now scale with position size.

## 6. Active Context
*   **Current Profile:** The root directory contains `AERODROME_WETH-USDC_008_status.json`, indicating an active or recent session on **Aerodrome (Base Chain)**.
*   **Workflows:** Refer to `doc/UNISWAP_MANAGER_WORKFLOW.md` for detailed state machine logic of the Manager.