add docs, link to issue

consensus/hotstuff/committee.go

@@ -73,6 +73,8 @@ type Replicas interface {
 	// The list of all legitimate HotStuff participants for the given epoch can be obtained by using `filter.Any`
 	//
 	// CAUTION: DO NOT use this method for validating block proposals.
+	// CAUTION: This method considers epochs outside of Previous, Current, Next, w.r.t. the
+	// finalized block, to be unknown. https://github.com/onflow/flow-go/issues/4085
 	//
 	// Returns the following expected errors for invalid inputs:
 	//   * model.ErrViewForUnknownEpoch if no epoch containing the given view is known
@@ -82,6 +84,9 @@ type Replicas interface {
 
 	// IdentityByEpoch returns the full Identity for specified HotStuff participant.
 	// The node must be a legitimate HotStuff participant with NON-ZERO WEIGHT at the specified block.
+	// CAUTION: This method considers epochs outside of Previous, Current, Next, w.r.t. the
+	// finalized block, to be unknown. https://github.com/onflow/flow-go/issues/4085
+	//
 	// ERROR conditions:
 	//  * model.InvalidSignerError if participantID does NOT correspond to an authorized HotStuff participant at the specified block.
 	//

consensus/hotstuff/committees/consensus_committee.go

@@ -187,13 +187,14 @@ func NewConsensusCommittee(state protocol.State, me flow.Identifier) (*Consensus
 	return com, nil
 }
 
-// Identities returns the identities of all authorized consensus participants at the given block.
+// IdentitiesByBlock returns the identities of all authorized consensus participants at the given block.
 // The order of the identities is the canonical order.
 func (c *Consensus) IdentitiesByBlock(blockID flow.Identifier) (flow.IdentityList, error) {
 	il, err := c.state.AtBlockID(blockID).Identities(filter.IsVotingConsensusCommitteeMember)
 	return il, err
 }
 
+// IdentityByBlock returns the identity of the node with the given node ID at the given block.
 func (c *Consensus) IdentityByBlock(blockID flow.Identifier, nodeID flow.Identifier) (*flow.Identity, error) {
 	identity, err := c.state.AtBlockID(blockID).Identity(nodeID)
 	if err != nil {
@@ -210,6 +211,8 @@ func (c *Consensus) IdentityByBlock(blockID flow.Identifier, nodeID flow.Identif
 
 // IdentitiesByEpoch returns the committee identities in the epoch which contains
 // the given view.
+// CAUTION: This method considers epochs outside of Previous, Current, Next, w.r.t. the
+// finalized block, to be unknown. https://github.com/onflow/flow-go/issues/4085
 //
 // Error returns:
 //   - model.ErrViewForUnknownEpoch if no committed epoch containing the given view is known.
@@ -225,6 +228,8 @@ func (c *Consensus) IdentitiesByEpoch(view uint64) (flow.IdentityList, error) {
 
 // IdentityByEpoch returns the identity for the given node ID, in the epoch which
 // contains the given view.
+// CAUTION: This method considers epochs outside of Previous, Current, Next, w.r.t. the
+// finalized block, to be unknown. https://github.com/onflow/flow-go/issues/4085
 //
 // Error returns:
 //   - model.ErrViewForUnknownEpoch if no committed epoch containing the given view is known.

module/epochs.go

@@ -46,6 +46,7 @@ type QCContractClient interface {
 }
 
 // EpochLookup enables looking up epochs by view.
+// CAUTION: EpochLookup should only be used for querying the previous, current, or next epoch.
 type EpochLookup interface {
 
 	// EpochForViewWithFallback returns the counter of the epoch that the input view belongs to.

module/epochs/epoch_lookup.go

@@ -100,6 +100,7 @@ func (cache *epochRangeCache) add(epoch epochRange) error {
 }
 
 // EpochLookup implements the EpochLookup interface using protocol state to match views to epochs.
+// CAUTION: EpochLookup should only be used for querying the previous, current, or next epoch.
 type EpochLookup struct {
 	state                    protocol.State
 	mu                       sync.RWMutex