不可变的合约如何「升级」？聊聊 Solidity 合约升级模式

Mon, 02 Sep 2024 20:00:00 +0800

一个让所有以太坊新手都困惑的悖论

智能合约最被反复强调的特性，是 不可变（immutable）——代码部署上链之后，一行都不能改。

但你只要在生产里跑过几个月就会发现一个现实：

代码会有 bug
业务会有新需求
协议会被攻击，要打补丁

这两件事看起来根本是矛盾的——承诺不可变，又必须能改。

整个"合约升级"这个话题，本质上就是在回答：怎么在不破坏不可变承诺的前提下，让合约的行为可以演进？

下面我们从最朴素的方案开始，一路讲到现在主流的代理模式、UUPS、Beacon、Diamond，把这些方案的来龙去脉、踩坑点和适用边界一次性讲清楚。

一、最朴素的方案：合约迁移（Contract Migration）

最直观的思路：既然合约不能改，那就部署一份新的。

流程大致是：

部署 TokenV2
写一个迁移脚本，把 TokenV1 上每个用户的余额读出来，写进 TokenV2
通知所有依赖方（前端、其他合约、CEX、用户）：地址换了，请用新的

这条路在小协议里偶尔还会用到，但作为通用方案，它的痛点很硬：

地址变了——所有依赖你的合约和应用都要改地址。DeFi 里这意味着流动性池要重建、用户授权要重做，几乎等于一次"硬分叉"。
状态迁移成本高——用户多的时候，光迁移就要几十万美元 Gas，且过程中可能有人在动账。
信任成本极高——用户怎么相信新合约里的余额没被篡改？

所以业界很快意识到：迁移不是"升级"，是"换房"。真正的升级，应该让地址不变、状态延续，只换"大脑"。

二、核心技巧：`delegatecall` 与代理模式

要做到"地址不变换大脑"，离不开 EVM 提供的一个特殊指令——delegatecall。

一句话理解 `delegatecall`

普通调用 call：用别人的代码、操作别人的存储。 delegatecall：用别人的代码、操作自己的存储。

也就是说，合约 A 通过 delegatecall 调合约 B 的某个函数时，执行的是 B 的字节码，但 msg.sender、msg.value、所有存储读写都发生在 A 上。

这就给了我们一个大胆的想法——

让一个只负责存数据的合约（Proxy），通过 delegatecall 把所有调用都转发给另一个只负责跑逻辑的合约（Logic）。

升级时只需要把 Proxy 指向的 Logic 地址换掉，Proxy 的地址和存储完全不变。

关系图

