uniswap_auto_clp/todo/KPI_IMPLEMENTATION_PLAN.md

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.