hyper_strategy/

grid_trading.rs

use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// #226 — Grid Trading State
// ---------------------------------------------------------------------------

/// How grid line spacing is calculated.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GridSpacing {
    /// Fixed percentage between consecutive grid lines.
    Fixed(f64),
    /// ATR multiplier between consecutive grid lines.
    AtrBased(f64),
}

/// Side of a grid line order.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GridSide {
    Buy,
    Sell,
}

/// A signal emitted when a grid line is crossed.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GridSignal {
    pub price: f64,
    pub side: GridSide,
    pub line_index: usize,
}

/// A single line in the grid.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GridLine {
    pub price: f64,
    pub side: GridSide,
    pub filled: bool,
    pub fill_price: Option<f64>,
}

/// State for a grid trading strategy.
///
/// The grid is symmetric around `center_price`.  Lines below the center
/// are **Buy** orders; lines above are **Sell** orders.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GridState {
    pub center_price: f64,
    pub grid_lines: Vec<GridLine>,
    pub spacing: GridSpacing,
    pub active: bool,
}

impl GridState {
    /// Create a new symmetric grid around `center`.
    ///
    /// `num_lines` is the number of lines *per side* (so total lines = 2 × num_lines).
    ///
    /// For `GridSpacing::Fixed(pct)`, each line is spaced `center * pct / 100`
    /// apart.  For `GridSpacing::AtrBased(mult)`, the spacing is `atr * mult`
    /// (requires `atr` to be `Some`).
    pub fn new(center: f64, num_lines: u8, spacing: GridSpacing, atr: Option<f64>) -> Self {
        let step = match &spacing {
            GridSpacing::Fixed(pct) => center * pct / 100.0,
            GridSpacing::AtrBased(mult) => {
                let atr_val = atr.unwrap_or(0.0);
                atr_val * mult
            }
        };

        let mut grid_lines = Vec::with_capacity(num_lines as usize * 2);

        // Buy lines below center (closest to center first)
        for i in 1..=num_lines {
            let price = center - step * i as f64;
            grid_lines.push(GridLine {
                price,
                side: GridSide::Buy,
                filled: false,
                fill_price: None,
            });
        }

        // Sell lines above center (closest to center first)
        for i in 1..=num_lines {
            let price = center + step * i as f64;
            grid_lines.push(GridLine {
                price,
                side: GridSide::Sell,
                filled: false,
                fill_price: None,
            });
        }

        Self {
            center_price: center,
            grid_lines,
            spacing,
            active: true,
        }
    }

    /// Check which unfilled grid lines have been crossed by the current price
    /// and mark them as filled.
    ///
    /// Returns signals for each newly filled line.
    pub fn check_fills(&mut self, current_price: f64) -> Vec<GridSignal> {
        let mut signals = Vec::new();

        for (idx, line) in self.grid_lines.iter_mut().enumerate() {
            if line.filled {
                continue;
            }

            let triggered = match line.side {
                GridSide::Buy => current_price <= line.price,
                GridSide::Sell => current_price >= line.price,
            };

            if triggered {
                line.filled = true;
                line.fill_price = Some(current_price);
                signals.push(GridSignal {
                    price: line.price,
                    side: line.side.clone(),
                    line_index: idx,
                });
            }
        }

        signals
    }

    /// Whether the price has moved far enough from center to warrant a reset.
    ///
    /// Returns `true` if `|current_price − center| / center > threshold_pct / 100`.
    pub fn should_reset(&self, current_price: f64, threshold_pct: f64) -> bool {
        if self.center_price == 0.0 {
            return false;
        }
        let deviation = (current_price - self.center_price).abs() / self.center_price;
        deviation > threshold_pct / 100.0
    }

    /// Reset the grid around a new center price, clearing all fills.
    pub fn reset(&mut self, new_center: f64, atr: Option<f64>) {
        let num_lines = (self.grid_lines.len() / 2) as u8;
        let new_grid = Self::new(new_center, num_lines, self.spacing.clone(), atr);
        self.center_price = new_grid.center_price;
        self.grid_lines = new_grid.grid_lines;
    }

