Upgradable Smart Contracts

Build, deploy, and upgrade proxy contracts with Hardhat and OpenZeppelin Upgrades. Replace contract logic while preserving its address and state.

Smart contracts are immutable: once deployed, the code cannot be changed, only the state. That is a problem when you need to fix a bug, add a feature, or meet a new requirement. An upgradable contract puts the logic behind a proxy, so you can replace the logic while the address and the state stay the same.

This guide shows you how to build, deploy, and upgrade such a contract with OpenZeppelin’s Upgrades plugin and Hardhat.

Prerequisites

• You have deployed a contract with Hardhat before.
• You can read JavaScript.

Instructions

Building an Upgradable Smart Contract

Deployment goes through OpenZeppelin’s deployProxy.

1. Install upgrades plugin

In your Hardhat project, install the OpenZeppelin package that holds the upgrade logic:

npm install --save-dev @openzeppelin/hardhat-upgrades@^3

Then require it in hardhat.config.js:

// hardhat.config.js
...
require('@openzeppelin/hardhat-upgrades');
...
module.exports = {
...
};

2. Create the contract

Place this SimpleStorage.sol in the contracts/ directory of your project:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract SimpleStorage {
    uint256 private data;
    
    // Emitted when the stored value changes
    event ValueChanged(uint256 _data);

    function set(uint256 _data) public {
        data = _data;
        emit ValueChanged(_data);
    }

    function get() public view returns (uint256) {
        return data;
    }
}

3. Write the deployment script

The deployment script goes in scripts/, not in ignition/modules/. Create scripts/upgrade_storage.js with the following code:

// scripts/upgrade_storage.js
const { ethers, upgrades } = require('hardhat');

async function main () {
  const SimpleStorage = await ethers.getContractFactory('SimpleStorage');
  console.log('Deploying SimpleStorage...');
  const simple_storage = await upgrades.deployProxy(SimpleStorage, [10], { initializer: 'set' });
  await simple_storage.waitForDeployment();
  console.log('SimpleStorage deployed to:', await simple_storage.getAddress());
}

main();

4. Deploy the contract

Upgradable contracts are deployed with npx hardhat run, not with ignition deploy:

npx hardhat run --network agung scripts/upgrade_storage.js

The script prints the proxy address. Save it, that is the address you keep using.

5. Interact with the contract

Open the Hardhat console:

npx hardhat console --network agung

Then check the deployment. Replace 0xYourProxyAddress with the proxy address printed by your deployment script:

Welcome to Node.js v22.4.1.
Type ".help" for more information.
> const SimpleStorage = await ethers.getContractFactory('SimpleStorage')
undefined
> const simple_storage = await SimpleStorage.attach('0xYourProxyAddress');
undefined
> (await simple_storage.get()).toString();
'10'

The stored value is 10, so the proxy was initialized correctly.

Upgrade previously deployed contract

Now add a feature to the deployed contract: incrementing the stored value.

1. Create a new contract

Create a second Solidity contract in contracts/ called SimpleStorageV2:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract SimpleStorageV2 {
    uint256 private data;
    
    // Emitted when the stored value changes
    event ValueChanged(uint256 _data);

    function set(uint256 _data) public {
        data = _data;
        emit ValueChanged(_data);
    }

    function get() public view returns (uint256) {
        return data;
    }

    // new function added
    function increment() public {
        data = data + 1;
        emit ValueChanged(data);
    }
}

The contract is the same as the first one, with a different name and the added increment function.

2. Upgrade previously deployed contract

OpenZeppelin’s upgradeProxy points the existing proxy at the new logic. Create scripts/upgrade_storagev2.js:

// scripts/upgrade_storagev2.js
const { ethers, upgrades } = require('hardhat');

async function main () {
  const SimpleStorageV2 = await ethers.getContractFactory('SimpleStorageV2');
  console.log('Upgrading SimpleStorage...');
  await upgrades.upgradeProxy('0xYourProxyAddress', SimpleStorageV2); // Replace with your deployed proxy address
  console.log('SimpleStorage upgraded');
}

main();

3. Run the upgrade

Run the upgrade script against the same network:

$ npx hardhat run --network agung scripts/upgrade_storagev2.js

Upgrading SimpleStorage...
SimpleStorage upgraded

The proxy now runs the new logic, at the same address and with the same state.

4. Interact with the contract

Back in the Hardhat console, increment() is callable. Use the same deployed proxy address in place of 0xYourProxyAddress:

npx hardhat console --network agung

Welcome to Node.js v22.4.1.
Type ".help" for more information.
> const SimpleStorageV2 = await ethers.getContractFactory('SimpleStorageV2');
undefined
> const simple_storage = await SimpleStorageV2.attach('0xYourProxyAddress');
undefined
> await (await simple_storage.increment()).wait();
...
> (await simple_storage.get()).toString();
'11'

The contract kept its address and its stored value across the upgrade, and the value only changed when increment() was called. For how proxies do this, see the OpenZeppelin documentation.