commend cleanup and removal of bloating white spaces

Author: AlexHentschel

storage/procedure/children.go

@@ -11,8 +11,8 @@ import (
 	"github.com/onflow/flow-go/storage/operation"
 )
 
-// IndexNewBlock and IndexNewClusterBlock will add parent-child index for the new block.
-//   - Each block has a parent, we use this parent-child relationship to build a reverse index
+// IndexNewBlock will add parent-child index for the new block.
+//   - Each block that we ingest has a parent, we use this parent-child relationship to build a reverse index
 //     for looking up children blocks for a given block. This is useful for forks recovery
 //     where we want to find all the pending children blocks for the lastest finalized block.
 //
@@ -33,6 +33,20 @@ func IndexNewBlock(lctx lockctx.Proof, rw storage.ReaderBatchWriter, blockID flo
 	return insertNewBlock(lctx, rw, blockID, parentID)
 }
 
+// IndexNewClusterBlock will add parent-child index for the new block.
+//   - Each block that we ingest has a parent, we use this parent-child relationship to build a reverse index
+//     for looking up children blocks for a given block. This is useful for forks recovery
+//     where we want to find all the pending children blocks for the lastest finalized block.
+//
+// When adding parent-child index for a new block, we will update two indexes:
+//  1. Per protocol convention, blocks must be ingested in "ancestors-first" order. Hence,
+//     if a block is new (needs to be verified, to avoid state corruption in case of repeated
+//     calls), its set of persisted children is empty at the time of insertion.
+//  2. Since the parent block has this new block as a child, we add to the parent block's children.
+//     There are two special cases for (2):
+//     - If the parent block is zero (i.e. genesis block), then we don't need to add this index.
+//     - If the parent block doesn't exist, then we will index the new block as the only child
+//     of the parent anyway. This is useful for bootstrapping nodes with truncated history.
 func IndexNewClusterBlock(lctx lockctx.Proof, rw storage.ReaderBatchWriter, blockID flow.Identifier, parentID flow.Identifier) error {
 	if !lctx.HoldsLock(storage.LockInsertOrFinalizeClusterBlock) {
 		return fmt.Errorf("missing required lock: %s", storage.LockInsertOrFinalizeClusterBlock)

storage/procedure/cluster.go

@@ -58,10 +58,6 @@ func InsertClusterBlock(lctx lockctx.Proof, rw storage.ReaderBatchWriter, propos
 		return fmt.Errorf("could not insert proposer signature: %w", err)
 	}
 
-	// since InsertHeader already checks for duplicates, we can safely
-	// assume that the block header is new and there is no existing index
-	// for other data related to this block ID.
-
 	// insert the block payload
 	err = InsertClusterPayload(lctx, rw, blockID, &proposal.Block.Payload)
 	if err != nil {
@@ -102,7 +98,6 @@ func RetrieveClusterBlock(r storage.Reader, blockID flow.Identifier, block *clus
 	if err != nil {
 		return fmt.Errorf("could not build cluster block: %w", err)
 	}
-
 	*block = *newBlock
 
 	return nil
@@ -212,7 +207,7 @@ func InsertClusterPayload(lctx lockctx.Proof, rw storage.ReaderBatchWriter, bloc
 	// Here, we persist a reduced representation of the collection, only listing the constituent transactions by their hashes.
 	light := payload.Collection.Light()
 	writer := rw.Writer()
-	err = operation.UpsertCollection(writer, light) // keyed by content hash so no lock needed
+	err = operation.UpsertCollection(writer, light) // collection is keyed by content hash, hence no overwrite protection is needed
 	if err != nil {
 		return fmt.Errorf("could not insert payload collection: %w", err)
 	}
@@ -285,7 +280,6 @@ func RetrieveClusterPayload(r storage.Reader, blockID flow.Identifier, payload *
 	if err != nil {
 		return fmt.Errorf("could not build the payload: %w", err)
 	}
-
 	*payload = *newPayload
 
 	return nil