hypercall_vol_oracle/

polymarket_oracle.rs

//! Polymarket-derived Volatility Oracle for pre-IPO assets (e.g., SPCX).
//!
//! Polls Polymarket's Gamma API for digital-option-style probability markets
//! (e.g., "SpaceX IPO closing market cap above $2T?"), converts market cap
//! thresholds to per-share strike prices, and inverts Black-Scholes digital
//! call pricing to extract an implied volatility smile.

use std::collections::HashMap;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, RwLock};
use std::time::Duration;

use anyhow::{Context, Result};
use chrono::Utc;
use metrics::counter;
use reqwest::Client;
use serde::Deserialize;
use tokio::task::JoinHandle;
use tracing::{debug, error, info, warn};

use super::risk_oracle::{
    RiskVolOracle, VolLookupError, VolOracleStatus, VolProviderKind, VolSurfaceSnapshot,
};
use super::vol_surface_cache::VolatilitySurface;

const GAMMA_API_BASE: &str = "https://gamma-api.polymarket.com";

#[derive(Debug, Clone)]
pub struct PolymarketVolOracleConfig {
    pub event_slug: String,
    /// Fully diluted shares outstanding for market-cap-to-price conversion.
    pub shares_outstanding: f64,
    /// Assumed time-to-expiry (days) for the Polymarket event when inverting
    /// digital call probabilities into annualized implied volatility.
    pub reference_tte_days: f64,
    pub poll_interval: Duration,
    pub staleness_threshold: Duration,
    pub symbols: Vec<String>,
}

#[derive(Debug, Default)]
struct PolymarketSurfaceState {
    surfaces: HashMap<String, VolatilitySurface>,
    connected: HashMap<String, bool>,
    last_update_ts_ms: HashMap<String, i64>,
    last_error: HashMap<String, String>,
    spot_prices: HashMap<String, f64>,
}

// --- Gamma API response types ---

#[derive(Debug, Deserialize)]
struct GammaEvent {
    markets: Option<Vec<GammaMarket>>,
}

#[derive(Debug, Deserialize)]
#[allow(dead_code)]
struct GammaMarket {
    question: Option<String>,
    #[serde(rename = "outcomePrices")]
    outcome_prices: Option<String>,
}

pub struct PolymarketVolOracle {
    client: Client,
    config: PolymarketVolOracleConfig,
    state: Arc<RwLock<PolymarketSurfaceState>>,
    messages_received: AtomicU64,
}

impl PolymarketVolOracle {
    pub fn new(config: PolymarketVolOracleConfig) -> Self {
        Self {
            client: Client::builder()
                .timeout(Duration::from_secs(15))
                .build()
                .expect("failed to build HTTP client"),
            config,
            state: Arc::new(RwLock::new(PolymarketSurfaceState::default())),
            messages_received: AtomicU64::new(0),
        }
    }

