跳转至

路线图

MoonUpgradeGuard 是一个针对 EVM 合约升级的升级前兼容性检查器。本页记录已经交付的能力、接下来要验证的产物形态，以及后续方向。它只描述工程优先级与产品行为：这不是排期，也不构成带时间的承诺。

优先级如何决定

  1. 可能把结论错判为"兼容"的规则，优先于只改善措辞的改动。
  2. 每条比较规则都配一个能复现它所要捕获变化的 fixture，以及一个在缺少该规则时会失败的测试。
  3. 不受支持的输入必须显式失败，并以退出码 2 结束；它永远不会变成静默放行。
  4. 范围按规则增长，而不是按界面增长。
  5. 任何改变诊断含义的改动——诊断码、严重度或 JSON 结构——都属于契约变更，必须明确声明。

已交付

  • 产物摄取：原始 storageLayout 对象、Foundry 写出的平铺 artifact、solc Standard JSON 输出、Hardhat build info，并提供 --contract 选择器处理包含多个合约的文档。歧义与不受支持的形态会被报告，而不是被猜测。
  • 存储：无损的 slot 与 byte offset、打包字段、定长与动态数组、mapping、struct、 递归类型图，以及被缩减或整体替换的 __gap 数组。
  • transient storage：使用同一套规则比较，位于它自己的 transientStorage[...] 命名空间。
  • ABI：规范化签名、Keccak-256 selector 与 event topic（已对公开向量校验）、删除、 返回值列表变化、indexed 与 anonymous 变化、mutability 变化，以及两个版本之间的 selector 或 topic 冲突。
  • 诊断：带严重度、位置与被比较的旧值和新值的稳定诊断码；确定性的文本与 JSON 输出；可供流水线判定的退出码 0、1、2。
  • 证据：包含针对生成布局的不变量检查的单元测试、CLI 进程级检查、每条规则一对 fixture，以及与 OpenZeppelin Upgrades Core 的差分对比记录。
  • CI：每次 push 与 pull request 都执行格式检查、类型检查、测试、生成物是否已提交 （接口与诊断码手册）、空白检查、端到端 CLI 脚本与发布包文件清单检查。
  • 版本报告：CLI 的 --version 输出版本号，端到端测试核对它与模块清单一致。
  • 原生发布产物：v0.2.0 提供 Linux x86_64 与 macOS arm64 可执行文件；两个平台均在发布 CI 中构建并通过端到端检查。
  • 诊断码手册：一页列出全部诊断码、严重度、是否阻断与含义，由源码生成，CI 重新生成后若与提交内容不一致即失败，因此新诊断码不可能没有文档。
  • 可复现走查：中英两版实战教程都能从全新 clone 走到一次通过检查与一次失败检查， 其中每一条命令、输出与退出码都由 CI 对真实二进制逐条核对。
  • 双语文档：公开文档以中文为主、英文镜像（X.md 与 X.en.md，顶部互相链接）：README、 诊断码手册、差分对比记录、参考与许可页、fixture 说明都有英文版；路线图目前只有中文。两份诊断码手册由同一份源码生成，翻译缺失会被生成器直接拒绝，中英结构一致性由 scripts/check_docs.py 在 CI 中校验。
  • 参考与许可：规则依据的一手规范、依赖许可证（MoonBit 标准库与 moonbitlang/async 为 Apache-2.0；OpenZeppelin Upgrades Core 为 MIT 且仅用于开发期行为对比；solc 仅使用其输出）、 fixture 来源与上游关系，记录在 docs/references.md 及其英文镜像中。
  • 真实编译产物回归矩阵：仓库自有源码生成 solc Standard JSON、Foundry 平铺 artifact 与 Hardhat build info，覆盖兼容、不兼容及无布局输入的退出码 0、1、2；另用 solc 真实产物验证打包字段、mapping、struct、__gap 与 transient storage 的组合变化。
  • 诊断来源标注：单侧输入诊断带有 old 或 new 来源；两侧无效时仍能分辨每条错误， 比较诊断不归属于单侧产物。这是 JSON 报告结构的公开变更。

更晚

  • 命名空间存储与非结构化 slot。 编译器的 storageLayout 只列出状态变量，因此 ERC-7201 命名空间成员与 EIP-1967 这类非结构化 slot 对它不可见。读取它们需要抽象语法树，而命名空间成员的位置还需要一次本工具刻意不执行的重新编译。在这一层出现之前，提到命名空间的产物会被拒绝，而不是被报告为兼容。
  • 严格重命名模式。 同一位置的重命名不会移动任何字节，因此目前是警告。有些团队可能希望它阻断升级；那会是一个可选项，且必须公开记录，而不是静默改变默认行为。
  • 更多目标平台。 库与目标平台无关，而 CLI 仅支持 native。只有在 CI 覆盖之后才会声明更多目标。
  • 包注册表发布，使 CLI 无需从源码构建即可安装。

稳定性

  • 诊断码及其严重度是稳定的，JSON 报告结构也是稳定的。新增内容会在发布说明中公布。
  • 在 0.x 版本之间，库 API 仍可能变动；命令行与退出码是更稳定的接触面。
  • 报告是确定性的：相同输入产生字节一致的输出，诊断始终按稳定顺序排序。

如何提供反馈

请提交 issue，并附上能复现该情况的 artifact 对、该规则应当遵循的规范或 EIP，以及你期望的行为。请不要附带私钥、个人地址或任何无法公开分享的内容。