Yield Analysis

#!/usr/bin/env python3
"""Offline DeFi yield calculator with fee APR, IL estimation, net yield,
break-even analysis, and sensitivity reporting.

Computes real yield from pool parameters without requiring any API calls.
Includes a --demo mode that compares three representative pool scenarios
(stablecoin, correlated, volatile).

Usage:
    python scripts/yield_calculator.py
    python scripts/yield_calculator.py --demo
    python scripts/yield_calculator.py --tvl 5000000 --volume 1500000 --fee-rate 0.0025 --volatility 0.8

Dependencies:
    uv pip install numpy

Environment Variables:
    None required — this script runs entirely offline.
"""

from __future__ import annotations

import argparse
import math
import sys
from dataclasses import dataclass
from typing import Optional

try:
    import numpy as np
except ImportError:
    print("numpy is required. Install with: uv pip install numpy")
    sys.exit(1)


# ── Data Models ─────────────────────────────────────────────────────


@dataclass
class PoolParams:
    """Parameters describing a liquidity pool and position."""

    name: str
    tvl: float  # Total pool TVL in USD
    daily_volume: float  # Average daily trading volume in USD
    fee_rate: float  # Swap fee rate (e.g. 0.0025 for 0.25%)
    annual_volatility: float  # Annualised volatility of the price ratio (0-1+)
    emission_apr: float  # Emission-based APR as decimal (e.g. 0.10 for 10%)
    emission_depreciation: float  # Expected 30-day emission token decline (0-1)
    position_size: float  # Your deposit in USD
    gas_cost_annual: float  # Estimated annual gas/tx costs in USD
    rebalance_cost_annual: float  # CLMM rebalance costs in USD (0 for standard pools)


@dataclass
class YieldReport:
    """Computed yield metrics for a pool position."""

    pool_name: str
    fee_apr: float
    emission_apr_raw: float
    emission_apr_adjusted: float
    estimated_il: float
    gas_cost_pct: float
    rebalance_cost_pct: float
    net_apr: float
    net_apy: float
    daily_income: float
    annual_income: float
    break_even_days: Optional[float]
    hold_vs_lp_advantage: float  # positive = LP is better


# ── Core Calculations ───────────────────────────────────────────────


def fee_apr(daily_volume: float, fee_rate: float, tvl: float) -> float:
    """Calculate annualised fee APR for a liquidity pool.

    Args:
        daily_volume: Average daily trading volume in USD.
        fee_rate: Swap fee rate as decimal (e.g. 0.0025).
        tvl: Total pool TVL in USD.

    Returns:
        Fee APR as a decimal (e.g. 0.20 for 20%).
    """
    if tvl <= 0:
        return 0.0
    return (daily_volume * fee_rate / tvl) * 365


def estimate_annual_il(annual_volatility: float) -> float:
    """Estimate annualised impermanent loss from volatility.

    Uses the approximation for constant-product AMMs:
        IL ≈ volatility^2 / 8
    This is a second-order Taylor expansion valid for moderate price moves.

    For high-volatility assets, actual IL may exceed this estimate.

    Args:
        annual_volatility: Annualised price-ratio volatility as decimal.

    Returns:
        Estimated annual IL as a positive decimal (e.g. 0.08 for 8%).
    """
    return (annual_volatility ** 2) / 8


def il_from_price_ratio(price_ratio: float) -> float:
    """Exact IL for a constant-product AMM given a price ratio change.

    Formula: IL = 2 * sqrt(r) / (1 + r) - 1

    Args:
        price_ratio: P_new / P_initial (e.g. 2.0 for a 2x price increase).

    Returns:
        IL as a negative decimal (e.g. -0.0566 for ~5.7% loss).
    """
    if price_ratio <= 0:
        return -1.0
    return 2 * math.sqrt(price_ratio) / (1 + price_ratio) - 1


def apr_to_apy(apr: float, compounds_per_year: int = 365) -> float:
    """Convert APR to APY with specified compounding frequency.

    Args:
        apr: Annual percentage rate as decimal.
        compounds_per_year: Number of compounding periods.

    Returns:
        APY as a decimal.
    """
    if compounds_per_year <= 0:
        return apr
    return (1 + apr / compounds_per_year) ** compounds_per_year - 1


