cosmos-sdk/docs/spec/staking/state.md

State

The staking module persists the following information to the store:

• GlobalState, a struct describing the global pools, inflation, and fees
• ValidatorCandidates: <pubkey | shares> => <candidate>, a map of all candidates (including current validators) in the store, indexed by their public key and shares in the global pool.
• DelegatorBonds: < delegator-address | candidate-pubkey > => <delegator-bond>. a map of all delegations by a delegator to a candidate, indexed by delegator address and candidate pubkey. public key
• UnbondQueue, the queue of unbonding delegations
• RedelegateQueue, the queue of re-delegations

Global State

The GlobalState contains information about the total amount of Atoms, the global bonded/unbonded position, the Atom inflation rate, and the fees.

Params is global data structure that stores system parameters and defines overall functioning of the module.

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 candidates
    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
}

type Params struct {
    HoldBonded   Address // account  where all bonded coins are held
    HoldUnbonding Address // account where all delegated but unbonding coins are held

    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 
}

Candidate

The Candidate holds the current state and some historical actions of validators or candidate-validators.

type CandidateStatus byte

const (
    Bonded   CandidateStatus = 0x01
    Unbonded CandidateStatus = 0x02
    Revoked  CandidateStatus = 0x03
)

type Candidate struct {
    Status                 CandidateStatus       
    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 
}

type Description struct {
    Name       string 
    DateBonded string 
    Identity   string 
    Website    string 
    Details    string 
}

Candidate parameters are described:

• Status: it can be Bonded (active validator), Unbonding (validator candidate) or Revoked
• ConsensusPubKey: candidate 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 Candidate.Status is Bonded; or shares of GlobalState.Unbondingt Pool otherwise
• IssuedDelegatorShares: Sum of all shares a candidate issued to delegators (which includes the candidate's self-bond); a delegator share represents their stake in the Candidate'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 Candidate.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 candidate can charge each day from the date GlobalState.DateLastCommissionReset
• CommissionChangeRate: The maximum daily increase of the candidate 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 candidate 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

Atom holders may delegate coins to candidates; under this circumstance their funds are held in a DelegatorBond data structure. It is owned by one delegator, and is associated with the shares for one candidate. The sender of the transaction is the owner of the bond.

type DelegatorBond struct {
    Candidate            crypto.PubKey
    Shares               rational.Rat
    AdjustmentFeePool    coin.Coins  
    AdjustmentRewardPool coin.Coins  
} 

Description:

• Candidate: the public key of the validator candidate: bonding too
• Shares: the number of delegator shares received from the validator candidate
• 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 Candidate.ProposerRewardPool

QueueElem

The Unbonding and re-delegation process is implemented using the ordered queue data structure. All queue elements share a common structure:

type QueueElem struct {
    Candidate   crypto.PubKey
    InitTime    int64    // when the element was added to the queue
}

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.

QueueElemUnbondDelegation

QueueElemUnbondDelegation structure is used in the unbonding queue.

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  // candidate slash ratio 
}

QueueElemReDelegate

QueueElemReDelegate structure is used in the re-delegation queue.

type QueueElemReDelegate struct {
    QueueElem
    Payout       Address       // account to pay out to
    Shares       rational.Rat  // amount of shares which are unbonding
    NewCandidate crypto.PubKey // validator to bond to after unbond
}