SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场spol-upgrade

spol-upgrade

部署与运维

查看项目

更新于 10-13 15:25

技能介绍

用途

spol-upgrade 是 Polygon spol-contracts 仓库中的一个技能，用于在规划、编写测试或执行 sPOL 合约升级时提供流程指导，同时也用于稳态运维检查，例如 L2-buy 陈旧度。该技能记录了跨链 sPOL 升级端到端运行的模式，包括 fork 测试、runbook 和 sanity 脚本。资料提到，PolBridger-to-proxy 升级（2026 年 4 月）是首次产生这些笔记的运行，其中的模式有意设计为与升级形态无关。

主要能力

该技能包含两个参考文件，二者基本独立：

  • fork-tests.md：在编写或审查升级的 fork 集成测试时阅读。涵盖跨链测试夹具（recordLogs + vm.selectFork）、prank 规则、mock-messenger 模式以及 EIP-7702 陷阱。
  • runbooks.md：在草拟 MAINNET-UPGRADE-PLAN.md、-PROTOCOL.md、-SAFETY-SUMMARY.md、*-INTEGRATOR-NOTES.md、TESTNET-DRY-RUN-PROTOCOL.md 时阅读。包含章节模板、注意事项以及何时提交什么内容。

使用方式

下次升级的快速配方如下，升级脚本是重心，计划、fork 测试和 runbook 都引用它。先写计划，再写脚本，然后处理其他内容。

  1. 先做计划。使用 runbooks.md 中的模板草拟 script/upgrades/<UPGRADE-NAME>-PLAN.md。在编写代码前获得批准。

  2. 编写升级脚本（script/upgrades/<UpgradeX>.s.sol）。这是操作者将要广播的内容，也是 fork 测试将要预演的内容。外部 runBoth(string) / runL1 / runL2 包装器处理 vm.startBroadcast 并从环境变量读取 DEPLOYER_PRIVATE_KEY。内部 _deployL1(cfg, deployer) / _deployL2(cfg, deployer) 将 deployer 作为参数，不广播也不读取环境变量，这使它们可被测试调用。包含 verifyL1(string, address) / verifyL2(string, address) 视图函数，重新推导每个 CREATE2 地址并断言代理实现槽位、不可变量、ProxyAdmin 所有权和指针值。广播后运行它们作为升级的第一道 sanity 门。在每个 _deployL* 辅助函数顶部断言 block.chainid 与预期链匹配。预测并检查：使用脚本的 verify*（或同类地址预测视图）暴露升级将落地的每个 CREATE2 地址，然后在它可能广播到的每条链上执行 cast code <addr>，广播前拒绝任何非零 codesize。

  3. 运行迁移健康脚本。script/operations/MigrationHealth.s.sol 在三种 APY 场景和五个时间偏移下报告当前和下一次迁移的规模、L2-buy 陈旧度截止时间以及 Plasma 注册表状态（谓词是否授权、contractMap 条目、HALF_EXIT_PERIOD）。在接近广播时重新运行，因为值会每小时漂移。即使不触及迁移代码的升级也应运行它作为当前状态健康检查。

  4. 编写升级 fork 测试，见 fork-tests.md。测试继承升级脚本（is Test, UpgradeX），在 vm.startPrank(deployer) 下运行其部署辅助函数，然后在 vm.prank(adminSafe) 下提交打印出的多签 calldata。该测试是字面预演，如果脚本改变，测试会在主网出错前先失败。测试放在 test/upgrades/ 下，CI 跳过该路径。

  5. 为任何新增或变更的合约行为添加或更新单元测试和集成测试。与升级 fork 测试分开，这些测试覆盖新代码本身，而非升级预演。它们位于 test/unit/ 和 test/integration/，在 CI 中每个 PR 运行，发布后不会被删除。规则包括：每个新的外部/公共函数都要有快乐路径和每个回滚路径的单元测试；每个变更的函数要更新其现有测试，若测试不再合理则删除而非任其腐烂；仅通过消息层可达的跨链行为要针对全新的 Deploy.s.sol 设置编写集成测试。

  6. 安全摘要。在计划稳定且合约编写完成后，撰写 <UPGRADE>-SAFETY-SUMMARY.md。一页纸，使用平实语言，面向 Safe 签名者和非工程审阅者。每个价值移动/状态转换有自己的章节：什么在移动、调用链、规模或风险价值、一个安全假设，以及如有损失确认。模板在 runbooks.md 中。

  7. 在匹配的测试网对上端到端测试网演练（例如 L1+L2 升级用 Sepolia↔Amoy；单链升级仅单链）。在 <UPGRADE>-TESTNET-DRY-RUN-PROTOCOL.md 中实时记录运行。要记录的内容见 runbooks.md。

  8. 合约冻结后编写集成者说明，为 UI/应用/索引团队提供地址、ABI、事件差异。模板在 runbooks.md 中。

  9. 主网协议。实时镜像测试网协议为 <UPGRADE>-PROTOCOL.md。每个阶段一个章节，内联交易哈希，每次读取都有时间戳。末尾有签署说明和事后总结。

