clarified method naming

Author: AlexHentschel

storage/operation/headers.go

@@ -124,7 +124,7 @@ func BlockExists(r storage.Reader, blockID flow.Identifier) (bool, error) {
 	return KeyExists(r, MakePrefix(codeHeader, blockID))
 }
 
-// IndexCollectionGuaranteeByBlock produces a mapping from collection ID to the block ID containing this collection.
+// IndexBlockContainingCollection produces a mapping from collection ID to the block ID containing this collection.
 //
 // CAUTION:
 //   - The caller must acquire the lock ??? and hold it until the database write has been committed.
@@ -137,12 +137,21 @@ func BlockExists(r storage.Reader, blockID flow.Identifier) (bool, error) {
 //
 // Expected errors during normal operations:
 // TODO: return [storage.ErrAlreadyExists] or [storage.ErrDataMismatch]
-func IndexCollectionGuaranteeByBlock(w storage.Writer, collID flow.Identifier, blockID flow.Identifier) error {
+func IndexBlockContainingCollection(w storage.Writer, collID flow.Identifier, blockID flow.Identifier) error {
 	return UpsertByKey(w, MakePrefix(codeCollectionBlock, collID), blockID)
 }
 
-// LookupCollectionGuaranteeByBlock looks up a block by a collection within that block.
-func LookupCollectionGuaranteeByBlock(r storage.Reader, collID flow.Identifier, blockID *flow.Identifier) error {
+// LookupBlockContainingCollection retrieves the block containing the collection with the given ID.
+//
+// CAUTION: A collection can be included in multiple *unfinalized* blocks. However, the implementation
+// assumes a one-to-one map from collection ID to a *single* block ID. This holds for FINALIZED BLOCKS ONLY
+// *and* only in the ABSENCE of BYZANTINE collector CLUSTERS (which the mature protocol must tolerate).
+// Hence, this function should be treated as a temporary solution, which requires generalization
+// (one-to-many mapping) for soft finality and the mature protocol.
+//
+// Expected errors during normal operations:
+//   - [storage.ErrNotFound] if no block is known that contains the specified collection ID.
+func LookupBlockContainingCollection(r storage.Reader, collID flow.Identifier, blockID *flow.Identifier) error {
 	return RetrieveByKey(r, MakePrefix(codeCollectionBlock, collID), blockID)
 }
 

storage/operation/headers_test.go

@@ -55,12 +55,12 @@ func TestHeaderIDIndexByCollectionID(t *testing.T) {
 		collectionGuaranteeID := unittest.IdentifierFixture()
 
 		err := db.WithReaderBatchWriter(func(rw storage.ReaderBatchWriter) error {
-			return operation.IndexCollectionGuaranteeByBlock(rw.Writer(), collectionGuaranteeID, headerID)
+			return operation.IndexBlockContainingCollection(rw.Writer(), collectionGuaranteeID, headerID)
 		})
 		require.NoError(t, err)
 
 		actualID := &flow.Identifier{}
-		err = operation.LookupCollectionGuaranteeByBlock(db.Reader(), collectionGuaranteeID, actualID)
+		err = operation.LookupBlockContainingCollection(db.Reader(), collectionGuaranteeID, actualID)
 		require.NoError(t, err)
 		assert.Equal(t, headerID, *actualID)
 	})

storage/store/blocks.go

@@ -196,7 +196,7 @@ func (b *Blocks) ByCollectionID(collID flow.Identifier) (*flow.Block, error) {
 		return nil, fmt.Errorf("could not look up guarantee: %w", err)
 	}
 	var blockID flow.Identifier
-	err = operation.LookupCollectionGuaranteeByBlock(b.db.Reader(), guarantee.ID(), &blockID)
+	err = operation.LookupBlockContainingCollection(b.db.Reader(), guarantee.ID(), &blockID)
 	if err != nil {
 		return nil, fmt.Errorf("could not look up block: %w", err)
 	}
@@ -216,7 +216,7 @@ func (b *Blocks) ByCollectionID(collID flow.Identifier) (*flow.Block, error) {
 func (b *Blocks) IndexBlockForCollectionGuarantees(blockID flow.Identifier, guaranteeIDs []flow.Identifier) error {
 	return b.db.WithReaderBatchWriter(func(rw storage.ReaderBatchWriter) error {
 		for _, guaranteeID := range guaranteeIDs {
-			err := operation.IndexCollectionGuaranteeByBlock(rw.Writer(), guaranteeID, blockID)
+			err := operation.IndexBlockContainingCollection(rw.Writer(), guaranteeID, blockID)
 			if err != nil {
 				return fmt.Errorf("could not index collection block (%x): %w", guaranteeID, err)
 			}