hypercall/standard_margin/

account_builder.rs

//! StandardAccountBuilder - Builds StandardAccount from data sources.
//!
//! This builder assembles a StandardAccount for margin calculations by combining:
//! - BalanceProvider: engine-owned USDC balance snapshot
//! - PortfolioService: Executed positions
//! - SpotPriceSource: Current spot prices for underlyings

#[cfg(test)]
use crate::portfolio::PortfolioBalance;
use crate::portfolio::PortfolioService;
use crate::rsm::ledger::{BalanceProvider, Ledger, LedgerBalanceProvider, LedgerError};
use crate::rsm::portfolio_margin::risk_account_builder::SpotPriceSource;
use crate::shared::order_types::ParsedSymbol;
use futures::future::join_all;
use hypercall_margin::standard::{OptionPosition, PerpPosition, StandardAccount};
use hypercall_types::{expiry_date_to_timestamp, WalletAddress};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use std::collections::{BTreeSet, HashMap};
use std::sync::Arc;
use tracing::debug;

/// Error type for StandardAccount building.
#[derive(Debug)]
pub enum StandardAccountError {
    Ledger(LedgerError),
    Parse(String),
    /// Spot price unavailable for an underlying - cannot safely calculate margin
    MissingSpotPrice {
        underlying: String,
    },
    /// Unrecognized symbol format - cannot determine if option or perp
    UnrecognizedSymbol {
        symbol: String,
    },
    /// Spot price f64 value is NaN or Infinity - cannot convert to Decimal
    InvalidSpotPrice {
        underlying: String,
        raw_value: f64,
    },
}

impl std::fmt::Display for StandardAccountError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            StandardAccountError::Ledger(e) => write!(f, "ledger error: {}", e),
            StandardAccountError::Parse(e) => write!(f, "parse error: {}", e),
            StandardAccountError::MissingSpotPrice { underlying } => {
                write!(f, "spot price unavailable for {}", underlying)
            }
            StandardAccountError::UnrecognizedSymbol { symbol } => {
                write!(
                    f,
                    "unrecognized symbol format '{}': expected option (e.g., BTC-20250131-100000-C) or perp (e.g., BTC-PERP)",
                    symbol
                )
            }
            StandardAccountError::InvalidSpotPrice {
                underlying,
                raw_value,
            } => {
                write!(
                    f,
                    "invalid spot price for {}: raw value {} is NaN or Infinity",
                    underlying, raw_value
                )
            }
        }
    }
}

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

impl From<LedgerError> for StandardAccountError {
    fn from(e: LedgerError) -> Self {
        StandardAccountError::Ledger(e)
    }
}

/// Builds StandardAccount instances for margin calculations.
///
/// Uses the same data sources as RiskAccountBuilder but produces
/// a simpler account structure optimized for linear margin formulas.
pub struct StandardAccountBuilder {
    balance_provider: Arc<dyn BalanceProvider + Send + Sync>,
    portfolio_service: Arc<dyn PortfolioService + Send + Sync>,
    spot_price_source: Arc<dyn SpotPriceSource + Send + Sync>,
}

impl StandardAccountBuilder {
    const MIN_POSITION_SIZE: Decimal = dec!(0.00000001);
    /// Create a new StandardAccountBuilder.
    pub fn new(
        ledger: Arc<dyn Ledger + Send + Sync>,
        portfolio_service: Arc<dyn PortfolioService + Send + Sync>,
        spot_price_source: Arc<dyn SpotPriceSource + Send + Sync>,
    ) -> Self {
        Self::new_with_balance_provider(
            Arc::new(LedgerBalanceProvider::new(ledger)),
            portfolio_service,
            spot_price_source,
        )
    }

    pub fn new_with_balance_provider(
        balance_provider: Arc<dyn BalanceProvider + Send + Sync>,
        portfolio_service: Arc<dyn PortfolioService + Send + Sync>,
        spot_price_source: Arc<dyn SpotPriceSource + Send + Sync>,
    ) -> Self {
        Self {
            balance_provider,
            portfolio_service,
            spot_price_source,
        }
    }

