​
大纲

​
外部数据结构

↑ 返回大纲 本节描述 CCV 模块使用的外部数据结构。 CCV 模块使用 ABCI ValidatorUpdate 数据结构，它由一个验证者及其权重组成（更多细节请参见 ABCI specification），即： 
interface ValidatorUpdate {
  pubKey: PublicKey
  power: int64
}
provider 链会向 consumer 链发送一个 ValidatorUpdate 列表，其中为每个权重发生更新的验证者都包含一项记录。 创建客户端所需的数据结构（即 ClientState、ConsensusState）定义于 ICS 2 中。 在 CCV 的上下文中，每条链都由其链 ID 和验证者集合唯一确定。 因此，CCV 要求 ClientState 包含链 ID，并要求某一高度对应的 ConsensusState 包含该高度的验证者集合。 此外，ClientState 还应包含 UnbondingPeriod。 示例可参考 ICS 7 中定义的 ClientState 和 ConsensusState。

​
CCV 数据结构

↑ 返回大纲 当链首次启动时，CCV 模块通过 InitGenesis 方法进行初始化。初始化基于创世状态完成。provider 链和 consumer 链都是如此：
  • 在 provider 链上，创世状态由以下接口描述： 
    interface ProviderGenesisState {
  // a list of existing consumer chains
  consumerStates: [ConsumerState]
}
    其中 ConsumerState 定义如下： 
    interface ConsumerState {
  chainId: string
  channelId: Identifier
}
  • 在 consumer 链上，创世状态由以下接口描述： 
    interface ConsumerGenesisState {
  preCCV: Bool
  unbondingPeriod: Duration
  connId: Identifier
  providerClientState: ClientState
  providerConsensusState: ConsensusState
  counterpartyClientId: Identifier
  initialValSet: [ValidatorUpdate]
  transferChannelId: Identifier
}
    • preCCV 是一个标志，用于指示 consumer CCV 模块是否以 pre-CCV 状态启动。 在 pre-CCV 状态下，consumer CCV 模块绝不能将验证者更新传递给底层共识引擎。 如果 preCCV == true，则必须设置 connId。
    • unbondingPeriod 是 consumer 链上的解绑期。
    • connId 是 consumer 链上用于建立 CCV 通道的连接端 ID。 如果 connId == ""，则会创建一个 provider 链的新客户端，并在该客户端之上创建一条新连接。
    • providerClientState 是用于创建 provider 链新客户端的客户端状态（定义见 ICS 2）。 如果 connId != ""，则忽略 providerClientState。
    • providerConsensusState 是用于创建 provider 链新客户端的共识状态（定义见 ICS 2）。 如果 connId != ""，则忽略 providerConsensusState。
    • counterpartyClientId 是 provider 链上 consumer 链客户端的 ID。 注意，counterpartyClientId 仅用于允许 consumer CCV 模块发起连接打开握手。 如果 connId != ""，则忽略 counterpartyClientId。
    • initialValSet 是将在该 consumer 链上开始执行验证的第一组验证者集合。
    • transferChannelId 是用于奖励分发子协议的代币转账通道 ID（定义见 ICS 20）。 如果 transferChannelId == ""，则会在与 CCV 通道相同的连接之上创建一条新的代币转账通道。
