Add documentation on Validator Sets

docs/protocol/Constants.md

@@ -0,0 +1,51 @@
+# Constants
+
+### Types
+
+These are the list of types used to represent various properties within the
+protocol.
+
+Alias                   | Shorthand | Type    |
+-----------------------------------------------
+Amount                  | Amount    | u64     |
+Curve                   | Curve     | u16     |
+Coin                    | Coin      | u32     |
+Global Validator Set ID | GVSID     | u32     |
+Validator Set Index     | VS        | u8      |
+Key                     | Key       | Vec<u8> |
+
+### Curves
+
+Integer IDs for various curves. It should be noted some curves may be the same,
+yet have distinct IDs due to having different basepoints, and accordingly
+different keys. For such cases, the processor is expected to create one secret
+per curve, and then use DLEq proofs to port keys to other basepoints as needed.
+
+Curve     | ID |
+----------------
+Secp256k1 | 0  |
+Ed25519   | 1  |
+
+### Networks
+
+Every network connected to Serai has a curve and a string ID. While the
+processor generates keys for curves, these keys are bound to specific networks
+via an additive offset created by hashing the network's string ID.
+
+Network  | String ID  | Curve |
+-------------------------------
+Bitcoin  | "bitcoin"  | 0     |
+Ethereum | "ethereum" | 0     |
+Monero   | "monero"   | 1     |
+
+### Coins
+
+Coins exist over a network and have a distinct integer ID.
+
+Coin     | Network  | ID |
+--------------------------
+Bitcoin  | Bitcoin  | 0  |
+Ethereum | Ethereum | 1  |
+USDC     | Ethereum | 2  |
+DAI      | Ethereum | 3  |
+Monero   | Monero   | 4  |

docs/protocol/Validator Sets.md

@@ -0,0 +1,28 @@
+# Validator Sets
+
+Validator Sets are defined at the protocol level, with the following parameters:
+
+- `index` (VS):        Validator set index, a global key atomically increasing
+from 0.
+- `bond`  (Amount):    Amount of bond per key-share of this validator set.
+- `coins` (Vec<Coin>): Coins managed by this validator set.
+
+At launch, there will solely be validator set 0, managing Bitcoin, Ethereum,
+USDC, DAI, and Monero.
+
+### Multisig Management
+
+Every validator set is expected to form a multisig per curve required by its
+coins. This multisig is secure to hold funds up to 67% of the validator set's
+bond value.
+
+### Participation in the BFT process
+
+All validator sets participate in the BFT process. Specifically, a block
+containing `Oraclization`s for a coin must be approved by the BFT majority of
+the validator set responsible for it, along with the BFT majority of the network
+by bond.
+
+At this time, `Oraclization`s for a coin are only expected to be included when a
+validator from the validator set managing the coin is the producer of the block
+in question.

docs/protocol/Validators.md

@@ -1,17 +1,19 @@
-# Register (message)
+# Validators
+
+### Register (message)
 
 - `validator` (signer): Address which will be the validator on Substrate.
 - `manager`   (signer): Address which will manage this validator.
-- `set`       (u8):     Validator set being joined.
+- `set`       (VS):     Validator set being joined.
 
-Marks `validator` as a validator candidate for the given validator set, enabling
-delegation.
+Marks `validator` as a validator candidate for the specified validator set,
+enabling delegation.
 
-# Delegate (message)
+### Delegate (message)
 
   - `delegator` (signer):  Address delegating funds to `validator`.
   - `validator` (address): Registered validator being delegated to.
-  - `amount`    (u64):     Amount of funds being delegated to `validator`.
+  - `amount`    (Amount):  Amount of funds being delegated to `validator`.
 
 Delegated funds will be removed from `delegator`'s wallet and moved to
 `validator`'s bond. If `validator`'s bond is not a multiple of the validator
@@ -21,11 +23,11 @@ delegator reduces their bond.
 Note: At launch, only `validator`'s manager will be able to delegate to
 `validator`, and only in multiples of the validator set's bond.
 
-# Undelegate (message)
+### Undelegate (message)
 
   - `delegator` (signer):  Address removing delegated funds from `validator`.
   - `validator` (address): Registered validator no longer being delegated to.
-  - `amount`    (u64):     Amount of funds no longer being delegated to
+  - `amount`    (Amount):  Amount of funds no longer being delegated to
 `validator`.
 
 If a sufficient amount of funds are queued, the `validator`'s operation
@@ -36,7 +38,7 @@ forming a sufficient queue.
 
 Note: At launch, only multiples of the validator set's bond will be valid.
 
-# Resign (message)
+### Resign (message)
 
   - `validator` (address): Validator being removed from the pool/candidacy.
   - `manager`   (signer):  Manage of `validator`.