optionstratlib_core/model/leg/

spot.rs

/******************************************************************************
   Author: Joaquín Béjar García
   Email: jb@taunais.com
   Date: 24/12/25
******************************************************************************/

//! # Spot Position Module
//!
//! This module provides the `SpotPosition` struct for representing direct ownership
//! of underlying assets such as stocks, cryptocurrency spot holdings, or forex spot positions.
//!
//! ## Characteristics
//!
//! - No expiration date
//! - No margin requirements (fully funded)
//! - Delta = ±1.0 per unit (Long = +1, Short = -1)
//! - No funding costs or time decay
//!
//! ## Example
//!
//! ```rust
//! # #[cfg(feature = "clock")] {
//! use optionstratlib_core::model::leg::SpotPosition;
//! use optionstratlib_core::model::types::Side;
//! use positive::{pos_or_panic,Positive};
//! use chrono::Utc;
//!
//! let spot = SpotPosition::new(
//!     "AAPL".to_string(),
//!     Positive::HUNDRED,      // 100 shares
//!     pos_or_panic!(150.0),      // cost basis $150 per share
//!     Side::Long,
//!     Utc::now(),
//!     Positive::ONE,        // $1 open fee
//!     Positive::ONE,        // $1 close fee
//! );
//! # }
//! ```

use crate::error::PositionError;
use crate::model::decimal::{d_div, d_mul, d_sub};
use crate::model::leg::traits::LegAble;
use crate::model::types::Side;
#[cfg(feature = "clock")]
use crate::utils::time::wall_clock;
use chrono::{DateTime, Utc};
use positive::Positive;
use rust_decimal::Decimal;
use serde::{Deserialize, Serialize};

/// Represents a spot/underlying asset position.
///
/// A spot position represents direct ownership of an asset without any derivative
/// characteristics. This includes stocks, cryptocurrency spot holdings, forex spot,
/// and commodities held for delivery.
///
/// # Fields
///
/// * `symbol` - The ticker symbol or identifier of the asset
/// * `quantity` - The number of units held
/// * `cost_basis` - The average acquisition price per unit
/// * `side` - Whether the position is Long (owned) or Short (borrowed/sold)
/// * `date` - The timestamp when the position was opened
/// * `open_fee` - Transaction fee paid to open the position
/// * `close_fee` - Transaction fee to be paid when closing the position
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SpotPosition {
    /// The ticker symbol or identifier of the underlying asset.
    pub symbol: String,

    /// The number of units held in this position.
    pub quantity: Positive,

    /// The average cost per unit at which the position was acquired.
    pub cost_basis: Positive,

    /// The direction of the position (Long = owned, Short = borrowed).
    pub side: Side,

    /// The timestamp when this position was opened.
    pub date: DateTime<Utc>,

    /// The fee paid to open this position.
    pub open_fee: Positive,

    /// The fee to be paid when closing this position.
    pub close_fee: Positive,
}

impl SpotPosition {
    /// Creates a new spot position.
    ///
    /// # Arguments
    ///
    /// * `symbol` - The ticker symbol of the asset
    /// * `quantity` - Number of units to hold
    /// * `cost_basis` - Average price per unit
    /// * `side` - Long or Short position
    /// * `date` - Position open timestamp
    /// * `open_fee` - Fee to open the position
    /// * `close_fee` - Fee to close the position
    ///
    /// # Returns
    ///
    /// A new `SpotPosition` instance.
    #[must_use]
    pub fn new(
        symbol: String,
        quantity: Positive,
        cost_basis: Positive,
        side: Side,
        date: DateTime<Utc>,
        open_fee: Positive,
        close_fee: Positive,
    ) -> Self {
        Self {
            symbol,
            quantity,
            cost_basis,
            side,
            date,
            open_fee,
            close_fee,
        }
    }

