hypercall_margin/portfolio/

span.rs

use crate::black_scholes::black_scholes_with_moments;
use crate::constants::MM_TO_IM_RATIO;
use crate::error::MarginError;
use crate::portfolio::config::PortfolioMarginScenario;
use crate::portfolio::contingency::calculate_contingency_margin_at;
use crate::portfolio::equity::{
    calculate_net_option_mtm, calculate_net_option_upnl, calculate_net_perp_upnl,
};
use crate::portfolio::evaluator::{calculate_scanning_risk, calculate_scenario_pnl};
use crate::portfolio::snapshot::{
    account_cash_decimal, PortfolioMarginMarketState, PortfolioMarginOptionKey,
    PortfolioMarginPerpExposure, PortfolioMarginSnapshot, PortfolioMarginUnderlyingSnapshot,
};
use crate::types::{Account, MarginDetails, OptionType};
use hypercall_types::WalletAddress;
use rust_decimal::prelude::ToPrimitive;
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};

fn f64_to_decimal(value: f64, field: &str, wallet: WalletAddress) -> Decimal {
    Decimal::from_f64_retain(value).unwrap_or_else(|| {
        panic!(
            "STATE_CORRUPTION: Failed to convert {} {} to Decimal for account {}. Restart required.",
            field, value, wallet
        )
    })
}

#[derive(Debug, Clone, Copy)]
struct MarginComputation {
    scanning_risk: f64,
    option_floor: f64,
    gamma_overlay: f64,
    net_option_mtm: f64,
    net_option_upnl: f64,
    net_perp_upnl: f64,
}

fn assemble_margin_details(
    snapshot: &PortfolioMarginSnapshot,
    margin: MarginComputation,
) -> MarginDetails {
    let initial_margin_required =
        margin.scanning_risk.max(margin.option_floor) + margin.gamma_overlay;
    let maintenance_margin_required = initial_margin_required * MM_TO_IM_RATIO;
    let cash_balance = snapshot.cash_balance.to_f64().unwrap_or_else(|| {
        panic!(
            "STATE_CORRUPTION: cash_balance {:?} for {} is not representable as f64",
            snapshot.cash_balance, snapshot.wallet
        )
    });
    let equity = cash_balance + margin.net_option_upnl + margin.net_perp_upnl;

    MarginDetails {
        account_id: snapshot.wallet,
        scanning_risk: f64_to_decimal(margin.scanning_risk, "scanning_risk", snapshot.wallet),
        option_floor: f64_to_decimal(margin.option_floor, "option_floor", snapshot.wallet),
        gamma_overlay: f64_to_decimal(margin.gamma_overlay, "gamma_overlay", snapshot.wallet),
        net_option_value: f64_to_decimal(margin.net_option_mtm, "net_option_mtm", snapshot.wallet),
        equity: f64_to_decimal(equity, "equity", snapshot.wallet),
        initial_margin_required: f64_to_decimal(
            initial_margin_required,
            "initial_margin_required",
            snapshot.wallet,
        ),
        maintenance_margin_required: f64_to_decimal(
            maintenance_margin_required,
            "maintenance_margin_required",
            snapshot.wallet,
        ),
    }
}

/// Compute SPAN margin from a fully-populated snapshot and market state.
///
/// This is the primary entry point for portfolio margin calculation. The caller
/// must populate all option IVs in `market_state` before calling -- this crate
/// has no IO and cannot fetch vol data.
///
/// The caller is responsible for populating option IVs in the market state
/// before calling this function (the margin crate has no IO).
pub fn compute_span_margin_at(
    snapshot: &PortfolioMarginSnapshot,
    market_state: &PortfolioMarginMarketState,
    now_ts: i64,
) -> Result<MarginDetails, MarginError> {
    let scenarios = generate_scenarios(market_state);
    let scanning_risk = calculate_scanning_risk(snapshot, market_state, &scenarios)?;
    let contingency = calculate_contingency_margin_at(snapshot, &market_state.config, now_ts)?;
    let net_option_mtm = calculate_net_option_mtm(snapshot, market_state)?;
    let net_option_upnl = calculate_net_option_upnl(snapshot, market_state)?;
    let net_perp_upnl = calculate_net_perp_upnl(snapshot, market_state)?;

    let margin = MarginComputation {
        scanning_risk,
        option_floor: contingency.option_floor,
        gamma_overlay: contingency.gamma_overlay,
        net_option_mtm,
        net_option_upnl,
        net_perp_upnl,
    };

    Ok(assemble_margin_details(snapshot, margin))
}

