Move docs to spec

spec/protocol/Constants.md

@@ -0,0 +1,46 @@
+# Constants
+
+### Types
+
+These are the list of types used to represent various properties within the
+protocol.
+
+| Alias           | Type                                         |
+|-----------------|----------------------------------------------|
+| SeraiAddress    | sr25519::Public (unchecked [u8; 32] wrapper) |
+| Amount          | u64                                          |
+| NetworkId       | NetworkId (Rust enum, SCALE-encoded)         |
+| Coin            | Coin (Rust enum, SCALE-encoded)              |
+| Session         | u32                                          |
+| Validator Set   | (NetworkId, Session)                         |
+| Key             | BoundedVec\<u8, 96>                          |
+| KeyPair         | (SeraiAddress, Key)                          |
+| ExternalAddress | BoundedVec\<u8, 196>                         |
+| Data            | BoundedVec\<u8, 512>                         |
+
+### Networks
+
+Every network connected to Serai operates over a specific curve. The processor
+generates a distinct set of keys per network. Beyond the key-generation itself
+being isolated, the generated keys are further bound to their respective
+networks via an additive offset created by hashing the network's name (among
+other properties). The network's key is used for all coins on that network.
+
+| Network  | Curve     | ID |
+|----------|-----------|----|
+| Serai    | Ristretto | 0  |
+| Bitcoin  | Secp256k1 | 1  |
+| Ethereum | Secp256k1 | 2  |
+| Monero   | Ed25519   | 3  |
+
+### Coins
+
+Coins exist over a network and have a distinct integer ID.
+
+| Coin     | Network  | ID |
+|----------|----------|----|
+| Serai    | Serai    | 0  |
+| Bitcoin  | Bitcoin  | 1  |
+| Ether    | Ethereum | 2  |
+| DAI      | Ethereum | 3  |
+| Monero   | Monero   | 4  |

spec/protocol/In Instructions.md

@@ -0,0 +1,8 @@
+# In Instructions
+
+In Instructions are included onto the Serai blockchain via unsigned
+transactions. In order to ensure the integrity of the included instructions, the
+validator set responsible for the network in question produces a threshold
+signature of their authenticity.
+
+This lets all other validators verify the instructions with an O(1) operation.

spec/protocol/Validator Sets.md

@@ -0,0 +1,54 @@
+# Validator Sets
+
+Validator Sets are defined at the protocol level, with the following parameters:
+
+  - `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.
+
+### Participation in Consensus
+
+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 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.
+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`
+multisig to be `t`-of-`n-1` reduces the fault tolerance of the created multisig
+which is a greater issue. If a node does prevent multisig creation, other
+validators should issue slashes for it/remove it from the Validator Set
+entirely.
+
+Placing the creation on chain also solves the question of if the multisig was
+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 Rotation
+
+Please see `processor/Multisig Rotation.md` for details on the timing.
+
+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 set.
+  - `key_pair`  (KeyPair):   Key pair being set for this `Session`.
+  - `signature` (Signature): A MuSig-style signature of all validators,
+                             confirming this key.