#MoonUpgradeGuard

#工作原理

flowchart LR
  old["旧产物<br/>Standard JSON · Foundry · Hardhat build info"] --> oldStage["提取，然后规范化<br/>无损 slot 与语义类型"]
  new["新产物<br/>同样的产物形态"] --> newStage["提取，然后规范化<br/>无损 slot 与语义类型"]
  oldStage --> compare["比较<br/>常规存储 · transient storage · ABI"]
  newStage --> compare
  compare --> report["诊断<br/>稳定诊断码，排序后的文本或 JSON"]
  report --> exit["退出码<br/>0 兼容 · 1 不兼容 · 2 输入不受支持"]

#仓库结构

• src/：MoonBit 核心库及其测试；src/cmd/moonupgradeguard/ 是原生命令行。
• fixtures/：兼容性样例、真实编译产物及其来源说明。
• scripts/：端到端、文档和发布包检查。
• docs/：诊断码、参考资料和差分对比记录。

#环境要求

• MoonBit 工具链，moonc 版本不低于 0.10.14， 并包含构建命令行所需的 native 后端。
• Python 3，仅用于 scripts/e2e.sh 校验 JSON 输出。

#构建与测试

moon check --deny-warn
moon test --deny-warn
moon build --target native

_build/native/debug/build/cmd/moonupgradeguard/moonupgradeguard.exe

#命令行

moonupgradeguard check OLD NEW [--format text|json] [--contract NAME|SOURCE:NAME]
moonupgradeguard storage OLD NEW [--format text|json] [--contract NAME|SOURCE:NAME]
moonupgradeguard abi OLD NEW [--format text|json] [--contract NAME|SOURCE:NAME]
moonupgradeguard --version

#输入

• 原始的 storageLayout 对象，例如 forge inspect 打印或布局工具写出的形式；
• 顶层带 storageLayout 的扁平产物，即 Foundry 写出的形式；
• solc Standard JSON 输出，contracts.<source>.<contract>；
• build info 文档，output.contracts.<source>.<contract>，即 Hardhat 写出的形式。

• Hardhat 的单合约产物不内嵌存储布局，Hardhat 的默认编译设置也不会请求它。请使用在 outputSelection 中请求了 storageLayout 的 build info 文件，或使用独立的布局文件。
• 当产物带有 transient storage 布局时，它会被比较：Foundry 会写出该布局，用 solc 时需要在 outputSelection 中包含 transientStorageLayout。没有报告该布局的产物会被视为没有 transient storage 变量，因此与带有该布局的产物比较时会报告为删除。

#复现走查

git clone https://github.com/snorfyang/moon-upgrade-guard.git
cd moon-upgrade-guard
moon build --target native

$ moon run src/cmd/moonupgradeguard -- check fixtures/compatible/old.json fixtures/compatible/new.json
$ echo $?
0

$ moon run src/cmd/moonupgradeguard -- check fixtures/append/old.json fixtures/append/new.json
info[abi.event.added] abi.events: event "Paused(address)" was added to the new ABI (new: Paused(address))
info[abi.function.added] abi.functions: function "pause()" was added to the new ABI (new: pause())
info[storage.entry.added] contracts/Token.sol:Token storage[2]: variable "paused" was added at slot 2, offset 0 (new: paused)
$ echo $?
0

$ moon run src/cmd/moonupgradeguard -- check fixtures/storage-moved/old.json fixtures/storage-moved/new.json
error[storage.entry.slot.changed] contracts/Token.sol:Token storage[0]: variable "totalSupply" moved from slot 0 to slot 1 (old: 0, new: 1)
error[storage.entry.slot.changed] contracts/Token.sol:Token storage[1]: variable "owner" moved from slot 1 to slot 0 (old: 1, new: 0)
$ echo $?
1

$ moon run src/cmd/moonupgradeguard -- check fixtures/abi-function-removed/old.json fixtures/abi-function-removed/new.json --format json
[
  {
    "code": "abi.function.removed",
    "severity": "error",
    "location": {"path": "abi.functions"},
    "message": "function \"transfer(address,uint256)\" is missing from the new ABI",
    "oldValue": "transfer(address,uint256)"
  }
]
$ echo $?
1

./scripts/e2e.sh

#在 CI 中使用

- name: upgrade compatibility
  run: |
    moon build --target native
    _build/native/debug/build/cmd/moonupgradeguard/moonupgradeguard.exe \
      check build/old.json build/new.json --format json

#兼容性模型

• Error：变量消失；变量移动了 slot 或字节 offset；变量的语义类型发生变化， 包括嵌套的 struct、数组和 mapping 变化。
• Warning：变量在同一位置、类型不变的情况下被重命名。字节仍在原处，因此布局依然兼容，但新名字可能承载了新的含义。
• Info：只出现在新布局中的变量（因此追加是兼容的），以及在原位调整大小的存储 gap。

flowchart TB
  subgraph oldLayout["旧布局"]
    o0["slot 0 — totalSupply"]
    o1["slot 1 — owner"]
  end
  subgraph newLayout["新布局"]
    n0["slot 0 — owner"]
    n1["slot 1 — totalSupply"]
  end
  o1 -. "移动：错误" .-> n0

• Error：function、event 或自定义错误的签名消失；返回类型列表发生变化，因为调用方按位置解码返回数据；event 的 indexed 布局或匿名性发生变化；某个 selector 或 topic 现在属于另一个签名；fallback/receive 处理器被同签名的具名函数取代 （或反之），因为两者到达方式不同：一个应答未被匹配的 calldata，另一个按 selector 分发。
• Warning：状态可变性（state mutability）变化，因为 selector 与 calldata 未变，而调用契约变了。
• Info：新增 function、event 或自定义错误。

#已知限制

• ERC-7201 命名空间存储（namespaced storage）不参与分析；若产物的 AST 含有合约内结构体的 @custom:storage-location erc7201: 标注，工具会报错拒绝，而不是报告为兼容。命名空间通过其注释自行推导出的 slot 访问，而编译器 storageLayout 只列出状态变量，因此其中不包含命名空间成员；要检查这些成员， 需要抽象语法树，外加一次本工具有意不执行的重新编译。单独提取布局文件也不会留下任何命名空间的痕迹，因此请传入完整产物。
• constructor 不参与比较：它的入参影响部署，而不是已部署代理对外暴露的接口。
• 这里的 ABI 兼容性指的是调用方兼容性，既不等同于 Solidity 源码兼容性，也不说明新代码的行为是否一致。
• 通过的检查结果是升级前预检，而不是审计。

#非目标

• 编译 Solidity 源码。
• 部署或升级合约。
• 管理钱包、私钥或 RPC 端点。
• 替代专业智能合约审计。
• 证明合约版本之间的业务逻辑等价。

#许可证