    pub fn start_polling(self: Arc<Self>) -> JoinHandle<()> {
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(self.config.poll_interval);
            loop {
                interval.tick().await;
                if let Err(err) = self.refresh_all().await {
                    error!("Polymarket vol oracle refresh failed: {err:#}");
                }
            }
        })
    }

    async fn refresh_all(&self) -> Result<()> {
        match self.fetch_surface().await {
            Ok((surface, spot)) => {
                let now_ms = Utc::now().timestamp_millis();
                let point_count = surface.len();
                {
                    let mut state = self
                        .state
                        .write()
                        .expect("polymarket vol oracle state poisoned");
                    for symbol in &self.config.symbols {
                        state.surfaces.insert(symbol.clone(), surface.clone());
                        state.connected.insert(symbol.clone(), true);
                        state.last_update_ts_ms.insert(symbol.clone(), now_ms);
                        state.last_error.remove(symbol);
                        state.spot_prices.insert(symbol.clone(), spot);
                    }
                }
                self.messages_received.fetch_add(1, Ordering::Relaxed);
                for symbol in &self.config.symbols {
                    counter!(
                        "ht_vol_oracle_messages_received_total",
                        "provider" => VolProviderKind::Polymarket.as_str(),
                        "underlying" => symbol.clone()
                    )
                    .increment(1);
                }
                info!(
                    "Updated Polymarket vol surface with {} points (spot ${:.2})",
                    point_count, spot
                );
            }
            Err(err) => {
                let message = err.to_string();
                let mut state = self
                    .state
                    .write()
                    .expect("polymarket vol oracle state poisoned");
                for symbol in &self.config.symbols {
                    state.connected.insert(symbol.clone(), false);
                    state.last_error.insert(symbol.clone(), message.clone());
                    if state.surfaces.contains_key(symbol) {
                        warn!(
                            "Polymarket vol surface refresh failed for {} (keeping last good data): {}",
                            symbol, message
                        );
                    } else {
                        warn!(
                            "Polymarket vol surface refresh failed for {}: {}",
                            symbol, message
                        );
                    }
                }
            }
        }
        Ok(())
    }

    async fn fetch_surface(&self) -> Result<(VolatilitySurface, f64)> {
        let url = format!("{}/events?slug={}", GAMMA_API_BASE, self.config.event_slug);
        let events: Vec<GammaEvent> = self
            .client
            .get(&url)
            .send()
            .await
            .with_context(|| {
                format!(
                    "Failed to fetch Polymarket event {}",
                    self.config.event_slug
                )
            })?
            .error_for_status()
            .with_context(|| "Polymarket Gamma API returned non-success")?
            .json()
            .await
            .with_context(|| "Failed to decode Polymarket event response")?;

        let event = events
            .into_iter()
            .next()
            .context("Polymarket returned no events for slug")?;

        let markets = event.markets.context("Event has no markets")?;
        let mut strike_probs: Vec<(f64, f64)> = Vec::new();

        for market in &markets {
            let question = match &market.question {
                Some(q) => q,
                None => continue,
            };

            let cap_dollars = match parse_market_cap_from_question(question) {
                Some(cap) => cap,
                None => {
                    debug!("Skipping unparseable Polymarket question: {}", question);
                    continue;
                }
            };

            let strike = cap_dollars / self.config.shares_outstanding;

            let prob = match &market.outcome_prices {
                Some(prices_str) => match parse_yes_probability(prices_str) {
                    Some(p) => p,
                    None => continue,
                },
                None => continue,
            };

            if prob > 0.02 && prob < 0.98 {
                strike_probs.push((strike, prob));
            }
        }

        if strike_probs.len() < 3 {
            anyhow::bail!(
                "Polymarket returned only {} usable strike-probability pairs (need >= 3)",
                strike_probs.len()
            );
        }

        strike_probs.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());

        // Estimate spot from the strike where P(above) ≈ 0.50
        let spot = estimate_spot_from_cdf(&strike_probs);

        let tte_years = self.config.reference_tte_days / 365.25;

        // Use $1 strike precision for SPCX-range prices ($100-$400)
        let mut surface = VolatilitySurface::with_precision(1.0);

        // Generate expiry timestamps: daily out to 30 days, then weekly to 90 days
        let now_ts = Utc::now().timestamp();
        let day_secs: i64 = 86400;
        let mut expiry_timestamps = Vec::new();
        for d in 1..=7 {
            expiry_timestamps.push(now_ts + d * day_secs);
        }
        for w in 2..=12 {
            expiry_timestamps.push(now_ts + w * 7 * day_secs);
        }

        let mut total_inserted = 0_u32;
        for (strike, prob) in &strike_probs {
            let iv = match solve_digital_iv(spot, *strike, tte_years, *prob) {
                Some(v) if v > 0.05 && v < 5.0 => v,
                _ => {
                    debug!(
                        "Skipping Polymarket strike {:.1} prob {:.3}: IV solve failed",
                        strike, prob
                    );
                    continue;
                }
            };

            for &expiry_ts in &expiry_timestamps {
                surface.insert(*strike, expiry_ts, iv);
                total_inserted += 1;
            }

            let moneyness = (*strike / spot - 1.0).abs();
            if moneyness < 0.05 {
                for &expiry_ts in &expiry_timestamps {
                    surface.set_atm_vol(expiry_ts, iv);
                }
            }
        }

        if total_inserted == 0 {
            anyhow::bail!("Failed to extract any IVs from Polymarket data");
        }

        if spot > 0.0 {
            let clamps = surface.sanitize_arb_free(spot, 0.0);
            if clamps > 0 {
                counter!(
                    "ht_vol_surface_arb_clamps_total",
                    "provider" => VolProviderKind::Polymarket.as_str(),
                    "underlying" => "SPCX".to_string()
                )
                .increment(clamps as u64);
                info!(
                    clamps,
                    "Clamped non-arb-free vol surface points (polymarket)"
                );
            }
        }

        Ok((surface, spot))
    }

    fn status_for(&self, symbol: &str) -> VolOracleStatus {
        let state = self
            .state
            .read()
            .expect("polymarket vol oracle state poisoned");
        let last_update_ts_ms = state.last_update_ts_ms.get(symbol).copied();
        let staleness_seconds = last_update_ts_ms
            .map(|ts| ((Utc::now().timestamp_millis() - ts) as f64 / 1000.0).max(0.0));
        let ready = staleness_seconds
            .map(|age| age <= self.config.staleness_threshold.as_secs_f64())
            .unwrap_or(false);
        let surface_points = state
            .surfaces
            .get(symbol)
            .map(VolatilitySurface::len)
            .unwrap_or(0);

        VolOracleStatus {
            underlying: symbol.to_string(),
            provider: VolProviderKind::Polymarket,
            route_facing: true,
            connected: state.connected.get(symbol).copied().unwrap_or(false),
            ready,
            last_update_ts_ms,
            staleness_seconds,
            staleness_threshold_seconds: Some(self.config.staleness_threshold.as_secs_f64()),
            surface_points,
            messages_received: self.messages_received.load(Ordering::Relaxed),
            last_error: state.last_error.get(symbol).cloned(),
        }
    }
}