provider CCV 模块处理用于新增 consumer 链和移除现有 consumer 链的治理提案。 虽然治理提案的结构取决于各个具体的 ABCI 应用（示例可参见 Cosmos SDK 的 Governance module documentation 中的 Proposal 接口）， 本规范要求，用于新增 consumer 链的提案（即 ConsumerAdditionProposal）以及移除现有 consumer 链的提案（即 ConsumerRemovalProposal）应包含以下字段： 
interface ConsumerAdditionProposal {
  chainId: string
  spawnTime: Timestamp
  connId: Identifier
  unbondingPeriod: Duration
  transferChannelId: Identifier
  lockUnbondingOnTimeout: Bool
}
  • chainId 是拟新增 consumer 链的链 ID。它必须不同于执行该提案的 provider 链上所有其他 consumer 链的链 ID。
  • spawnTime 是 provider 链上的时间点，在该时间点 consumer 链的创世完成，且所有验证者都有责任启动其 consumer 链验证者节点。
  • connId 是 provider 链上用于建立 CCV 通道的连接端 ID。 如果 connId == ""，则会创建一个 consumer 链的新客户端，并在该客户端之上创建一条新连接。 注意，主权链可以通过提供有效的 connId，在保留其与其他链现有 IBC 通道的同时切换为 consumer 链。
  • unbondingPeriod 是 consumer 链上的解绑期。
  • transferChannelId 是用于奖励分发子协议的代币转账通道 ID（定义见 ICS 20）。 如果 transferChannelId == ""，则会在与 CCV 通道相同的连接之上创建一条新的代币转账通道。 注意，transferChannelId 是 consumer 链上的通道端 ID。
  • lockUnbondingOnTimeout 是一个布尔值，用于指示在发生超时时，是否释放与尚未完成的解绑操作对应的资金。 如果 lockUnbondingOnTimeout == true，则需要一个治理提案来停止已超时的 consumer 链，才能释放被锁定的资金。 
    interface ConsumerRemovalProposal {
  chainId: string
  stopTime: Timestamp
}
  • chainId 是要移除的 consumer 链的链 ID。它必须是执行该提案的 provider 链上某条现有 consumer 链的 ID。
  • stopTime 是 provider 链上的时间点，在该时间点所有验证者都有责任停止其 consumer 链验证者节点。
在 CCV 通道打开握手期间，provider 链会将其分发模块账户地址作为元数据加入通道版本中（如 ICS 4 所述）。 该元数据结构由以下接口描述： 
interface CCVHandshakeMetadata {
  providerDistributionAccount: string // the account's address
  version: string
}
本规范假定 provider CCV 模块可通过 GetDistributionAccountAddress() 方法访问分发模块账户的地址。示例可参考 Cosmos SDK 的 auth module。

​
CCV 数据包

↑ 返回大纲 通过 CCV 通道发送的数据包结构由 ICS 4 中的 Packet 接口定义。 CCV 模块需要以下几种数据包数据类型：
  • VSCPacketData 包含一个验证者更新列表，即： 
    interface VSCPacketData {
  // the id of this VSC
  id: uint64 
  // validator updates
  updates: [ValidatorUpdate]
  // downtime slash requests acknowledgements, 
  // i.e., list of validator addresses
  downtimeSlashAcks: [string]
}
  • VSCMaturedPacketData 包含已达到成熟状态的 VSC 的 ID，即： 
    interface VSCMaturedPacketData {
  id: uint64 // the id of the VSC that reached maturity
}
  • SlashPacketData 包含一个对验证者执行 slash 的请求，即： 
      interface SlashPacketData {
    valAddress: string // validator address, i.e., the hash of its public key
    valPower: int64
    vscId: uint64
    downtime: Bool
  }
注意，为了简洁起见，我们会使用例如 VSCPacket 来表示其数据为 VSCPacketData 的数据包。
数据包由远端通过回传一个 Acknowledgement 来确认，其中包含结果（成功时）或错误（定义见 ICS 4）。 CCV 模块需要以下几种确认类型： 
type VSCPacketAcknowledgement = VSCPacketSuccess | VSCPacketError;
type VSCMaturedPacketAcknowledgement = VSCMaturedPacketSuccess | VSCMaturedPacketError;
type SlashPacketAcknowledgement = SlashPacketSuccess | SlashPacketError;
type PacketAcknowledgement = PacketSuccess | PacketError; // general ack

​
CCV 状态

↑ 返回大纲 本节描述 CCV 模块的内部状态。为简化说明，状态以一组变量来描述；对每个变量，都提供其类型和简要说明。在实践中，所有状态（除硬编码常量外，例如 ProviderPortId）都存储在键值存储（KVS）中。宿主状态机提供带有三个函数的 KVS 接口，即 get()、set() 和 delete()（定义见 ICS 24）。
  • ccvVersion = "ccv-1" 是 CCV 的预期版本。provider 链和 consumer 链都需要就此版本达成一致。
  • zeroTimeoutHeight = {0,0} 是 CCV 用于发送数据包的 timeoutHeight（定义见 ICS 4）。注意，CCV 发送 CCV 数据包时使用 ccvTimeoutTimestamp，而转移代币时使用 transferTimeoutTimestamp。
  • ccvTimeoutTimestamp: uint64 是发送 CCV 数据包时的 timeoutTimestamp（定义见 ICS 4）。CCV 协议负责设置 ccvTimeoutTimestamp，以使 Correct Relayer 假设可行。
  • transferTimeoutTimestamp: uint64 是转移代币时的 timeoutTimestamp（定义见 ICS 4）。

