github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/module/epochs.go (about)

     1  package module
     2  
     3  import (
     4  	"context"
     5  
     6  	"github.com/onflow/flow-go/consensus/hotstuff/model"
     7  	"github.com/onflow/flow-go/state/protocol"
     8  )
     9  
    10  // ClusterRootQCVoter is responsible for submitting a vote to the cluster QC
    11  // contract to coordinate generation of a valid root quorum certificate for the
    12  // next epoch.
    13  type ClusterRootQCVoter interface {
    14  
    15  	// Vote handles the full procedure of generating a vote, submitting it to the epoch
    16  	// smart contract, and verifying submission. It is safe to run Vote multiple
    17  	// times within a single setup phase.
    18  	// Error returns:
    19  	//   - epochs.ClusterQCNoVoteError if we fail to vote for a benign reason
    20  	//   - generic error in case of critical unexpected failure
    21  	Vote(context.Context, protocol.Epoch) error
    22  }
    23  
    24  // QCContractClient enables interacting with the cluster QC aggregator smart
    25  // contract. This contract is deployed to the service account as part of a
    26  // collection of smart contracts that facilitate and manage epoch transitions.
    27  type QCContractClient interface {
    28  
    29  	// SubmitVote submits the given vote to the cluster QC aggregator smart
    30  	// contract. This function returns only once the transaction has been
    31  	// processed by the network. An error is returned if the transaction has
    32  	// failed and should be re-submitted.
    33  	// Error returns:
    34  	//   - network.TransientError for any errors from the underlying client, if the retry period has been exceeded
    35  	//   - errTransactionExpired if the transaction has expired
    36  	//   - errTransactionReverted if the transaction execution reverted
    37  	//   - generic error in case of unexpected critical failure
    38  	SubmitVote(ctx context.Context, vote *model.Vote) error
    39  
    40  	// Voted returns true if we have successfully submitted a vote to the
    41  	// cluster QC aggregator smart contract for the current epoch.
    42  	// Error returns:
    43  	//   - network.TransientError for any errors from the underlying Flow client
    44  	//   - generic error in case of unexpected critical failures
    45  	Voted(ctx context.Context) (bool, error)
    46  }
    47  
    48  // EpochLookup enables looking up epochs by view.
    49  // CAUTION: EpochLookup should only be used for querying the previous, current, or next epoch.
    50  type EpochLookup interface {
    51  
    52  	// EpochForViewWithFallback returns the counter of the epoch that the input view belongs to.
    53  	// If epoch fallback has been triggered, returns the last committed epoch counter
    54  	// in perpetuity for any inputs beyond the last committed epoch view range.
    55  	// For example, if we trigger epoch fallback during epoch 10, and reach the final
    56  	// view of epoch 10 before epoch 11 has finished being setup, this function will
    57  	// return 10 even for input views beyond the final view of epoch 10.
    58  	//
    59  	// Returns model.ErrViewForUnknownEpoch if the input does not fall within the range of a known epoch.
    60  	EpochForViewWithFallback(view uint64) (epochCounter uint64, err error)
    61  }