working version, before optimalization

florida/doc/SECURITY_AND_OPTIMIZATION.md

@@ -0,0 +1,93 @@
+# 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.