hypercall/rsm/portfolio_margin/

account_builder.rs

//! Account builder for converting PortfolioBalance to types::Account.
//!
//! This module provides the translation layer between:
//! - `PortfolioBalance` (PortfolioService's internal state for executed positions)
//! - `types::Account` (SPAN/margin calculation input)
//!
//! The key insight is that PortfolioBalance stores positions keyed by full symbol
//! (e.g., "BTC-20250131-100000-C"), while Account groups by underlying (e.g., "BTC").
//!
//! ## Fail-Closed Design
//!
//! This builder returns `Result<Account, BuildAccountError>` rather than silently
//! skipping unknown or missing data. If we cannot safely construct a complete
//! risk view, we return an error so callers can reject margin-sensitive operations.

use crate::portfolio::PortfolioBalance;
use crate::shared::order_types::ParsedSymbol;
use crate::types::{Account, OptionContract, Position};
use hypercall_types::WalletAddress;
use rust_decimal::Decimal;
use std::collections::HashMap;
use std::fmt;

/// Error type for account construction failures.
///
/// When we cannot safely build a risk Account from PortfolioBalance,
/// we return an error rather than silently skipping risk exposure.
/// This ensures we "fail closed" - unknown risk = rejected operation.
#[derive(Debug, Clone)]
pub enum BuildAccountError {
    /// Failed to parse a symbol in the portfolio
    UnparseableSymbol { symbol: String, reason: String },
    /// Missing spot price for an underlying with positions
    MissingSpotPrice { underlying: String },
    /// Instrument type not supported for margin calculation
    UnsupportedInstrument { symbol: String, kind: String },
    /// Invalid expiry in a parsed option symbol
    InvalidExpiry { symbol: String, expiry: u64 },
    /// Position data is inconsistent or invalid
    InconsistentPosition { symbol: String, details: String },
}

impl fmt::Display for BuildAccountError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            BuildAccountError::UnparseableSymbol { symbol, reason } => {
                write!(f, "unparseable symbol '{}': {}", symbol, reason)
            }
            BuildAccountError::MissingSpotPrice { underlying } => {
                write!(f, "missing spot price for underlying '{}'", underlying)
            }
            BuildAccountError::UnsupportedInstrument { symbol, kind } => {
                write!(f, "unsupported instrument '{}' of kind '{}'", symbol, kind)
            }
            BuildAccountError::InvalidExpiry { symbol, expiry } => {
                write!(f, "invalid expiry '{}' in symbol '{}'", expiry, symbol)
            }
            BuildAccountError::InconsistentPosition { symbol, details } => {
                write!(f, "inconsistent position for '{}': {}", symbol, details)
            }
        }
    }
}

impl std::error::Error for BuildAccountError {}

