From b8b200ac34e31b58b35e6ab4675ea4d6f0cd968b Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Tue, 8 May 2018 17:45:05 -0400 Subject: [PATCH] consolidate into valset-changes.md --- docs/spec/staking/README.md | 4 + docs/spec/staking/slashing.md | 79 ----------------- docs/spec/staking/transactions.md | 39 ++------- .../staking/{time.md => valset-changes.md} | 86 ++++++++++++++++++- 4 files changed, 98 insertions(+), 110 deletions(-) delete mode 100644 docs/spec/staking/slashing.md rename docs/spec/staking/{time.md => valset-changes.md} (51%) diff --git a/docs/spec/staking/README.md b/docs/spec/staking/README.md index 37e07b70b..8ec7b41cf 100644 --- a/docs/spec/staking/README.md +++ b/docs/spec/staking/README.md @@ -34,4 +34,8 @@ The following specification uses *Atom* as the native staking token. The module 4. Unbond 5. Redelegate 6. ProveLive + 3. **[Validator Set Changes](valset-changes.md)** + 1. Validator set updates + 2. Slashing + 3. Automatic Unbonding 3. **[Future improvements](future_improvements.md)** diff --git a/docs/spec/staking/slashing.md b/docs/spec/staking/slashing.md deleted file mode 100644 index c64aa9d79..000000000 --- a/docs/spec/staking/slashing.md +++ /dev/null @@ -1,79 +0,0 @@ - -# Slashing - -A validator bond is an economic commitment made by a validator signing key to both the safety and liveness of -the consensus. Validator keys must not sign invalid messages which could -violate consensus safety, and their signed precommit messages must be regularly included in -block commits. - -The incentivization of these two goals are treated separately. - -## Safety - -Messges which may compromise the safety of the underlying consensus protocol ("equivocations") -result in some amount of the offending validator's shares being removed ("slashed"). - -Currently, such messages include only the following: - -- prevotes by the same validator for more than one BlockID at the same - Height and Round -- precommits by the same validator for more than one BlockID at the same - Height and Round - -We call any such pair of conflicting votes `Evidence`. Full nodes in the network prioritize the -detection and gossipping of `Evidence` so that it may be rapidly included in blocks and the offending -validators punished. - -For some `evidence` to be valid, it must satisfy: - -`evidence.Height >= block.Height - MAX_EVIDENCE_AGE` - -If valid evidence is included in a block, the offending validator loses -a constant `SLASH_PROPORTION` of their current stake: - -``` -oldShares = validator.shares -validator.shares = oldShares * (1 - SLASH_PROPORTION) -``` - -This ensures that offending validators are punished the same amount whether they -act as a single validator with X stake or as N validators with collectively X -stake. - - - -## Liveness - -Every block includes a set of precommits by the validators for the previous block, -known as the LastCommit. A LastCommit is valid so long as it contains precommits from +2/3 of voting power. - -Proposers are incentivized to include precommits from all -validators in the LastCommit by receiving additional fees -proportional to the difference between the voting power included in the -LastCommit and +2/3 (see [TODO](https://github.com/cosmos/cosmos-sdk/issues/967)). - -Validators are penalized for failing to be included in the LastCommit for some -number of blocks by being automatically unbonded. - - -TODO: do we do this by trying to track absence directly in the state, using -something like the below, or do we let users notify the app when a validator has -been absent using the -[TxLivenessCheck](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/spec/staking/spec-technical.md#txlivelinesscheck). - - -A list, `ValidatorAbsenceInfos`, is stored in the state and used to track how often -validators were included in a LastCommit. - -```go -// Ordered by ValidatorAddress. -// One entry for each validator. -type ValidatorAbsenceInfos []ValidatorAbsenceInfo - -type ValidatorAbsenceInfo struct { - ValidatorAddress []byte // address of the validator - FirstHeight int64 // first height the validator was absent - Count int64 // number of heights validator was absent since (and including) first -} -``` - diff --git a/docs/spec/staking/transactions.md b/docs/spec/staking/transactions.md index ceb5e3be8..52f324b0f 100644 --- a/docs/spec/staking/transactions.md +++ b/docs/spec/staking/transactions.md @@ -7,7 +7,6 @@ Available Transactions: * TxDelegate * TxUnbond * TxRedelegate -* TxLivelinessCheck * TxProveLive ## Transaction processing @@ -264,37 +263,10 @@ redelegate(tx TxRedelegate): return ``` -### TxLivelinessCheck - -Liveliness issues are calculated by keeping track of the block precommits in -the block header. A queue is persisted which contains the block headers from -all recent blocks for the duration of the unbonding period. A validator is -defined as having livliness issues if they have not been included in more than -33% of the blocks over: -* The most recent 24 Hours if they have >= 20% of global stake -* The most recent week if they have = 0% of global stake -* Linear interpolation of the above two scenarios - -Liveliness kicks are only checked when a `TxLivelinessCheck` transaction is -submitted. - -```golang -type TxLivelinessCheck struct { - PubKey crypto.PubKey - RewardAccount Addresss -} -``` - -If the `TxLivelinessCheck` is successful in kicking a validator, 5% of the -liveliness punishment is provided as a reward to `RewardAccount`. - ### TxProveLive -If the validator was kicked for liveliness issues and is able to regain -liveliness then all delegators in the temporary unbonding pool which have not -transacted to move will be bonded back to the now-live validator and begin to -once again collect provisions and rewards. Regaining liveliness is demonstrated -by sending in a `TxProveLive` transaction: +If a validator was automatically unbonded due to liveness issues and wishes to +assert it is still online, it can send `TxProveLive`: ```golang type TxProveLive struct { @@ -302,3 +274,10 @@ type TxProveLive struct { } ``` +All delegators in the temporary unbonding pool which have not +transacted to move will be bonded back to the now-live validator and begin to +once again collect provisions and rewards. + +``` +TODO: pseudo-code +``` diff --git a/docs/spec/staking/time.md b/docs/spec/staking/valset-changes.md similarity index 51% rename from docs/spec/staking/time.md rename to docs/spec/staking/valset-changes.md index 45f40a0c3..db2a5f812 100644 --- a/docs/spec/staking/time.md +++ b/docs/spec/staking/valset-changes.md @@ -1,5 +1,89 @@ +# Slashing -### End of block handling +A validator bond is an economic commitment made by a validator signing key to both the safety and liveness of +the consensus. Validator keys must not sign invalid messages which could +violate consensus safety, and their signed precommit messages must be regularly included in +block commits. + +The incentivization of these two goals are treated separately. + +## Safety + +Messges which may compromise the safety of the underlying consensus protocol ("equivocations") +result in some amount of the offending validator's shares being removed ("slashed"). + +Currently, such messages include only the following: + +- prevotes by the same validator for more than one BlockID at the same + Height and Round +- precommits by the same validator for more than one BlockID at the same + Height and Round + +We call any such pair of conflicting votes `Evidence`. Full nodes in the network prioritize the +detection and gossipping of `Evidence` so that it may be rapidly included in blocks and the offending +validators punished. + +For some `evidence` to be valid, it must satisfy: + +`evidence.Height >= block.Height - MAX_EVIDENCE_AGE` + +If valid evidence is included in a block, the offending validator loses +a constant `SLASH_PROPORTION` of their current stake: + +``` +oldShares = validator.shares +validator.shares = oldShares * (1 - SLASH_PROPORTION) +``` + +This ensures that offending validators are punished the same amount whether they +act as a single validator with X stake or as N validators with collectively X +stake. + + + +## Liveness + +Every block includes a set of precommits by the validators for the previous block, +known as the LastCommit. A LastCommit is valid so long as it contains precommits from +2/3 of voting power. + +Proposers are incentivized to include precommits from all +validators in the LastCommit by receiving additional fees +proportional to the difference between the voting power included in the +LastCommit and +2/3 (see [TODO](https://github.com/cosmos/cosmos-sdk/issues/967)). + +Validators are penalized for failing to be included in the LastCommit for some +number of blocks by being automatically unbonded. + + +TODO: do we do this by trying to track absence directly in the state, using +something like the below, or do we let users notify the app when a validator has +been absent using the +[TxLivenessCheck](https://github.com/cosmos/cosmos-sdk/blob/develop/docs/spec/staking/spec-technical.md#txlivelinesscheck). + + +A list, `ValidatorAbsenceInfos`, is stored in the state and used to track how often +validators were included in a LastCommit. + +```go +// Ordered by ValidatorAddress. +// One entry for each validator. +type ValidatorAbsenceInfos []ValidatorAbsenceInfo + +type ValidatorAbsenceInfo struct { + ValidatorAddress []byte // address of the validator + FirstHeight int64 // first height the validator was absent + Count int64 // number of heights validator was absent since (and including) first +} +``` + + +### BeginBlock Handling + + + +### EndBlock Handling + +This is where we inflate the Atoms and deal with validator set changes. ```golang tick(ctx Context):