How to Deploy with Proxies

Proxies enable contract upgrades by separating logic and storage. This guide covers deploying upgradeable contracts using hardhat-deploy's proxy features.

Prerequisites

Install the proxy extension:

npm

npm install -D @rocketh/proxy

pnpm

pnpm add -D @rocketh/proxy

Add it to your rocketh/config.ts:

import * as proxyExtensions from '@rocketh/proxy';
import * as deployExtensions from '@rocketh/deploy';

const extensions = {...deployExtensions, ...proxyExtensions};
export {extensions};

Proxy Types

hardhat-deploy supports several proxy patterns:

1. Transparent Proxy (OpenZeppelin)

• Admin can upgrade, users can call functions
• Gas overhead on every call
• Most secure for production

2. UUPS (Universal Upgradeable Proxy Standard)

• Upgrade logic in implementation contract
• Lower gas costs
• Implementation must include upgrade functionality

3. Beacon Proxy

• Multiple proxies share same implementation
• Efficient for deploying many identical contracts

Basic Proxy Deployment

Transparent Proxy

import { deployScript, artifacts } from "../rocketh/deploy.js";

export default deployScript(
  async ({ deployViaProxy, namedAccounts }) => {
    const { deployer, admin } = namedAccounts;

    await deployViaProxy(
      "MyContract", // Contract name
      {
        account: deployer,
        artifact: artifacts.Greeter,
        args: ["initialValue"], // Constructor arguments
      },
      {
        owner: admin, // Proxy admin
        proxyContract: "SharedAdminOptimizedTransparentProxy", // Proxy type
      }
    );
  },
  { tags: ["MyContract"] }
);

UUPS Proxy

import { deployScript, artifacts } from "../rocketh/deploy.js";

export default deployScript(
  async ({ deployViaProxy, namedAccounts }) => {
    const { deployer, admin } = namedAccounts;

    await deployViaProxy(
      "MyUUPSContract",
      {
        account: deployer,
        artifact: artifacts.MyUUPSContract,
        args: [admin, "initialValue"],
      },
      {
        owner: admin,
        proxyContract: "UUPS", // UUPS proxy type
        execute: "initialize", // Initialization function
      }
    );
  },
  { tags: ["MyUUPSContract"] }
);

Contract Upgrades

Upgrading Implementation

When you modify your contract and redeploy, hardhat-deploy automatically detects changes and upgrades the implementation:

// After modifying your contract source code:
// 1. Recompile: npx hardhat compile
// 2. Redeploy: npx hardhat deploy

// hardhat-deploy will:
// - Detect that the implementation bytecode has changed
// - Deploy a new implementation contract
// - Call upgradeToAndCall (or upgrade) on the proxy
// - Keep the same proxy address and storage

Checking for Upgrades

You can also check if an upgrade is needed before deploying:

import { deployScript, artifacts } from "../rocketh/deploy.js";

export default deployScript(
  async ({ deployViaProxy, namedAccounts }) => {
    const { deployer, admin } = namedAccounts;

    const result = await deployViaProxy(
      "MyContract",
      {
        account: deployer,
        artifact: artifacts.MyContract,
        args: ["initialValue"],
      },
      {
        owner: admin,
        proxyContract: "SharedAdminOptimizedTransparentProxy",
      }
    );

    if (result.newlyDeployed) {
      console.log("Contract was upgraded or newly deployed");
    } else {
      console.log("Contract unchanged, no upgrade needed");
    }
  },
  { tags: ["MyContract"] }
);

Advanced Proxy Patterns

Initialization Function

For contracts that need initialization after deployment:

import { deployScript, artifacts } from "../rocketh/deploy.js";

export default deployScript(
  async ({ deployViaProxy, namedAccounts }) => {
    const { deployer, admin } = namedAccounts;

    await deployViaProxy(
      "MyContract",
      {
        account: deployer,
        artifact: artifacts.Greeter,
        args: [""], // No constructor args
      },
      {
        owner: admin,
        proxyContract: "SharedAdminOptimizedTransparentProxy",
        execute: {
          methodName: "initialize",
          args: [admin, deployer, 1000], // Initialization parameters
        },
      }
    );
  },
  { tags: ["MyContract"] }
);

Next Steps

• Deploy Diamond Contracts for modular upgrades
• Deployment Fixtures in Tests for testing proxy deployments