properly documented function in storage/operation/spork.go

Author: AlexHentschel

storage/operation/receipts.go

@@ -14,7 +14,7 @@ func InsertExecutionReceiptStub(w storage.Writer, receiptID flow.Identifier, met
 	return UpsertByKey(w, MakePrefix(codeExecutionReceiptMeta, receiptID), meta)
 }
 
-// RetrieveExecutionReceiptMeta retrieves a [flow.ExecutionReceiptStub] by its ID.
+// RetrieveExecutionReceiptStub retrieves a [flow.ExecutionReceiptStub] by its ID.
 //
 // Expected errors during normal operations:
 //   - [storage.ErrNotFound] if no receipt stub with the specified ID is known.

storage/operation/spork.go

@@ -6,17 +6,23 @@ import (
 )
 
 // IndexSporkRootBlock indexes the spork root block ID for the present spork.
+// A Node's state is strictly tied to a specific spork, and should never change during
+// the lifetime of the node. This values is inserted exactly once when bootstrapping the
+// state and should always be present for a properly bootstrapped node.
+// CAUTION: OVERWRITES existing data (potential for data corruption).
+// TODO: error if key already exists!
 //
-// Error returns:
-//   - generic error in case of unexpected failure from the database layer or encoding failure.
+// No errors are expected during normal operation.
 func IndexSporkRootBlock(w storage.Writer, blockID flow.Identifier) error {
 	return UpsertByKey(w, MakePrefix(codeSporkRootBlockID), blockID)
 }
 
-// RetrieveSporkRootBlockID retrieves the spork root block ID for the present spork.
-//
-// Error returns:
-//   - generic error in case of unexpected failure from the database layer or encoding failure.
+// RetrieveSporkRootBlockID retrieves the spork root block's ID for the present spork, which this node is
+// participating in. A Node's state is strictly tied to a specific spork, and should never change during
+// the lifetime of the node.
+// This values is inserted exactly once when bootstrapping the state and should always be present for a
+// properly bootstrapped node.
+// No errors are expected during normal operation.
 func RetrieveSporkRootBlockID(r storage.Reader, blockID *flow.Identifier) error {
 	return RetrieveByKey(r, MakePrefix(codeSporkRootBlockID), blockID)
 }