0.24.0

Translate

协议升级

CITA 版本升级作为协议升级的一部分，在协议不变的情况下可单独升级 CITA 版本。 详细可参考 协议升级的公共流程 的第 3 步骤。

升级 CITA 版本过程中建议停止发送交易，避免出现不可预料甚至无法恢复的异常

由于区块链去中心化的特性，不同节点运行的软件版本会有新旧差异，甚至可能是不同的代码实现(比如以太坊的 Geth 和 Parity)。因此区块链系统版本代表的不是某一特定实现，而是一个特定的协议。 系统通过协议升级来完善功能, 修复已有问题, 为用户提供去中心化服务.

CITA 升级说明

对于公链来说，因为只有一条链，通常使用指定的区块高度作为分叉开关，链达到这个指定高度即触发协议升级。但 CITA 作为高性能的区块链内核，服务于多条链，区块高度并不唯一，无法采用区块高度作为分叉开关。

CITA 同样采用类似公链分叉的方式进行协议升级, 只不过我们的升级方案是通过增加一个专门的 version_manager 合约，存放一个单调递增的协议版本号, 超级管理员通过发送交易变更版本号来触发协议升级。 节点数较少的情况下，相对可控，要求所有节点先统一实施 软件升级，然后再实施 协议升级。

协议升级公共流程

  1. CITA 开发团队完成新版本协议的开发工作，发布支持新版本协议的 CITA 版本，并附带相关的文档。
  2. 已有链的运营方讨论之后决定升级到新版本协议。
  3. 所有的节点都升级至支持新版本协议的 CITA 版本。升级 CITA 版本，只需要停掉节点，替换发布件中的二进制执行文件（节点文件夹不动）实施 软件升级，然后再启动节点即可。如果有额外的操作，会在 release notes 中说明。升级 CITA 版本之后，使用的依然是老的协议。因此可以预留一个比较长的时间，让各个节点错开时间分别升级 CITA 版本，可以避免中断业务。
  4. 待所有节点升级 CITA 版本完成后，链的超级管理员根据升级文档操作指南发送交易，实施 协议升级。
  5. 普通用户需要将使用的工具以及 SDK 升级至支持新版本协议的版本, 这些内容也会在相关文档中详细描述。

注意

  1. 超级管理员实施协议升级过程中，最好暂停一下业务。老的交易如果在协议升级生效之前进入交易池，协议升级生效之后才打包上链，将会在打包交易阶段报错，此时错误已经无法反馈给用户，会给用户制造一些困扰。可以参考紧急制动。
  2. 如果节点没有及时升级 CITA 版本，超级管理员实施协议升级之后，节点将停止工作，并可能会出现各种异常情况。
  3. 如果链实施完协议升级，但是普通用户没有及时升级工具和 SDK 版本。发送交易将会得到 InvalidVersion 错误。
  4. 使用支持新版本协议的 CITA 版本重新创建一条链，除非在生成链配置的时候指定协议版本号，否则默认使用该 CITA 支持的最新版本协议。

完整协议升级示例

  1. 假设现在有一条正在运营的四节点 CITA v0.19 的链，当前使用的协议版本为 v0, 每个节点对应一名运维人员, 共 4 名运维人员，还有一个超级管理员。
  2. CITA v0.20 正式发布后, v0.20 支持 v0/v1 两个版本的协议。
  3. 链的超级管理员通知 4 个节点的运维人员，可以开始升级 CITA v0.20 了，限期 10 天。
  4. 4 个运维人员在这 10 天里的任何时间对自己维护的节点实施 软件升级 CITA v0.20 的操作。所以这段时间 4 个共识节点会存在 v0.19 和 v0.20 混用的情况。这种情况没有任何问题，过程中业务也不会中断, 此时使用的依然是 v0 协议。
  5. 10 天的期限结束。4 个节点都升级到 CITA v0.20 了。
  6. 超级管理员开启紧急制动功能, 链的业务暂停，只有超级管理员可以发交易上链。
  7. 超级管理员发交易，升级系统合约。我们提供了脚本 scripts/amend_sys_cont_to_v0-20.sh 辅助完成这项工作。
  8. 超级管理员发送交易，将 VersionManager 系统合约中的 version 从 0 改为 1 ，完成 协议升级。
  9. 超级管理员关闭紧急制动功能，链的业务恢复。
  10. 至此，只有使用 v1 协议的交易才能发送上链，依然使用 v0 协议的交易，发送时将会返回错误。

协议说明

CITA 的每个协议版本都有专门的文档指南，说明支持该协议版本的最小 Release 版本号，该版本协议相对上一个版本的变化，以及实施协议升级的详细操作.