    /// Count of unfilled grid lines.
    pub fn unfilled_count(&self) -> usize {
        self.grid_lines.iter().filter(|l| !l.filled).count()
    }

    /// Count of filled grid lines.
    pub fn filled_count(&self) -> usize {
        self.grid_lines.iter().filter(|l| l.filled).count()
    }

    /// Total number of grid lines.
    pub fn total_lines(&self) -> usize {
        self.grid_lines.len()
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    // --- Construction ---

    #[test]
    fn test_new_fixed_spacing() {
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        // 3 buy + 3 sell = 6 lines
        assert_eq!(g.grid_lines.len(), 6);
        assert_eq!(g.center_price, 100.0);
        assert!(g.active);
    }

    #[test]
    fn test_new_fixed_spacing_prices() {
        // center=100, 1% spacing → step = 1.0
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);

        // Buy lines: 99, 98, 97
        let buys: Vec<f64> = g
            .grid_lines
            .iter()
            .filter(|l| l.side == GridSide::Buy)
            .map(|l| l.price)
            .collect();
        assert_eq!(buys.len(), 3);
        assert!((buys[0] - 99.0).abs() < 1e-10);
        assert!((buys[1] - 98.0).abs() < 1e-10);
        assert!((buys[2] - 97.0).abs() < 1e-10);

        // Sell lines: 101, 102, 103
        let sells: Vec<f64> = g
            .grid_lines
            .iter()
            .filter(|l| l.side == GridSide::Sell)
            .map(|l| l.price)
            .collect();
        assert_eq!(sells.len(), 3);
        assert!((sells[0] - 101.0).abs() < 1e-10);
        assert!((sells[1] - 102.0).abs() < 1e-10);
        assert!((sells[2] - 103.0).abs() < 1e-10);
    }

    #[test]
    fn test_new_atr_spacing() {
        // ATR = 5.0, multiplier = 2.0 → step = 10.0
        let g = GridState::new(100.0, 2, GridSpacing::AtrBased(2.0), Some(5.0));
        assert_eq!(g.grid_lines.len(), 4);

        let buys: Vec<f64> = g
            .grid_lines
            .iter()
            .filter(|l| l.side == GridSide::Buy)
            .map(|l| l.price)
            .collect();
        assert!((buys[0] - 90.0).abs() < 1e-10); // 100 - 10
        assert!((buys[1] - 80.0).abs() < 1e-10); // 100 - 20

        let sells: Vec<f64> = g
            .grid_lines
            .iter()
            .filter(|l| l.side == GridSide::Sell)
            .map(|l| l.price)
            .collect();
        assert!((sells[0] - 110.0).abs() < 1e-10); // 100 + 10
        assert!((sells[1] - 120.0).abs() < 1e-10); // 100 + 20
    }

    #[test]
    fn test_new_atr_spacing_no_atr_gives_zero_step() {
        let g = GridState::new(100.0, 2, GridSpacing::AtrBased(2.0), None);
        // All lines at center since step = 0
        for line in &g.grid_lines {
            assert!((line.price - 100.0).abs() < 1e-10);
        }
    }

    #[test]
    fn test_new_zero_lines() {
        let g = GridState::new(100.0, 0, GridSpacing::Fixed(1.0), None);
        assert!(g.grid_lines.is_empty());
    }

    #[test]
    fn test_all_lines_start_unfilled() {
        let g = GridState::new(100.0, 5, GridSpacing::Fixed(1.0), None);
        for line in &g.grid_lines {
            assert!(!line.filled);
            assert!(line.fill_price.is_none());
        }
    }

    // --- check_fills ---

    #[test]
    fn test_check_fills_buy_triggered() {
        let mut g = GridState::new(100.0, 2, GridSpacing::Fixed(1.0), None);
        // Buy lines at 99 and 98. Price drops to 98.5 → triggers 99 only
        let signals = g.check_fills(98.5);
        assert_eq!(signals.len(), 1);
        assert_eq!(signals[0].side, GridSide::Buy);
        assert!((signals[0].price - 99.0).abs() < 1e-10);
    }

