From 53622c613a951afd90e278ab429e75ba3e5fe76b Mon Sep 17 00:00:00 2001 From: Thom Ivy <38070512+thomivy@users.noreply.github.com> Date: Fri, 9 Jun 2023 14:36:34 -0500 Subject: [PATCH] Update and rename signing-manager-v2.md to signing-manager.md (#632) --- dkg-gadget/signing-manager-v2.md | 45 -------------------------------- dkg-gadget/signing-manager.md | 38 +++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 45 deletions(-) delete mode 100644 dkg-gadget/signing-manager-v2.md create mode 100644 dkg-gadget/signing-manager.md diff --git a/dkg-gadget/signing-manager-v2.md b/dkg-gadget/signing-manager-v2.md deleted file mode 100644 index 5cbe13f2e..000000000 --- a/dkg-gadget/signing-manager-v2.md +++ /dev/null @@ -1,45 +0,0 @@ -# Signing Manager - -![](../assets/signing_manager_v2.png) - -## Introduction - -The Signing Manager is the job/work execution and management abstraction used to run threshold-signing protocols over cross-chain messages. The goals for the Signing Manager are to be efficient in the execution of protocols, reliable in the signing of them, and fast in the completion of threshold signing jobs. - - -## Design -The Signing Manager is comprised of two primary components: The signing manager itself, which is a sort of an intermediary between the DKG worker -and the job manager, and the job manager, which is responsible for enqueueing, executing, managing, and handling stalled jobs. - -### The DKG Worker -Relative to the Signing Manager, the DKG worker is responsible for sending finality notifications from the blockchain and signed DKG messages from the gossiping protocol to the signing manager. - -### The Signing Manager -#### Unsigned Proposal Generation from Finality Notifications -When the DKG worker sends a finality notification to the signing manager, the signing manager will check if there are any unsigned proposals for the finalized block. If there are, -then, the signing manager will check to see if the current node is in the set of best authorities. If so, then, the signing manager will send these unsigned proposals to the job manager. - -An important process of the former is the generation of the seed used for symmetrically calculating the signing set. This is done as follows: -* create a seed s where s is `keccak256`(`public_key`, `finality_notification_block`, `unsignedProposal`) -* take s and use it as a seed to random number generator. -* generate a t+1 signing set from this RNG -* if we are in this set, we send it to the signing manager - -#### Signed DKG message handling -When the DKG worker sends a signed DKG message to the signing manager, the signing manager forwards these messages to the job manager for processing. It is up to the job manager to determine how to handle these messages - -### The Job Manager -#### The background worker -![](../assets/signing_manager_v2_job.png) -Every 500ms, the `poll` function is executed. The `poll` function checks the set of active jobs, and sees if any have stalled or have finished. Stalled jobs are removed from the set of active jobs. It is up to a future finality notification to re-enqueue this job. - -Nexr, `poll` checks the enqueued set of jobs associated with each unsigned proposal, and checks to see if any of these jobs need to be moved into the active set. If `j` active jobs may execute in parallel, and, there are `a` < `j` jobs running , then, `poll` will attempt to move at most `j` - `a` jobs from the enqueued set to the active set. When moved to the active set, the corresponding async protocols are also executed. - -### Receiving unsigned proposals -When receiving unsigned proposals, the job manager takes the corresponding async protocol and *initializes* it. Initializing the protocol, as opposed ot *starting* it, means allowing the protocol to begin enqueueing messages. The protocol will not begin executing until the job manager starts it later in the `poll` function. -After initializing the protocol, the job manager will enqueue the job associated with the unsigned proposal, then immediately call `poll` to potentially immediately start the async protocol. - -### Receiving signed DKG messages -When receiving signed DKG messages, the job manager will check to see if it needs to be delivered to any active or enqueued protocol. If delivery cannot be performed, then, there is the possibility that another node started a protocol ahead of the current node, meaning the current node will need to enqueue these messages in such a case. -Later, after the future corresponding protocol is *initialized*, the enqueued messages will be drained and sent to the appropriate protocol. - diff --git a/dkg-gadget/signing-manager.md b/dkg-gadget/signing-manager.md new file mode 100644 index 000000000..a5fd9cce3 --- /dev/null +++ b/dkg-gadget/signing-manager.md @@ -0,0 +1,38 @@ +# Signing Manager + +![](../assets/signing_manager_v2.png) + +## Introduction + +The Signing Manager is a robust system utilized to execute and manage the threshold-signing protocols over cross-chain messages. It is specifically designed to be efficient, reliable, and fast in protocol execution, message signing, and job completion. + +## Design +The Signing Manager primarily consists of two integral components: The Signing Manager and the Job Manager. The former acts as a bridge between the DKG worker and the Job Manager, while the latter takes on the responsibility of enqueueing, executing, handling, and managing stalled jobs. + +### The DKG Worker +In relation to the Signing Manager, the DKG Worker's task is to send finality notifications from the blockchain and signed DKG messages from the gossip protocol to the Signing Manager. + +### The Signing Manager +When the DKG worker transmits a finality notification to the Signing Manager, it checks for any unsigned proposals for the finalized block. If any exist, the Signing Manager verifies if the current node is within the set of best authorities. If confirmed, the Signing Manager forwards these unsigned proposals to the Job Manager. + +A crucial part of this process is the creation of the seed, which is used to symmetrically calculate the signing set. This process entails: + +1. The creation of a seed s where s is derived from the keccak256 algorithm applied to the public_key, finality_notification_block, and unsignedProposal. +2. Utilizing s as a seed to a random number generator. +3. Generating a t+1 signing set from this RNG. +4. If the node is in this set, sending it to the signing manager. + +When the DKG worker delivers a signed DKG message to the Signing Manager, these messages are forwarded to the Job Manager for processing. + + +### The Job Manager (the background worker) +![](../assets/signing_manager_v2_job.png) +This background worker executes the `poll` function every 500ms. The `poll` function assesses the set of active jobs to identify if any have stalled or finished. Stalled jobs are removed from the set of active jobs. + +The `poll` function also examines the enqueued set of jobs associated with each unsigned proposal and determines if any of these jobs need to be transitioned into the active set. If `j` active jobs may execute in parallel, and there are `a` < `j` jobs running, then `poll` attempts to shift at most `j` - `a` jobs from the enqueued set to the active set. When transitioned to the active set, the corresponding asynchronous protocols are also executed. + +### Receiving unsigned proposals +When the Job Manager receives unsigned proposals, it takes the corresponding asynchronous protocol and initializes it. Initializing the protocol, as opposed to starting it, allows the protocol to begin enqueueing messages. The protocol will not commence execution until the Job Manager starts it later in the `poll` function. After initializing the protocol, the Job Manager enqueues the job associated with the unsigned proposal, then immediately executes the `poll` function to potentially start the asynchronous protocol immediately. + +### Receiving signed DKG messages +When the Job Manager receives signed DKG messages, it checks if these need to be delivered to any active or enqueued protocol. If delivery is not possible, the messages are enqueued for future delivery. This could occur if another node has started a protocol ahead of the current node, necessitating the current node to enqueue these messages. Later, once the corresponding future protocol is initialized, the enqueued messages are drained and sent to the appropriate protocol.