摘要
本文规定了 Cosmos SDK 的 Staking 模块，该模块最早于 2016 年 6 月在 Cosmos 白皮书中进行了说明。 该模块使基于 Cosmos SDK 的区块链能够支持高级的权益证明（PoS）系统。在该系统中，链的原生质押代币持有者可以成为验证者，也可以将代币委托给验证者，最终决定系统的有效验证者集合。 该模块已用于 Cosmos Hub，即 Cosmos 网络中的第一个 Hub。目录
状态
资金池
资金池用于跟踪 bond denomination 的已绑定和未绑定代币供应量。上一轮总权重
LastTotalPower 用于跟踪在上一个区块结束时记录的已绑定代币总量。 所有带有Last 前缀的存储条目在 EndBlock 之前都必须保持不变。
- LastTotalPower:
0x12 -> ProtocolBuffer(math.Int)
验证者更新
ValidatorUpdates 包含每个区块结束时返回给 ABCI 的验证者更新。 这些值会在每个区块中被覆盖。- ValidatorUpdates
0x61 -> []abci.ValidatorUpdate
解绑 ID
UnbondingID 存储最新一次解绑操作的 ID。它支持为解绑操作创建唯一 ID，也就是说，每当发起一次新的解绑操作（验证者解绑、解除委托、重新委托）时，UnbondingID 都会递增。- UnbondingID:
0x37 -> uint64
参数
staking 模块以0x51 为前缀将其参数存储在状态中，
这些参数可以通过治理或由具有 authority 的地址进行更新。
- Params:
0x51 | ProtocolBuffer(Params)
验证者
验证者可以具有以下三种状态之一Unbonded：验证者不在活跃集合中。他们不能签名区块，也不会获得 奖励。但他们可以接收委托。Bonded：一旦验证者接收到足够的已绑定代币，他们会在EndBlock期间自动加入 活跃集合，并且其状态会更新为Bonded。 他们会签名区块并获得奖励，也可以继续接收委托。 他们可能因不当行为而被惩罚。向该验证者委托的委托人在解除委托时 必须等待 UnbondingTime，这是一项链级参数；在这段时间内， 如果源验证者的违规行为发生在这些代币处于绑定状态的期间， 这些委托代币仍然可能被惩罚。Unbonding：当验证者因主动退出，或因被惩罚、监禁或 tombstoning 而离开 活跃集合时，其所有委托都会开始解绑。随后所有委托都必须等待 UnbondingTime， 在此之后，其代币才会从BondedPool转入各自账户。
OperatorAddr 进行存储和访问，OperatorAddr 是验证者运营者的 SDK 验证者地址。每个验证者对象还维护了两个附加索引，以满足惩罚和验证者集合更新所需的查询需求。另有第三个特殊索引（LastValidatorPower）也会被维护，但与前两个在区块内镜像验证者记录的索引不同，它在每个区块期间保持不变。
- Validators:
0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator) - ValidatorsByConsAddr:
0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr - ValidatorsByPower:
0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr - LastValidatorsPower:
0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower) - ValidatorsByUnbondingID:
0x38 | UnbondingID -> 0x21 | OperatorAddrLen (1 byte) | OperatorAddr
Validators 是主索引，它确保每个运营者只能关联一个验证者，而该验证者的公钥未来可以发生变化。委托人可以引用验证者不可变的运营者标识，而无需关心公钥的变化。
ValidatorsByUnbondingID 是一个附加索引，用于根据与验证者当前解绑状态对应的解绑 ID 查询验证者。
ValidatorByConsAddr 是一个附加索引，用于支持惩罚查询。当 CometBFT 报告证据时，它提供的是验证者地址，因此需要这个映射来找到对应的运营者。请注意，ConsAddr 对应的地址可以从验证者的 ConsPubKey 推导出来。
ValidatorsByPower 是一个附加索引，它提供了按顺序排列的潜在验证者列表，以便快速确定当前活跃集合。这里的 ConsensusPower 默认等于 validator.Tokens/10^6。请注意，所有 Jailed 为 true 的验证者都不会存储在该索引中。
LastValidatorsPower 是一个特殊索引，它提供上一块中已绑定验证者的历史列表。该索引在一个区块期间保持不变，但会在 EndBlock 中执行的验证者集合更新过程中被更新。
每个验证者的状态都存储在一个 Validator 结构体中：
委托
委托通过组合DelegatorAddr（委托人地址）和 ValidatorAddr 来标识。委托人在存储中的索引方式如下：
- Delegation:
0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)
Delegation 数据结构中。它归属于单个委托人，并与某个验证者的份额相关联。交易发送方就是该 bond 的所有者。
委托人份额
当用户向某个验证者委托代币时，会基于一个动态兑换率获得一定数量的委托人份额。该兑换率根据委托给该验证者的代币总数以及目前已发行的份额数量按如下方式计算：Shares per Token = validator.TotalShares() / validator.Tokens()
在 DelegationEntry 上只会存储所获得的份额数量。随后，当委托人执行 Undelegate 时，他们收到的代币数量会根据其当前持有的份额数量以及反向兑换率来计算：
Tokens per Share = validator.Tokens() / validatorShares()
这些 Shares 只是一个记账机制，并不是可流通资产。之所以采用这种机制，是为了简化与惩罚相关的记账过程。系统无需迭代地惩罚每一条委托记录中的代币，而是可以直接惩罚验证者的已绑定代币总量，从而实际降低每一份已发行委托人份额的价值。
UnbondingDelegation
Delegation 中的份额可以解除绑定，但在一段时间内它们必须以
UnbondingDelegation 的形式存在；如果检测到拜占庭行为，份额可能会被削减。
UnbondingDelegation 在存储中的索引方式如下：
- UnbondingDelegation:
0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation) - UnbondingDelegationsFromValidator:
0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil - UnbondingDelegationByUnbondingId:
0x38 | UnbondingId -> 0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddrUnbondingDelegation用于查询，以查找给定委托人对应的所有解除绑定委托。
UnbondingDelegationsFromValidator 用于惩罚，以查找与给定验证者关联且需要被惩罚的所有解除绑定委托。
UnbondingDelegationByUnbondingId 是一个额外索引，用于根据所包含的解除绑定委托条目的 unbonding ID 查找解除绑定委托。
每次发起解除绑定时，都会创建一个 UnbondingDelegation 对象。
Redelegation
Delegation 所对应的已绑定代币可以立即从源验证者重新委托给另一个验证者（目标验证者）。但发生这种情况时，必须在 Redelegation 对象中跟踪它们；如果这些代币曾对源验证者造成的拜占庭故障有贡献，那么其份额可能会被惩罚。
Redelegation 在存储中的索引方式如下：
- Redelegations:
0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation) - RedelegationsBySrc:
0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil - RedelegationsByDst:
0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil - RedelegationByUnbondingId:
0x38 | UnbondingId -> 0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr
Redelegations 用于查询，以查找给定委托人的所有重新委托。
RedelegationsBySrc 用于基于 ValidatorSrcAddr 执行惩罚。
RedelegationsByDst 用于基于 ValidatorDstAddr 执行惩罚。
这里的第一张映射用于查询，以查找给定委托人的所有重新委托。第二张映射用于基于 ValidatorSrcAddr 执行惩罚，而第三张映射用于基于 ValidatorDstAddr 执行惩罚。
RedelegationByUnbondingId 是一个额外索引，用于根据所包含的重新委托条目的 unbonding ID 查找重新委托。
每次发生重新委托时，都会创建一个 redelegation 对象。为防止“重新委托跳转”，在以下情况下不允许发生重新委托：
- （重新）委托人已经有另一笔尚未成熟、仍在进行中的重新委托，且其目标是某个验证者（记作
Validator X） - 并且，该（重新）委托人正尝试创建一笔新的重新委托，而这笔新重新委托的源验证者正是
Validator X。
Queues
所有队列对象都按时间戳排序。任何队列中使用的时间都会先转换为 UTC，四舍五入到最接近的纳秒，然后再排序。所使用的可排序时间格式是对 RFC3339Nano 的轻微修改，格式字符串为"2006-01-02T15:04:05.000000000"。需要注意的是，这种格式：
- 会在右侧补齐所有零
- 会去掉时区信息（因为我们已经统一使用 UTC）
UnbondingDelegationQueue
为跟踪解除绑定委托的进度，会维护解除绑定委托队列。- UnbondingDelegation:
0x41 | format(time) -> []DVPair
RedelegationQueue
为跟踪重新委托的进度，会维护重新委托队列。- RedelegationQueue:
0x42 | format(time) -> []DVVTriplet
ValidatorQueue
为跟踪解除绑定中的验证者进度，会维护验证者队列。- ValidatorQueueTime:
0x43 | format(time) -> []sdk.ValAddress
HistoricalInfo
HistoricalInfo 对象会在每个区块处被存储并裁剪，因此 staking keeper 会持久化由 staking 模块参数HistoricalEntries 定义的最近 n 条 historical info。
BeginBlock 时，staking keeper 都会将当前的 Header 以及提交当前区块的验证者持久化到一个 HistoricalInfo 对象中。验证者会按其地址排序，以确保顺序具有确定性。
最旧的 HistoricalEntries 会被修剪，以确保历史条目的数量始终不超过参数定义的值。
状态转换
验证者
验证者的状态转换会在每个EndBlock 中执行，以检查活跃 ValidatorSet 是否发生变化。
验证者可以处于 Unbonded、Unbonding 或 Bonded 状态。Unbonded
和 Unbonding 统称为 Not Bonded。验证者可以在这些状态之间直接转换，
唯一例外是不能从 Bonded 直接转换到 Unbonded。
从未绑定到已绑定
当某个验证者在ValidatorPowerIndex 中的排名超过 LastValidator 时，
会发生以下转换：
- 将
validator.Status设为Bonded - 将
validator.Tokens从NotBondedTokens转入BondedPoolModuleAccount - 从
ValidatorByPowerIndex中删除现有记录 - 向
ValidatorByPowerIndex添加一条新的更新记录 - 更新该验证者对应的
Validator对象 - 如果存在，则删除该验证者对应的任何
ValidatorQueue记录
从已绑定到解绑中
当验证者开始解绑流程时，会执行以下操作：- 将
validator.Tokens从BondedPool转入NotBondedTokensModuleAccount - 将
validator.Status设为Unbonding - 从
ValidatorByPowerIndex中删除现有记录 - 向
ValidatorByPowerIndex添加一条新的更新记录 - 更新该验证者对应的
Validator对象 - 为该验证者向
ValidatorQueue插入一条新记录
从解绑中到未绑定
当ValidatorQueue 对象从已绑定转为未绑定时，
验证者会从解绑中状态转为未绑定状态
- 更新该验证者对应的
Validator对象 - 将
validator.Status设为Unbonded
监禁/解除监禁
当验证者被监禁时，它会被有效地从 CometBFT 集合中移除。 这个过程也可以反向执行。会发生以下操作：- 设置
Validator.Jailed并更新对象 - 如果被监禁，则从
ValidatorByPowerIndex删除记录 - 如果解除监禁，则向
ValidatorByPowerIndex添加记录
- power store（从共识投票权到地址）
委托
委托
发生委托时，验证者对象和委托对象都会受到影响- 根据委托的 token 数量和验证者的兑换率确定委托人的 shares
- 从发送账户中移除 token
- 向委托对象中添加 shares，或者将其添加到新创建的验证者对象中
- 添加新的委托人 shares 并更新
Validator对象 - 根据
validator.Status是否为Bonded，将delegation.Amount从委托人账户转入BondedPool或NotBondedPoolModuleAccount - 从
ValidatorByPowerIndex中删除现有记录 - 向
ValidatorByPowerIndex添加一条新的更新记录
开始解绑
作为 Undelegate 和 Complete Unbonding 状态转换的一部分， 可能会调用 Unbond Delegation。- 从委托人处扣减已解绑的 shares
- 将已解绑的 token 添加到一个
UnbondingDelegationEntry - 更新该委托；如果已无剩余 shares，则移除该委托
- 如果该委托属于验证者的 operator，且已无剩余 shares，则触发对验证者的监禁
- 更新验证者，移除委托人的 shares 及其关联的 coins
- 如果验证者状态为
Bonded，则将与已解绑 shares 对应价值的Coins从BondedPool转入NotBondedPoolModuleAccount - 如果验证者为未绑定状态且已无剩余委托 shares，则移除该验证者。
- 如果验证者为未绑定状态且已无剩余委托 shares，则移除该验证者
- 获取一个唯一的
unbondingId，并在UnbondingDelegationByUnbondingId中将其映射到该UnbondingDelegationEntry - 调用
AfterUnbondingInitiated(unbondingId)hook - 将该解绑委托添加到
UnbondingDelegationQueue，其完成时间设置为UnbondingTime
取消一个 UnbondingDelegation 条目
当发生 cancel unbond delegation 时，validator、delegation 以及 UnbondingDelegationQueue 的状态都会被更新。
- 如果取消解绑委托的数量等于
UnbondingDelegation条目的balance，则该UnbondingDelegation条目会从UnbondingDelegationQueue中删除。 - 如果取消解绑委托的数量小于
UnbondingDelegation条目的balance，则该UnbondingDelegation条目会在UnbondingDelegationQueue中用新的余额进行更新。 - 取消的
amount会被重新委托回原始validator。
完成解绑
对于不会立即完成的取消委托，当解绑委托队列元素到期时， 会执行以下操作：- 从
UnbondingDelegation对象中移除该条目 - 将 token 从
NotBondedPoolModuleAccount转入委托人的Account
开始重委托
重委托会影响委托对象、源验证者和目标验证者。- 从源验证者执行一次
unbond委托，以取回与已解绑 shares 对应价值的 token - 使用这些已解绑的 token，将其
Delegate到目标验证者 - 如果
sourceValidator.Status为Bonded，而destinationValidator不是， 则将新委托的 token 从BondedPool转入NotBondedPoolModuleAccount - 否则，如果
sourceValidator.Status不是Bonded，而destinationValidator是Bonded，则将新委托的 token 从NotBondedPool转入BondedPoolModuleAccount - 在相关的
Redelegation中记录一条新条目，写入 token 数量
完成重委托
当重委托完成时，会发生以下操作：- 从
Redelegation对象中移除该条目
惩罚
惩罚验证者
当验证者被惩罚时，会发生以下情况：- 总
slashAmount会被计算为slashFactor（链参数）乘以TokensFromConsensusPower，即违规发生时绑定在该验证者上的 token 总数。 - 所有满足以下条件的解绑委托和伪解绑重委托都会被按
slashFactor对初始余额的比例进行惩罚：违规发生时间早于该验证者发起解绑或重委托的时间。 - 从重委托和解绑委托中被惩罚的每一部分金额，都会从总惩罚金额中扣除。
- 然后，
remaingSlashAmount会根据验证者的状态，从其BondedPool或NonBondedPool中的 token 继续扣减。这会减少 token 的总供应量。
惩罚解绑委托
当验证者被惩罚时，该验证者名下那些在违规发生之后才开始解绑的解绑委托也会被惩罚。该验证者每一笔解绑委托中的每个条目都会按slashFactor 被惩罚。惩罚金额根据该委托的 InitialBalance 计算，并且会设置上限，以避免最终余额变为负数。已完成的（或已到期的）解绑不会被惩罚。
惩罚重委托
当验证者被惩罚时，该验证者名下所有在违规发生之后才开始的重委托也会被惩罚。 重委托会按slashFactor 被惩罚。
在违规发生之前开始的重委托不会被惩罚。
惩罚金额根据该委托的 InitialBalance 计算，并设置上限，
以避免最终余额变为负数。
已成熟的重委托（即已完成伪解绑）不会被惩罚。
份额如何计算
在任意时刻，每个验证者都有一定数量的代币T，并发行了一定数量的份额 S。
每个委托人 i 持有一定数量的份额 S_i。
代币数量等于委托给该验证者的所有代币之和，加上奖励，再减去罚没。
委托人有权获得底层代币中与其份额占比成比例的部分。
因此，委托人 i 有权获得该验证者 T * S_i / S 数量的代币。
当委托人向验证者新增委托代币时，他们会按其贡献比例获得相应数量的份额。
因此，当委托人 j 委托 T_j 个代币时，他们会获得 S_j = S * T_j / T 份额。
此时代币总数变为 T + T_j，份额总数变为 S + S_j。
j 的份额占比与其贡献的总代币占比相同：(S + S_j) / S = (T + T_j) / T。
一种特殊情况是初始委托，此时 T = 0 且 S = 0，因此 T_j / T 未定义。
对于初始委托，委托 T_j 个代币的委托人 j 会获得 S_j = T_j 份额。
因此，一个尚未获得任何奖励且未被罚没的验证者将满足 T = S。
消息
本节描述质押消息的处理方式，以及对状态的相应更新。每条消息创建或修改的状态对象都定义在 state 一节中。MsgCreateValidator
使用MsgCreateValidator 消息创建验证者。
创建验证者时，运营者必须提供初始自委托。
- 已经存在使用该运营者地址注册的其他验证者
- 已经存在使用该公钥注册的其他验证者
- 初始自委托代币的 denom 不是指定的 bonding denom
- 佣金参数有误，具体包括：
MaxRate大于 1 或小于 0- 初始
Rate为负数或大于MaxRate - 初始
MaxChangeRate为负数或大于MaxRate
- 描述字段过大
Validator 对象。
此外，还会使用初始代币委托 Delegation 执行一次自委托。验证者初始状态始终为未绑定，但可能会在第一个 end-block 中变为已绑定。
MsgEditValidator
可以使用MsgEditValidator 消息更新验证者的 Description 和 CommissionRate。
- 初始
CommissionRate为负数或大于MaxRate CommissionRate在前 24 小时内已经更新过CommissionRate大于MaxChangeRate- 描述字段过大
Validator 对象。
MsgDelegate
在此消息中，委托人提供代币，作为回报会收到其验证者的部分（新创建的）delegator-shares，并分配到Delegation.Shares。
- 验证者不存在
AmountCoin的 denom 与params.BondDenom定义的 denom 不同- 兑换率无效，即验证者没有代币（由于罚没）但仍有未清份额
- 委托金额低于允许的最小委托额
Delegation 对象尚不存在，则会作为此消息处理的一部分创建；否则会更新现有的 Delegation，将新获得的份额计入其中。
委托人会按照当前兑换率获得新铸造的份额。
兑换率等于验证者中现有份额数量除以当前已委托代币数量。
验证者会在 ValidatorByPower 索引中更新，而该委托会在 Validators 索引中的验证者对象里被跟踪。
可以向被 jailed 的验证者进行委托，唯一的区别是它在 unjailed 之前不会被加入 power 索引。
MsgUndelegate
MsgUndelegate 消息允许委托人从验证者处解除委托其代币。
- 委托不存在
- 验证者不存在
- 该委托持有的份额少于
Amount对应价值的份额 - 现有
UnbondingDelegation的条目数已达到params.MaxEntries定义的最大值 Amount的 denom 与params.BondDenom定义的 denom 不同
- 验证者的
DelegatorShares和该委托的Shares都会按消息中的SharesAmount减少 - 计算这些份额对应的代币价值，并从验证者持有的代币中移除相应数量的代币
- 对于这些被移除的代币，如果验证者是：
Bonded- 将它们加入UnbondingDelegation中的一个条目（如果UnbondingDelegation不存在则创建），其完成时间为从当前时刻起完整的 unbonding 周期。更新池份额，减少 BondedTokens，并按份额对应的代币价值增加 NotBondedTokens。Unbonding- 将它们加入UnbondingDelegation中的一个条目（如果UnbondingDelegation不存在则创建），完成时间与验证者相同（UnbondingMinTime）。Unbonded- 直接将代币发送给消息中的DelegatorAddr
- 如果该委托中不再有
Shares，则从存储中移除该委托对象- 在这种情况下，如果该委托是验证者的自委托，还会将该验证者关押。
MsgCancelUnbondingDelegation
MsgCancelUnbondingDelegation 消息允许委托人取消 unbondingDelegation 条目，并重新委托回之前的验证者。
unbondingDelegation条目已经处理完毕。cancel unbonding delegation的金额大于该unbondingDelegation条目的余额。- 该
cancel unbonding delegation的高度在委托人的unbondingDelegationQueue中不存在。
- 如果
unbondingDelegation条目的余额为零- 在这种情况下，会从
unbondingDelegationQueue中移除该unbondingDelegation条目。 - 否则，会使用新的
unbondingDelegation条目余额和初始余额更新unbondingDelegationQueue
- 在这种情况下，会从
- 验证者的
DelegatorShares和该委托的Shares都会按消息中的Amount增加。
MsgBeginRedelegate
重新委托命令允许委托人即时切换验证者。一旦解绑期结束，重新委托会在 EndBlocker 中自动完成。- 委托不存在
- 源验证者或目标验证者不存在
- 该委托的份额少于
Amount对应的份额数量 - 源验证者存在一笔尚未成熟的接收中重新委托（即该重新委托可能是传递性的）
- 现有
Redelegation的条目数已达到params.MaxEntries定义的最大值 Amount中Coin的面额与params.BondDenom定义的面额不同
- 源验证者的
DelegatorShares和该委托的Shares都会按消息中的SharesAmount减少 - 计算这些份额对应的 token 数量，并从源验证者持有的 token 中移除该数量
- 如果源验证者处于以下状态：
Bonded- 向Redelegation添加一个条目（如果Redelegation不存在则创建），其完成时间为从当前时间起完整的一个解绑期之后。更新池份额，将BondedTokens按这些份额对应的 token 数量减少，并将NotBondedTokens增加相同数量（不过这可能会在下一步中被实际逆转）Unbonding- 向Redelegation添加一个条目（如果Redelegation不存在则创建），其完成时间与该验证者相同（UnbondingMinTime）Unbonded- 此步骤无需执行任何操作
- 将这些份额对应的 token 委托给目标验证者，这可能会把 token 移回已绑定状态
- 如果源委托中不再有
Shares，则从存储中移除该源委托对象- 在这种情况下，如果该委托是验证者的自委托，还会同时将该验证者关押
MsgUpdateParams
MsgUpdateParams 用于更新 staking 模块参数。
参数通过治理提案更新，签名者为 gov 模块账户地址。
- 签名者不是 staking keeper 中定义的 authority（通常为 gov 模块账户）。
- 更新后参数中的
bond_denom在 bank 模块中供应量为 0（即该 denom 在链上不存在）。
Begin-Block
每次 abci begin block 调用时，历史信息都会按照HistoricalEntries 参数进行存储和裁剪。
历史信息跟踪
如果HistoricalEntries 参数为 0，则 BeginBlock 不执行任何操作。
否则，最新的历史信息会存储在键 historicalInfoKey|height 下，而所有早于 height - HistoricalEntries 的条目都会被删除。
在大多数情况下，这会导致每个区块只裁剪一个条目。
不过，如果 HistoricalEntries 参数被调低，存储中就会有多个必须裁剪的条目。
End-Block
每次 abci end block 调用时，都会执行用于更新队列和验证者集合变更的操作。验证者集合变更
在该过程中，staking 验证者集合会通过每个区块结束时运行的状态转换进行更新。作为此过程的一部分，任何已更新的验证者也会返回给 CometBFT，以纳入 CometBFT 验证者集合，该集合负责在共识层验证 CometBFT 消息。具体操作如下：- 新的验证者集合取自
ValidatorsByPower索引中检索到的前params.MaxValidators个验证者 - 将前一个验证者集合与新的验证者集合进行比较：
- 缺失的验证者开始解绑，其
Tokens会从BondedPool转移到NotBondedPoolModuleAccount - 新的验证者会立即绑定，其
Tokens会从NotBondedPool转移到BondedPoolModuleAccount
- 缺失的验证者开始解绑，其
LastTotalPower 和 LastValidatorsPower 保存了上一个区块结束时的总权重和验证者权重状态，并用于检查 ValidatorsByPower 以及新的总权重中发生的变化；新的总权重是在 EndBlock 期间计算的。
队列
在 staking 中，某些状态转换并不是即时完成的，而是会持续一段时间（通常是解绑期）。当这些转换成熟后，必须执行某些操作来完成该状态变更。这是通过使用队列来实现的，这些队列会在每个区块结束时被检查和处理。解绑中的验证者
当某个验证者被踢出已绑定验证者集合时（无论是因为被关押，还是因为没有足够的已绑定 token），它会开始解绑流程，同时它的所有委托也会开始解绑（但仍然委托给该验证者）。此时，该验证者被称为“解绑中的验证者”，在解绑期结束后，它会成熟为“未绑定验证者”。 每个区块都会检查验证者队列中是否存在已成熟的解绑中验证者（即完成时间<= 当前时间，且完成高度 <= 当前区块高度）。此时，任何已成熟且没有剩余委托的验证者都会从状态中删除。对于所有其他仍有剩余委托的已成熟解绑中验证者，其 validator.Status 会从 types.Unbonding 切换为 types.Unbonded。
外部模块可以通过 PutUnbondingOnHold(unbondingId) 方法暂停解绑操作。
因此，处于暂停状态的解绑操作（例如解绑委托）即使已经成熟，也无法完成。
对于具有 unbondingId 的解绑操作，若要最终完成（在其成熟之后），每一次对 PutUnbondingOnHold(unbondingId) 的调用都必须对应一次对 UnbondingCanComplete(unbondingId) 的调用。
解绑委托
通过以下流程，完成UnbondingDelegations 队列中所有已成熟 UnbondingDelegations.Entries 的解绑：
- 将余额中的 coin 转入委托人的钱包地址
- 从
UnbondingDelegation.Entries中移除已成熟条目 - 如果没有剩余条目，则从存储中移除
UnbondingDelegation对象
重新委托
通过以下流程，完成Redelegations 队列中所有已成熟 Redelegation.Entries 的解绑：
- 从
Redelegation.Entries中移除已成熟条目 - 如果没有剩余条目，则从存储中移除
Redelegation对象
Hooks
其他模块可以注册操作，以便在 staking 中发生某个事件时执行。这些事件可以注册为在 staking 事件Before 或 After 执行（与 hook 名称一致）。staking 可注册以下 hooks：
AfterValidatorCreated(Context, ValAddress) error- 在验证者创建时调用
BeforeValidatorModified(Context, ValAddress) error- 在验证者状态变更时调用
AfterValidatorRemoved(Context, ConsAddress, ValAddress) error- 在验证者被删除时调用
AfterValidatorBonded(Context, ConsAddress, ValAddress) error- 在验证者完成绑定时调用
AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error- 在验证者开始解绑时调用
BeforeDelegationCreated(Context, AccAddress, ValAddress) error- 在委托创建时调用
BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error- 在委托份额被修改时调用
AfterDelegationModified(Context, AccAddress, ValAddress) error- 在委托被创建或修改时调用
BeforeDelegationRemoved(Context, AccAddress, ValAddress) error- 在委托被移除时调用
AfterUnbondingInitiated(Context, UnbondingID)- 在解绑操作（验证者解绑、解绑委托、重新委托）启动时调用
事件
staking 模块会触发以下事件：
EndBlocker
| 类型 | 属性键 | 属性值 |
|---|---|---|
| complete_unbonding | amount | {totalUnbondingAmount} |
| complete_unbonding | validator | {validatorAddress} |
| complete_unbonding | delegator | {delegatorAddress} |
| complete_redelegation | amount | {totalRedelegationAmount} |
| complete_redelegation | source_validator | {srcValidatorAddress} |
| complete_redelegation | destination_validator | {dstValidatorAddress} |
| complete_redelegation | delegator | {delegatorAddress} |
消息
MsgCreateValidator
| 类型 | 属性键 | 属性值 |
|---|---|---|
| create_validator | validator | {validatorAddress} |
| create_validator | amount | {delegationAmount} |
| message | module | staking |
| message | action | create_validator |
| message | sender | {senderAddress} |
MsgEditValidator
| 类型 | 属性键 | 属性值 |
|---|---|---|
| edit_validator | commission_rate | {commissionRate} |
| edit_validator | min_self_delegation | {minSelfDelegation} |
| message | module | staking |
| message | action | edit_validator |
| message | sender | {senderAddress} |
MsgDelegate
| 类型 | 属性键 | 属性值 |
|---|---|---|
| delegate | validator | {validatorAddress} |
| delegate | amount | {delegationAmount} |
| message | module | staking |
| message | action | delegate |
| message | sender | {senderAddress} |
MsgUndelegate
| 类型 | 属性键 | 属性值 |
|---|---|---|
| unbond | validator | {validatorAddress} |
| unbond | amount | {unbondAmount} |
| unbond | completion_time [0] | {completionTime} |
| message | module | staking |
| message | action | begin_unbonding |
| message | sender | {senderAddress} |
- [0] 时间按 RFC3339 标准格式化
MsgCancelUnbondingDelegation
| 类型 | 属性键 | 属性值 |
|---|---|---|
| cancel_unbonding_delegation | validator | {validatorAddress} |
| cancel_unbonding_delegation | delegator | {delegatorAddress} |
| cancel_unbonding_delegation | amount | {cancelUnbondingDelegationAmount} |
| cancel_unbonding_delegation | creation_height | {unbondingCreationHeight} |
| message | module | staking |
| message | action | cancel_unbond |
| message | sender | {senderAddress} |
MsgBeginRedelegate
| 类型 | 属性键 | 属性值 |
|---|---|---|
| redelegate | source_validator | {srcValidatorAddress} |
| redelegate | destination_validator | {dstValidatorAddress} |
| redelegate | amount | {unbondAmount} |
| redelegate | completion_time [0] | {completionTime} |
| message | module | staking |
| message | action | begin_redelegate |
| message | sender | {senderAddress} |
- [0] 时间按 RFC3339 标准格式化
参数
staking 模块包含以下参数：
| 键 | 类型 | 示例 |
|---|---|---|
| UnbondingTime | string（时间 ns） | “259200000000000” |
| MaxValidators | uint16 | 100 |
| KeyMaxEntries | uint16 | 7 |
| HistoricalEntries | uint16 | 3 |
| BondDenom | string | ”stake” |
| MinCommissionRate | string | ”0.000000000000000000” |
客户端
CLI
用户可以使用 CLI 查询并与staking 模块交互。
查询
query 命令允许用户查询 staking 状态。
delegation
delegation 命令允许用户查询单个委托人在单个验证者上的委托。
用法：
delegations
delegations 命令允许用户查询单个委托人在所有验证者上的委托。
用法：
delegations-to
delegations-to 命令允许用户查询单个验证者上的委托。
用法：
historical-info
historical-info 命令允许用户查询指定高度的历史信息。
用法：
params
params 命令允许用户查询设置为质押参数的值。
用法：
pool
pool 命令允许用户查询存储在质押池中的金额数值。
用法：
redelegation
redelegation 命令允许用户根据委托人地址以及源验证者和目标验证者地址查询一条重新委托记录。
用法：
redelegations
redelegations 命令允许用户查询某个委托人的全部重新委托记录。
用法：
redelegations-from
redelegations-from 命令允许用户查询正在从某个验证者重新委托出去的委托记录。
用法：
unbonding-delegation
unbonding-delegation 命令允许用户查询某个委托人在某个验证者上的解绑委托。
用法：
unbonding-delegations
unbonding-delegations 命令允许用户查询某个委托人的全部解绑委托记录。
用法：
unbonding-delegations-from
unbonding-delegations-from 命令允许用户查询从某个验证者 发起解绑 的委托。
用法：
validator
validator 命令允许用户查询单个验证者的详细信息。
用法：
validators
validators 命令允许用户查询网络中所有验证者的详细信息。
用法：
交易
tx 命令允许用户与 staking 模块交互。
create-validator
create-validator 命令允许用户创建新的验证者，并在创建时为其初始化一笔自委托。
用法：
validator.json 包含：
simd tendermint show-validator 命令获取。
delegate
delegate 命令允许用户将流动代币委托给某个验证者。
用法：
edit-validator
edit-validator 命令允许用户编辑现有的验证者账户。
用法：
redelegate
redelegate 命令允许用户将非流动代币从一个验证者重新委托给另一个验证者。
用法：
unbond
unbond 命令允许用户从某个验证者处解绑份额。
用法：
cancel unbond
cancel-unbond 命令允许用户取消正在解绑的委托条目，并重新委托回原始验证者。
用法：
gRPC
用户可以使用 gRPC 端点查询staking 模块。
Validators
Validators 端点用于查询所有符合给定状态的验证者。
Validator
Validator 端点用于查询给定验证者地址的验证者信息。
ValidatorDelegations
ValidatorDelegations 端点用于查询给定验证者的委托信息。
ValidatorUnbondingDelegations
ValidatorUnbondingDelegations 端点用于查询给定验证者的委托信息。
Delegation
Delegation 端点用于查询给定验证者与委托人组合的委托信息。
UnbondingDelegation
UnbondingDelegation 端点用于查询给定验证者与委托人的解绑委托信息。
DelegatorDelegations
DelegatorDelegations 端点用于查询给定委托人地址的全部委托。
DelegatorUnbondingDelegations
DelegatorUnbondingDelegations 端点用于查询给定委托人地址的全部解绑委托。
Redelegations
Redelegations 端点用于查询给定地址的重新委托信息。
DelegatorValidators
DelegatorValidators 端点用于查询给定委托人的所有验证者信息。
DelegatorValidator
DelegatorValidator 端点用于查询给定委托人与验证者对应的验证者信息。
HistoricalInfo
Pool
Pool 端点用于查询池信息。
Params
Params 端点用于查询池信息。
REST
用户可以使用 REST 端点查询staking 模块。
DelegatorDelegations
DelegtaorDelegations REST 端点用于查询给定委托人地址的所有委托。
Redelegations
Redelegations REST 端点用于查询给定地址的再委托。
DelegatorUnbondingDelegations
DelegatorUnbondingDelegations REST 端点用于查询给定委托人地址的所有解绑中委托。
DelegatorValidators
DelegatorValidators REST 端点用于查询给定委托人地址对应的所有验证者信息。
DelegatorValidator
DelegatorValidator REST 端点用于查询给定委托人和验证者配对的信息。
HistoricalInfo
HistoricalInfo REST 端点用于查询给定高度的历史信息。
Parameters
Parameters REST 端点用于查询质押参数。
Pool
Pool REST 端点用于查询资金池信息。
验证人
Validators REST 端点会查询所有与给定状态匹配的验证人。
验证人
Validator REST 端点会查询给定验证人地址的验证人信息。
ValidatorDelegations
ValidatorDelegations REST 端点会查询给定验证人的委托信息。
委托
Delegation REST 端点会查询给定验证人和委托人地址对的委托信息。
解除绑定委托
UnbondingDelegation REST 端点会查询给定验证人和委托人地址对的解除绑定信息。
ValidatorUnbondingDelegations
ValidatorUnbondingDelegations REST 端点用于查询某个验证者的解除委托中的委托。
Abstract
This paper specifies the Staking module of the Cosmos SDK that was first described in the Cosmos Whitepaper in June 2016. The module enables Cosmos SDK-based blockchain to support an advanced Proof-of-Stake (PoS) system. In this system, holders of the native staking token of the chain can become validators and can delegate tokens to validators, ultimately determining the effective validator set for the system. This module is used in the Cosmos Hub, the first Hub in the Cosmos network.Contents
State
Pool
Pool is used for tracking bonded and not-bonded token supply of the bond denomination.LastTotalPower
LastTotalPower tracks the total amounts of bonded tokens recorded during the previous end block. Store entries prefixed with “Last” must remain unchanged until EndBlock.- LastTotalPower:
0x12 -> ProtocolBuffer(math.Int)
ValidatorUpdates
ValidatorUpdates contains the validator updates returned to ABCI at the end of every block. The values are overwritten in every block.- ValidatorUpdates
0x61 -> []abci.ValidatorUpdate
UnbondingID
UnbondingID stores the ID of the latest unbonding operation. It enables creating unique IDs for unbonding operations, i.e., UnbondingID is incremented every time a new unbonding operation (validator unbonding, unbonding delegation, redelegation) is initiated.- UnbondingID:
0x37 -> uint64
Params
The staking module stores its params in state with the prefix of0x51,
it can be updated with governance or the address with authority.
- Params:
0x51 | ProtocolBuffer(Params)
Validator
Validators can have one of three statusesUnbonded: The validator is not in the active set. They cannot sign blocks and do not earn rewards. They can receive delegations.Bonded: Once the validator receives sufficient bonded tokens they automatically join the active set duringEndBlockand their status is updated toBonded. They are signing blocks and receiving rewards. They can receive further delegations. They can be slashed for misbehavior. Delegators to this validator who unbond their delegation must wait the duration of the UnbondingTime, a chain-specific param, during which time they are still slashable for offences of the source validator if those offences were committed during the period of time that the tokens were bonded.Unbonding: When a validator leaves the active set, either by choice or due to slashing, jailing or tombstoning, an unbonding of all their delegations begins. All delegations must then wait the UnbondingTime before their tokens are moved to their accounts from theBondedPool.
OperatorAddr, an SDK validator address for the operator of the validator. Two
additional indices are maintained per validator object in order to fulfill
required lookups for slashing and validator-set updates. A third special index
(LastValidatorPower) is also maintained which however remains constant
throughout each block, unlike the first two indices which mirror the validator
records within a block.
- Validators:
0x21 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(validator) - ValidatorsByConsAddr:
0x22 | ConsAddrLen (1 byte) | ConsAddr -> OperatorAddr - ValidatorsByPower:
0x23 | BigEndian(ConsensusPower) | OperatorAddrLen (1 byte) | OperatorAddr -> OperatorAddr - LastValidatorsPower:
0x11 | OperatorAddrLen (1 byte) | OperatorAddr -> ProtocolBuffer(ConsensusPower) - ValidatorsByUnbondingID:
0x38 | UnbondingID -> 0x21 | OperatorAddrLen (1 byte) | OperatorAddr
Validators is the primary index - it ensures that each operator can have only one
associated validator, where the public key of that validator can change in the
future. Delegators can refer to the immutable operator of the validator, without
concern for the changing public key.
ValidatorsByUnbondingID is an additional index that enables lookups for
validators by the unbonding IDs corresponding to their current unbonding.
ValidatorByConsAddr is an additional index that enables lookups for slashing.
When CometBFT reports evidence, it provides the validator address, so this
map is needed to find the operator. Note that the ConsAddr corresponds to the
address which can be derived from the validator’s ConsPubKey.
ValidatorsByPower is an additional index that provides a sorted list of
potential validators to quickly determine the current active set. Here
ConsensusPower is validator.Tokens/10^6 by default. Note that all validators
where Jailed is true are not stored within this index.
LastValidatorsPower is a special index that provides a historical list of the
last-block’s bonded validators. This index remains constant during a block but
is updated during the validator set update process which takes place in EndBlock.
Each validator’s state is stored in a Validator struct:
Delegation
Delegations are identified by combiningDelegatorAddr (the address of the delegator)
with the ValidatorAddr Delegators are indexed in the store as follows:
- Delegation:
0x31 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(delegation)
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.
Delegator Shares
When one delegates tokens to a Validator, they are issued a number of delegator shares based on a dynamic exchange rate, calculated as follows from the total number of tokens delegated to the validator and the number of shares issued so far:Shares per Token = validator.TotalShares() / validator.Tokens()
Only the number of shares received is stored on the DelegationEntry. When a delegator then
Undelegates, the token amount they receive is calculated from the number of shares they currently
hold and the inverse exchange rate:
Tokens per Share = validator.Tokens() / validatorShares()
These Shares are simply an accounting mechanism. They are not a fungible asset. The reason for
this mechanism is to simplify the accounting around slashing. Rather than iteratively slashing the
tokens of every delegation entry, instead the Validator’s total bonded tokens can be slashed,
effectively reducing the value of each issued delegator share.
UnbondingDelegation
Shares in aDelegation can be unbonded, but they must for some time exist as
an UnbondingDelegation, where shares can be reduced if Byzantine behavior is
detected.
UnbondingDelegation are indexed in the store as:
- UnbondingDelegation:
0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddr -> ProtocolBuffer(unbondingDelegation) - UnbondingDelegationsFromValidator:
0x33 | ValidatorAddrLen (1 byte) | ValidatorAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil - UnbondingDelegationByUnbondingId:
0x38 | UnbondingId -> 0x32 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorAddrUnbondingDelegationis used in queries, to lookup all unbonding delegations for a given delegator.
UnbondingDelegationsFromValidator is used in slashing, to lookup all
unbonding delegations associated with a given validator that need to be
slashed.
UnbondingDelegationByUnbondingId is an additional index that enables
lookups for unbonding delegations by the unbonding IDs of the containing
unbonding delegation entries.
A UnbondingDelegation object is created every time an unbonding is initiated.
Redelegation
The bonded tokens worth of aDelegation may be instantly redelegated from a
source validator to a different validator (destination validator). However when
this occurs they must be tracked in a Redelegation object, whereby their
shares can be slashed if their tokens have contributed to a Byzantine fault
committed by the source validator.
Redelegation are indexed in the store as:
- Redelegations:
0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr -> ProtocolBuffer(redelegation) - RedelegationsBySrc:
0x35 | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil - RedelegationsByDst:
0x36 | ValidatorDstAddrLen (1 byte) | ValidatorDstAddr | ValidatorSrcAddrLen (1 byte) | ValidatorSrcAddr | DelegatorAddrLen (1 byte) | DelegatorAddr -> nil - RedelegationByUnbondingId:
0x38 | UnbondingId -> 0x34 | DelegatorAddrLen (1 byte) | DelegatorAddr | ValidatorAddrLen (1 byte) | ValidatorSrcAddr | ValidatorDstAddr
Redelegations is used for queries, to lookup all redelegations for a given
delegator.
RedelegationsBySrc is used for slashing based on the ValidatorSrcAddr.
RedelegationsByDst is used for slashing based on the ValidatorDstAddr
The first map here is used for queries, to lookup all redelegations for a given
delegator. The second map is used for slashing based on the ValidatorSrcAddr,
while the third map is for slashing based on the ValidatorDstAddr.
RedelegationByUnbondingId is an additional index that enables
lookups for redelegations by the unbonding IDs of the containing
redelegation entries.
A redelegation object is created every time a redelegation occurs. To prevent
“redelegation hopping” redelegations may not occur under the situation that:
- the (re)delegator already has another immature redelegation in progress
with a destination to a validator (let’s call it
Validator X) - and, the (re)delegator is attempting to create a new redelegation
where the source validator for this new redelegation is
Validator X.
Queues
All queue objects are sorted by timestamp. The time used within any queue is firstly converted to UTC, rounded to the nearest nanosecond then sorted. The sortable time format used is a slight modification of the RFC3339Nano and uses the format string"2006-01-02T15:04:05.000000000". Notably this format:
- right pads all zeros
- drops the time zone info (we already use UTC)
UnbondingDelegationQueue
For the purpose of tracking progress of unbonding delegations the unbonding delegations queue is kept.- UnbondingDelegation:
0x41 | format(time) -> []DVPair
RedelegationQueue
For the purpose of tracking progress of redelegations the redelegation queue is kept.- RedelegationQueue:
0x42 | format(time) -> []DVVTriplet
ValidatorQueue
For the purpose of tracking progress of unbonding validators the validator queue is kept.- ValidatorQueueTime:
0x43 | format(time) -> []sdk.ValAddress
HistoricalInfo
HistoricalInfo objects are stored and pruned at each block such that the staking keeper persists then most recent historical info defined by staking module parameter: HistoricalEntries.
HistoricalInfo object. The Validators are sorted on their address to ensure that
they are in a deterministic order.
The oldest HistoricalEntries will be pruned to ensure that there only exist the parameter-defined number of
historical entries.
State Transitions
Validators
State transitions in validators are performed on everyEndBlock
in order to check for changes in the active ValidatorSet.
A validator can be Unbonded, Unbonding or Bonded. Unbonded
and Unbonding are collectively called Not Bonded. A validator can move
directly between all the states, except for from Bonded to Unbonded.
Not bonded to Bonded
The following transition occurs when a validator’s ranking in theValidatorPowerIndex surpasses
that of the LastValidator.
- set
validator.StatustoBonded - send the
validator.Tokensfrom theNotBondedTokensto theBondedPoolModuleAccount - delete the existing record from
ValidatorByPowerIndex - add a new updated record to the
ValidatorByPowerIndex - update the
Validatorobject for this validator - if it exists, delete any
ValidatorQueuerecord for this validator
Bonded to Unbonding
When a validator begins the unbonding process the following operations occur:- send the
validator.Tokensfrom theBondedPoolto theNotBondedTokensModuleAccount - set
validator.StatustoUnbonding - delete the existing record from
ValidatorByPowerIndex - add a new updated record to the
ValidatorByPowerIndex - update the
Validatorobject for this validator - insert a new record into the
ValidatorQueuefor this validator
Unbonding to Unbonded
A validator moves from unbonding to unbonded when theValidatorQueue object
moves from bonded to unbonded
- update the
Validatorobject for this validator - set
validator.StatustoUnbonded
Jail/Unjail
when a validator is jailed it is effectively removed from the CometBFT set. this process may be also be reversed. the following operations occur:- set
Validator.Jailedand update object - if jailed delete record from
ValidatorByPowerIndex - if unjailed add record to
ValidatorByPowerIndex
- the power store (from consensus power to address)
Delegations
Delegate
When a delegation occurs both the validator and the delegation objects are affected- determine the delegators shares based on tokens delegated and the validator’s exchange rate
- remove tokens from the sending account
- add shares the delegation object or add them to a created validator object
- add new delegator shares and update the
Validatorobject - transfer the
delegation.Amountfrom the delegator’s account to theBondedPoolor theNotBondedPoolModuleAccountdepending if thevalidator.StatusisBondedor not - delete the existing record from
ValidatorByPowerIndex - add an new updated record to the
ValidatorByPowerIndex
Begin Unbonding
As a part of the Undelegate and Complete Unbonding state transitions Unbond Delegation may be called.- subtract the unbonded shares from delegator
- add the unbonded tokens to an
UnbondingDelegationEntry - update the delegation or remove the delegation if there are no more shares
- if the delegation is the operator of the validator and no more shares exist then trigger a jail validator
- update the validator with removed the delegator shares and associated coins
- if the validator state is
Bonded, transfer theCoinsworth of the unbonded shares from theBondedPoolto theNotBondedPoolModuleAccount - remove the validator if it is unbonded and there are no more delegation shares.
- remove the validator if it is unbonded and there are no more delegation shares
- get a unique
unbondingIdand map it to theUnbondingDelegationEntryinUnbondingDelegationByUnbondingId - call the
AfterUnbondingInitiated(unbondingId)hook - add the unbonding delegation to
UnbondingDelegationQueuewith the completion time set toUnbondingTime
Cancel an UnbondingDelegation Entry
When a cancel unbond delegation occurs both the validator, the delegation and an UnbondingDelegationQueue state will be updated.
- if cancel unbonding delegation amount equals to the
UnbondingDelegationentrybalance, then theUnbondingDelegationentry deleted fromUnbondingDelegationQueue. - if the
cancel unbonding delegation amount is less than theUnbondingDelegationentry balance, then theUnbondingDelegationentry will be updated with new balance in theUnbondingDelegationQueue`. - cancel
amountis Delegated back to the originalvalidator.
Complete Unbonding
For undelegations which do not complete immediately, the following operations occur when the unbonding delegation queue element matures:- remove the entry from the
UnbondingDelegationobject - transfer the tokens from the
NotBondedPoolModuleAccountto the delegatorAccount
Begin Redelegation
Redelegations affect the delegation, source and destination validators.- perform an
unbonddelegation from the source validator to retrieve the tokens worth of the unbonded shares - using the unbonded tokens,
Delegatethem to the destination validator - if the
sourceValidator.StatusisBonded, and thedestinationValidatoris not, transfer the newly delegated tokens from theBondedPoolto theNotBondedPoolModuleAccount - otherwise, if the
sourceValidator.Statusis notBonded, and thedestinationValidatorisBonded, transfer the newly delegated tokens from theNotBondedPoolto theBondedPoolModuleAccount - record the token amount in an new entry in the relevant
Redelegation
Complete Redelegation
When a redelegations complete the following occurs:- remove the entry from the
Redelegationobject
Slashing
Slash Validator
When a Validator is slashed, the following occurs:- The total
slashAmountis calculated as theslashFactor(a chain parameter) *TokensFromConsensusPower, the total number of tokens bonded to the validator at the time of the infraction. - Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occurred before the unbonding or
redelegation began from the validator are slashed by the
slashFactorpercentage of the initialBalance. - Each amount slashed from redelegations and unbonding delegations is subtracted from the total slash amount.
- The
remaingSlashAmountis then slashed from the validator’s tokens in theBondedPoolorNonBondedPooldepending on the validator’s status. This reduces the total supply of tokens.
Slash Unbonding Delegation
When a validator is slashed, so are those unbonding delegations from the validator that began unbonding after the time of the infraction. Every entry in every unbonding delegation from the validator is slashed byslashFactor. The amount slashed is calculated from the InitialBalance of the
delegation and is capped to prevent a resulting negative balance. Completed (or mature) unbondings are not slashed.
Slash Redelegation
When a validator is slashed, so are all redelegations from the validator that began after the infraction. Redelegations are slashed byslashFactor.
Redelegations that began before the infraction are not slashed.
The amount slashed is calculated from the InitialBalance of the delegation and is capped to
prevent a resulting negative balance.
Mature redelegations (that have completed pseudo-unbonding) are not slashed.
How Shares are calculated
At any given point in time, each validator has a number of tokens,T, and has a number of shares issued, S.
Each delegator, i, holds a number of shares, S_i.
The number of tokens is the sum of all tokens delegated to the validator, plus the rewards, minus the slashes.
The delegator is entitled to a portion of the underlying tokens proportional to their proportion of shares.
So delegator i is entitled to T * S_i / S of the validator’s tokens.
When a delegator delegates new tokens to the validator, they receive a number of shares proportional to their contribution.
So when delegator j delegates T_j tokens, they receive S_j = S * T_j / T shares.
The total number of tokens is now T + T_j, and the total number of shares is S + S_j.
js proportion of the shares is the same as their proportion of the total tokens contributed: (S + S_j) / S = (T + T_j) / T.
A special case is the initial delegation, when T = 0 and S = 0, so T_j / T is undefined.
For the initial delegation, delegator j who delegates T_j tokens receive S_j = T_j shares.
So a validator that hasn’t received any rewards and has not been slashed will have T = S.
Messages
In this section we describe the processing of the staking messages and the corresponding updates to the state. All created/modified state objects specified by each message are defined within the state section.MsgCreateValidator
A validator is created using theMsgCreateValidator message.
The validator must be created with an initial delegation from the operator.
- another validator with this operator address is already registered
- another validator with this pubkey is already registered
- the initial self-delegation tokens are of a denom not specified as the bonding denom
- the commission parameters are faulty, namely:
MaxRateis either > 1 or < 0- the initial
Rateis either negative or >MaxRate - the initial
MaxChangeRateis either negative or >MaxRate
- the description fields are too large
Validator object at appropriate indexes.
Additionally a self-delegation is made with the initial tokens delegation
tokens Delegation. The validator always starts as unbonded but may be bonded
in the first end-block.
MsgEditValidator
TheDescription, CommissionRate of a validator can be updated using the
MsgEditValidator message.
- the initial
CommissionRateis either negative or >MaxRate - the
CommissionRatehas already been updated within the previous 24 hours - the
CommissionRateis >MaxChangeRate - the description fields are too large
Validator object.
MsgDelegate
Within this message the delegator provides coins, and in return receives some amount of their validator’s (newly created) delegator-shares that are assigned toDelegation.Shares.
- the validator does not exist
- the
AmountCoinhas a denomination different than one defined byparams.BondDenom - the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
- the amount delegated is less than the minimum allowed delegation
Delegation object for provided addresses does not already
exist then it is created as part of this message otherwise the existing
Delegation is updated to include the newly received shares.
The delegator receives newly minted shares at the current exchange rate.
The exchange rate is the number of existing shares in the validator divided by
the number of currently delegated tokens.
The validator is updated in the ValidatorByPower index, and the delegation is
tracked in validator object in the Validators index.
It is possible to delegate to a jailed validator, the only difference being it
will not be added to the power index until it is unjailed.
MsgUndelegate
TheMsgUndelegate message allows delegators to undelegate their tokens from
validator.
- the delegation doesn’t exist
- the validator doesn’t exist
- the delegation has less shares than the ones worth of
Amount - existing
UnbondingDelegationhas maximum entries as defined byparams.MaxEntries - the
Amounthas a denomination different than one defined byparams.BondDenom
- validator’s
DelegatorSharesand the delegation’sSharesare both reduced by the messageSharesAmount - calculate the token worth of the shares remove that amount tokens held within the validator
- with those removed tokens, if the validator is:
Bonded- add them to an entry inUnbondingDelegation(createUnbondingDelegationif it doesn’t exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares.Unbonding- add them to an entry inUnbondingDelegation(createUnbondingDelegationif it doesn’t exist) with the same completion time as the validator (UnbondingMinTime).Unbonded- then send the coins the messageDelegatorAddr
- if there are no more
Sharesin the delegation, then the delegation object is removed from the store- under this situation if the delegation is the validator’s self-delegation then also jail the validator.
MsgCancelUnbondingDelegation
TheMsgCancelUnbondingDelegation message allows delegators to cancel the unbondingDelegation entry and delegate back to a previous validator.
- the
unbondingDelegationentry is already processed. - the
cancel unbonding delegationamount is greater than theunbondingDelegationentry balance. - the
cancel unbonding delegationheight doesn’t exist in theunbondingDelegationQueueof the delegator.
- if the
unbondingDelegationEntry balance is zero- in this condition
unbondingDelegationentry will be removed fromunbondingDelegationQueue. - otherwise
unbondingDelegationQueuewill be updated with newunbondingDelegationentry balance and initial balance
- in this condition
- the validator’s
DelegatorSharesand the delegation’sSharesare both increased by the messageAmount.
MsgBeginRedelegate
The redelegation command allows delegators to instantly switch validators. Once the unbonding period has passed, the redelegation is automatically completed in the EndBlocker.- the delegation doesn’t exist
- the source or destination validators don’t exist
- the delegation has less shares than the ones worth of
Amount - the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive)
- existing
Redelegationhas maximum entries as defined byparams.MaxEntries - the
AmountCoinhas a denomination different than one defined byparams.BondDenom
- the source validator’s
DelegatorSharesand the delegationsSharesare both reduced by the messageSharesAmount - calculate the token worth of the shares remove that amount tokens held within the source validator.
- if the source validator is:
Bonded- add an entry to theRedelegation(createRedelegationif it doesn’t exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares (this may be effectively reversed in the next step however).Unbonding- add an entry to theRedelegation(createRedelegationif it doesn’t exist) with the same completion time as the validator (UnbondingMinTime).Unbonded- no action required in this step
- Delegate the token worth to the destination validator, possibly moving tokens back to the bonded state.
- if there are no more
Sharesin the source delegation, then the source delegation object is removed from the store- under this situation if the delegation is the validator’s self-delegation then also jail the validator.
MsgUpdateParams
TheMsgUpdateParams update the staking module parameters.
The params are updated through a governance proposal where the signer is the gov module account address.
- signer is not the authority defined in the staking keeper (usually the gov module account).
- the
bond_denomin the updated params has zero supply in the bank module (i.e., the denom does not exist on-chain).
Begin-Block
Each abci begin block call, the historical info will get stored and pruned according to theHistoricalEntries parameter.
Historical Info Tracking
If theHistoricalEntries parameter is 0, then the BeginBlock performs a no-op.
Otherwise, the latest historical info is stored under the key historicalInfoKey|height, while any entries older than height - HistoricalEntries is deleted.
In most cases, this results in a single entry being pruned per block.
However, if the parameter HistoricalEntries has changed to a lower value there will be multiple entries in the store that must be pruned.
End-Block
Each abci end block call, the operations to update queues and validator set changes are specified to execute.Validator Set Changes
The staking validator set is updated during this process by state transitions that run at the end of every block. As a part of this process any updated validators are also returned back to CometBFT for inclusion in the CometBFT validator set which is responsible for validating CometBFT messages at the consensus layer. Operations are as following:- the new validator set is taken as the top
params.MaxValidatorsnumber of validators retrieved from theValidatorsByPowerindex - the previous validator set is compared with the new validator set:
- missing validators begin unbonding and their
Tokensare transferred from theBondedPoolto theNotBondedPoolModuleAccount - new validators are instantly bonded and their
Tokensare transferred from theNotBondedPoolto theBondedPoolModuleAccount
- missing validators begin unbonding and their
LastTotalPower and LastValidatorsPower hold the state of the total power
and validator power from the end of the last block, and are used to check for
changes that have occurred in ValidatorsByPower and the total new power, which
is calculated during EndBlock.
Queues
Within staking, certain state-transitions are not instantaneous but take place over a duration of time (typically the unbonding period). When these transitions are mature certain operations must take place in order to complete the state operation. This is achieved through the use of queues which are checked/processed at the end of each block.Unbonding Validators
When a validator is kicked out of the bonded validator set (either through being jailed, or not having sufficient bonded tokens) it begins the unbonding process along with all its delegations begin unbonding (while still being delegated to this validator). At this point the validator is said to be an “unbonding validator”, whereby it will mature to become an “unbonded validator” after the unbonding period has passed. Each block the validator queue is to be checked for mature unbonding validators (namely with a completion time<= current time and completion height <= current
block height). At this point any mature validators which do not have any
delegations remaining are deleted from state. For all other mature unbonding
validators that still have remaining delegations, the validator.Status is
switched from types.Unbonding to
types.Unbonded.
Unbonding operations can be put on hold by external modules via the PutUnbondingOnHold(unbondingId) method.
As a result, an unbonding operation (e.g., an unbonding delegation) that is on hold, cannot complete
even if it reaches maturity. For an unbonding operation with unbondingId to eventually complete
(after it reaches maturity), every call to PutUnbondingOnHold(unbondingId) must be matched
by a call to UnbondingCanComplete(unbondingId).
Unbonding Delegations
Complete the unbonding of all matureUnbondingDelegations.Entries within the
UnbondingDelegations queue with the following procedure:
- transfer the balance coins to the delegator’s wallet address
- remove the mature entry from
UnbondingDelegation.Entries - remove the
UnbondingDelegationobject from the store if there are no remaining entries.
Redelegations
Complete the unbonding of all matureRedelegation.Entries within the
Redelegations queue with the following procedure:
- remove the mature entry from
Redelegation.Entries - remove the
Redelegationobject from the store if there are no remaining entries.
Hooks
Other modules may register operations to execute when a certain event has occurred within staking. These events can be registered to execute either rightBefore or After the staking event (as per the hook name). The
following hooks can registered with staking:
AfterValidatorCreated(Context, ValAddress) error- called when a validator is created
BeforeValidatorModified(Context, ValAddress) error- called when a validator’s state is changed
AfterValidatorRemoved(Context, ConsAddress, ValAddress) error- called when a validator is deleted
AfterValidatorBonded(Context, ConsAddress, ValAddress) error- called when a validator is bonded
AfterValidatorBeginUnbonding(Context, ConsAddress, ValAddress) error- called when a validator begins unbonding
BeforeDelegationCreated(Context, AccAddress, ValAddress) error- called when a delegation is created
BeforeDelegationSharesModified(Context, AccAddress, ValAddress) error- called when a delegation’s shares are modified
AfterDelegationModified(Context, AccAddress, ValAddress) error- called when a delegation is created or modified
BeforeDelegationRemoved(Context, AccAddress, ValAddress) error- called when a delegation is removed
AfterUnbondingInitiated(Context, UnbondingID)- called when an unbonding operation (validator unbonding, unbonding delegation, redelegation) was initiated
Events
The staking module emits the following events:EndBlocker
| Type | Attribute Key | Attribute Value |
|---|---|---|
| complete_unbonding | amount | {totalUnbondingAmount} |
| complete_unbonding | validator | {validatorAddress} |
| complete_unbonding | delegator | {delegatorAddress} |
| complete_redelegation | amount | {totalRedelegationAmount} |
| complete_redelegation | source_validator | {srcValidatorAddress} |
| complete_redelegation | destination_validator | {dstValidatorAddress} |
| complete_redelegation | delegator | {delegatorAddress} |
Msg’s
MsgCreateValidator
| Type | Attribute Key | Attribute Value |
|---|---|---|
| create_validator | validator | {validatorAddress} |
| create_validator | amount | {delegationAmount} |
| message | module | staking |
| message | action | create_validator |
| message | sender | {senderAddress} |
MsgEditValidator
| Type | Attribute Key | Attribute Value |
|---|---|---|
| edit_validator | commission_rate | {commissionRate} |
| edit_validator | min_self_delegation | {minSelfDelegation} |
| message | module | staking |
| message | action | edit_validator |
| message | sender | {senderAddress} |
MsgDelegate
| Type | Attribute Key | Attribute Value |
|---|---|---|
| delegate | validator | {validatorAddress} |
| delegate | amount | {delegationAmount} |
| message | module | staking |
| message | action | delegate |
| message | sender | {senderAddress} |
MsgUndelegate
| Type | Attribute Key | Attribute Value |
|---|---|---|
| unbond | validator | {validatorAddress} |
| unbond | amount | {unbondAmount} |
| unbond | completion_time [0] | {completionTime} |
| message | module | staking |
| message | action | begin_unbonding |
| message | sender | {senderAddress} |
- [0] Time is formatted in the RFC3339 standard
MsgCancelUnbondingDelegation
| Type | Attribute Key | Attribute Value |
|---|---|---|
| cancel_unbonding_delegation | validator | {validatorAddress} |
| cancel_unbonding_delegation | delegator | {delegatorAddress} |
| cancel_unbonding_delegation | amount | {cancelUnbondingDelegationAmount} |
| cancel_unbonding_delegation | creation_height | {unbondingCreationHeight} |
| message | module | staking |
| message | action | cancel_unbond |
| message | sender | {senderAddress} |
MsgBeginRedelegate
| Type | Attribute Key | Attribute Value |
|---|---|---|
| redelegate | source_validator | {srcValidatorAddress} |
| redelegate | destination_validator | {dstValidatorAddress} |
| redelegate | amount | {unbondAmount} |
| redelegate | completion_time [0] | {completionTime} |
| message | module | staking |
| message | action | begin_redelegate |
| message | sender | {senderAddress} |
- [0] Time is formatted in the RFC3339 standard
Parameters
The staking module contains the following parameters:| Key | Type | Example |
|---|---|---|
| UnbondingTime | string (time ns) | “259200000000000” |
| MaxValidators | uint16 | 100 |
| KeyMaxEntries | uint16 | 7 |
| HistoricalEntries | uint16 | 3 |
| BondDenom | string | ”stake” |
| MinCommissionRate | string | ”0.000000000000000000” |
Client
CLI
A user can query and interact with thestaking module using the CLI.
Query
Thequery commands allows users to query staking state.
delegation
Thedelegation command allows users to query delegations for an individual delegator on an individual validator.
Usage:
delegations
Thedelegations command allows users to query delegations for an individual delegator on all validators.
Usage:
delegations-to
Thedelegations-to command allows users to query delegations on an individual validator.
Usage:
historical-info
Thehistorical-info command allows users to query historical information at given height.
Usage:
params
Theparams command allows users to query values set as staking parameters.
Usage:
pool
Thepool command allows users to query values for amounts stored in the staking pool.
Usage:
redelegation
Theredelegation command allows users to query a redelegation record based on delegator and a source and destination validator address.
Usage:
redelegations
Theredelegations command allows users to query all redelegation records for an individual delegator.
Usage:
redelegations-from
Theredelegations-from command allows users to query delegations that are redelegating from a validator.
Usage:
unbonding-delegation
Theunbonding-delegation command allows users to query unbonding delegations for an individual delegator on an individual validator.
Usage:
unbonding-delegations
Theunbonding-delegations command allows users to query all unbonding-delegations records for one delegator.
Usage:
unbonding-delegations-from
Theunbonding-delegations-from command allows users to query delegations that are unbonding from a validator.
Usage:
validator
Thevalidator command allows users to query details about an individual validator.
Usage:
validators
Thevalidators command allows users to query details about all validators on a network.
Usage:
Transactions
Thetx commands allows users to interact with the staking module.
create-validator
The commandcreate-validator allows users to create new validator initialized with a self-delegation to it.
Usage:
validator.json contains:
simd tendermint show-validator command.
delegate
The commanddelegate allows users to delegate liquid tokens to a validator.
Usage:
edit-validator
The commandedit-validator allows users to edit an existing validator account.
Usage:
redelegate
The commandredelegate allows users to redelegate illiquid tokens from one validator to another.
Usage:
unbond
The commandunbond allows users to unbond shares from a validator.
Usage:
cancel unbond
The commandcancel-unbond allow users to cancel the unbonding delegation entry and delegate back to the original validator.
Usage:
gRPC
A user can query thestaking module using gRPC endpoints.
Validators
TheValidators endpoint queries all validators that match the given status.
Validator
TheValidator endpoint queries validator information for given validator address.
ValidatorDelegations
TheValidatorDelegations endpoint queries delegate information for given validator.
ValidatorUnbondingDelegations
TheValidatorUnbondingDelegations endpoint queries delegate information for given validator.
Delegation
TheDelegation endpoint queries delegate information for given validator delegator pair.
UnbondingDelegation
TheUnbondingDelegation endpoint queries unbonding information for given validator delegator.
DelegatorDelegations
TheDelegatorDelegations endpoint queries all delegations of a given delegator address.
DelegatorUnbondingDelegations
TheDelegatorUnbondingDelegations endpoint queries all unbonding delegations of a given delegator address.
Redelegations
TheRedelegations endpoint queries redelegations of given address.
DelegatorValidators
TheDelegatorValidators endpoint queries all validators information for given delegator.
DelegatorValidator
TheDelegatorValidator endpoint queries validator information for given delegator validator
HistoricalInfo
Pool
ThePool endpoint queries the pool information.
Params
TheParams endpoint queries the pool information.
REST
A user can query thestaking module using REST endpoints.
DelegatorDelegations
TheDelegtaorDelegations REST endpoint queries all delegations of a given delegator address.
Redelegations
TheRedelegations REST endpoint queries redelegations of given address.
DelegatorUnbondingDelegations
TheDelegatorUnbondingDelegations REST endpoint queries all unbonding delegations of a given delegator address.
DelegatorValidators
TheDelegatorValidators REST endpoint queries all validators information for given delegator address.
DelegatorValidator
TheDelegatorValidator REST endpoint queries validator information for given delegator validator pair.
HistoricalInfo
TheHistoricalInfo REST endpoint queries the historical information for given height.
Parameters
TheParameters REST endpoint queries the staking parameters.
Pool
ThePool REST endpoint queries the pool information.
Validators
TheValidators REST endpoint queries all validators that match the given status.
Validator
TheValidator REST endpoint queries validator information for given validator address.
ValidatorDelegations
TheValidatorDelegations REST endpoint queries delegate information for given validator.
Delegation
TheDelegation REST endpoint queries delegate information for given validator delegator pair.
UnbondingDelegation
TheUnbondingDelegation REST endpoint queries unbonding information for given validator delegator pair.
ValidatorUnbondingDelegations
TheValidatorUnbondingDelegations REST endpoint queries unbonding delegations of a validator.