Nfk/refactor tvl

[nofreekoolaid]

Add TVL Extrapolation Feature and Enhanced Tooling

Summary

This PR introduces linear extrapolation for TVL data analysis, adds convenient make targets for quick queries, and includes a comprehensive test suite with 26 tests covering all functionality.

New Features

TVL Extrapolation

• Linear Extrapolation at start/end dates: Uses the trend from the two nearest data points to estimate TVL values when data only exists on one side of a date
• --no-extrapolate flag: Optional flag to disable extrapolation and only return dates that can be interpolated between two surrounding data points
• Default behavior: Extrapolation is enabled by default for complete date range coverage

Make Targets for Easy Usage

• make tvl: Get daily TVL data in CSV format

  make tvl PROTOCOL=euler START=2025-01-01 END=2025-01-15

• make avgtvl: Get average TVL with interpolation/extrapolation

  make avgtvl PROTOCOL=euler START=2025-01-01 END=2025-01-15

• Optional parameters: Support for OPTS='--no-extrapolate' or other flags

Technical Details

API Changes

• Added extrapolate: bool = True parameter to:
  • get_tvl_dataset()
  • get_average_tvl()
• Added _get_extrapolation_slope() helper function
• Enhanced interpolation logic to support both interpolation and extrapolation

How Extrapolation Works

1. Start of range: If data only exists after the start date, uses the two earliest data points to calculate a slope and extrapolates backward
2. End of range: If data only exists before the end date, uses the two most recent data points to calculate a slope and extrapolates forward
3. Middle gaps: Continues to use linear interpolation between surrounding points

Example Output

date,tvl,is_interpolated
2025-01-01,110398623.00,false
2025-01-02,111157719.00,false
2025-01-03,115676449.00,false
2025-01-04,124228188.00,false
2025-01-05,137182701.00,false

Backward Compatibility

Fully backward compatible

• Default behavior now includes extrapolation (more features)
• Original behavior available with --no-extrapolate flag
• Existing scripts will work without modifications
• All existing function signatures maintained with new optional parameters

Usage Examples

# Get daily TVL data (CSV)
make tvl PROTOCOL=euler START=2025-01-01 END=2025-01-15

# Get average TVL
make avgtvl PROTOCOL=euler START=2025-01-01 END=2025-01-15

# Disable extrapolation
make tvl PROTOCOL=aave START=2025-01-01 END=2025-01-31 OPTS='--no-extrapolate'

# Using CLI tool
uv run trr.py tvl euler 2025-01-01 2025-01-15 --format json
uv run trr.py tvl euler 2025-01-01 2025-01-15 --mean

Testing Instructions

1. Run the test suite:

   make test

2. Test with real data:

   make avgtvl PROTOCOL=euler START=2025-01-01 END=2025-01-15

3. Run all CI checks:

   make cichecks