    #[test]
    fn test_check_fills_multiple_buys() {
        let mut g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        // Price drops to 97 → triggers all 3 buy lines (99, 98, 97)
        let signals = g.check_fills(97.0);
        let buy_signals: Vec<_> = signals.iter().filter(|s| s.side == GridSide::Buy).collect();
        assert_eq!(buy_signals.len(), 3);
    }

    #[test]
    fn test_check_fills_sell_triggered() {
        let mut g = GridState::new(100.0, 2, GridSpacing::Fixed(1.0), None);
        // Sell lines at 101, 102. Price rises to 101.5 → triggers 101
        let signals = g.check_fills(101.5);
        let sell_signals: Vec<_> = signals
            .iter()
            .filter(|s| s.side == GridSide::Sell)
            .collect();
        assert_eq!(sell_signals.len(), 1);
        assert!((sell_signals[0].price - 101.0).abs() < 1e-10);
    }

    #[test]
    fn test_check_fills_no_double_fill() {
        let mut g = GridState::new(100.0, 2, GridSpacing::Fixed(1.0), None);
        let signals1 = g.check_fills(98.0); // triggers buy lines 99, 98
        assert_eq!(signals1.len(), 2);

        let signals2 = g.check_fills(97.0); // already filled lines should not re-trigger
                                            // Only buy lines were at 99, 98. No line at 97.
        assert_eq!(signals2.len(), 0);
    }

    #[test]
    fn test_check_fills_records_fill_price() {
        let mut g = GridState::new(100.0, 1, GridSpacing::Fixed(1.0), None);
        g.check_fills(98.5); // triggers buy at 99, fill at 98.5
        let buy_line = g
            .grid_lines
            .iter()
            .find(|l| l.side == GridSide::Buy)
            .unwrap();
        assert!(buy_line.filled);
        assert_eq!(buy_line.fill_price, Some(98.5));
    }

    #[test]
    fn test_check_fills_at_center_no_triggers() {
        let mut g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        let signals = g.check_fills(100.0);
        assert!(signals.is_empty());
    }

    // --- should_reset ---

    #[test]
    fn test_should_reset_within_threshold() {
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        // 5% threshold, price at 104 → deviation = 4% < 5%
        assert!(!g.should_reset(104.0, 5.0));
    }

    #[test]
    fn test_should_reset_beyond_threshold() {
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        // 5% threshold, price at 106 → deviation = 6% > 5%
        assert!(g.should_reset(106.0, 5.0));
    }

    #[test]
    fn test_should_reset_below_center() {
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        // Price at 93 → deviation = 7% > 5%
        assert!(g.should_reset(93.0, 5.0));
    }

    #[test]
    fn test_should_reset_at_exact_threshold() {
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        // At exactly 5%, should NOT reset (uses > not >=)
        assert!(!g.should_reset(105.0, 5.0));
    }

    #[test]
    fn test_should_reset_zero_center() {
        let mut g = GridState::new(100.0, 1, GridSpacing::Fixed(1.0), None);
        g.center_price = 0.0;
        assert!(!g.should_reset(50.0, 5.0));
    }

    // --- reset ---

    #[test]
    fn test_reset_rebuilds_grid() {
        let mut g = GridState::new(100.0, 2, GridSpacing::Fixed(1.0), None);
        g.check_fills(98.0); // fill some lines
        assert!(g.filled_count() > 0);

        g.reset(110.0, None);
        assert_eq!(g.center_price, 110.0);
        assert_eq!(g.unfilled_count(), 4); // all unfilled
        assert_eq!(g.filled_count(), 0);

        // Check new prices
        let buys: Vec<f64> = g
            .grid_lines
            .iter()
            .filter(|l| l.side == GridSide::Buy)
            .map(|l| l.price)
            .collect();
        // New step = 110 * 1% = 1.1
        assert!((buys[0] - (110.0 - 1.1)).abs() < 1e-10);
    }

