From 35956c1c789ef8ca0bce766fb25e41f0d4f9e9a8 Mon Sep 17 00:00:00 2001 From: rigelrozanski Date: Wed, 23 May 2018 15:42:37 -0400 Subject: [PATCH] staking spec state revisions --- docs/spec/slashing/state.md | 13 ++ docs/spec/staking/state.md | 240 ++++++++++++++---------------------- x/stake/delegation.go | 1 - x/stake/shares.go | 3 - x/stake/validator.go | 8 +- 5 files changed, 110 insertions(+), 155 deletions(-) create mode 100644 docs/spec/slashing/state.md diff --git a/docs/spec/slashing/state.md b/docs/spec/slashing/state.md new file mode 100644 index 000000000..0711b01aa --- /dev/null +++ b/docs/spec/slashing/state.md @@ -0,0 +1,13 @@ + + +Validator + +* Adjustment factor used to passively calculate each validators entitled fees + from `GlobalState.FeePool` + +Delegation Shares + +* AdjustmentFeePool: Adjustment factor used to passively calculate each bonds + entitled fees from `GlobalState.FeePool` +* AdjustmentRewardPool: Adjustment factor used to passively calculate each + bonds entitled fees from `Validator.ProposerRewardPool` diff --git a/docs/spec/staking/state.md b/docs/spec/staking/state.md index 397ce1c1c..c5601d044 100644 --- a/docs/spec/staking/state.md +++ b/docs/spec/staking/state.md @@ -10,193 +10,139 @@ indexed by their public key and shares in the global pool. indexed by delegator address and validator pubkey. public key -### Global State +### Pool -The GlobalState contains information about the total amount of Atoms, the -global bonded/unbonded position, the Atom inflation rate, and the fees. +The pool is a space for all dynamic global state of the Cosmos Hub. It tracks +information about the total amounts of Atoms in all states, representative +validator shares for stake in the global pools, moving Atom inflation +information, etc. -`Params` is global data structure that stores system parameters and defines overall functioning of the -module. +```golang +type Pool struct { + LooseUnbondedTokens int64 // tokens not associated with any validator + UnbondedTokens int64 // reserve of unbonded tokens held with validators + UnbondingTokens int64 // tokens moving from bonded to unbonded pool + BondedTokens int64 // reserve of bonded tokens + UnbondedShares sdk.Rat // sum of all shares distributed for the Unbonded Pool + UnbondingShares sdk.Rat // shares moving from Bonded to Unbonded Pool + BondedShares sdk.Rat // sum of all shares distributed for the Bonded Pool + InflationLastTime int64 // block which the last inflation was processed // TODO make time + Inflation sdk.Rat // current annual inflation rate -``` go -type GlobalState struct { - TotalSupply int64 // total supply of Atoms - BondedPool int64 // reserve of bonded tokens - BondedShares rational.Rat // sum of all shares distributed for the BondedPool - UnbondedPool int64 // reserve of unbonding tokens held with validators - UnbondedShares rational.Rat // sum of all shares distributed for the UnbondedPool - InflationLastTime int64 // timestamp of last processing of inflation - Inflation rational.Rat // current annual inflation rate - DateLastCommissionReset int64 // unix timestamp for last commission accounting reset - FeePool coin.Coins // fee pool for all the fee shares which have already been distributed - ReservePool coin.Coins // pool of reserve taxes collected on all fees for governance use - Adjustment rational.Rat // Adjustment factor for calculating global fee accum + DateLastCommissionReset int64 // unix timestamp for last commission accounting reset (daily) } +type PoolShares struct { + Status sdk.BondStatus // either: unbonded, unbonding, or bonded + Amount sdk.Rat // total shares of type ShareKind +} +``` + +### Params + +Params is global data structure that stores system parameters and defines +overall functioning of the stake module. + +```golang type Params struct { - HoldBonded Address // account where all bonded coins are held - HoldUnbonding Address // account where all delegated but unbonding coins are held + InflationRateChange sdk.Rat // maximum annual change in inflation rate + InflationMax sdk.Rat // maximum inflation rate + InflationMin sdk.Rat // minimum inflation rate + GoalBonded sdk.Rat // Goal of percent bonded atoms - InflationRateChange rational.Rational // maximum annual change in inflation rate - InflationMax rational.Rational // maximum inflation rate - InflationMin rational.Rational // minimum inflation rate - GoalBonded rational.Rational // Goal of percent bonded atoms - ReserveTax rational.Rational // Tax collected on all fees - - MaxVals uint16 // maximum number of validators - AllowedBondDenom string // bondable coin denomination - - // gas costs for txs - GasDeclareCandidacy int64 - GasEditCandidacy int64 - GasDelegate int64 - GasRedelegate int64 - GasUnbond int64 + MaxValidators uint16 // maximum number of validators + BondDenom string // bondable coin denomination } ``` ### Validator -The `Validator` holds the current state and some historical -actions of validators. - -``` go -type ValidatorStatus byte - -const ( - Bonded ValidatorStatus = 0x01 - Unbonded ValidatorStatus = 0x02 - Revoked ValidatorStatus = 0x03 -) +The `Validator` holds the current state and some historical actions of the +validator. +```golang type Validator struct { - Status ValidatorStatus - ConsensusPubKey crypto.PubKey - GovernancePubKey crypto.PubKey - Owner crypto.Address - GlobalStakeShares rational.Rat - IssuedDelegatorShares rational.Rat - RedelegatingShares rational.Rat - VotingPower rational.Rat - Commission rational.Rat - CommissionMax rational.Rat - CommissionChangeRate rational.Rat - CommissionChangeToday rational.Rat - ProposerRewardPool coin.Coins - Adjustment rational.Rat - Description Description + Owner sdk.Address // sender of BondTx - UnbondTx returns here + ConsensusPubKey crypto.PubKey // Tendermint consensus pubkey of validator + Revoked bool // has the validator been revoked? + + PoolShares PoolShares // total shares for tokens held in the pool + DelegatorShares sdk.Rat // total shares issued to a validator's delegators + + Description Description // description terms for the validator + BondHeight int64 // earliest height as a bonded validator + BondIntraTxCounter int16 // block-local tx index of validator change + ProposerRewardPool sdk.Coins // reward pool collected from being the proposer + + Commission sdk.Rat // the commission rate of fees charged to any delegators + CommissionMax sdk.Rat // maximum commission rate which this validator can ever charge + CommissionChangeRate sdk.Rat // maximum daily increase of the validator commission + CommissionChangeToday sdk.Rat // commission rate change today, reset each day (UTC time) + + PrevPoolShares PoolShares // total shares of a global hold pools } type Description struct { - Name string - DateBonded string - Identity string - Website string - Details string + Moniker string // name + Identity string // optional identity signature (ex. UPort or Keybase) + Website string // optional website link + Details string // optional details } ``` -Validator parameters are described: -* Status: it can be Bonded (active validator), Unbonding (validator) - or Revoked -* ConsensusPubKey: validator public key that is used strictly for participating in - consensus -* GovernancePubKey: public key used by the validator for governance voting -* Owner: Address that is allowed to unbond coins. -* GlobalStakeShares: Represents shares of `GlobalState.BondedPool` if - `Validator.Status` is `Bonded`; or shares of `GlobalState.Unbondingt Pool` - otherwise -* IssuedDelegatorShares: Sum of all shares a validator issued to delegators - (which includes the validator's self-bond); a delegator share represents - their stake in the Validator's `GlobalStakeShares` * RedelegatingShares: The portion of `IssuedDelegatorShares` which are currently re-delegating to a new validator -* VotingPower: Proportional to the amount of bonded tokens which the validator - has if `Validator.Status` is `Bonded`; otherwise it is equal to `0` -* Commission: The commission rate of fees charged to any delegators -* CommissionMax: The maximum commission rate this validator can charge each - day from the date `GlobalState.DateLastCommissionReset` -* CommissionChangeRate: The maximum daily increase of the validator commission -* CommissionChangeToday: Counter for the amount of change to commission rate - which has occurred today, reset on the first block of each day (UTC time) -* ProposerRewardPool: reward pool for extra fees collected when this validator - is the proposer of a block -* Adjustment factor used to passively calculate each validators entitled fees - from `GlobalState.FeePool` -* Description - * Name: moniker - * DateBonded: date determined which the validator was bonded - * Identity: optional field to provide a signature which verifies the - validators identity (ex. UPort or Keybase) - * Website: optional website link - * Details: optional details -### DelegatorBond +### Delegation Atom holders may delegate coins to validators; under this circumstance their -funds are held in a `DelegatorBond` data structure. It is owned by one +funds are held in a `Delegation` data structure. It is owned by one delegator, and is associated with the shares for one validator. The sender of the transaction is the owner of the bond. -``` go -type DelegatorBond struct { - Validator crypto.PubKey - Shares rational.Rat - AdjustmentFeePool coin.Coins - AdjustmentRewardPool coin.Coins -} -``` - -Description: -* Validator: the public key of the validator: bonding too -* Shares: the number of delegator shares received from the validator -* AdjustmentFeePool: Adjustment factor used to passively calculate each bonds - entitled fees from `GlobalState.FeePool` -* AdjustmentRewardPool: Adjustment factor used to passively calculate each - bonds entitled fees from `Validator.ProposerRewardPool` - - -### QueueElem - -The Unbonding and re-delegation process is implemented using the ordered queue -data structure. All queue elements share a common structure: - ```golang -type QueueElem struct { - Validator crypto.PubKey - InitTime int64 // when the element was added to the queue +type Delegation struct { + DelegatorAddr sdk.Address // delegation owner address + ValidatorAddr sdk.Address // validator owner address + Shares sdk.Rat // delegation shares recieved + Height int64 // last height bond updated } ``` -The queue is ordered so the next element to unbond/re-delegate is at the head. -Every tick the head of the queue is checked and if the unbonding period has -passed since `InitTime`, the final settlement of the unbonding is started or -re-delegation is executed, and the element is popped from the queue. Each -`QueueElem` is persisted in the store until it is popped from the queue. +### UnbondingDelegation -### QueueElemUnbondDelegation - -QueueElemUnbondDelegation structure is used in the unbonding queue. +A UnbondingDelegation object is created every time an unbonding is initiated. +It must be completed with a second transaction provided by the delegation owner +after the unbonding period has passed. ```golang -type QueueElemUnbondDelegation struct { - QueueElem - Payout Address // account to pay out to - Tokens coin.Coins // the value in Atoms of the amount of delegator shares which are unbonding - StartSlashRatio rational.Rat // validator slash ratio +type UnbondingDelegation struct { + DelegationKey []byte // key of the delegation + InitTime int64 // unix time at unbonding initation + InitHeight int64 // block height at unbonding initation + ExpectedTokens sdk.Coins // the value in Atoms of the amount of shares which are unbonding + StartSlashRatio sdk.Rat // validator slash ratio at unbonding initiation } ``` -### QueueElemReDelegate +### Redelegation -QueueElemReDelegate structure is used in the re-delegation queue. +A redelegation object is created every time a redelegation occurs. It must be +completed with a second transaction provided by the delegation owner after the +unbonding period has passed. The destination delegation of a redelegation may +not itself undergo a new redelegation until the original redelegation has been +completed. + + - index: delegation address + - index 2: source validator owner address + - index 3: destination validator owner address ```golang -type QueueElemReDelegate struct { - QueueElem - Payout Address // account to pay out to - Shares rational.Rat // amount of shares which are unbonding - NewValidator crypto.PubKey // validator to bond to after unbond +type Redelegation struct { + SourceDelegation []byte // source delegation key + DestinationDelegation []byte // destination delegation key + InitTime int64 // unix time at redelegation + InitHeight int64 // block height at redelegation + Shares sdk.Rat // amount of shares redelegating } ``` - diff --git a/x/stake/delegation.go b/x/stake/delegation.go index dedac03e5..ae08e0867 100644 --- a/x/stake/delegation.go +++ b/x/stake/delegation.go @@ -10,7 +10,6 @@ import ( // Delegation represents the bond with tokens held by an account. It is // owned by one delegator, and is associated with the voting power of one // pubKey. -// TODO better way of managing space type Delegation struct { DelegatorAddr sdk.Address `json:"delegator_addr"` ValidatorAddr sdk.Address `json:"validator_addr"` diff --git a/x/stake/shares.go b/x/stake/shares.go index d5fe93844..48781e2c6 100644 --- a/x/stake/shares.go +++ b/x/stake/shares.go @@ -4,9 +4,6 @@ import ( sdk "github.com/cosmos/cosmos-sdk/types" ) -// kind of shares -type PoolShareKind byte - // pool shares held by a validator type PoolShares struct { Status sdk.BondStatus `json:"status"` diff --git a/x/stake/validator.go b/x/stake/validator.go index a0b484d71..97e1a827e 100644 --- a/x/stake/validator.go +++ b/x/stake/validator.go @@ -82,10 +82,10 @@ func (v Validator) equal(c2 Validator) bool { // Description - description fields for a validator type Description struct { - Moniker string `json:"moniker"` - Identity string `json:"identity"` - Website string `json:"website"` - Details string `json:"details"` + Moniker string `json:"moniker"` // name + Identity string `json:"identity"` // optional identity signature (ex. UPort or Keybase) + Website string `json:"website"` // optional website link + Details string `json:"details"` // optional details } func NewDescription(moniker, identity, website, details string) Description {