absolutebi/serai
1
0
Fork 0
mirror of https://github.com/serai-dex/serai.git synced 2025-12-08 12:19:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

Modernize protocol documentation

Browse Source
This commit is contained in:
Luke Parker
2023-10-16 05:11:31 -04:00
parent e4d59eeeca
commit e06e4edc8e
2 changed files with 24 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/protocol/Constants.md
View File

@@ -9,14 +9,13 @@ protocol.
|-----------------|----------------------------------------------| |-----------------|----------------------------------------------|
| SeraiAddress | sr25519::Public (unchecked [u8; 32] wrapper) | | SeraiAddress | sr25519::Public (unchecked [u8; 32] wrapper) |
| Amount | u64 | | Amount | u64 |
| NetworkId | u16 | | NetworkId | NetworkId (Rust enum, SCALE-encoded) |
| Coin | u32 | | Coin | Coin (Rust enum, SCALE-encoded) |
| Network | Vec<Coin> |
| Session | u32 | | Session | u32 |
| Validator Set | (Session, NetworkId) | | Validator Set | (NetworkId, Session) |
| Key | BoundedVec\<u8, 96> | | Key | BoundedVec\<u8, 96> |
| KeyPair | (SeraiAddress, Key) | | KeyPair | (SeraiAddress, Key) |
| ExternalAddress | BoundedVec\<u8, 128> | | ExternalAddress | BoundedVec\<u8, 196> |
| Data | BoundedVec\<u8, 512> | | Data | BoundedVec\<u8, 512> |
### Networks ### Networks

54
docs/protocol/Validator Sets.md
View File

@@ -2,32 +2,29 @@
Validator Sets are defined at the protocol level, with the following parameters: Validator Sets are defined at the protocol level, with the following parameters:
- `bond` (Amount): Amount of bond per key-share. - `network` (NetworkId): The network this validator set
- `network` (Network): The network this validator set operates operates over.
over. - `allocation_per_key_share` (Amount): Amount of stake needing allocation
- `participants` (Vec\<SeraiAddress>): List of participants within this set. in order to receive a key share.
Validator Sets are referred to by `NetworkId` yet have their data accessible via ### Participation in Consensus
`ValidatorSetInstance`.
### Participation in consensus The validator set for `NetworkId::Serai` participates in Serai's own consensus,
producing and finalizing blocks.
All Validator Sets participate in consensus. In the future, a dedicated group
to order Serai is planned.
### Multisig ### Multisig
Every Validator Set is expected to form a `t`-of-`n` multisig, where `n` is the 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 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 of its networks. This multisig is secure to hold coins valued at up to 33% of
Validator Set's bonded value. If the coins exceed that threshold, there's more the Validator Set's allocated stake. If the coins exceed that threshold, there's
value in the multisig than in the supermajority of bond that must be put forth more value in the multisig and associated liquidity pool than in the
to control it. Accordingly, it'd be no longer financially secure, and it MUST supermajority of allocated stake securing them both. Accordingly, it'd be no
reject newly added coins which would cross that threshold. longer financially secure, and it MUST reject newly added coins.
### Multisig Creation ### 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 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 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` 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. succeeded without creating an instance of the Byzantine Generals Problem.
Placing results within a Byzantine Fault Tolerant system resolves this. Placing results within a Byzantine Fault Tolerant system resolves this.
### Multisig Lifetime ### Multisig Rotation
The keys for a Validator Set remain valid until its participants change. If a Please see `processor/Multisig Rotation.md` for details on the timing.
Validator Set adds a new member, and then they leave, the set's historical keys
are not reused.
### Multisig Handoffs 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,
Once new keys are confirmed for a given Validator Set, they become tracked and they may deallocate their stake.
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.
### Set Keys (message) ### 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`. - `key_pair` (KeyPair): Key pair being set for this `Session`.
- `signature` (Signature): A MuSig-style signature of all validators, - `signature` (Signature): A MuSig-style signature of all validators,
confirming this key. confirming this key.
Once a key is voted on by every member, it's adopted as detailed above.