diff --git a/docs/protocol/Constants.md b/docs/protocol/Constants.md new file mode 100644 index 00000000..2ab4f55e --- /dev/null +++ b/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 | + +### 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 | diff --git a/docs/protocol/Validator Sets.md b/docs/protocol/Validator Sets.md new file mode 100644 index 00000000..bfdc8575 --- /dev/null +++ b/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): 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. diff --git a/docs/protocol/Validators.md b/docs/protocol/Validators.md index f2e8cb72..f80f01d2 100644 --- a/docs/protocol/Validators.md +++ b/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`.