/// Build a `types::Account` from PortfolioService's internal state.
///
/// This converts executed positions (PortfolioBalance) into the format
/// that SPAN/margin code expects (types::Account).
///
/// # Arguments
/// * `account_id` - The wallet address / account identifier
/// * `balance` - The internal PortfolioBalance from PortfolioService
/// * `address` - Optional on-chain address (for HyperCore lookups)
/// * `spot_prices` - Map of underlying -> current spot price (e.g., {"BTC": 100000.0})
///
/// # Returns
/// * `Ok(Account)` - A complete, trustworthy Account ready for SPAN margin calculations
/// * `Err(BuildAccountError)` - If any position cannot be safely converted
///
/// # Fail-Closed Behavior
/// This function returns an error (rather than skipping) if:
/// - A symbol cannot be parsed
/// - A spot price is missing for an underlying with positions
/// - An instrument type is not supported
pub fn build_account_from_balance(
    account_id: &WalletAddress,
    balance: &PortfolioBalance,
    address: Option<WalletAddress>,
    spot_prices: &HashMap<String, f64>,
) -> Result<Account, BuildAccountError> {
    // Group positions by underlying
    let mut portfolio: HashMap<String, Position> = HashMap::new();

    for (symbol, pos_data) in &balance.positions {
        let underlying = symbol
            .strip_suffix("-PERP")
            .map(ToOwned::to_owned)
            .or_else(|| {
                if !symbol.contains('-') && !symbol.is_empty() {
                    Some(symbol.clone())
                } else {
                    None
                }
            });
        let option_symbol = if underlying.is_some() {
            None
        } else {
            Some(ParsedSymbol::from_symbol(symbol).map_err(|e| {
                tracing::error!(
                    "Failed to parse symbol {} for account {}: {} - rejecting account build",
                    symbol,
                    account_id,
                    e
                );
                BuildAccountError::UnparseableSymbol {
                    symbol: symbol.clone(),
                    reason: e,
                }
            })?)
        };

        let spot_underlying = option_symbol
            .as_ref()
            .map(|parsed| parsed.underlying.as_str())
            .or(underlying.as_deref())
            .expect("underlying must be present for option or perp position");
        let spot = spot_prices.get(spot_underlying).copied().ok_or_else(|| {
            tracing::error!(
                "Missing spot price for underlying {} (symbol {}) in account {} - rejecting account build",
                spot_underlying,
                symbol,
                account_id
            );
            BuildAccountError::MissingSpotPrice {
                underlying: spot_underlying.to_string(),
            }
        })?;

        let position = portfolio
            .entry(spot_underlying.to_string())
            .or_insert_with(|| Position {
                spot: Decimal::from_f64_retain(spot)
                    .expect("validated spot price must be representable as Decimal"),
                delta: Decimal::ZERO,
                perp_unrealized_pnl: Decimal::ZERO,
                options: Vec::new(),
            });

        if underlying.is_some() {
            position.delta += pos_data.amount;
            position.perp_unrealized_pnl += pos_data.unrealized_pnl;
            continue;
        }

        let parsed = option_symbol.expect("option symbol must be present for non-perp positions");

        // Convert expiry from YYYYMMDD to years-to-expiry
        let expiry_years = expiry_to_years(&parsed.underlying, parsed.expiry);
        let expiry_ts =
            hypercall_types::expiry_date_to_timestamp(&parsed.underlying, parsed.expiry);
        if expiry_ts <= 0 {
            return Err(BuildAccountError::InvalidExpiry {
                symbol: symbol.clone(),
                expiry: parsed.expiry,
            });
        }

        // Create OptionContract with entry_price for UPNL calculation
        // Keep Decimal values - margin service will convert to f64 for Black-Scholes
        let option_contract = OptionContract {
            option_type: parsed.option_type,
            strike: parsed.strike,
            expiry_ts,
            expiry: Decimal::from_f64_retain(expiry_years)
                .expect("validated option expiry in years must be representable as Decimal"),
            quantity: pos_data.amount, // Positive for long, negative for short
            entry_price: pos_data.entry_price, // Cost basis per contract
        };

        position.options.push(option_contract);
    }

    Ok(Account {
        id: *account_id,
        portfolio,
        cash: 0.0, // Filled by RiskAccountBuilder from its BalanceProvider.
        address,
    })
}