​
Provider 链上的状态

↑ 返回大纲
  • ProviderPortId = "provider" 是 provider CCV 模块预期要绑定的端口 ID。
  • initTimeout: uint64 是通道初始化子协议可执行的最大持续时间， 也就是说，对于任意 consumer 链，如果自该 consumer 链注册起在 initTimeout 时间内未建立 CCV 通道，则移除该 consumer 链。
  • vscTimeout: uint64 是向任意 consumer 链发送任意 VSCPacket 与接收到对应 VSCMaturedPacket 之间允许的最大时间间隔；超过该时间间隔则该 consumer 链超时，并因此被移除。
  • pendingConsumerAdditionProposals: [ConsumerAdditionProposal] 是待处理的新增 consumer 链治理提案列表。
  • pendingConsumerRemovalProposals: [ConsumerRemovalProposal] 是待处理的移除现有 consumer 链治理提案列表。 这两个待处理治理提案列表都暴露如下接口：
  interface [Proposal] {
    // 将提案追加到列表中；列表会被修改
    Append(p: Proposal) 

    // 从列表中移除提案；列表会被修改
    Remove(p: Proposal)
  }
  • lockUnbondingOnTimeout: Map<string, Bool> 是从 consumer 链 ID 到布尔值的映射，用于指示在发生超时时，正在进行中的解绑操作对应的资金是否应被释放。
  • chainToClient: Map<string, Identifier> 是从 consumer 链 ID 到关联 client ID 的映射。
  • chainToConnection: Map<string, Identifier> 是从 consumer 链 ID 到关联 connection ID 的映射。
  • chainToChannel: Map<string, Identifier> 是从 consumer 链 ID 到 CCV 通道 ID 的映射。
  • channelToChain: Map<Identifier, string> 是从 CCV 通道 ID 到 consumer 链 ID 的映射。
  • initTimeoutTimestamps: Map<string, uint64> 是从 consumer 链 ID 到初始化超时时间戳的映射，参见 initTimeout。
  • pendingVSCPackets: Map<string, [VSCPacketData]> 是从 consumer 链 ID 到待处理 VSCPacketData 列表的映射；一旦 CCV 通道建立，必须将这些数据发送到对应 consumer 链。该映射暴露如下接口： 
    interface Map<string, [VSCPacketData]> {
  // 将 VSCPacketData 追加到映射到 chainId 的列表中；
  // 列表会被修改
  Append(chainId: string, data: VSCPacketData) 

  // 移除映射到 chainId 的所有 VSCPacketData；
  // 列表会被修改
  Remove(chainId: string)
}
  • vscId: uint64 是一个单调、严格递增且为正的 ID，用于唯一标识发送到 consumer 链的 VSC。 注意，0 被用作从 consumer 高度映射到 provider 高度时的特殊 ID。
  • vscSendTimestamps: Map<(string, uint64), uint64> 是从 (chainId, vscId) 元组到发送 VSCPacket 的时间戳的映射。
  • initialHeights: Map<string, Height> 是从 consumer 链 ID 到 provider 链上高度的映射。 对于每条 consumer 链，该映射存储的是到该 consumer 链的 CCV 通道建立时的高度。 注意，该高度上的 provider 验证者集合与向该 consumer 链提供第一个 VSC 时所在高度的验证者集合一致。 它使得从 consumer 高度到 provider 高度的映射成为可能。
  • VSCtoH: Map<uint64, Height> 是从 VSC ID 到 provider 链高度的映射。它使得从 consumer 高度到 provider 高度的映射成为可能， 即 provider 链在高度 VSCtoH[id] 处的投票权最后一次由 ID 为 id 的 VSC 中包含的验证者更新所更新。
  • unbondingOps: Map<uint64, UnbondingOperation> 是一个映射，用于对每个解绑操作访问仍处于解绑中的 consumer 链列表。当发起解绑操作时，Staking 模块会调用 AfterUnbondingInitiated() hook); 这会创建一个新的 UnbondingOperation，其定义如下 
    interface UnbondingOperation {
  id: uint64
  // 仍处于解绑中的 consumer 链 ID 列表
  unbondingChainIds: [string] 
}
  • vscToUnbondingOps: Map<(string, uint64), [uint64]> 是从 (chainId, vscId) 元组到解绑操作 ID 列表的映射。 它使 provider CCV 模块能够将从 chainId 对应 consumer 链接收到的 VSCMaturedPacket{vscId} 与相应的解绑操作匹配起来。 因此，可以将 chainId 从这些操作中仍处于解绑中的 consumer 链列表里移除。 更多细节参见接收到的 VSCMaturedPacket 如何处理。
  • maturedUnbondingOps: [uint64] 是已成熟解绑操作 ID 的列表（从 consumer 链的视角），可据此向 Staking 模块发送通知（见 stakingKeeper.UnbondingCanComplete）。 注意，maturedUnbondingOps 会在每个区块结束时清空。
  • downtimeSlashRequests: Map<string, [string]> 是从 chainId 到验证者地址列表的映射， 即 downtimeSlashRequests[chainId] 包含 provider 链从 chainId 对应 consumer 链收到的所有因宕机而发起惩罚请求的验证者地址。

