Starcoin-Framework 合约投票升级流程
- 1 简述
- 2 升级步骤
- 2.1 注意事项
- 2.2 一、准备升级包 (注意mpm release)
- 2.3 二、提交升级投票提案
- 2.4 三、执行两阶段升级
- 3 参考链接
简述
该文档描述了 Starcoin-Framework 两阶段升级流程,这里实际上分为了两步
第一步,产生了一个升级的投票提案,会将两阶段升级的动作作为投票的结果来执行。
第二步,从投票成功的提案中提取两阶段升级的plan,执行完该plan之后,就完成了整个升级流程。
升级步骤
注意事项
参考https://github.com/starcoinorg/starcoin-framework/blob/main/release/README.md 参考你此次升级是否需要有init_script function一般就是类似 StdlibUpgradeScripts::do_upgrade_from_v6_to_v7 这种函数
一、准备升级包 (注意mpm release)
从https://github.com/starcoinorg/starcoin-framework 找到对应的tag,签出该tag并执行以下命令编译打包
# 编译
$ ./scripts/build.sh
# 打包
$ mpm package build
# 在 release/ 目录下能找到对应的编译好的二进制包,并可以在控制台中找到对应的package hash
# 根据实际需要看看是否调用--function
mpm release --function 0x1::StdlibUpgradeScripts::upgrade_from_v11_to_v12
二、提交升级投票提案
调用ModuleUpgradeScripts::propose_module_upgrade_v2 方法来提交,将上面的打包出来的对应的hash作为参数传入。
starcoin% account execute-function --function 0x00000000000000000000000000000001::ModuleUpgradeScripts::propose_module_upgrade_v2 -s 0x8a47a41e0465d9a53b19bf858d990865 -t 0x00000000000000000000000000000001::STC::STC --arg 0x00000000000000000000000000000001 --arg x"e4cb45429ef1fb27c7271b446ce9b1222263c3c09315583de27d275ec098459e" --arg 12u64 --arg 0 --arg false -b # 命令返回 { "ok": { "dry_run_output": { "events": [ { "data": "0x01000000000000008a47a41e0465d9a53b19bf858d990865", "event_key": "0x120000000000000000000000000000000000000000000001", "event_seq_number": "1", "type_tag": "0x00000000000000000000000000000001::Dao::ProposalCreatedEvent" } ], "explained_status": "Executed", "gas_used": "173293", "status": "Executed", ... } ... }
检查提案投票状态,这里的状态为2(可投票)(状态定义参考Starcoin去中心化治理机制, 也可以参考Dao.move中的定义)
# 这里proposal_id为全局自增,是因为该账号之前投过一次票了,所以为1 starcoin% dev call --function 0x1::Dao::proposal_state -t 0x1::STC::STC -t 0x1::UpgradeModuleDaoProposal::UpgradeModuleV2 --arg 0x8a47a41e0465d9a53b19bf858d990865 --arg 2 # 命令返回 { "ok": [ 2 ] } # 若不确定这里是哪个proposal id,可以执行以下命令查看当前 proposal id 命令 starcoin% state get resource 0x8a47a41e0465d9a53b19bf858d990865 0x1::Dao::Proposal<0x1::STC::STC,0x1::UpgradeModuleDaoProposal::UpgradeModuleV2> { "ok": { "json": { "action": { "vec": [ { "enforced": false, "module_address": "0x00000000000000000000000000000001", "package_hash": "0xe4cb45429ef1fb27c7271b446ce9b1222263c3c09315583de27d275ec098459e", "version": 12 } ] }, "action_delay": 60000, "against_votes": 0, "end_time": 1682076798301, "eta": 0, "for_votes": 15925669899949605, "id": 2, // 当前proposal id "proposer": "0x8a47a41e0465d9a53b19bf858d990865", "quorum_votes": 3187142521908000, "start_time": 1682076198301 }, "raw": "0x02000000000000008a47a41e0465d9a53b19bf858d9908659de58da3870100005d0d97a387010000255632f94f943800000000000000000000000000000000000000000000000000000000000000000060ea00000000000020ebdd71b0520b000000000000000000010000000000000000000000000000000120e4cb45429ef1fb27c7271b446ce9b1222263c3c09315583de27d275ec098459e0c0000000000000000" } }
这里在console中使用基金会账号投票,一定能保证结果超过4%,
在console中如果没有基金会权限,参考Halley & Proxima & Barnard 基金会账号 ,使用如下命令得到基金会账号权限, 基金会STC有159256698999279320,取10分之一能保证一定成功
这里可以结合本地账号信息,使用如下脚本进行投票,并且查看投票信息
返回分别是Proposal_id,投票开始时间,投票结束时间,赞成票数,反对票数 (这里时间使用的毫秒)
实际结束时间是
1682076198301 / 1000
=1682076798
, 使用 date -r1682076798
看到结束时间是Fri Apr 21 19:33:18 CST 2023
等到这个时间过后, 查看投票状态
投票成功后将其加入执行队列(main使用poll.starcoin.org网页,这步会自动执行)
执行提案,该函数会将投票通过的UpgradePlan动作提交给升级模块
取回质押的Token并且完成清理提案
三、执行两阶段升级
背景介绍
在介绍两阶段升级之前,先介绍一下升级策略,一共有以下几种:
两阶段升级,也就是当升级策略为 1 的时候,才可以进行两阶段升级。每个账户都会有一个模块的升级策略(0x1也不例外),可以执行以下命令进行查看:
这里的两阶段,将升级分为plan提交公示阶段和实际执行升级的阶段,故称为两阶段。
公示阶段,需要提交一个升级时的包对应的hash,以便第二阶段在真正升级的时候做检查,这里有个公示的时间,第二阶段必须要在这个时间之后才可以执行
提交阶段,需要提交跟hash对应的二进制包
上面说的投票升级,实际上是由于普通账户对0x1没有权限,所以需要通过Dao投票治理来决定的。如果用户对模块有权限,则可以直接通过调用 UpgradeModuleDaoProposal::submit_upgrade_plan 来提交升级提案。
通过阅读代码可以看到在UpgradeModuleDaoProposal::submit_upgrade_plan 中需要UpgradePlanCapability ,这个能力在调用update_module_upgrade_strategy
这个函数来赋予的。
升级流程
首先需要检查用户是否拥有 UpgradePlan,如果发现 plan 字段为空,则需要重新去跑一遍投票流程或者重新调用提交plan函数
如果有 Plan,则直接调用dev deploy部署之前打包出来的二进制模块,注意这个包需要跟前一步提交plan时传入的hash值对应,注意这里提交的时间应该在 UpgradePlan { active_after_time: “123456“ } 这个时间戳之后。
至此升级模块完成。Enjoy it!