working version, before optimalization

florida/doc/CLP_DATA_INTERPRETATION.md

@@ -0,0 +1,66 @@
+# Interpreting CLP Pool Data
+
+This guide explains how to read and use the data generated by the **Pool Scanner** and **Analyzer** tools to select the most profitable liquidity pools.
+
+## 1. The Data Pipeline
+
+1.  **Scanner (`pool_scanner.py`):** Runs continuously. Connects to the blockchain every 10 minutes and records the "Heartbeat" of each pool:
+    *   **Tick:** The current price tick.
+    *   **FeeGrowthGlobal:** A cumulative counter of all fees earned by the pool since inception.
+2.  **Analyzer (`analyze_pool_data.py`):** Runs on demand. It "replays" the history recorded by the scanner to simulate how a specific strategy (e.g., $10k investment, +/- 10% range) would have performed.
+
+## 2. Reading the Analyzer Report
+
+When you run `python tools/analyze_pool_data.py`, you get a table like this:
+
+```text
+=== POOL PERFORMANCE REPORT ===
+Pool                                      Duration   Rebalances  Final Equity (Est)  ROI %
+Uniswap V3 (Base) - WETH/USDC             1 days     2           10050.00            0.50
+Aerodrome SlipStream (Base) - WETH/USDC   1 days     0           10010.00            0.10
+```
+
+### Key Metrics
+
+*   **Duration:** How long the scanner has been tracking this pool. Longer duration = more reliable data.
+*   **Rebalances:** How many times the price went **Out of Range** (+/- 10%) during this period.
+    *   **Low is Good:** Means the price is stable relative to your range. Less work for the bot, fewer fees paid.
+    *   **High is Bad:** Means the pool is volatile. You are paying frequent swap/gas fees to move your range.
+*   **Final Equity (Est):** Your simulated $10,000 starting capital after:
+    *   (+) Adding estimated Fee Income.
+    *   (-) Subtracting Rebalance Costs (0.1% per rebalance).
+    *   (+/-) Asset Value Change (Impermanent Loss is inherently captured because we track value in USD).
+*   **ROI %:** The return on investment for the duration.
+    *   `0.50%` in 1 day approx `180%` APR (compounded).
+
+## 3. Selecting a Pool
+
+Use the report to find the "Sweet Spot":
+
+| Scenario | Verdict |
+| :--- | :--- |
+| **High Fees, Low Rebalances** | **🥇 BEST.** The ideal pool. Price stays in range, volume is high. |
+| **High Fees, High Rebalances** | **⚠️ RISKY.** You earn a lot, but you burn a lot on swaps/gas. Net profit might be lower than expected. |
+| **Low Fees, Low Rebalances** | **😴 SAFE.** Good for "set and forget," but returns are meager. |
+| **Low Fees, High Rebalances** | **❌ AVOID.** You will lose money rebalancing a chop-heavy pool with no volume. |
+
+## 4. Advanced: Raw Data (`pool_history.csv`)
+
+If you open the CSV directly, you will see columns like `feeGrowthGlobal0X128`.
+
+*   **Fee Growth:** This number ONLY goes up.
+*   **Speed of Growth:** The faster this number increases, the higher the trading volume (and APR) of the pool.
+*   **Tick:**
+    *   `Price = 1.0001 ^ Tick`
+    *   Stable Tick = Low Volatility.
+
+## 5. Simulation Logic
+
+The Analyzer assumes:
+1.  **Initial Investment:** $10,000 USD.
+2.  **Strategy:** Active Management (Auto-Rebalance).
+3.  **Range:** +/- 10% (Configurable in script).
+4.  **Cost:** 0.1% of capital per rebalance (Swap fee + Gas estimate).
+5.  **Fee Accrual:** You ONLY earn fees when the recorded tick is inside your virtual range.
+
+*Note: This is a "Paper Trading" simulation. Real-world slippage and exact execution timing may vary.*