def compute_yield(params: PoolParams) -> YieldReport:
    """Compute full yield report for a pool position.

    Args:
        params: Pool and position parameters.

    Returns:
        Complete yield analysis report.
    """
    # Fee income
    f_apr = fee_apr(params.daily_volume, params.fee_rate, params.tvl)

    # Emission yield adjusted for depreciation
    emission_raw = params.emission_apr
    emission_adj = emission_raw * (1 - params.emission_depreciation)

    # IL estimate
    il_annual = estimate_annual_il(params.annual_volatility)

    # Cost percentages relative to position
    gas_pct = params.gas_cost_annual / params.position_size if params.position_size > 0 else 0
    rebalance_pct = params.rebalance_cost_annual / params.position_size if params.position_size > 0 else 0

    # Net APR
    net = f_apr + emission_adj - il_annual - gas_pct - rebalance_pct

    # Net APY (daily compounding)
    net_apy = apr_to_apy(max(net, 0), 365) if net > 0 else net

    # Daily and annual income
    daily = net * params.position_size / 365
    annual = net * params.position_size

    # Break-even: how many days until fee income covers IL + costs
    daily_gross = (f_apr + emission_adj) * params.position_size / 365
    daily_cost = (il_annual + gas_pct + rebalance_pct) * params.position_size / 365
    if daily_gross > daily_cost and daily_cost > 0:
        # Days for cumulative net to cover initial entry cost (~$1 gas on Solana)
        entry_cost = 1.0  # approximate Solana deposit cost
        break_even = entry_cost / (daily_gross - daily_cost)
    elif daily_gross <= daily_cost:
        break_even = None  # Never breaks even
    else:
        break_even = 0.0

    # LP vs hold comparison: positive means LP is better
    # Hold earns 0 from fees/emissions but avoids IL
    hold_return = 0.0  # holding earns nothing extra (unless staking)
    lp_return = net
    advantage = lp_return - hold_return

    return YieldReport(
        pool_name=params.name,
        fee_apr=f_apr,
        emission_apr_raw=emission_raw,
        emission_apr_adjusted=emission_adj,
        estimated_il=il_annual,
        gas_cost_pct=gas_pct,
        rebalance_cost_pct=rebalance_pct,
        net_apr=net,
        net_apy=net_apy,
        daily_income=daily,
        annual_income=annual,
        break_even_days=break_even,
        hold_vs_lp_advantage=advantage,
    )


# ── Sensitivity Analysis ───────────────────────────────────────────


def sensitivity_table(
    params: PoolParams,
    volatilities: Optional[list[float]] = None,
) -> list[tuple[float, float, float]]:
    """Compute net yield across different volatility scenarios.

    Args:
        params: Base pool parameters.
        volatilities: List of volatilities to test. Defaults to a range.

    Returns:
        List of (volatility, net_apr, estimated_il) tuples.
    """
    if volatilities is None:
        volatilities = [0.1, 0.2, 0.3, 0.5, 0.7, 0.9, 1.2, 1.5, 2.0]

    results = []
    for vol in volatilities:
        p = PoolParams(
            name=params.name,
            tvl=params.tvl,
            daily_volume=params.daily_volume,
            fee_rate=params.fee_rate,
            annual_volatility=vol,
            emission_apr=params.emission_apr,
            emission_depreciation=params.emission_depreciation,
            position_size=params.position_size,
            gas_cost_annual=params.gas_cost_annual,
            rebalance_cost_annual=params.rebalance_cost_annual,
        )
        report = compute_yield(p)
        results.append((vol, report.net_apr, report.estimated_il))
    return results


# ── Display ─────────────────────────────────────────────────────────


def format_pct(value: float) -> str:
    """Format a decimal as a percentage string."""
    return f"{value * 100:+.2f}%" if value < 0 else f"{value * 100:.2f}%"


