智能合约与以太坊 / 系统课时
比对升级前后存储布局
比对升级前后存储布局
升级代理合约时,即使新实现能够编译并成功部署,也可能因状态变量位置变化而破坏用户余额或管理员权限。本文使用 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 中写入:
// 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;
}这个示例专门用于布局检查,并非可直接部署的完整业务代理实现。真实项目应分别检查实际的新旧实现合约,包括所有继承的状态变量、存储命名空间以及编译器配置。
执行以下命令:
forge build
forge inspect VaultV1 storage-layout --json > layout-v1.json
forge inspect VaultV2 storage-layout --json > layout-v2.json预期结果:构建成功,当前目录生成两个包含 storage 和 types 等字段的 JSON 文件。可以使用以下命令查看变量的槽位与偏移:
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:
#!/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 节点必须能读取该区块的历史状态。
在执行正式升级之前运行:
OUTPUT=before.txt bash snapshot.sh预期结果:生成 before.txt,其中依次包含 totalSupply、balance 和 owner 三个字段,数值来自真实代理,不应使用人为编造的余额代替。
随后通过项目已授权的升级流程完成实现切换。应使用经过审计的升级入口,并保留交易哈希;不能直接修改代理的底层存储槽来模拟升级。
升级完成后运行:
OUTPUT=after.txt bash snapshot.sh
diff -u before.txt after.txt
echo 'Comparison completed'在本例假设升级期间没有充值、转账、铸造、销毁、权限转移或其他预期状态变更的情况下,预期输出为:
Comparison completeddiff 没有打印差异且退出码为 0,表示三个查询结果完全一致;否则由于 set -e 只作用于脚本内部,外部命令会继续执行,因此应单独检查 diff 的退出状态,不能只看最后的提示文字。在自动化 CI 中应使用 diff -u before.txt after.txt 的退出码作为断言。
升级验收还需要检查什么
可以按以下顺序完成一次可追溯的升级验收:
- 保存旧实现地址、代理地址、链 ID、旧编译产物及其存储布局。
- 对比新旧布局,确认已有变量的槽位、偏移和类型定义兼容。
- 使用真实链状态建立升级前快照,覆盖总供应量、典型用户余额和核心权限。
- 在主网分叉环境中调用实际升级入口,检查升级交易及初始化调用的执行结果。
- 升级后读取同一代理地址,验证不应改变的数据与升级前一致。
- 验证新增变量初始值与初始化结果,并检查权限主体和升级授权规则。
- 保存新实现地址、升级交易哈希、快照差异和自动化测试报告。
对于透明代理,还应检查 ProxyAdmin 或等效升级管理权限;对于 UUPS 实现,应验证 _authorizeUpgrade 对应的授权约束。若使用 AccessControl,应逐项检查真实角色成员和角色管理员关系,而不能只比较 owner()。
此外,升级后的新实现可能包含合法的数据迁移逻辑。此时应明确写出迁移前后的预期值与守恒条件,例如总余额是否保持、费率是否正确初始化,以及是否发生重复初始化。
只要存储布局存在无法解释的变化,或真实代理中的关键余额、权限出现非预期差异,就应停止正式升级,修正实现或设计明确的数据迁移方案后重新验证。