Consensus Protocol Upgrade Process

[arhag]

This document has been moved to the Developer's Portal

[abourget]

Is there a repo with worldwide agreement on block or header extensions numbers? I see a risk of clash with BOS's use of some those. Both use 0 for different reasons. An EEP someone?

[wanderingbort]

We are not aware of one at the moment.

Given the breadth of changes that forks of eosio can make, it seems unlikely that a global registry would truly capture all of the conflicting numbers/decisions and enable an agnostic client to navigate all possible permutations. That sounds like a far more aggressive and utopian standard of the eosio kingdom. A noble goal in the long term.

For the time period where we cannot provide a truly backend agnostic standard of interoperation, integrators will unfortunately need to be aware of which flavor they are talking to and take appropriate measures to account for the differences. This means, disambiguating a number of things including various extension IDs on core data structures will be a burden on those integrators for the foreseeable future. To that end, we expect each "primary" repo can serve as its own registry of that flavor's extensions for now. It's unfortunate.

[shuke0327]

I made a draft Chinese version for Chinese BP, plz fix me if anything wrong.
Translator: Kai|EOS42(wechat and TG id: shuke0327)

共识协议升级指南

这一指南的目的，在于帮助节点人员知悉在对 EOSIO 网络进行成功的共识升级时所需要采取的相应步骤(即所谓“硬分叉升级”)，目的在于尽量减少对用户的影响。

对网络进行测试

务必先在测试网络上进行部署与验证，才可以在正式网络上部署共识升级。支持初始协议升级的nodeos版本将首先作为候选版本发布， 版本号为: v1.8.0-rc2。现有的 EOSIO 测试网络可以使用这个版本的 nodeos 来执行和测试升级过程。

对升级的测试过程，有助于帮助出块节点了解在各自的 EOSIO 区块链网络实践与执行首个共识协议升级时所需要的步骤，以便能够共同协作以成功激活首个共识协议升级功能(简称协议特性)。在激活时若有节点未升级至最新版本会无法被兼容。该过程还会帮助出块节点知悉将 nodeos 从 v1.7.x 或更早的版本升级至 v1.8.x版本时的要求，帮助他们设定恰当的截止日期，以便告知社区首个共识协议特性激活的时间。

在测试网络上对升级过程进行测试，还能够帮助区块浏览器和其他的dApp测试在激活了协议特性之后的新规则下，其应用程序的变化与表现。部分协议特性对区块和交易数据的结构做了若干小的调整（例如 PREACTIVATE_FEATURE 和 NO_DUPLICATE_DEFERRED_ID 特性），因此需要对原先依赖于旧的数据结构的程序进行强制迁移。RESTRICT_ACTION_TO_SELF 这一协议特性对自 v1.5.1 版本开始存在的授权绕行的方式(authorization bypass) 进行了限定，有可能使得继续依赖于授权绕行功能(authorization bypass) 的智能合约无法运行。

EOSIO 网络的升级过程(也适用于测试网络)

因为这些步骤需要从创世块开始重播(replay)，所以在发布了支持初始一致协议升级的适当版本的nodeos之后(供测试网络使用的v1.8.0-rc2，对所有其他网络而言，是稳定版的 v1.8.0)，所有节点操作者都应该尽快执行以下步骤。这些步骤应在额外的节点服务器上执行，这些节点可以承受长时间离线（they can afford to be taken offline for an extended period of time）:

1. 确保其现有的节点运行着更新至最新的稳定版本的 nodeos (1.7.x)。然后，关闭 nodeos.

2. 做好备份后，删除 data 文件夹中的 blocks/reversible 文件夹、state-history 文件夹，以及 state 文件夹。

3. 将 nodeos 的旧版本替换为新版本。

4. 启动新的 1.8.x 版本的 nodeos, 将其从创世文件开始进行完全的重播(replay), 与网络同步。节点应接收区块，LIB 应当提前。运行着 v1.8.x 与 v1.7.x 的节点在激活首个协议升级特征之前可以在相同网络中同时存在。

（附上操作步骤的英文，供核对）

1. Ensure that their existing node is running the most recent stable release (1.7.x) of nodeos and then shut down nodeos.