impl RiskVolOracle for PolymarketVolOracle {
    fn get_iv(&self, underlying: &str, strike: f64, expiry_ts: i64) -> Result<f64, VolLookupError> {
        let state = self
            .state
            .read()
            .expect("polymarket vol oracle state poisoned");
        let has_surface = state.surfaces.contains_key(underlying);

        let connected = state.connected.get(underlying).copied().unwrap_or(false);
        if !connected && !has_surface {
            return Err(VolLookupError::UnhealthyProvider {
                underlying: underlying.to_string(),
                provider: VolProviderKind::Polymarket,
                reason: state
                    .last_error
                    .get(underlying)
                    .cloned()
                    .unwrap_or_else(|| "not connected".to_string()),
            });
        }

        let last_update_ts_ms = state.last_update_ts_ms.get(underlying).copied();
        let staleness_seconds = last_update_ts_ms
            .map(|ts| ((Utc::now().timestamp_millis() - ts) as f64 / 1000.0).max(0.0));
        let ready = staleness_seconds
            .map(|age| age <= self.config.staleness_threshold.as_secs_f64())
            .unwrap_or(false);

        if !ready {
            return Err(VolLookupError::StaleSurface {
                underlying: underlying.to_string(),
                provider: VolProviderKind::Polymarket,
                staleness_seconds: staleness_seconds.unwrap_or(f64::INFINITY),
                threshold_seconds: self.config.staleness_threshold.as_secs_f64(),
            });
        }

        let iv = state
            .surfaces
            .get(underlying)
            .and_then(|surface| surface.get_interpolated(strike, expiry_ts))
            .ok_or_else(|| VolLookupError::MissingSurface {
                underlying: underlying.to_string(),
                provider: VolProviderKind::Polymarket,
                strike,
                expiry_ts,
            })?;

        debug!(
            underlying,
            strike,
            expiry_ts,
            iv,
            provider = VolProviderKind::Polymarket.as_str(),
            "Backend vol oracle value used"
        );

        Ok(iv)
    }

    fn statuses(&self) -> Vec<VolOracleStatus> {
        self.config
            .symbols
            .iter()
            .map(|symbol| self.status_for(symbol))
            .collect()
    }

    fn get_surface_snapshot(&self, underlying: &str) -> Option<VolSurfaceSnapshot> {
        let state = self
            .state
            .read()
            .expect("polymarket vol oracle state poisoned");
        let surface = state.surfaces.get(underlying)?;
        Some(VolSurfaceSnapshot {
            underlying: underlying.to_string(),
            last_update_ts_ms: state.last_update_ts_ms.get(underlying).copied(),
            expiries: surface.expiries().iter().copied().collect(),
            strike_points: surface.export_all_points(),
            delta_curves: surface.export_delta_curves(),
            atm_vols: surface.export_atm_vols(),
            spot_price: state.spot_prices.get(underlying).copied(),
        })
    }

