Merge pull request #371 from joaquinbejar/M5/issue-335-checked-decimal-monetary

M5 #335: Audit and convert monetary Decimal arithmetic to checked helpers

Author: joaquinbejar

src/chains/chain.rs

@@ -21,6 +21,7 @@ use crate::metrics::{
     TimeDecayCurve, TimeDecaySurface, VannaVolgaSurface, VolatilitySensitivityCurve,
     VolatilitySensitivitySurface, VolatilitySkewCurve, VolumeProfileCurve, VolumeProfileSurface,
 };
+use crate::model::decimal::d_add;
 use crate::model::{
     BasicAxisTypes, ExpirationDate, OptionStyle, OptionType, Options, Position, Side,
 };
@@ -1941,7 +1942,11 @@ impl OptionChain {
     pub fn gamma_exposure(&self) -> Result<Decimal, ChainError> {
         let mut gamma_exposure = Decimal::ZERO;
         for option in &self.options {
-            gamma_exposure += option.gamma.unwrap_or(Decimal::ZERO);
+            gamma_exposure = d_add(
+                gamma_exposure,
+                option.gamma.unwrap_or(Decimal::ZERO),
+                "chains::gamma_exposure",
+            )?;
         }
         Ok(gamma_exposure)
     }
@@ -1968,8 +1973,16 @@ impl OptionChain {
     pub fn delta_exposure(&self) -> Result<Decimal, ChainError> {
         let mut delta_exposure = Decimal::ZERO;
         for option in &self.options {
-            delta_exposure += option.delta_call.unwrap_or(Decimal::ZERO);
-            delta_exposure += option.delta_put.unwrap_or(Decimal::ZERO);
+            delta_exposure = d_add(
+                delta_exposure,
+                option.delta_call.unwrap_or(Decimal::ZERO),
+                "chains::delta_exposure::call",
+            )?;
+            delta_exposure = d_add(
+                delta_exposure,
+                option.delta_put.unwrap_or(Decimal::ZERO),
+                "chains::delta_exposure::put",
+            )?;
         }
         Ok(delta_exposure)
     }
@@ -1999,11 +2012,11 @@ impl OptionChain {
             let vega = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .vega()?;
-            vega_exposure += vega;
+            vega_exposure = d_add(vega_exposure, vega, "chains::vega_exposure::call")?;
             let vega = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .vega()?;
-            vega_exposure += vega;
+            vega_exposure = d_add(vega_exposure, vega, "chains::vega_exposure::put")?;
         }
         Ok(vega_exposure)
     }
@@ -2033,11 +2046,11 @@ impl OptionChain {
             let theta = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .theta()?;
-            theta_exposure += theta;
+            theta_exposure = d_add(theta_exposure, theta, "chains::theta_exposure::call")?;
             let theta = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .theta()?;
-            theta_exposure += theta;
+            theta_exposure = d_add(theta_exposure, theta, "chains::theta_exposure::put")?;
         }
         Ok(theta_exposure)
     }
@@ -2067,11 +2080,11 @@ impl OptionChain {
             let vanna = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .vanna()?;
-            vanna_exposure += vanna;
+            vanna_exposure = d_add(vanna_exposure, vanna, "chains::vanna_exposure::call")?;
             let vanna = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .vanna()?;
-            vanna_exposure += vanna;
+            vanna_exposure = d_add(vanna_exposure, vanna, "chains::vanna_exposure::put")?;
         }
         Ok(vanna_exposure)
     }
@@ -2100,11 +2113,11 @@ impl OptionChain {
             let vomma = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .vomma()?;
-            vomma_exposure += vomma;
+            vomma_exposure = d_add(vomma_exposure, vomma, "chains::vomma_exposure::call")?;
             let vomma = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .vomma()?;
-            vomma_exposure += vomma;
+            vomma_exposure = d_add(vomma_exposure, vomma, "chains::vomma_exposure::put")?;
         }
         Ok(vomma_exposure)
     }
