Slippage Modeling

#!/usr/bin/env python3
"""Estimate total execution cost and break-even for a Solana DEX trade.

Computes all cost components — price impact, DEX fee, priority fee, and
MEV risk — then calculates the minimum price move needed to break even
on a roundtrip trade.

Usage:
    python scripts/execution_cost.py
    python scripts/execution_cost.py --demo
    TOKEN_MINT=<mint> TRADE_SIZE_SOL=5.0 python scripts/execution_cost.py

Dependencies:
    uv pip install httpx

Environment Variables:
    TOKEN_MINT: Solana token mint address (optional, defaults to BONK).
    TRADE_SIZE_SOL: Trade size in SOL (optional, defaults to 1.0).
"""

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

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


# ── Configuration ───────────────────────────────────────────────────
JUPITER_QUOTE_URL = "https://quote-api.jup.ag/v6/quote"
SOL_MINT = "So11111111111111111111111111111111111111112"
SOL_DECIMALS = 9

DEFAULT_TOKEN_MINT = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
DEFAULT_TRADE_SIZE = 1.0

# Priority fee estimates by congestion level
PRIORITY_FEE_LOW = 0.0001      # SOL
PRIORITY_FEE_NORMAL = 0.001    # SOL
PRIORITY_FEE_HIGH = 0.005      # SOL

# MEV risk thresholds (trade size in SOL)
MEV_THRESHOLD_LOW = 1.0
MEV_THRESHOLD_MED = 5.0
MEV_THRESHOLD_HIGH = 20.0

REQUEST_TIMEOUT = 15.0


# ── Data Classes ────────────────────────────────────────────────────
@dataclass
class CostBreakdown:
    """Complete execution cost breakdown for a trade."""

    trade_size_sol: float
    direction: str  # "buy" or "sell"

    # Component costs in basis points
    impact_bps: float
    fee_bps: float
    priority_bps: float
    mev_bps: float

    # Derived
    total_bps: float
    total_sol: float

    # Quote details
    output_amount: float
    effective_price: float
    spot_estimate: float  # estimated spot from small quote

    # Route info
    route_description: str


@dataclass
class BreakEvenAnalysis:
    """Break-even analysis for a roundtrip trade."""

    entry_cost_bps: float
    exit_cost_bps: float
    roundtrip_bps: float
    roundtrip_pct: float
    roundtrip_sol: float
    required_price_move_pct: float


# ── Jupiter Quote ───────────────────────────────────────────────────
def fetch_quote(
    input_mint: str,
    output_mint: str,
    amount_lamports: int,
) -> Optional[dict]:
    """Fetch a Jupiter V6 quote.

    Args:
        input_mint: Input token mint.
        output_mint: Output token mint.
        amount_lamports: Input amount in smallest units.

    Returns:
        Parsed JSON response or None on error.
    """
    params = {
        "inputMint": input_mint,
        "outputMint": output_mint,
        "amount": str(amount_lamports),
        "slippageBps": "5000",
    }

    try:
        with httpx.Client(timeout=REQUEST_TIMEOUT) as client:
            resp = client.get(JUPITER_QUOTE_URL, params=params)
            resp.raise_for_status()
            return resp.json()
    except (httpx.HTTPStatusError, httpx.RequestError) as e:
        print(f"Quote error: {e}")
        return None


def extract_fee_bps(quote_data: dict) -> float:
    """Extract total swap fee from Jupiter route plan.

    Args:
        quote_data: Raw Jupiter quote response.

    Returns:
        Estimated fee in basis points.
    """
    route_plan = quote_data.get("routePlan", [])
    if not route_plan:
        return 25.0  # Default assumption: Raydium 0.25%

    total_fee_pct = 0.0
    for step in route_plan:
        swap_info = step.get("swapInfo", {})
        fee_amount = int(swap_info.get("feeAmount", "0"))
        in_amount = int(swap_info.get("inAmount", "1"))
        if in_amount > 0:
            total_fee_pct += fee_amount / in_amount

    return total_fee_pct * 10_000 if total_fee_pct > 0 else 25.0


