Antelope Spring v1.0 升级指南  

2024年9月25日星期三，EOS 区块链上的节点（BPs）即将执行一次硬分叉，升级至Spring v1.0 blockchain software，完成节点升级并进行 go/no-go 投票。

此次新版本发布引入了新的 Savanna 共识算法，节点也将在9月25日当天激活该算法。

同时还引入了 BLS finalizer keys，所有节点必须使用 spring-util 生成，并在9月25日后使用 eosio regfinkey 操作注册。

升级步骤

所有节点运营商必须在9月25日之前完成以下步骤：

1. 生成快照  

2. 停止 nodeos  

3. 删除 shared_memory.bin  

4. 升级节点软件至 Spring v1.0.0  

5. 从每个节点配置中删除 producer-threads 选项  

6. 使用 spring-util 生成 finalizer key(s)  

•     配置 finalizer keys。每个 nodeos 实例必须使用 config.ini 文件中的 signature-provider 或命令行来定义一组新的唯一 finalizer keys。  

7. 从快照重新启动节点  

9月25日，网络预计将签署多签交易以激活 BLS 协议功能，允许节点注册其 finalizer keys。

8. BLS 协议功能激活后，使用 eosio 合约中的 regfinkey 操作注册第一个 finalizer key。

• 第一次执行此操作时，该操作还将激活 finalizer key。其他 finalizer keys可以通过 regfinkey 注册，并随后使用 eosio 合约中的 actfinkey 操作激活。

完成这些步骤后，节点即可准备好进行 Savanna 共识激活。

• 重要提示：不正确的 finalizer key 处理可能会导致与网络同步问题。您可以在下方或官方文档中找到更多详细信息。  
• 使用 State History 的节点需要采用替代的日志文件压缩方式，如 ZFS LZ4 压缩，因为 SHiP 日志压缩已被移除。然而，从 Leap 4 及更高版本生成的 SHiP 日志文件仍可与 Spring 1.0 一起使用，无需重新生成。  
• 私有网络还需要升级系统合约至 EOS System Contracts v3.6.0。公共网络将通过多签交易升级系统合约。  
• 此外，超级节点需要升级合约开发工具包（CDT），以便从源代码构建 EOS System Contracts v3.6.0。任何从源代码构建基于 BLS 的智能合约（如系统合约 v3.6.0）的开发者都需要升级至 CDT v4.1.0。  
• 来自先前版本的区块日志、状态历史日志和追踪日志与 Spring v1 兼容。

Savanna 激活

9月25日，节点将进行 go/no-go 投票，以验证 21 个 finalizer key 中的 15 个。如果投票通过，节点将签署一个多签交易，执行 switchtosvnn 操作，在 EOS 网络上激活 Savanna 共识算法。

Spring v1.0 和 Savanna 共识算法代表了区块链技术的飞跃。Savanna 使用了升级的验证架构，允许 Antelope 网络扩展活跃节点的数量，而不会增加最终确认时间。它还将最终确认时间减少了95%以上，这对所有交易都有帮助。这种速度极大地改变了 Antelope 的 IBC 协议的实用性，使其成为一个完全水平可扩展的网络网络。

重要发行说明

Spring 1.0 的大部分新功能与 Savanna 共识算法有关，但一些组件已被删除或修改：

• 节点运营商必须从 config.ini 文件中删除 producer-threads 配置选项，因为该选项已被软件移除。如果配置选项中包含 producer-threads，nodeos 软件将无法启动。  
• State History（SHiP）日志文件压缩已被禁用。拥有状态历史的节点运营商需要实施自己的压缩解决方案。目前，一些节点使用 ZFS LZ4 压缩来完成此操作。  

Spring 1.0 还包含与许多节点和其他节点运营商相关的更改：  

• 新的配置选项 vote-threads 必须在连接到 BP 节点的所有 intermediate peer/sentry nodes 上设置为正数（1 或更大）；否则，投票将无法在网络中传播。BP 节点的 vote-threads 默认值为 4，但对于其他配置可以设置为 0。您可以从 EOS Nation 找到对等设置示例，并在官方文档中了解更多关于对等的内容。 
• get_block_header_state 端点现在返回不同的响应，其中包含所有字段，但只有 block_num、id、header 和 additional_signatures 填充完整。  
• 为支持跨链通信运行 SHiP 的节点，必须将 finalizer-data-history 选项设置为 true。  
• finalizer-dir 选项允许节点运营商可选设置用于存储投票历史的目录路径。这是为了避免在移动或删除 data 目录时引发节点同步问题。  

所有节点运营商都应注意这些详细信息，以准备 Spring 1.0 的硬分叉。

升级清单

一些具体步骤可能因节点配置而异，但这些通用步骤适用于大多数节点。

升级规划  

