github.com/onflow/flow-go@v0.35.7-crescendo-preview.23-atree-inlining/consensus/hotstuff/verifier.go (about)

     1  package hotstuff
     2  
     3  import (
     4  	"github.com/onflow/flow-go/model/flow"
     5  )
     6  
     7  // Verifier is the component responsible for the cryptographic integrity of
     8  // votes, proposals and QC's against the block they are signing.
     9  // Overall, there are two criteria for the validity of a vote and QC:
    10  //
    11  //	(1) the signer ID(s) must correspond to authorized consensus participants
    12  //	(2) the signature must be cryptographically valid.
    13  //
    14  // Note that Verifier only implements (2). This API design allows to decouple
    15  //
    16  //	 (i)  the common logic for checking that a super-majority of the consensus
    17  //	      committee voted
    18  //	 (ii) the handling of combined staking+RandomBeacon votes (consensus nodes)
    19  //		  vs only staking votes (collector nodes)
    20  //
    21  // On the one hand, this API design makes code less concise, as the two checks
    22  // are now distributed over API boundaries. On the other hand, we can avoid
    23  // repeated Identity lookups in the implementation, which increases performance.
    24  type Verifier interface {
    25  
    26  	// VerifyVote checks the cryptographic validity of a vote's `SigData` w.r.t.
    27  	// the view and blockID. It is the responsibility of the calling code to ensure
    28  	// that `voter` is authorized to vote.
    29  	// Return values:
    30  	//  * nil if `sigData` is cryptographically valid
    31  	//  * model.InvalidFormatError if the signature has an incompatible format.
    32  	//  * model.ErrInvalidSignature is the signature is invalid
    33  	//  * model.InvalidSignerError is only relevant for extended signature schemes,
    34  	//    where special signing authority is only given to a _subset_ of consensus
    35  	//    participants (e.g. random beacon). In case a participant signed despite not
    36  	//    being authorized, an InvalidSignerError is returned.
    37  	//  * model.ErrViewForUnknownEpoch is only relevant for extended signature schemes,
    38  	//    where querying of DKG might fail if no epoch containing the given view is known.
    39  	//  * unexpected errors should be treated as symptoms of bugs or uncovered
    40  	//    edge cases in the logic (i.e. as fatal)
    41  	VerifyVote(voter *flow.IdentitySkeleton, sigData []byte, view uint64, blockID flow.Identifier) error
    42  
    43  	// VerifyQC checks the cryptographic validity of a QC's `SigData` w.r.t. the
    44  	// given view and blockID. It is the responsibility of the calling code to ensure that
    45  	// all `signers` are authorized, without duplicates.
    46  	// Return values:
    47  	//  * nil if `sigData` is cryptographically valid
    48  	//  * model.InvalidFormatError if `sigData` has an incompatible format
    49  	//  * model.InsufficientSignaturesError if `signers is empty.
    50  	//    Depending on the order of checks in the higher-level logic this error might
    51  	//    be an indicator of a external byzantine input or an internal bug.
    52  	//  * model.ErrInvalidSignature if a signature is invalid
    53  	//  * model.InvalidSignerError is only relevant for extended signature schemes,
    54  	//    where special signing authority is only given to a _subset_ of consensus
    55  	//    participants (e.g. random beacon). In case a participant signed despite not
    56  	//    being authorized, an InvalidSignerError is returned.
    57  	//  * model.ErrViewForUnknownEpoch is only relevant for extended signature schemes,
    58  	//    where querying of DKG might fail if no epoch containing the given view is known.
    59  	//  * unexpected errors should be treated as symptoms of bugs or uncovered
    60  	//	  edge cases in the logic (i.e. as fatal)
    61  	VerifyQC(signers flow.IdentitySkeletonList, sigData []byte, view uint64, blockID flow.Identifier) error
    62  
    63  	// VerifyTC checks cryptographic validity of the TC's `sigData` w.r.t. the
    64  	// given view. It is the responsibility of the calling code to ensure
    65  	// that all `signers` are authorized, without duplicates. Return values:
    66  	//  * nil if `sigData` is cryptographically valid
    67  	//  * model.InsufficientSignaturesError if `signers is empty.
    68  	//  * model.InvalidFormatError if `signers`/`highQCViews` have differing lengths
    69  	//  * model.ErrInvalidSignature if a signature is invalid
    70  	//  * unexpected errors should be treated as symptoms of bugs or uncovered
    71  	//	  edge cases in the logic (i.e. as fatal)
    72  	VerifyTC(signers flow.IdentitySkeletonList, sigData []byte, view uint64, highQCViews []uint64) error
    73  }