@@ -2133,11 +2146,11 @@ impl OptionChain {
             let veta = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .veta()?;
-            veta_exposure += veta;
+            veta_exposure = d_add(veta_exposure, veta, "chains::veta_exposure::call")?;
             let veta = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .veta()?;
-            veta_exposure += veta;
+            veta_exposure = d_add(veta_exposure, veta, "chains::veta_exposure::put")?;
         }
         Ok(veta_exposure)
     }
@@ -2167,11 +2180,11 @@ impl OptionChain {
             let charm = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .charm()?;
-            charm_exposure += charm;
+            charm_exposure = d_add(charm_exposure, charm, "chains::charm_exposure::call")?;
             let charm = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .charm()?;
-            charm_exposure += charm;
+            charm_exposure = d_add(charm_exposure, charm, "chains::charm_exposure::put")?;
         }
         Ok(charm_exposure)
     }
@@ -2201,11 +2214,11 @@ impl OptionChain {
             let color = option_data
                 .get_option(Side::Long, OptionStyle::Call)?
                 .color()?;
-            color_exposure += color;
+            color_exposure = d_add(color_exposure, color, "chains::color_exposure::call")?;
             let color = option_data
                 .get_option(Side::Long, OptionStyle::Put)?
                 .color()?;
-            color_exposure += color;
+            color_exposure = d_add(color_exposure, color, "chains::color_exposure::put")?;
         }
         Ok(color_exposure)
     }

src/error/decimal.rs

@@ -3,6 +3,7 @@
    Email: jb@taunais.com
    Date: 25/12/24
 ******************************************************************************/
+use rust_decimal::Decimal;
 use thiserror::Error;
 
 /// # Decimal Error Management
@@ -128,6 +129,33 @@ pub enum DecimalError {
     /// Expiration-date conversion error surfaced during decimal operations.
     #[error(transparent)]
     ExpirationDate(expiration_date::error::ExpirationDateError),
+
+    /// Error when a `Decimal` arithmetic operation overflows the representable range.
+    ///
+    /// Emitted by the crate-private `d_add` / `d_sub` / `d_mul` / `d_div` helpers
+    /// in [`crate::model::decimal`] when the underlying
+    /// `Decimal::checked_*` call returns `None`. The `operation` tag is a
+    /// short, static identifier describing the call-site (for example
+    /// `"pricing::black_scholes::discount_strike"`) so failures can be
+    /// traced back to their kernel without walking the call stack.
+    ///
+    /// The operands are captured verbatim for post-mortem debugging and
+    /// are included in the formatted error output (see the `#[error]`
+    /// template below). This `DecimalError` variant is propagated across
+    /// domain modules through the existing `#[from]` cascade, so the
+    /// operand values will appear in any log or wrapper-error string
+    /// produced downstream. Callers that need to redact them for
+    /// production logging should match on the `Overflow` variant
+    /// explicitly and reformat rather than rely on the default `Display`.
+    #[error("Decimal {operation} overflow: {lhs} op {rhs}")]
+    Overflow {
+        /// Short static tag identifying the call-site.
+        operation: &'static str,
+        /// Left-hand operand of the failed arithmetic.
+        lhs: Decimal,
+        /// Right-hand operand of the failed arithmetic.
+        rhs: Decimal,
+    },
 }
 
 /// A specialized `Result` type for decimal calculation operations.
@@ -285,6 +313,33 @@ impl DecimalError {
             reason: reason.to_string(),
         }
     }