• 不要在生产节点上测试升级——请先使用测试节点  
• 确保您的 Ubuntu 构建已更新。旧版本的 Ubuntu，如 18.04，不受支持。支持的操作系统包括：
  •   Ubuntu 22.04 Jammy（推荐）  
  •   Ubuntu 20.04 Focal  
• 不要使用已弃用的插件或选项：
  •   producer-threads  
  •   SHiP（State History）日志文件压缩（请改用 ZFS）  
• 启用任何新的必需插件和选项（见下文）  
• 备份您的节点 

节点升级  

1.下载/构建二进制文件。  

1. Spring 1.0.0  

这是所有节点都必须执行的操作。  

2. （某些节点）EOS System Contracts v3.6.0  

仅适用于私有网络。公共网络通过15/21个超级节点批准的多签名交易推送系统合约更新。  

3. （某些节点）CDT v4.1.0  

仅在构建系统合约二进制文件，或其他使用BLS功能的合约时需要此更新。  

2.确保启用 producer_api_plugin 插件。这是创建快照所必需的。除非此插件已在节点上使用，否则建议在创建快照后禁用它。  

1. 通过命令行 --plugin eosio::producer_api_plugin，或在配置文件中添加 plugin = eosio::producer_api_plugin。  

3.使用/v1/producer/create_snapshot 端点创建快照。  

1. 使用命令 curl -X POST http://127.0.0.1:8888/v1/producer/create_snapshot。等待curl返回包含新创建的快照文件名的JSON响应。  

• 此步骤需要nodeos继续从P2P网络接收区块，否则curl命令将不会返回。  

2. 或者，您可以从超级节点（如EOSphere、EOSUSA、Genereos和EOS Nation）下载快照。Leap v5.0生成的快照将采用v6格式。Spring 1.0兼容v4、v6和v7的快照。  

4.停止您的节点。  

5.删除旧的状态数据。  

• 区块日志、状态历史日志和先前版本的跟踪日志都与Spring v1兼容，因此在执行升级过程中无需删除这些文件。  

1. 删除 /data/state/shared_memory.bin。该文件位于$HOME/local/share/eosio/nodeos/data/state，或在命令行中通过--data-dir参数指定的目录中。  
2. （可选）删除protocol_features目录。  

6.删除旧的配置选项和插件，并添加新的选项。  

删除：  

• producer-threads选项。  
• 某些插件或选项已在Leap v5.0.0中删除或弃用。确保节点未使用以下任何选项：
  • cpu-effort-percent  
  • last-block-cpu-effort-percent  
  • last-block-time-offset-us  
  • produce-time-offset-us  
  • max-nonprivileged-inline-action-size  
  • max-scheduled-transaction-time-per-block-ms  
  • disable-subjective-billing  
  • 使用延迟交易的操作  

在5.0升级指南中了解如何禁用这些功能的更多信息。  

7.更新您的二进制文件。  

根据您的偏好和设置，选择性地执行以下操作：  

• 添加 finalizers-dir 选项以设置存储投票历史的目录路径。大多数节点可以使用默认设置。
  • 保护移动或删除“data”目录的脚本中的finalizer safety file，或使用该选项设置finalizer safety.dat 文件的其他位置。  
• 为运行 SHiP 以支持 IBC 的节点添加 finality-data-history 选项。  
• 准备处理新的 get_block_header_state API调用响应。  
• 开启状态历史的节点应使用ZFS-LZ4等压缩解决方案代替SHiP（状态历史）日志文件压缩。关于Antelope节点上ZFS压缩的详细信息，请参阅此处。  
• vote-threads 一般应保持不变。BP节点的默认值为 4，而其他节点类型的默认值可能为 0。默认值通常有效，但位于BP节点与 intermediate nodes 之间的中间节点可能需要将该值设置为1或更高。中间节点必须至少有一个投票线程，以便正确广播投票到网络的其他部分。  

8.使用spring-util生成多个唯一的finalizer keys，并将其添加到 config.ini 中的signature-provider 中。详情如下。  

9.启动您的节点。  

节点更新到 Spring 1.0 后，可以生成用于后续使用的finalizer keys。然而，在激活finalizer key之前，网络必须启用BLS_PRIMITIVES2协议功能，这需要在9月25日进行的多签名交易。一旦BLS primitives被激活，您可以注册并激活finalizer keys。  

Finalizer Key 安全  

请注意，每个区块生产节点都必须拥有自己的新的唯一finalizer key。如果您有一个主要BP节点和一个备选BP节点，每个节点都需要一个唯一的finalizer key列表，不能在节点之间共享密钥。重复使用节点之间的finalizer key将导致生产者与链条的其余部分不同步。  

关于safety.dat文件的一个重要注意事项：该文件记录了给定BLS finalizer key的投票历史。finalizer key 投票历史的任何不匹配都会导致节点在链的错误分支上投票，并失去与网络的同步。这有几个影响：  

