Merge pull request #524 from abdulrcrtw/feat/sandbox-scaffold-fixtures-env

feat(devkit/sandbox): scaffold sandbox module, normal network fixture, in-memory env, and analytics docs

Author: Tinna23

packages/devkit/README.md

@@ -240,3 +240,107 @@ Benchmarks compile and run on every PR touching `packages/devkit/` via the [Devk
 [dev-dependencies]
 stellar-devkit = { path = "../devkit" }
 ```
+
+## Fee Analytics
+
+The `analytics` module provides composable, zero-dependency fee analysis functions for trend detection, volatility measurement, correlation, forecasting, and regime change detection.
+
+### Modules
+
+| Sub-module | Key exports | Description |
+|---|---|---|
+| `analytics::trend` | `analyze_trend`, `fee_velocity`, `trend_strength_score` | Linear regression trend detection and rate-of-change measurement |
+| `analytics::volatility` | `compute_volatility`, `bollinger_bands`, `coefficient_of_variation` | Standard deviation, CV, and Bollinger Bands (SMA ± 2σ) |
+| `analytics::correlation` | `pearson_correlation`, `autocorrelation`, `cross_correlation` | Pearson correlation, lag-based autocorrelation, fee-capacity correlation |
+| `analytics::forecaster` | `forecast`, `forecast_linear`, `forecast_holt`, `confidence_intervals` | Linear extrapolation, Holt double-exponential smoothing, and CI bands |
+| `analytics::regime` | `detect_regime_change`, `ks_statistic` | KS-statistic regime shift detector (flags when KS > 0.3) |
+
+### Trend Detection
+
+```rust
+use stellar_devkit::analytics::trend::{analyze_trend, fee_velocity, trend_strength_score, TrendDirection};
+
+let fees: Vec<f64> = (0..100).map(|i| 100.0 + i as f64 * 5.0).collect();
+let trend = analyze_trend(&fees);
+assert_eq!(trend.direction, TrendDirection::Upward);
+println!("R²: {:.3}", trend.r_squared);            // ~1.0 for perfect line
+println!("Strength: {:.3}", trend_strength_score(&fees)); // same as r_squared
+
+// Rate of change in stroops/sec
+let timestamped: Vec<(u64, u64)> = (0..10)
+    .map(|i| (i as u64 * 1_000, 100 + i as u64 * 50))
+    .collect();
+let velocity = fee_velocity(&timestamped, 30);
+println!("Velocity: {:.1} stroops/sec", velocity);
+```
+
+### Volatility Measures
+
+```rust
+use stellar_devkit::analytics::volatility::{compute_volatility, bollinger_bands, coefficient_of_variation};
+
+let fees: Vec<f64> = (0..200).map(|i| 200.0 + (i as f64 * 0.3).sin() * 50.0).collect();
+
+let v = compute_volatility(&fees);
+println!("Std dev: {:.2}", v.standard_deviation);
+println!("CV:      {:.4}", v.coefficient_of_variation); // scale-invariant
+
+// Standalone CV function
+let cv = coefficient_of_variation(&fees);
+
+// Bollinger Bands with window=20
+let bands = bollinger_bands(&fees, 20);
+for b in &bands {
+    assert!(b.upper_band >= b.sma && b.sma >= b.lower_band);
+}
+```
+
+### Forecasting
+
+```rust
+use stellar_devkit::analytics::forecaster::{forecast_linear, forecast_holt, confidence_intervals};
+
+let fees: Vec<f64> = (0..50).map(|i| 100.0 + i as f64 * 3.0).collect();
+
+// Linear extrapolation
+let linear = forecast_linear(&fees, 10);
+
+// Holt's double exponential smoothing (alpha=0.3, beta=0.1)
+let holt = forecast_holt(&fees, 10, 0.3, 0.1);
+
+// 80% and 95% confidence intervals around the linear forecast
+let cis = confidence_intervals(&linear, /* residual_variance= */ 25.0);
+println!("Next step: {:.1} ± {:.1} (95%)", cis[0].predicted, cis[0].upper_95 - cis[0].predicted);
+```
+
+### Regime Change Detection
+
+```rust
+use stellar_devkit::analytics::regime::detect_regime_change;
+
+// Rolling 1-hour window vs 24-hour baseline
+let fees_1h: Vec<f64>  = vec![50_000.0; 100]; // sustained spike
+let fees_24h: Vec<f64> = (0..1000).map(|_| 200.0).collect(); // normal baseline
+
+if detect_regime_change(&fees_1h, &fees_24h) {
+    println!("Regime change detected — fee distribution has fundamentally shifted");
+}
+```
+
+### Correlation
+
+```rust
+use stellar_devkit::analytics::correlation::{pearson_correlation, autocorrelation, cross_correlation};
+
+let fees: Vec<f64>    = (0..100).map(|i| 100.0 + (i as f64 * 0.2).sin() * 50.0).collect();
+let capacity: Vec<f64> = (0..100).map(|i| 0.5 + (i as f64 * 0.2).sin() * 0.3).collect();
+
+// Fee-capacity cross-correlation
+let r = cross_correlation(&fees, &capacity);
+println!("Fee-capacity Pearson r: {:.3}", r.pearson_r);
+
+// Autocorrelation at lag 5
+let ac = autocorrelation(&fees, 5);
+println!("Autocorrelation at lag 5: {:.3}", ac);
+assert_eq!(autocorrelation(&fees, 0), 1.0); // lag=0 is always 1.0
+```

packages/devkit/src/lib.rs

@@ -5,6 +5,7 @@ pub mod data_quality;
 pub mod error;
 pub mod harness;
 pub mod monitoring;
+pub mod sandbox;
 pub mod simulation;
 pub mod test_helpers;
 pub mod types;

packages/devkit/src/sandbox/environment.rs

@@ -0,0 +1,173 @@
+//! In-memory fee database for the sandbox environment.
+//!
+//! [`SandboxEnv`] holds 10,000 synthetic fee records spanning a 24-hour window
+//! covering Normal, Rising, Congested, and Spike network scenarios.
+//! No external database dependencies are required.
+
+use crate::sandbox::fixtures;
+
+/// Network regime represented by a block of fee records.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Regime {
+    /// Quiet network — fees 100–500 stroops.
+    Normal,
+    /// Fees gradually climbing above the normal band.
+    Rising,
+    /// Sustained high demand; fees significantly elevated.
+    Congested,
+    /// Short-lived burst; fees spike then recover.
+    Spike,
+}
+
+/// A single fee observation stored in the sandbox database.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct FeeRecord {
+    /// Milliseconds since the Unix epoch.
+    pub timestamp_ms: u64,
+    /// Fee amount in stroops.
+    pub fee_stroops: u64,
+    /// Network regime this record belongs to.
+    pub regime: Regime,
+}
+
+/// In-memory fee database pre-seeded with 10,000 [`FeeRecord`]s spanning 24 hours.
+///
+/// Records are partitioned evenly across four [`Regime`] scenarios so tests can
+/// exercise the full range of network behaviour without hitting live infrastructure.
+///
+/// # Example
+/// ```rust
+/// use stellar_devkit::sandbox::environment::SandboxEnv;
+///
+/// let mut env = SandboxEnv::new();
+/// assert_eq!(env.records().len(), 10_000);
+/// env.reset();
+/// assert_eq!(env.records().len(), 10_000);
+/// ```
+pub struct SandboxEnv {
+    records: Vec<FeeRecord>,
+}
+
+impl SandboxEnv {
+    /// Creates a new [`SandboxEnv`] and seeds it with 10,000 records.
+    pub fn new() -> Self {
+        let mut env = Self { records: Vec::with_capacity(10_000) };
+        env.seed();
+        env
+    }
+
+    /// Seeds the database with 10,000 fee records spanning 24 hours.
+    pub fn seed(&mut self) {
+        self.records.clear();
+        const ANCHOR_MS: u64 = 1_753_315_200_000;
+        const DAY_MS: u64 = 86_400_000;
+        let start_ms = ANCHOR_MS.saturating_sub(DAY_MS);
+        let per_regime: u64 = 2_500;
+        let regime_duration_ms = DAY_MS / 4;
+
+        let scenarios: &[(Regime, u64)] = &[
+            (Regime::Normal, 0),
+            (Regime::Rising, 1),
+            (Regime::Congested, 2),
+            (Regime::Spike, 3),
+        ];
+
+        for &(regime, quarter) in scenarios {
+            let seg_start = start_ms + quarter * regime_duration_ms;
+            let interval_ms = regime_duration_ms / per_regime;
+            for i in 0..per_regime {
+                let timestamp_ms = seg_start + i * interval_ms;
+                let fee_stroops = match regime {
+                    Regime::Normal => 100 + (i * 400 / per_regime),
+                    Regime::Rising => 400 + (i * 1_100 / per_regime),
+                    Regime::Congested => 1_000 + (i * 4_000 / per_regime),
+                    Regime::Spike => if i % 50 == 0 { 50_000 } else { 100 + (i % 50) * 4 },
+                };
+                self.records.push(FeeRecord { timestamp_ms, fee_stroops, regime });
+            }
+        }
+    }
+
+    /// Discards all records and re-seeds the database from scratch.
+    pub fn reset(&mut self) {
+        self.seed();
+    }
+
+    /// Returns a read-only slice of all fee records.
+    pub fn records(&self) -> &[FeeRecord] {
+        &self.records
+    }
+
+    /// Returns a mutable reference to the underlying record list.
+    pub fn records_mut(&mut self) -> &mut Vec<FeeRecord> {
+        &mut self.records
+    }
+
+    /// Returns only the records belonging to the given [`Regime`].
+    pub fn records_for_regime(&self, regime: Regime) -> Vec<&FeeRecord> {
+        self.records.iter().filter(|r| r.regime == regime).collect()
+    }
+
+    /// Total number of fee records currently in the database.
+    pub fn len(&self) -> usize {
+        self.records.len()
+    }
+
+    /// Returns `true` if the database contains no records.
+    pub fn is_empty(&self) -> bool {
+        self.records.is_empty()
+    }
+
+    /// Creates a [`SandboxEnv`] seeded from the normal-network fixture.
+    pub fn from_normal_fixture() -> Self {
+        let raw = fixtures::normal_network();
+        let records = raw
+            .into_iter()
+            .map(|(timestamp_ms, fee_stroops)| FeeRecord {
+                timestamp_ms,
+                fee_stroops,
+                regime: Regime::Normal,
+            })
+            .collect();
+        Self { records }
+    }
+}
+
+impl Default for SandboxEnv {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn seed_produces_10k_records() {
+        let env = SandboxEnv::new();
+        assert_eq!(env.len(), 10_000);
+    }
+
+    #[test]
+    fn each_regime_has_2500_records() {
+        let env = SandboxEnv::new();
+        for regime in [Regime::Normal, Regime::Rising, Regime::Congested, Regime::Spike] {
+            assert_eq!(env.records_for_regime(regime).len(), 2_500);
+        }
+    }
+
+    #[test]
+    fn reset_restores_10k_records() {
+        let mut env = SandboxEnv::new();
+        env.records_mut().clear();
+        env.reset();
+        assert_eq!(env.len(), 10_000);
+    }
+
+    #[test]
+    fn from_normal_fixture_has_10k_records() {
+        let env = SandboxEnv::from_normal_fixture();
+        assert_eq!(env.len(), 10_000);
+    }
+}

packages/devkit/src/sandbox/fixtures.rs

@@ -0,0 +1,56 @@
+//! Fixture generators for the sandbox.
+//!
+//! Each function returns a [`Vec`] of `(timestamp_ms, fee_stroops)` tuples
+//! representing a particular network condition. All fixtures are fully
+//! deterministic — no RNG seed is required.
+
+use std::f64::consts::PI;
+
+/// Generates 10,000 fee records representing a quiet Stellar testnet session.
+///
+/// Fees are clustered in the **100–500 stroop** range with gentle sinusoidal
+/// variation. No spike events are included. Timestamps are spaced ~8.64 seconds
+/// apart spanning exactly 24 hours.
+pub fn normal_network() -> Vec<(u64, u64)> {
+    const ANCHOR_MS: u64 = 1_753_315_200_000;
+    const COUNT: usize = 10_000;
+    const DAY_MS: u64 = 86_400_000;
+    let interval_ms = DAY_MS / COUNT as u64;
+
+    (0..COUNT)
+        .map(|i| {
+            let timestamp_ms = ANCHOR_MS + i as u64 * interval_ms;
+            let fi = i as f64;
+            let wave1 = 120.0 * (2.0 * PI * fi / 137.0).sin();
+            let wave2 = 80.0 * (2.0 * PI * fi / 89.0).sin();
+            let raw = 200.0 + wave1 + wave2;
+            let fee = (raw.round() as i64).clamp(100, 500) as u64;
+            (timestamp_ms, fee)
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn normal_network_count() {
+        assert_eq!(normal_network().len(), 10_000);
+    }
+
+    #[test]
+    fn normal_network_fees_in_range() {
+        for (_, fee) in normal_network() {
+            assert!(fee >= 100 && fee <= 500, "fee out of range: {fee}");
+        }
+    }
+
+    #[test]
+    fn normal_network_timestamps_ascending() {
+        let records = normal_network();
+        for w in records.windows(2) {
+            assert!(w[0].0 < w[1].0);
+        }
+    }
+}

packages/devkit/src/sandbox/mod.rs

@@ -0,0 +1,3 @@
+pub mod environment;
+pub mod fixtures;
+pub mod runner;

packages/devkit/src/sandbox/runner.rs

@@ -0,0 +1,23 @@
+//! Synchronous test runner for the sandbox environment.
+
+use crate::sandbox::environment::SandboxEnv;
+
+/// Runs `f` with a freshly-seeded [`SandboxEnv`] and returns its result.
+pub fn run<F, T>(f: F) -> T
+where
+    F: FnOnce(&SandboxEnv) -> T,
+{
+    let env = SandboxEnv::new();
+    f(&env)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn run_receives_seeded_env() {
+        let count = run(|env| env.len());
+        assert_eq!(count, 10_000);
+    }
+}