    /// Build a StandardAccount for the given wallet.
    ///
    /// # Arguments
    /// * `wallet` - The wallet address
    ///
    /// # Returns
    /// A StandardAccount with USDC balance and all positions.
    pub async fn build(
        &self,
        wallet: &WalletAddress,
    ) -> Result<StandardAccount, StandardAccountError> {
        // 1. Get USDC balance from ledger
        let usdc_balance = self.balance_provider.get_balance(wallet).await?;

        // 2. Get portfolio balance (positions) from PortfolioService
        let portfolio_balance = self
            .portfolio_service
            .get_portfolio_balance(wallet)
            .await
            .unwrap_or_default();

        // 3. Balance comes entirely from ledger (faucet deposits + realized PnL)
        let total_balance = usdc_balance;

        // 4. Build account
        let mut account = StandardAccount::new(wallet.to_string(), total_balance);
        let spot_prices = self
            .fetch_spot_prices_for_balance(&portfolio_balance)
            .await?;

        // 5. Convert positions
        for (symbol, pos_data) in &portfolio_balance.positions {
            // Try to parse as option
            if let Ok(parsed) = ParsedSymbol::from_symbol(symbol) {
                let spot_price = *spot_prices.get(&parsed.underlying).ok_or_else(|| {
                    StandardAccountError::MissingSpotPrice {
                        underlying: parsed.underlying.clone(),
                    }
                })?;

                // Compute mark_price from entry + UPNL/size.
                // When UPNL is zero (stale after restart replay), fall back to
                // intrinsic value so equity isn't inflated by the full entry premium.
                let mark_price = if pos_data.amount.abs() < Self::MIN_POSITION_SIZE {
                    pos_data.entry_price
                } else if pos_data.unrealized_pnl == dec!(0) {
                    // UPNL hasn't been refreshed yet (likely after restart).
                    // Use intrinsic value as a conservative mark estimate.
                    let spot_dec = spot_price;
                    let strike_dec = parsed.strike;
                    let intrinsic = if matches!(parsed.option_type, crate::types::OptionType::Call)
                    {
                        spot_dec - strike_dec
                    } else {
                        strike_dec - spot_dec
                    };
                    intrinsic.max(dec!(0))
                } else {
                    pos_data.entry_price + pos_data.unrealized_pnl / pos_data.amount
                };

                let option_pos = OptionPosition {
                    symbol: symbol.clone(),
                    underlying: parsed.underlying.clone(),
                    expiry_ts: expiry_date_to_timestamp(&parsed.underlying, parsed.expiry),
                    strike: parsed.strike,
                    is_call: matches!(parsed.option_type, crate::types::OptionType::Call),
                    size: pos_data.amount,
                    mark_price,
                    entry_price: pos_data.entry_price,
                    spot_price,
                };

                account.option_positions.push(option_pos);
            } else if symbol.ends_with("-PERP") {
                // It's a perpetual
                let underlying = symbol.trim_end_matches("-PERP").to_string();
                let spot_price = *spot_prices.get(&underlying).ok_or_else(|| {
                    StandardAccountError::MissingSpotPrice {
                        underlying: underlying.clone(),
                    }
                })?;

                let perp_pos = PerpPosition {
                    symbol: symbol.clone(),
                    underlying,
                    size: pos_data.amount,
                    mark_price: spot_price, // Perp mark ≈ spot
                    entry_price: pos_data.entry_price,
                };

                account.perp_positions.push(perp_pos);
            } else {
                // Fail-safe: return an error for unrecognized symbols instead of silently dropping
                return Err(StandardAccountError::UnrecognizedSymbol {
                    symbol: symbol.clone(),
                });
            }
        }

        debug!(
            "StandardAccountBuilder: built account for {}: balance={:.2}, options={}, perps={}",
            wallet,
            account.usdc_balance,
            account.option_positions.len(),
            account.perp_positions.len()
        );

        Ok(account)
    }