    fn supports_surface_snapshots(&self) -> bool {
        true
    }
}

// --- Parsing helpers ---

/// Parse a market cap dollar amount from a Polymarket question.
/// E.g., "SpaceX IPO closing market cap above $2T?" → 2_000_000_000_000.0
fn parse_market_cap_from_question(question: &str) -> Option<f64> {
    let dollar_pos = question.find('$')?;
    let after_dollar = &question[dollar_pos + 1..];
    let end = after_dollar
        .find(|c: char| !c.is_ascii_digit() && c != '.' && c != 'T' && c != 'B' && c != 'M')
        .unwrap_or(after_dollar.len());
    let token = &after_dollar[..end];

    if let Some(num_str) = token.strip_suffix('T') {
        num_str.parse::<f64>().ok().map(|n| n * 1e12)
    } else if let Some(num_str) = token.strip_suffix('B') {
        num_str.parse::<f64>().ok().map(|n| n * 1e9)
    } else if let Some(num_str) = token.strip_suffix('M') {
        num_str.parse::<f64>().ok().map(|n| n * 1e6)
    } else {
        token.parse::<f64>().ok()
    }
}

/// Parse the "Yes" probability from a Polymarket outcomePrices JSON string.
/// The field is double-encoded: `"[\"0.705\",\"0.295\"]"`.
fn parse_yes_probability(prices_json: &str) -> Option<f64> {
    let prices: Vec<String> = serde_json::from_str(prices_json).ok()?;
    prices.first()?.parse::<f64>().ok()
}

/// Estimate spot price from the CDF by finding where P(above) ≈ 0.50.
fn estimate_spot_from_cdf(strike_probs: &[(f64, f64)]) -> f64 {
    let mut best_strike = strike_probs[0].0;
    let mut best_dist = f64::MAX;
    for &(strike, prob) in strike_probs {
        let dist = (prob - 0.50).abs();
        if dist < best_dist {
            best_dist = dist;
            best_strike = strike;
        }
    }

    // Linear interpolation between the two bracketing strikes
    for window in strike_probs.windows(2) {
        let (k1, p1) = window[0];
        let (k2, p2) = window[1];
        if (p1 >= 0.50 && p2 <= 0.50) || (p1 <= 0.50 && p2 >= 0.50) {
            let denom = p2 - p1;
            if denom.abs() < 1e-12 {
                return best_strike;
            }
            let t = (0.50 - p1) / denom;
            return k1 + t * (k2 - k1);
        }
    }

    best_strike
}

// --- Black-Scholes digital call inversion ---

fn norm_cdf(x: f64) -> f64 {
    0.5 * (1.0 + libm::erf(x / std::f64::consts::SQRT_2))
}

/// Price of a digital (binary) call: pays $1 if S_T > K.
fn bs_digital_call_price(spot: f64, strike: f64, sigma: f64, tte_years: f64) -> f64 {
    let d2 = (libm::log(spot / strike) - 0.5 * sigma * sigma * tte_years)
        / (sigma * libm::sqrt(tte_years));
    norm_cdf(d2)
}

