refactor: add comments for persist_epoch and should_prune in historical_epochs_state

Author: golddydev

modules/historical_epochs_state/src/historical_epochs_state.rs

@@ -143,7 +143,7 @@ impl HistoricalEpochsState {
                         state.immutable.clone()
                     };
 
-                    if let Err(e) = persist_tx.send((current_block.epoch - 1, immutable)).await {
+                    if let Err(e) = persist_tx.send((current_block.epoch, immutable)).await {
                         error!("persistence worker crashed: {e}");
                     }
                 }

modules/historical_epochs_state/src/immutable_historical_epochs_state.rs

@@ -49,11 +49,13 @@ impl ImmutableHistoricalEpochsState {
         pending.push_back(ea);
     }
 
-    /// Persists pending EpochActivityMessages for epoch N
+    /// Persists pending EpochActivityMessages for Epoch N - 1
+    /// at the first block of Epoch N
     /// There should be only one EpochActivityMessage for each epoch
     /// Returns the number of persisted EpochActivityMessages
     /// Errors if the batch commit or persist fails
     pub async fn persist_epoch(&self, epoch: u64) -> Result<u32> {
+        let saving_epoch = epoch - 1;
         let drained_epochs = {
             let mut pending = self.pending.lock().await;
             std::mem::take(&mut *pending)
@@ -69,16 +71,16 @@ impl ImmutableHistoricalEpochsState {
         }
 
         if let Err(e) = batch.commit() {
-            error!("batch commit failed for epoch {epoch}: {e}");
+            error!("batch commit failed for epoch {saving_epoch}: {e}");
             return Err(e.into());
         }
 
         if let Err(e) = self.keyspace.persist(PersistMode::Buffer) {
-            error!("persist failed for epoch {epoch}: {e}");
+            error!("persist failed for epoch {saving_epoch}: {e}");
             return Err(e.into());
         }
 
-        info!("persisted {persisted_epochs} epochs for epoch {epoch}");
+        info!("persisted {persisted_epochs} epochs for epoch {saving_epoch}");
         Ok(persisted_epochs)
     }
 

modules/historical_epochs_state/src/state.rs

@@ -40,6 +40,9 @@ impl State {
         }
     }
 
+    /// block_info is the first block of Epoch N (epoch param)
+    /// And at that point, we are saving EpochActivityMessage for Epoch N - 1
+    /// That is why we check Some(block_info.epoch - 1) != self.volatile.last_persisted_epoch
     pub fn ready_to_prune(&self, block_info: &BlockInfo) -> bool {
         block_info.epoch > 0
             && Some(block_info.epoch - 1) != self.volatile.last_persisted_epoch
@@ -179,7 +182,7 @@ mod tests {
         assert!(state.ready_to_prune(&block_info));
 
         state.prune_volatile().await;
-        state.immutable.persist_epoch(0).await.unwrap();
+        state.immutable.persist_epoch(block_info.epoch).await.unwrap();
 
         let block_info = make_block_info(2, true);
         let ea_1 = make_ea(1);
@@ -192,7 +195,7 @@ mod tests {
         assert!(state.ready_to_prune(&block_info));
 
         state.prune_volatile().await;
-        state.immutable.persist_epoch(1).await.unwrap();
+        state.immutable.persist_epoch(block_info.epoch).await.unwrap();
 
         let historical_epoch = state.immutable.get_historical_epoch(0).unwrap().unwrap();
         assert_eq!(historical_epoch, ea_0);