An upgradeable smart contract is only as trustworthy as whoever can upgrade it, and a single unguarded upgrade path can replace every rule a protocol has. Proxies let teams fix bugs and add features after deployment by pointing a fixed address at new logic. They also add new failure modes: proxies left uninitialised, upgrade functions without access control, storage layouts that collide, and admin keys held by one person. OWASP lists these as SC10:2026 Proxy and Upgradeability Vulnerabilities in its Smart Contract Top 10. This guide covers how proxy patterns work, how they fail, how to run upgrades safely and how to treat upgrade authority as the privileged identity it is. It is for protocol engineers, auditors and the people who hold or operate upgrade keys. For the wider contract security lifecycle, see the Smart Contract Security Guide.
Key takeaways
- Initialise in the same transaction as deployment. Attackers scan for freshly deployed ERC-1967 proxies and initialise them first; OWASP links a 2025 campaign of this kind to more than $10 million in losses.
- Upgrade authority is a non-human identity with total power. Put it behind a multisig and a timelock, never a single externally owned account.
- Pick one established pattern and its tooling. Transparent, UUPS or beacon proxies from a maintained library, checked by upgrade validation tooling, beat custom designs.
- Storage layout is a contract. Every upgrade must preserve the existing layout; verify it with tooling and simulation before execution.
- Watch the slots. Monitor
Upgraded,AdminChangedandBeaconUpgradedevents and the ERC-1967 slots on every proxy you depend on.
How proxies work
A proxy contract holds the state and forwards calls with delegatecall to an implementation contract that holds the logic. Because delegatecall runs the implementation's code against the proxy's storage, changing the stored implementation address changes the behaviour of the contract without changing its address or losing its state.
ERC-1967, a Final Ethereum standard, defines where proxies keep these addresses so they do not collide with the implementation's own variables. Each slot is computed as bytes32(uint256(keccak256('label')) - 1):
| Purpose | Label | Slot | Event on change |
|---|---|---|---|
| Implementation address | eip1967.proxy.implementation | 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc | Upgraded(address indexed implementation) |
| Admin address | eip1967.proxy.admin | 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103 | AdminChanged(address previousAdmin, address newAdmin) |
| Beacon address | eip1967.proxy.beacon | 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50 | BeaconUpgraded(address indexed beacon) |
These fixed slots matter for defenders too: monitoring tools and block explorers read them to tell you which implementation a proxy is really running and who can change it.
Choosing a proxy pattern
The OpenZeppelin Contracts 5.x documentation describes the three common patterns and recommends using its Upgrades Plugins for Hardhat and Foundry because secure upgradeable proxies need deep knowledge.
| Pattern | Where upgrade logic lives | Who can upgrade | Strengths | Watch for |
|---|---|---|---|---|
Transparent proxy (TransparentUpgradeableProxy) | In the proxy | The owner of the ProxyAdmin contract, which the proxy deploys in 5.x; the admin can only call upgradeToAndCall | Upgrade logic cannot be removed by a bad implementation; admin and user calls are separated | Higher deployment cost; never add external functions to the proxy, because selector clashes are not checked and could shadow the upgrade function |
UUPS (UUPSUpgradeable, ERC-1822) | In the implementation | Whoever passes the _authorizeUpgrade check you write | Cheaper; upgrade rights can be removed later by upgrading to a non-upgradeable implementation | A missing or weak _authorizeUpgrade check means anyone can upgrade; upgrading to a non-UUPS implementation can lock upgrades permanently |
Beacon (UpgradeableBeacon and BeaconProxy) | In a shared beacon | The beacon owner | One transaction upgrades many proxies, useful for factories and vaults | The beacon is a single point of control for every proxy using it; a BeaconProxy cannot change its beacon |
| Minimal clones (ERC-1167) | Not upgradeable | Nobody | Cheap copies of fixed logic | OpenZeppelin warns Clones does not check the implementation has code; an uninitialised clone can be taken over |
Decision guidance: use transparent proxies when you want the clearest separation and can afford the gas; UUPS when you want lower cost and a planned path to immutability, and you trust your review of _authorizeUpgrade; beacons when many identical instances must upgrade together. Do not mix UUPS implementations behind a transparent proxy: OpenZeppelin warns both use the same implementation slot, which can let non-admins upgrade. Teams with a simple, well-audited contract and no need to change it should consider not using a proxy at all, because immutability removes the whole SC10 category.
How upgradeability fails
OWASP SC10:2026 groups the failures below and notes the category overlaps with SC01 Access Control but is listed separately because of its systemic impact. See the OWASP Smart Contract Top 10 Guide for the full list.
- Uninitialised proxy: proxied code cannot use constructors, so it uses an
initializefunction. If the proxy is deployed without calling it, or the function lacks aninitializerguard, anyone can call it and become owner. OWASP describes the Kinto incident in July 2025, about $1.55 million, where attackers initialised ERC-1967 proxies with implementations carrying dormant backdoors, then later upgraded and minted tokens. - Uninitialised implementation: the implementation contract itself is left initialisable, so an attacker can take ownership of it directly. For UUPS this can be dangerous where the implementation contains upgrade or self-destruct paths.
- Unguarded upgrade function: an upgrade or admin function with no access control, or with no validation of the new implementation address.
- Storage collision: a new implementation reorders, removes or changes the type of existing variables, or a custom proxy stores its own variables in normal slots, so state is silently overwritten.
- Re-initialisation: a later upgrade adds an initialiser that can be called again, resetting ownership or configuration.
- Dormant backdoors: a malicious or compromised upgrader installs logic that stays inactive through audits and is triggered later, an impact OWASP calls out specifically.
Secure coding rules for upgradeable contracts
- Initialise atomically: pass the initialisation call as the proxy constructor's data argument. OpenZeppelin's
ERC1967Proxyreverts on empty data unless you deliberately override_unsafeAllowUninitialized. - Lock the implementation: call
_disableInitializers()in the implementation's constructor so the logic contract can never be initialised directly. - Guard initialisers: use
initializerfor the first version,reinitializer(n)for each later version andonlyInitializingfor parent initialisers. - Protect upgrades: in UUPS, override
_authorizeUpgradewith a role check such asonlyRole(UPGRADER_ROLE), and give that role only to the timelock. - Preserve storage layout: append new variables only; never reorder, delete or retype. Use namespaced storage (ERC-7201, as used by OpenZeppelin 5.x upgradeable contracts) or storage gaps, and let the upgrades tooling validate layout against the previous version.
- Avoid unsafe operations in logic: no
selfdestructor arbitrarydelegatecallin implementations, and no immutable variables that need to differ per proxy unless the tooling marks them safe. - Keep the proxy minimal: no extra external functions in transparent proxies.
Upgrade authority as an identity: multisig, timelock and roles
Whoever controls ProxyAdmin, the UUPS upgrader role or the beacon owner can replace all logic and drain everything the contract holds. That authority is a privileged non-human identity and should be governed like one. See the Smart Contract Access Control Guide for role design.
| Control | Recommended setting | Why |
|---|---|---|
| Owner of ProxyAdmin, upgrader role or beacon | A timelock contract, never an externally owned account | Gives users and monitors time to see and react to an upgrade |
| Timelock proposers | A governance multisig (for example 4-of-7) with signers on independent hardware wallets | No single key can schedule an upgrade |
| Timelock delay | Days for upgrades, sized to how long users need to exit | An upgrade can replace every rule; users need time to leave |
| Executors and cancellers | Executors restricted or open after delay; a separate guardian multisig able to cancel | Allows a malicious or mistaken proposal to be stopped |
| Timelock admin role | Renounced after set-up, so only the timelock can change its own settings | Stops an admin bypassing the delay |
| Emergency path | Pause only, not upgrade, without delay; pauser cannot move funds | Fast response without a fast upgrade backdoor |
Deployer keys deserve attention: the account that deployed the proxies often starts as owner. Transfer ownership to the timelock as part of the deployment script, verify it on chain, then retire the deployer key. See the Multisig Treasury Operations Guide for signer operations, and the Web3 Developer Operational Security Guide for protecting the machines that hold deployer keys.
Running an upgrade safely
- Change review: code review and, for material changes, an external audit of the new implementation and the diff from the old one.
- Layout validation: run the upgrades plugin or equivalent to compare storage layouts and flag unsafe patterns.
- Fork simulation: deploy and upgrade on a mainnet fork, run the full test suite and key user journeys against real state.
- Deploy the implementation: deploy and verify source on the block explorer; confirm initialisers are disabled.
- Schedule through the timelock: the multisig proposes the exact
upgradeToAndCallcall; publish the proposal and diff for users. - Independent verification: each signer checks the calldata decodes to the expected implementation address on a separate device, not only in the web interface.
- Execute and verify: after the delay, execute, then read the ERC-1967 implementation slot and run post-upgrade checks.
- Rollback plan: keep the previous implementation deployed and a pre-approved proposal to revert to it, and know which state migrations cannot be undone.
Choosing an upgrade governance model
Upgradeability is a business decision as much as a technical one. Users of a protocol are trusting whoever holds upgrade authority, so the model should match the value at risk and the maturity of the code.
| Model | How it works | Fits | Trade-off |
|---|---|---|---|
| Immutable | No proxy; bugs are handled by deploying a new version and migrating users | Small, heavily audited contracts such as tokens and simple vaults | No fixes in place; migration is slow and needs user action |
| Team multisig with timelock | Core team multisig proposes, timelock delays, guardian can cancel | Early-stage protocols that still ship fixes often | Users must trust the team; delay limits how fast real bugs can be fixed |
| Token governance with timelock | On-chain vote schedules upgrades through a governor and timelock | Mature protocols with active, distributed governance | Governance attacks (borrowed voting power, low turnout) become upgrade attacks |
| Upgrade then freeze | Upgradeable during an initial period, then upgrade rights are removed (for example by renouncing ownership or, with UUPS, upgrading to a non-upgradeable implementation) | Protocols with a clear launch and stabilisation phase | Freezing is irreversible; any later bug needs migration |
| Scoped upgradeability | Only peripheral modules are upgradeable; core accounting is immutable | Larger systems with separable components | More complex architecture and interfaces to review |
Small teams versus large protocols: a small team rarely has the signer base for a safe 4-of-7 multisig and the monitoring to watch it, so the safer choice may be immutability or a short upgrade-then-freeze period with an independent co-signer. Large protocols need the full set: separate multisigs for proposing and cancelling, multi-day delays, public proposals, automated layout checks and an incident runbook for unexpected upgrades.
Assessing a dependency's upgrade risk
If your protocol integrates tokens, oracles, bridges or vaults that are themselves proxies, their upgrade authority is part of your attack surface. Before integrating, read the ERC-1967 implementation and admin slots, identify who owns the admin or beacon, check whether that owner is a timelock and how long its delay is, and confirm who the multisig signers are and what threshold applies. Record this in your dependency register and set alerts on the dependency's upgrade events. If a critical dependency can be upgraded by one key with no delay, either cap your exposure to it or build a pause that triggers when its implementation changes.
Detection and measurement
Monitor every proxy you own and every proxy you integrate with. Alert on Upgraded, AdminChanged and BeaconUpgraded events, on timelock CallScheduled entries that target proxy admin functions, on role grants for upgrader roles, and on any change to the ERC-1967 slots that did not come through your timelock. Integrators should treat an unexpected upgrade of a dependency as an incident trigger.
- Upgrade authority coverage: share of proxies whose upgrade authority is a timelock controlled by a multisig; target 100 percent.
- Initialisation gap: number of proxies deployed without atomic initialisation; target zero.
- Layout validation pass rate: upgrades that passed automated layout checks before scheduling.
- Time to detect an unexpected upgrade: minutes from event to alert, tested with drills on a test network.
- Timelock delay versus exit time: delay compared with the time users need to withdraw.
Framework mapping
| Framework | Reference | Application |
|---|---|---|
| OWASP Smart Contract Top 10 | SC10:2026 Proxy and Upgradeability Vulnerabilities; SC01:2026 Access Control | The risk category and its overlap with privileged roles |
| NIST SP 800-53 Rev. 5 | CM-3, CM-4, SA-10 | Change control, impact analysis and developer configuration management for upgrades |
| NIST SP 800-53 Rev. 5 | AC-5, SI-7 | Separation of proposer, executor and canceller; integrity of deployed code |
| NIST CSF 2.0 | PR.PS-01, PR.AA-05 | Configuration management; least privilege and separation of duties for upgrade roles |
| Ethereum standards | ERC-1967, ERC-1822 | Proxy storage slots and UUPS proxiable interface |
Common failure patterns
- Two-step deployments: deploying a proxy and initialising it in a later transaction, which automated attackers race.
- EOA as ProxyAdmin owner: one developer's wallet can upgrade a contract holding user funds; one compromised laptop ends the protocol.
- Timelock with a live admin: the timelock admin role is never renounced, so the holder can shorten the delay or grant themselves proposer rights.
- Layout drift: a variable inserted mid-contract during a refactor corrupts balances after upgrade.
- Blind signing upgrades: multisig signers approve an upgrade proposal without decoding the target implementation.
- One beacon for everything: hundreds of vault proxies share one beacon owned by a hot wallet, so a single key compromise upgrades every vault in one transaction. Give beacons the same timelock and multisig protection as the largest balance they control.
- Ignoring dependency upgrades: integrators trust a token or oracle proxy whose owner can change its logic at any time, with no monitoring.
Practitioner checklist
- Inventory every proxy you deploy or depend on, with pattern, implementation and upgrade authority.
- Initialise every proxy in its deployment transaction and disable initialisers on implementations.
- Use one maintained proxy library and its upgrade validation tooling.
- Move all upgrade authority to a timelock controlled by a multisig and renounce timelock admin.
- Size the timelock delay to user exit time and publish upgrade proposals.
- Validate storage layout and simulate on a fork before every upgrade.
- Decode and verify upgrade calldata on an independent device before signing.
- Monitor ERC-1967 events and slots and treat unexpected changes as incidents.
- Retire deployer keys once ownership has moved.
Standards and references
- OWASP: SC10:2026 Proxy and Upgradeability Vulnerabilities
- Ethereum: ERC-1967 Proxy Storage Slots
- OpenZeppelin: Contracts 5.x Proxies API
- OWASP: Smart Contract Top 10
- NIST: SP 800-53 Rev. 5
- NIST: Cybersecurity Framework 2.0
Related NHI Mgmt Group resources: Smart Contract Security Guide · Smart Contract Access Control Guide · OWASP Smart Contract Top 10 Guide · Smart Contract Audit Readiness and Choosing an Auditor Guide