Web3 & DApp Development Fundamentals · Lesson

Upgradeable Contracts

Proxy patterns.

Upgradeable Contracts is a free Web3 & DApp Development Fundamentals lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Web3 & DApp Development Fundamentals learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Immutability Problem

Deployed contract code cannot be changed. If you find a bug or need a new feature, the code is frozen at its address.

Upgradeable contracts work around this using a proxy pattern that lets you swap the logic while keeping the same address and data.

The Proxy Pattern

Upgradeability splits a contract into two parts:

Proxy — holds the state and a pointer to the logic; users interact with it.
Implementation — holds the code, no permanent state.

The proxy delegatecalls into the implementation, so logic runs against the proxy's storage.

How delegatecall Works

delegatecall executes another contract's code in the caller's storage context. So when the proxy delegatecalls the implementation:

Code comes from the implementation.
Storage read/written is the proxy's.

Upgrading just changes which implementation the proxy points to.

Initializers, Not Constructors

Constructors run at deploy time and do not affect proxy storage. Upgradeable contracts use an initialize function instead:

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract Box is Initializable {
    uint256 public value;
    function initialize(uint256 v) public initializer {
        value = v;
    }
}

import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract Box is Initializable {
    uint256 public value;
    function initialize(uint256 v) public initializer {
        value = v;
    }
}

The Upgradeable Library

OpenZeppelin ships a separate package for this. Its modules use initializers instead of constructors:

npm install @openzeppelin/contracts-upgradeable

Pair it with the Hardhat Upgrades plugin to deploy and manage proxies safely.

npm install @openzeppelin/contracts-upgradeable @openzeppelin/hardhat-upgrades

Deploying a Proxy

The Hardhat Upgrades plugin deploys the implementation and proxy together, calling your initializer:

const { ethers, upgrades } = require("hardhat");

const Box = await ethers.getContractFactory("Box");
const box = await upgrades.deployProxy(Box, [42]);
await box.waitForDeployment();

The array holds the initializer arguments.

const { ethers, upgrades } = require("hardhat");

const Box = await ethers.getContractFactory("Box");
const box = await upgrades.deployProxy(Box, [42]);
await box.waitForDeployment();

Performing an Upgrade

To upgrade, deploy a new implementation and point the existing proxy at it:

const BoxV2 = await ethers.getContractFactory("BoxV2");
const upgraded = await upgrades.upgradeProxy(
  await box.getAddress(),
  BoxV2
);

The address and stored state are preserved; only the logic changes.

const BoxV2 = await ethers.getContractFactory("BoxV2");
const upgraded = await upgrades.upgradeProxy(
  await box.getAddress(),
  BoxV2
);

Storage Layout Rules

Because the proxy keeps its storage, new versions must preserve the storage layout:

Never reorder or remove existing state variables.
Only append new variables at the end.
Reserve gaps in base contracts for future fields.

The plugin checks for unsafe changes and warns you.

Transparent vs UUPS

Two common proxy styles:

Transparent — upgrade logic lives in the proxy; simple but slightly more gas.
UUPS — upgrade logic lives in the implementation (via UUPSUpgradeable); cheaper, but you must not forget to include it.

UUPS is now the generally recommended default.

Upgradeability Trade-offs

Upgradeability is powerful but adds risk:

Whoever controls upgrades can change the rules — a centralization concern.
Storage and initializer mistakes can brick the contract.

Guard the upgrade authority with a multisig or timelock, and test upgrades thoroughly.

Disabling Initializers in the Implementation

An implementation contract should never be initialized directly. Lock it in its constructor:

constructor() {
    _disableInitializers();
}

This prevents an attacker from taking over the standalone implementation while leaving the proxy's initializer usable.

constructor() {
    _disableInitializers();
}

Quick Check

Test your understanding of upgradeable contracts.

Recap

You learned how upgradeable contracts work.

A proxy holds state and delegatecalls a swappable implementation.
Use initialize (guarded by initializer) instead of a constructor.
The Hardhat Upgrades plugin deploys and upgrades proxies safely.
Preserve storage layout: only append variables; use gaps.
Choose Transparent or UUPS, and protect upgrade authority with a multisig or timelock.

Frequently asked questions

Is the “Upgradeable Contracts” lesson free?

Yes — the full text of “Upgradeable Contracts” is free to read here on the web, and the Web3 & DApp Development Fundamentals course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Web3 & DApp Development Fundamentals course, upgrade to CoddyKit PRO.

What will I learn in “Upgradeable Contracts”?

Proxy patterns. You practise Web3 & DApp Development Fundamentals with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Web3 & DApp Development Fundamentals?

No prior experience is required. Web3 & DApp Development Fundamentals on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Upgradeable Contracts” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Web3 & DApp Development Fundamentals lesson?

Yes. Every Web3 & DApp Development Fundamentals lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Web3 & DApp Development Fundamentals