def print_report(report: YieldReport) -> None:
    """Print a formatted yield report to stdout.

    Args:
        report: Computed yield report.
    """
    print(f"\n{'═' * 60}")
    print(f"  YIELD REPORT: {report.pool_name}")
    print(f"{'═' * 60}")
    print(f"  Fee APR:                    {format_pct(report.fee_apr)}")
    print(f"  Emission APR (raw):         {format_pct(report.emission_apr_raw)}")
    print(f"  Emission APR (adjusted):    {format_pct(report.emission_apr_adjusted)}")
    print(f"  Estimated IL:               {format_pct(report.estimated_il)}")
    print(f"  Gas cost:                   {format_pct(report.gas_cost_pct)}")
    print(f"  Rebalance cost:             {format_pct(report.rebalance_cost_pct)}")
    print(f"{'─' * 60}")
    print(f"  Net APR:                    {format_pct(report.net_apr)}")
    print(f"  Net APY (daily compound):   {format_pct(report.net_apy)}")
    print(f"  Daily income:               ${report.daily_income:,.2f}")
    print(f"  Annual income:              ${report.annual_income:,.2f}")
    if report.break_even_days is not None:
        print(f"  Break-even:                 {report.break_even_days:.1f} days")
    else:
        print(f"  Break-even:                 Never (costs exceed income)")
    print(f"  LP vs Hold advantage:       {format_pct(report.hold_vs_lp_advantage)}")
    print(f"{'═' * 60}\n")


def print_sensitivity(params: PoolParams) -> None:
    """Print sensitivity analysis table.

    Args:
        params: Base pool parameters for sensitivity sweep.
    """
    results = sensitivity_table(params)
    print(f"\n{'─' * 50}")
    print(f"  SENSITIVITY: {params.name}")
    print(f"  Net yield vs. annual volatility")
    print(f"{'─' * 50}")
    print(f"  {'Volatility':>12}  {'Est. IL':>10}  {'Net APR':>10}")
    print(f"  {'─' * 12}  {'─' * 10}  {'─' * 10}")
    for vol, net, il in results:
        net_str = format_pct(net)
        print(f"  {format_pct(vol):>12}  {format_pct(il):>10}  {net_str:>10}")
    print(f"{'─' * 50}\n")


def print_comparison(reports: list[YieldReport]) -> None:
    """Print a side-by-side comparison table.

    Args:
        reports: List of yield reports to compare.
    """
    print(f"\n{'═' * 72}")
    print(f"  YIELD COMPARISON")
    print(f"{'═' * 72}")
    header = f"  {'Pool':<22} {'Fee APR':>9} {'IL':>9} {'Net APR':>9} {'Net APY':>9}"
    print(header)
    print(f"  {'─' * 22} {'─' * 9} {'─' * 9} {'─' * 9} {'─' * 9}")
    for r in sorted(reports, key=lambda x: x.net_apr, reverse=True):
        print(
            f"  {r.pool_name:<22} "
            f"{format_pct(r.fee_apr):>9} "
            f"{format_pct(r.estimated_il):>9} "
            f"{format_pct(r.net_apr):>9} "
            f"{format_pct(r.net_apy):>9}"
        )
    print(f"{'═' * 72}\n")


# ── Demo Scenarios ──────────────────────────────────────────────────


def demo_scenarios() -> list[PoolParams]:
    """Return three representative pool scenarios for demo mode.

    Returns:
        List of PoolParams for stablecoin, correlated, and volatile pools.
    """
    return [
        PoolParams(
            name="USDC-USDT (Stable)",
            tvl=50_000_000,
            daily_volume=15_000_000,
            fee_rate=0.0001,  # 1 bps
            annual_volatility=0.02,
            emission_apr=0.02,
            emission_depreciation=0.1,
            position_size=10_000,
            gas_cost_annual=10,
            rebalance_cost_annual=0,
        ),
        PoolParams(
            name="SOL-mSOL (Correlated)",
            tvl=20_000_000,
            daily_volume=5_000_000,
            fee_rate=0.0004,  # 4 bps
            annual_volatility=0.10,
            emission_apr=0.05,
            emission_depreciation=0.20,
            position_size=10_000,
            gas_cost_annual=20,
            rebalance_cost_annual=15,
        ),
        PoolParams(
            name="SOL-USDC (Volatile)",
            tvl=12_000_000,
            daily_volume=3_000_000,
            fee_rate=0.0025,  # 25 bps
            annual_volatility=0.80,
            emission_apr=0.15,
            emission_depreciation=0.35,
            position_size=10_000,
            gas_cost_annual=30,
            rebalance_cost_annual=50,
        ),
    ]


