Struct SpanMarginService 

pub struct SpanMarginService {
    config: Config,
    vol_oracle: SharedVolOracle,
}

SPAN-style margin calculation service.

This consolidates margin logic that was previously scattered across UnifiedEngine, providing a single source of truth for margin computations.

Architecture

The service uses scenario-based risk analysis:

• Evaluates portfolio P&L across multiple market scenarios (spot moves, vol changes, etc.)
• Includes both delta (perp) P&L and options P&L in scenario evaluation
• Computes “scanning risk” as the worst-case loss across all scenarios

Portfolio Margin (PM) Semantics

Any non-empty portfolio goes through SPAN scenario evaluation:

• Long options: scenario loss when spot drops (call loses value)
• Short options: scenario loss when spot rises (unlimited upside risk)
• Spreads: hedging benefits reduce net scenario loss

Only truly empty portfolios (no positions) return zero margin immediately.

Fields

config: Config

vol_oracle: SharedVolOracle

Implementations

impl SpanMarginService

pub fn new(config: Config) -> Self

Create a new SpanMarginService with the given configuration.

pub fn new_fail_closed(config: Config) -> Self

Create a fail-closed SpanMarginService for production wiring.

pub fn new_for_tests(config: Config) -> Self

Create a fixed-vol SPAN service for tests that do not exercise live vol wiring.

pub fn new_with_vol_oracle(config: Config, vol_oracle: SharedVolOracle) -> Self

pub fn config(&self) -> &Config

pub fn set_vol_oracle(&mut self, oracle: SharedVolOracle)

fn snapshot_and_market_state_from_account( &self, account: &Account, ) -> (PortfolioMarginSnapshot, PortfolioMarginMarketState)

fn populate_option_market_state( &self, snapshot: &PortfolioMarginSnapshot, market_state: &mut PortfolioMarginMarketState, ) -> Result<(), MarginError>

pub fn compute_span( &self, accounts: &[Account], ) -> Result<Vec<MarginDetails>, MarginError>

Compute margin details for one or more accounts using Portfolio Margin semantics.

Portfolio Margin Behavior

All accounts with positions (long or short) are included in the result. Empty portfolios return zero margin. This follows PM semantics where:

• equity = cash + executed option UPNL + executed perp UPNL
  • cash comes from the engine-owned balance snapshot
  • option UPNL is computed from Black-Scholes valuations
  • perp UPNL comes from executed perp state only
• IM = max(scanning_risk, option_floor) + gamma_overlay
• MM = IM * 0.85

pub fn compute_span_at( &self, accounts: &[Account], now_ts: i64, ) -> Result<Vec<MarginDetails>, MarginError>

pub fn compute_risk_grid( &self, account: &Account, ) -> Result<Vec<ScenarioPnl>, MarginError>

Compute the risk grid showing scenario PnL for each configured scenario.

This provides introspection into how SPAN scenarios affect the portfolio, similar to Deribit’s risk grid endpoint.

Returns

A vector of scenario PnL entries, one per configured scenario.

pub fn compute_extended_risk_grid( &self, account: &Account, ) -> Result<ExtendedRiskGrid, MarginError>

Compute extended risk grid with per-instrument breakdown.

This provides a full risk matrix like Deribit’s Extended Risk Matrix, showing P&L for each position under each scenario.

pub fn compute_margin_from_snapshot( &self, snapshot: &PortfolioMarginSnapshot, market_state: PortfolioMarginMarketState, ) -> Result<MarginDetails, MarginError>

pub fn compute_margin_from_snapshot_at( &self, snapshot: &PortfolioMarginSnapshot, market_state: PortfolioMarginMarketState, now_ts: i64, ) -> Result<MarginDetails, MarginError>

pub fn compute_risk_grid_from_snapshot( &self, snapshot: &PortfolioMarginSnapshot, market_state: PortfolioMarginMarketState, ) -> Result<Vec<ScenarioPnl>, MarginError>

pub fn compute_extended_risk_grid_from_snapshot( &self, snapshot: &PortfolioMarginSnapshot, market_state: PortfolioMarginMarketState, ) -> Result<ExtendedRiskGrid, MarginError>

fn lookup_option_iv_from_key( &self, underlying: &str, strike: f64, expiry_ts: i64, ) -> Result<f64, MarginError>

fn has_positions(&self, account: &Account) -> bool

Check if account has any positions (options or delta exposure).

Returns true if:

• Any options positions exist (long or short)
• Any significant delta (perp) exposure exists

Used to determine if SPAN scenario evaluation should run. Empty portfolios can skip SPAN and return zero margin immediately.

Note: We iterate by underlying (e.g., “BTC”, “ETH”), not individual symbols. Each Position contains all options for that underlying plus delta exposure. No symbol-level filtering is needed here since we’re checking existence, not value.

impl SpanMarginService

pub fn compute_margin_for_account_at( &self, account: &Account, now_ts: i64, ) -> Result<MarginDetails, MarginError>

Trait Implementations

impl MarginService for SpanMarginService

fn compute_margin_for_account<'life0, 'life1, 'async_trait>( &'life0 self, account: &'life1 Account, ) -> Pin<Box<dyn Future<Output = Result<MarginDetails, MarginError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Compute margin for a single account.

fn compute_margin_for_accounts<'life0, 'life1, 'async_trait>( &'life0 self, accounts: &'life1 [Account], ) -> Pin<Box<dyn Future<Output = Result<Vec<MarginDetails>, MarginError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Convenience batch API for computing margin across multiple accounts.