From 49906474c1040ff84b630ce6cfcc7a4632219453 Mon Sep 17 00:00:00 2001 From: Jordan Schalm Date: Fri, 22 Nov 2024 14:19:05 -0800 Subject: [PATCH 1/4] 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 From 12d132010bb82d92cbfe3d9be3cbadf42317eb90 Mon Sep 17 00:00:00 2001 From: Jordan Schalm Date: Mon, 25 Nov 2024 09:05:28 -0800 Subject: [PATCH 2/4] dkg package documentation tweaks --- engine/consensus/dkg/doc.go | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/engine/consensus/dkg/doc.go b/engine/consensus/dkg/doc.go index af9393534cf..2feff12aa42 100644 --- a/engine/consensus/dkg/doc.go +++ b/engine/consensus/dkg/doc.go @@ -2,12 +2,13 @@ // // # 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. +// 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 // @@ -16,12 +17,12 @@ // // # 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). +// 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 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 for details). // -// EpochSetup/EpochCommit/OnView +// EpochSetup/EpochCommit/OnView events // | // v // +---------------+ @@ -29,7 +30,7 @@ // +---------------+ // | // v -// *~~~~~~~~~~~~~~~~~~~~~* <- Epoch-scoped +// *~~~~~~~~~~~~~~~~~~~~~* <- Epoch-scoped components // | +---------------+ | // | | Controller | | // | +---------------+ | From fa089b0a59a70bf08933f183024c9cd217e223d3 Mon Sep 17 00:00:00 2001 From: Jordan Schalm Date: Tue, 3 Dec 2024 15:22:25 -0800 Subject: [PATCH 3/4] remove ex-package links these don't resolve correctly when testing locally --- engine/consensus/dkg/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/engine/consensus/dkg/doc.go b/engine/consensus/dkg/doc.go index 2feff12aa42..5bf29b43eaa 100644 --- a/engine/consensus/dkg/doc.go +++ b/engine/consensus/dkg/doc.go @@ -18,8 +18,8 @@ // # 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 ControllerFactory. -// The ControllerFactory ties new DKGControllers to the [MessagingEngine] via a BrokerTunnel, +// 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 From 3f1de8f49f95c4bf909ceb192610dca53a3fe4eb Mon Sep 17 00:00:00 2001 From: Jordan Schalm Date: Tue, 3 Dec 2024 15:23:20 -0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Alexander Hentschel --- engine/consensus/dkg/doc.go | 47 +++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 26 deletions(-) diff --git a/engine/consensus/dkg/doc.go b/engine/consensus/dkg/doc.go index 5bf29b43eaa..15ee9e1e06a 100644 --- a/engine/consensus/dkg/doc.go +++ b/engine/consensus/dkg/doc.go @@ -5,7 +5,7 @@ // 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. +// 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. @@ -22,29 +22,24 @@ // 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 -// | -// v -// +---------------+ -// | ReactorEngine | -// +---------------+ -// | -// v -// *~~~~~~~~~~~~~~~~~~~~~* <- Epoch-scoped components -// | +---------------+ | -// | | Controller | | -// | +---------------+ | -// | | | -// | v | -// | +---------------+ | -// | | Broker | | -// | +---------------+ | -// *~~~~~~~~|~~~~~~~~~\~~* -// | \ -// BrokerTunnel DKGContractClient -// | \ -// +--------------+ +------------------+ -// | Messaging | | FlowDKG smart | -// | Engine | | contract | -// +--------------+ +------------------+ +// EpochSetup/EpochCommit/OnView events +// ↓ +// ┏━━━━━━━━━━━━━━━━━┓ +// ┃ ReactorEngine ┃ +// ┗━━━━━━━━━━━━━━━━━┛ +// ↓ +// ┏━━━━━━━━━━━━━━━━━┓ ╮ +// ┃ Controller ┃ │ +// ┗━━━━━━━━━━━━━━━━━┛ │ +// ↓ ┝ Epoch-scoped components +// ┏━━━━━━━━━━━━━━━━━┓ │ +// ┃ Broker ┃ │ +// ┗━━━━━━━━━━━━━━━━━┛ ╯ +// │ │ +// BrokerTunnel DKGContractClient +// ↓ ↓ +// ┏━━━━━━━━━━━━━━┓ ┏━━━━━━━━━━━━━━━━━━┓ +// ┃ Messaging ┃ ┃ FlowDKG smart ┃ +// ┃ Engine ┃ ┃ contract ┃ +// ┗━━━━━━━━━━━━━━┛ ┗━━━━━━━━━━━━━━━━━━┛ package dkg