# ── CLI ─────────────────────────────────────────────────────────────


def build_parser() -> argparse.ArgumentParser:
    """Build CLI argument parser.

    Returns:
        Configured ArgumentParser.
    """
    parser = argparse.ArgumentParser(
        description="DeFi yield calculator — compute real yield from pool parameters"
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Run demo comparing stablecoin, correlated, and volatile pool scenarios",
    )
    parser.add_argument("--tvl", type=float, default=10_000_000, help="Pool TVL in USD")
    parser.add_argument("--volume", type=float, default=2_000_000, help="Daily volume in USD")
    parser.add_argument("--fee-rate", type=float, default=0.0025, help="Fee rate (e.g. 0.0025)")
    parser.add_argument("--volatility", type=float, default=0.80, help="Annual volatility (e.g. 0.80)")
    parser.add_argument("--emission-apr", type=float, default=0.10, help="Emission APR (e.g. 0.10)")
    parser.add_argument("--emission-depreciation", type=float, default=0.30, help="Emission token depreciation (0-1)")
    parser.add_argument("--position", type=float, default=10_000, help="Your position size in USD")
    parser.add_argument("--name", type=str, default="Custom Pool", help="Pool name for display")
    return parser


# ── Main ────────────────────────────────────────────────────────────


def main() -> None:
    """Entry point for yield calculator."""
    parser = build_parser()
    args = parser.parse_args()

    if args.demo:
        print("\n  DeFi Yield Calculator — Demo Mode")
        print("  Comparing three representative Solana pool scenarios\n")

        scenarios = demo_scenarios()
        reports = []

        for params in scenarios:
            report = compute_yield(params)
            reports.append(report)
            print_report(report)

        print_comparison(reports)

        # Sensitivity for the volatile pool
        print_sensitivity(scenarios[2])
    else:
        params = PoolParams(
            name=args.name,
            tvl=args.tvl,
            daily_volume=args.volume,
            fee_rate=args.fee_rate,
            annual_volatility=args.volatility,
            emission_apr=args.emission_apr,
            emission_depreciation=args.emission_depreciation,
            position_size=args.position,
            gas_cost_annual=30,
            rebalance_cost_annual=0,
        )

        report = compute_yield(params)
        print_report(report)
        print_sensitivity(params)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Fetch and compare DeFi yield opportunities on Solana.

Queries the DeFiLlama yields API (free, no authentication) for Solana pools
and lending markets, then ranks them by risk-adjusted yield. Includes a
--demo mode with representative data for offline use.

Usage:
    python scripts/yield_comparison.py
    python scripts/yield_comparison.py --demo
    python scripts/yield_comparison.py --min-tvl 1000000 --top 20

Dependencies:
    uv pip install httpx

Environment Variables:
    None required — DeFiLlama yields API is free and requires no API key.
