From 7364a433caa73648f8409f5da6fa7963666a0b2f Mon Sep 17 00:00:00 2001
From: Jordan Schalm <jordan@dapperlabs.com>
Date: Wed, 22 Mar 2023 17:47:13 -0400
Subject: [PATCH] add docs, link to issue

---
 consensus/hotstuff/committee.go                      | 5 +++++
 consensus/hotstuff/committees/consensus_committee.go | 7 ++++++-
 module/epochs.go                                     | 1 +
 module/epochs/epoch_lookup.go                        | 1 +
 4 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/consensus/hotstuff/committee.go b/consensus/hotstuff/committee.go
index 5203ebc7bee..556c5ca6bee 100644
--- a/consensus/hotstuff/committee.go
+++ b/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.
 	//
diff --git a/consensus/hotstuff/committees/consensus_committee.go b/consensus/hotstuff/committees/consensus_committee.go
index c61ff5941ac..08e2b861e8d 100644
--- a/consensus/hotstuff/committees/consensus_committee.go
+++ b/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.
diff --git a/module/epochs.go b/module/epochs.go
index 874fc44a4fc..6964959e950 100644
--- a/module/epochs.go
+++ b/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.
diff --git a/module/epochs/epoch_lookup.go b/module/epochs/epoch_lookup.go
index f0ec869a0ec..195c72159f7 100644
--- a/module/epochs/epoch_lookup.go
+++ b/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