Part IV · Upgradeable contracts
Upgradeable UBOX: proxy, V1 and V2
Think of a proxy as “the shop’s street address stays the same while the back-office till system is replaced”.
Upgradeability must be designed in at deployment
Chapters 8 and 9 showed that once an ordinary contract is deployed, its logic is frozen at that address. UBOX used a proxy pattern from the start: the address users always call is fixed as the proxy, and the logic lives in a replaceable implementation contract.
It used OpenZeppelin 5.6.1’s TransparentUpgradeableProxy and ProxyAdmin rather than a home-made proxy, so the storage slots (ERC-1967) and upgrade interface can be checked against the official ones.
Users talk to a fixed proxy; the proxy runs the implementation’s code against its own storage; upgrade power sits with ProxyAdmin.
Open the full-size diagram in a new tab- The proxy holds all the state: balances, allowances, the name… Users, wallets and other contracts only know this address.
- The implementation only provides code. The proxy borrows it with
delegatecall, but reads and writes the proxy’s own storage. - ProxyAdmin is the only contract that can point the proxy at a new implementation. Its owner is account A.
initialize is not a constructor
A constructor only writes into the implementation contract’s own storage, never into the proxy. So upgradeable contracts use an ordinary function, initialize(), to set the name, supply and owner, called once through the proxy. It must be callable only once; running it again might mint again or change the owner.
Step 1: deploy V1 and the proxy (no V2 yet)
| Role | Address |
|---|---|
| Proxy (the token address users use) | View address on Sepolia Etherscan (opens in a new tab): 0xc3F20D5488784D922aC3428a54125715fA98db04 |
| V1 implementation | View address on Sepolia Etherscan (opens in a new tab): 0xdaBaDC03042B010eFF67Bf2553798d75e817300a |
| ProxyAdmin (owner: account A) | View address on Sepolia Etherscan (opens in a new tab): 0x6DEAe6C7fAa9fabe1983082277922CDcf90BBEE9 |
Token name 可升级沙盒代币 (“upgradeable sandbox token”), symbol UBOX, 18 decimals; after initialize all 1,000,000 were minted to A. All three addresses matched the predictions from A’s nonces 11 and 12; ProxyAdmin is created inside the proxy’s constructor and does not use one of A’s nonces.
| Nonce | Time (Singapore) | Action | Transaction | Block | Gas used | Fee (wei) |
|---|---|---|---|---|---|---|
| 11 | 2026-11-12 11:12:24 | Deploy V1 implementation | View transaction on Sepolia Etherscan (opens in a new tab): 0xdf571b52c1d2c323b1ef40bb8305c62be7f447fa605a758f5137334c38cacd66 | 12116097 | 10,625,841 | 701,305,506 |
| 12 | 11:12:36 | Deploy proxy and initialize | View transaction on Sepolia Etherscan (opens in a new tab): 0xaeb0216f26dfe3270faf68bb4b280ab61e763b371f869d989061205f5a9bb0db | 12116098 | 7,451,338 | 491,788,308 |
Three problems came up and were fixed during simulation, all before broadcasting: the Chinese name needs unicode"..."; _initialized was first a bool, which the compiler packed into the same storage slot as owner, so a simulation that wrote “one variable per slot” read garbage, and it became a uint256 alone in slot 0; and when simulating two contract creations in a row, the nonce has to be set to “after V1 is deployed”, or you hit CreateCollision.
Step 2: upgrade to V2 (without calling initialize again)
V2 adds no state variables and does not reorder storage. It only adds the atomic batchTransfer / batchTransferFrom used in Chapter 12.
- V2 implementation: View address on Sepolia Etherscan (opens in a new tab): 0x0711Ef7C97b061fd3C87026ad38703dd253E779F
- A upgraded via
ProxyAdmin.upgradeAndCall(proxy, V2, 0x)with empty calldata0x: initialize was not called again and no transfer was made. V1’s initialize had already run; calling it again would fail with “already initialized” and could even trigger minting logic.
| Nonce | Time (Singapore) | Action | Transaction | Block | Gas used | Fee (wei) |
|---|---|---|---|---|---|---|
| 13 | 2026-11-12 11:56:36 | Deploy V2 implementation | View transaction on Sepolia Etherscan (opens in a new tab): 0xcc60956bd0b5b285ec61ca2eaaf6c074df07b92f50303c5e7112fba58ad71878 | 12116317 | 12,703,689 | 838,443,474 |
| 14 | 11:57:00 | upgradeAndCall(…, 0x) | View transaction on Sepolia Etherscan (opens in a new tab): 0x91e5ec0b662fa6622841386e81b410cafe5ef2a433fba8fe309e30093990cb61 | 12116319 | 41,724 | 2,753,784 |
After the upgrade the name, supply, balances and owner were all unchanged, and so was the proxy address: still 0xc3F20D5488784D922aC3428a54125715fA98db04. The upgrade transaction used only 41,724 gas, far less than deploying a whole new proxy: that is the benefit of keeping the address and state and swapping only the logic.
Every upgrade stays on-chain
- An upgrade is an ordinary on-chain transaction: it has a hash, costs gas, emits an
Upgradedevent and rewrites the ERC-1967 implementation slot. There is no “silent upgrade”. - The old V1 code remains at its original address; the proxy simply no longer points to it.
- The
stateOverrideused in simulations only pretends locally that some code or storage exists on-chain; it does not change the real chain.
A double-edged sword
- Benefit: fixing bugs or adding features does not force users to switch addresses.
- Cost: if the admin key is stolen or abused, the rules the application runs later can change (including transfer rules, and in theory even what
name()returns). - Technical risk: an incompatible storage layout in a new version (reordering, inserting variables) makes old data “read from the wrong place”. The rule is append only, never reorder.
- Governance: who holds upgrade power? Is it a multisig? Is there a delay, an announcement, a way to exit?
In this lab the ProxyAdmin owner is a single test account, A. That is a deliberately accepted teaching model, not a decentralised issuance.