/// Scenario PnL entry for risk grid introspection.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ScenarioPnl {
    pub scenario_id: String,
    pub scenario: PortfolioMarginScenario,
    pub total_pnl: f64,
}

/// P&L for a single instrument under all scenarios.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InstrumentRiskRow {
    pub symbol: String,
    pub underlying: String,
    pub amount: f64,
    pub base_amount: f64,
    pub current_value: f64,
    pub scenario_pnls: Vec<f64>,
}

/// Extended risk grid with per-instrument breakdown.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExtendedRiskGrid {
    pub scenarios: Vec<PortfolioMarginScenario>,
    pub instruments: Vec<InstrumentRiskRow>,
    pub total_pnls: Vec<f64>,
    pub worst_scenario_index: usize,
    pub worst_scenario_pnl: f64,
}

/// Compute per-scenario total PnL for a normalized portfolio margin snapshot.
///
/// The snapshot is treated as an immutable weighted view of executed positions
/// plus hypothetical open-order exposure. Missing or non-representable market
/// inputs are returned as `MarginError`.
pub fn compute_risk_grid_from_snapshot(
    snapshot: &PortfolioMarginSnapshot,
    market_state: &PortfolioMarginMarketState,
) -> Result<Vec<ScenarioPnl>, MarginError> {
    let scenarios = generate_scenarios(market_state);
    let mut output = Vec::with_capacity(scenarios.len());
    for scenario in &scenarios {
        output.push(ScenarioPnl {
            scenario_id: scenario.id.clone(),
            scenario: scenario.clone(),
            total_pnl: calculate_scenario_pnl(snapshot, market_state, scenario)?,
        });
    }
    Ok(output)
}

/// Compute per-instrument and aggregate scenario PnL rows for a snapshot.
///
/// Uses `PortfolioMarginMarketState` scenarios and underlying market inputs.
/// Returns `MarginError` for missing option state or decimal values that cannot
/// be represented for grid math. Empty snapshots return an empty instrument set
/// with zero aggregate PnL across the configured scenarios.
pub fn compute_extended_risk_grid_from_snapshot(
    snapshot: &PortfolioMarginSnapshot,
    market_state: &PortfolioMarginMarketState,
) -> Result<ExtendedRiskGrid, MarginError> {
    let scenarios = generate_scenarios(market_state);
    let mut instruments = Vec::new();
    let mut total_pnls = vec![0.0; scenarios.len()];

    for underlying in &snapshot.underlyings {
        let state = market_state
            .underlyings
            .get(&underlying.underlying)
            .expect("market state missing underlying after prior validation");
        let grid = market_state
            .config
            .grid_for_underlying(&underlying.underlying);

        for option in underlying
            .executed_options
            .iter()
            .chain(underlying.hypothetical_open_order_options.iter())
        {
            let option_state = state
                .option_inputs
                .get(&option.key)
                .expect("option market state missing after prior resolution");
            let strike = option
                .key
                .strike
                .to_f64()
                .ok_or_else(|| MarginError::InvalidStrike {
                    underlying: underlying.underlying.clone(),
                    strike: option.key.strike,
                })?;
            let expiry = option.expiry_years.to_f64().ok_or_else(|| {
                MarginError::NonRepresentableDecimal {
                    field: "expiry_years",
                    underlying: underlying.underlying.clone(),
                }
            })?;
            let quantity =
                option
                    .quantity
                    .to_f64()
                    .ok_or_else(|| MarginError::NonRepresentableDecimal {
                        field: "quantity",
                        underlying: underlying.underlying.clone(),
                    })?;
            let current_value = quantity
                * black_scholes_with_moments(
                    &option.key.option_type,
                    state.spot_price,
                    strike,
                    expiry,
                    market_state.config.risk_free_rate,
                    option_state.implied_volatility,
                    grid.base_skew,
                    grid.base_excess_kurtosis,
                );
            let mut scenario_pnls = Vec::with_capacity(scenarios.len());
            for (index, scenario) in scenarios.iter().enumerate() {
                let pnl = calculate_scenario_pnl(
                    &single_option_snapshot(snapshot.wallet, underlying, option.clone()),
                    market_state,
                    scenario,
                )?;
                scenario_pnls.push(pnl);
                total_pnls[index] += pnl;
            }
            instruments.push(InstrumentRiskRow {
                symbol: format_option_symbol(&option.key),
                underlying: underlying.underlying.clone(),
                amount: quantity,
                base_amount: quantity,
                current_value,
                scenario_pnls,
            });
        }

        let mut net_perp_quantity = 0.0;
        let mut perp_current_total = 0.0;
        let mut has_perp_current_value = false;
        for perp in underlying
            .executed_perps
            .iter()
            .chain(underlying.hypothetical_open_order_perps.iter())
        {
            net_perp_quantity +=
                perp.quantity
                    .to_f64()
                    .ok_or_else(|| MarginError::NonRepresentableDecimal {
                        field: "perp_quantity",
                        underlying: underlying.underlying.clone(),
                    })?;
            let current_value = perp_current_value(perp, state.spot_price, &underlying.underlying)?;
            has_perp_current_value |= current_value != 0.0;
            perp_current_total += current_value;
        }
        if net_perp_quantity.abs() > grid.delta_threshold || has_perp_current_value {
            let mut scenario_pnls = Vec::with_capacity(scenarios.len());
            for (index, scenario) in scenarios.iter().enumerate() {
                let adjusted_spot = state.spot_price * (1.0 + scenario.spot_shock_pct);
                let pnl = net_perp_quantity * (adjusted_spot - state.spot_price);
                scenario_pnls.push(pnl);
                total_pnls[index] += pnl;
            }
            instruments.push(InstrumentRiskRow {
                symbol: format!("{}-PERP", underlying.underlying),
                underlying: underlying.underlying.clone(),
                amount: net_perp_quantity,
                base_amount: net_perp_quantity,
                current_value: perp_current_total,
                scenario_pnls,
            });
        }
    }

    let (worst_scenario_index, worst_scenario_pnl) = total_pnls
        .iter()
        .enumerate()
        .min_by(|(left_index, left), (right_index, right)| {
            let left_weighted = **left * scenarios[*left_index].pnl_weight;
            let right_weighted = **right * scenarios[*right_index].pnl_weight;
            left_weighted.partial_cmp(&right_weighted).unwrap_or_else(|| {
                panic!(
                    "STATE_CORRUPTION: non-finite weighted scenario pnl in extended risk grid: left={}, right={}",
                    left_weighted, right_weighted
                )
            })
        })
        .map(|(index, pnl)| (index, *pnl * scenarios[index].pnl_weight))
        .unwrap_or((0, 0.0));

    Ok(ExtendedRiskGrid {
        scenarios,
        instruments,
        total_pnls,
        worst_scenario_index,
        worst_scenario_pnl,
    })
}