/// Convert YYYYMMDD expiry to years-to-expiry from now.
///
/// Returns 0.0 if the expiry is in the past or invalid.
pub fn expiry_to_years(underlying: &str, expiry_yyyymmdd: u64) -> f64 {
    use chrono::{DateTime, Utc};

    let expiry_timestamp =
        match hypercall_types::expiry_date_to_timestamp_checked(underlying, expiry_yyyymmdd) {
            Ok(timestamp) => timestamp,
            Err(err) => {
                tracing::warn!("Invalid expiry date {}: {}", expiry_yyyymmdd, err);
                return 0.0;
            }
        };

    let expiry_datetime = match DateTime::<Utc>::from_timestamp(expiry_timestamp as i64, 0) {
        Some(datetime) => datetime,
        None => {
            tracing::warn!(
                "Invalid expiry timestamp {} for date {}",
                expiry_timestamp,
                expiry_yyyymmdd
            );
            return 0.0;
        }
    };

    let now = Utc::now();
    let duration = expiry_datetime.signed_duration_since(now);

    // Convert to years (365.25 days per year)
    let days = duration.num_seconds() as f64 / 86400.0;
    let years = days / 365.25;

    if years < 0.0 {
        0.0 // Expired
    } else {
        years
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::portfolio::PositionData;
    use crate::types::OptionType;
    use hypercall_types::wallet_address::test_wallet;
    use rust_decimal::prelude::ToPrimitive;
    use rust_decimal_macros::dec;

    #[test]
    fn test_build_account_from_empty_balance() {
        let balance = PortfolioBalance {
            positions: HashMap::new(),
            total_margin_used: dec!(0),
        };

        let spot_prices = HashMap::new();
        let account = build_account_from_balance(&test_wallet(1), &balance, None, &spot_prices)
            .expect("empty balance should succeed");

        assert_eq!(account.id, test_wallet(1));
        assert_eq!(account.cash, 0.0); // Filled later from RiskAccountBuilder's BalanceProvider.
        assert!(account.portfolio.is_empty());
        assert!(account.address.is_none());
    }

    #[test]
    fn test_build_account_with_positions() {
        let mut positions = HashMap::new();
        positions.insert(
            "BTC-20251231-100000-C".to_string(),
            PositionData {
                symbol: "BTC-20251231-100000-C".to_string(),
                amount: dec!(10),
                entry_price: dec!(5000),
                margin_posted: dec!(5000),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(0),
            },
        );
        positions.insert(
            "BTC-20251231-90000-P".to_string(),
            PositionData {
                symbol: "BTC-20251231-90000-P".to_string(),
                amount: dec!(-5), // Short
                entry_price: dec!(3000),
                margin_posted: dec!(4500),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(0),
            },
        );

        let balance = PortfolioBalance {
            positions,
            total_margin_used: dec!(9500),
        };

        let mut spot_prices = HashMap::new();
        spot_prices.insert("BTC".to_string(), 95000.0);

        let account = build_account_from_balance(
            &test_wallet(1),
            &balance,
            Some(test_wallet(1)),
            &spot_prices,
        )
        .expect("valid balance with spot prices should succeed");

        assert_eq!(account.id, test_wallet(1));
        assert_eq!(account.cash, 0.0); // Filled later from RiskAccountBuilder's BalanceProvider.
        assert_eq!(account.address, Some(test_wallet(1)));

        // Should have one Position for BTC underlying
        assert_eq!(account.portfolio.len(), 1);
        let btc_position = account.portfolio.get("BTC").expect("BTC position");

        assert_eq!(btc_position.spot.to_f64().unwrap(), 95000.0);
        assert_eq!(btc_position.options.len(), 2);

        // Check the call option
        let call = btc_position
            .options
            .iter()
            .find(|o| o.option_type == OptionType::Call)
            .expect("call option");
        assert_eq!(call.strike, dec!(100000));
        assert_eq!(call.quantity, dec!(10));

        // Check the put option
        let put = btc_position
            .options
            .iter()
            .find(|o| o.option_type == OptionType::Put)
            .expect("put option");
        assert_eq!(put.strike, dec!(90000));
        assert_eq!(put.quantity, dec!(-5)); // Short
    }

    #[test]
    fn test_expiry_to_years() {
        use chrono::{Datelike, Days, Utc};

        // Test with a future date (1 year from now)
        let now = Utc::now().date_naive();
        let future = now + Days::new(365);
        let future_expiry =
            (future.year() as u64) * 10000 + (future.month() as u64) * 100 + future.day() as u64;
        let years = expiry_to_years("BTC", future_expiry);
        assert!(
            years > 0.9 && years < 1.1,
            "Future expiry ~1 year should be between 0.9 and 1.1, got {}",
            years
        );

        // Test with a past date
        let past_expiry = 20200101u64; // Jan 1, 2020
        let years = expiry_to_years("BTC", past_expiry);
        assert_eq!(years, 0.0, "Past expiry should return 0");
    }

    #[test]
    fn test_multiple_underlyings() {
        let mut positions = HashMap::new();
        positions.insert(
            "BTC-20251231-100000-C".to_string(),
            PositionData {
                symbol: "BTC-20251231-100000-C".to_string(),
                amount: dec!(10),
                entry_price: dec!(5000),
                margin_posted: dec!(5000),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(0),
            },
        );
        positions.insert(
            "ETH-20251231-4000-C".to_string(),
            PositionData {
                symbol: "ETH-20251231-4000-C".to_string(),
                amount: dec!(20),
                entry_price: dec!(200),
                margin_posted: dec!(4000),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(0),
            },
        );

        let balance = PortfolioBalance {
            positions,
            total_margin_used: dec!(9000),
        };

        let mut spot_prices = HashMap::new();
        spot_prices.insert("BTC".to_string(), 95000.0);
        spot_prices.insert("ETH".to_string(), 3500.0);

        let account = build_account_from_balance(&test_wallet(1), &balance, None, &spot_prices)
            .expect("valid multi-underlying balance should succeed");

        // Should have two Positions - one for each underlying
        assert_eq!(account.portfolio.len(), 2);
        assert!(account.portfolio.contains_key("BTC"));
        assert!(account.portfolio.contains_key("ETH"));

        let btc_pos = account.portfolio.get("BTC").unwrap();
        assert_eq!(btc_pos.spot.to_f64().unwrap(), 95000.0);

        let eth_pos = account.portfolio.get("ETH").unwrap();
        assert_eq!(eth_pos.spot.to_f64().unwrap(), 3500.0);
    }

    #[test]
    fn test_fail_closed_on_unparseable_symbol() {
        let mut positions = HashMap::new();
        positions.insert(
            "INVALID-SYMBOL".to_string(), // Not a valid option symbol
            PositionData {
                symbol: "INVALID-SYMBOL".to_string(),
                amount: dec!(10),
                entry_price: dec!(100),
                margin_posted: dec!(100),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(0),
            },
        );

        let balance = PortfolioBalance {
            positions,
            total_margin_used: dec!(100),
        };

        let spot_prices = HashMap::new();
        let result = build_account_from_balance(&test_wallet(1), &balance, None, &spot_prices);

        assert!(result.is_err());
        match result.unwrap_err() {
            BuildAccountError::UnparseableSymbol { symbol, .. } => {
                assert_eq!(symbol, "INVALID-SYMBOL");
            }
            other => panic!("Expected UnparseableSymbol error, got {:?}", other),
        }
    }

    #[test]
    fn test_fail_closed_on_missing_spot_price() {
        let mut positions = HashMap::new();
        positions.insert(
            "BTC-20251231-100000-C".to_string(),
            PositionData {
                symbol: "BTC-20251231-100000-C".to_string(),
                amount: dec!(10),
                entry_price: dec!(5000),
                margin_posted: dec!(5000),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(0),
            },
        );

        let balance = PortfolioBalance {
            positions,
            total_margin_used: dec!(5000),
        };

        // No spot price for BTC - should fail
        let spot_prices = HashMap::new();
        let result = build_account_from_balance(&test_wallet(1), &balance, None, &spot_prices);

        assert!(result.is_err());
        match result.unwrap_err() {
            BuildAccountError::MissingSpotPrice { underlying } => {
                assert_eq!(underlying, "BTC");
            }
            other => panic!("Expected MissingSpotPrice error, got {:?}", other),
        }
    }
}