serai/docs/processor/Processor.md

Processor

The processor is a service which has an instance spawned per network. It is responsible for several tasks, from scanning the connected network to signing transactions with payments.

This document primarily discusses its flow with regards to the coordinator.

Generate Key

On key_gen::CoordinatorMessage::GenerateKey, the processor begins a pair of instances of the distributed key generation protocol specified in the FROST paper.

The first instance is for a key to use on the connected network. The second instance is for a Ristretto public key used to publish data to the Serai blockchain. This pair of FROST DKG instances is considered a single instance of Serai's overall key generation protocol.

The commitments for both protocols are sent to the coordinator in a single key_gen::ProcessorMessage::Commitments.

Key Gen Commitments

On key_gen::CoordinatorMessage::Commitments, the processor continues the specified key generation instance. The secret shares for each fellow participant are sent to the coordinator in a key_gen::ProcessorMessage::Shares.

Key Gen Shares

On key_gen::CoordinatorMessage::Shares, the processor completes the specified key generation instance. The generated key pair is sent to the coordinator in a key_gen::ProcessorMessage::GeneratedKeyPair.

Confirm Key Pair

On substrate::CoordinatorMessage::ConfirmKeyPair, the processor starts using the newly confirmed key, scanning blocks on the connected network for transfers to it.

Connected Network Block

When the connected network has a new block, which is considered finalized (either due to being literally finalized or due to having a sufficient amount of confirmations), it's scanned.

Outputs to the key of Serai's multisig are saved to the database. Outputs which newly transfer into Serai are used to build a Batch for the block. The processor then begins a threshold signature protocol with its key pair's Ristretto key to sign the batch. The protocol's preprocess is sent to the coordinator in a coordinator::ProcessorMessage::BatchPreprocess.

As a design comment, we may be able to sign now possible, already scheduled, branch/leaf transactions at this point. Doing so would be giving a mutable borrow over the scheduler to both the external network and the Serai network, and would accordingly be unsafe. We may want to look at splitting the scheduler in two, in order to reduce latency (TODO).

Batch Preprocesses

On coordinator::CoordinatorMessage::BatchPreprocesses, the processor continues the specified batch signing protocol, sending coordinator::ProcessorMessage::BatchShare to the coordinator.

Batch Shares

On coordinator::CoordinatorMessage::BatchShares, the processor completes the specified batch signing protocol. If successful, the processor stops signing for this batch and sends substrate::ProcessorMessage::Update to the coordinator.

Batch Re-attempt

On coordinator::CoordinatorMessage::BatchReattempt, the processor will create a new instance of the batch signing protocol. The new protocol's preprocess is sent to the coordinator in a coordinator::ProcessorMessage::BatchPreprocess.

Substrate Block

On substrate::CoordinatorMessage::SubstrateBlock, the processor:

1. Marks all blocks, up to the external block now considered finalized by Serai, as having had their batches signed.
2. Adds the new outputs from newly finalized blocks to the scheduler, along with the necessary payments from Burn events on Serai.

The processor also sends a substrate::ProcessorMessage::SubstrateBlockAck, containing the IDs of all plans now being signed for, to the coordinator.

Sign Preprocesses

On sign::CoordinatorMessage::Preprocesses, the processor continues the specified transaction signing protocol, sending sign::ProcessorMessage::Share to the coordinator.

Sign Shares

On sign::CoordinatorMessage::Shares, the processor completes the specified transaction signing protocol. If successful, the processor stops signing for this transaction and publishes the signed transaction. Then, sign::ProcessorMessage::Completed is sent to the coordinator, to be broadcasted to all validators so everyone can observe the transaction was signed and stop locally attempting to do so.

Sign Re-attempt

On sign::CoordinatorMessage::Reattempt, the processor will create a new a new instance of the transaction signing protocol. The new protocol's preprocess is sent to the coordinator in a sign::ProcessorMessage::Preprocess.

Sign Completed

On sign::CoordinatorMessage::Completed, the processor verifies the included transaction hash actually refers to an accepted transaction which completes the plan it was supposed to. If so, the processor stops locally signing for the transaction, and emits sign::ProcessorMessage::Completed.