v0.2.7-pre.011-fix.001

crates/ksp-onchain-transport-lib/src/ws_cluster.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-onchain-transport-lib/src/ws_cluster.rs
-// version: 2
+// version: 3
 
 /// Slot relationship reported by the standard Solana `slotNotification` WebSocket method.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
@@ -68,23 +68,69 @@ impl SolanaSlotUpdateStats {
 #[derive(Clone, Debug, PartialEq)]
 pub enum SolanaSlotUpdate {
     /// The first shred for a slot was received.
-    FirstShredReceived { slot: u64, timestamp: i64 },
+    FirstShredReceived {
+        /// Slot whose first shred was observed.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+    },
     /// All shreds for a slot were received.
-    Completed { slot: u64, timestamp: i64 },
+    Completed {
+        /// Slot whose shred set completed.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+    },
     /// A bank was created for the slot.
-    CreatedBank { slot: u64, timestamp: i64, parent: u64 },
+    CreatedBank {
+        /// Slot whose bank was created.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+        /// Parent slot used to create the bank.
+        parent: u64,
+    },
     /// A bank was frozen and execution statistics are available.
-    Frozen { slot: u64, timestamp: i64, stats: crate::SolanaSlotUpdateStats },
+    Frozen {
+        /// Slot whose bank was frozen.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+        /// Execution statistics reported for the frozen bank.
+        stats: crate::SolanaSlotUpdateStats,
+    },
     /// The slot was marked dead.
-    Dead { slot: u64, timestamp: i64, error: std::string::String },
+    Dead {
+        /// Slot marked dead by the validator.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+        /// Upstream diagnostic string explaining why the slot was marked dead.
+        error: std::string::String,
+    },
     /// The slot reached the current unstable optimistic-confirmation marker.
-    OptimisticConfirmation { slot: u64, timestamp: i64 },
+    OptimisticConfirmation {
+        /// Slot that reached optimistic confirmation.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+    },
     /// The slot became root.
-    Root { slot: u64, timestamp: i64 },
+    Root {
+        /// Slot that became root.
+        slot: u64,
+        /// Millisecond Unix timestamp reported by the validator.
+        timestamp: i64,
+    },
     /// A future upstream variant that KSP does not yet interpret.
     ///
     /// `raw` is bounded by the physical session's configured inbound WebSocket message limit before JSON decoding.
-    Unknown { update_type: std::string::String, raw: serde_json::Value },
+    Unknown {
+        /// Upstream `type` discriminator that KSP does not yet recognize.
+        update_type: std::string::String,
+        /// Complete bounded JSON object preserved for forward-compatible inspection.
+        raw: serde_json::Value,
+    },
 }
 
 impl SolanaSlotUpdate {