第四部分 · 可升级合约

UBOX V3:面额重标

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

把「缩小 4 个 0」做成合约升级:能改的是从现在起的记账,改不了的是已经写进历史的日志。

目标与难点

V3 要做的事:让 10,000 个旧 UBOX = 1 个新 UBOX。

难点在于 ERC-20 没有可以枚举的持有人名单。如果写死「把 A、B 的余额各除以 10,000」,会漏掉以后出现的持有人,还容易破坏「余额之和 = 总供应」这个不变量。

设计:全局缩放

  • 内部的原始余额仍按旧单位存放,不重写任何存储。
  • 新增一个全局系数 scale = 10000,放在原有 __gap(slot 8–57)之后的 slot 58,不重排旧的存储槽。
  • balanceOf / totalSupply / allowance 返回「原始值 ÷ 10,000」。
  • transfer / approve / burn 和 V2 的批量函数都按新单位工作:传入 1e18 表示 1 个新币,实际扣 10,000 倍的原始量。
  • decimals() 仍然是 18。用户直接读 balanceOf() 就能看到新数字。

另一种没有采用的做法是把 decimals() 改成 22:钱包显示也会缩小 10,000 倍,但 balanceOf() 仍然返回旧的原始数。本次希望一读 balanceOf() 就是新数字。

左边是代理存储中的原始值(旧单位):A 999,900e18、B 100e18、总供应 1,000,000e18;除以 scale 10000 后,右边读出 A 99.99、B 0.01、总供应 100,decimals 仍为 18。下方警告:历史 Transfer 日志仍是旧单位,若按新单位读会大 10,000 倍。
图 6|

存储不改写,读出时统一除以 scale。历史日志是旧单位,不会被改写。

在新窗口打开大图

一次性的 initializeV3

  • V1 的 initialize() 已经把 _initialized 设成 1,而且 V1 没有使用 OpenZeppelin 的 Initializable,所以这里不是 reinitializer(2),而是检查 _scale == 0 后写入 _scale = 10000。
  • 它不得再调用 V1 的 initialize,也不铸币、不转账。
  • V3 实现的构造函数会在实现合约自己的存储里先把 _scale 锁上,防止有人直接对实现合约做初始化。
  • 为了让 V3 能覆盖 balanceOf 等 getter,V1 的源码把原来的 public 变量改成了同槽位的 internal 变量加 virtual 函数。这不改变存储布局,也不改变已经部署的 V1/V2 字节码——但它让「当前源码」不再能精确复现历史 V1/V2(第 15 章会看到后果)。

上链:只有两笔交易

nonce 时间(新加坡) 操作 交易 区块 gas used 手续费(wei)
17 2026-11-12 14:23:00 部署 V3 实现 在 Sepolia Etherscan 查看交易(新窗口打开): 0xad0fd9cbb6c1c9ef9df16ab039d1dfa54eac7c95327c976ac961fcfcbe6f28f9 12117040 14,639,984 1,010,158,896
18 14:23:12 upgradeAndCall(initializeV3) 在 Sepolia Etherscan 查看交易(新窗口打开): 0x5765d84eaff6cab6851f4c3dd7675dae11cf54c7514e084a9a054db9a89295f1 12117041 156,185 10,776,765

升级交易发出了 Upgraded(V3) 和 Redenominated(10000) 两个事件,没有任何 Transfer 事件——确认没有铸币、没有转账。initializeV3() 只运行了这一次。两笔的 gasUsed 都与升级前的模拟完全一致。

快照:通过代理读取(新单位)

字段 原始返回值 含义
name / symbol 可升级沙盒代币 / UBOX —
decimals 18 没有改
totalSupply 100000000000000000000 100 UBOX
balanceOf(A) 99990000000000000000 99.99 UBOX
balanceOf(B) 10000000000000000 0.01 UBOX
scale 10000 10,000 旧 = 1 新
实现 V3 0x16E3D2f25e28253b467C66c462973e4ca86fad28 V4 未上链

换算示例:A 的原始余额 999,900e18 ÷ 10,000 = 99.99e18。99.99 + 0.01 = 100。

模拟里还试过「A 转 1 个新 UBOX 给 B」(会变成 A 98.99、B 1.01,供应仍 100)——那笔演示转账没有被授权广播,链上并不存在。

历史事件不会被改写

这是本章最重要的一点:

  • 第 12 章成功批次里「100 给 B」的 Transfer 日志,记录的是旧单位的 100e18。
  • 重标之后,B 的 balanceOf 是 0.01。
  • 如果有人把那条旧日志按新单位去读,就会以为 B 收到了 100——偏大 10,000 倍。

面额重标能改的是从现在起的记账和新事件的单位,不能改写已经上链的旧日志,也不能决定任何市场价格。读历史数据时,必须按「升级前/升级后」的分界分别换算。

粉尘与发现

  • 粉尘:不能被 10,000 整除的原始余额,在显示层会被截断,看起来是 0 却转不出去(P0 记为 Low 级 F-V3-002、F-V3-003)。快照时已知持有人的原始余额都能被 10,000 整除,所以这个问题不影响当前持有人。
  • Medium 级发现 F-V3-001:approve(spender, type(uint256).max) 会回退 "amount overflow",因为 value × 10000 溢出了;V3 没有「无限授权」的哨兵值。很多协议依赖这种 max 授权,所以不要把 UBOX 接入依赖 max approve 的协议。它是兼容性和数值边界问题,不是资产已经受损;快照时链上 UBOX 的授权都是 0。