CCV: Technical Specification

大纲

将 CCV 置于 ABCI 应用中
- 已实现的接口
- 与其他模块的交互
数据结构与方法

将 CCV 置于 ABCI 应用中

↑ 返回大纲在描述 CCV 协议的数据结构和子协议之前，我们先简要概述 CCV 模块所实现的接口，以及它与其他 ABCI 应用模块之间的交互。

已实现的接口

CCV 是一个 ABCI 应用模块，这意味着它必须实现处理一部分通过 ABCI 从共识引擎接收到的消息的逻辑，例如 InitChain、BeginBlock、EndBlock（更多细节可参见 ABCI specification）。在本规范中，我们定义了以下用于处理与 CCV 协议特别相关消息的方法：
- InitGenesis() — 当链首次启动并从共识引擎接收到 InitChain 消息时调用。应用也会在这里将初始验证者集合通知给底层共识引擎。
- BeginBlock() — 包含每个区块开始时自动触发的逻辑。
- EndBlock() — 包含每个区块结束时自动触发的逻辑。应用也会在这里将验证者集合的变更通知给底层共识引擎。
CCV 是一个 IBC 模块，这意味着它必须实现 ICS 26 中定义的模块回调接口。该接口由一组用于以下场景的回调组成：
- 通道打开握手，我们将在初始化章节中说明；
- 通道关闭握手，我们将在消费者链移除章节中说明；
- 以及数据包中继，我们将在数据包中继章节中说明。

与其他模块的交互

作为 ABCI 应用模块，CCV 模块通过 ABCI 与底层共识引擎交互：
- 在提供者链上，
  - 它在 InitGenesis() 方法中初始化应用（例如绑定到预期的 IBC 端口）。
- 在消费者链上，
  - 它在 InitGenesis() 方法中初始化应用（例如绑定到预期的 IBC 端口、创建提供者链的客户端）；
  - 它在 EndBlock() 方法中提供验证者更新。
作为 IBC 模块，CCV 模块通过 Core IBC 与以下功能交互：
- 通过 portKeeper 进行端口分配（ICS 5）；
- 通过 channelKeeper 处理通道和数据包语义（ICS 4）；
- 通过 connectionKeeper 处理连接语义（ICS 3）；
- 通过 clientKeeper 处理客户端语义（ICS 2）。
消费者侧 CCV 模块通过 transferKeeper 与 IBC Token Transfer 模块（ICS 20）交互。
对于初始化子协议，提供者侧 CCV 模块通过处理新增消费者链的治理提案与治理模块交互。如果此类提案通过，那么提供者链上的所有验证者在消费者链启动时都必须为其执行验证；否则它们会被罚没。关于治理提案如何工作的示例，可参见 Cosmos SDK 的 Governance module documentation。
消费者侧 pre-CCV 模块（即 preCCV == true 的 CCV 模块）会与消费者链上的 Staking 模块交互。请注意，一旦 preCCV 被设置为 false，Staking 模块就不得再向底层共识引擎提供验证者更新。关于质押如何工作的示例，可参见 Cosmos SDK 的 Staking module documentation。其交互由以下接口定义：
```
interface StakingKeeper {
  // replace the validator set with valset
  ReplaceValset(valset: [ValidatorUpdate])
}
```

提供者侧 CCV 模块会与提供者链上的 Staking 模块交互。关于质押如何工作的示例，可参见 Cosmos SDK 的 Staking module documentation。其交互由以下接口定义：

interface StakingKeeper {
  // get UnbondingPeriod from the provider Staking module 
  UnbondingTime(): Duration

  // get validator updates from the provider Staking module
  GetValidatorUpdates(): [ValidatorUpdate]

  // request the Staking module to put on hold 
  // the completion of an unbonding operation
  PutUnbondingOnHold(id: uint64)

  // notify the Staking module of an unboding operation that
  // has matured from the perspective of the consumer chains 
  UnbondingCanComplete(id: uint64)
}

提供者侧 CCV 模块会与提供者链上的 Slashing 模块交互。关于惩罚如何工作的示例，可参见 Cosmos SDK 的 Slashing module documentation。其交互由以下接口定义：

interface SlashingKeeper {
  // query the Slashing module for the slashing factor, 
  // which may be different for downtime infractions
  GetSlashFactor(downtime: Bool): int64

  // request the Slashing module to slash a validator
  Slash(valAddress: string, 
        infractionHeight: int64, 
        power: int64, 
        slashFactor: int64)

  // query the Slashing module for the jailing time, 
  // which may be different for downtime infractions
  GetJailTime(downtime: Bool): int64

  // request the Slashing module to jail a validator until time
  JailUntil(valAddress: string, time: uint64)
}

以下 hook 使提供者侧 CCV 模块能够注册操作，以便在提供者侧 Staking 模块内发生特定事件时执行：

// invoked by the Staking module after 
// initiating an unbonding operation
function AfterUnbondingInitiated(opId: uint64);

消费者侧 CCV 模块定义了以下 hook，使其他模块能够注册操作，以便在 CCV 内发生特定事件时执行：

// invoked after a new validator is added to the validator set
function AfterCCValidatorBonded(valAddress: string);

// invoked after a validator is removed from the validator set
function AfterCCValidatorBeginUnbonding(valAddress: string);

数据结构与方法