​
Consumer 链上的状态

↑ 返回大纲
  • ConsumerPortId = "consumer" 是 consumer CCV 模块预期要绑定的端口 ID。
  • ConsumerUnbondingPeriod: Duration 是 consumer 链上的解绑周期。
  • preCCV: Bool 是一个标志，用于指示 consumer CCV 模块是否以 pre-CCV 状态启动。 在 pre-CCV 状态下，consumer CCV 模块不得将验证者更新传递给底层共识引擎。
  • providerClientId: Identifier 标识 CCV 通道所依赖的 provider 链 client（位于 consumer 链上）。
  • providerChannel: Identifier 标识 CCV 通道在 consumer 侧的通道端。
  • ccvValidatorSet: <string, ValidatorUpdate> 是一个映射，用于存储 consumer 链验证者集合中的验证者。
  • receivedVSCs: [VSCPacketData] 是已收到但尚未应用的 VSCPacket 中数据项（即 VSCPacketData）列表。
  • HtoVSC: Map<Height, uint64> 是从 consumer 链高度到 VSC ID 的映射。它使得从 consumer 高度到 provider 高度的映射成为可能。也就是说，
    • 如果 HtoVSC[h] == 0，则 consumer 链在高度 h 处的投票权是在通道初始化期间于创世时设置的；
    • 否则，consumer 链在高度 h 处的投票权由 ID 为 HtoVSC[h] 的 VSC 更新。
  • maturingVSCs: [(uint64, uint64)] 是 (id, ts) 元组列表，其中 id 是通过 VSCPacket 接收到的 VSC 的 ID，ts 是该 VSC 在 consumer 链上成熟时的时间戳。 该列表用于跟踪解绑操作何时在 consumer 链上成熟。它暴露如下接口： 
    interface [(uint64, uint64)] {
  // 将 VSC ID 及其成熟时间戳添加到列表中；
  // 列表会被修改
  Add(id: uint64, ts: uint64)

  // 返回按成熟时间戳排序后的列表；
  // 原始列表不会被修改
  SortedByMaturityTime(): [(uint64, uint64)]

  // 从列表中移除 (id, ts)；
  // 列表会被修改
  Remove(id: uint64, ts: uint64)
}
  • pendingSlashRequests: [SlashRequest] 是待处理的 SlashRequest 列表；一旦 CCV 通道建立，必须将其发送到 provider 链。一个 SlashRequest 由一个 SlashPacketData 和一个用于指示该请求是否针对宕机惩罚的标志组成。该列表暴露如下接口： 
    interface SlashRequest {
  data: SlashPacketData
  downtime: Bool
}
interface [SlashRequest] {
  // 将 SlashRequest 追加到列表中；
  // 列表会被修改
  Append(data: SlashRequest) 

  // 返回逆序列表，即最新的 SlashRequest 在最前；
  // 原始列表不会被修改
  Reverse(): [SlashRequest]

