In July 2022 someone called initialize a second time on Audius's governance contract, and it went through. The proxy in front of it, AudiusAdminUpgradabilityProxy, kept its proxyAdmin address in storage slot 0. OpenZeppelin's Initializable keeps its initialized and initializing flags in slot 0 as well. With an address sitting on top of those two booleans, the initializer check could always pass. The attacker re-initialized Governance, Staking and DelegateManagerV2 with their own settings and passed a proposal that moved 18,564,497 AUDIO out of the community treasury (Audius post-mortem).
Each contract looked fine on its own. The bug was in how the two shared storage.
That's where most proxy bugs live: between the proxy and the implementation, or between version 1 and version 2. Reading either contract alone won't show them. This is the list I'd want a team to go through before an audit, and again before every upgrade.
Storage layout
The proxy holds the storage and the implementation decides what each slot means. Every version of the implementation has to agree with every earlier one about every slot that's already in use.
-
Proxy variables go in ERC-1967 slots. Implementation at
keccak256("eip1967.proxy.implementation") - 1(0x3608...2bbc), admin atkeccak256("eip1967.proxy.admin") - 1(0xb531...6103), beacon atkeccak256("eip1967.proxy.beacon") - 1(0xa3f0...3d50). Those are hashes, so a normal layout starting at slot 0 never reaches them. A hand-written proxy that declaresaddress adminas an ordinary state variable is the Audius setup. -
Append only. New variables go at the end. Don't reorder, don't change a type, don't delete. A variable you no longer need stays where it is, renamed to something like
__deprecated_feeRecipient. - Structs count as their full size. A struct stored directly in the layout, or inside an array, can't take a new member: its size changes and everything after it moves. A struct used only as a mapping value can take new members at the end.
-
Parents come first. Inherited variables are laid out in linearization order before the child's. Add a variable to a parent and every child variable shifts. Change
is A, Btois B, Aand the layout changes too. -
Gaps or namespaces, one of the two. OpenZeppelin's upgradeable contracts up to 4.x reserve space with
uint256[50] private __gap. Add two one-slot variables to that contract and the gap becomesuint256[48]. Since 5.0 they use ERC-7201 namespaced storage instead: each contract keeps its variables in a struct at a hashed slot (@custom:storage-location erc7201:openzeppelin.storage.Ownable), so there's no gap to maintain in their code. Your own base contracts still need one or the other. - 4.x to 5.x is not an upgrade. The two major versions lay out storage differently. Moving a live proxy from an implementation built on 4.x to one built on 5.x will misread existing state. OpenZeppelin says not to do it.
Check it with a tool, not by eye. forge inspect VaultV1 storageLayout and forge inspect VaultV2 storageLayout print slot, offset and type for every variable; each V1 entry has to appear in V2 unchanged. OpenZeppelin's Upgrades plugins for Hardhat and Foundry do the comparison for you and refuse an incompatible upgrade.
Initializers
A proxy can't run the implementation's constructor, so setup happens in an initialize function, and anything that can be initialized can be initialized by the wrong person.
Lock the implementation itself:
/// @custom:oz-upgrades-unsafe-allow constructor
constructor() {
_disableInitializers();
}
In February 2022 a whitehat known as satya0x found Wormhole's Ethereum bridge implementation sitting uninitialized, after an earlier fix had reverted its initialization. Anyone could call initialize on it with their own guardian set, then, as that guardian, run an upgrade into a contract that self-destructs. That would have destroyed the implementation and left the proxy pointing at nothing. Wormhole fixed it the same day and paid a $10M bounty (Immunefi's write-up).
Since Dencun (March 2024 on Ethereum mainnet), EIP-6780 changed SELFDESTRUCT: it only deletes code when it runs in the same transaction that created the contract. So on mainnet that exact bricking path is gone. Check whether the chain you deploy on has adopted it. And disable initializers anyway, because an implementation anyone can initialize is an owner anyone can become.
Then the proxy:
- Deploy and initialize in one transaction. Pass the init call to the proxy constructor:
Vault impl = new Vault();
ERC1967Proxy proxy = new ERC1967Proxy(
address(impl),
abi.encodeCall(Vault.initialize, (owner, asset))
);
A deploy script that creates the proxy and calls initialize in a second transaction leaves a window where someone else can call it first.
-
Every parent initializer gets called.
__Ownable_init(owner),__ERC20_init(name, symbol)and the rest. A missed one leaves its state at zero, an owner ofaddress(0)for example. Your own internal init functions takeonlyInitializing. - Validate the inputs. Zero addresses and out-of-range fees are as wrong in an initializer as anywhere else, and there's usually no second chance to set them.
-
V2 setup uses
reinitializer(2), passed to the upgrade. Send it as thedataofupgradeToAndCallso it runs in the same transaction. A publicinitializeV2called afterwards has the same front-running window as above. -
Apart from
_disableInitializers(), the implementation's constructor only sets immutables. Storage written there lands in the implementation's own storage, which no proxy reads. Immutables work because they're in the bytecode, so every proxy sees the same value.
Who can upgrade
Whoever can upgrade can replace every line of code behind the proxy. That key outranks every onlyOwner in the contracts.
- Not a single EOA in production. A multisig at least, and a timelock in front of routine upgrades so users can see a new implementation and leave before it runs. Keep any emergency path narrow: pausing, not upgrading without delay.
-
UUPS:
_authorizeUpgradehas access control. An empty override likefunction _authorizeUpgrade(address) internal override {}lets anyone upgrade. Every new version must still inheritUUPSUpgradeablewith the same restriction. OpenZeppelin'supgradeToAndCallcallsproxiableUUID()on the new implementation and reverts if it's missing, which stops an upgrade to a contract that couldn't upgrade again. A hand-written UUPS base may not check that. -
Transparent (OpenZeppelin 5.x): the admin is fixed at deployment. The proxy's constructor deploys its own
ProxyAdminand stores its address as an immutable. TheinitialOwneryou pass becomes thatProxyAdmin's owner, so if the deploy script passes the deployer EOA, that EOA can upgrade until ownership moves. You can't point the proxy at a new admin later; you transfer ownership of theProxyAdmin. -
ProxyAdmindoesn't validate anything. It forwardsupgradeAndCall, and the only check underneath is that the new implementation has code. Layout and initializer checks happen in your process or they don't happen. -
Beacon: one call upgrades every proxy.
upgradeToon the beacon moves all its proxies at once, so the beacon's owner is a bigger key than any single proxy admin. -
Watch the events. Alert on
Upgraded(address),AdminChangedandBeaconUpgradedfor every proxy you run.
What the proxy answers by itself
A call reaches the implementation only if the proxy doesn't handle it first.
-
Selector clashes. If a function in the proxy has the same 4-byte selector as one in the implementation, the proxy answers and the implementation never sees the call.
burn(uint256)andcollate_propagate_storage(bytes16)are both0x42966c68, so a proxy can hide an admin function behind what looks like a normal token call.cast sigprints any selector; compareforge inspect <Proxy> methodIdentifierswith the implementation's. -
OpenZeppelin's proxies avoid most of this. A UUPS proxy (
ERC1967Proxy) has no public functions of its own. The Transparent proxy forwards every call except those from its admin, and the admin can only callupgradeToAndCall; anything else from the admin reverts withProxyDeniedAdminAccess. A custom proxy withupgradeTo,admin()orowner()on the proxy needs the selector check. -
Diamonds. Every selector maps to exactly one facet,
diamondCutis restricted like any other upgrade, and each facet keeps its storage in its own namespace.
Delegatecall from the implementation
The implementation runs with the proxy's storage, address and balance. address(this) is the proxy.
-
Any
delegatecallinside the implementation to an address from calldata or from writable storage can run arbitrary code against the proxy's storage. That includes "multicall" or "execute" helpers. -
Code checks happen at upgrade time. OpenZeppelin's
ERC1967Utilsreverts if the new implementation has no code, but the fallback doesn't check on every call. A hand-written proxy that can be pointed at an address with no code doesn't revert: adelegatecallto an empty address succeeds and returns nothing, so every call looks like it worked. -
Old chains, old opcode. On a chain without EIP-6780, a
selfdestructreachable through the implementation, directly or through a library it delegatecalls, still deletes the code every proxy depends on. In 2017 a user initialized the Parity multisig wallet library, became its owner and killed it, which froze about 513,000 ETH in the wallets that delegated to it.
Before every upgrade
The audit covered the implementation you sent. The upgrade is a new deployment, and it deserves its own check.
- Compare the storage layouts (above).
- List what the new version changes: functions added or removed, modifiers, roles, any new
reinitializer. - Read what's live:
cast implementation <proxy>andcast admin <proxy>print the ERC-1967 slots, and the explorer's verified source should match the build you reviewed. - Run the upgrade on a fork of the real proxy, then check that state survived:
function test_upgradeKeepsState() public {
vm.createSelectFork(vm.envString("MAINNET_RPC_URL"));
Vault vault = Vault(PROXY);
uint256 assetsBefore = vault.totalAssets();
address ownerBefore = vault.owner();
VaultV2 v2 = new VaultV2();
vm.prank(UPGRADER); // the address _authorizeUpgrade accepts, e.g. the timelock
vault.upgradeToAndCall(address(v2), abi.encodeCall(VaultV2.initializeV2, (NEW_FEE)));
assertEq(vault.totalAssets(), assetsBefore);
assertEq(vault.owner(), ownerBefore);
}
Add an assertion for every variable a user's money depends on: balances of a few real holders, share price, total supply, who holds each role. A layout mistake usually shows up here as a value that's suddenly zero or suddenly huge.
Adapted from a checklist our team published on zealynx.io, which has the longer version with all 33 checks and per-pattern lists. This version drops the original's unsourced loss and finding totals, corrects the point that only UUPS implementations hold storage (in both patterns the implementation declares the variables and they live in the proxy), replaces the "never use slots below" rule with how ERC-1967 slots work, and adds the Audius, Wormhole and Parity cases, EIP-6780, OpenZeppelin 5.x's namespaced storage and its fixed ProxyAdmin.
I wrote this with help from AI for drafting and editing. The opinions and the audit experience are mine.
Top comments (0)