Bootstrap_controller, Transition_frontier_controller & Transition_rou…

…ter: add & update comments

src/lib/bootstrap_controller/transition_cache.ml

@@ -56,6 +56,16 @@ let add (t : t) ~parent new_child =
     | Some children ->
         let children', b =
           List.fold children ~init:([], false) ~f:(fun (acc, b) child ->
+              (* If state hash was already among children, existing child is
+                 merged with the new transition.
+                 It's needed to maintain consistency about transitions that may
+                 come from gossip or other ways; we want to preserve some
+                 validation callback (and we don't expect two gossips for the
+                 same).
+                 Also, if we received a block after receiving a header
+                 (possible when we'll simultaneously support both old and new
+                 gossip topics), we want to preserve a block because it's more
+                 than a header. *)
               if
                 (not b)
                 && State_hash.equal

src/lib/transition_frontier_controller/transition_frontier_controller.ml

@@ -85,7 +85,8 @@ let run ~context:(module Context : CONTEXT) ~trust_system ~verifier ~network
         | `Block b ->
             Some (map x ~f:(const b), vc)
         | _ ->
-            (* TODO: handle headers too *)
+            (* TODO: handle headers too (headers can't be actually received at
+               this point, so this TODO is safe to be left for future.) *)
             None )
   in
   List.iter collected_transitions ~f:(fun (t, vc) ->

src/lib/transition_router/transition_router.ml

@@ -100,6 +100,11 @@ let start_transition_frontier_controller ~context:(module Context : CONTEXT)
     Strict_pipe.create ~name:"transition frontier: producer transition"
       Synchronous
   in
+  (* No block production happens when bootstrap is running. The
+     [producer_transition_writer_ref] pipe was created just to substitute a
+     value for the type and was never actually used. It could have been read
+     only by the transition frontier controller, and it's not running when
+     bootstrap controller is active *)
   producer_transition_writer_ref := Some producer_transition_writer ;
   Broadcast_pipe.Writer.write frontier_w (Some frontier) |> don't_wait_for ;
   let new_verified_transition_reader =
@@ -533,7 +538,7 @@ let run ?(sync_local_state = true) ?(cache_exceptions = false)
           ~pipe_name:name ~logger ?valid_cb )
       ()
   in
-  (* Ref is None when bootstrap is in progress and Some writer when it's catch-up.query
+  (* Ref is None when bootstrap is in progress and Some writer when it's catch-up.
      In fact, we don't expect any produced blocks during bootstrap (possible only in rare case
      of race condition between bootstrap and block creation) *)
   let producer_transition_writer_ref = ref None in