    #[test]
    fn test_reset_preserves_num_lines() {
        let mut g = GridState::new(100.0, 5, GridSpacing::Fixed(2.0), None);
        assert_eq!(g.total_lines(), 10);
        g.reset(200.0, None);
        assert_eq!(g.total_lines(), 10);
    }

    // --- unfilled_count / filled_count ---

    #[test]
    fn test_unfilled_count_all_unfilled() {
        let g = GridState::new(100.0, 3, GridSpacing::Fixed(1.0), None);
        assert_eq!(g.unfilled_count(), 6);
        assert_eq!(g.filled_count(), 0);
    }

    #[test]
    fn test_counts_after_fills() {
        let mut g = GridState::new(100.0, 2, GridSpacing::Fixed(1.0), None);
        g.check_fills(98.0); // triggers both buy lines (99, 98)
        assert_eq!(g.filled_count(), 2);
        assert_eq!(g.unfilled_count(), 2); // sell lines still unfilled
    }

    // --- Serialization ---

    #[test]
    fn test_grid_state_serialization_roundtrip() {
        let mut g = GridState::new(100.0, 2, GridSpacing::Fixed(1.5), None);
        g.check_fills(98.0);

        let json = serde_json::to_string(&g).unwrap();
        let parsed: GridState = serde_json::from_str(&json).unwrap();

        assert_eq!(parsed.center_price, 100.0);
        assert_eq!(parsed.grid_lines.len(), 4);
        assert!(parsed.active);
        assert_eq!(parsed.spacing, GridSpacing::Fixed(1.5));
        assert_eq!(parsed.filled_count(), g.filled_count());
    }

    #[test]
    fn test_grid_spacing_serialization() {
        let fixed = GridSpacing::Fixed(1.5);
        let json = serde_json::to_string(&fixed).unwrap();
        let parsed: GridSpacing = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, GridSpacing::Fixed(1.5));

        let atr = GridSpacing::AtrBased(2.0);
        let json = serde_json::to_string(&atr).unwrap();
        let parsed: GridSpacing = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, GridSpacing::AtrBased(2.0));
    }

    #[test]
    fn test_grid_side_serialization() {
        let buy_json = serde_json::to_string(&GridSide::Buy).unwrap();
        assert_eq!(buy_json, "\"buy\"");
        let sell_json = serde_json::to_string(&GridSide::Sell).unwrap();
        assert_eq!(sell_json, "\"sell\"");
    }

    // --- Integration scenario ---

    #[test]
    fn test_full_grid_scenario() {
        // Create grid at 1000 with 2% spacing, 3 lines per side
        let mut g = GridState::new(1000.0, 3, GridSpacing::Fixed(2.0), None);
        // step = 1000 * 2 / 100 = 20
        // Buy: 980, 960, 940
        // Sell: 1020, 1040, 1060
        assert_eq!(g.total_lines(), 6);
        assert_eq!(g.unfilled_count(), 6);

        // Price drops to 975 → fills buy at 980
        let signals = g.check_fills(975.0);
        assert_eq!(signals.len(), 1);
        assert_eq!(signals[0].side, GridSide::Buy);

        // Price drops further to 955 → fills buy at 960
        let signals = g.check_fills(955.0);
        assert_eq!(signals.len(), 1);

        // Price bounces to 1025 → fills sell at 1020
        let signals = g.check_fills(1025.0);
        assert_eq!(signals.len(), 1);
        assert_eq!(signals[0].side, GridSide::Sell);

        assert_eq!(g.filled_count(), 3);
        assert_eq!(g.unfilled_count(), 3);

        // Price moves far → should reset
        assert!(g.should_reset(1100.0, 5.0)); // 10% deviation > 5%

        // Reset at new center
        g.reset(1100.0, None);
        assert_eq!(g.filled_count(), 0);
        assert_eq!(g.center_price, 1100.0);
    }
}