    /// Creates a long spot position with default fees.
    ///
    /// # Arguments
    ///
    /// * `symbol` - The ticker symbol
    /// * `quantity` - Number of units
    /// * `cost_basis` - Price per unit
    ///
    /// # Returns
    ///
    /// A new long `SpotPosition` with zero fees.
    #[cfg(feature = "clock")]
    #[must_use]
    pub fn long(symbol: String, quantity: Positive, cost_basis: Positive) -> Self {
        Self::new(
            symbol,
            quantity,
            cost_basis,
            Side::Long,
            wall_clock(),
            Positive::ZERO,
            Positive::ZERO,
        )
    }

    /// Creates a short spot position with default fees.
    ///
    /// # Arguments
    ///
    /// * `symbol` - The ticker symbol
    /// * `quantity` - Number of units
    /// * `cost_basis` - Price per unit (entry price for short)
    ///
    /// # Returns
    ///
    /// A new short `SpotPosition` with zero fees.
    #[cfg(feature = "clock")]
    #[must_use]
    pub fn short(symbol: String, quantity: Positive, cost_basis: Positive) -> Self {
        Self::new(
            symbol,
            quantity,
            cost_basis,
            Side::Short,
            wall_clock(),
            Positive::ZERO,
            Positive::ZERO,
        )
    }

    /// Returns the total value of the position at the cost basis.
    ///
    /// This represents the initial investment (for long) or proceeds (for short).
    ///
    /// # Errors
    ///
    /// Returns [`PositionError::PositiveError`] when the product leaves the
    /// `Positive` range; `Positive * Positive` aborted on it (#788).
    pub fn initial_value(&self) -> Result<Positive, PositionError> {
        Ok(self.quantity.checked_mul(&self.cost_basis)?)
    }

    /// Returns the current market value at a given price.
    ///
    /// # Arguments
    ///
    /// * `current_price` - The current market price per unit
    ///
    /// # Errors
    ///
    /// Returns [`PositionError::PositiveError`] when the product leaves the
    /// `Positive` range (#788).
    pub fn market_value(&self, current_price: Positive) -> Result<Positive, PositionError> {
        Ok(self.quantity.checked_mul(&current_price)?)
    }

    /// Calculates the percentage return on the position.
    ///
    /// # Arguments
    ///
    /// * `current_price` - The current market price per unit
    ///
    /// # Returns
    ///
    /// The percentage return as a Decimal (e.g., 0.10 = 10% gain).
    ///
    /// # Errors
    ///
    /// Returns [`PositionError::DecimalError`] when the return leaves the
    /// `Decimal` range: a cost basis near zero against a large price, where
    /// the division aborted with `Division overflowed` (#788).
    pub fn percentage_return(&self, current_price: Positive) -> Result<Decimal, PositionError> {
        if self.cost_basis == Positive::ZERO {
            return Ok(Decimal::ZERO);
        }

        let price_change = d_sub(
            current_price.to_dec(),
            self.cost_basis.to_dec(),
            "SpotPosition::percentage_return/price_change",
        )?;
        let return_pct = d_div(
            price_change,
            self.cost_basis.to_dec(),
            "SpotPosition::percentage_return",
        )?;

        Ok(match self.side {
            Side::Long => return_pct,
            Side::Short => -return_pct,
        })
    }

    /// Calculates the break-even price including fees.
    ///
    /// For long positions: cost_basis + (total_fees / quantity)
    /// For short positions: cost_basis - (total_fees / quantity), floored
    /// at zero.
    ///
    /// # Errors
    ///
    /// Returns [`PositionError::PositiveError`] when the fee total, the fee
    /// per unit or the long break-even leaves the `Positive` range: a
    /// quantity near zero against large fees, where the division aborted
    /// with `Positive arithmetic overflow in div` (#788).
    pub fn break_even_price(&self) -> Result<Positive, PositionError> {
        if self.quantity == Positive::ZERO {
            return Ok(self.cost_basis);
        }

        let fee_per_unit = self
            .open_fee
            .checked_add(&self.close_fee)?
            .checked_div(&self.quantity)?;

        Ok(match self.side {
            Side::Long => self.cost_basis.checked_add(&fee_per_unit)?,
            Side::Short => {
                if self.cost_basis > fee_per_unit {
                    self.cost_basis.checked_sub(&fee_per_unit)?
                } else {
                    Positive::ZERO
                }
            }
        })
    }
}

