Smart contracts are immutable by default. Once deployed, the code can't change. That is a feature when you want users to trust a contract, and a headache when you find a bug or need to add a feature. The common answer is a proxy: a small contract that holds the data and the address of a logic contract, and forwards every call to it. To "upgrade", you point the proxy at a new logic contract. The user keeps the same address and the same stored data.
There are two popular ways to manage that pointer, UUPS and Transparent proxies, and beginners are often told conflicting things about which to choose. This post explains the difference in plain terms, shows both upgraded in tested code, and finishes with the mistakes that cause real damage. A fair warning first: OpenZeppelin's own documentation cautions that using upgradeable proxies correctly and securely is difficult and requires deep knowledge of the proxy pattern, Solidity and the EVM. If you don't need upgradeability, don't add it.
The shared idea
Both patterns use a proxy that delegates calls to an implementation. The implementation's code runs, but against the proxy's storage. Two consequences matter immediately:
- Constructors don't work as initializers. The constructor runs once when the implementation is deployed, against the implementation's own storage, not the proxy's. OpenZeppelin's docs explain that proxies are oblivious to what a constructor does. So you write an
initializefunction and call it through the proxy. - Storage layout is forever. New versions can add variables at the end, but reordering or changing the type of existing ones corrupts data.
The only real difference: where the upgrade function lives
This is the whole distinction, as OpenZeppelin puts it: in a Transparent proxy, the upgrade and admin logic is included in the proxy itself. In UUPS (named after ERC-1822), the upgrade is handled by the implementation, and can eventually be removed.
Everything else follows from that choice.
UUPS in code
The UUPS implementation inherits UUPSUpgradeable and must override _authorizeUpgrade to say who may upgrade. Here it is onlyOwner. The proxy itself is an ordinary ERC1967Proxy, which is not upgradeable on its own.
Upgradeable.sol
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
import {ERC1967Proxy} from "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import {TransparentUpgradeableProxy} from "@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol";
import {ProxyAdmin} from "@openzeppelin/contracts/proxy/transparent/ProxyAdmin.sol";
/// UUPS: the upgrade logic lives in the implementation.
contract BoxUUPSV1 is Initializable, OwnableUpgradeable, UUPSUpgradeable {
uint256 public value;
/// @custom:oz-upgrades-unsafe-allow constructor
constructor() {
_disableInitializers(); // the implementation itself must never be initialised
}
function initialize(address initialOwner, uint256 value_) external initializer {
__Ownable_init(initialOwner);
value = value_;
}
function _authorizeUpgrade(address) internal override onlyOwner {}
}
contract BoxUUPSV2 is BoxUUPSV1 {
function increment() external { value += 1; }
function version() external pure returns (uint256) { return 2; }
}
/// Transparent: the upgrade logic lives in the proxy + ProxyAdmin; the implementation stays plain.
contract BoxV1 is Initializable {
uint256 public value;
/// @custom:oz-upgrades-unsafe-allow constructor
constructor() { _disableInitializers(); }
function initialize(uint256 value_) external initializer { value = value_; }
}
contract BoxV2 is BoxV1 {
function increment() external { value += 1; }
function version() external pure returns (uint256) { return 2; }
}
// Thin wrappers so Hardhat builds deployable artifacts for the OpenZeppelin proxies.
contract UUPSProxy is ERC1967Proxy {
constructor(address impl, bytes memory data) ERC1967Proxy(impl, data) {}
}
contract TransparentProxy is TransparentUpgradeableProxy {
constructor(address impl, address adminOwner, bytes memory data)
TransparentUpgradeableProxy(impl, adminOwner, data) {}
}
contract BoxProxyAdmin is ProxyAdmin {
constructor(address initialOwner) ProxyAdmin(initialOwner) {}
}
Two details deserve attention. The constructor calls _disableInitializers(), so nobody can initialize the bare implementation and take it over. And initialize uses the OpenZeppelin v5 form of Ownable, which takes the initial owner explicitly.
Transparent proxy in code
With a Transparent proxy, the implementation is plain: no upgrade code at all. The proxy is set up with an admin, and in OpenZeppelin 5 the proxy creates its own ProxyAdmin contract owned by the address you pass. The ProxyAdmin is the only thing that can upgrade it. A key rule of the pattern is that the admin address can't call the implementation's functions through the proxy: calls from the admin are for administration only. That is what "transparent" means, and it avoids function-selector clashes between the proxy's admin functions and the implementation's.
Tests for both
Upgradeable.ts
import { expect } from "chai";
import { network } from "hardhat";
const { ethers, networkHelpers } = await network.create();
// EIP-1967 admin slot: where a TransparentUpgradeableProxy stores its ProxyAdmin address.
const ADMIN_SLOT = "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103";
describe("UUPS", function () {
it("upgrades through the proxy, keeps state, and only the owner may upgrade", async function () {
const [owner, other] = await ethers.getSigners();
const v1 = await ethers.deployContract("BoxUUPSV1");
const initData = v1.interface.encodeFunctionData("initialize", [owner.address, 41n]);
const proxy = await ethers.deployContract("UUPSProxy", [await v1.getAddress(), initData]);
const asV1 = await ethers.getContractAt("BoxUUPSV1", await proxy.getAddress());
expect(await asV1.value()).to.equal(41n);
const v2 = await ethers.deployContract("BoxUUPSV2");
await expect(asV1.connect(other).upgradeToAndCall(await v2.getAddress(), "0x"))
.to.be.revertedWithCustomError(asV1, "OwnableUnauthorizedAccount");
await asV1.upgradeToAndCall(await v2.getAddress(), "0x");
const asV2 = await ethers.getContractAt("BoxUUPSV2", await proxy.getAddress());
await asV2.increment();
expect(await asV2.value()).to.equal(42n); // old state kept, new logic works
expect(await asV2.version()).to.equal(2n);
});
it("the bare implementation cannot be initialised by a stranger", async function () {
const [owner] = await ethers.getSigners();
const v1 = await ethers.deployContract("BoxUUPSV1");
await expect(v1.initialize(owner.address, 1n)).to.be.revertedWithCustomError(v1, "InvalidInitialization");
});
});
describe("Transparent proxy", function () {
it("is upgraded by its ProxyAdmin, and the admin cannot call the implementation", async function () {
const [admin, user] = await ethers.getSigners();
const v1 = await ethers.deployContract("BoxV1");
const initData = v1.interface.encodeFunctionData("initialize", [41n]);
const proxy = await ethers.deployContract("TransparentProxy", [await v1.getAddress(), admin.address, initData]);
const adminSlot = await ethers.provider.getStorage(await proxy.getAddress(), ADMIN_SLOT);
const proxyAdminAddr = ethers.getAddress("0x" + adminSlot.slice(26));
const proxyAdmin = await ethers.getContractAt("BoxProxyAdmin", proxyAdminAddr);
expect(await proxyAdmin.owner()).to.equal(admin.address);
const asV1 = await ethers.getContractAt("BoxV1", await proxy.getAddress());
expect(await asV1.connect(user).value()).to.equal(41n);
const v2 = await ethers.deployContract("BoxV2");
await proxyAdmin.upgradeAndCall(await proxy.getAddress(), await v2.getAddress(), "0x");
const asV2 = await ethers.getContractAt("BoxV2", await proxy.getAddress());
await asV2.connect(user).increment();
expect(await asV2.connect(user).value()).to.equal(42n);
// The ProxyAdmin address itself is not allowed to call implementation functions through the proxy.
await networkHelpers.impersonateAccount(proxyAdminAddr);
await networkHelpers.setBalance(proxyAdminAddr, 10n ** 18n);
const adminSigner = await ethers.getSigner(proxyAdminAddr);
await expect(asV2.connect(adminSigner).value()).to.be.revertedWithCustomError(proxy, "ProxyDeniedAdminAccess");
});
});
All three tests pass. The UUPS test deploys version 1 behind the proxy, stores 41, checks that a stranger can't upgrade (it reverts with OwnableUnauthorizedAccount), upgrades to version 2 as the owner, calls the new increment function and confirms the value is 42, so old state survived and new logic works. The second test confirms that a stranger can't initialize the bare implementation.
The Transparent test reads the proxy's admin from the standard ERC-1967 storage slot to find the ProxyAdmin, upgrades through it, and then verifies the rule: when the ProxyAdmin itself tries to call value() through the proxy, it reverts with ProxyDeniedAdminAccess.
How to choose
| Question | Transparent | UUPS |
|---|---|---|
| Where is the upgrade logic? | In the proxy and its ProxyAdmin | In the implementation |
| Deployment cost | Proxy is more expensive to deploy, per OpenZeppelin | Proxy is lighter |
| Can upgradeability be removed later? | The upgrade logic stays in the proxy; it is not something an implementation can remove | Yes, by upgrading to an implementation without the upgrade function |
| Biggest beginner risk | Confusion over who the admin is | Shipping a new version that lacks the upgrade function, or forgetting access control |
| OpenZeppelin's stated direction | Still provided | Recommendation "shifting towards" UUPS |
My practical guidance for a beginner: if you are using OpenZeppelin's contracts and tooling, UUPS is a sound default, which is also the direction their documentation points. Choose Transparent when you want the upgrade authority kept entirely outside the implementation, for example if several people will write implementations and you don't want each to remember an upgrade function. Whichever you choose, use the OpenZeppelin Upgrades plugin or an equivalent for storage-layout checks. I did not run it in this post, so these tests don't demonstrate that safety.
Mistakes that cause real damage
- Forgetting
_disableInitializers(). An uninitialized implementation can be claimed by a stranger. The second UUPS test exists to prove it is blocked. - Missing or weak
_authorizeUpgrade(UUPS). If anyone can call it, anyone can replace your logic. Always put real access control on it. - Upgrading to an implementation without upgrade code (UUPS). You would lock upgradeability forever. OpenZeppelin's
UUPSUpgradeableincludes a check that blocks upgrades to a non-UUPS implementation by default. Don't bypass it casually. - Mixing proxies and implementations. The docs warn that using a UUPS-compliant implementation behind a Transparent proxy might allow non-admins to perform upgrades, because both use the same storage slot for the implementation address.
- Changing storage layout. Never reorder or retype existing variables. Add new ones at the end.
- Initializing twice, or never. Use the
initializermodifier and call it in the same transaction that deploys the proxy. - Treating the upgrade key as an afterthought. Whoever can upgrade can change what your contract does. Use a multisig, and consider a timelock so users can see an upgrade coming.
The question to ask first
Before choosing between the two, ask whether you need upgradeability at all. An upgradeable contract asks users to trust whoever holds the upgrade key, forever. For many projects, a simple immutable contract plus a migration plan to a new address is easier to reason about and to audit. If you do go upgradeable, write down who can upgrade, how, and under what process, and tell your users. Then check your assumptions against the audit preparation checklist before you deploy.
Planning an upgradeable contract?
I build and test Solidity projects, including proxy setups with deployment scripts and upgrade tests. If you want a second pair of eyes on your design, get in touch.
See services Get in touchWhat I ran this against
- Hardhat 3.22.0 (Mocha + ethers template), @openzeppelin/contracts 5.6.1, ethers 6.17.0, solc 0.8.34, Node.js 24.22.1, run on 17 November 2026 on Hardhat's in-process simulated network. Three tests pass: a UUPS upgrade that keeps state and restricts who can upgrade, an uninitialised UUPS implementation that a stranger cannot take over, and a Transparent proxy upgrade through its ProxyAdmin.
- Nothing was deployed to a testnet or mainnet, and the contracts are teaching examples that have not been audited. I did not use the OpenZeppelin Upgrades plugin's storage-layout checks here, so the examples do not demonstrate layout safety between versions.
Sources checked
- OpenZeppelin Contracts 5.x, Proxy API reference, including the "Transparent vs UUPS Proxies" section and the caution that using upgradeable proxies correctly and securely requires deep knowledge: docs.openzeppelin.com.
- OpenZeppelin Upgrades, "Proxy Upgrade Pattern" (storage collisions, the constructor caveat, function clashes and the per-proxy ProxyAdmin): docs.openzeppelin.com/upgrades-plugins/proxies.