+
+    /// Creates a new `Overflow` error for a failed checked arithmetic operation.
+    ///
+    /// Used by the crate-private `d_add` / `d_sub` / `d_mul` / `d_div` helpers
+    /// to surface an overflow of the underlying `Decimal::checked_*` call
+    /// with full operand context.
+    ///
+    /// # Parameters
+    ///
+    /// * `operation` - Short static tag identifying the call-site
+    ///   (for example `"pricing::black_scholes::discount_strike"`).
+    /// * `lhs` - Left-hand operand of the failed arithmetic.
+    /// * `rhs` - Right-hand operand of the failed arithmetic.
+    ///
+    /// # Returns
+    ///
+    /// A new `DecimalError::Overflow` instance.
+    #[cold]
+    #[inline(never)]
+    #[must_use]
+    pub fn overflow(operation: &'static str, lhs: Decimal, rhs: Decimal) -> Self {
+        DecimalError::Overflow {
+            operation,
+            lhs,
+            rhs,
+        }
+    }
 }
 
 impl From<expiration_date::error::ExpirationDateError> for DecimalError {
@@ -332,4 +387,31 @@ mod tests {
         assert!(matches!(error, DecimalError::InvalidPrecision { .. }));
         assert!(error.to_string().contains("non-negative"));
     }
+
+    #[test]
+    fn test_overflow_error() {
+        let error = DecimalError::overflow("test::site", Decimal::MAX, Decimal::MAX);
+        assert!(matches!(error, DecimalError::Overflow { .. }));
+        let rendered = error.to_string();
+        assert!(rendered.contains("test::site"));
+        assert!(rendered.contains("overflow"));
+    }
+
+    #[test]
+    fn test_overflow_fields() {
+        let lhs = Decimal::MAX;
+        let rhs = Decimal::from(2);
+        if let DecimalError::Overflow {
+            operation,
+            lhs: captured_lhs,
+            rhs: captured_rhs,
+        } = DecimalError::overflow("test::mul", lhs, rhs)
+        {
+            assert_eq!(operation, "test::mul");
+            assert_eq!(captured_lhs, lhs);
+            assert_eq!(captured_rhs, rhs);
+        } else {
+            panic!("expected Overflow variant");
+        }
+    }
 }

src/error/position.rs

@@ -119,6 +119,17 @@ pub enum PositionError {
     /// Errors related to position update
     #[error("Update error: {0}")]
     UpdateError(PositionUpdateErrorKind),
+
+    /// Decimal arithmetic failures propagated from monetary-flow
+    /// computations (overflow, division by zero, conversion).
+    ///
+    /// Produced when a checked Decimal helper in `model::decimal`
+    /// surfaces a [`crate::error::DecimalError`] from inside a
+    /// `Position` method (for example `pnl_at_expiration` or
+    /// `unrealized_pnl`). Propagated transparently via the
+    /// `#[from]` cascade so callers keep matching `PositionError`.
+    #[error(transparent)]
+    DecimalError(#[from] crate::error::DecimalError),
 }
 
 /// Specific errors that can occur in strategy operations

src/error/volatility.rs

@@ -126,6 +126,19 @@ pub enum VolatilityError {
     /// Positive value errors
     #[error(transparent)]
     PositiveError(#[from] positive::PositiveError),
+
+    /// Decimal arithmetic failures propagated from monetary-flow
+    /// computations in volatility kernels (overflow, division by
+    /// zero, conversion).
+    ///
+    /// Produced when a checked Decimal helper in `model::decimal`
+    /// surfaces a [`crate::error::DecimalError`] from inside a
+    /// volatility routine (for example `constant_volatility`,
+    /// `ewma_volatility`, or `garch_volatility`). Propagated
+    /// transparently via the `#[from]` cascade so callers keep
+    /// matching `VolatilityError`.
+    #[error(transparent)]
+    DecimalError(#[from] crate::error::DecimalError),
 }
 
 impl From<crate::error::ChainError> for VolatilityError {

src/greeks/equations.rs

@@ -6,6 +6,7 @@
 use crate::constants::{TRADING_DAYS, ZERO};
 use crate::error::greeks::GreeksError;
 use crate::greeks::utils::{big_n, d1, d2, n};
+use crate::model::decimal::{d_div, d_mul};
 use crate::model::types::{OptionStyle, OptionType};
 use crate::{Options, Side};
 use positive::Positive;
@@ -838,8 +839,17 @@ pub fn theta(option: &Options) -> Result<Decimal, GreeksError> {
         }
     };
 
-    // Adjust for quantity and convert to daily value
-    Ok((theta * option.quantity.to_dec()) / Decimal::from(365))
+    // Adjust for quantity and convert to daily value (banker's-rounded annualisation).
+    let weighted = d_mul(
+        theta,
+        option.quantity.to_dec(),
+        "greeks::theta::position_weighted",
+    )?;
+    Ok(d_div(
+        weighted,
+        Decimal::from(365),
+        "greeks::theta::per_day",
+    )?)
 }
 
 /// Computes the vega of an option.
@@ -1102,8 +1112,17 @@ pub fn rho(option: &Options) -> Result<Decimal, GreeksError> {
         }
     };
 
-    // Adjust for quantity and convert to basis points
-    Ok((rho * option.quantity.to_dec()) / Decimal::from(100))
+    // Adjust for quantity and convert to basis points (banker's rounding).
+    let weighted = d_mul(
+        rho,
+        option.quantity.to_dec(),
+        "greeks::rho::position_weighted",
+    )?;
+    Ok(d_div(
+        weighted,
+        Decimal::from(100),
+        "greeks::rho::per_basis_point",
+    )?)
 }
 
 /// Computes the sensitivity of the option price to changes in the dividend yield (Rho_d).
