第四部分 · 可升级合约

可升级的 UBOX:代理、V1 与 V2

整理:Kang页面发布:链上快照:,区块 12117419

用「店铺门牌地址不变,后台收银系统更换」来理解代理(Proxy)。

可升级必须在部署时就设计好

第 8、9 章看到:普通合约一旦部署,逻辑就冻在那个地址上。UBOX 从一开始就用了代理模式,把「用户永远调用的地址」固定为代理,把逻辑放在可替换的实现合约里。

采用的是 OpenZeppelin 5.6.1 的 TransparentUpgradeableProxy 和 ProxyAdmin,没有自己写代理,便于对照官方的存储槽规范(ERC-1967)和升级接口。

用户调用固定的 UBOX 代理地址,代理保存余额等存储,并通过 delegatecall 执行当前实现 V3;V1、V2 的代码仍在但已不被指向;V4 只在本地。ProxyAdmin 的 owner 是账户 A,可调用 upgradeAndCall 更换实现。
图 5|

用户访问固定的代理;代理用实现合约的代码、在自己的存储上运行;升级权由 ProxyAdmin 控制。

在新窗口打开大图
  • 代理保存所有状态:余额、授权、名称……用户、钱包和其他合约都只认这个地址。
  • 实现合约只提供代码。代理用 delegatecall 借用它的代码,但读写的是代理自己的存储。
  • ProxyAdmin 是唯一能让代理换实现的合约,它的 owner 是账户 A。

initialize 不是构造函数

构造函数只会写进实现合约自己的存储,不会写进代理。所以可升级合约改用一个普通函数 initialize() 来设定名称、供应和 owner,并通过代理调用一次。它必须只能执行一次——再执行一次,可能重新铸币或改掉 owner。

第一步:部署 V1 与代理(当时不部署 V2)

代币名称 可升级沙盒代币,符号 UBOX,18 位小数,initialize 后 1,000,000 枚全部铸给 A。三个地址都与按 A 的 nonce 11、12 预测的一致;ProxyAdmin 由代理的构造过程创建,不额外消耗 A 的 nonce。

nonce 时间(新加坡) 操作 交易 区块 gas used 手续费(wei)
11 2026-11-12 11:12:24 部署 V1 实现 在 Sepolia Etherscan 查看交易(新窗口打开): 0xdf571b52c1d2c323b1ef40bb8305c62be7f447fa605a758f5137334c38cacd66 12116097 10,625,841 701,305,506
12 11:12:36 部署代理并 initialize 在 Sepolia Etherscan 查看交易(新窗口打开): 0xaeb0216f26dfe3270faf68bb4b280ab61e763b371f869d989061205f5a9bb0db 12116098 7,451,338 491,788,308

模拟阶段遇到并修正过三个问题(都发生在广播之前):中文名必须用 unicode"...";_initialized 起初是 bool,会和 owner 打包进同一个存储槽,导致按「各占一槽」写入的模拟读到错乱数据,后来改成单独占用 slot 0 的 uint256;在同一次模拟里连续创建两个合约时,要把 nonce 设成「V1 已部署之后」的值,否则会碰到 CreateCollision。

第二步:升级到 V2(不再调用 initialize)

V2 不新增状态变量、不重排存储,只增加原子的 batchTransfer / batchTransferFrom(第 12 章用的就是它们)。

nonce 时间(新加坡) 操作 交易 区块 gas used 手续费(wei)
13 2026-11-12 11:56:36 部署 V2 实现 在 Sepolia Etherscan 查看交易(新窗口打开): 0xcc60956bd0b5b285ec61ca2eaaf6c074df07b92f50303c5e7112fba58ad71878 12116317 12,703,689 838,443,474
14 11:57:00 upgradeAndCall(…, 0x) 在 Sepolia Etherscan 查看交易(新窗口打开): 0x91e5ec0b662fa6622841386e81b410cafe5ef2a433fba8fe309e30093990cb61 12116319 41,724 2,753,784

升级后名称、供应、余额、owner 全部不变,代理地址也不变:仍是 0xc3F20D5488784D922aC3428a54125715fA98db04。升级交易本身只用了 41,724 gas,远少于重新部署一整套代理——这就是「地址和状态保留、只换逻辑」的好处。

所有升级都留在链上

  • 升级是普通的链上交易:有哈希、消耗 gas,发出 Upgraded 事件,并改写 ERC-1967 实现槽。没有「静默升级」。
  • 旧的 V1 代码仍然留在原地址上,只是代理不再指向它。
  • 模拟时用的 stateOverride 只是在本地「假装」链上已有某段代码或存储,不会改变真实的链。

双刃剑

  • 好处:修 bug 或加功能时,用户不必更换所有对接地址。
  • 代价:管理员权限如果被盗或被滥用,可能改变应用之后执行的规则(包括转账规则,理论上甚至 name() 的返回值)。
  • 技术风险:新版本的存储布局如果不兼容(重排、插入变量),会把旧数据「读错位置」。规则是只追加、不重排。
  • 治理问题:谁有升级权?是不是多签?有没有延迟、公告和退出机制?

在本实验里,ProxyAdmin 的 owner 是单个测试账户 A——这是一个明确接受的教学模型,不是去中心化发行。