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

     1  package hotstuff
     2  
     3  import (
     4  	"github.com/onflow/crypto"
     5  )
     6  
     7  // RandomBeaconInspector encapsulates all methods needed by a Hotstuff leader to validate the
     8  // beacon votes and reconstruct a beacon signature.
     9  // The random beacon methods are based on a threshold signature scheme.
    10  type RandomBeaconInspector interface {
    11  	// Verify verifies the signature share under the signer's public key and the message agreed upon.
    12  	// The function is thread-safe and wait-free (i.e. allowing arbitrary many routines to
    13  	// execute the business logic, without interfering with each other).
    14  	// It allows concurrent verification of the given signature.
    15  	// Returns :
    16  	//  - model.InvalidSignerError if signerIndex is invalid
    17  	//  - model.ErrInvalidSignature if signerIndex is valid but signature is cryptographically invalid
    18  	//  - other error if there is an unexpected exception.
    19  	Verify(signerIndex int, share crypto.Signature) error
    20  
    21  	// TrustedAdd adds a share to the internal signature shares store.
    22  	// There is no pre-check of the signature's validity _before_ adding it.
    23  	// It is the caller's responsibility to make sure the signature was previously verified.
    24  	// Nevertheless, the implementation guarantees safety (only correct threshold signatures
    25  	// are returned) through a post-check (verifying the threshold signature
    26  	// _after_ reconstruction before returning it).
    27  	// The function is thread-safe but locks its internal state, thereby permitting only
    28  	// one routine at a time to add a signature.
    29  	// Returns:
    30  	//  - (true, nil) if the signature has been added, and enough shares have been collected.
    31  	//  - (false, nil) if the signature has been added, but not enough shares were collected.
    32  	//  - (false, error) if there is any exception adding the signature share.
    33  	//      - model.InvalidSignerError if signerIndex is invalid (out of the valid range)
    34  	//  	- model.DuplicatedSignerError if the signer has been already added
    35  	//      - other error if there is an unexpected exception.
    36  	TrustedAdd(signerIndex int, share crypto.Signature) (enoughshares bool, exception error)
    37  
    38  	// EnoughShares indicates whether enough shares have been accumulated in order to reconstruct
    39  	// a group signature. The function is thread-safe.
    40  	EnoughShares() bool
    41  
    42  	// Reconstruct reconstructs the group signature. The function is thread-safe but locks
    43  	// its internal state, thereby permitting only one routine at a time.
    44  	//
    45  	// Returns:
    46  	// - (signature, nil) if no error occurred
    47  	// - (nil, model.InsufficientSignaturesError) if not enough shares were collected
    48  	// - (nil, model.InvalidSignatureIncluded) if at least one collected share does not serialize to a valid BLS signature,
    49  	//    or if the constructed signature failed to verify against the group public key and stored message. This post-verification
    50  	//    is required  for safety, as `TrustedAdd` allows adding invalid signatures.
    51  	// - (nil, error) for any other unexpected error.
    52  	Reconstruct() (crypto.Signature, error)
    53  }