Document the processor/tributary/coordinator/serai flow

docs/coordinator/Coordinator.md

@@ -0,0 +1,40 @@
+# Coordinator
+
+The coordinator is a service which communicates with all of the processors,
+all of the other coordinators over a secondary P2P network, and with the Serai
+node.
+
+This document primarily details its flow with regards to the Serai node and
+processor.
+
+## New Set Event
+
+On `validator_sets::pallet::Event::NewSet`, the coordinator spawns a tributary
+for the new set. It additionally sends the processor
+`key_gen::CoordinatorMessage::GenerateKey`.
+
+## Generated Key Pair
+
+On `key_gen::ProcessorMessage::GeneratedKeyPair`, a
+`validator_sets::pallet::vote` transaction is made to vote in the new key.
+
+The Serai blockchain needs to know the key pair in order for it to be able to
+publish `Batch`s. Additionally, having the Serai blockchain confirm the keys
+provides a BFT consensus guarantee. While the tributary itself could also offer
+a BFT consensus guarantee, there's no point when we'd then get BFT consensus
+on the Serai blockchain anyways.
+
+## Key Generation Event
+
+On `validator_sets::pallet::Event::KeyGen`, the coordinator sends
+`substrate::CoordinatorMessage::ConfirmKeyPair` to the processor.
+
+# Update
+
+On `key_gen::ProcessorMessage::Update`, the coordinator publishes an unsigned
+transaction containing the signed batch to the Serai blockchain.
+
+# Sign Completed
+
+On `sign::ProcessorMessage::Completed`, the coordinator broadcasts the
+contained information to all validators.

docs/coordinator/Tributary.md

@@ -0,0 +1,91 @@
+# Tributary
+
+A tributary is a side-chain, created for a specific multisig instance, used
+as a verifiable broadcast layer.
+
+## Transactions
+
+### Key Gen Commitments
+
+`DkgCommitments` is created when a processor sends the coordinator
+`key_gen::ProcessorMessage::Commitments`. When all validators participating in
+a multisig publish `DkgCommitments`, the coordinator sends the processor
+`key_gen::CoordinatorMessage::Commitments`.
+
+### Key Gen Shares
+
+`DkgShares` is created when a processor sends the coordinator
+`key_gen::ProcessorMessage::Shares`. When all validators participating in
+a multisig publish `DkgShares`, the coordinator sends the processor
+`key_gen::CoordinatorMessage::Shares`.
+
+### External Block
+
+When *TODO*, a `ExternalBlock` transaction is provided. This is used to have
+the group acknowledge and synchronize around the block, without the overhead of
+voting in its acknowledgment.
+
+When a `ExternalBlock` transaction is included, participants are allowed to
+publish transactions to produce a threshold signature for the block's `Batch`.
+
+### Substrate Block
+
+`SubstrateBlock` is provided when the processor sends the coordinator
+`substrate::ProcessorMessage::SubstrateBlockAck`.
+
+When a `SubstrateBlock` transaction is included, participants are allowed to
+publish transactions for the signing protocols it causes.
+
+### Batch Preprocess
+
+`BatchPreprocess` is created when a processor sends the coordinator
+`coordinator::ProcessorMessage::BatchPreprocess` and an `ExternalBlock`
+transaction allowing the batch to be signed has already been included on chain.
+
+When `t` validators have published `BatchPreprocess` transactions, a
+`coordinator::ProcessorMessage::BatchPreprocesses` is sent to the processor.
+
+### Batch Share
+
+`BatchShare` is created when a processor sends the coordinator
+`coordinator::ProcessorMessage::BatchShare`. The relevant `ExternalBlock`
+transaction having already been included on chain follows from
+`coordinator::ProcessorMessage::BatchShare` being a response to a message which
+also has that precondition.
+
+When the `t` validators who first published `BatchPreprocess` transactions have
+published `BatchShare` transactions, a
+`coordinator::ProcessorMessage::BatchShares` with the relevant shares is sent
+to the processor.
+
+### Sign Preprocess
+
+`SignPreprocess` is created when a processor sends the coordinator
+`sign::ProcessorMessage::Preprocess` and a `SubstrateBlock` transaction
+allowing the transaction to be signed has already been included on chain.
+
+When `t` validators have published `SignPreprocess` transactions, a
+`sign::ProcessorMessage::Preprocesses` is sent to the processor.
+
+### Sign Share
+
+`SignShare` is created when a processor sends the coordinator
+`sign::ProcessorMessage::Share`. The relevant `SubstrateBlock` transaction
+having already been included on chain follows from
+`sign::ProcessorMessage::Share` being a response to a message which
+also has that precondition.
+
+When the `t` validators who first published `SignPreprocess` transactions have
+published `SignShare` transactions, a `sign::ProcessorMessage::Shares` with the
+relevant shares is sent to the processor.
+
+## Re-attempts
+
+The key generation and signing protocols, whether batch or transaction, may
+fail if a validator goes offline or takes too long to respond. Accordingly,
+the tributary will schedule re-attempts. These are communicated with
+`key_gen::CoordinatorMessage::GenerateKey`,
+`coordinator::CoordinatorMessage::BatchReattempt`, and
+`sign::CoordinatorMessage::Reattempt`.
+
+TODO: Document the re-attempt scheduling logic.