/// Solve for the Black-Scholes implied volatility of a digital call option
/// given its market probability. Returns None if the inversion fails.
fn solve_digital_iv(spot: f64, strike: f64, tte_years: f64, target_prob: f64) -> Option<f64> {
    if tte_years <= 0.0 || spot <= 0.0 || strike <= 0.0 {
        return None;
    }
    if target_prob <= 0.01 || target_prob >= 0.99 {
        return None;
    }

    let mut lo = 0.05_f64;
    let mut hi = 4.0_f64;

    // For OTM digital calls, price first increases then decreases with vol.
    // The peak occurs at sigma* = sqrt(2 * ln(K/S) / T). If the target is
    // above the peak price, no BS solution exists.
    if strike > spot {
        let m = libm::log(strike / spot);
        let sigma_peak = libm::sqrt(2.0 * m / tte_years);
        let peak_price = bs_digital_call_price(spot, strike, sigma_peak, tte_years);
        if target_prob > peak_price + 0.001 {
            return None;
        }
        hi = hi.min(sigma_peak);
    }

    let lo_price = bs_digital_call_price(spot, strike, lo, tte_years);
    let hi_price = bs_digital_call_price(spot, strike, hi, tte_years);

    let increasing = hi_price > lo_price;
    if increasing {
        if target_prob < lo_price || target_prob > hi_price {
            return None;
        }
    } else if target_prob > lo_price || target_prob < hi_price {
        return None;
    }

    for _ in 0..100 {
        let mid = 0.5 * (lo + hi);
        let price = bs_digital_call_price(spot, strike, mid, tte_years);
        if (price - target_prob).abs() < 1e-6 {
            return Some(mid);
        }
        if (price > target_prob) == increasing {
            hi = mid;
        } else {
            lo = mid;
        }
    }

    Some(0.5 * (lo + hi))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_market_cap() {
        assert_eq!(
            parse_market_cap_from_question("SpaceX IPO closing market cap above $2T?"),
            Some(2e12)
        );
        assert_eq!(
            parse_market_cap_from_question("SpaceX IPO closing market cap above $1.5T?"),
            Some(1.5e12)
        );
        assert_eq!(
            parse_market_cap_from_question("SpaceX IPO closing market cap above $3.2T?"),
            Some(3.2e12)
        );
        assert_eq!(parse_market_cap_from_question("No IPO by 2028"), None);
    }

    #[test]
    fn test_parse_yes_probability() {
        assert_eq!(parse_yes_probability(r#"["0.705","0.295"]"#), Some(0.705));
        assert_eq!(parse_yes_probability(r#"["0.984","0.016"]"#), Some(0.984));
    }

    #[test]
    fn test_norm_cdf() {
        assert!((norm_cdf(0.0) - 0.5).abs() < 1e-10);
        assert!((norm_cdf(1.0) - 0.8413).abs() < 1e-3);
        assert!((norm_cdf(-1.0) - 0.1587).abs() < 1e-3);
    }

    #[test]
    fn test_bs_digital_roundtrip() {
        let spot = 200.0;
        let strike = 168.5;
        let sigma = 0.65;
        let tte = 30.0 / 365.25;

        let price = bs_digital_call_price(spot, strike, sigma, tte);
        assert!(
            price > 0.5 && price < 1.0,
            "ITM digital call should be > 0.5"
        );

        let recovered = solve_digital_iv(spot, strike, tte, price).unwrap();
        assert!(
            (recovered - sigma).abs() < 0.01,
            "Roundtrip IV should match: expected {sigma}, got {recovered}"
        );
    }

    #[test]
    fn test_solve_iv_otm() {
        let spot = 200.0;
        let strike = 250.0;
        let sigma = 0.80;
        let tte = 30.0 / 365.25;

        let price = bs_digital_call_price(spot, strike, sigma, tte);
        assert!(
            price > 0.0 && price < 0.5,
            "OTM digital call should be < 0.5"
        );

        let recovered = solve_digital_iv(spot, strike, tte, price).unwrap();
        assert!(
            (recovered - sigma).abs() < 0.02,
            "Roundtrip IV: expected {sigma}, got {recovered}"
        );
    }

    #[test]
    fn test_estimate_spot() {
        let data = vec![
            (150.0, 0.85),
            (170.0, 0.75),
            (200.0, 0.50),
            (230.0, 0.25),
            (260.0, 0.10),
        ];
        let spot = estimate_spot_from_cdf(&data);
        assert!(
            (spot - 200.0).abs() < 1.0,
            "Spot should be near 200, got {spot}"
        );
    }

    #[test]
    fn test_oracle_not_ready_before_poll() {
        let config = PolymarketVolOracleConfig {
            event_slug: "test".to_string(),
            shares_outstanding: 11.87e9,
            reference_tte_days: 30.0,
            poll_interval: Duration::from_secs(60),
            staleness_threshold: Duration::from_secs(300),
            symbols: vec!["SPCX".to_string()],
        };
        let oracle = PolymarketVolOracle::new(config);
        let result = oracle.get_iv("SPCX", 200.0, 1800000000);
        assert!(matches!(
            result,
            Err(VolLookupError::UnhealthyProvider { .. })
        ));
    }
}