    /// Build a StandardAccount synchronously from engine-owned state.
    ///
    /// Used by the engine's margin check path where all data is already
    /// in balance_ledger and engine_positions.
    pub fn build_from_engine_state(
        wallet: &WalletAddress,
        balance_ledger: &HashMap<WalletAddress, Decimal>,
        engine_positions: &HashMap<
            (WalletAddress, String),
            crate::rsm::engine_deps::EnginePosition,
        >,
        reference_prices: &HashMap<String, f64>,
    ) -> Result<StandardAccount, StandardAccountError> {
        let usdc_balance = balance_ledger.get(wallet).copied().unwrap_or(Decimal::ZERO);
        let mut account = StandardAccount::new(wallet.to_string(), usdc_balance);

        for ((w, symbol), pos) in engine_positions {
            if w != wallet {
                continue;
            }
            if pos.quantity.abs() < Self::MIN_POSITION_SIZE {
                continue;
            }

            if let Ok(parsed) = ParsedSymbol::from_symbol(symbol) {
                let spot_f64 = reference_prices.get(&parsed.underlying).ok_or_else(|| {
                    StandardAccountError::MissingSpotPrice {
                        underlying: parsed.underlying.clone(),
                    }
                })?;
                let spot_price = Decimal::from_f64_retain(*spot_f64).ok_or_else(|| {
                    StandardAccountError::InvalidSpotPrice {
                        underlying: parsed.underlying.clone(),
                        raw_value: *spot_f64,
                    }
                })?;

                let intrinsic = if matches!(parsed.option_type, crate::types::OptionType::Call) {
                    spot_price - parsed.strike
                } else {
                    parsed.strike - spot_price
                };
                let mark_price = intrinsic.max(dec!(0));

                account.option_positions.push(OptionPosition {
                    symbol: symbol.clone(),
                    underlying: parsed.underlying.clone(),
                    expiry_ts: expiry_date_to_timestamp(&parsed.underlying, parsed.expiry),
                    strike: parsed.strike,
                    is_call: matches!(parsed.option_type, crate::types::OptionType::Call),
                    size: pos.quantity,
                    mark_price,
                    entry_price: pos.entry_price,
                    spot_price,
                });
            } else if symbol.ends_with("-PERP") {
                let underlying = symbol.trim_end_matches("-PERP").to_string();
                let spot_f64 = reference_prices.get(&underlying).ok_or_else(|| {
                    StandardAccountError::MissingSpotPrice {
                        underlying: underlying.clone(),
                    }
                })?;
                let spot_price = Decimal::from_f64_retain(*spot_f64).ok_or_else(|| {
                    StandardAccountError::InvalidSpotPrice {
                        underlying: underlying.clone(),
                        raw_value: *spot_f64,
                    }
                })?;

                account.perp_positions.push(PerpPosition {
                    symbol: symbol.clone(),
                    underlying,
                    size: pos.quantity,
                    mark_price: spot_price,
                    entry_price: pos.entry_price,
                });
            } else {
                return Err(StandardAccountError::UnrecognizedSymbol {
                    symbol: symbol.clone(),
                });
            }
        }

        Ok(account)
    }