v0 协议说明

CITA 从 v0.19 开始提供兼容性保证。除了一些特殊的情况，之前的 CITA 版本之间都不保证兼容性。

v0.19 之前的版本链升级 CITA 最新版本需要重新创建链，无法兼容链上的历史数据。v0 协议即 CITA v0.19 时实际使用的协议。

对应 RELEASE 版本

v0.19 及以上版本

协议变更

参考 v0.19

注意

交易中的 version 字段必须填 0(默认也是 0)。v0.19 并没有校验 version，填非 0 值也可以正常工作。 v0.20 增加了对 version 的校验。因此，如果用户之前发送过 version 不为 0 的交易，升级 v0.20 版本之后，查询这些交易或者新节点同步过程中可能会出现异常情况。可以通过快照方式解决，不影响协议升级操作。

v1 协议说明

在 v1 之前的协议存在两个问题:

  1. v0 协议 Transaction 结构中目标地址 to 字段类型为 String，即十六进制字符。但是链上存储时是按照 bytes 类型存储的。 因为字符大小写的问题，导致交易具有可变性，无法准确恢复出发送交易的地址。因此，在 v1 协议中，将目标地址的类型由 String 改为 bytes。

  2. v0 协议 Transaction 结构中 chain_id 字段类型为 u32。每条链有唯一的 chain_id，但 u32 取值空间太小， 必须有中心化机构协调才能保证不会出现两条链的 chain_id 重复的情况。因此，在 v1 协议中，将chain_id的类型由 u32 改为 bytes(u256)。 这样链的运营方可以选择使用 uuid 或者随机的哈希值作为 chain_id，不需要中心化机构协调，也可以在很大概率上保证 chain_id 的唯一。

对应 RELEASE 版本

v0.20 及以上版本

协议变更

  • Transaction 结构中增加 to_v1 字段，类型 bytes。在链的协议版本为 v1 时，原来 to 字段不再使用。

  • Transaction 结构中增加 chain_id_v1 字段，类型 bytes(u256)。在链的协议版本为 v1 时，原来 chain_id 字段不再使用。

  • Transaction 结构中的 version 字段必须填 1。

实施协议升级

  1. 安排所有节点升级 CITA 版本至 v0.20 及以上版本。
  2. 升级系统合约。 参数是 Admin, private key, chain id, version, url.

注意：这里的参数仅作为演示使用，请实际操作时替换为目标链的相应参数

$ ./env.sh scripts/amend_sys_cont_to_v0-20.sh 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6 1 0 http://127.0.0.1:1337
  1. 使用超级管理员账户，执行如下 协议升级命令

注意：这里的admin-private私钥仅作为演示使用，请实际操作时替换为目标链的实际私钥。

$ cita-cli scm VersionManager setVersion --admin-private 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6 --version 1
  1. 用户升级相关工具和 SDK 至明确支持 v1 协议的版本，具体请参见 SDK 和 工具的 RELEASE NOTES。

注意

  1. 原来的 to 字段和 chain_id 字段一定不能填，否则会有交易可变性问题, 协议升级之后有相关的检查，发现 to 字段和 chain_id 字段不为空就报错。
  2. 因为跨链功能目前还没有正式使用，因此升级后相关工具将不再支持 v0 协议，只支持 v1 协议。

v2 协议说明

v2 之前的版本存在两个问题:

  1. 使用自动执行功能时, coinbase 是地址默认值, 并非共识节点地址.
  2. Charge 模型下, 对合约执行 self-destruct 操作, 合约账户余额无法返还给 refund account.

所以我们在协议版本 v2 修复了以上两个问题.

  1. 自动执行功能中的 coinbase 是该块对应的出块节点地址,
  2. 对合约执行 self-destruct 操作后, 合约账户有余额返还指定的 refund account.

对应 RELEASE 版本

v.24.0 及其以上版本

实施协议升级

  1. 安排所有节点升级 CITA 版本至 v0.24.0 及以上版本。
  2. 使用超级管理员账户，执行如下协议升级命令

注意：这里的 admin-private 私钥仅作为演示使用，请实际操作时替换为目标链的实际私钥。

$ cita-cli scm VersionManager setVersion --admin-private 0x5f0258a4778057a8a7d97809bd209055b2fbafa654ce7d31ec7191066b9225e6 --version 2
  1. 用户升级相关工具和 SDK 至明确支持 v2 协议的版本，具体请参见 SDK 和 工具的 RELEASE NOTES。
← 上一篇下一篇 →