2. Make a backup and delete the blocks/reversible directory, state-history directory, and state directory within the data directory.

3. Replace their old version of nodeos with the new release.

4. Start the new 1.8.x release of nodeos and let it complete replay from genesis and catch up with syncing with the network. The node should receive blocks and LIB should advance. Nodes running v1.8.x and v1.7.x will continue to coexist in the same network prior to the activation of the first protocol upgrade feature.

nodeos 自v1.7.x 升级至 v1.8.x 版本时，需要从创世文件开始对区块链重播。之后，v1.8.x 的节点可以如之前一样快速的启动和停止而无需重放区块。v1.7.x 版本的节点程序所生成的状态文件夹(state) 无法与 v1.8.x兼容。由 V1.7.x生成的便携式快照(便携式快照版本1)无法兼容 v1.8.x的程序版本,后者需要的
快照为版本2的快照。

由于从创世重放区块耗时甚久(如果运行用于追踪历史的插件，则时间更长)，建议出块节点预留给社区足够的时间用于在第一个协议升级特征激活之前对节点程序升级。

如果节点希望进行升级但并不想追踪自创世块以来的区块链历史，可以使用版本二的便携快照加快速度，该快照可以通过同步 v1.8.x 节点而生成。由于便携式快照所生成的方式具备确定性和可移动性，用户可以对比从任意来源所所下载的快照文件的hash值与若干可信任来源所发布的hash值，不过前提是他们是对同一区块id所进行的快照。

针对出块节点的特别说明

毫无疑问，出块节点应当在单独的一台非出块服务器上进行 nodeos 的重播(replay)过程。该服务器应当做好出块准备，可以在重放和同步工作完成之后，切换至该服务器进行出块。或者，可以在重播（replay）的服务器上做快照，然后传输至另外一台做好出块准备的机器上，之后再在该服务器上从当前的出块 BP 节点程序 v1.7.x 切换至 v.1.8.x 版本的节点程序。

v1.8 中引入的几乎所有协议升级特性首先都需要激活一个特殊的协议特性(代码名PREACTIVATE_FEATURE)，并使用该特性引入的功能来部署系统合约的更新版本。出块节点应当知晓，一旦BPs激活了 PREACTIVATE_FEATURE 协议特性，所有仍然使用 v1.7.x 版本的节点将无法继续正常同步，最后一个不可逆块(LIB)将停止前进。因此，重要的是就激活发生的时间进行协调，并宣布预期的激活日期，提供足够的时间给社区，以便及时升级节点。

激活 PREACTIVATE_FEATURE 并部署更新后的系统合约之后，出块节点能够更容易地对进一步的协议特性的激活进行协调。对于v1.8.x 中的其他协议特性, 可以在任何时候激活，而不需要给社区任何准备时间，因为此时，与区块链同步所使用的 nodeos 程序必须至少已经升级至 v1.8.x 版本，因而会支持所有的初始协议特性集。此外，由于 PREACTIVATE_FEATURE 协议特性的存在，节点可以通过多签的方式发起提案，使用新系统合约中的 activate（激活）指令对其余的协议特性进行激活，不需要再对区块链进行重放。

然而，首个协议特性(即PREACTIVATE_FEATURE）的激活，不能改通过 eosio.msig 多签提案的方式进行。需要出块节点更多的协调和人工操作。首先，出块节点应当就激活首个协议特征的最早时间达成一致意见。

之后，出块节点应当在 JSON 配置文件中设定好该时间，用于其 v1.8.x 节点程序的 PREACTIVATE_FEATURE 协议升级。具体来说，他们应当对配置文件夹中的 protocol_features/BUILTIN-PREACTIVATE_FEATURE.json 这一文件中的 earliest_allowed_activation_time 字段进行修改。

重要的是，应当先对节点程序的配置做好修改之后，才能够允许该节点在网络上出块。只要超过2/3的活跃出块节点(即排名前21的节点)在其BP节点的配置文件中就 PREACTIVATE_FEATURE 特征设定好了相同的未来激活时间，网络就可以保持安全，不会受到其他出块节点过早激活的影响。

在所商定的时间点之后，前21名出块节点中任意一位都可以通过向其 BP 节点的 producer_api_plugin 发起请求的方式激活 PREACTIVATE_FEATURE 这一协议特性。

为了确定请求命令的特定格式，首先需要确定 PREACTIVATE_FEATURE 合约特性的digest（摘要)信息。可以通过查看nodeos启动log，或者更好的方式是在启用 producer_api_plugin 后本地运行如下的命令行：

