feat: add untracked aerodrome tools and todo analysis documents

todo/KPI_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,57 @@
+# KPI Implementation Proposal
+
+**Status:** Proposed
+**Date:** 2025-12-20
+
+## 1. Objective
+Implement a robust KPI tracking system to answer: "Is this strategy actually making money compared to HODLing?"
+
+## 2. Architecture
+We will introduce a lightweight **KPI Module** (`tools/kpi_tracker.py`) that is called periodically by `uniswap_manager.py`.
+
+### A. Data Sources
+1.  **Uniswap V3:** Current Position Value + Unclaimed Fees (from `uniswap_manager.py`).
+2.  **Hyperliquid:** Equity + Unrealized PnL (from `clp_hedger.py` / API).
+3.  **Wallet:** ETH/USDC balances (from Web3).
+4.  **History:** Initial Amounts (from `hedge_status.json`).
+
+### B. The Metrics (KPIs)
+
+#### 1. Net Asset Value (NAV)
+*   `NAV = (Uniswap Pos Value) + (Hyperliquid Equity) + (Wallet ETH * Price) + (Wallet USDC)`
+*   *Note:* Allows tracking total portfolio health.
+
+#### 2. Strategy vs. Benchmark (Alpha)
+*   **Strategy Value:** `Current NAV`
+*   **Benchmark Value (HODL):** 
+    *   Snapshot at start: `Initial ETH` + `Initial USDC`.
+    *   Current Val: `(Initial ETH * Current Price) + Initial USDC`.
+*   **Alpha:** `Strategy Value - Benchmark Value`.
+
+#### 3. Fee Coverage Ratio
+*   `Ratio = (Uniswap Fees Earned) / (Hedge Cost)`
+*   *Hedge Cost:* Fees paid on Hyperliquid + Funding Paid.
+
+## 3. Implementation Plan
+
+### Step 1: Create `tools/kpi_tracker.py`
+This module will handle the math and logging.
+*   **Functions:**
+    *   `log_kpi_snapshot(nav_data, market_data)`: Appends to CSV.
+    *   `calculate_benchmark(initial_snapshot, current_price)`: Returns HODL value.
+
+### Step 2: CSV Schema (`logs/kpi_history.csv`)
+| Timestamp | NAV | Benchmark_NAV | Alpha | Uniswap_Fees_Acc | Hedge_Cost_Acc | Fee_Coverage | ETH_Price |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| ... | ... | ... | ... | ... | ... | ... | ... |
+
+### Step 3: Integration
+*   **Hook into `uniswap_manager.py`:**
+    *   Every loop (or every hour), gather data.
+    *   Call `kpi_tracker.log_kpi_snapshot()`.
+*   **Note:** `uniswap_manager.py` manages the slow loop, so it's the perfect place to record "macro" performance without adding latency to the hedger.
+
+## 4. Next Steps
+1.  Approve this plan?
+2.  I will generate `tools/kpi_tracker.py`.
+3.  I will integrate it into `uniswap_manager.py`.