How to Deploy and Use Upgradeable Smart Contracts

In this comprehensive guide, we'll explore the fundamental design principles behind developing upgradeable smart contracts. By the end, you'll understand why and how to upgrade smart contracts, along with key considerations during the process. Our focus will be on Ethereum and EVM-based smart contracts.

Prerequisites

Before diving in, ensure you have:

Basic knowledge of blockchain fundamentals, especially Ethereum
Programming experience with Solidity and its compilation process
Familiarity with deployment tools like MetaMask and Hardhat

What Are Upgradeable Smart Contracts?

The Immutability Paradox

Blockchain's core principle of immutability means deployed smart contracts cannot be altered. However, upgrades become necessary to:

Fix critical bugs
Enhance functionality
Optimize gas efficiency
Adapt to market/technological changes
Avoid costly user migrations

The Proxy Pattern Solution

Smart contracts achieve upgradability through architectural patterns where:

A proxy contract (with a permanent address) handles state storage
A logic contract contains executable code that can be replaced

When users interact with the dApp:

All calls route through the proxy
The proxy delegates calls to the current logic contract via delegatecall
State remains in the proxy while execution occurs in the logic contract's context

Key Upgrade Patterns

1. Transparent Proxy Pattern

Most common approach (used by OpenZeppelin)
Distinguishes between admin and regular users:
- Admin calls: Handled by proxy's admin functions
- User calls: Delegated to logic contract
Prevents selector clashes between proxy/admin and logic functions

2. UUPS (EIP1822) Pattern

Upgrade logic resides in the logic contract (not the proxy)
More gas-efficient for deployment
Allows complete removal of upgradability
Requires careful inheritance management

3. Diamond Pattern (Advanced)

Supports multiple logic contracts ("facets")
Enables modular upgrades
Complex implementation

Hands-On Implementation

Project Setup

# Install dependencies
yarn add -D hardhat @openzeppelin/hardhat-upgrades @nomiclabs/hardhat-ethers ethers
yarn add @chainlink/contracts @openzeppelin/contracts-upgradeable

Sample Upgradeable Contract (V1)

// PriceFeedTrackerV1.sol
pragma solidity ^0.8.0;
import "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract PriceFeedTracker is Initializable {
    address private admin;
    
    function initialize(address _admin) public initializer {
        admin = _admin;
    }
    
    function getAdmin() public view returns (address) {
        return admin;
    }
    
    function retrievePrice() public view returns (int) {
        AggregatorV3Interface aggregator = AggregatorV3Interface(
            0xD4a33860578De61DBAbDc8BFdb98FD742fA7028e // ETH/USD feed
        );
        (,int price,,,) = aggregator.latestRoundData();
        return price;
    }
}

Deployment Script

// deploy_upgradeable_pricefeedtracker.js
const { ethers, upgrades } = require("hardhat");

async function main() {
    const PriceFeedTracker = await ethers.getContractFactory("PriceFeedTracker");
    const [account1] = await ethers.getSigners();
    
    const instance = await upgrades.deployProxy(
        PriceFeedTracker,
        [account1.address],
        { initializer: "initialize" }
    );
    
    console.log("Deployed to:", instance.address);
}
main();

👉 Learn more about proxy deployment

Upgrading to V2

Enhanced Contract Features

// PriceFeedTrackerV2.sol
contract PriceFeedTrackerV2 is Initializable {
    // Maintain existing storage layout
    address private admin;
    int public price; // New variable appended
    
    event PriceRetrieved(address feed, int price);
    
    function retrievePrice(address feed) public returns (int) {
        require(feed != address(0), "Invalid feed address");
        AggregatorV3Interface aggregator = AggregatorV3Interface(feed);
        (,int _price,,,) = aggregator.latestRoundData();
        price = _price;
        emit PriceRetrieved(feed, _price);
        return price;
    }
}

Upgrade Script

// upgrade_pricefeedtracker.js
const { ethers, upgrades } = require("hardhat");

async function main() {
    const PriceFeedTrackerV2 = await ethers.getContractFactory("PriceFeedTrackerV2");
    const upgraded = await upgrades.upgradeProxy(
        "0x...", // Existing proxy address
        PriceFeedTrackerV2
    );
    console.log("Upgrade complete");
}
main();

Best Practices

Storage Management:
- Never modify existing variable order
- Only append new variables
- Use gap pattern for future-proofing
Testing:
- Validate upgrades in testnet first
- Test all state migrations
- Verify historical data integrity
Security:
- Implement upgrade timelocks
- Use multi-sig for admin functions
- Consider removing upgradeability post-launch

FAQ

Why can't we directly modify deployed contracts?

Blockchain immutability prevents direct changes to deployed code. The proxy pattern separates storage and logic to enable controlled upgrades.

How does delegatecall enable upgrades?

delegatecall executes logic contract code in the proxy's context, maintaining state while allowing logic replacement.

What happens to old contract versions?

Previous logic contracts remain on-chain but unused. Only the proxy's referenced logic contract address changes.

👉 Explore advanced upgrade patterns

Conclusion

Upgradeable smart contracts provide necessary flexibility while maintaining blockchain's security principles. By implementing proper proxy patterns and following upgrade best practices, developers can build future-proof dApps capable of evolving with user needs and technological advancements.

Key takeaways:

Use standardized tools like OpenZeppelin Upgrades
Maintain strict storage layout discipline
Implement comprehensive upgrade testing
Consider long-term upgrade governance

For production deployments, always audit your upgrade mechanism and consider phased rollout strategies.