Implement Week 1: State Monotonicity Check (CRITICAL)

Added high-water mark system to prevent state rollbacks:

New module: crates/ultradag-coin/src/persistence/monotonicity.rs
- HighWaterMark struct tracks highest round ever finalized
- Stores round number, timestamp, and state hash
- verify_monotonic() checks new_round >= max_round
- Atomic file operations for persistence
- 8 comprehensive unit tests (all passing)

Integration in main.rs load_state():
- Load high-water mark on startup
- Verify monotonicity before loading DAG state
- Exit with detailed error message if rollback detected
- Prevents loading old state files that would cause rollback

Integration in validator.rs:
- Update high-water mark after each finalized round
- Store state hash for verification
- Atomic save to disk

Error handling:
- Detailed error messages explaining rollback detection
- Lists possible causes (old deployment, backup restore, corruption)
- Provides recovery instructions
- Refuses to start if r- Refuses to start if r- Refuses to start if r- Refuses to start if r- Refuses toom
ever happening again. Node will refuse to start if attemptever happening again. Node will refuse to start iplan: COMPLETE ✅
Next: Week 2 - Peer state verification

Author: UltraDAGcom

Cargo.lock

@@ -16,3 +16,4 @@ thiserror = { workspace = true }
 
 [dev-dependencies]
 serde_json = "1"
+tempfile = "3"

crates/ultradag-coin/Cargo.toml

@@ -2,6 +2,8 @@ use std::fs;
 use std::path::Path;
 use serde::{Serialize, Deserialize};
 
+pub mod monotonicity;
+
 /// Persistence error types
 #[derive(Debug, thiserror::Error)]
 pub enum PersistenceError {
@@ -20,6 +22,14 @@ pub fn save<T: Serialize>(data: &T, path: &Path) -> Result<(), PersistenceError>
     Ok(())
 }
 
