feat: add florida module for unified hedging and monitoring

florida/summaries/CLP_STRATEGY_LOG.md

@@ -0,0 +1,76 @@
+# CLP Strategy & Configuration Log
+
+This document tracks different configuration approaches for the Uniswap V3 CLP Hedger, their specific settings, and the observed results. Use this to refine the strategy over time.
+
+---
+
+## 1. Low Volatility / Weekend Optimization (Narrow Range)
+**Date:** 2025-12-23
+**Status:** Active
+**Objective:** Optimize for stable market conditions with a narrow trading range to maximize fee collection while maintaining tight delta neutrality.
+
+### 🔍 Context
+*   **Market Condition:** Low Volatility / Weekend / Chop
+*   **Capital:** $2,000 USDC
+*   **Range:** +/- 1% (Narrow)
+
+### ⚙️ Configuration
+**`uniswap_manager.py`**
+*   `RANGE_WIDTH_PCT`: **0.01** (+/- 1%)
+*   `INITIAL_HEDGE_CAPITAL_USDC`: **2000**       
+*   `SLIPPAGE_TOLERANCE`: **0.02** (2%)
+
+**`clp_hedger.py`**
+*   `PRICE_BUFFER_PCT`: **0.0015** (0.15%)       
+*   `MIN_THRESHOLD_ETH`: **0.008** (~$24)        
+*   `BASE_REBALANCE_THRESHOLD_PCT`: **0.09** (9%)
+*   `LARGE_HEDGE_MULTIPLIER`: **2.8**
+
+### test results
+position:
+  {
+    "type": "AUTOMATIC",
+    "token_id": 5174808,
+    "status": "CLOSED",
+    "target_value": 1994.89,
+    "entry_price": 2954.93,
+    "amount0_initial": 0.3299,      
+    "amount1_initial": 1019.94,     
+    "liquidity": "3679197389549125",
+    "range_upper": 2983.95,
+    "range_lower": 2924.86,
+    "timestamp_open": 1766529348,
+    "initial_hedge_usdc": 1001.01805,
+    "hedge_equity_usd": 1008.884158,
+    "hedge_pnl_realized": -5.85,
+    "hedge_fees_paid": 2.21,
+    "timestamp_close": 1766545502
+  }
+
+## results of tests are not satisfactional:
+1. the main problem of 5174808 is still difference between value of clp position at the end (start: $1994.42, end $1982.71 value of (tokens plus fees ~$4)) versus value of the hedge position (0.6735 weth, price 2922.5 -> 1968.3), it gives delta 1978 - 1968 = **-$10**...
+
+# questions
+1. is the calculation of hedge wrong?
+2. how we can proactivly fix it?
+
+---
+
+### 🚀 Analysis & New Idea: Asymmetric Compensation (2025-12-24)
+
+#### **Findings from Pos 5174808:**
+*   **The Problem:** Alpha (NAV vs Hold) dropped by ~$3.84 during a 1.1% price drop. 
+*   **The Cause:** Even though the **Mathematical Delta** was correct (using raw Liquidity), **Execution Friction** (Slippage and "Gamma Bleed") eroded the profit. 
+*   **The Mechanism:** When price drops, we must sell to increase the short. We are always "selling the bottom" of each micro-move. This means our average entry price for the hedge is always worse than the ideal theoretical price.
+
+#### **Proactive Fix: "Leaning into the Trend"**
+We have implemented a creative solution to offset this 0.35% leakage: **Asymmetric Compensation**.
+
+1.  **Linear Bias Adjustment:** The bot no longer calculates a purely symmetric hedge. It now "leans" into the price direction to create a PnL buffer.
+    *   **On Drops (Price < Entry):** The bot **Over-Hedges** by up to **+2.5%** at the bottom edge. This ensures the short gains "extra" value to cover the slippage/fees paid during rebalancing.
+    *   **On Rises (Price > Entry):** The bot **Under-Hedges** by up to **-2.5%** at the top edge.
+2.  **Efficiency:** Increased rebalance threshold to **15%** and price buffer to **0.25%** to reduce unnecessary churn ("Chop Bleed").
+3.  **Visibility:** IDLE and rebalance logs now include an `Adj: +X.X%` tag so the compensation is transparent.
+
+#### **Lessons Learned:**
+*   Pure delta-neutrality is theoretical. In a live market with fees and slippage, you must be "slightly biased" in the direction of the move to maintain a neutral **value** (NAV).