def describe_route(quote_data: dict) -> str:
    """Generate human-readable route description.

    Args:
        quote_data: Raw Jupiter quote response.

    Returns:
        String describing the route.
    """
    route_plan = quote_data.get("routePlan", [])
    if not route_plan:
        return "Unknown route"

    labels = []
    for step in route_plan:
        swap_info = step.get("swapInfo", {})
        label = swap_info.get("label", "Unknown")
        pct = step.get("percent", 100)
        labels.append(f"{label} ({pct}%)")

    return " → ".join(labels)


# ── Cost Estimation ─────────────────────────────────────────────────
def estimate_priority_fee_bps(trade_size_sol: float, congestion: str = "normal") -> float:
    """Estimate priority fee in bps relative to trade size.

    Args:
        trade_size_sol: Trade size in SOL.
        congestion: Network congestion level ('low', 'normal', 'high').

    Returns:
        Priority fee cost in basis points.
    """
    fee_sol = {
        "low": PRIORITY_FEE_LOW,
        "normal": PRIORITY_FEE_NORMAL,
        "high": PRIORITY_FEE_HIGH,
    }.get(congestion, PRIORITY_FEE_NORMAL)

    if trade_size_sol <= 0:
        return 0.0
    return (fee_sol / trade_size_sol) * 10_000


def estimate_mev_bps(trade_size_sol: float, pool_tvl_estimate: str = "medium") -> float:
    """Estimate MEV risk cost in basis points.

    Uses trade size and estimated pool liquidity to assess sandwich
    attack risk. Larger trades on thinner pools face higher MEV cost.

    Args:
        trade_size_sol: Trade size in SOL.
        pool_tvl_estimate: Pool liquidity category ('deep', 'medium', 'thin').

    Returns:
        Estimated MEV cost in basis points.
    """
    # Base MEV risk by pool depth
    base_mev = {
        "deep": 2.0,    # >$1M TVL
        "medium": 10.0,  # $100K-$1M TVL
        "thin": 30.0,    # <$100K TVL
    }.get(pool_tvl_estimate, 10.0)

    # Scale with trade size (larger trades attract more MEV)
    if trade_size_sol < MEV_THRESHOLD_LOW:
        size_mult = 0.5
    elif trade_size_sol < MEV_THRESHOLD_MED:
        size_mult = 1.0
    elif trade_size_sol < MEV_THRESHOLD_HIGH:
        size_mult = 2.0
    else:
        size_mult = 4.0

    return base_mev * size_mult


def estimate_execution_cost(
    token_mint: str,
    trade_size_sol: float,
    direction: str = "buy",
    congestion: str = "normal",
    pool_depth: str = "medium",
) -> Optional[CostBreakdown]:
    """Estimate total execution cost for a trade.

    Fetches Jupiter quotes at the target size and a small reference size,
    computes price impact, adds fee/priority/MEV estimates.

    Args:
        token_mint: Token mint address.
        trade_size_sol: Trade size in SOL.
        direction: 'buy' (SOL -> token) or 'sell' (token -> SOL).
        congestion: Network congestion level.
        pool_depth: Estimated pool liquidity depth.

    Returns:
        CostBreakdown or None if quotes fail.
    """
    # Fetch small reference quote (0.001 SOL) for spot price estimate
    ref_lamports = int(0.001 * 10**SOL_DECIMALS)
    ref_quote = fetch_quote(SOL_MINT, token_mint, ref_lamports)
    if not ref_quote:
        print("Failed to fetch reference quote.")
        return None

    ref_out = int(ref_quote.get("outAmount", 0))
    if ref_out <= 0:
        print("Reference quote returned zero output.")
        return None

    spot_estimate = 0.001 / ref_out  # SOL per raw unit

    # Fetch actual trade quote
    trade_lamports = int(trade_size_sol * 10**SOL_DECIMALS)
    trade_quote = fetch_quote(SOL_MINT, token_mint, trade_lamports)
    if not trade_quote:
        print("Failed to fetch trade quote.")
        return None

    trade_out = int(trade_quote.get("outAmount", 0))
    if trade_out <= 0:
        print("Trade quote returned zero output.")
        return None

    effective_price = trade_size_sol / trade_out  # SOL per raw unit

    # Price impact: how much worse than spot
    impact_frac = (effective_price - spot_estimate) / spot_estimate if spot_estimate > 0 else 0
    impact_bps = max(0.0, impact_frac * 10_000)

    # Fee from route
    fee_bps = extract_fee_bps(trade_quote)

    # Priority fee
    priority_bps = estimate_priority_fee_bps(trade_size_sol, congestion)

    # MEV risk
    mev_bps = estimate_mev_bps(trade_size_sol, pool_depth)

    total_bps = impact_bps + fee_bps + priority_bps + mev_bps
    total_sol = trade_size_sol * total_bps / 10_000

    return CostBreakdown(
        trade_size_sol=trade_size_sol,
        direction=direction,
        impact_bps=round(impact_bps, 2),
        fee_bps=round(fee_bps, 2),
        priority_bps=round(priority_bps, 2),
        mev_bps=round(mev_bps, 2),
        total_bps=round(total_bps, 2),
        total_sol=round(total_sol, 6),
        output_amount=trade_out,
        effective_price=effective_price,
        spot_estimate=spot_estimate,
        route_description=describe_route(trade_quote),
    )


