update comments and TentativeEpoch doc comment

Co-authored-by: Jordan Schalm <[email protected]>

consensus/hotstuff/committees/leader/consensus.go

@@ -9,7 +9,8 @@ import (
 	"github.com/onflow/flow-go/state/protocol/prg"
 )
 
-// SelectionForConsensusFromEpoch is a ...
+// SelectionForConsensusFromEpoch returns the leader selection for the input epoch.
+// See [SelectionForConsensus] for additional details.
 func SelectionForConsensusFromEpoch(epoch protocol.CommittedEpoch) (*LeaderSelection, error) {
 
 	identities, err := epoch.InitialIdentities()

engine/consensus/dkg/reactor_engine.go

@@ -335,7 +335,9 @@ func (e *ReactorEngine) handleEpochCommittedPhaseStarted(currentEpochCounter uin
 	log.Info().Msgf("successfully ended DKG, my beacon pub key for epoch %d is %s", nextEpochCounter, localPubKey)
 }
 
-// TODO document error returns
+// getDKGInfo returns the information required to initiate the DKG for the current epoch.
+// firstBlockID must be the first block of the EpochSetup phase.
+// No errors are expected during normal operation.
 func (e *ReactorEngine) getDKGInfo(firstBlockID flow.Identifier) (*dkgInfo, error) {
 	currEpoch := e.State.AtBlockID(firstBlockID).Epochs().Current()
 	nextEpoch := e.State.AtBlockID(firstBlockID).Epochs().NextUnsafe()

state/protocol/badger/mutator_test.go

@@ -963,13 +963,13 @@ func TestExtendEpochTransitionValid(t *testing.T) {
 			require.Error(t, err)
 		}
 
-		// we should be able to query epoch 2 wrt block 3
+		// we should be able to query epoch 2 as a TentativeEpoch wrt block 3
 		_, err = state.AtBlockID(block3.ID()).Epochs().NextUnsafe().InitialIdentities()
 		assert.NoError(t, err)
 		_, err = state.AtBlockID(block3.ID()).Epochs().NextUnsafe().Clustering()
 		assert.NoError(t, err)
 
-		// only setup event is finalized, not commit, so shouldn't be able to get certain info
+		// only setup event is finalized, not commit, so shouldn't be able to read a CommittedEpoch
 		_, err = state.AtBlockID(block3.ID()).Epochs().NextCommitted().DKG()
 		require.Error(t, err)
 
@@ -1032,7 +1032,7 @@ func TestExtendEpochTransitionValid(t *testing.T) {
 			require.Error(t, err)
 		}
 
-		// now epoch 2 is fully ready, we can query anything we want about it wrt block 6 (or later)
+		// now epoch 2 is committed, we can query anything we want about it wrt block 6 (or later)
 		_, err = state.AtBlockID(block6.ID()).Epochs().NextCommitted().InitialIdentities()
 		require.NoError(t, err)
 		_, err = state.AtBlockID(block6.ID()).Epochs().NextCommitted().Clustering()

state/protocol/epoch.go

@@ -210,6 +210,12 @@ type CommittedEpoch interface {
 	FinalHeight() (uint64, error)
 }
 
+// TentativeEpoch returns the data associated with the "working next epoch",
+// the upcoming epoch which the protocol is in the process of committing.
+// Only the data that is strictly necessary for committing the epoch is exposed;
+// after commitment, all epoch data is accessible through the [CommittedEpoch] interface.
+// This should only be used by components that participate in committing the epoch
+// (transition from [flow.EpochPhaseSetup] to [flow.EpochPhaseCommitted]).
 type TentativeEpoch interface {
 
 	// Counter returns the Epoch's counter.