  // 移除所有 SlashRequest；
  // 列表会被修改
  RemoveAll()
}
  • outstandingDowntime: <string, Bool> 是从验证者地址到布尔值的映射。 outstandingDowntime[valAddr] == TRUE 表示 consumer 链已经发送了对地址为 valAddr 的验证者因宕机进行惩罚的请求。 当 consumer 链收到 provider 链已接收该宕机惩罚请求的确认后，outstandingDowntime[valAddr] 会被设为 false，即收到一个在 downtimeSlashAcks 中包含 valAddr 的 VSCPacket。 该映射使 consumer CCV 模块能够避免就同一次宕机违规向 provider 链发送多个惩罚请求。
  • providerDistributionAccount: string 是 provider 链上分发模块账户的地址。它使 consumer 链能够将奖励转移到 provider 链。
  • distributionChannelId: Identifier 是用于向 provider 链发送奖励的分发代币转移通道 ID。
  • BlocksPerDistributionTransfer: int64 是两次分发代币转移之间的间隔（以区块数计）。
  • lastDistributionTransferHeight: Height 是上一次分发代币转移的区块高度。
  • ccvAccount: string 是 CCV 模块账户地址，consumer 链奖励的一部分会先汇集到这里，然后再转移到 provider 链。

​
Outline

​
External Data Structures

↑ Back to Outline This section describes external data structures used by the CCV module. The CCV module uses the ABCI ValidatorUpdate data structure, which consists of a validator and its power (for more details, take a look at the ABCI specification), i.e., 
interface ValidatorUpdate {
  pubKey: PublicKey
  power: int64
}
The provider chain sends to the consumer chain a list of ValidatorUpdates, containing an entry for every validator that had its power updated. The data structures required for creating clients (i.e., ClientState, ConsensusState) are defined in ICS 2. In the context of CCV, every chain is uniquely defined by their chain ID and the validator set. Thus, CCV requires the ClientState to contain the chain ID and the ConsensusState for a particular height to contain the validator set at that height. In addition, the ClientState should contain the UnbondingPeriod. For an example, take a look at the ClientState and ConsensusState defined in ICS 7.

​
CCV Data Structures

↑ Back to Outline The CCV module is initialized through the InitGenesis method when the chain is first started. The initialization is done from a genesis state. This is the case for both provider and consumer chains:
  • On the provider chain, the genesis state is described by the following interface: 
    interface ProviderGenesisState {
  // a list of existing consumer chains
  consumerStates: [ConsumerState]
}
    with ConsumerState defined as 
    interface ConsumerState {
  chainId: string
  channelId: Identifier
}
  • On the consumer chain, the genesis state is described by the following interface: 
    interface ConsumerGenesisState {
  preCCV: Bool
  unbondingPeriod: Duration
  connId: Identifier
  providerClientState: ClientState
  providerConsensusState: ConsensusState
  counterpartyClientId: Identifier
  initialValSet: [ValidatorUpdate]
  transferChannelId: Identifier
}
    • preCCV is a flag indicating whether the consumer CCV module starts in pre-CCV state. In pre-CCV state the consumer CCV module MUST NOT pass validator updates to the underlying consensus engine. If preCCV == true, then connId must be set.
    • unbondingPeriod is the unbonding period on the consumer chain.
    • connId is the ID of the connection end on the consumer chain on top of which the CCV channel will be established. If connId == "", a new client of the provider chain and a new connection on top of this client are created.
    • providerClientState is the client state used to create a new client of the provider chain (as defined in ICS 2). If connId != "", then providerClientState is ignored.
    • providerConsensusState is the consensus state used to create a new client of the provider chain (as defined in ICS 2). If connId != "", then providerConsensusState is ignored.
    • counterpartyClientId is the ID of the client of the consumer chain on the provider chain. Note that counterpartyClientId is only needed to allow the consumer CCV module to initiate the connection opening handshake. If connId != "", then counterpartyClientId is ignored.
    • initialValSet is the first validator set that will start validating on this consumer chain.
    • transferChannelId is the ID of a token transfer channel (as defined in ICS 20) used for the Reward Distribution sub-protocol. If transferChannelId == "", a new token transfer channel is created on top of the same connection as the CCV channel.