impl LegAble for SpotPosition {
    fn get_symbol(&self) -> &str {
        &self.symbol
    }

    fn get_quantity(&self) -> Positive {
        self.quantity
    }

    fn get_side(&self) -> Side {
        self.side
    }

    fn pnl_at_price(&self, price: Positive) -> Result<Decimal, PositionError> {
        let price_change = d_sub(
            price.to_dec(),
            self.cost_basis.to_dec(),
            "SpotPosition::pnl_at_price/price_change",
        )?;
        let gross_pnl = d_mul(
            price_change,
            self.quantity.to_dec(),
            "SpotPosition::pnl_at_price/gross",
        )?;
        let total_fees = self.open_fee.checked_add(&self.close_fee)?;

        let signed_gross = match self.side {
            Side::Long => gross_pnl,
            // `Decimal` is symmetric, so negating a representable value is
            // itself representable and needs no check.
            Side::Short => -gross_pnl,
        };
        Ok(d_sub(
            signed_gross,
            total_fees.to_dec(),
            "SpotPosition::pnl_at_price/net",
        )?)
    }

    fn total_cost(&self) -> Result<Positive, PositionError> {
        Ok(match self.side {
            Side::Long => self
                .quantity
                .checked_mul(&self.cost_basis)?
                .checked_add(&self.open_fee)?
                .checked_add(&self.close_fee)?,
            Side::Short => self.open_fee.checked_add(&self.close_fee)?,
        })
    }

    fn fees(&self) -> Result<Positive, PositionError> {
        Ok(self.open_fee.checked_add(&self.close_fee)?)
    }
}

impl std::fmt::Display for SpotPosition {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "{} {} {} @ {} (fees: ",
            self.side, self.quantity, self.symbol, self.cost_basis,
        )?;
        // Fees whose total leaves the `Positive` range are shown as the sum
        // they are; `Positive + Positive` aborted on them (#788).
        match self.open_fee.checked_add(&self.close_fee) {
            Ok(total) => write!(f, "{total})"),
            Err(_) => write!(f, "{} + {})", self.open_fee, self.close_fee),
        }
    }
}

#[cfg(feature = "clock")]
impl Default for SpotPosition {
    fn default() -> Self {
        Self {
            symbol: String::new(),
            quantity: Positive::ZERO,
            cost_basis: Positive::ZERO,
            side: Side::Long,
            date: wall_clock(),
            open_fee: Positive::ZERO,
            close_fee: Positive::ZERO,
        }
    }
}

#[cfg(test)]
mod tests {
    #[cfg(feature = "clock")]
    use super::*;
    #[cfg(feature = "clock")]
    use positive::pos_or_panic;