curl -X POST http://127.0.0.1:8888/v1/producer/get_supported_protocol_features -d '{}' | jq

返回数组中，找到指向PREACTIVATE_FEATURE代码名的对象, 例如:

{
  "feature_digest": "0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd",
  "subjective_restrictions": {
    "enabled": true,
    "preactivation_required": false,
    "earliest_allowed_activation_time": "1970-01-01T00:00:00.000"
  },
  "description_digest": "64fe7df32e9b86be2b296b3f81dfd527f84e82b98e363bc97e40bc7a83733310",
  "dependencies": [],
  "protocol_feature_type": "builtin",
  "specification": [
    {
      "name": "builtin_feature_codename",
      "value": "PREACTIVATE_FEATURE"
    }
  ]
},

上面例子中，PREACTIVATE_FEATURE 协议特性的digest数值为: 0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd. 请注意，由于对特定区块链网络的协议特性配置所做的本地更改的原因，该数值可能会有所变化。

获取了该数值之后，可以用如下的命令发送至本地出块的 nodeos 程序实体，在下一次该节点出块时激活 PREACTIVATE_FEATURE 协议:

curl -X POST http://127.0.0.1:8888/v1/producer/schedule_protocol_feature_activations -d '{"protocol_features_to_activate": ["0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd"]}' | jq

只能够在设定的激活时间之后，才使用上述命令。 PREACTIVATE_FEATURE 协议特征的激活时间，是经过 BP 一致同意后，在配置文件中对earliest_allowed_activation_time这一字段进行的设定。

任何 v1.8.x 的同步节点可用以下命令检查已激活了哪些协议特征:

curl -X POST http://127.0.0.1:8888/v1/chain/get_activated_protocol_features -d '{}' | jq

例如，若 PREACTIVATE_FEATURE 协议特征已激活，可能会得到如下的返回数组(注意，某些数值，特别是 activation_block_num 该字段，可能会有所变化):

{
  "activated_protocol_features": [
    {
      "feature_digest": "0ec7e080177b2c02b278d5088611686b49d739925a92d9bfcacd7fc6b74053bd",
      "activation_ordinal": 0,
      "activation_block_num": 348,
      "description_digest": "64fe7df32e9b86be2b296b3f81dfd527f84e82b98e363bc97e40bc7a83733310",
      "dependencies": [],
      "protocol_feature_type": "builtin",
      "specification": [
        {
          "name": "builtin_feature_codename",
          "value": "PREACTIVATE_FEATURE"
        }
      ]
    }
  ]
}

PREACTIVATE_FEATURE 协议特征激活之后，可以部署添加了 activate 激活指令的新的系统合约了。
（注：在新的系统合约中，添加了一项操作：activate, 可用于激活后续的协议特征。）

针对区块浏览器、交易所及 dApp 团队的说明

构建在 EOSIO 区块链上的区块浏览器、交易所和应用程序都可以遵循上面描述的四个步骤，及时对node程序升级，以确保在第一个协议升级激活时服务能够正常运行。不过，也请知悉，某些协议特性会改变区块链上现有的操作行为，在某些情况下，还会对区块和事务的结构进行轻微变动。

