智能合约与以太坊 / 系统课时

比对升级前后存储布局

比对升级前后存储布局

升级代理合约时,即使新实现能够编译并成功部署,也可能因状态变量位置变化而破坏用户余额或管理员权限。本文使用 Solidity、Foundry 和真实代理地址,完成升级前后的存储布局检查、链上数据快照及一致性验证,判断一次升级是否安全。

学习目标

  • 理解代理合约的存储槽与状态变量布局之间的关系。
  • 使用 Foundry 对比新旧实现的存储布局,识别变量重排与类型变更风险。
  • 在实际代理升级前后验证余额、总供应量和管理员权限没有意外变化。

为什么升级会破坏已有数据

常见的代理模式使用 delegatecall 执行实现合约代码,但状态数据保存在代理合约自身的存储空间中。升级操作通常只改变代理指向的实现地址,不会把旧存储数据自动转换为新结构。

Solidity 会按照继承关系、变量声明顺序、类型大小和打包规则安排状态变量。完整占用存储槽的 uint256 通常占据一个槽,而相邻的小类型变量可能共享一个槽。映射与动态数组还具有专门的存储寻址规则。

假设旧实现包含以下布局:

变量 类型 存储位置
totalSupply uint256 槽 0
balances mapping(address => uint256) 槽 1 为映射锚点
owner address 槽 2,偏移 0

其中,balances 的实际元素不直接存储在槽 1。对于地址 a,元素位置由地址编码与映射锚点共同计算,即 keccak256(abi.encode(a, uint256(1)))。

如果新实现把 balances 移到槽 0,旧余额仍保存在按照槽 1 推导的位置,新代码却会从按照槽 0 推导的位置读取。余额可能显示为零,尽管原始数据并未被删除。

代理升级前后存储槽错位与兼容布局示意图

使用 Foundry 检查新旧布局

下面使用 Solidity 0.8.24 编写两个示例实现。假设项目已经安装 Foundry,并采用默认 src/ 目录;两个合约均不声明父合约,因此可以直接观察变量顺序的影响。

在 src/LayoutCheck.sol 中写入:

solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract VaultV1 {
    uint256 public totalSupply;
    mapping(address => uint256) public balances;
    address public owner;
}

contract VaultV2 {
    uint256 public totalSupply;
    mapping(address => uint256) public balances;
    address public owner;

    // 新变量只能追加到原有布局之后。
    uint256 public feeBps;
}

这个示例专门用于布局检查,并非可直接部署的完整业务代理实现。真实项目应分别检查实际的新旧实现合约,包括所有继承的状态变量、存储命名空间以及编译器配置。

执行以下命令:

bash
forge build
forge inspect VaultV1 storage-layout --json > layout-v1.json
forge inspect VaultV2 storage-layout --json > layout-v2.json

预期结果:构建成功,当前目录生成两个包含 storage 和 types 等字段的 JSON 文件。可以使用以下命令查看变量的槽位与偏移:

bash
jq -r '.storage[] | [.label, .slot, .offset, .type] | @tsv' layout-v1.json
jq -r '.storage[] | [.label, .slot, .offset, .type] | @tsv' layout-v2.json

预期输出中的关键列应满足以下条件:

变量 V1 槽位 V2 槽位
totalSupply 0 0
balances 1 1
owner 2 2
feeBps 不存在 3

这里的 jq 查询只显示布局摘要。实际审计时还要比较 types 中的类型定义,尤其是结构体成员、数组元素类型和映射的键值类型,不能仅依靠变量名称判断兼容性。

识别危险的布局变更

对旧变量的基本要求是:升级后保持相同的存储位置、偏移、编码方式和业务含义。仅仅保证变量名称相同,并不足以证明升级安全。

变更方式 风险判断 处理方法
在末尾追加 uint256 通常兼容 确认没有占用保留槽或其他命名空间
调换两个 uint256 的顺序 不兼容 恢复原有顺序
将 uint256 改为 uint128 存在编码与打包风险 保持旧类型不变
在已有变量前插入字段 通常不兼容 改为末尾追加
删除中间变量后复用槽位 高风险 保留原布局,避免复用
修改结构体字段顺序 可能破坏已有数据 逐项检查结构体布局

还要特别注意继承关系。即使派生合约自身没有调整字段,新增基类状态变量、改变基类顺序也可能移动后续变量。

对于采用 ERC-7201 命名空间存储的项目,需要根据实际命名空间及其成员结构单独验证,不能直接套用从槽 0 开始的示例。使用 OpenZeppelin Upgrades 插件的项目,应在升级前执行对应的升级安全验证,而不只是比对 forge inspect 的输出。

