staking spec state revisions
This commit is contained in:
parent
55cc086f55
commit
35956c1c78
|
@ -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`
|
|
@ -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
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
@ -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"`
|
||||
|
|
|
@ -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"`
|
||||
|
|
|
@ -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 {
|
||||
|
|
Loading…
Reference in New Issue