"""

from __future__ import annotations

import argparse
import sys
from dataclasses import dataclass
from typing import Optional

try:
    import httpx
except ImportError:
    print("httpx is required. Install with: uv pip install httpx")
    sys.exit(1)


# ── Configuration ───────────────────────────────────────────────────

DEFILLAMA_YIELDS_URL = "https://yields.llama.fi/pools"
REQUEST_TIMEOUT = 30
SOL_STAKING_APR = 7.0  # Baseline SOL staking APR for comparison


# ── Data Models ─────────────────────────────────────────────────────


@dataclass
class YieldOpportunity:
    """A single yield opportunity with decomposed metrics."""

    pool_id: str
    project: str
    symbol: str
    chain: str
    tvl_usd: float
    apy_total: float
    apy_base: float  # From fees / real yield
    apy_reward: float  # From emissions
    il_7d: Optional[float]  # 7-day IL percentage
    exposure: str  # "single" or "multi"
    risk_tier: str  # Computed: "low", "medium", "high"
    real_yield_pct: float  # Percentage of yield from fees
    risk_adjusted_yield: float  # yield / risk_score


# ── Risk Assessment ─────────────────────────────────────────────────


def classify_risk(
    apy_total: float,
    apy_base: float,
    apy_reward: float,
    tvl_usd: float,
    exposure: str,
) -> tuple[str, float]:
    """Classify the risk tier and compute a risk score for a yield opportunity.

    Risk score ranges from 1 (lowest risk) to 10 (highest risk).

    Args:
        apy_total: Total APY.
        apy_base: Base APY from fees.
        apy_reward: Reward APY from emissions.
        tvl_usd: Total value locked in USD.
        exposure: "single" for single-asset, "multi" for multi-asset.

    Returns:
        Tuple of (risk_tier, risk_score).
    """
    score = 0.0

    # Emission dependency: high reward APY relative to base = more risk
    if apy_total > 0:
        emission_ratio = apy_reward / apy_total
    else:
        emission_ratio = 0
    score += emission_ratio * 3.0  # Max 3.0

    # Absolute yield level: very high APY is suspicious
    if apy_total > 100:
        score += 2.5
    elif apy_total > 50:
        score += 1.5
    elif apy_total > 20:
        score += 0.5

    # TVL: lower TVL = higher risk (less battle-tested, more slippage)
    if tvl_usd < 100_000:
        score += 2.0
    elif tvl_usd < 1_000_000:
        score += 1.0
    elif tvl_usd < 10_000_000:
        score += 0.5

    # Multi-asset exposure has IL risk
    if exposure == "multi":
        score += 1.0

    # Clamp to 1-10 range
    score = max(1.0, min(10.0, score))

    if score <= 3.0:
        tier = "low"
    elif score <= 6.0:
        tier = "medium"
    else:
        tier = "high"

    return tier, score


def compute_real_yield_pct(apy_base: float, apy_total: float) -> float:
    """Compute what percentage of total yield comes from real sources (fees).

    Args:
        apy_base: Base APY from fees.
        apy_total: Total APY.

    Returns:
        Percentage of yield from fees (0-100).
    """
    if apy_total <= 0:
        return 0.0
    return min(100.0, (apy_base / apy_total) * 100)


# ── Data Fetching ───────────────────────────────────────────────────


def fetch_solana_yields(min_tvl: float = 100_000) -> list[dict]:
    """Fetch Solana yield data from DeFiLlama.

    Args:
        min_tvl: Minimum TVL filter in USD.

    Returns:
        List of pool dictionaries from DeFiLlama.

    Raises:
        httpx.HTTPStatusError: On API error.
        httpx.ConnectError: On network failure.
    """
    try:
        response = httpx.get(DEFILLAMA_YIELDS_URL, timeout=REQUEST_TIMEOUT)
        response.raise_for_status()
    except httpx.ConnectError:
        print("Error: Could not connect to DeFiLlama API.")
        print("Check your internet connection or try --demo mode.")
        sys.exit(1)
    except httpx.HTTPStatusError as e:
        print(f"Error: DeFiLlama API returned {e.response.status_code}")
        sys.exit(1)

    data = response.json()
    pools = data.get("data", [])

    # Filter for Solana pools with minimum TVL
    solana_pools = [
        p for p in pools
        if p.get("chain") == "Solana"
        and (p.get("tvlUsd") or 0) >= min_tvl
        and (p.get("apy") or 0) > 0
    ]

    return solana_pools


def parse_pool(pool: dict) -> YieldOpportunity:
    """Parse a DeFiLlama pool dict into a YieldOpportunity.

    Args:
        pool: Raw pool data from DeFiLlama.

    Returns:
        Parsed YieldOpportunity with risk assessment.
    """
    apy_total = pool.get("apy") or 0.0
    apy_base = pool.get("apyBase") or 0.0
    apy_reward = pool.get("apyReward") or 0.0
    tvl_usd = pool.get("tvlUsd") or 0.0
    exposure = pool.get("exposure") or "multi"
    il_7d = pool.get("il7d")

    risk_tier, risk_score = classify_risk(
        apy_total, apy_base, apy_reward, tvl_usd, exposure
    )

    real_pct = compute_real_yield_pct(apy_base, apy_total)

    # Risk-adjusted yield: higher is better
    risk_adjusted = apy_total / risk_score if risk_score > 0 else 0

    return YieldOpportunity(
        pool_id=pool.get("pool", ""),
        project=pool.get("project", "unknown"),
        symbol=pool.get("symbol", "???"),
        chain="Solana",
        tvl_usd=tvl_usd,
        apy_total=apy_total,
        apy_base=apy_base,
        apy_reward=apy_reward,
        il_7d=il_7d,
        exposure=exposure,
        risk_tier=risk_tier,
        real_yield_pct=real_pct,
        risk_adjusted_yield=risk_adjusted,
    )


# ── Demo Data ───────────────────────────────────────────────────────


def demo_data() -> list[YieldOpportunity]:
    """Generate representative Solana yield data for offline demo.

    Returns:
        List of YieldOpportunity objects with realistic parameters.
    """
    pools = [
        # LP pools
        {"project": "raydium", "symbol": "SOL-USDC", "tvl": 45_000_000,
         "apy": 22.5, "base": 16.8, "reward": 5.7, "exposure": "multi"},
        {"project": "orca", "symbol": "SOL-USDC", "tvl": 38_000_000,
         "apy": 19.2, "base": 15.1, "reward": 4.1, "exposure": "multi"},
        {"project": "raydium", "symbol": "SOL-mSOL", "tvl": 12_000_000,
         "apy": 11.3, "base": 8.2, "reward": 3.1, "exposure": "multi"},
        {"project": "orca", "symbol": "SOL-jitoSOL", "tvl": 8_500_000,
         "apy": 12.8, "base": 9.5, "reward": 3.3, "exposure": "multi"},
        {"project": "raydium", "symbol": "USDC-USDT", "tvl": 55_000_000,
         "apy": 5.2, "base": 4.8, "reward": 0.4, "exposure": "multi"},
        {"project": "meteora", "symbol": "SOL-USDC", "tvl": 15_000_000,
         "apy": 28.4, "base": 22.1, "reward": 6.3, "exposure": "multi"},
        {"project": "raydium", "symbol": "RAY-USDC", "tvl": 6_200_000,
         "apy": 35.6, "base": 12.3, "reward": 23.3, "exposure": "multi"},
        {"project": "orca", "symbol": "BONK-SOL", "tvl": 3_800_000,
         "apy": 68.2, "base": 45.1, "reward": 23.1, "exposure": "multi"},
        # Lending
        {"project": "marginfi", "symbol": "USDC", "tvl": 120_000_000,
         "apy": 8.5, "base": 5.2, "reward": 3.3, "exposure": "single"},
        {"project": "marginfi", "symbol": "SOL", "tvl": 85_000_000,
         "apy": 6.1, "base": 3.8, "reward": 2.3, "exposure": "single"},
        {"project": "kamino", "symbol": "USDC", "tvl": 95_000_000,
         "apy": 9.2, "base": 6.1, "reward": 3.1, "exposure": "single"},
        {"project": "kamino", "symbol": "SOL", "tvl": 60_000_000,
         "apy": 5.8, "base": 3.5, "reward": 2.3, "exposure": "single"},
        {"project": "solend", "symbol": "USDC", "tvl": 45_000_000,
         "apy": 6.8, "base": 5.5, "reward": 1.3, "exposure": "single"},
        # Staking / LST
        {"project": "marinade", "symbol": "mSOL", "tvl": 800_000_000,
         "apy": 7.2, "base": 7.2, "reward": 0.0, "exposure": "single"},
        {"project": "jito", "symbol": "jitoSOL", "tvl": 600_000_000,
         "apy": 7.5, "base": 7.5, "reward": 0.0, "exposure": "single"},
        {"project": "blazestake", "symbol": "bSOL", "tvl": 150_000_000,
         "apy": 7.0, "base": 7.0, "reward": 0.0, "exposure": "single"},
    ]

    results = []
    for p in pools:
        risk_tier, risk_score = classify_risk(
            p["apy"], p["base"], p["reward"], p["tvl"], p["exposure"]
        )
        real_pct = compute_real_yield_pct(p["base"], p["apy"])
        risk_adj = p["apy"] / risk_score if risk_score > 0 else 0

        results.append(YieldOpportunity(
            pool_id=f"demo-{p['project']}-{p['symbol']}",
            project=p["project"],
            symbol=p["symbol"],
            chain="Solana",
            tvl_usd=p["tvl"],
            apy_total=p["apy"],
            apy_base=p["base"],
            apy_reward=p["reward"],
            il_7d=None,
            exposure=p["exposure"],
            risk_tier=risk_tier,
            real_yield_pct=real_pct,
            risk_adjusted_yield=risk_adj,
        ))

    return results


# ── Display ─────────────────────────────────────────────────────────


def format_usd(value: float) -> str:
    """Format USD value with K/M/B suffixes."""
    if value >= 1_000_000_000:
        return f"${value / 1_000_000_000:.1f}B"
    if value >= 1_000_000:
        return f"${value / 1_000_000:.1f}M"
    if value >= 1_000:
        return f"${value / 1_000:.0f}K"
    return f"${value:.0f}"


def print_yield_table(
    opportunities: list[YieldOpportunity],
    title: str,
    sort_by: str = "risk_adjusted",
    limit: int = 20,
) -> None:
    """Print a formatted yield comparison table.

    Args:
        opportunities: List of yield opportunities.
        title: Table title.
        sort_by: Sort key — "risk_adjusted", "apy", "real_yield", "tvl".
        limit: Maximum rows to display.
    """
    sort_keys = {
        "risk_adjusted": lambda x: x.risk_adjusted_yield,
        "apy": lambda x: x.apy_total,
        "real_yield": lambda x: x.real_yield_pct,
        "tvl": lambda x: x.tvl_usd,
    }
    key_fn = sort_keys.get(sort_by, sort_keys["risk_adjusted"])
    sorted_opps = sorted(opportunities, key=key_fn, reverse=True)[:limit]

    print(f"\n{'═' * 100}")
    print(f"  {title}")
    print(f"  Sorted by: {sort_by} | SOL staking baseline: {SOL_STAKING_APR:.1f}% APR")
    print(f"{'═' * 100}")

    header = (
        f"  {'Protocol':<12} {'Pool':<16} {'TVL':>9} "
        f"{'APY':>7} {'Fee':>7} {'Reward':>7} "
        f"{'Real%':>6} {'Risk':>6} {'Adj.':>7}"
    )
    print(header)
    print(f"  {'─' * 12} {'─' * 16} {'─' * 9} {'─' * 7} {'─' * 7} {'─' * 7} {'─' * 6} {'─' * 6} {'─' * 7}")

    for opp in sorted_opps:
        risk_marker = {"low": " ", "medium": "*", "high": "!"}
        marker = risk_marker.get(opp.risk_tier, "?")

        print(
            f"  {opp.project:<12} {opp.symbol:<16} {format_usd(opp.tvl_usd):>9} "
            f"{opp.apy_total:>6.1f}% {opp.apy_base:>6.1f}% {opp.apy_reward:>6.1f}% "
            f"{opp.real_yield_pct:>5.0f}% {opp.risk_tier:>5}{marker} "
            f"{opp.risk_adjusted_yield:>6.1f}"
        )

    print(f"{'═' * 100}")
    print(f"  Risk: * = medium, ! = high | Adj. = APY / risk_score (higher is better)")
    print()


def print_category_summary(opportunities: list[YieldOpportunity]) -> None:
    """Print yield summary grouped by category.

    Args:
        opportunities: List of yield opportunities.
    """
    # Group by type
    lp_pools = [o for o in opportunities if o.exposure == "multi"]
    lending = [o for o in opportunities if o.exposure == "single" and o.apy_reward > 0]
    staking = [o for o in opportunities if o.exposure == "single" and o.apy_reward == 0]

    print(f"\n{'─' * 60}")
    print(f"  CATEGORY SUMMARY")
    print(f"{'─' * 60}")

    categories = [
        ("LP Pools", lp_pools),
        ("Lending", lending),
        ("Staking / LST", staking),
    ]

    for name, group in categories:
        if not group:
            continue
        avg_apy = sum(o.apy_total for o in group) / len(group)
        avg_real = sum(o.real_yield_pct for o in group) / len(group)
        total_tvl = sum(o.tvl_usd for o in group)
        best = max(group, key=lambda x: x.risk_adjusted_yield)

        print(f"\n  {name} ({len(group)} opportunities)")
        print(f"    Average APY:          {avg_apy:.1f}%")
        print(f"    Average real yield:   {avg_real:.0f}% of total")
        print(f"    Total TVL:            {format_usd(total_tvl)}")
        print(f"    Best risk-adjusted:   {best.symbol} on {best.project} ({best.apy_total:.1f}% APY)")

    print(f"\n{'─' * 60}")

    # Comparison to SOL staking
    above_staking = [o for o in opportunities if o.apy_base > SOL_STAKING_APR]
    print(f"\n  {len(above_staking)} of {len(opportunities)} opportunities have")
    print(f"  fee-based yield above SOL staking ({SOL_STAKING_APR:.1f}% APR).")
    print()


def print_top_picks(opportunities: list[YieldOpportunity], count: int = 5) -> None:
    """Print top risk-adjusted yield picks with rationale.

    Args:
        opportunities: All yield opportunities.
        count: Number of top picks to display.
    """
    # Filter to medium or low risk only
    viable = [o for o in opportunities if o.risk_tier in ("low", "medium")]
    top = sorted(viable, key=lambda x: x.risk_adjusted_yield, reverse=True)[:count]

    print(f"\n{'═' * 60}")
    print(f"  TOP {count} RISK-ADJUSTED OPPORTUNITIES")
    print(f"  (filtered to low/medium risk only)")
    print(f"{'═' * 60}")

    for i, opp in enumerate(top, 1):
        real_label = "real yield" if opp.real_yield_pct > 50 else "emission-heavy"
        print(f"\n  {i}. {opp.symbol} on {opp.project}")
        print(f"     APY: {opp.apy_total:.1f}% ({opp.apy_base:.1f}% fees + {opp.apy_reward:.1f}% rewards)")
        print(f"     TVL: {format_usd(opp.tvl_usd)} | Risk: {opp.risk_tier} | Type: {real_label}")
        print(f"     Risk-adjusted score: {opp.risk_adjusted_yield:.1f}")

    print(f"\n{'═' * 60}")
    print(f"  Note: This is analysis output, not financial advice.")
    print(f"  Always verify data on-chain before making decisions.")
    print()


# ── CLI ─────────────────────────────────────────────────────────────


def build_parser() -> argparse.ArgumentParser:
    """Build CLI argument parser.

    Returns:
        Configured ArgumentParser.
    """
    parser = argparse.ArgumentParser(
        description="Compare Solana DeFi yield opportunities using DeFiLlama data"
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Use representative demo data instead of live API",
    )
    parser.add_argument(
        "--min-tvl",
        type=float,
        default=1_000_000,
        help="Minimum TVL filter in USD (default: 1000000)",
    )
    parser.add_argument(
        "--top",
        type=int,
        default=20,
        help="Number of results to display (default: 20)",
    )
    parser.add_argument(
        "--sort",
        choices=["risk_adjusted", "apy", "real_yield", "tvl"],
        default="risk_adjusted",
        help="Sort order (default: risk_adjusted)",
    )
    return parser


# ── Main ────────────────────────────────────────────────────────────


def main() -> None:
    """Entry point for yield comparison tool."""
    parser = build_parser()
    args = parser.parse_args()

    if args.demo:
        print("\n  Solana Yield Comparison — Demo Mode")
        print("  Using representative data (not live)\n")
        opportunities = demo_data()
    else:
        print("\n  Solana Yield Comparison — Live Data")
        print(f"  Fetching from DeFiLlama (min TVL: {format_usd(args.min_tvl)})...\n")
        raw_pools = fetch_solana_yields(min_tvl=args.min_tvl)
        if not raw_pools:
            print("  No Solana pools found matching criteria.")
            print("  Try lowering --min-tvl or use --demo mode.")
            sys.exit(0)
        opportunities = [parse_pool(p) for p in raw_pools]
        print(f"  Found {len(opportunities)} Solana yield opportunities.\n")

    # Display results
    print_yield_table(opportunities, "SOLANA YIELD OPPORTUNITIES", sort_by=args.sort, limit=args.top)
    print_category_summary(opportunities)
    print_top_picks(opportunities)


if __name__ == "__main__":
    main()