Join our Newsletter — 33% off our NHI Course
Home› Guides› Smart Contract Upgradeability and Proxy Security Guide: Safe…
Guide Fraud Prevention

Smart Contract Upgradeability and Proxy Security Guide: Safe Upgrades, Admin Keys and Timelocks

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

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, AdminChanged and BeaconUpgraded events 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):

PurposeLabelSlotEvent on change
Implementation addresseip1967.proxy.implementation0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbcUpgraded(address indexed implementation)
Admin addresseip1967.proxy.admin0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103AdminChanged(address previousAdmin, address newAdmin)
Beacon addresseip1967.proxy.beacon0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50BeaconUpgraded(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.

PatternWhere upgrade logic livesWho can upgradeStrengthsWatch for
Transparent proxy (TransparentUpgradeableProxy)In the proxyThe owner of the ProxyAdmin contract, which the proxy deploys in 5.x; the admin can only call upgradeToAndCallUpgrade logic cannot be removed by a bad implementation; admin and user calls are separatedHigher 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 implementationWhoever passes the _authorizeUpgrade check you writeCheaper; upgrade rights can be removed later by upgrading to a non-upgradeable implementationA 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 beaconThe beacon ownerOne transaction upgrades many proxies, useful for factories and vaultsThe beacon is a single point of control for every proxy using it; a BeaconProxy cannot change its beacon
Minimal clones (ERC-1167)Not upgradeableNobodyCheap copies of fixed logicOpenZeppelin 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 initialize function. If the proxy is deployed without calling it, or the function lacks an initializer guard, 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

  1. Initialise atomically: pass the initialisation call as the proxy constructor's data argument. OpenZeppelin's ERC1967Proxy reverts on empty data unless you deliberately override _unsafeAllowUninitialized.
  2. Lock the implementation: call _disableInitializers() in the implementation's constructor so the logic contract can never be initialised directly.
  3. Guard initialisers: use initializer for the first version, reinitializer(n) for each later version and onlyInitializing for parent initialisers.
  4. Protect upgrades: in UUPS, override _authorizeUpgrade with a role check such as onlyRole(UPGRADER_ROLE), and give that role only to the timelock.
  5. 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.
  6. Avoid unsafe operations in logic: no selfdestruct or arbitrary delegatecall in implementations, and no immutable variables that need to differ per proxy unless the tooling marks them safe.
  7. 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.

ControlRecommended settingWhy
Owner of ProxyAdmin, upgrader role or beaconA timelock contract, never an externally owned accountGives users and monitors time to see and react to an upgrade
Timelock proposersA governance multisig (for example 4-of-7) with signers on independent hardware walletsNo single key can schedule an upgrade
Timelock delayDays for upgrades, sized to how long users need to exitAn upgrade can replace every rule; users need time to leave
Executors and cancellersExecutors restricted or open after delay; a separate guardian multisig able to cancelAllows a malicious or mistaken proposal to be stopped
Timelock admin roleRenounced after set-up, so only the timelock can change its own settingsStops an admin bypassing the delay
Emergency pathPause only, not upgrade, without delay; pauser cannot move fundsFast 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

  1. Change review: code review and, for material changes, an external audit of the new implementation and the diff from the old one.
  2. Layout validation: run the upgrades plugin or equivalent to compare storage layouts and flag unsafe patterns.
  3. Fork simulation: deploy and upgrade on a mainnet fork, run the full test suite and key user journeys against real state.
  4. Deploy the implementation: deploy and verify source on the block explorer; confirm initialisers are disabled.
  5. Schedule through the timelock: the multisig proposes the exact upgradeToAndCall call; publish the proposal and diff for users.
  6. Independent verification: each signer checks the calldata decodes to the expected implementation address on a separate device, not only in the web interface.
  7. Execute and verify: after the delay, execute, then read the ERC-1967 implementation slot and run post-upgrade checks.
  8. 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.

ModelHow it worksFitsTrade-off
ImmutableNo proxy; bugs are handled by deploying a new version and migrating usersSmall, heavily audited contracts such as tokens and simple vaultsNo fixes in place; migration is slow and needs user action
Team multisig with timelockCore team multisig proposes, timelock delays, guardian can cancelEarly-stage protocols that still ship fixes oftenUsers must trust the team; delay limits how fast real bugs can be fixed
Token governance with timelockOn-chain vote schedules upgrades through a governor and timelockMature protocols with active, distributed governanceGovernance attacks (borrowed voting power, low turnout) become upgrade attacks
Upgrade then freezeUpgradeable 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 phaseFreezing is irreversible; any later bug needs migration
Scoped upgradeabilityOnly peripheral modules are upgradeable; core accounting is immutableLarger systems with separable componentsMore 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

FrameworkReferenceApplication
OWASP Smart Contract Top 10SC10:2026 Proxy and Upgradeability Vulnerabilities; SC01:2026 Access ControlThe risk category and its overlap with privileged roles
NIST SP 800-53 Rev. 5CM-3, CM-4, SA-10Change control, impact analysis and developer configuration management for upgrades
NIST SP 800-53 Rev. 5AC-5, SI-7Separation of proposer, executor and canceller; integrity of deployed code
NIST CSF 2.0PR.PS-01, PR.AA-05Configuration management; least privilege and separation of duties for upgrade roles
Ethereum standardsERC-1967, ERC-1822Proxy 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.