dkg

Documentation

Overview

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         ┃
┗━━━━━━━━━━━━━━┛   ┗━━━━━━━━━━━━━━━━━━┛

Index

• Constants
• type MessagingEngine
  • func NewMessagingEngine(log zerolog.Logger, net network.EngineRegistry, me module.Local, ...) (*MessagingEngine, error)
  • func (e *MessagingEngine) Process(channel channels.Channel, originID flow.Identifier, message any) error
• type MessagingEngineConfig
  • func DefaultMessagingEngineConfig() MessagingEngineConfig
• type ReactorEngine
  • func NewReactorEngine(log zerolog.Logger, me module.Local, state protocol.State, ...) *ReactorEngine
  • func (e *ReactorEngine) Done() <-chan struct{}
  • func (e *ReactorEngine) EpochCommittedPhaseStarted(currentEpochCounter uint64, first *flow.Header)
  • func (e *ReactorEngine) EpochSetupPhaseStarted(currentEpochCounter uint64, first *flow.Header)
  • func (e *ReactorEngine) Ready() <-chan struct{}

Constants

const DefaultPollStep = 10

DefaultPollStep specifies the default number of views that separate two calls to the DKG smart-contract to read broadcast messages.

Types

type MessagingEngine

type MessagingEngine struct {
	component.Component
	// contains filtered or unexported fields
}

MessagingEngine is an engine which sends and receives all DKG private messages. The same engine instance is used for the lifetime of a node and will be used for different DKG instances. The ReactorEngine is responsible for the lifecycle of components which are scoped one DKG instance, for example the DKGController. The dkg.BrokerTunnel handles routing messages to/from the current DKG instance.

func NewMessagingEngine

func NewMessagingEngine(
	log zerolog.Logger,
	net network.EngineRegistry,
	me module.Local,
	tunnel *dkg.BrokerTunnel,
	collector module.MempoolMetrics,
	config MessagingEngineConfig,
) (*MessagingEngine, error)

NewMessagingEngine returns a new MessagingEngine.

func (*MessagingEngine) Process

func (e *MessagingEngine) Process(channel channels.Channel, originID flow.Identifier, message any) error

Process processes messages from the networking layer. No errors are expected during normal operation.

type MessagingEngineConfig

type MessagingEngineConfig struct {
	// RetryMax is the maximum number of times the engine will attempt to send
	// an outbound message before permanently giving up.
	RetryMax uint64
	// RetryBaseWait is the duration to wait between the two first send attempts.
	RetryBaseWait time.Duration
	// RetryJitterPercent is the percent jitter to add to each inter-retry wait.
	RetryJitterPercent uint64
}

MessagingEngineConfig configures outbound message submission.

func DefaultMessagingEngineConfig

func DefaultMessagingEngineConfig() MessagingEngineConfig

DefaultMessagingEngineConfig returns the config defaults. With 9 attempts and exponential backoff, this will retry for about 8m before giving up.

type ReactorEngine

type ReactorEngine struct {
	events.Noop

	State protocol.State
	// contains filtered or unexported fields
}

ReactorEngine is an engine that reacts to chain events to start new DKG runs, and manage subsequent phase transitions. Any unexpected error triggers a panic as it would undermine the security of the protocol. TODO replace engine.Unit with component.Component

func NewReactorEngine

func NewReactorEngine(
	log zerolog.Logger,
	me module.Local,
	state protocol.State,
	dkgState storage.DKGState,
	controllerFactory module.DKGControllerFactory,
	viewEvents events.Views,
) *ReactorEngine

NewReactorEngine return a new ReactorEngine.

func (*ReactorEngine) Done

func (e *ReactorEngine) Done() <-chan struct{}

Done implements the module ReadyDoneAware interface. It returns a channel that will close when the engine has successfully stopped.

func (*ReactorEngine) EpochCommittedPhaseStarted

func (e *ReactorEngine) EpochCommittedPhaseStarted(currentEpochCounter uint64, first *flow.Header)

EpochCommittedPhaseStarted handles the EpochCommittedPhaseStarted protocol event by checking the consistency of our locally computed key share. NOTE: ReactorEngine will not recover from mid-DKG crashes, therefore we do not need to handle dropped protocol events here.

func (*ReactorEngine) EpochSetupPhaseStarted

func (e *ReactorEngine) EpochSetupPhaseStarted(currentEpochCounter uint64, first *flow.Header)

EpochSetupPhaseStarted handles the EpochSetupPhaseStarted protocol event by starting the DKG process. NOTE: ReactorEngine will not recover from mid-DKG crashes, therefore we do not need to handle dropped protocol events here.

func (*ReactorEngine) Ready

func (e *ReactorEngine) Ready() <-chan struct{}

Ready implements the module ReadyDoneAware interface. It returns a channel that will close when the engine has successfully started.