Deploy.s.sol 边界

script/Deploy.s.sol 是绿地部署。用于单元测试、全新状态集成测试和需要干净 sPOL 环境的模糊测试（sPOLControllerFullL1.t.sol、sPOLControllerOther.t.sol）。不要在主网/测试网升级的 fork 测试中继承它。这样做会在分叉状态之上产生一个并行协议，无法模拟在途升级在链上的行为。应改用升级脚本（见第 2 步）。如果升级脚本尚不存在，先编写它，这是标准流程。

升级发布后删除与保留的内容

这些文件是一次性工件，升级后删除，依赖本技能进行下一轮：

  • test/upgrades/<upgrade-name>.t.sol — 固定到升级前状态的 fork 测试。所有升级 fork 测试必须放在 test/upgrades/ 下，CI 通过 forge test --no-match-path "test/upgrades/" 跳过该路径（见 .github/workflows/test.yml），这样发布后不可避免的失败不会阻塞 PR。不要把升级 fork 测试放在 test/integration/。
  • script/upgrades/<UpgradeX>.s.sol — 升级脚本本身。
  • script/upgrades/*Proof.json — 仅在适用时。PolBridger 升级为卡住的迁移发布了恢复证明；常规升级不需要。
  • 升级特定的 runbook：-PLAN.md、-PROTOCOL.md、-SAFETY-SUMMARY.md、TESTNET-DRY-RUN.md。*-INTEGRATOR-NOTES.md 保留作为公开变更日志条目，见 runbooks.md。

保留的内容：

  • test/integration/sPOLControllerFullL1.t.sol、sPOLControllerOther.t.sol — 非升级特定。
  • test/integration/CheckpointData.sol — 当 L1 RPC 修剪时需要定期刷新。见 fork-tests.md 的 CheckpointData 章节。
  • test/mocks/MocksPOLMessenger.sol — 通用辅助工具，可在各次升级中复用。
  • script/operations/MigrationHealth.s.sol — 通用迁移健康计算器。只读；在 APY 场景下报告当前和下一次迁移安全以及 L2-buy 陈旧度截止时间。用于广播前以及操作者想估算捐赠规模或检查 L2 健康时。
  • script/Deploy.s.sol — 绿地部署夹具。仅用于单元/全新状态集成/模糊测试。不用于升级 fork 测试（见上文 Deploy.s.sol 边界）。
  • calculator/index.html — 无关的用户面向 APY 计算器。不要动。

约定

  • Foundry 自动加载 .env。forge script / forge test 自动读取仓库根目录的 .env，不要 source .env 或在 forge 命令前加 L1_RPC_URL=... L2_RPC_URL=...。直接运行 forge script ...。使用 vm.envString("L1_RPC_URL") 的测试同样适用。如果缺少值，编辑 .env，不要通过 shell 管道传入。
  • RPC 和 salt 安全。三条规则避免广播到错误的链或与之前的部署冲突：升级脚本的 _deployL1 / _deployL2 必须在任何部署前断言 block.chainid == cfg.chainIdL1 / chainIdL2。这是唯一能捕获错误 RPC 环境变量的检查。salt 前缀必须在不同环境间不同（testnet-、mainnet-），这样错误链的广播不会静默与真实部署冲突。在每次升级前于 script/input.json 中验证。预测每个 CREATE2 地址并在广播前在每个候选链上 cast code 它。非零 codesize 意味着中止。

适用场景

当用户进行以下任何操作时触发此技能：编写或修订驱动升级端到端跨一条或两条链的 fork 测试；草拟/执行升级 runbook（部署脚本、多签 calldata、sanity 脚本、集成者说明）；让新贡献者入职升级工作流。升级可能涉及或不涉及卡住的迁移恢复、捐赠或国库操作，这些是通用工作流的特殊情况。

限制

资料未提供该技能的具体安装命令、支持平台、收费或价格信息，这些内容暂未提供。