Document after passing the header state history between ChainSync cli…

…ents.

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client.hs

@@ -1228,22 +1228,33 @@ knownIntersectionStateTop cfgEnv dynEnv intEnv =
                   continueWithState kis' $ nextStep mkPipelineDecision Zero (Their theirTip)
             }
         where
-          combineJumpInfo :: KnownIntersectionState blk -> Maybe (JumpInfo blk) -> KnownIntersectionState blk
+          combineJumpInfo ::
+               KnownIntersectionState blk
+            -> Maybe (JumpInfo blk)
+            -> KnownIntersectionState blk
           combineJumpInfo kis Nothing = kis
           combineJumpInfo kis (Just ji) =
             let mRewoundHistory =
                   HeaderStateHistory.rewind
                     (AF.castPoint $ AF.headPoint $ jTheirFragment ji)
                     (jTheirHeaderStateHistory ji)
+                -- We assume the history is always possible to rewind. The case
+                -- where this wouldn't be true is if the original candidate
+                -- fragment provided by the dynamo contained headers that have
+                -- no corresponding header state.
                 rewoundHistory =
                   fromMaybe (error "offerJump: cannot rewind history") mRewoundHistory
+                -- If the tip of jTheirFragment does not match the tip of
+                -- jTheirHeaderStateHistory, then the history needs rewinding.
                 historyNeedsRewinding =
                      (/= AF.headPoint (jTheirFragment ji)) $
                      castPoint $
                      either headerStatePoint headerStatePoint $
                      AF.head $
                      HeaderStateHistory.unHeaderStateHistory $
                      jTheirHeaderStateHistory ji
+                -- Recompute the intersection only if a suffix of the candidate
+                -- fragment was trimmed.
                 intersection
                   | historyNeedsRewinding = case AF.intersect (jOurFragment ji) (jTheirFragment ji) of
                       Just (po, _, _, _) -> castPoint $ AF.headPoint po
@@ -1481,6 +1492,7 @@ knownIntersectionStateTop cfgEnv dynEnv intEnv =
                   continueWithState kis' $
                       nextStep mkPipelineDecision n theirTip
 
+-- | Let ChainSync jumping know about an update to the 'KnownIntersectionState'.
 updateJumpInfoSTM ::
      Jumping.Jumping m blk
   -> KnownIntersectionState blk

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/Jumping.hs

@@ -134,10 +134,18 @@ data Jumping m blk = Jumping
     jgOnRollBackward    :: !(WithOrigin SlotNo -> m ()),
 
     -- | Process the result of a jump, either accepted or rejected.
+    --
+    -- The returned JumpInfo contains the new candidate fragment for the peer
+    -- and other bits relevant to update the @KnownIntersectionState@ of the
+    -- ChainSync client. See 'JumpInfo' for more details.
     jgProcessJumpResult :: !(JumpResult blk -> m (Maybe (JumpInfo blk))),
 
     -- | To be called to update the last known jump possible to the tip of
-    -- a candidate fragment
+    -- the peers candidate fragment. The ChainSync clients for all peers should
+    -- call this function in case they are or they become dynamos.
+    --
+    -- JumpInfo is meant to be a snapshot of the @KnownIntersectionState@ of
+    -- the ChainSync client. See 'JumpInfo' for more details.
     jgUpdateJumpInfo    :: !(JumpInfo blk -> STM m ())
   }
   deriving stock (Generic)

ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/MiniProtocol/ChainSync/Client/State.hs

@@ -123,6 +123,13 @@ deriving anyclass instance
   ) => NoThunks (ChainSyncJumpingState m blk)
 
 -- | The ChainSync state required for jumps
+--
+-- The jump info is mostly a snapshot of the @KnownIntersectionState@ of the
+-- dynamo, with the difference that 'jTheirFragment' might be a proper prefix of
+-- the original candidate fragment.
+--
+-- This can happen if we need to look for an intersection when the jumper
+-- rejects a jump.
 data JumpInfo blk = JumpInfo
   { jMostRecentIntersection :: !(Point blk)
   , jOurFragment :: !(AnchoredFragment (Header blk))