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

     1  /*
     2  Package dkg implements a controller that manages the lifecycle of a Joint
     3  Feldman DKG node, as well as a broker that enables the controller to communicate
     4  with other nodes
     5  
     6  # Controller
     7  
     8  A new controller must be instantiated for every epoch.
     9  
    10  The state-machine can be represented as follows:
    11  
    12  	+-------+  /Run() +---------+  /EndPhase1() +---------+  /EndPhase2() +---------+  /End()   +-----+     +----------+
    13  	| Init  | ----->  | Phase 1 | ------------> | Phase 2 | ------------> | Phase 3 | --------> | End | --> | Shutdown |
    14  	+-------+         +---------+               +---------+               +---------+           +-----+     +----------+
    15  	|                   |                         |                         |                                 ^
    16  	v___________________v_________________________v_________________________v_________________________________|
    17  	                                         /Shutdown()
    18  
    19  The controller is always in one of 6 states:
    20  
    21  - Init: Default state before the instance is started
    22  - Phase 1: 1st phase of the JF DKG protocol while it's running
    23  - Phase 2: 2nd phase ---
    24  - Phase 3: 3rd phase ---
    25  - End: When the DKG protocol is finished
    26  - Shutdown: When the controller and all its routines are stopped
    27  
    28  The controller exposes the following functions to trigger transitions:
    29  
    30  Run(): Triggers transition from Init to Phase1. Starts the DKG protocol instance
    31  and background communication routines.
    32  
    33  EndPhase1(): Triggers transition from Phase 1 to Phase 2.
    34  
    35  EndPhase2(): Triggers transition from Phase 2 to Phase 3.
    36  
    37  End(): Ends the DKG protocol and records the artifacts in controller. Triggers
    38  transition from Phase 3 to End.
    39  
    40  Shutdown(): Can be called from any state to stop the DKG instance.
    41  
    42  The End and Shutdown states differ in that the End state can only be arrived at
    43  from Phase 3 and after successfully computing the DKG artifacts. Whereas the
    44  Shutdown state can be reached from any other state.
    45  
    46  # Broker
    47  
    48  The controller requires a broker to communicate with other nodes over the
    49  network and to read broadcast messages from the DKG smart-contract. A new broker
    50  must be instantiated for every epoch.
    51  
    52  The Broker is responsible for:
    53  
    54    - converting to and from the message format used by the underlying crypto DKG
    55      package.
    56    - appending dkg instance id to messages to prevent replay attacks
    57    - checking the integrity of incoming messages
    58    - signing and verifying broadcast messages (broadcast messages are signed with
    59      the staking key of the sender)
    60    - forwarding incoming messages (private and broadcast) to the controller via a
    61      channel
    62    - forwarding outgoing messages (private and broadcast) to other nodes.
    63  
    64  +------------+  +-------------+
    65  |            |  |             | <--------(tunnel)-----------> network engine <--> Other nodes
    66  | Controller |--| Broker      |
    67  |            |  |             | <--(smart-contract client)--> DKG smart-contract
    68  +------------+  +-------------+
    69  
    70  To relay private messages, the broker uses a BrokerTunnel to communicate with a
    71  network engine.
    72  
    73  To send and receive broadcast messages, the broker communicates with the DKG
    74  smart-contract via a smart-contract client. The broker's Poll method must be
    75  called regularly to read broadcast messages from the smart-contract.
    76  */
    77  package dkg