# Security & Optimization Protocols

This document details the safety mechanisms, entry guardrails, and optimization strategies implemented in the Uniswap Auto CLP & Hedger system.

## 1. CLP Manager: Entry & Position Safety

The `clp_manager.py` module is responsible for opening and managing Concentrated Liquidity Positions (CLP). It implements strict checks to ensure positions are only opened under favorable conditions.

### A. Oracle Guard Rail (Anti-Manipulation)
**Goal:** Prevent entering a pool that is actively being manipulated (Flash Loans) or has momentarily de-pegged.
*   **Mechanism:** Before any calculation, the bot fetches the **Real-Time Mid Price** directly from the Hyperliquid API.
*   **Logic:**
    *   `Pool Price` is calculated from the on-chain `sqrtPriceX96`.
    *   `Oracle Price` is fetched from Hyperliquid (`https://api.hyperliquid.xyz/info`).
    *   **Rule:** If `abs(Pool - Oracle) / Oracle > 0.25%`, the bot **ABORTS** the entry.
*   **Benefit:** Protects against entering at a "fake" price which would lead to instant arbitrage loss (LVR).

### B. Stale Tick Protection (Volatility Guard)
**Goal:** Prevent entering a position if the price moves significantly during the transaction setup phase (e.g., while swapping tokens).
*   **Mechanism:**
    1.  The bot calculates the target tick range at $T_0$.
    2.  It performs necessary token swaps (e.g., USDC -> WETH) which takes time ($T_1$).
    3.  **Critical Check:** Just before minting ($T_2$), it re-fetches the current pool tick.
*   **Rule:** If `abs(Tick_T0 - Tick_T2) > 13 ticks` (approx 0.13%), the bot **ABORTS** the mint transaction.
*   **Benefit:** Ensures the range is centered on the *actual* execution price, not an outdated one.

### C. Post-Mint Accuracy
**Goal:** Ensure the "Entry Price" recorded for the Hedger is 100% accurate.
*   **Mechanism:** Immediately after the Mint transaction is confirmed on-chain, the bot fetches the pool state *one more time*.
*   **Benefit:** Captures the exact price impact of the user's own liquidity insertion, preventing discrepancies in the Hedger's PnL calculations.

### D. Safe Entry Zones (AUTO Mode)
**Goal:** Only enter when mean reversion is statistically likely.
*   **Mechanism:**
    *   **Bollinger Bands (BB):** Price must be inside the 12h BB.
    *   **Moving Average (MA):** The MA88 must also be inside the 12h BB.
*   **Benefit:** Avoids opening positions during breakout trends or extreme volatility expansion.

### E. Manual Override (Force Mode)
**Goal:** Allow operator intervention for testing or recovery.
*   **Command:** `python clp_manager.py --force <width>` (e.g., 0.95).
*   **Behavior:** Bypasses Oracle, BB, and MA checks for the **first** position only. Automatically disables itself after one successful mint.

---

## 2. CLP Hedger: Risk Management

The `clp_hedger.py` module manages the Delta-Neutral hedge on Hyperliquid.

### A. Emergency Edge Closure (Stop-Loss)
**Goal:** Prevent indefinite hedging losses if the price breaks out of the LP range violently.
*   **Trigger:** If `Price >= Range Upper Bound`.
*   **Action:** Immediately **CLOSE** the short hedge position.
*   **Benefit:** Stops the strategy from "selling low and buying high" (hedging) when the LP position is already out of range and effectively essentially 100% stablecoin (impermanent loss realized).

### B. Hysteresis Reset
**Goal:** Prevent "whipsaw" losses (opening/closing repeatedly) if the price hovers exactly at the edge.
*   **Logic:** Once an Emergency Closure triggers, the hedge does **not** re-open immediately if the price dips slightly back in.
*   **Reset Condition:** Price must drop back to a "Safe Zone" (e.g., 75% of the range width or a specific buffer below the edge).
*   **Benefit:** Filters out noise at the range boundaries.

### C. Asymmetric Compensation (EAC)
**Goal:** Reduce the "Buy High/Sell Low" churn near the edges of the range.
*   **Mechanism:** The target hedge delta is adjusted (reduced) as the price approaches the boundaries.
*   **Logic:** `Target Hedge = Pool Delta * (1 - Proximity_Factor)`.
*   **Benefit:** Softens the impact of entering/exiting the range, preserving capital.

### D. Fishing Orders (Maker Rebates)
**Goal:** Reduce execution costs.
*   **Mechanism:** Instead of market dumping (Taker fee ~0.035%), the bot places Limit Orders (Maker) slightly away from the spread.
*   **Logic:** If the price moves favorably, the order fills, earning a rebate (or paying 0 fee). If not filled within `TIMEOUT`, it falls back to a Taker order if the delta drift is critical.

---

## 3. Future Improvements (Roadmap)

### A. WebSocket Integration
*   **Current:** Polling REST API every 30-300s (or 1s for guard rails).
*   **Upgrade:** Implement a persistent WebSocket connection to Hyperliquid and the EVM RPC.
*   **Benefit:** Sub-100ms reaction times to volatility events.

### B. Multi-Chain Arbitrage Check
*   **Current:** Checks Hyperliquid vs Pool.
*   **Upgrade:** Check Binance/Coinbase prices.
*   **Benefit:** Detects on-chain lag before it happens (CEX leads DEX).

### C. Dynamic Fee Optimization
*   **Current:** Fixed `POOL_FEE`.
*   **Upgrade:** Automatically switch between 0.05% and 0.01% pools based on volatility and volume metrics.

### D. Smart Rebalance (Inventory Management)
*   **Current:** Swaps surplus tokens using 1inch/Universal Router.
*   **Upgrade:** Use CowSwap or CoW intents for MEV-protected rebalancing of large inventory imbalances.