Improve DKG engine package documentation

engine/consensus/dkg/doc.go

@@ -1,54 +1,45 @@
-/*
-
-Package dkg implements engines for the DKG protocol.
-
-ReactorEngine
-
-ReactorEngine implements triggers to control the lifecycle of DKG runs. A new
-DKG protocol is started when an EpochSetup event is sealed and finalized. The
-subsequent phase transitions are triggered when specified views are encountered
-(specifically when the first block of a given view is finalized). In between
-phase transitions the engine regularly queries the DKG smart-contract to read
-broadcast messages.
-
-MessagingEngine
-
-MessagingEngine is a network engine that enables consensus nodes to securely
-exchange private DKG messages. Note that broadcast messages are not exchanged
-through this engine, but rather via the DKG smart-contract.
-
-Architecture
-
-For every new epoch, the ReactorEngine instantiates a new DKGController with a
-new Broker using the provided ControllerFactory. The ControllerFactory ties new
-DKGControllers to the MessagingEngine via a BrokerTunnel which exposes channels
-to relay incoming and outgoing messages (cf. module/dkg).
-
-    EpochSetup/OnView
-          |
-          v
-   +---------------+
-   | ReactorEngine |
-   +---------------+
-          |
-          v
-*~~~~~~~~~~~~~~~~~~~~~* (one/epoch)
-|  +---------------+  |
-|  | Controller    |  |
-|  +---------------+  |
-|         |           |
-|         v           |
-|  +---------------+  |
-|  | Broker        |  |
-|  +---------------+  |
-*~~~~~~~~|~~~~~~~~~\~~*
-       tunnel      smart-contract client
-         |           \
-   +--------------+   +------------------+
-   | Messaging    |   | DKGSmartContract |
-   | Engine       |   |                  |
-   +--------------+   +------------------+
-
-*/
-
+// Package dkg implements engines for the DKG protocol.
+//
+// # Reactor Engine
+//
+// The [ReactorEngine] implements triggers to control the lifecycle of DKG instances.
+// A new DKG instance is started when an EpochSetup service event is sealed.
+// The subsequent phase transitions are triggered when specified views are encountered.
+// Specifically, phase transitions for a view V are triggered when the first block with view ≥V is finalized.
+// Between phase transitions, we periodically query the DKG smart-contract ("whiteboard") to read broadcast messages.
+// Before transitioning the state machine to the next phase, we query the whiteboard w.r.t. the final view
+// of the phase - this ensures all participants eventually observe the same set of messages for each phase.
+//
+// # Messaging Engine
+//
+// The [MessagingEngine] is a network engine that enables consensus nodes to securely exchange
+// private (not broadcast) DKG messages. Broadcast messages are sent via the DKG smart contract.
+//
+// # Architecture
+//
+// In the happy path, one DKG instance runs every epoch. For each DKG instance, the [ReactorEngine]
+// instantiates a new, epoch-scoped module.DKGController and module.DKGBroker using the provided dkg.ControllerFactory.
+// The dkg.ControllerFactory ties new module.DKGController's to the [MessagingEngine] via a dkg.BrokerTunnel,
+// which exposes channels to relay incoming and outgoing messages (see package module/dkg for details).
+//
+//	EpochSetup/EpochCommit/OnView events
+//	              ↓
+//	      ┏━━━━━━━━━━━━━━━━━┓
+//	      ┃   ReactorEngine ┃
+//	      ┗━━━━━━━━━━━━━━━━━┛
+//	              ↓
+//	      ┏━━━━━━━━━━━━━━━━━┓    ╮
+//	      ┃   Controller    ┃    │
+//	      ┗━━━━━━━━━━━━━━━━━┛    │
+//	              ↓              ┝ Epoch-scoped components
+//	      ┏━━━━━━━━━━━━━━━━━┓    │
+//	      ┃       Broker    ┃    │
+//	      ┗━━━━━━━━━━━━━━━━━┛    ╯
+//	          │         │
+//	 BrokerTunnel      DKGContractClient
+//	          ↓         ↓
+//	┏━━━━━━━━━━━━━━┓   ┏━━━━━━━━━━━━━━━━━━┓
+//	┃ Messaging    ┃   ┃ FlowDKG smart    ┃
+//	┃ Engine       ┃   ┃ contract         ┃
+//	┗━━━━━━━━━━━━━━┛   ┗━━━━━━━━━━━━━━━━━━┛
 package dkg