def estimate_execution_cost_demo(
    trade_size_sol: float,
    direction: str = "buy",
) -> CostBreakdown:
    """Generate demo execution cost estimate with synthetic data.

    Simulates a mid-cap token with ~$300K TVL.

    Args:
        trade_size_sol: Trade size in SOL.
        direction: Trade direction.

    Returns:
        Synthetic CostBreakdown.
    """
    # Simulated pool: 750 SOL reserves
    pool_sol = 750.0
    impact_frac = trade_size_sol / (pool_sol + trade_size_sol)
    impact_bps = round(impact_frac * 10_000, 2)

    fee_bps = 25.0  # Raydium standard
    priority_bps = round(estimate_priority_fee_bps(trade_size_sol, "normal"), 2)
    mev_bps = round(estimate_mev_bps(trade_size_sol, "medium"), 2)

    total_bps = impact_bps + fee_bps + priority_bps + mev_bps
    total_sol = trade_size_sol * total_bps / 10_000

    spot_price = 0.0001
    eff_price = spot_price * (1 + impact_frac)

    return CostBreakdown(
        trade_size_sol=trade_size_sol,
        direction=direction,
        impact_bps=impact_bps,
        fee_bps=fee_bps,
        priority_bps=priority_bps,
        mev_bps=mev_bps,
        total_bps=round(total_bps, 2),
        total_sol=round(total_sol, 6),
        output_amount=int(trade_size_sol / eff_price),
        effective_price=eff_price,
        spot_estimate=spot_price,
        route_description="Raydium AMM (100%) [demo]",
    )


# ── Break-Even Analysis ────────────────────────────────────────────
def compute_break_even(
    entry_cost: CostBreakdown,
    exit_multiplier: float = 1.2,
) -> BreakEvenAnalysis:
    """Compute break-even price move for a roundtrip trade.

    Exit slippage is typically higher than entry (selling into a pool
    you just bought from). exit_multiplier scales the entry cost.

    Args:
        entry_cost: Cost breakdown for the entry trade.
        exit_multiplier: Factor to scale entry costs for exit estimate.

    Returns:
        BreakEvenAnalysis with roundtrip costs.
    """
    exit_impact = entry_cost.impact_bps * exit_multiplier
    exit_bps = exit_impact + entry_cost.fee_bps + entry_cost.priority_bps + entry_cost.mev_bps * 0.5

    roundtrip_bps = entry_cost.total_bps + exit_bps
    roundtrip_pct = roundtrip_bps / 100.0
    roundtrip_sol = entry_cost.trade_size_sol * roundtrip_bps / 10_000
    required_move = roundtrip_bps / (10_000 - roundtrip_bps) * 100

    return BreakEvenAnalysis(
        entry_cost_bps=round(entry_cost.total_bps, 2),
        exit_cost_bps=round(exit_bps, 2),
        roundtrip_bps=round(roundtrip_bps, 2),
        roundtrip_pct=round(roundtrip_pct, 4),
        roundtrip_sol=round(roundtrip_sol, 6),
        required_price_move_pct=round(required_move, 4),
    )


