node: add notes to outofsync

Author: fed-franz

node/src/chain/fsm.rs

@@ -485,6 +485,13 @@ impl<DB: database::DB, VM: vm::VMExecution, N: Network> InSyncImpl<DB, VM, N> {
     /// performed when entering the state
     async fn on_entering(&mut self, blk: &Block) -> anyhow::Result<()> {
         let mut acc = self.acc.write().await;
+
+        // NOTE: If we switched to InSync because of a timeout handled in the
+        // OutOfSync's on_block_event, we need to handle `blk` as usual.
+        // However, given the current implementation, we only handle the tip+1
+        // case, at the risk of losing this block. This should be improved in
+        // the future
+
         let curr_h = acc.get_curr_height().await;
 
         if blk.header().height == curr_h + 1 {

node/src/chain/fsm/outofsync.rs

@@ -240,6 +240,14 @@ impl<DB: database::DB, VM: vm::VMExecution, N: Network>
             return Ok(false);
         }
 
+        // If we receive a block higher than the current target, we "extend" the
+        // range of the syncing process
+        //
+        // NOTE: the block could be coming from a different peer than the one we
+        // are currently syncing with. This means the current peer could
+        // actually not have blocks up to the new target. We might want to
+        // handle this update differently in the future, e.g. by also updating
+        // the sync peer.
         if block_height > self.range.1 {
             debug!(
                 event = "update sync target",
@@ -329,7 +337,6 @@ impl<DB: database::DB, VM: vm::VMExecution, N: Network>
             return Ok(false);
         }
 
-        let block_height = blk.header().height;
         let pool_len = self.pool.len();
 
         if self.pool.contains_key(&block_height) {