Upgradeable smart contract

Also known as: proxy contract

On this page 7

An upgradeable smart contract is a contract system whose address and stored state stay fixed while the executable logic can be replaced after deployment. In smart contracts on Ethereum and other EVM chains, deployed bytecode is immutable, so upgradeability is achieved indirectly: users interact with a proxy contract that holds the data and forwards every call to a separate implementation contract, which an authorized party can swap for a newer version.

The pattern is common in Crypto & blockchain projects that need to fix bugs, add features or respond to incidents without migrating users and balances to a new address. It also introduces a trust trade-off: whoever controls the upgrade can change the rules, so upgradeability is as much a governance question as a technical one.

How the proxy pattern makes code replaceable

Upgradeability rests on the EVM opcode `delegatecall`, which runs the code of another contract in the storage context of the caller. The proxy has almost no logic of its own; its fallback function takes any incoming call, forwards the calldata to the implementation with delegatecall, and returns the result. Because storage writes land in the proxy, balances and variables persist across upgrades.

An upgrade is simply a transaction that changes the implementation address stored in the proxy. From that block onward, every call executes the new code against the same storage. Users, integrators and token holders keep using one address, and indexers see an uninterrupted history.

The table below lists the components of a typical upgradeable deployment and the role each one plays.

ComponentWhat it holdsRole in an upgrade
Proxy contractState, balances, implementation addressStays deployed permanently at the public address
Implementation contractBusiness logic onlyReplaced by a new version on upgrade
Admin or upgrade authorityPermission to change the pointerSigns or executes the upgrade transaction
Proxy admin contractOwnership of one or more proxiesSeparates admin calls from user calls
TimelockQueued upgrade transactionsDelays execution so users can react
Components of a proxy-based upgradeable system

Main upgradeable proxy patterns

Several standardized patterns exist, and they differ mainly in where the upgrade logic lives and how they avoid clashes between admin and user functions. Most are specified in Ethereum Improvement Proposals, notably EIP-1967 for standard storage slots, EIP-1822 for UUPS and EIP-2535 for the diamond pattern.

PatternWhere upgrade logic livesStrengthsWeaknesses
Transparent proxyIn the proxy, callable only by adminClear separation, widely auditedHigher gas per call, admin cannot use the dApp
UUPS proxyIn the implementation contractCheaper calls, smaller proxyAn upgrade without the upgrade function bricks the contract
Beacon proxyIn a shared beacon contractOne transaction upgrades many proxiesSingle beacon is a concentrated risk
Diamond (EIP-2535)In a facet registryModular, bypasses contract size limitComplex, harder to audit and reason about
Minimal proxy (EIP-1167)None, implementation is fixedVery cheap clonesNot upgradeable at all
Comparison of common proxy patterns

The transparent proxy routes calls by sender: the admin reaches upgrade functions, everyone else reaches the logic. UUPS (Universal Upgradeable Proxy Standard) moves the upgrade function into the implementation, which saves gas but means every new version must keep the upgrade mechanism, or the system freezes permanently. The minimal clone is included because it is often confused with upgradeable proxies, although it only reduces deployment cost.

Storage layout and initialization rules

The most frequent technical failure in upgradeable contracts is a storage collision. Solidity assigns state variables to sequential storage slots, so a new implementation must preserve the order and types of every existing variable and only append new ones. Inserting, removing or reordering a variable silently makes the new code read the wrong data.

EIP-1967 reduces collisions between proxy and logic by placing the implementation and admin addresses in pseudo-random storage slots derived from a hash. Developers also reserve storage gaps, fixed-size unused arrays in base contracts, so that inherited contracts can gain variables later without shifting child storage.

Constructors do not work in this model, because constructor code runs at deployment in the implementation’s own storage, not in the proxy. Instead, logic contracts use an initializer function guarded so it can run exactly once. Leaving an implementation uninitialized has enabled real exploits in which an attacker initialized the logic contract directly and then destroyed or hijacked it.

  • Append new state variables only at the end of the layout.
  • Never change the type of an existing variable.
  • Call the initializer in the same transaction as deployment.
  • Disable initializers on the implementation contract itself.
  • Run an automated storage layout check before each upgrade.

Governance and trust in upgrade authority

An upgradeable contract is only as trustworthy as the party that controls upgrades. If a single private key holds that power, a compromised or malicious key can replace the logic and drain every deposit, which undermines the promise of code that cannot be changed. Experienced reviewers therefore examine the upgrade path before the code itself.

The following table summarizes common control models, from the most centralized to the least, with the main risk of each.

Control modelTypical setupMain riskSuitable stage
Single key (EOA)One developer walletKey theft or insider abuseTestnet and early prototypes
Multisignature wallet3 of 5 or 4 of 7 signersSigner collusion or shared infrastructureEarly mainnet launch
Multisig plus timelockDelay of 24 hours to 14 daysSlow response to active exploitsMature protocols
DAO governanceToken vote, then timelockVote buying or low turnoutDecentralized protocols
Renounced or frozenAdmin removedBugs can no longer be fixedFinal, fully audited code
Upgrade control models and their risks

A timelock gives users a window to inspect a queued upgrade and withdraw if they disagree. Many teams pair it with an emergency pause controlled by a guardian, so they can stop an exploit quickly while still requiring a delay for logic changes.

Risks, audits and common mistakes

Upgradeability enlarges the attack surface: the proxy, the admin keys, the initializer and every future version all become audit targets. A smart contract audit of version one does not cover version two, so each upgrade needs its own review and, for high-value systems, formal verification of storage compatibility.

SymptomLikely causePrevention
Corrupted balances after upgradeReordered or inserted state variablesAutomated layout diff in CI
Contract no longer upgradeableUUPS version without upgrade functionTest the upgrade path on a fork
Logic contract hijackedUninitialized implementationDisable initializers in constructor
Function selector clashAdmin and logic share a selectorTransparent proxy or selector checks
Unexpected admin takeoverLeaked upgrade keyMultisig, hardware keys, timelock
Typical failures in upgradeable contracts

A common misconception is that a verified proxy on a block explorer means the code is final. Explorers verify the current implementation only; users should check who can upgrade and how quickly, because that determines whether the visible code can change tomorrow.

The simple explanation

Think of an upgradeable smart contract as a shop with a fixed street address and a manager who follows a rulebook. Customers always walk into the same shop, and their accounts stay on file. The owner can hand the manager a new rulebook, and from then on the shop works differently, while the address and the records stay the same.

This is useful because mistakes can be fixed without moving everyone to a new shop. The catch is that someone holds the power to change the rulebook. The key question is always who that someone is and whether customers get warning before the rules change.

How it is used in practice

A lending protocol launches on an EVM chain with its core pool deployed behind a UUPS proxy. Upgrade rights belong to a 4-of-7 multisignature wallet, and every upgrade passes through a 48-hour timelock. A guardian key can pause deposits but cannot change logic.

Six months after launch, an auditor reports that interest accrues incorrectly when a reserve has zero borrowers. The team writes version two, appends one new state variable, runs an automated storage layout comparison and replays the upgrade on a mainnet fork. After a second audit, the signers queue the transaction and announce it publicly.

Two days later the upgrade executes. Deposits worth tens of millions of dollars stay at the same address, integrators change nothing, and the accounting bug is gone. Users who disagreed had the full timelock window to withdraw, which is the practical balance between fixability and trust that upgradeable designs aim for.