The provider CCV module handles governance proposals to add new consumer chains and to remove existing consumer chains. While the structure of governance proposals is specific to every ABCI application (for an example, see the Proposal interface in the Governance module documentation of Cosmos SDK), this specification expects the following fields to be part of the proposals to add new consumer chains (i.e., ConsumerAdditionProposal) and to remove existing ones (i.e., ConsumerRemovalProposal): 
interface ConsumerAdditionProposal {
  chainId: string
  spawnTime: Timestamp
  connId: Identifier
  unbondingPeriod: Duration
  transferChannelId: Identifier
  lockUnbondingOnTimeout: Bool
}
  • chainId is the proposed chain ID of the new consumer chain. It must be different from all other consumer chain IDs of the executing provider chain.
  • spawnTime is the time on the provider chain at which the consumer chain genesis is finalized and all validators are responsible to start their consumer chain validator node.
  • connId is the ID of the connection end on the provider chain on top of which the CCV channel will be established. If connId == "", a new client of the consumer chain and a new connection on top of this client are created. Note that a sovereign chain can transition to a consumer chain while maintaining existing IBC channels to other chains by providing a valid connId.
  • unbondingPeriod is the unbonding period on the consumer chain.
  • transferChannelId is the ID of a token transfer channel (as defined in ICS 20) used for the Reward Distribution sub-protocol. If transferChannelId == "", a new token transfer channel is created on top of the same connection as the CCV channel. Note that transferChannelId is the ID of the channel end on the consumer chain.
  • lockUnbondingOnTimeout is a boolean value that indicates whether the funds corresponding to the outstanding unbonding operations are to be released in case of a timeout. If lockUnbondingOnTimeout == true, a governance proposal to stop the timed out consumer chain would be necessary to release the locked funds. 
    interface ConsumerRemovalProposal {
  chainId: string
  stopTime: Timestamp
}
  • chainId is the chain ID of the consumer chain to be removed. It must be the ID of an existing consumer chain of the executing provider chain.
  • stopTime is the time on the provider chain at which all validators are responsible to stop their consumer chain validator node.
During the CCV channel opening handshake, the provider chain adds the address of its distribution module account to the channel version as metadata (as described in ICS 4). The metadata structure is described by the following interface: 
interface CCVHandshakeMetadata {
  providerDistributionAccount: string // the account's address
  version: string
}
This specification assumes that the provider CCV module has access to the address of the distribution module account through the GetDistributionAccountAddress() method. For an example, take a look at the auth module of Cosmos SDK.

​
CCV Packets

↑ Back to Outline The structure of the packets sent through the CCV channel is defined by the Packet interface in ICS 4. The following packet data types are required by the CCV module:
  • VSCPacketData contains a list of validator updates, i.e., 
    interface VSCPacketData {
  // the id of this VSC
  id: uint64 
  // validator updates
  updates: [ValidatorUpdate]
  // downtime slash requests acknowledgements, 
  // i.e., list of validator addresses
  downtimeSlashAcks: [string]
}
  • VSCMaturedPacketData contains the ID of the VSC that reached maturity, i.e., 
    interface VSCMaturedPacketData {
  id: uint64 // the id of the VSC that reached maturity
}
  • SlashPacketData contains a request to slash a validator, i.e., 
      interface SlashPacketData {
    valAddress: string // validator address, i.e., the hash of its public key
    valPower: int64
    vscId: uint64
    downtime: Bool
  }
Note that for brevity we use e.g., VSCPacket to refer to a packet with VSCPacketData as its data.
Packets are acknowledged by the remote side by sending back an Acknowledgement that contains either a result (in case of success) or an error (as defined in ICS 4). The following acknowledgement types are required by the CCV module: 
type VSCPacketAcknowledgement = VSCPacketSuccess | VSCPacketError;
type VSCMaturedPacketAcknowledgement = VSCMaturedPacketSuccess | VSCMaturedPacketError;
type SlashPacketAcknowledgement = SlashPacketSuccess | SlashPacketError;
type PacketAcknowledgement = PacketSuccess | PacketError; // general ack

​
CCV State

↑ Back to Outline This section describes the internal state of the CCV module. For simplicity, the state is described by a set of variables; for each variable, both the type and a brief description is provided. In practice, all the state (except for hardcoded constants, e.g., ProviderPortId) is stored in a key/value store (KVS). The host state machine provides a KVS interface with three functions, i.e., get(), set(), and delete() (as defined in ICS 24).
  • ccvVersion = "ccv-1" is the CCV expected version. Both the provider and the consumer chains need to agree on this version.
  • zeroTimeoutHeight = {0,0} is the timeoutHeight (as defined in ICS 4) used by CCV for sending packets. Note that CCV uses ccvTimeoutTimestamp for sending CCV packets and transferTimeoutTimestamp for transferring tokens.
  • ccvTimeoutTimestamp: uint64 is the timeoutTimestamp (as defined in ICS 4) for sending CCV packets. The CCV protocol is responsible of setting ccvTimeoutTimestamp such that the Correct Relayer assumption is feasible.
  • transferTimeoutTimestamp: uint64 is the timeoutTimestamp (as defined in ICS 4) for transferring tokens.

