Part IV · Upgradeable contracts
UBOX V3: redenomination
“Knock four zeros off” as a contract upgrade: you can change the bookkeeping from now on, but not the logs already written into history.
Goal and difficulty
V3’s job: make 10,000 old UBOX = 1 new UBOX.
The difficulty is that ERC-20 has no list of holders you can enumerate. Hard-coding “divide A’s and B’s balances by 10,000” would miss any future holder and could easily break the invariant “sum of balances = total supply”.
Design: a global scale
- Raw balances stay stored in old units; no storage is rewritten.
- A new global factor
scale = 10000lives in slot 58, after the existing__gap(slots 8–57), without reordering any old slot. balanceOf/totalSupply/allowancereturn “raw value ÷ 10,000”.transfer/approve/burnand V2’s batch functions all work in new units: passing 1e18 means one new token, and 10,000 times as many raw units are moved.decimals()stays 18. ReadingbalanceOf()directly shows the new number.
An alternative that was not chosen: change decimals() to 22. Wallets would also display amounts 10,000 times smaller, but balanceOf() would still return the old raw number. The goal here was for balanceOf() itself to show the new figure.
Storage is not rewritten; every read divides by the scale. Historical logs stay in old units and are never rewritten.
Open the full-size diagram in a new tabA one-time initializeV3
- V1’s
initialize()had already set_initializedto 1, and V1 does not use OpenZeppelin’sInitializable, so this is notreinitializer(2): it checks_scale == 0and then writes_scale = 10000. - It must not call V1’s
initializeagain, and it neither mints nor transfers. - The V3 implementation’s constructor locks
_scalein the implementation’s own storage, so nobody can initialise the implementation directly. - So that V3 could override getters such as
balanceOf, the V1 source turned the original public variables into internal variables in the same slots plus virtual functions. That changes neither the storage layout nor the already-deployed V1/V2 bytecode, but it means the current source no longer reproduces the historical V1/V2 exactly (Chapter 15 shows the consequence).
On-chain: just two transactions
- V3 implementation (exactly as predicted at nonce 17): View address on Sepolia Etherscan (opens in a new tab): 0x16E3D2f25e28253b467C66c462973e4ca86fad28
- The proxy address did not change; the implementation slot now points to V3.
| Nonce | Time (Singapore) | Action | Transaction | Block | Gas used | Fee (wei) |
|---|---|---|---|---|---|---|
| 17 | 2026-11-12 14:23:00 | Deploy V3 implementation | View transaction on Sepolia Etherscan (opens in a new tab): 0xad0fd9cbb6c1c9ef9df16ab039d1dfa54eac7c95327c976ac961fcfcbe6f28f9 | 12117040 | 14,639,984 | 1,010,158,896 |
| 18 | 14:23:12 | upgradeAndCall(initializeV3) | View transaction on Sepolia Etherscan (opens in a new tab): 0x5765d84eaff6cab6851f4c3dd7675dae11cf54c7514e084a9a054db9a89295f1 | 12117041 | 156,185 | 10,776,765 |
The upgrade emitted Upgraded(V3) and Redenominated(10000) and no Transfer event at all, confirming nothing was minted or moved. initializeV3() ran exactly once. Both transactions used exactly the gas predicted by the pre-upgrade simulation.
Snapshot: read through the proxy (new units)
| Field | Raw return value | Meaning |
|---|---|---|
| name / symbol | 可升级沙盒代币 / UBOX | — |
| decimals | 18 | Unchanged |
| totalSupply | 100000000000000000000 | 100 UBOX |
| balanceOf(A) | 99990000000000000000 | 99.99 UBOX |
| balanceOf(B) | 10000000000000000 | 0.01 UBOX |
| scale | 10000 | 10,000 old = 1 new |
| Implementation | V3 0x16E3D2f25e28253b467C66c462973e4ca86fad28 |
V4 not on-chain |
Worked example: A’s raw balance 999,900e18 ÷ 10,000 = 99.99e18. And 99.99 + 0.01 = 100.
The simulation also tried “A sends 1 new UBOX to B” (which would give A 98.99, B 1.01, supply still 100). That demo transfer was never authorised for broadcast and does not exist on-chain.
Historical events are not rewritten
This is the most important point of the chapter:
- The
Transferlog for “100 to B” in Chapter 12’s successful batch records 100e18 in old units. - After the redenomination, B’s
balanceOfis 0.01. - Anyone who reads that old log as new units will think B received 100: 10,000 times too much.
A redenomination changes the bookkeeping and the unit of new events from now on. It cannot rewrite logs already on-chain, and it cannot set any market price. When reading historical data, convert separately on each side of the upgrade.
Dust and findings
- Dust: raw balances that are not multiples of 10,000 are truncated for display, so they look like 0 yet cannot be moved (recorded in P0 as Low findings F-V3-002 and F-V3-003). At the snapshot every known holder’s raw balance was divisible by 10,000, so this does not affect current holders.
- Medium finding F-V3-001:
approve(spender, type(uint256).max)reverts with"amount overflow"becausevalue × 10000overflows; V3 has no “infinite allowance” sentinel. Many protocols rely on max approvals, so do not plug UBOX into a protocol that depends on max approve. It is a compatibility and numeric-boundary issue, not damaged assets; at the snapshot all UBOX allowances on-chain were 0.