crypto

type DKGProcessor interface {
	// PrivateSend sends a message to a destination over
	// a private channel. The channel must preserve the
	// confidentiality of the message and should authenticate
	// the sender.
	// It is recommended that the private channel is unique per
	// protocol instance. This can be achieved by prepending all
	// messages by a unique instance ID.
	PrivateSend(dest int, data []byte)
	// Broadcast broadcasts a message to all participants.
	// This function assumes all participants have received the same message,
	// failing to do so, the protocol can be broken.
	// The broadcasted message is public and not confidential.
	// The broadcasting channel should authenticate the sender.
	// It is recommended that the broadcasting channel is unique per
	// protocol instance. This can be achieved by prepending all
	// messages by a unique instance ID.
	Broadcast(data []byte)
	// Disqualify flags that a participant is misbehaving and that it got
	// disqualified from the protocol. Such behavior deserves
	// disqualifying as it is flagged to all honest participants in
	// the protocol.
	// log describes the disqualification reason.
	Disqualify(participant int, log string)
	// FlagMisbehavior warns that a participant is misbehaving.
	// Such behavior is not necessarily flagged to all participants and therefore
	// the participant is not disqualified from the protocol. Other mechanisms
	// outside DKG could be implemented to synchronize slashing the misbehaving
	// participant by all participating participants, using the api `ForceDisqualify`. Failing to
	// do so, the protocol can be broken.
	// log describes the misbehavior.
	FlagMisbehavior(participant int, log string)
}

type DKGState interface {
	// Size returns the size of the DKG group n
	Size() int
	// Threshold returns the threshold value t
	Threshold() int
	// Start starts running a DKG in the current participant
	Start(seed []byte) error
	// HandleBroadcastMsg processes a new broadcasted message received by the current participant.
	// orig is the message origin index
	HandleBroadcastMsg(orig int, msg []byte) error
	// HandlePrivateMsg processes a new private message received by the current participant.
	// orig is the message origin index
	HandlePrivateMsg(orig int, msg []byte) error
	// End ends a DKG protocol in the current participant.
	// It returns the finalized public data and participant private key share.
	// - the group public key corresponding to the group secret key
	// - all the public key shares corresponding to the participants private
	// key shares
	// - the finalized private key which is the current participant's own private key share
	End() (PrivateKey, PublicKey, []PublicKey, error)
	// NextTimeout set the next timeout of the protocol if any timeout applies.
	// Some protocols could require more than one timeout
	NextTimeout() error
	// Running returns the running state of the DKG protocol
	Running() bool
	// ForceDisqualify forces a participant to get disqualified
	// for a reason outside of the DKG protocol.
	// The caller should make sure all honest participants call this function,
	// otherwise, the protocol can be broken.
	ForceDisqualify(participant int) error
}

type PrivateKey interface {
	// Algorithm returns the signing algorithm related to the private key.
	Algorithm() SigningAlgorithm
	// Size return the key size in bytes.
	Size() int
	// String return a hex representation of the key
	String() string
	// Sign generates a signature using the provided hasher.
	Sign([]byte, hash.Hasher) (Signature, error)
	// PublicKey returns the public key.
	PublicKey() PublicKey
	// Encode returns a bytes representation of the private key
	Encode() []byte
	// Equals returns true if the given PrivateKeys are equal. Keys are considered unequal if their algorithms are
	// unequal or if their encoded representations are unequal. If the encoding of either key fails, they are considered
	// unequal as well.
	Equals(PrivateKey) bool
}

type PublicKey interface {
	// Algorithm returns the signing algorithm related to the public key.
	Algorithm() SigningAlgorithm
	// Size() return the key size in bytes.
	Size() int
	// String return a hex representation of the key
	String() string
	// Verify verifies a signature of an input message using the provided hasher.
	Verify(Signature, []byte, hash.Hasher) (bool, error)
	// Encode returns a bytes representation of the public key.
	Encode() []byte
	// EncodeCompressed returns a compressed byte representation of the public key.
	// The compressed serialization concept is generic to elliptic curves,
	// but we refer to individual curve parameters for details of the compressed format
	EncodeCompressed() []byte
	// Equals returns true if the given PublicKeys are equal. Keys are considered unequal if their algorithms are
	// unequal or if their encoded representations are unequal. If the encoding of either key fails, they are considered
	// unequal as well.
	Equals(PublicKey) bool
}

