hypercall_engine/

fee.rs

//! Fee calculation service for trading fees.
//!
//! This module provides fee calculation functionality including:
//! - Maker/taker fee calculation based on configurable BPS rates
//! - Builder code fee calculation (share of taker fee)
//!
//! All calculations are pure math with no external dependencies.

use hypercall_types::{WalletAddress, CONTRACT_UNIT_MULTIPLIER};
use rust_decimal::Decimal;

/// Configuration for fee calculation.
#[derive(Debug, Clone)]
pub struct FeeConfig {
    /// Maker fee in basis points (e.g., 0.5 = 0.005%)
    pub maker_fee_bps: f64,
    /// Taker fee in basis points (e.g., 2.0 = 0.02%)
    pub taker_fee_bps: f64,
    /// Percentage of taker fee that goes to builder code (e.g., 0.10 = 10%)
    pub builder_code_share_pct: f64,
}

impl Default for FeeConfig {
    fn default() -> Self {
        Self {
            maker_fee_bps: 0.0,
            taker_fee_bps: 0.0,
            builder_code_share_pct: 0.0,
        }
    }
}

/// Result of fee calculation.
#[derive(Debug, Clone)]
pub struct FeeCalculation {
    /// Fee charged to the maker
    pub maker_fee: f64,
    /// Fee charged to the taker
    pub taker_fee: f64,
    /// Fee paid to builder code (deducted from platform revenue, not additional to taker)
    pub builder_code_fee: Option<Decimal>,
}

/// Service for calculating trading fees.
#[derive(Debug, Clone)]
pub struct FeeService {
    config: FeeConfig,
}

impl FeeService {
    /// Create a new FeeService with the given configuration.
    pub fn new(config: FeeConfig) -> Self {
        Self { config }
    }

    /// Calculate fees for a trade.
    ///
    /// # Arguments
    /// * `_maker_account` - Maker's account address (reserved for future tier-based fees)
    /// * `_taker_account` - Taker's account address (reserved for future tier-based fees)
    /// * `price` - Trade price
    /// * `size` - Trade size in contract units
    /// * `builder_code_address` - Optional builder code address for fee sharing
    ///
    /// # Returns
    /// FeeCalculation containing maker_fee, taker_fee, and optional builder_code_fee
    pub fn get_fees(
        &self,
        _maker_account: &str,
        _taker_account: &str,
        price: f64,
        size: u64,
        builder_code_address: Option<&WalletAddress>,
    ) -> FeeCalculation {
        // Convert size from contract units to human-readable
        let size_human = size as f64 / CONTRACT_UNIT_MULTIPLIER;

        // Calculate notional value
        let notional = price * size_human;

        // Calculate fees in basis points (1 bps = 0.01% = 0.0001)
        let maker_fee = notional * self.config.maker_fee_bps / 10_000.0;
        let taker_fee = notional * self.config.taker_fee_bps / 10_000.0;

        // Calculate builder code fee if builder code exists
        // Builder code fee is a share of taker fee (deducted from platform revenue)
        let builder_code_fee = if builder_code_address.is_some()
            && taker_fee > 0.0
            && self.config.builder_code_share_pct > 0.0
        {
            Decimal::from_f64_retain(taker_fee * self.config.builder_code_share_pct)
        } else {
            None
        };

        FeeCalculation {
            maker_fee,
            taker_fee,
            builder_code_fee,
        }
    }

    /// Get the current fee configuration.
    pub fn config(&self) -> &FeeConfig {
        &self.config
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::str::FromStr;

    #[test]
    fn test_fee_calculation_basic() {
        let service = FeeService::new(FeeConfig {
            maker_fee_bps: 0.5,
            taker_fee_bps: 2.0,
            builder_code_share_pct: 0.10,
        });

        // Trade: price = 100.0, size = 1_000_000 (1.0 contract)
        // Notional = 100.0 * 1.0 = 100.0
        // Maker fee = 100.0 * 0.5 / 10000 = 0.005
        // Taker fee = 100.0 * 2.0 / 10000 = 0.02
        let result = service.get_fees("maker", "taker", 100.0, 1_000_000, None);

        assert!((result.maker_fee - 0.005).abs() < 1e-10);
        assert!((result.taker_fee - 0.02).abs() < 1e-10);
        assert!(result.builder_code_fee.is_none());
    }

    #[test]
    fn test_fee_calculation_with_builder_code() {
        let service = FeeService::new(FeeConfig {
            maker_fee_bps: 0.5,
            taker_fee_bps: 2.0,
            builder_code_share_pct: 0.10,
        });

        // Trade: price = 100.0, size = 1_000_000 (1.0 contract)
        // Taker fee = 0.02
        // Builder code fee = 0.02 * 0.10 = 0.002
        let builder_code =
            WalletAddress::from_str("0x1234567890123456789012345678901234567890").unwrap();
        let result = service.get_fees("maker", "taker", 100.0, 1_000_000, Some(&builder_code));

        assert!((result.maker_fee - 0.005).abs() < 1e-10);
        assert!((result.taker_fee - 0.02).abs() < 1e-10);
        assert!(result.builder_code_fee.is_some());
        assert_eq!(
            result.builder_code_fee.unwrap(),
            Decimal::from_f64_retain(0.002).unwrap()
        );
    }

    #[test]
    fn test_fee_calculation_zero_size() {
        let service = FeeService::new(FeeConfig {
            maker_fee_bps: 0.5,
            taker_fee_bps: 2.0,
            builder_code_share_pct: 0.10,
        });

        let result = service.get_fees("maker", "taker", 100.0, 0, None);

        assert_eq!(result.maker_fee, 0.0);
        assert_eq!(result.taker_fee, 0.0);
        assert!(result.builder_code_fee.is_none());
    }

    #[test]
    fn test_fee_calculation_large_notional() {
        let service = FeeService::new(FeeConfig {
            maker_fee_bps: 0.5,
            taker_fee_bps: 2.0,
            builder_code_share_pct: 0.10,
        });

        // Trade: price = 50000.0 (BTC), size = 10_000_000 (10.0 BTC)
        // Notional = 50000.0 * 10.0 = 500000.0
        // Maker fee = 500000.0 * 0.5 / 10000 = 25.0
        // Taker fee = 500000.0 * 2.0 / 10000 = 100.0
        let result = service.get_fees("maker", "taker", 50000.0, 10_000_000, None);

        assert!((result.maker_fee - 25.0).abs() < 1e-10);
        assert!((result.taker_fee - 100.0).abs() < 1e-10);
    }

    #[test]
    fn test_default_config() {
        let config = FeeConfig::default();

        assert_eq!(config.maker_fee_bps, 0.0);
        assert_eq!(config.taker_fee_bps, 0.0);
        assert_eq!(config.builder_code_share_pct, 0.0);
    }

    #[test]
    fn test_default_config_disables_builder_code_fee() {
        let service = FeeService::new(FeeConfig::default());
        let builder_code =
            WalletAddress::from_str("0x1234567890123456789012345678901234567890").unwrap();

        let result = service.get_fees("maker", "taker", 100.0, 1_000_000, Some(&builder_code));

        assert_eq!(result.maker_fee, 0.0);
        assert_eq!(result.taker_fee, 0.0);
        assert!(result.builder_code_fee.is_none());
    }
}