/// Detect whether a legacy account has portfolio exposure requiring PM math.
///
/// Options always count as live exposure. Perps count when account delta exceeds
/// `delta_threshold` or when residual perp UPNL is non-zero, so flat but
/// unsettled accounts are not treated as empty.
pub fn has_portfolio_positions(account: &Account, delta_threshold: f64) -> bool {
    for position in account.portfolio.values() {
        if !position.options.is_empty() {
            return true;
        }

        let delta_f64 = position.delta.to_f64().unwrap_or_else(|| {
            panic!(
                "STATE_CORRUPTION: account delta {:?} for {} is not representable as f64",
                position.delta, account.id
            )
        });
        if delta_f64.abs() > delta_threshold {
            return true;
        }
        if position.perp_unrealized_pnl != Decimal::ZERO {
            return true;
        }
    }
    false
}

/// Build zero-margin details for a legacy account with no portfolio exposure.
///
/// Cash is still carried into equity, while scanning risk, contingency margin,
/// IM, and MM are all zero. Use only after `has_portfolio_positions` has
/// determined the account has no PM-relevant positions.
pub fn empty_portfolio_margin_details(account: &Account) -> MarginDetails {
    MarginDetails {
        account_id: account.id,
        scanning_risk: Decimal::ZERO,
        option_floor: Decimal::ZERO,
        gamma_overlay: Decimal::ZERO,
        net_option_value: Decimal::ZERO,
        equity: account_cash_decimal(account),
        initial_margin_required: Decimal::ZERO,
        maintenance_margin_required: Decimal::ZERO,
    }
}

pub fn generate_scenarios(
    market_state: &PortfolioMarginMarketState,
) -> Vec<PortfolioMarginScenario> {
    market_state.config.base_grid.scenarios.clone()
}

fn single_option_snapshot(
    wallet: WalletAddress,
    underlying: &PortfolioMarginUnderlyingSnapshot,
    option: crate::portfolio::snapshot::PortfolioMarginOptionExposure,
) -> PortfolioMarginSnapshot {
    PortfolioMarginSnapshot {
        wallet,
        cash_balance: Decimal::ZERO,
        underlyings: vec![PortfolioMarginUnderlyingSnapshot {
            underlying: underlying.underlying.clone(),
            spot_price: underlying.spot_price,
            executed_options: vec![option],
            hypothetical_open_order_options: Vec::new(),
            executed_perps: Vec::new(),
            hypothetical_open_order_perps: Vec::new(),
        }],
    }
}

