From 0bda3240ed9d6b23b8b47f1b9dc605d4198464e0 Mon Sep 17 00:00:00 2001 From: Jordan Schalm Date: Fri, 22 Nov 2024 14:19:05 -0800 Subject: [PATCH] improve dkg engine package docs - put the godoc directly above package declaration so it appears as godoc - remove tabs to correctly align diagram --- engine/consensus/dkg/doc.go | 101 +++++++++++++++++------------------- 1 file changed, 48 insertions(+), 53 deletions(-) diff --git a/engine/consensus/dkg/doc.go b/engine/consensus/dkg/doc.go index 2c72beabc5a..af9393534cf 100644 --- a/engine/consensus/dkg/doc.go +++ b/engine/consensus/dkg/doc.go @@ -1,54 +1,49 @@ -/* - -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 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. +// +// # 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 +// +// For every new epoch, the [ReactorEngine] instantiates a new [module.DKGController] with a +// new [module.DKGBroker] using the provided ControllerFactory. The ControllerFactory ties new +// DKGControllers to the [MessagingEngine] via a BrokerTunnel which exposes channels +// to relay incoming and outgoing messages (see package module/dkg). +// +// EpochSetup/EpochCommit/OnView +// | +// v +// +---------------+ +// | ReactorEngine | +// +---------------+ +// | +// v +// *~~~~~~~~~~~~~~~~~~~~~* <- Epoch-scoped +// | +---------------+ | +// | | Controller | | +// | +---------------+ | +// | | | +// | v | +// | +---------------+ | +// | | Broker | | +// | +---------------+ | +// *~~~~~~~~|~~~~~~~~~\~~* +// | \ +// BrokerTunnel DKGContractClient +// | \ +// +--------------+ +------------------+ +// | Messaging | | FlowDKG smart | +// | Engine | | contract | +// +--------------+ +------------------+ package dkg