# 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`.