​
State on Provider Chain

↑ Back to Outline
  • ProviderPortId = "provider" is the port ID the provider CCV module is expected to bind to.
  • initTimeout: uint64 is the maximum time duration the Channel Initialization subprotocol may execute, i.e., for any consumer chain, if the CCV channel is not established within initTimeout since the consumer chain was registered, then the consumer chain is removed.
  • vscTimeout: uint64 is the maximum time duration between sending any VSCPacket to any consumer chain and receiving the corresponding VSCMaturedPacket, without timing out the consumer chain and consequently removing it.
  • pendingConsumerAdditionProposals: [ConsumerAdditionProposal] is a list of pending governance proposals to add new consumer chains.
  • pendingConsumerRemovalProposals: [ConsumerRemovalProposal] is a list of pending governance proposals to remove existing consumer chains. Both lists of pending governance proposals expose the following interface:
  interface [Proposal] {
    // append a proposal to the list; the list is modified
    Append(p: Proposal) 

    // remove a proposal from the list; the list is modified
    Remove(p: Proposal)
  }
  • lockUnbondingOnTimeout: Map<string, Bool> is a mapping from consumer chain IDs to the boolean values indicating whether the funds corresponding to the in progress unbonding operations are to be released in case of a timeout.
  • chainToClient: Map<string, Identifier> is a mapping from consumer chain IDs to the associated client IDs.
  • chainToConnection: Map<string, Identifier> is a mapping from consumer chain IDs to the associated connection IDs.
  • chainToChannel: Map<string, Identifier> is a mapping from consumer chain IDs to the CCV channel IDs.
  • channelToChain: Map<Identifier, string> is a mapping from CCV channel IDs to consumer chain IDs.
  • initTimeoutTimestamps: Map<string, uint64> is a mapping from consumer chain IDs to init timeout timestamps, see initTimeout.
  • pendingVSCPackets: Map<string, [VSCPacketData]> is a mapping from consumer chain IDs to a list of pending VSCPacketDatas that must be sent to the consumer chain once the CCV channel is established. The map exposes the following interface: 
    interface Map<string, [VSCPacketData]> {
  // append a VSCPacketData to the list mapped to chainId;
  // the list is modified
  Append(chainId: string, data: VSCPacketData) 

  // remove all the VSCPacketData mapped to chainId;
  // the list is modified
  Remove(chainId: string)
}
  • vscId: uint64 is a monotonic strictly increasing and positive ID that is used to uniquely identify the VSCs sent to the consumer chains. Note that 0 is used as a special ID for the mapping from consumer heights to provider heights.
  • vscSendTimestamps: Map<(string, uint64), uint64> is a mapping from (chainId, vscId) tuples to the timestamps of sending VSCPackets.
  • initialHeights: Map<string, Height> is a mapping from consumer chain IDs to the heights on the provider chain. For every consumer chain, the mapping stores the height when the CCV channel to that consumer chain is established. Note that the provider validator set at this height matches the validator set at the height when the first VSC is provided to that consumer chain. It enables the mapping from consumer heights to provider heights.
  • VSCtoH: Map<uint64, Height> is a mapping from VSC IDs to heights on the provider chain. It enables the mapping from consumer heights to provider heights, i.e., the voting power at height VSCtoH[id] on the provider chain was last updated by the validator updates contained in the VSC with ID id.
  • unbondingOps: Map<uint64, UnbondingOperation> is a mapping that enables accessing for every unbonding operation the list of consumer chains that are still unbonding. When unbonding operations are initiated, the Staking module calls the AfterUnbondingInitiated() hook); this leads to the creation of a new UnbondingOperation, which is defined as 
    interface UnbondingOperation {
  id: uint64
  // list of consumer chain IDs that are still unbonding
  unbondingChainIds: [string] 
}
  • vscToUnbondingOps: Map<(string, uint64), [uint64]> is a mapping from (chainId, vscId) tuples to a list of unbonding operation IDs. It enables the provider CCV module to match a VSCMaturedPacket{vscId}, received from a consumer chain with chainId, with the corresponding unbonding operations. As a result, chainId can be removed from the list of consumer chains that are still unbonding these operations. For more details see how received VSCMaturedPackets are handled.
  • maturedUnbondingOps: [uint64] is a list of IDs of matured unbonding operations (from the perspective of the consumer chains), for which notifications can be sent to the Staking module (see stakingKeeper.UnbondingCanComplete). Note that maturedUnbondingOps is emptied at the end of each block.
  • downtimeSlashRequests: Map<string, [string]> is a mapping from chainIds to lists of validator addresses, i.e., downtimeSlashRequests[chainId] contains all the validator addresses for which the provider chain received slash requests for downtime from the consumer chain with chainId.