fn perp_current_value(
    perp: &PortfolioMarginPerpExposure,
    spot_price: f64,
    underlying: &str,
) -> Result<f64, MarginError> {
    if perp.unrealized_pnl != Decimal::ZERO {
        return perp
            .unrealized_pnl
            .to_f64()
            .ok_or_else(|| MarginError::NonRepresentableDecimal {
                field: "perp_unrealized_pnl",
                underlying: underlying.to_string(),
            });
    }

    match perp.entry_price {
        Some(entry_price) => {
            let quantity =
                perp.quantity
                    .to_f64()
                    .ok_or_else(|| MarginError::NonRepresentableDecimal {
                        field: "perp_quantity",
                        underlying: underlying.to_string(),
                    })?;
            let entry_price =
                entry_price
                    .to_f64()
                    .ok_or_else(|| MarginError::NonRepresentableDecimal {
                        field: "perp_entry_price",
                        underlying: underlying.to_string(),
                    })?;
            Ok(quantity * (spot_price - entry_price))
        }
        None => Ok(0.0),
    }
}

fn format_option_symbol(key: &PortfolioMarginOptionKey) -> String {
    format!(
        "{}-{}-{}-{}",
        key.underlying,
        format_expiry_from_ts(key.expiry_ts),
        key.strike.normalize(),
        match key.option_type {
            OptionType::Call => "C",
            OptionType::Put => "P",
        }
    )
}

fn format_expiry_from_ts(expiry_ts: i64) -> String {
    let days = expiry_ts.div_euclid(86_400);
    let (year, month, day) = civil_from_days(days);
    format!("{year:04}{month:02}{day:02}")
}

fn civil_from_days(days_since_unix_epoch: i64) -> (i64, i64, i64) {
    let z = days_since_unix_epoch + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 }.div_euclid(146_097);
    let day_of_era = z - era * 146_097;
    let year_of_era =
        (day_of_era - day_of_era / 1_460 + day_of_era / 36_524 - day_of_era / 146_096) / 365;
    let year = year_of_era + era * 400;
    let day_of_year = day_of_era - (365 * year_of_era + year_of_era / 4 - year_of_era / 100);
    let month_param = (5 * day_of_year + 2) / 153;
    let day = day_of_year - (153 * month_param + 2) / 5 + 1;
    let month = month_param + if month_param < 10 { 3 } else { -9 };
    let year = year + if month <= 2 { 1 } else { 0 };

    (year, month, day)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::portfolio::{
        PortfolioMarginConfig, PortfolioMarginMarketState, PortfolioMarginUnderlyingMarketState,
    };
    use hypercall_types::wallet_address::test_wallet;
    use rust_decimal_macros::dec;
    use std::collections::HashMap;

    #[test]
    fn extended_grid_keeps_flat_perp_with_residual_upnl() {
        let snapshot = PortfolioMarginSnapshot {
            wallet: test_wallet(201),
            cash_balance: dec!(0),
            underlyings: vec![PortfolioMarginUnderlyingSnapshot {
                underlying: "BTC".to_string(),
                spot_price: dec!(100000),
                executed_options: Vec::new(),
                hypothetical_open_order_options: Vec::new(),
                executed_perps: vec![PortfolioMarginPerpExposure {
                    underlying: "BTC".to_string(),
                    quantity: dec!(0),
                    entry_price: Some(dec!(90000)),
                    unrealized_pnl: dec!(125.50),
                }],
                hypothetical_open_order_perps: Vec::new(),
            }],
        };
        let market_state = PortfolioMarginMarketState {
            config: PortfolioMarginConfig::from_legacy_config(
                0.05, 0.3, 0.0, 0.0, 0.001, 0.01, 0.001,
            ),
            underlyings: HashMap::from([(
                "BTC".to_string(),
                PortfolioMarginUnderlyingMarketState {
                    spot_price: 100000.0,
                    option_inputs: HashMap::new(),
                    funding: None,
                },
            )]),
        };

        let grid = compute_extended_risk_grid_from_snapshot(&snapshot, &market_state)
            .expect("extended grid should compute");

        let perp_row = grid
            .instruments
            .iter()
            .find(|instrument| instrument.symbol == "BTC-PERP")
            .expect("flat perp with residual UPNL must remain visible");
        assert_eq!(perp_row.amount, 0.0);
        assert_eq!(perp_row.base_amount, 0.0);
        assert_eq!(perp_row.current_value, 125.50);
        assert!(perp_row.scenario_pnls.iter().all(|pnl| *pnl == 0.0));
    }
}