Upgrade Patterns for Contracts

A deployed contract cannot be modified. Upgradeability is therefore achieved by separating the address users interact with from the code that executes.

The proxy pattern

Users interact with a proxy contract that holds the state. The proxy delegates execution to a separate implementation contract.

Upgrading means pointing the proxy at a new implementation. State persists because it lives in the proxy; logic changes because the implementation address changed.

This is the dominant pattern and it is why an address you have interacted with for years can behave differently tomorrow.

The variants

Transparent proxy. Administrative functions are separated from user functions to avoid collisions.

Minimal proxy. A cheap clone pattern used for deploying many identical contracts.

Diamond pattern. Multiple implementation contracts behind one proxy, each handling different functions, allowing partial upgrades.

Beacon proxy. Many proxies pointing at a shared beacon, so one change upgrades all of them simultaneously.

The questions that matter

Who can upgrade. An externally owned account means one person. A multi-signature means a threshold. Governance means a vote.

Is there a timelock. A delay between an upgrade being scheduled and executed, during which users can exit.

This is the single most user-relevant property and it is rarely discussed. Without it, an upgrade is a fait accompli.

Can it be made immutable. Some designs allow upgradeability to be permanently disabled, which is a strong commitment.

The risks

Storage collisions. If a new implementation lays out storage differently, existing data is misinterpreted. This has caused real losses.

Initialisation. Proxies require careful initialisation, and mistakes have left contracts uninitialised and takeable.

Trust. An upgradeable contract is only as safe as whoever holds the upgrade key, regardless of how good the current code is.

What a user should check

For any contract holding meaningful value: is it upgradeable, who can upgrade it, and is there a timelock.

All three are visible. The proxy pattern is identifiable from the contract code, the admin address is readable, and the timelock is either present in the code or it is not.

Independent watchdog sites publish this for major protocols in a standard format, which is the fastest route to the answer.

The implication for audits

An audit covers the implementation reviewed at a specific commit. An upgradeable contract can be pointed at different code afterwards.

So an audit of an upgradeable contract establishes that one version was reviewed, not that the running version is that one. Checking the current implementation address against the audited commit is the step that closes the gap, and almost nobody performs it.