↑ 返回大纲本技术规范的其余部分分为数据结构和方法。

Outline

Placing CCV within an ABCI Application
- Implemented Interfaces
- Interfacing Other Modules
Data Structures and Methods

Placing CCV within an ABCI Application

↑ Back to Outline Before describing the data structures and sub-protocols of the CCV protocol, we provide a short overview of the interfaces the CCV module implements and the interactions with the other ABCI application modules.

Implemented Interfaces

CCV is an ABCI application module, which means it MUST implement the logic to handle some of the messages received from the consensus engine via ABCI, e.g., InitChain, BeginBlock, EndBlock (for more details, take a look at the ABCI specification). In this specification we define the following methods that handle messages that are of particular interest to the CCV protocol:
- InitGenesis() — Called when the chain is first started, on receiving an InitChain message from the consensus engine. This is also where the application can inform the underlying consensus engine of the initial validator set.
- BeginBlock() — Contains logic that is automatically triggered at the beginning of each block.
- EndBlock() — Contains logic that is automatically triggered at the end of each block. This is also where the application can inform the underlying consensus engine of changes in the validator set.
CCV is an IBC module, which means it MUST implement the module callbacks interface defined in ICS 26. The interface consists of a set of callbacks for
- channel opening handshake, which we describe in the Initialization section;
- channel closing handshake, which we describe in the Consumer Chain Removal section;
- and packet relay, which we describe in the Packet Relay section.

Interfacing Other Modules

As an ABCI application module, the CCV module interacts with the underlying consensus engine through ABCI:
- On the provider chain,
  - it initializes the application (e.g., binds to the expected IBC port) in the InitGenesis() method.
- On the consumer chain,
  - it initializes the application (e.g., binds to the expected IBC port, creates a client of the provider chain) in the InitGenesis() method;
  - it provides the validator updates in the EndBlock() method.
As an IBC module, the CCV module interacts with Core IBC for functionalities regarding
- port allocation (ICS 5) via portKeeper;
- channels and packet semantics (ICS 4) via channelKeeper;
- connection semantics (ICS 3) via connectionKeeper;
- client semantics (ICS 2) via clientKeeper.
The consumer CCV module interacts with the IBC Token Transfer module (ICS 20) via transferKeeper.
For the Initialization sub-protocol, the provider CCV module interacts with a Governance module by handling governance proposals to add new consumer chains. If such proposals pass, then all validators on the provider chain MUST validate the consumer chain at spawn time; otherwise they get slashed. For an example of how governance proposals work, take a look at the Governance module documentation of Cosmos SDK.
The consumer pre-CCV module (i.e., the CCV module with preCCV == true) interacts with a Staking module on the consumer chain. Note that once preCCV is set to false, the Staking module MUST no longer provide validator updates to the underlying consensus engine. For an example of how staking works, take a look at the Staking module documentation of Cosmos SDK. The interaction is defined by the following interface:
```
interface StakingKeeper {
  // replace the validator set with valset
  ReplaceValset(valset: [ValidatorUpdate])
}
```

The provider CCV module interacts with a Staking module on the provider chain. For an example of how staking works, take a look at the Staking module documentation of Cosmos SDK. The interaction is defined by the following interface:

interface StakingKeeper {
  // get UnbondingPeriod from the provider Staking module 
  UnbondingTime(): Duration

  // get validator updates from the provider Staking module
  GetValidatorUpdates(): [ValidatorUpdate]

  // request the Staking module to put on hold 
  // the completion of an unbonding operation
  PutUnbondingOnHold(id: uint64)

  // notify the Staking module of an unboding operation that
  // has matured from the perspective of the consumer chains 
  UnbondingCanComplete(id: uint64)
}

The provider CCV module interacts with a Slashing module on the provider chain. For an example of how slashing works, take a look at the Slashing module documentation of Cosmos SDK. The interaction is defined by the following interface:

interface SlashingKeeper {
  // query the Slashing module for the slashing factor, 
  // which may be different for downtime infractions
  GetSlashFactor(downtime: Bool): int64

  // request the Slashing module to slash a validator
  Slash(valAddress: string, 
        infractionHeight: int64, 
        power: int64, 
        slashFactor: int64)

  // query the Slashing module for the jailing time, 
  // which may be different for downtime infractions
  GetJailTime(downtime: Bool): int64

  // request the Slashing module to jail a validator until time
  JailUntil(valAddress: string, time: uint64)
}

The following hook enables the provider CCV module to register operations to be execute when certain events occur within the provider Staking module:
```
// invoked by the Staking module after 
// initiating an unbonding operation
function AfterUnbondingInitiated(opId: uint64);
```

The consumer CCV module defines the following hooks that enable other modules to register operations to execute when certain events have occurred within CCV:

// invoked after a new validator is added to the validator set
function AfterCCValidatorBonded(valAddress: string);

// invoked after a validator is removed from the validator set
function AfterCCValidatorBeginUnbonding(valAddress: string);

Data Structures and Methods

↑ Back to Outline The remainder of this technical specification is split into Data Structures and Methods.

​大纲

​将 CCV 置于 ABCI 应用中

​已实现的接口

​与其他模块的交互

​数据结构与方法

​Outline

​Placing CCV within an ABCI Application

​Implemented Interfaces

​Interfacing Other Modules

​Data Structures and Methods

大纲