​
State on Consumer Chain

↑ Back to Outline
  • ConsumerPortId = "consumer" is the port ID the consumer CCV module is expected to bind to.
  • ConsumerUnbondingPeriod: Duration is the unbonding period on the consumer chain.
  • preCCV: Bool is a flag indicating whether the consumer CCV module starts in pre-CCV state. In pre-CCV state, the consumer CCV module MUST NOT pass validator updates to the underlying consensus engine.
  • providerClientId: Identifier identifies the client of the provider chain (on the consumer chain) that the CCV channel is build upon.
  • providerChannel: Identifier identifies the consumer’s channel end of the CCV channel.
  • ccvValidatorSet: <string, ValidatorUpdate> is a mapping that stores the validators in the validator set of the consumer chain.
  • receivedVSCs: [VSCPacketData] is a list of data items (i.e., VSCPacketData) received in VSCPackets that are not yet applied.
  • HtoVSC: Map<Height, uint64> is a mapping from consumer chain heights to VSC IDs. It enables the mapping from consumer heights to provider heights., i.e.,
    • if HtoVSC[h] == 0, then the voting power on the consumer chain at height h was setup at genesis during Channel Initialization;
    • otherwise, the voting power on the consumer chain at height h was updated by the VSC with ID HtoVSC[h].
  • maturingVSCs: [(uint64, uint64)] is a list of (id, ts) tuples, where id is the ID of a VSC received via a VSCPacket and ts is the timestamp at which the VSC reaches maturity on the consumer chain. The list is used to keep track of when unbonding operations are matured on the consumer chain. It exposes the following interface: 
    interface [(uint64, uint64)] {
  // add a VSC id with its maturity timestamp to the list;
  // the list is modified
  Add(id: uint64, ts: uint64)

  // return the list sorted by the maturity timestamps;
  // the original list is not modified
  SortedByMaturityTime(): [(uint64, uint64)]

  // remove (id, ts) from the list;
  // the list is modified
  Remove(id: uint64, ts: uint64)
}
  • pendingSlashRequests: [SlashRequest] is a list of pending SlashRequests that must be sent to the provider chain once the CCV channel is established. A SlashRequest consist of a SlashPacketData and a flag indicating whether the request is for downtime slashing. The list exposes the following interface: 
    interface SlashRequest {
  data: SlashPacketData
  downtime: Bool
}
interface [SlashRequest] {
  // append a SlashRequest to the list;
  // the list is modified
  Append(data: SlashRequest) 

  // return the reverse list, i.e., latest SlashRequest first;
  // the original list is not modified
  Reverse(): [SlashRequest]

  // remove all the SlashRequest;
  // the list is modified
  RemoveAll()
}
  • outstandingDowntime: <string, Bool> is a mapping from validator addresses to boolean values. outstandingDowntime[valAddr] == TRUE entails that the consumer chain sent a request to slash for downtime the validator with address valAddr. outstandingDowntime[valAddr] is set to false once the consumer chain receives a confirmation that the downtime slash request was received by the provider chain, i.e., a VSCPacket that contains valAddr in downtimeSlashAcks. The mapping enables the consumer CCV module to avoid sending to the provider chain multiple slashing requests for the same downtime infraction.
  • providerDistributionAccount: string is the address of the distribution module account on the provider chain. It enables the consumer chain to transfer rewards to the provider chain.
  • distributionChannelId: Identifier is the ID of the distribution token transfer channel used for sending rewards to the provider chain.
  • BlocksPerDistributionTransfer: int64 is the interval (in number of blocks) between two distribution token transfers.
  • lastDistributionTransferHeight: Height is the block height of the last distribution token transfer.
  • ccvAccount: string is the address of the CCV module account where a fraction of the consumer chain rewards are collected before being transferred to the provider chain.