# ── Display ─────────────────────────────────────────────────────────
def print_cost_report(cost: CostBreakdown, break_even: BreakEvenAnalysis) -> None:
    """Print formatted execution cost report.

    Args:
        cost: Execution cost breakdown.
        break_even: Break-even analysis.
    """
    print("\n" + "=" * 60)
    print("EXECUTION COST REPORT")
    print("=" * 60)
    print(f"Direction:    {cost.direction.upper()}")
    print(f"Trade size:   {cost.trade_size_sol:.4f} SOL")
    print(f"Route:        {cost.route_description}")

    print("\n--- Cost Components ---")
    print(f"  Price impact:    {cost.impact_bps:>8.2f} bps")
    print(f"  DEX fee:         {cost.fee_bps:>8.2f} bps")
    print(f"  Priority fee:    {cost.priority_bps:>8.2f} bps")
    print(f"  MEV risk:        {cost.mev_bps:>8.2f} bps")
    print(f"  ────────────────────────────")
    print(f"  TOTAL:           {cost.total_bps:>8.2f} bps  ({cost.total_bps / 100:.2f}%)")
    print(f"  Cost in SOL:     {cost.total_sol:>8.6f} SOL")

    print("\n--- Break-Even Analysis ---")
    print(f"  Entry cost:        {break_even.entry_cost_bps:>8.2f} bps")
    print(f"  Exit cost (est):   {break_even.exit_cost_bps:>8.2f} bps")
    print(f"  Roundtrip cost:    {break_even.roundtrip_bps:>8.2f} bps  ({break_even.roundtrip_pct:.2f}%)")
    print(f"  Roundtrip in SOL:  {break_even.roundtrip_sol:>8.6f} SOL")
    print(f"  Min price move:    {break_even.required_price_move_pct:>8.4f}%")

    print("\n--- Assessment ---")
    if break_even.roundtrip_bps < 100:
        print("  LOW COST — Favorable execution. Most strategies can absorb this.")
    elif break_even.roundtrip_bps < 300:
        print("  MODERATE COST — Ensure expected move exceeds break-even threshold.")
    elif break_even.roundtrip_bps < 1000:
        print("  HIGH COST — Only viable for high-conviction, large-move trades.")
    else:
        print("  VERY HIGH COST — Consider smaller size or higher-liquidity alternatives.")

    print("\n" + "=" * 60)
    print("NOTE: This is an estimate for informational purposes.")
    print("Actual costs may differ due to market conditions.")
    print("=" * 60)


# ── Main ────────────────────────────────────────────────────────────
def main() -> None:
    """Run execution cost estimation."""
    parser = argparse.ArgumentParser(description="Estimate DEX execution costs")
    parser.add_argument("--demo", action="store_true", help="Use synthetic data")
    parser.add_argument("--token", type=str, default=None, help="Token mint address")
    parser.add_argument("--size", type=float, default=None, help="Trade size in SOL")
    parser.add_argument("--direction", type=str, default="buy", choices=["buy", "sell"])
    parser.add_argument("--congestion", type=str, default="normal", choices=["low", "normal", "high"])
    parser.add_argument("--pool-depth", type=str, default="medium", choices=["deep", "medium", "thin"])
    args = parser.parse_args()

    token_mint = args.token or os.getenv("TOKEN_MINT", DEFAULT_TOKEN_MINT)
    trade_size = args.size or float(os.getenv("TRADE_SIZE_SOL", str(DEFAULT_TRADE_SIZE)))

    if args.demo:
        print("DEMO MODE — using synthetic cost estimates")
        print(f"Simulated mid-cap token, pool TVL ~$300K")
        cost = estimate_execution_cost_demo(trade_size, args.direction)
    else:
        print(f"Estimating costs for {trade_size:.4f} SOL {args.direction}")
        print(f"Token: {token_mint}")
        cost = estimate_execution_cost(
            token_mint, trade_size, args.direction, args.congestion, args.pool_depth
        )

    if cost is None:
        print("Failed to estimate execution cost.")
        sys.exit(1)

    break_even = compute_break_even(cost)
    print_cost_report(cost, break_even)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Build empirical slippage curves from Jupiter quotes or synthetic data.

