Modernize protocol documentation

serai-dex · Oct 16, 2023 · e06e4ed · e06e4ed
1 parent e4d59ee
commit e06e4ed
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 39 deletions.
diff --git a/docs/protocol/Constants.md b/docs/protocol/Constants.md
@@ -9,14 +9,13 @@ protocol.
 |-----------------|----------------------------------------------|
 | SeraiAddress    | sr25519::Public (unchecked [u8; 32] wrapper) |
 | Amount          | u64                                          |
-| NetworkId       | u16                                          |
-| Coin            | u32                                          |
-| Network         | Vec<Coin>                                    |
+| NetworkId       | NetworkId (Rust enum, SCALE-encoded)         |
+| Coin            | Coin (Rust enum, SCALE-encoded)              |
 | Session         | u32                                          |
-| Validator Set   | (Session, NetworkId)                         |
+| Validator Set   | (NetworkId, Session)                         |
 | Key             | BoundedVec\<u8, 96>                          |
 | KeyPair         | (SeraiAddress, Key)                          |
-| ExternalAddress | BoundedVec\<u8, 128>                         |
+| ExternalAddress | BoundedVec\<u8, 196>                         |
 | Data            | BoundedVec\<u8, 512>                         |
 
 ### Networks

diff --git a/docs/protocol/Validator Sets.md b/docs/protocol/Validator Sets.md
@@ -2,32 +2,29 @@
 
 Validator Sets are defined at the protocol level, with the following parameters:
 
-  - `bond`         (Amount):             Amount of bond per key-share.
-  - `network`      (Network):            The network this validator set operates
-                                         over.
-  - `participants` (Vec\<SeraiAddress>): List of participants within this set.
+  - `network`                  (NetworkId): The network this validator set
+                                            operates over.
+  - `allocation_per_key_share` (Amount):    Amount of stake needing allocation
+                                            in order to receive a key share.
 
-Validator Sets are referred to by `NetworkId` yet have their data accessible via
-`ValidatorSetInstance`.
+### Participation in Consensus
 
-### Participation in consensus
-
-All Validator Sets participate in consensus. In the future, a dedicated group
-to order Serai is planned.
+The validator set for `NetworkId::Serai` participates in Serai's own consensus,
+producing and finalizing blocks.
 
 ### Multisig
 
 Every Validator Set is expected to form a `t`-of-`n` multisig, where `n` is the
 amount of key shares in the Validator Set and `t` is `n * 2 / 3 + 1`, for each
-of its networks. This multisig is secure to hold coins up to 67% of the
-Validator Set's bonded value. If the coins exceed that threshold, there's more
-value in the multisig than in the supermajority of bond that must be put forth
-to control it. Accordingly, it'd be no longer financially secure, and it MUST
-reject newly added coins which would cross that threshold.
+of its networks. This multisig is secure to hold coins valued at up to 33% of
+the Validator Set's allocated stake. If the coins exceed that threshold, there's
+more value in the multisig and associated liquidity pool than in the
+supermajority of allocated stake securing them both. Accordingly, it'd be no
+longer financially secure, and it MUST reject newly added coins.
 
 ### Multisig Creation
 
-Multisigs are created by processors, communicating via their Coordinators.
+Multisigs are created by Processors, communicating via their Coordinators.
 They're then confirmed on chain via the `validator-sets` pallet. This is done by
 having 100% of participants agree on the resulting group key. While this isn't
 fault tolerant regarding liveliness, a malicious actor who forces a `t`-of-`n`
@@ -41,28 +38,17 @@ successfully created or not. Processors cannot simply ask each other if they
 succeeded without creating an instance of the Byzantine Generals Problem.
 Placing results within a Byzantine Fault Tolerant system resolves this.
 
-### Multisig Lifetime
-
-The keys for a Validator Set remain valid until its participants change. If a
-Validator Set adds a new member, and then they leave, the set's historical keys
-are not reused.
+### Multisig Rotation
 
-### Multisig Handoffs
+Please see `processor/Multisig Rotation.md` for details on the timing.
 
-Once new keys are confirmed for a given Validator Set, they become tracked and
-the recommended set of keys for incoming coins. The old keys are still eligible
-to receive coins for a provided grace period, requiring the current Validator
-Set to track both sets of keys. The old keys are also prioritized for handling
-outbound transfers, until the end of the grace period, at which point they're
-no longer eligible to receive coins and they forward all of their coins to the
-new set of keys. It is only then that validators in the previous instance of the
-set, yet not the current instance, may unbond their stake.
+Once the new multisig publishes its first `Batch`, the old multisig's keys are
+cleared and the set is considered retired. After a one-session cooldown period,
+they may deallocate their stake.
 
 ### Set Keys (message)
 
-  - `network`   (Network):   Network whose key is being voted for.
+  - `network`   (Network):   Network whose key is being set.
   - `key_pair`  (KeyPair):   Key pair being set for this `Session`.
   - `signature` (Signature): A MuSig-style signature of all validators,
-confirming this key.
-
-Once a key is voted on by every member, it's adopted as detailed above.
+                             confirming this key.