flowchart LR
 User([用户 / DApp])
 Proxy["Proxy 合约
(地址不变 + 存储)"]
 LogicV1["Logic V1
(纯代码)"]
 LogicV2["Logic V2
(升级后)"]

 User -- 调用 --> Proxy
 Proxy -- delegatecall --> LogicV1
 Proxy -. 升级后改指向 .-> LogicV2

一个最小可运行的代理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


contract MinimalProxy {
 address public implementation; // 当前指向的逻辑合约
 address public admin;

 constructor(address _impl) {
 implementation = _impl;
 admin = msg.sender;
 }

 function upgrade(address _newImpl) external {
 require(msg.sender == admin, "not admin");
 implementation = _newImpl;
 }

 fallback() external payable {
 address impl = implementation;
 assembly {
 calldatacopy(0, 0, calldatasize())
 let result := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
 returndatacopy(0, 0, returndatasize())
 switch result
 case 0 { revert(0, returndatasize()) }
 default { return(0, returndatasize()) }
 }
 }
}

fallback 把任何调用都 delegatecall 到 implementation。换 implementation 就等于升级。

看起来挺优雅，但魔鬼藏在细节里——存储布局。

三、升级最大的坑：存储布局冲突

delegatecall 操作的是 Proxy 的存储，但用的是 Logic 的代码。这就要求两件事：

Logic 合约里读写哪个存储槽，必须和 Proxy 里实际的存储槽对得上
升级前后两版 Logic 之间，存储槽不能错位

举个例子。假设 Logic V1 是这样：

1
2
3
4


contract LogicV1 {
 address public owner; // slot 0
 uint256 public totalSupply; // slot 1
}

某天我们想升级，写了个看起来合情合理的 V2：

1
2
3
4
5


contract LogicV2 {
 uint256 public totalSupply; // slot 0 ← 和 V1 的 owner 撞了！
 address public owner; // slot 1
 uint256 public newField; // slot 2
}

升级完，原来 owner 的位置被当成了 totalSupply，瞬间把一个地址解读成天文数字的代币总量——协议直接报废。

三条铁律

不能删除已有变量
不能调整变量顺序
不能改变量类型（包括 uint256 ↔ int256、定长数组长度等）

新版本想加字段？只能在末尾追加。

Storage Gap 习惯（OpenZeppelin 4.x 时代的做法）

时效性更新：本节描述的 __gap 模式是 OpenZeppelin 4.x 的标准做法。OpenZeppelin 5.0（2023-10）起的 contracts-upgradeable 包已经改用 ERC-7201 命名空间存储（Namespaced Storage Layout）——每个合约的 storage 字段被收进一个独立 struct，slot 从 keccak256(namespace) - 1 派生，* *升级加字段不再受顺序约束，也不再需要预留 __gap**。新项目应该直接用 ERC-7201；老项目从 __gap 模式迁移到 ERC-7201 时要小心 storage layout 兼容。下面这段 __gap 写法仍然适用于 4.x 的基类继承场景（与 4.x 升级链路向后兼容）。

为了给未来"末尾追加"留余地，可继承的基类里通常会预留一段空槽：

1
2
3
4
5
6
7


contract MyUpgradeable {
 address public owner;
 uint256 public totalSupply;
 // ... 业务字段

 uint256[50] private __gap; // 给未来升级留 50 个槽
}

这是 OpenZeppelin 4.x 的标准做法。一旦未来要在基类加字段，就从 __gap 里"借"——既不破坏子类的存储布局，又不需要 fork 一份父类。

ERC-7201 的等价写法长这样（5.0+）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


contract MyUpgradeable {
 /// @custom:storage-location erc7201:myproject.storage.MyUpgradeable
 struct MyStorage {
 address owner;
 uint256 totalSupply;
 // ... 业务字段
 }

 // keccak256(abi.encode(uint256(keccak256("myproject.storage.MyUpgradeable")) - 1)) & ~bytes32(uint256(0xff))
 bytes32 private constant STORAGE_SLOT =
 0x...;

 function _s() private pure returns (MyStorage storage s) {
 bytes32 slot = STORAGE_SLOT;
 assembly { s.slot := slot }
 }
}

每个合约把自己的 storage 锁进独立命名空间——升级时加字段、调顺序、改基类继承都不会再撞槽。这是 5.x 在升级模型上最关键的一步。

升级前一定要做 storage layout 校验

存储布局错位的检查靠人肉是不现实的——升级链路必须有自动化校验把这个关。具体工具按你用的栈选：

Hardhat 栈：OpenZeppelin Upgrades Plugin（ @openzeppelin/hardhat-upgrades）——升级前自动比对两版合约的存储布局，不兼容直接报错挡住。
Foundry 栈：openzeppelin-foundry-upgrades，或者直接 forge inspect <Contract> storageLayout 把新旧两版的 storage layout 输出成 JSON，在 CI 里做 diff。
更通用：Slither 的 slither-check-upgradeability 也能做静态布局比对。

形式不重要——一定要有一道自动检查。生产合约靠肉眼 review storage layout 早晚出事。

四、三种主流代理标准

代理模式发展到今天，演化出了三种主流形态。

1. Transparent Proxy（透明代理）

OpenZeppelin 早期推荐。它的核心问题是解决一个微妙的冲突——

如果 Proxy 自己有个函数叫 upgrade()，Logic 里也有个函数叫 upgrade()，用户调进来时到底是哪个执行？

Transparent Proxy 的解法是按调用者区分：

管理员调用 → 永远走 Proxy 自己的管理函数
普通用户调用 → 永远走 delegatecall 到 Logic

flowchart LR
 Admin([管理员]) -->|管理调用| ProxyAdmin["Proxy
(管理逻辑)"]
 User([普通用户]) -->|业务调用| ProxyDelegate["Proxy
(delegatecall)"]
 ProxyDelegate --> Logic["Logic 合约"]

简单可靠，但代价是 Proxy 里要存管理员判断逻辑，每次调用都多一次条件判断和 SLOAD，Gas 偏贵。

2. UUPS（ERC-1822，OZ 现在的默认推荐）

UUPS 的核心反转是——把升级逻辑搬进 Logic 合约。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


contract LogicUUPS {
 address public owner;

 function upgradeTo(address newImpl) external {
 require(msg.sender == owner, "not owner");
 // 通过 delegatecall 改的是 Proxy 自己的 implementation 槽
 assembly { sstore(_IMPL_SLOT, newImpl) }
 }
 // ... 其他业务函数
}

这样一来：

Proxy 极度精简，只有一个 fallback，Gas 最省
升级权限由 Logic 控制——这意味着 如果你升级到一个忘了写 upgradeTo 的新 Logic，合约就永远没法再升级了（一种" 自爆开关"）

OpenZeppelin 现在更推荐 UUPS，但前提是开发者必须严格遵守"新版本永远要继承 UUPSUpgradeable“的规范，否则可能误锁死。

3. Beacon Proxy（信标代理）

前两种都是"一个 Proxy 对应一个 Logic”。如果你有 几百上千个同种合约（比如 Uniswap V3 工厂创建的众多池子），每次升级要逐一调用，成本难以承受。

Beacon Proxy 抽象出一个信标合约：

flowchart LR
 Beacon["Beacon
(只存当前 Logic 地址)"]
 Logic["Logic 合约"]

 P1["Pool Proxy 1"] -.读地址.-> Beacon
 P2["Pool Proxy 2"] -.读地址.-> Beacon
 P3["Pool Proxy ..."] -.读地址.-> Beacon

 P1 -.delegatecall.-> Logic
 P2 -.delegatecall.-> Logic
 P3 -.delegatecall.-> Logic

 Beacon -. 指向 .-> Logic

所有 Proxy 都从 Beacon 读"当前 Logic 地址"。升级时只改 Beacon 一处，所有 Proxy 同时生效。代价是每次调用多一次跨合约读地址的 Gas。

方案	Gas 开销	升级权限位置	适用场景
Transparent Proxy	较高	Proxy	单实例、追求稳定保守
UUPS	最低	Logic	单实例、追求性能（OZ 默认推荐）
Beacon Proxy	中等	Beacon	多实例、需要批量同步升级

五、更激进的方案：Diamond（EIP-2535）

EVM 对单个合约的字节码大小有 24KB 的硬上限（EIP-170）。当协议复杂到一个 Logic 合约塞不下时，前面那些"单 Logic" 的代理模式就不够用了。

Diamond 模式的思路是——一个 Proxy（Diamond），多个 Logic（Facet），按函数选择器路由。

flowchart TB
 User([用户调用])
 Diamond["Diamond Proxy
(查路由表 + delegatecall)"]
 F1["Facet A
转账逻辑"]
 F2["Facet B
治理逻辑"]
 F3["Facet C
奖励逻辑"]
 F4["Facet ...
(可动态增删)"]

 User --> Diamond
 Diamond -- delegatecall --> F1
 Diamond -- delegatecall --> F2
 Diamond -- delegatecall --> F3
 Diamond -- delegatecall --> F4

每个 Facet 只实现一部分函数，Diamond 内部维护一张 selector → facet address 的路由表，调用进来时查表然后 delegatecall 。升级时可以按 facet 增、删、换，粒度比单 Logic 细得多。

代价是复杂度陡升——存储布局要按"Diamond Storage"的命名空间约定写、调试链路更长、对应工具链不如 OZ 主流模式成熟。* 不是协议规模真的超过单合约能力，不要轻易上 Diamond*（Aavegotchi 是公认上得最成功的案例之一）。

六、不能忽略的工程细节

1. 没有 constructor，只有 initializer

constructor 在合约部署时执行，只对 Logic 自己的存储生效，不会写到 Proxy 的存储。所以可升级合约的初始化必须放在一个普通函数里，靠 只能调用一次的修饰符保护：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


contract MyLogic {
 bool private initialized;
 address public owner;

 function initialize(address _owner) external {
 require(!initialized, "already initialized");
 initialized = true;
 owner = _owner;
 }
}

OpenZeppelin 提供了 Initializable 基类，标准做法是用 initializer 修饰符。

2. 部署后立刻调用 initializer

如果部署完 Logic 不立刻初始化，任何人都可以抢先调一次 initialize 把自己设成 owner。这种漏洞历史上发生过多次。脚本部署 Proxy 时要用 atomicallyDeployAndInitialize 之类的封装，把"部署 + 初始化"放进同一个交易。

3. 升级权限 = 协议生死开关

控制 upgrade 的私钥，等于握有协议的全部资金权。任何成熟协议都会用：

多签：避免单点泄密
Timelock：提案到生效之间留出延迟（通常 24~72 小时），让用户有撤资时间
DAO 治理投票：进一步去中心化，把升级决策交给代币持有者

如果你看到一个号称"去中心化"的协议，升级权在一把单签钥匙上——它在技术上和中心化产品没有任何区别。

七、可升级的代价：安全与去中心化的张力

可升级合约的存在，本身就违反了"不可变"的初心。

管理员可以悄悄换掉 Logic，把所有用户的资金转走——这是真实发生过的攻击。
审计的难度被放大：用户审计了今天的代码，明天升级后等于审了个寂寞。
形式化验证、不可变指标都失效：协议的安全保证从"代码"层退化为"运营方信誉 + 治理流程"层。

所以业界有一种相反的声音：真正成熟的协议应当逐步放弃可升级性。Uniswap V2/V3 的核心合约就是不可升级的——它的迭代靠" 部署新协议、用户自愿迁移"完成，代价高，但换来了最强的信任。

作为协议设计者，你需要问自己：

“这个合约的升级权，是不是协议安全的天花板？”

如果答案是"是"，那就要尽一切努力收紧它——多签、Timelock、治理、最终弃管。

作为协议用户，你也要学会问：

“这个合约能升级吗？升级权在谁手里？有 Timelock 吗？”

回答不出来的协议，本质上就是一个许可型应用，无论它前端多花哨。

小结

把这一整圈讲下来，回到最初那个悖论——

智能合约的不可变是承诺，但现实的演进是必需。升级模式就是在两者之间做工程妥协的产物。

四种主流方案的本质：

合约迁移：放弃地址不变，老老实实换房
Transparent Proxy / UUPS：地址不变，靠 delegatecall 把存储和代码解耦
Beacon Proxy：多个 Proxy 共享一个 Logic 指针，批量升级
Diamond：突破合约大小上限，按 facet 灵活增删

而无论用哪种方案，真正的难点从来不是合约怎么写，而是升级权怎么管。技术层面可升级是简单的，治理层面让用户敢用一个可升级的合约，才是更难、也更重要的命题。

一句话收尾：

可升级是工程能力，不可升级是产品承诺，怎么在两者之间找平衡，是每一个协议设计者要回答的问题。

代理模式 on 牛哥聊技术