Queries Jupiter V6 API at multiple trade sizes to measure actual executable
slippage, fits a power-law model, and estimates maximum trade sizes for
various slippage thresholds.

Usage:
    python scripts/slippage_curve.py
    python scripts/slippage_curve.py --demo
    TOKEN_MINT=<mint_address> python scripts/slippage_curve.py

Dependencies:
    uv pip install httpx

Environment Variables:
    TOKEN_MINT: Solana token mint address to analyze (optional, defaults to
                BONK for demonstration).
"""

import argparse
import json
import math
import os
import sys
import time
from dataclasses import dataclass, field
from typing import Optional

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


# ── Configuration ───────────────────────────────────────────────────
JUPITER_QUOTE_URL = "https://quote-api.jup.ag/v6/quote"
SOL_MINT = "So11111111111111111111111111111111111111112"
SOL_DECIMALS = 9

# Default token: BONK (widely available, decent liquidity)
DEFAULT_TOKEN_MINT = "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"

# Trade sizes to test (in SOL)
TRADE_SIZES_SOL = [0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 25.0, 50.0]

# Request timeout and delay
REQUEST_TIMEOUT = 15.0
REQUEST_DELAY = 0.5  # seconds between requests to avoid rate limiting


# ── Data Classes ────────────────────────────────────────────────────
@dataclass
class QuoteResult:
    """Result from a single Jupiter quote query."""

    trade_size_sol: float
    input_lamports: int
    output_amount: int
    output_decimals: int
    effective_price: float  # SOL per token
    route_plan: list[dict] = field(default_factory=list)
    error: Optional[str] = None


@dataclass
class SlippagePoint:
    """A single point on the slippage curve."""

    trade_size_sol: float
    slippage_bps: float
    effective_price: float
    output_tokens: float


@dataclass
class PowerLawFit:
    """Parameters of the power-law slippage model: bps = a * size^b."""

    a: float
    b: float
    r_squared: float


# ── Jupiter Quote Functions ─────────────────────────────────────────
def fetch_jupiter_quote(
    input_mint: str,
    output_mint: str,
    amount_lamports: int,
    slippage_bps: int = 5000,
    timeout: float = REQUEST_TIMEOUT,
) -> QuoteResult:
    """Fetch a single quote from Jupiter V6 API.

    Args:
        input_mint: Input token mint address.
        output_mint: Output token mint address.
        amount_lamports: Input amount in smallest unit (lamports for SOL).
        slippage_bps: Maximum slippage tolerance in basis points.
        timeout: HTTP request timeout in seconds.

    Returns:
        QuoteResult with execution details.
    """
    params = {
        "inputMint": input_mint,
        "outputMint": output_mint,
        "amount": str(amount_lamports),
        "slippageBps": str(slippage_bps),
    }

    try:
        with httpx.Client(timeout=timeout) as client:
            resp = client.get(JUPITER_QUOTE_URL, params=params)
            resp.raise_for_status()
            data = resp.json()
    except httpx.HTTPStatusError as e:
        return QuoteResult(
            trade_size_sol=amount_lamports / 10**SOL_DECIMALS,
            input_lamports=amount_lamports,
            output_amount=0,
            output_decimals=0,
            effective_price=0.0,
            error=f"HTTP {e.response.status_code}: {e.response.text[:200]}",
        )
    except httpx.RequestError as e:
        return QuoteResult(
            trade_size_sol=amount_lamports / 10**SOL_DECIMALS,
            input_lamports=amount_lamports,
            output_amount=0,
            output_decimals=0,
            effective_price=0.0,
            error=f"Request error: {str(e)[:200]}",
        )

    out_amount = int(data.get("outAmount", 0))
    # Infer decimals from the first route or default
    out_decimals = _infer_output_decimals(data)
    trade_sol = amount_lamports / 10**SOL_DECIMALS
    tokens = out_amount / 10**out_decimals if out_decimals > 0 else out_amount
    eff_price = trade_sol / tokens if tokens > 0 else 0.0

    route_plan = data.get("routePlan", [])

    return QuoteResult(
        trade_size_sol=trade_sol,
        input_lamports=amount_lamports,
        output_amount=out_amount,
        output_decimals=out_decimals,
        effective_price=eff_price,
        route_plan=route_plan,
    )


def _infer_output_decimals(quote_data: dict) -> int:
    """Infer output token decimals from quote response data.

    Args:
        quote_data: Raw Jupiter quote response.

    Returns:
        Number of decimal places for the output token.
    """
    # Jupiter V6 doesn't always return decimals directly.
    # Use a heuristic: if outAmount is very large relative to a
    # reasonable token amount, it has many decimals.
    out_amount = int(quote_data.get("outAmount", 0))
    in_amount = int(quote_data.get("inAmount", 1))

    # For well-known tokens we could hardcode, but generically:
    # Most SPL tokens use 6 or 9 decimals.
    # Check if routePlan has decimal info.
    route_plan = quote_data.get("routePlan", [])
    for step in route_plan:
        swap_info = step.get("swapInfo", {})
        out_mint = swap_info.get("outputMint", "")
        # If the last hop outputs SOL, it's 9 decimals
        if out_mint == SOL_MINT:
            return SOL_DECIMALS

    # Default assumption for most SPL tokens
    if out_amount > 10**15:
        return 9
    if out_amount > 10**10:
        return 6
    return 6


# ── Slippage Curve Building ─────────────────────────────────────────
def build_slippage_curve_live(
    token_mint: str,
    trade_sizes: list[float],
    direction: str = "buy",
) -> list[SlippagePoint]:
    """Build slippage curve by querying Jupiter at multiple trade sizes.

    Args:
        token_mint: Token mint address to analyze.
        trade_sizes: List of trade sizes in SOL.
        direction: 'buy' (SOL -> token) or 'sell' (token -> SOL).

    Returns:
        List of SlippagePoint objects sorted by trade size.
    """
    quotes: list[QuoteResult] = []

    for size_sol in sorted(trade_sizes):
        lamports = int(size_sol * 10**SOL_DECIMALS)

        if direction == "buy":
            quote = fetch_jupiter_quote(SOL_MINT, token_mint, lamports)
        else:
            # For sell, we'd need token amount, not SOL amount.
            # Approximate by using the buy direction for curve shape.
            quote = fetch_jupiter_quote(SOL_MINT, token_mint, lamports)

        if quote.error:
            print(f"  WARNING: {size_sol} SOL — {quote.error}")
        else:
            quotes.append(quote)
            print(f"  {size_sol:>8.2f} SOL → {quote.output_amount} raw units")

        time.sleep(REQUEST_DELAY)

    if len(quotes) < 2:
        print("ERROR: Need at least 2 successful quotes to build curve.")
        return []

    # Use smallest trade as reference price (closest to spot)
    ref_price = quotes[0].effective_price
    if ref_price <= 0:
        print("ERROR: Reference price is zero. Cannot compute slippage.")
        return []

    points: list[SlippagePoint] = []
    for q in quotes:
        if q.effective_price <= 0:
            continue
        # Slippage = how much more you pay vs reference
        slippage_frac = (q.effective_price - ref_price) / ref_price
        slippage_bps = slippage_frac * 10_000
        tokens = q.output_amount / 10**q.output_decimals if q.output_decimals > 0 else float(q.output_amount)
        points.append(SlippagePoint(
            trade_size_sol=q.trade_size_sol,
            slippage_bps=max(0.0, slippage_bps),
            effective_price=q.effective_price,
            output_tokens=tokens,
        ))

    return points


def build_slippage_curve_demo(trade_sizes: list[float]) -> list[SlippagePoint]:
    """Generate synthetic slippage curve for demonstration.

    Simulates a mid-cap token with ~$200K TVL pool.
    Model: slippage_bps = 15 * trade_size^1.05

    Args:
        trade_sizes: List of trade sizes in SOL.

    Returns:
        List of SlippagePoint objects.
    """
    # Simulated pool: 500 SOL / 5,000,000 tokens
    pool_sol = 500.0
    pool_tokens = 5_000_000.0
    spot_price = pool_sol / pool_tokens  # 0.0001 SOL/token

    points: list[SlippagePoint] = []
    for size in sorted(trade_sizes):
        # Constant-product with some noise for realism
        tokens_out = pool_tokens * size / (pool_sol + size)
        eff_price = size / tokens_out if tokens_out > 0 else 0
        slippage_frac = (eff_price - spot_price) / spot_price
        slippage_bps = slippage_frac * 10_000

        # Add small random-ish perturbation (deterministic based on size)
        noise = math.sin(size * 7.3) * 0.5 + 1.0  # 0.5x to 1.5x
        slippage_bps = max(0.01, slippage_bps * (0.9 + 0.2 * (noise / 1.5)))

        points.append(SlippagePoint(
            trade_size_sol=size,
            slippage_bps=round(slippage_bps, 2),
            effective_price=eff_price,
            output_tokens=tokens_out,
        ))

    return points


# ── Power-Law Fitting ───────────────────────────────────────────────
def fit_power_law(points: list[SlippagePoint]) -> Optional[PowerLawFit]:
    """Fit slippage_bps = a * trade_size^b using log-linear regression.

    Args:
        points: Slippage data points (must have at least 2 with slippage > 0).

    Returns:
        PowerLawFit with coefficients and R-squared, or None if fitting fails.
    """
    # Filter to points with positive slippage
    valid = [(p.trade_size_sol, p.slippage_bps) for p in points if p.slippage_bps > 0 and p.trade_size_sol > 0]

    if len(valid) < 2:
        return None

    # Log-transform
    log_x = [math.log(s) for s, _ in valid]
    log_y = [math.log(b) for _, b in valid]

    n = len(valid)
    sum_x = sum(log_x)
    sum_y = sum(log_y)
    sum_xy = sum(lx * ly for lx, ly in zip(log_x, log_y))
    sum_x2 = sum(lx * lx for lx in log_x)

    denom = n * sum_x2 - sum_x * sum_x
    if abs(denom) < 1e-12:
        return None

    b = (n * sum_xy - sum_x * sum_y) / denom
    log_a = (sum_y - b * sum_x) / n
    a = math.exp(log_a)

    # R-squared
    mean_y = sum_y / n
    ss_tot = sum((ly - mean_y) ** 2 for ly in log_y)
    ss_res = sum((ly - (log_a + b * lx)) ** 2 for lx, ly in zip(log_x, log_y))
    r_sq = 1.0 - (ss_res / ss_tot) if ss_tot > 0 else 0.0

    return PowerLawFit(a=a, b=b, r_squared=r_sq)


def max_trade_size(fit: PowerLawFit, threshold_bps: float) -> float:
    """Compute maximum trade size for a given slippage threshold.

    Args:
        fit: Power-law fit parameters.
        threshold_bps: Maximum acceptable slippage in basis points.

    Returns:
        Maximum trade size in SOL.
    """
    if fit.a <= 0 or fit.b == 0:
        return 0.0
    return (threshold_bps / fit.a) ** (1.0 / fit.b)


# ── Display Functions ───────────────────────────────────────────────
def print_slippage_table(points: list[SlippagePoint]) -> None:
    """Print formatted slippage curve table.

    Args:
        points: List of slippage data points.
    """
    print("\n" + "=" * 72)
    print("SLIPPAGE CURVE")
    print("=" * 72)
    print(f"{'Trade Size (SOL)':>18} {'Slippage (bps)':>16} {'Slippage (%)':>14} {'Eff. Price':>14}")
    print("-" * 72)
    for p in points:
        pct = p.slippage_bps / 100.0
        print(f"{p.trade_size_sol:>18.4f} {p.slippage_bps:>16.2f} {pct:>13.4f}% {p.effective_price:>14.10f}")
    print("-" * 72)


def print_fit_results(fit: PowerLawFit) -> None:
    """Print power-law fit results and max trade size estimates.

    Args:
        fit: Fitted power-law model parameters.
    """
    print(f"\nPOWER-LAW FIT: slippage_bps = {fit.a:.4f} * trade_size ^ {fit.b:.4f}")
    print(f"R-squared: {fit.r_squared:.4f}")

    thresholds = [25, 50, 100, 200, 500, 1000]
    print(f"\n{'Threshold (bps)':>18} {'Max Trade (SOL)':>18}")
    print("-" * 40)
    for t in thresholds:
        max_sol = max_trade_size(fit, t)
        if max_sol > 10_000:
            print(f"{t:>18} {'> 10,000':>18}")
        else:
            print(f"{t:>18} {max_sol:>18.4f}")
    print("-" * 40)


def print_tranche_recommendation(fit: PowerLawFit, total_size: float, threshold_bps: float = 100.0) -> None:
    """Print multi-tranche execution recommendation.

    Args:
        fit: Power-law fit parameters.
        total_size: Total desired trade size in SOL.
        threshold_bps: Maximum slippage per tranche in bps.
    """
    max_sol = max_trade_size(fit, threshold_bps)
    if max_sol <= 0:
        print("\nCannot determine tranche size — fit parameters invalid.")
        return

    if total_size <= max_sol:
        single_slip = fit.a * total_size**fit.b
        print(f"\nTRANCHE ANALYSIS for {total_size:.2f} SOL:")
        print(f"  Single execution: {single_slip:.1f} bps slippage")
        print(f"  Max size for {threshold_bps:.0f} bps: {max_sol:.4f} SOL")
        print(f"  Recommendation: Execute as single trade")
        return

    n_tranches = math.ceil(total_size / max_sol)
    tranche_size = total_size / n_tranches
    per_tranche_slip = fit.a * tranche_size**fit.b
    single_slip = fit.a * total_size**fit.b

    print(f"\nTRANCHE ANALYSIS for {total_size:.2f} SOL:")
    print(f"  Single execution: {single_slip:.1f} bps slippage")
    print(f"  Max size for {threshold_bps:.0f} bps: {max_sol:.4f} SOL")
    print(f"  Recommended tranches: {n_tranches}")
    print(f"  Tranche size: {tranche_size:.4f} SOL")
    print(f"  Per-tranche slippage: {per_tranche_slip:.1f} bps")
    print(f"  Wait between tranches: 5-10 seconds (allow arb rebalancing)")


# ── Main ────────────────────────────────────────────────────────────
def main() -> None:
    """Run slippage curve analysis."""
    parser = argparse.ArgumentParser(description="Build empirical slippage curves")
    parser.add_argument("--demo", action="store_true", help="Use synthetic data instead of live API")
    parser.add_argument("--token", type=str, default=None, help="Token mint address")
    parser.add_argument("--total-size", type=float, default=10.0, help="Total trade size for tranche analysis (SOL)")
    parser.add_argument("--threshold", type=float, default=100.0, help="Slippage threshold for tranche analysis (bps)")
    args = parser.parse_args()

    token_mint = args.token or os.getenv("TOKEN_MINT", DEFAULT_TOKEN_MINT)

    if args.demo:
        print("DEMO MODE — using synthetic slippage curve")
        print("Simulated pool: 500 SOL / 5,000,000 tokens (~$200K TVL)")
        points = build_slippage_curve_demo(TRADE_SIZES_SOL)
    else:
        print(f"Querying Jupiter for token: {token_mint}")
        print(f"Testing {len(TRADE_SIZES_SOL)} trade sizes...")
        points = build_slippage_curve_live(token_mint, TRADE_SIZES_SOL, direction="buy")

    if not points:
        print("No data points collected. Exiting.")
        sys.exit(1)

    print_slippage_table(points)

    fit = fit_power_law(points)
    if fit:
        print_fit_results(fit)
        print_tranche_recommendation(fit, args.total_size, args.threshold)
    else:
        print("\nCould not fit power-law model (insufficient valid data points).")

    print("\nNOTE: This analysis is for informational purposes only.")
    print("Actual execution slippage may differ from quotes due to")
    print("price movement, MEV, and changing liquidity conditions.")


if __name__ == "__main__":
    main()