certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

staking spec state revisions

This commit is contained in:
rigelrozanski 2018-05-23 15:42:37 -04:00
parent 55cc086f55
commit 35956c1c78
5 changed files with 110 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/spec/slashing/state.md Normal file
View File

@ -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`

240
docs/spec/staking/state.md
View File

@ -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
}
```

1
x/stake/delegation.go
View File

@ -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"`

3
x/stake/shares.go
View File

@ -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"`

8
x/stake/validator.go
View File

@ -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 {