• 不要在主机之间共享BLS finalizer keys。相反，在从一个活动主机切换到另一个时激活一个新钥匙。  
• 不要在主机或节点之间共享safety.dat文件。  
• 不要备份和恢复safety.dat文件。相反，切换到一个新的BLS finalizer key。  

这些考虑很重要，因为投票是根据一个从前一个Digest增量构建的Merkle Tree Digest提交的。使用旧的投票历史会使用旧的Merkle Tree Digest来计算新的Digest，这是不正确的。一旦错误的Digest成为计算的一部分，所有后续的Digest都会出错。  

因此，最佳实践是永远不要重复使用BLS finalizer keys，并在切换节点时始终激活一个新的、唯一的finalizer key。  

切换到一个新钥匙会从零开始，无需历史记录。从无历史记录开始，使用现有信息创建Merkle Tree Digest，以防止不匹配。  

了解更多关于finalizer safety 和 managing finalizer keys，请参考官方文档，或查看finalizer key 轮换的示例。 

Finalizer Key 细节

要生成并激活finalizer keys，请按照以下步骤操作：

1.使用 spring-util 生成 key(s)。 示例：

spring-util bls create key --to-console > producer-name.finalizer.key

这将生成一个Private key、一个Public key以及一个proof_of_possession。

响应示例：

首先，将你生成的一个或多个钥匙添加到某个 nodeos 实例的 config.ini 文件中的 signature-provider 配置选项中。

该选项的格式为：signature-provider = <PUBLIC_KEY>=KEY:<PRIVATE_KEY>，每个钥匙需要写在新的一行。如果文件中没有此选项，你需要手动添加。

这里列出的钥匙在不同的节点之间应该是不同的，并且任何您计划注册和激活的钥匙必须在启动节点之前列在这里。

示例：

4.使用 regfinkey 操作在链上注册一个钥匙

此操作将钥匙注册为一个潜在的激活钥匙。生产者第一次调用此操作时，钥匙会自动激活。

建议注册多个finalizer keys，但每个生产者节点一次只能激活一个finalizer key。

示例：

5.切换到新节点时，或在其他需要的情况下，可以使用 actfinkey 操作在链上激活一个新的预注册钥匙。

注册后，生产者可以随时使用 actfinkey 操作安全地激活任何新的唯一finalizer key。使用的钥匙必须已经存在于配置文件的 signature-provider 选项中，并且必须已经通过 regfinkey 操作注册。

示例：

6.如有需要，可以使用 delfinkey 操作删除 finalizer key。

要删除的 finalizer key 必须是已注册的密钥，格式为 base64url，并且不能是活跃状态。删除 finalizer key 的账户必须具备在 finalizer_name 字段中指定的权限。

如果被删除的钥匙是最近注册的 finalizer key，delfinkey 操作将成功删除该活跃钥匙。如果删除的是最后注册的钥匙密钥，该BP将被从前 21 个活跃验证的 BP 中移除，下一个拥有注册finalizer key的 BP 将接替其位置。

示例：

在注册并激活一个新的唯一 finalizer key 后，确保所有节点都已升级到 Spring 1.0 软件，您的基础设施应该已准备好进行升级。

让每个节点为Savanna做好准备  

Savanna 共识算法是 Antelope 网络在速度和去中心化方面的重大突破。升级到 Spring 1.0 并切换到 Savanna 涉及一系列步骤，确保平稳过渡。

构建系统合约的节点和其他开发人员应将合约开发工具包（CDT）升级到v4.1.0版本。

EOS网络上的超级节点必须在9月25日之前完成以下步骤：

1.构建并升级节点软件到 Spring v1.0.0  

• 创建快照  
• 停止节点  
• 删除旧的状态文件shared_memory.bin  
• 从config.ini中移除producer-threads  
• 从源代码构建并更新二进制文件  
• 重新启动节点  

2.使用 spring-utils 生成 finalizer key(s)  

• 每个nodeos实例应拥有一组唯一的finalizer keys，这些finalizer keys不应存在于任何其他nodeos实例中。重复使用finalizer keys会导致节点在链的错误分支上进行投票。  

3.在9月25日进行系统合约升级后，使用eosio合约中的regfinkey操作注册finalizer key。  

• 节点首次注册finalizer key时，该操作还会激活该finalizer key。  
• 通过regfinkey注册其他finalizer key。必须在激活之前先注册密钥。  
• 使用actfinkey操作激活已注册的密钥。  

通过遵循这些步骤，节点可以确保平稳过渡到Savanna，并帮助解锁EOS区块链的新功能。有关finalizer key、管理finalizer key、切换到Savanna共识以及升级到Spring 1.0的更多信息，请查阅官方文档中的迁移指南。立即升级，以引领一个更强大和去中心化的EOS网络。