    async fn fetch_spot_prices_for_balance(
        &self,
        portfolio_balance: &crate::portfolio::PortfolioBalance,
    ) -> Result<HashMap<String, Decimal>, StandardAccountError> {
        let mut underlyings = BTreeSet::new();
        for symbol in portfolio_balance.positions.keys() {
            if let Ok(parsed) = ParsedSymbol::from_symbol(symbol) {
                underlyings.insert(parsed.underlying);
            } else if let Some(underlying) = symbol.strip_suffix("-PERP") {
                underlyings.insert(underlying.to_string());
            } else {
                return Err(StandardAccountError::UnrecognizedSymbol {
                    symbol: symbol.clone(),
                });
            }
        }

        let fetches = underlyings.into_iter().map(|underlying| {
            let spot_price_source = self.spot_price_source.clone();
            async move {
                let spot_price_f64 = spot_price_source
                    .get_spot_price(&underlying)
                    .await
                    .ok_or_else(|| StandardAccountError::MissingSpotPrice {
                        underlying: underlying.clone(),
                    })?;
                let spot_price = Decimal::from_f64_retain(spot_price_f64).ok_or_else(|| {
                    StandardAccountError::InvalidSpotPrice {
                        underlying: underlying.clone(),
                        raw_value: spot_price_f64,
                    }
                })?;
                Ok::<(String, Decimal), StandardAccountError>((underlying, spot_price))
            }
        });

        let mut spot_prices = HashMap::new();
        for result in join_all(fetches).await {
            let (underlying, spot_price) = result?;
            spot_prices.insert(underlying, spot_price);
        }

        Ok(spot_prices)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::portfolio::PositionData;
    use crate::rsm::ledger::InMemoryLedger;
    use crate::standard_margin::service::StandardMarginService;
    use async_trait::async_trait;
    use hypercall_types::wallet_address::test_wallet;
    use std::collections::HashMap;
    use tokio::sync::RwLock;

    // Mock PortfolioService for testing
    struct MockPortfolioService {
        balances: RwLock<HashMap<String, PortfolioBalance>>,
    }

    #[async_trait]
    impl PortfolioService for MockPortfolioService {
        async fn get_portfolio(
            &self,
            _account: &WalletAddress,
        ) -> hypercall_types::api_models::Portfolio {
            unimplemented!()
        }

        async fn get_portfolio_balance(&self, account: &WalletAddress) -> Option<PortfolioBalance> {
            let balances = self.balances.read().await;
            balances.get(&account.as_hex().to_lowercase()).cloned()
        }

        async fn all_portfolios(&self) -> HashMap<WalletAddress, PortfolioBalance> {
            // This mock uses String keys, but we need to return WalletAddress keys
            // For testing purposes, return empty since this is a mock
            HashMap::new()
        }

        async fn apply_event(
            &self,
            _event: &hypercall_types::EngineMessage,
        ) -> Result<Vec<crate::portfolio::PortfolioChange>, crate::portfolio::PortfolioError>
        {
            Ok(vec![])
        }

        async fn apply_hypercore_position_update(
            &self,
            _update: &crate::portfolio::HypercorePositionUpdate,
        ) {
        }

        async fn set_hypercore_position(
            &self,
            _update: &crate::portfolio::HypercorePositionUpdate,
        ) {
        }

        async fn calculate_fill_accounting(
            &self,
            fill: &hypercall_types::Fill,
        ) -> Result<hypercall_types::FillAccounting, crate::portfolio::PortfolioError> {
            Ok(hypercall_types::FillAccounting::zero(fill.trade_id))
        }

        async fn remove_expired_position(&self, _wallet: &WalletAddress, _symbol: &str) {
            // Mock: no-op
        }

        async fn apply_fill_to_memory(
            &self,
            _wallet: &WalletAddress,
            _symbol: &str,
            _side: &hypercall_types::Side,
            _price: Decimal,
            _quantity: Decimal,
        ) {
        }

        fn as_any(&self) -> &dyn std::any::Any {
            self
        }
    }

    // Mock SpotPriceSource
    struct MockSpotPriceSource {
        prices: HashMap<String, f64>,
    }

    #[async_trait]
    impl SpotPriceSource for MockSpotPriceSource {
        async fn get_spot_price(&self, underlying: &str) -> Option<f64> {
            self.prices.get(underlying).copied()
        }
    }

    #[tokio::test]
    async fn test_build_empty_account() {
        let wallet = test_wallet(1);
        let ledger = Arc::new(InMemoryLedger::new());
        let portfolio = Arc::new(MockPortfolioService {
            balances: RwLock::new(HashMap::new()),
        });
        let spot_source = Arc::new(MockSpotPriceSource {
            prices: HashMap::new(),
        });

        let builder = StandardAccountBuilder::new(ledger.clone(), portfolio, spot_source);

        let account = builder.build(&wallet).await.unwrap();

        assert_eq!(account.wallet, wallet.as_hex().to_lowercase());
        assert_eq!(account.usdc_balance, dec!(0));
        assert!(account.option_positions.is_empty());
        assert!(account.perp_positions.is_empty());
    }

    #[tokio::test]
    async fn test_build_with_balance() {
        let wallet = test_wallet(1);
        let ledger = Arc::new(InMemoryLedger::new());
        ledger.set_balance(&wallet, dec!(5000)).await.unwrap();

        let portfolio = Arc::new(MockPortfolioService {
            balances: RwLock::new(HashMap::new()),
        });
        let spot_source = Arc::new(MockSpotPriceSource {
            prices: HashMap::new(),
        });

        let builder = StandardAccountBuilder::new(ledger, portfolio, spot_source);

        let account = builder.build(&wallet).await.unwrap();

        assert_eq!(account.usdc_balance, dec!(5000));
    }

    #[tokio::test]
    async fn test_build_with_option_position() {
        let wallet = test_wallet(1);
        let ledger = Arc::new(InMemoryLedger::new());
        ledger.set_balance(&wallet, dec!(5000)).await.unwrap();

        let mut positions = HashMap::new();
        positions.insert(
            "ETH-20251231-4000-C".to_string(),
            PositionData {
                symbol: "ETH-20251231-4000-C".to_string(),
                amount: dec!(10),
                entry_price: dec!(200),
                margin_posted: dec!(0),
                realized_pnl: dec!(0),
                unrealized_pnl: dec!(500),
            },
        );

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

        let mut balances = HashMap::new();
        balances.insert(wallet.as_hex().to_lowercase(), balance);

        let portfolio = Arc::new(MockPortfolioService {
            balances: RwLock::new(balances),
        });

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

        let spot_source = Arc::new(MockSpotPriceSource { prices });

        let builder = StandardAccountBuilder::new(ledger, portfolio, spot_source);

        let account = builder.build(&wallet).await.unwrap();

        // Balance = ledger (5000)
        assert_eq!(account.usdc_balance, dec!(5000));
        assert_eq!(account.option_positions.len(), 1);

        let opt = &account.option_positions[0];
        assert_eq!(opt.symbol, "ETH-20251231-4000-C");
        assert_eq!(opt.underlying, "ETH");
        assert_eq!(opt.strike, dec!(4000));
        assert!(opt.is_call);
        assert_eq!(opt.size, dec!(10));
        assert_eq!(opt.spot_price, dec!(3500));
    }

    /// Verify that mark_price and equity depend on the UPNL value passed to the builder.
    ///
    /// When UPNL=0 (stale after restart replay), the builder falls back to intrinsic
    /// value (`max(spot - strike, 0)` for a call) so equity isn't inflated by the
    /// full entry premium — see the intrinsic-fallback branch at
    /// `build()` above and PR #1304 ("fix(server): UPNL repricing, intrinsic
    /// fallback"). When UPNL is fresh, mark = entry_price + upnl/amount and
    /// reflects the market.
    #[tokio::test]
    async fn test_mark_price_and_equity_depend_on_upnl_input() {
        let wallet = test_wallet(1);
        let ledger = Arc::new(InMemoryLedger::new());
        ledger.set_balance(&wallet, dec!(5000)).await.unwrap();

        // Position with UPNL=0 (e.g., stale cache or just-opened position)
        let mut positions = HashMap::new();
        positions.insert(
            "BTC-20260331-100000-C".to_string(),
            PositionData {
                symbol: "BTC-20260331-100000-C".to_string(),
                amount: dec!(1),
                entry_price: dec!(5000),
                unrealized_pnl: dec!(0),
                margin_posted: dec!(0),
                realized_pnl: dec!(0),
            },
        );

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

        let mut balances = HashMap::new();
        balances.insert(wallet.as_hex().to_lowercase(), balance);

        let portfolio = Arc::new(MockPortfolioService {
            balances: RwLock::new(balances),
        });

        let mut prices = HashMap::new();
        prices.insert("BTC".to_string(), 110000.0);
        let spot_source = Arc::new(MockSpotPriceSource { prices });

        let builder = StandardAccountBuilder::new(ledger.clone(), portfolio, spot_source);

        let account = builder.build(&wallet).await.unwrap();

        // With UPNL=0 the builder falls back to intrinsic value:
        // max(spot - strike, 0) = max(110000 - 100000, 0) = 10000 for the call.
        assert_eq!(
            account.option_positions[0].mark_price,
            dec!(10000),
            "mark_price = intrinsic value when UPNL=0"
        );

        let service = StandardMarginService::new();
        let result = service.compute_margin(&account);

        // Equity = cash (ledger reflects the $5000 premium debit) + signed
        // option value at the intrinsic mark (1 * 10000) = 15000.
        assert_eq!(
            result.equity,
            dec!(15000),
            "equity reflects intrinsic option mark (premium already in cash)"
        );

        // Now show what correct behavior looks like with fresh UPNL
        let mut fresh_positions = HashMap::new();
        fresh_positions.insert(
            "BTC-20260331-100000-C".to_string(),
            PositionData {
                symbol: "BTC-20260331-100000-C".to_string(),
                amount: dec!(1),
                entry_price: dec!(5000),
                unrealized_pnl: dec!(10000), // Fresh: reflects deep ITM call mark ~15000
                margin_posted: dec!(0),
                realized_pnl: dec!(0),
            },
        );

        let fresh_balance = PortfolioBalance {
            positions: fresh_positions,
            total_margin_used: dec!(0),
        };

        let mut fresh_balances = HashMap::new();
        fresh_balances.insert(wallet.as_hex().to_lowercase(), fresh_balance);

        let fresh_portfolio = Arc::new(MockPortfolioService {
            balances: RwLock::new(fresh_balances),
        });

        let mut fresh_prices = HashMap::new();
        fresh_prices.insert("BTC".to_string(), 110000.0);
        let fresh_spot_source = Arc::new(MockSpotPriceSource {
            prices: fresh_prices,
        });

        let fresh_builder =
            StandardAccountBuilder::new(ledger.clone(), fresh_portfolio, fresh_spot_source);

        let fresh_account = fresh_builder.build(&wallet).await.unwrap();

        // With fresh UPNL, mark_price = 5000 + 10000/1 = 15000
        assert_eq!(fresh_account.option_positions[0].mark_price, dec!(15000));

        let fresh_result = service.compute_margin(&fresh_account);

        // With fresh pricing, the same premium-debited cash plus the new option
        // mark yields higher equity.
        assert_eq!(fresh_result.equity, dec!(20000));

        // Demonstrates sensitivity: stale-UPNL fallback (intrinsic, $15k equity) vs
        // fresh UPNL (entry+upnl/amount mark, $20k equity) = $5k difference.
        assert_ne!(
            result.equity,
            fresh_result.equity,
            "equity differs by ${} depending on UPNL freshness",
            fresh_result.equity - result.equity
        );
    }
}