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

     1  package module
     2  
     3  import (
     4  	"github.com/onflow/crypto"
     5  
     6  	"github.com/onflow/flow-go/model/flow"
     7  	"github.com/onflow/flow-go/model/messages"
     8  )
     9  
    10  // DKGContractClient enables interacting with the DKG smart contract. This
    11  // contract is deployed to the service account as part of a collection of
    12  // smart contracts that facilitate and manage epoch transitions.
    13  type DKGContractClient interface {
    14  
    15  	// Broadcast broadcasts a message to all other nodes participating in the
    16  	// DKG. The message is broadcast by submitting a transaction to the DKG
    17  	// smart contract. An error is returned if the transaction has failed has
    18  	// failed.
    19  	// TBD: retry logic
    20  	Broadcast(msg messages.BroadcastDKGMessage) error
    21  
    22  	// ReadBroadcast reads the broadcast messages from the smart contract.
    23  	// Messages are returned in the order in which they were broadcast (received
    24  	// and stored in the smart contract). The parameters are:
    25  	//
    26  	// * fromIndex: return messages with index >= fromIndex
    27  	// * referenceBlock: a marker for the state against which the query should
    28  	//   be executed
    29  	//
    30  	// DKG nodes should call ReadBroadcast one final time once they have
    31  	// observed the phase deadline trigger to guarantee they receive all
    32  	// messages for that phase.
    33  	ReadBroadcast(fromIndex uint, referenceBlock flow.Identifier) ([]messages.BroadcastDKGMessage, error)
    34  
    35  	// SubmitResult submits the final public result of the DKG protocol. This
    36  	// represents the group public key and the node's local computation of the
    37  	// public keys for each DKG participant.
    38  	//
    39  	// SubmitResult must be called strictly after the final phase has ended.
    40  	SubmitResult(crypto.PublicKey, []crypto.PublicKey) error
    41  }
    42  
    43  // DKGController controls the execution of a Joint Feldman DKG instance.
    44  type DKGController interface {
    45  
    46  	// Run starts the DKG controller and starts phase 1. It is a blocking call
    47  	// that blocks until the controller is shutdown or until an error is
    48  	// encountered in one of the protocol phases.
    49  	Run() error
    50  
    51  	// EndPhase1 notifies the controller to end phase 1, and start phase 2.
    52  	EndPhase1() error
    53  
    54  	// EndPhase2 notifies the controller to end phase 2, and start phase 3.
    55  	EndPhase2() error
    56  
    57  	// End terminates the DKG state machine and records the artifacts.
    58  	End() error
    59  
    60  	// Shutdown stops the controller regardless of the current state.
    61  	Shutdown()
    62  
    63  	// Poll instructs the controller to actively fetch broadcast messages (ex.
    64  	// read from DKG smart contract). The method does not return until all
    65  	// received messages are processed.
    66  	Poll(blockReference flow.Identifier) error
    67  
    68  	// GetArtifacts returns our node's private key share, the group public key,
    69  	// and the list of all nodes' public keys (including ours), as computed by
    70  	// the DKG.
    71  	GetArtifacts() (crypto.PrivateKey, crypto.PublicKey, []crypto.PublicKey)
    72  
    73  	// GetIndex returns the index of this node in the DKG committee list.
    74  	GetIndex() int
    75  
    76  	// SubmitResult instructs the broker to publish the results of the DKG run
    77  	// (ex. publish to DKG smart contract).
    78  	SubmitResult() error
    79  }
    80  
    81  // DKGControllerFactory is a factory to create instances of DKGController.
    82  type DKGControllerFactory interface {
    83  
    84  	// Create instantiates a new DKGController.
    85  	Create(dkgInstanceID string, participants flow.IdentitySkeletonList, seed []byte) (DKGController, error)
    86  }