首先，v1.8.x 版本在任何协议特征激活之前就更改了事务追踪(transaction traces)的结构。通过历史插件、mongo_db_plugin 插件或者状态历史插件来使用事务和指令追踪的客户端程序，需要了解这些对追踪结构的变更(细节参见 #7044 及 #7108)。客户端程序如果使用来自区块链 API 的 push_transaction RPC 的追踪输出，不需要做任何改动，因为该 RPC 的输出应当会向后兼容。但是，我们更建议使用新的 send_transaction RPC 替换 push_transaction，它使用新的扁平式结构来存储指令跟踪(action traces)。

在 v1.8.x 中，状态历史插件也更改了 API 及存储在硬盘上的文件结构，支持向后兼容。这些更改反映了事务跟踪结构更改和链状态数据库中为支持新协议特性而进行的数据结构更改。状态历史插件的使用者需要进行更新，以适应 v1.8.x 中的新更改。

其次，所有的协议特征都是通过在一个块发送256位的摘要信息来激活的。出块节点可以将协议特征的摘要信息放在区块头的一个特殊位置中(称为区块头扩展（block head extensions）), 在原先 v1.7.x 的规则下，该部分数据为空。

区块浏览器团队应该特别注意这一变更，需要确保不会因为在区块头信息中加入这一额外的数据而造成区块浏览器工具出现问题，理想的做法是对区块浏览器升级以反映新的信息。在激活 PREACTIVATE_FEATURE 协议特征期间，区块浏览器或区块链数据的其他使用者会第一次遇到区块头扩展非空的情形。

第三，激活 NO_DUPLICATE_DEFERRED_ID 后，合约所生成的延迟事务会包含非空的交易扩展字段。虽然区块浏览器可能有兴趣用对用户友好的方式展示该字段内容，不过用户可以忽略这一信息。不过，对于直接处理这些事务的二进制序列化形式的代码而言，必须能够成功的将具有扩展数据的事务反序列化。注意，这也适用于智能合约代码，合约代码可能会读取使其执行的延时事务，不论是因为在延时交易内执行操作，还是执行因合约发送了失败的延迟事务而执行 eosio::onerror 通知处理程序。

第四，RESTRICT_ACTION_TO_SELF 协议特征激活后，原本在合约向自身发起内联操作时可以使用的绕过授权(authorization bypass)的方式会被移除(在 EOSIO的 v1.5.1 版本中绕过授权的方式被设定为不推荐/弃用的操作)。在 BP 激活 RESTRICT_ACTION_TO_SELF 协议特征之前，智能合约开发者应当确保其合约不依赖于这一绕过授权的做法，以保证其应用程序可以正常运行。

[heifner]

Thank you @shuke0327 and Translator: Kai|EOS42

[YordanPavlov]

I have an EOS Node version 1.7 running in mode:

--validation-mode=light --read-mode=read-only

would such node continue to operate on a 1.8 blockchain? If not, is there a date when the hard fork is taking place, which would be the deadline to upgrade from what I understand. Thanks.

[matthewdarwin]

You need to replay blocks or restore backup from 1.8 snapshot or backup once the protocol upgrade happens on 1.8.

As to when the protocol upgrade happens, that depends on each blockchain. For some chains (eg Jungle testnet) it has already happened.

[rskaskiw]

Fourth, activation of the RESTRICT_ACTION_TO_SELF protocol feature will remove the authorization bypass that is available when a contract sends an inline action to itself (this authorization bypass was deprecated in the v1.5.1 release of EOSIO). Smart contract developers should ensure their contracts do not rely on this authorization bypass prior to the time the block producers activate the RESTRICT_ACTION_TO_SELF protocol feature, otherwise, their contracts may stop functioning correctly.

Is there a reason for this restriction? It breaks parts of https://github.com/cryptolions/simpleassets .

[nksanthosh]

Fourth, activation of the RESTRICT_ACTION_TO_SELF protocol feature will remove the authorization bypass that is available when a contract sends an inline action to itself (this authorization bypass was deprecated in the v1.5.1 release of EOSIO). Smart contract developers should ensure their contracts do not rely on this authorization bypass prior to the time the block producers activate the RESTRICT_ACTION_TO_SELF protocol feature, otherwise, their contracts may stop functioning correctly.

Is there a reason for this restriction? It breaks parts of https://github.com/cryptolions/simpleassets .

Roman, this provides the details:
https://github.com/EOSIO/eos/releases/tag/v1.5.1

[aclark-b1]

In order to focus our efforts on issues that are currently creating difficulty for the community we are closing tickets that were created prior to the EOSIO 2.0 release. If you believe this issue is still relevant please feel free to reopen it or create a new one. Thank you for your continued support of EOSIO!