58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# 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`.
|