type Signature []byte

type SigningAlgorithm int

type ThresholdSignatureInspector interface {
	// VerifyShare verifies the input signature against the stored message and stored
	// key at the input index. This function does not update the internal state.
	// The function is thread-safe.
	// Returns:
	//  - (true, nil) if the signature is valid
	//  - (false, nil) if `orig` is a valid index but the signature share is invalid
	//  - (false, InvalidInputsError) if `orig` is an invalid index value
	//  - (false, error) for all other unexpected errors
	VerifyShare(orig int, share Signature) (bool, error)

	// VerifyThresholdSignature verifies the input signature against the stored
	// message and stored group public key. It does not update the internal state.
	// The function is thread-safe.
	// Returns:
	//  - (true, nil) if the signature is valid
	//  - (false, nil) if the signature is invalid
	//  - (false, error) for all other unexpected errors
	VerifyThresholdSignature(thresholdSignature Signature) (bool, error)

	// EnoughShares indicates whether enough shares have been accumulated in order to reconstruct
	// a group signature. This function is thread safe and locks the internal state.
	// Returns:
	//  - true if and only if at least (threshold+1) shares were added
	EnoughShares() bool

	// TrustedAdd adds a signature share to the internal pool of shares
	// without verifying the signature against the message and the participant's
	// public key. This function is thread safe and locks the internal state.
	//
	// The share is only added if the signer index is valid and has not been
	// added yet. Moreover, the share is added only if not enough shares were collected.
	// The function returns:
	//  - (true, nil) if enough signature shares were already collected and no error occurred
	//  - (false, nil) if not enough shares were collected and no error occurred
	//  - (false, InvalidInputsError) if index is invalid
	//  - (false, duplicatedSignerError) if a signature for the index was previously added
	TrustedAdd(orig int, share Signature) (bool, error)

	// VerifyAndAdd verifies a signature share (same as `VerifyShare`),
	// and may or may not add the share to the local pool of shares.
	// This function is thread safe and locks the internal state.
	//
	// The share is only added if the signature is valid, the signer index is valid and has not been
	// added yet. Moreover, the share is added only if not enough shares were collected.
	// Boolean returns:
	//  - First boolean output is true if the share is valid and no error is returned, and false otherwise.
	//  - Second boolean output is true if enough shares were collected and no error is returned, and false otherwise.
	// Error returns:
	//  - invalidInputsError if input index is invalid. A signature that doesn't verify against the signer's
	//    public key is not considered an invalid input.
	//  - duplicatedSignerError if signer was already added.
	//  - other errors if an unexpected exception occurred.
	VerifyAndAdd(orig int, share Signature) (bool, bool, error)

	// HasShare checks whether the internal map contains the share of the given index.
	// This function is thread safe.
	// The function errors with InvalidInputsError if the index is invalid.
	HasShare(orig int) (bool, error)

	// ThresholdSignature returns the threshold signature if the threshold was reached.
	// The threshold signature is reconstructed only once and is cached for subsequent calls.
	//
	// Returns:
	// - (signature, nil) if no error occurred
	// - (nil, notEnoughSharesError) if not enough shares were collected
	// - (nil, invalidSignatureError) if at least one collected share does not serialize to a valid BLS signature.
	// - (nil, invalidInputsError) if the constructed signature failed to verify against the group public key and stored message. This post-verification
	//    is required  for safety, as `TrustedAdd` allows adding invalid signatures.
	// - (nil, error) for any other unexpected error.
	ThresholdSignature() (Signature, error)
}

type ThresholdSignatureParticipant interface {
	ThresholdSignatureInspector
	// SignShare generates a signature share using the current private key share.
	//
	// The function does not add the share to the internal pool of shares and do
	// not update the internal state.
	// This function is thread safe
	// No error is expected unless an unexpected exception occurs
	SignShare() (Signature, error)
}