    #[cfg(feature = "clock")]
    #[test]
    fn test_spot_position_new() {
        let spot = SpotPosition::new(
            "AAPL".to_string(),
            Positive::HUNDRED,
            pos_or_panic!(150.0),
            Side::Long,
            wall_clock(),
            Positive::ONE,
            Positive::ONE,
        );

        assert_eq!(spot.symbol, "AAPL");
        assert_eq!(spot.quantity, Positive::HUNDRED);
        assert_eq!(spot.cost_basis, pos_or_panic!(150.0));
        assert_eq!(spot.side, Side::Long);
        assert_eq!(spot.open_fee, Positive::ONE);
        assert_eq!(spot.close_fee, Positive::ONE);
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_spot_position_long_convenience() {
        let spot = SpotPosition::long("BTC".to_string(), Positive::ONE, pos_or_panic!(50000.0));

        assert_eq!(spot.symbol, "BTC");
        assert_eq!(spot.quantity, Positive::ONE);
        assert_eq!(spot.cost_basis, pos_or_panic!(50000.0));
        assert_eq!(spot.side, Side::Long);
        assert_eq!(spot.open_fee, Positive::ZERO);
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_spot_position_short_convenience() {
        let spot = SpotPosition::short(
            "ETH".to_string(),
            pos_or_panic!(10.0),
            pos_or_panic!(3000.0),
        );

        assert_eq!(spot.symbol, "ETH");
        assert_eq!(spot.quantity, pos_or_panic!(10.0));
        assert_eq!(spot.cost_basis, pos_or_panic!(3000.0));
        assert_eq!(spot.side, Side::Short);
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_initial_value() {
        let spot = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        assert_eq!(spot.initial_value().ok(), Some(pos_or_panic!(15000.0)));
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_market_value() {
        let spot = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        assert_eq!(
            spot.market_value(pos_or_panic!(160.0)).ok(),
            Some(pos_or_panic!(16000.0))
        );
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_long_pnl_profit() {
        let spot = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        let pnl = spot.pnl_at_price(pos_or_panic!(160.0));
        assert_eq!(pnl.ok(), Some(Decimal::from(1000))); // (160-150) * 100
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_long_pnl_loss() {
        let spot = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        let pnl = spot.pnl_at_price(pos_or_panic!(140.0));
        assert_eq!(pnl.ok(), Some(Decimal::from(-1000))); // (140-150) * 100
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_short_pnl_profit() {
        let spot = SpotPosition::short("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        let pnl = spot.pnl_at_price(pos_or_panic!(140.0));
        assert_eq!(pnl.ok(), Some(Decimal::from(1000))); // Short profits when price drops
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_short_pnl_loss() {
        let spot = SpotPosition::short("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        let pnl = spot.pnl_at_price(pos_or_panic!(160.0));
        assert_eq!(pnl.ok(), Some(Decimal::from(-1000))); // Short loses when price rises
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_pnl_with_fees() {
        let spot = SpotPosition::new(
            "AAPL".to_string(),
            Positive::HUNDRED,
            pos_or_panic!(150.0),
            Side::Long,
            wall_clock(),
            pos_or_panic!(10.0),
            pos_or_panic!(10.0),
        );
        let pnl = spot.pnl_at_price(pos_or_panic!(160.0));
        assert_eq!(pnl.ok(), Some(Decimal::from(980))); // 1000 profit - 20 fees
    }

    /// `cost_basis` and `quantity` are `pub`, so a spot leg can hold a
    /// price difference the `Decimal` range cannot express. Before #471 the
    /// trait signature had nowhere to say so and the process aborted with
    /// `Subtraction overflowed`.
    #[cfg(feature = "clock")]
    #[test]
    fn test_spot_position_pnl_at_price_overflowing_notional_is_reported() {
        let mut spot =
            SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        spot.quantity = Positive::MAX;

        assert!(spot.pnl_at_price(Positive::MAX).is_err());
    }

    /// A long spot leg's `total_cost` multiplies size by cost basis before
    /// adding the two fees, so both steps can leave the `Positive` range.
    #[cfg(feature = "clock")]
    #[test]
    fn test_spot_position_total_cost_overflowing_notional_is_reported() {
        let mut spot = SpotPosition::long("AAPL".to_string(), Positive::MAX, Positive::MAX);
        spot.open_fee = Positive::ONE;

        assert!(spot.total_cost().is_err());
    }

    /// A short leg pays only the fees, and those still have to sum.
    #[cfg(feature = "clock")]
    #[test]
    fn test_spot_position_total_cost_overflowing_fees_is_reported() {
        let mut spot =
            SpotPosition::short("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        spot.open_fee = Positive::MAX;
        spot.close_fee = Positive::MAX;

        assert!(spot.total_cost().is_err());
        assert!(spot.fees().is_err());
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_total_cost_long() {
        let spot = SpotPosition::new(
            "AAPL".to_string(),
            Positive::HUNDRED,
            pos_or_panic!(150.0),
            Side::Long,
            wall_clock(),
            pos_or_panic!(10.0),
            pos_or_panic!(10.0),
        );
        assert_eq!(spot.total_cost().ok(), Some(pos_or_panic!(15020.0))); // 15000 + 20 fees
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_total_cost_short() {
        let spot = SpotPosition::new(
            "AAPL".to_string(),
            Positive::HUNDRED,
            pos_or_panic!(150.0),
            Side::Short,
            wall_clock(),
            pos_or_panic!(10.0),
            pos_or_panic!(10.0),
        );
        assert_eq!(spot.total_cost().ok(), Some(pos_or_panic!(20.0))); // Only fees for short
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_percentage_return_long() {
        let spot = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, Positive::HUNDRED);
        let return_pct = spot.percentage_return(pos_or_panic!(110.0));
        assert_eq!(return_pct.ok(), Some(Decimal::new(1, 1))); // 10% = 0.1
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_percentage_return_short() {
        let spot = SpotPosition::short("AAPL".to_string(), Positive::HUNDRED, Positive::HUNDRED);
        let return_pct = spot.percentage_return(pos_or_panic!(90.0));
        assert_eq!(return_pct.ok(), Some(Decimal::new(1, 1))); // 10% profit for short when price drops
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_break_even_long() {
        let spot = SpotPosition::new(
            "AAPL".to_string(),
            Positive::HUNDRED,
            pos_or_panic!(150.0),
            Side::Long,
            wall_clock(),
            pos_or_panic!(50.0),
            pos_or_panic!(50.0),
        );
        assert_eq!(spot.break_even_price().ok(), Some(pos_or_panic!(151.0))); // 150 + (100/100)
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_break_even_short() {
        let spot = SpotPosition::new(
            "AAPL".to_string(),
            Positive::HUNDRED,
            pos_or_panic!(150.0),
            Side::Short,
            wall_clock(),
            pos_or_panic!(50.0),
            pos_or_panic!(50.0),
        );
        assert_eq!(spot.break_even_price().ok(), Some(pos_or_panic!(149.0))); // 150 - (100/100)
    }

    // Each of these aborted before #788: `Positive * Positive` with
    // `Positive arithmetic overflow in mul`, the return with `Division
    // overflowed`, the fee per unit with `Positive arithmetic overflow in
    // div` and the `Display` fee total with `... in add`.
    #[cfg(feature = "clock")]
    #[test]
    fn test_extreme_values_are_errors_not_aborts() {
        let wide = SpotPosition::long("X".to_string(), Positive::MAX, Positive::TWO);
        assert!(wide.initial_value().is_err());
        assert!(wide.market_value(Positive::TWO).is_err());

        let tiny_basis = SpotPosition::long("X".to_string(), Positive::ONE, pos_or_panic!(1e-27));
        assert!(matches!(
            tiny_basis.percentage_return(Positive::MAX),
            Err(PositionError::DecimalError(_))
        ));

        let mut tiny_quantity =
            SpotPosition::long("X".to_string(), pos_or_panic!(1e-27), Positive::ONE);
        tiny_quantity.open_fee = Positive::MAX;
        assert!(tiny_quantity.break_even_price().is_err());

        tiny_quantity.close_fee = Positive::MAX;
        let shown = tiny_quantity.to_string();
        assert!(shown.ends_with(&format!("(fees: {} + {})", Positive::MAX, Positive::MAX)));
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_display() {
        let spot = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        let display = format!("{}", spot);
        assert!(display.contains("Long"));
        assert!(display.contains("AAPL"));
        assert!(display.contains("100"));
    }

    #[cfg(feature = "clock")]
    #[test]
    fn test_is_long_short() {
        let long = SpotPosition::long("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));
        let short =
            SpotPosition::short("AAPL".to_string(), Positive::HUNDRED, pos_or_panic!(150.0));

        assert!(long.is_long());
        assert!(!long.is_short());
        assert!(!short.is_long());
        assert!(short.is_short());
    }
}