用真实代理数据验证余额和权限

静态布局检查只能发现一部分风险。正式升级时,还应对同一个代理地址采集升级前后的链上状态,验证关键数据未发生未经授权的变化。

以下示例适用于实现合约公开 totalSupply()、balances(address) 和 owner() 查询接口的代理。它们是本课示例合约的 getter;其他项目需要替换成真实存在的业务接口,例如 ERC-20 的 balanceOf(address)。

准备一个具有 JSON-RPC 访问权限的节点,以及真实代理地址和一个已知存在余额的用户地址。将环境变量 RPC_URL、PROXY、USER_ADDRESS 设置为对应值。

创建 snapshot.sh:

bash
#!/usr/bin/env bash
set -euo pipefail

# 必须使用同一个 RPC、代理地址和查询账户。
: "${RPC_URL:?RPC_URL is required}"
: "${PROXY:?PROXY is required}"
: "${USER_ADDRESS:?USER_ADDRESS is required}"
: "${OUTPUT:?OUTPUT is required}"

# 对不同方法使用同一确定区块,防止采集中途状态变化。
BLOCK=$(cast block-number --rpc-url "$RPC_URL")
SUPPLY=$(cast call "$PROXY" 'totalSupply()(uint256)' \
  --rpc-url "$RPC_URL" --block "$BLOCK")
BALANCE=$(cast call "$PROXY" 'balances(address)(uint256)' \
  "$USER_ADDRESS" --rpc-url "$RPC_URL" --block "$BLOCK")
OWNER=$(cast call "$PROXY" 'owner()(address)' \
  --rpc-url "$RPC_URL" --block "$BLOCK")

printf 'totalSupply=%s\nbalance=%s\nowner=%s\n' \
  "$SUPPLY" "$BALANCE" "${OWNER,,}" > "$OUTPUT"

这个脚本使用 Foundry 的 cast 查询链上数据。BLOCK 固定本次快照所使用的区块,避免不同字段读取到同一次采集期间的不同状态。RPC 节点必须能读取该区块的历史状态。

在执行正式升级之前运行:

bash
OUTPUT=before.txt bash snapshot.sh

预期结果:生成 before.txt,其中依次包含 totalSupply、balance 和 owner 三个字段,数值来自真实代理,不应使用人为编造的余额代替。

随后通过项目已授权的升级流程完成实现切换。应使用经过审计的升级入口,并保留交易哈希;不能直接修改代理的底层存储槽来模拟升级。

升级完成后运行:

bash
OUTPUT=after.txt bash snapshot.sh
diff -u before.txt after.txt
echo 'Comparison completed'

在本例假设升级期间没有充值、转账、铸造、销毁、权限转移或其他预期状态变更的情况下,预期输出为:

text
Comparison completed

diff 没有打印差异且退出码为 0,表示三个查询结果完全一致;否则由于 set -e 只作用于脚本内部,外部命令会继续执行,因此应单独检查 diff 的退出状态,不能只看最后的提示文字。在自动化 CI 中应使用 diff -u before.txt after.txt 的退出码作为断言。

升级验收还需要检查什么

可以按以下顺序完成一次可追溯的升级验收:

  1. 保存旧实现地址、代理地址、链 ID、旧编译产物及其存储布局。
  2. 对比新旧布局,确认已有变量的槽位、偏移和类型定义兼容。
  3. 使用真实链状态建立升级前快照,覆盖总供应量、典型用户余额和核心权限。
  4. 在主网分叉环境中调用实际升级入口,检查升级交易及初始化调用的执行结果。
  5. 升级后读取同一代理地址,验证不应改变的数据与升级前一致。
  6. 验证新增变量初始值与初始化结果,并检查权限主体和升级授权规则。
  7. 保存新实现地址、升级交易哈希、快照差异和自动化测试报告。

对于透明代理,还应检查 ProxyAdmin 或等效升级管理权限;对于 UUPS 实现,应验证 _authorizeUpgrade 对应的授权约束。若使用 AccessControl,应逐项检查真实角色成员和角色管理员关系,而不能只比较 owner()。

此外,升级后的新实现可能包含合法的数据迁移逻辑。此时应明确写出迁移前后的预期值与守恒条件,例如总余额是否保持、费率是否正确初始化,以及是否发生重复初始化。

只要存储布局存在无法解释的变化,或真实代理中的关键余额、权限出现非预期差异,就应停止正式升级,修正实现或设计明确的数据迁移方案后重新验证。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

比对升级前后存储布局

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通