@@ -1235,7 +1254,12 @@ pub fn rho_d(option: &Options) -> Result<Decimal, GreeksError> {
     };
 
     let quantity: Decimal = option.quantity.into();
-    Ok(rhod * quantity / Decimal::from(100))
+    let weighted = d_mul(rhod, quantity, "greeks::rho_d::position_weighted")?;
+    Ok(d_div(
+        weighted,
+        Decimal::from(100),
+        "greeks::rho_d::per_basis_point",
+    )?)
 }
 
 pub fn alpha(option: &Options) -> Result<Decimal, GreeksError> {
@@ -1767,8 +1791,17 @@ pub fn charm(option: &Options) -> Result<Decimal, GreeksError> {
             (-q * exp_minus_qt * big_n(-d1)?) - (exp_minus_qt * n(d1)? * common_term)
         }
     };
-    // Adjust for quantity and convert to daily value
-    Ok((charm * option.quantity) / Decimal::from(365))
+    // Adjust for quantity and convert to daily value.
+    let weighted = d_mul(
+        charm,
+        option.quantity.to_dec(),
+        "greeks::charm::position_weighted",
+    )?;
+    Ok(d_div(
+        weighted,
+        Decimal::from(365),
+        "greeks::charm::per_day",
+    )?)
 }
 
 /// Computes the Color of an option.
@@ -1902,7 +1935,22 @@ pub fn color(option: &Options) -> Result<Decimal, GreeksError> {
     let numerator = (Decimal::TWO * (r - q) * tau) - (d2 * sigma * tau.sqrt());
     let denominator = sigma * tau.sqrt();
     let factor2 = (Decimal::TWO * q * tau) + Decimal::ONE + ((numerator / denominator) * d1);
-    let color = (-exp_minus_qt * factor1 * factor2 * option.quantity) / Decimal::from(365);
+    // Build the color numerator with checked multiplications so an
+    // overflow on `-exp(-qt) * factor1 * factor2 * quantity` surfaces
+    // a tagged `DecimalError::Overflow` instead of silently saturating
+    // before the final checked `d_div(/, 365)`.
+    let numerator = d_mul(
+        -exp_minus_qt,
+        factor1,
+        "greeks::color::numerator_exp_factor1",
+    )?;
+    let numerator = d_mul(numerator, factor2, "greeks::color::numerator_factor2")?;
+    let numerator = d_mul(
+        numerator,
+        option.quantity.to_dec(),
+        "greeks::color::numerator_quantity",
+    )?;
+    let color = d_div(numerator, Decimal::from(365), "greeks::color::per_day")?;
     Ok(color)
 }