+/// Atomic write of raw bytes (used by monotonicity module)
+pub fn atomic_write(path: &Path, data: &[u8]) -> std::io::Result<()> {
+    let tmp_path = path.with_extension("tmp");
+    fs::write(&tmp_path, data)?;
+    fs::rename(&tmp_path, path)?;
+    Ok(())
+}
+
 /// Load data from disk
 pub fn load<T: for<'de> Deserialize<'de>>(path: &Path) -> Result<T, PersistenceError> {
     let json = fs::read_to_string(path)?;

crates/ultradag-coin/src/persistence.rs

@@ -0,0 +1,205 @@
+use std::path::{Path, PathBuf};
+use std::fs;
+use serde::{Serialize, Deserialize};
+use thiserror::Error;
+
+use crate::persistence::atomic_write;
+
+#[derive(Debug, Error)]
+pub enum MonotonicityError {
+    #[error("State rollback detected: attempting to load round {attempting} but high-water mark is {current}")]
+    StateRollbackDetected {
+        current: u64,
+        attempting: u64,
+    },
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+    #[error("Serialization error: {0}")]
+    Serialization(#[from] serde_json::Error),
+}
+
+/// High-water mark tracking the highest round ever finalized.
+/// This prevents loading old state files that would cause a rollback.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HighWaterMark {
+    /// Highest round number ever finalized
+    pub max_round: u64,
+    /// Timestamp when this round was reached (Unix timestamp)
+    pub timestamp: i64,
+    /// Blake3 hash of the state at this round (for verification)
+    pub state_hash: [u8; 32],
+}
+
+impl HighWaterMark {
+    /// Create a new high-water mark at genesis
+    pub fn new() -> Self {
+        Self {
+            max_round: 0,
+            timestamp: chrono::Utc::now().timestamp(),
+            state_hash: [0; 32],
+        }
+    }
+
+    /// Load from disk or create new if doesn't exist
+    pub fn load_or_create(path: &Path) -> Result<Self, MonotonicityError> {
+        if path.exists() {
+            let data = fs::read(path)?;
+            let hwm: HighWaterMark = serde_json::from_slice(&data)?;
+            Ok(hwm)
+        } else {
+            Ok(Self::new())
+        }
+    }
+
+    /// Verify that new_round is >= max_round (monotonicity check)
+    /// Returns error if attempting to go backwards
+    pub fn verify_monotonic(&self, new_round: u64) -> Result<(), MonotonicityError> {
+        if new_round < self.max_round {
+            return Err(MonotonicityError::StateRollbackDetected {
+                current: self.max_round,
+                attempting: new_round,
+            });
+        }
+        Ok(())
+    }
+
+    /// Update to new high-water mark
+    /// Only updates if new round is >= current max
+    pub fn update(&mut self, round: u64, state_hash: [u8; 32]) {
+        if round >= self.max_round {
+            self.max_round = round;
+            self.timestamp = chrono::Utc::now().timestamp();
+            self.state_hash = state_hash;
+        }
+    }
+
+    /// Save to disk atomically
+    pub fn save(&self, path: &Path) -> Result<(), MonotonicityError> {
+        let data = serde_json::to_vec_pretty(self)?;
+        atomic_write(path, &data)?;
+        Ok(())
+    }
+
+    /// Get the current high-water mark round
+    pub fn current_round(&self) -> u64 {
+        self.max_round
+    }
+
+    /// Get the path for the high-water mark file in a data directory
+    pub fn path_in_dir(data_dir: &Path) -> PathBuf {
+        data_dir.join("high_water_mark.json")
+    }
+}
+
+impl Default for HighWaterMark {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_new_high_water_mark() {
+        let hwm = HighWaterMark::new();
+        assert_eq!(hwm.max_round, 0);
+        assert_eq!(hwm.state_hash, [0; 32]);
+    }
+
+    #[test]
+    fn test_verify_monotonic_allows_forward() {
+        let hwm = HighWaterMark {
+            max_round: 100,
+            timestamp: 0,
+            state_hash: [0; 32],
+        };
+
+        assert!(hwm.verify_monotonic(100).is_ok());
+        assert!(hwm.verify_monotonic(101).is_ok());
+        assert!(hwm.verify_monotonic(1000).is_ok());
+    }
+
+    #[test]
+    fn test_verify_monotonic_rejects_backward() {
+        let hwm = HighWaterMark {
+            max_round: 100,
+            timestamp: 0,
+            state_hash: [0; 32],
+        };
+
+        let result = hwm.verify_monotonic(99);
+        assert!(result.is_err());
+        
+        if let Err(MonotonicityError::StateRollbackDetected { current, attempting }) = result {
+            assert_eq!(current, 100);
+            assert_eq!(attempting, 99);
+        } else {
+            panic!("Expected StateRollbackDetected error");
+        }
+    }
+
+    #[test]
+    fn test_update_advances_forward() {
+        let mut hwm = HighWaterMark::new();
+        let hash1 = [1; 32];
+        let hash2 = [2; 32];
+
+        hwm.update(50, hash1);
+        assert_eq!(hwm.max_round, 50);
+        assert_eq!(hwm.state_hash, hash1);
+
+        hwm.update(100, hash2);
+        assert_eq!(hwm.max_round, 100);
+        assert_eq!(hwm.state_hash, hash2);
+    }
+
+    #[test]
+    fn test_update_ignores_backward() {
+        let mut hwm = HighWaterMark {
+            max_round: 100,
+            timestamp: 0,
+            state_hash: [1; 32],
+        };
+
+        let hash2 = [2; 32];
+        hwm.update(50, hash2);
+        
+        // Should not update
+        assert_eq!(hwm.max_round, 100);
+        assert_eq!(hwm.state_hash, [1; 32]);
+    }
+
+    #[test]
+    fn test_save_and_load() {
+        let temp_dir = TempDir::new().unwrap();
+        let path = temp_dir.path().join("hwm.json");
+
+        let mut hwm = HighWaterMark::new();
+        hwm.update(42, [7; 32]);
+        hwm.save(&path).unwrap();
+
+        let loaded = HighWaterMark::load_or_create(&path).unwrap();
+        assert_eq!(loaded.max_round, 42);
+        assert_eq!(loaded.state_hash, [7; 32]);
+    }
+
+    #[test]
+    fn test_load_or_create_when_missing() {
+        let temp_dir = TempDir::new().unwrap();
+        let path = temp_dir.path().join("missing.json");
+
+        let hwm = HighWaterMark::load_or_create(&path).unwrap();
+        assert_eq!(hwm.max_round, 0);
+    }
+
+    #[test]
+    fn test_path_in_dir() {
+        let dir = Path::new("/data");
+        let path = HighWaterMark::path_in_dir(dir);
+        assert_eq!(path, Path::new("/data/high_water_mark.json"));
+    }
+}

crates/ultradag-coin/src/persistence/monotonicity.rs

@@ -120,17 +120,65 @@ async fn save_state(server: &NodeServer, data_dir: &std::path::Path) {
 
 /// Load all node state from disk if available.
 async fn load_state(server: &NodeServer, data_dir: &std::path::Path) {
+    use ultradag_coin::persistence::monotonicity::HighWaterMark;
+    
     let dag_path = data_dir.join("dag.json");
     let finality_path = data_dir.join("finality.json");
     let state_path = data_dir.join("state.json");
     let mempool_path = data_dir.join("mempool.json");
+    let hwm_path = HighWaterMark::path_in_dir(data_dir);
 
     info!("Loading state from: {}", data_dir.display());
 
+    // Load high-water mark for monotonicity checking
+    let hwm = match HighWaterMark::load_or_create(&hwm_path) {
+        Ok(hwm) => {
+            if hwm.current_round() > 0 {
+                info!("High-water mark: round {}", hwm.current_round());
+            }
+            hwm
+        }
+        Err(e) => {
+            error!("Failed to load high-water mark: {}", e);
+            error!("Cannot verify state monotonicity. Refusing to start.");
+            std::process::exit(1);
+        }
+    };
+
     if BlockDag::exists(&dag_path) {
         match BlockDag::load(&dag_path) {
             Ok(dag) => {
                 let current_round = dag.current_round();
+                
+                // CRITICAL: Verify monotonicity - prevent rollback
+                if let Err(e) = hwm.verify_monotonic(current_round) {
+                    error!("╔═══════════════════════════════════════════════════════╗");
+                    error!("║  🚨 STATE ROLLBACK DETECTED - REFUSING TO START 🚨   ║");
+                    error!("╚═══════════════════════════════════════════════════════╝");
+                    error!("");
+                    error!("Error: {}", e);
+                    error!("High-water mark: round {}", hwm.current_round());
+                    error!("Attempting to load: round {}", current_round);
+                    error!("Rollback amount: {} rounds", hwm.current_round() - current_round);
+                    error!("");
+                    error!("This indicates you are trying to load an old state file.");
+                    error!("Loading old state would cause a network rollback.");
+                    error!("");
+                    error!("POSSIBLE CAUSES:");
+                    error!("1. Deployment with old Docker image");
+                    error!("2. Restored from old backup");
+                    error!("3. State file corruption");
+                    error!("");
+                    error!("MANUAL INTERVENTION REQUIRED:");
+                    error!("1. Verify the state file is correct");
+                    error!("2. Check deployment configuration");
+                    error!("3. Consider fast-sync from network");
+                    error!("");
+                    error!("DO NOT bypass this check unless you understand the consequences.");
+                    std::process::exit(1);
+                }
+                
+                info!("✅ Monotonicity check passed: round {}", current_round);
                 info!("Loaded DAG from disk: current_round={}", current_round);
                 *server.dag.write().await = dag;
             }

crates/ultradag-node/src/main.rs

@@ -251,6 +251,28 @@ pub async fn validator_loop(
                 if let Err(e) = state_w.apply_finalized_vertices(&finalized_vertices) {
                     warn!("Failed to apply finalized vertices to state: {}", e);
                 } else {
+                    // Update high-water mark after successful finalization
+                    let last_finalized_round = state_w.last_finalized_round().unwrap_or(0);
+                    if last_finalized_round > 0 {
+                        use ultradag_coin::persistence::monotonicity::HighWaterMark;
+                        let hwm_path = HighWaterMark::path_in_dir(&data_dir);
+                        
+                        match HighWaterMark::load_or_create(&hwm_path) {
+                            Ok(mut hwm) => {
+                                let state_snapshot = state_w.snapshot();
+                                let state_hash = ultradag_coin::consensus::compute_state_root(&state_snapshot);
+                                hwm.update(last_finalized_round, state_hash);
+                                
+                                if let Err(e) = hwm.save(&hwm_path) {
+                                    warn!("Failed to save high-water mark: {}", e);
+                                }
+                            }
+                            Err(e) => {
+                                warn!("Failed to load high-water mark for update: {}", e);
+                            }
+                        }
+                    }
+                    
                     // Epoch transition: sync active validator set to FinalityTracker
                     if state_w.epoch_just_changed(prev_round) {
                         sync_epoch_validators(&mut fin, &state_w);
@@ -265,7 +287,6 @@ pub async fn validator_loop(
                     }
 
                     // Checkpoint generation: produce checkpoint at CHECKPOINT_INTERVAL
-                    let last_finalized_round = state_w.last_finalized_round().unwrap_or(0);
                     if last_finalized_round > 0 && last_finalized_round % ultradag_coin::CHECKPOINT_INTERVAL == 0 {
                         let state_snapshot = state_w.snapshot();
                         let state_root = ultradag_coin::consensus::compute_state_root(&state_snapshot);