Verifying Proxy Contracts

Works on: Virtual Environments and public networks (mainnets and testnets). The same plugin handles both; point it at the right network in hardhat.config.ts.

This guide will walk you through proxy contract verification using @tenderly/hardhat-tenderly.

Requirements

Automatic proxy verification works out of the box on @tenderly/hardhat-tenderly:

>= 1.10.0 (Ethers 5 line)
>= 2.1.0 (Ethers 6 line)

npm update @tenderly/hardhat-tenderly

It only works when you deploy proxies with @openzeppelin/hardhat-upgrades. Hardhat Ignition is not supported for proxy verification yet. If you’re on a lower plugin version and can’t upgrade, use the manual workaround below.

Automatic verification

The plugin verifies three proxy patterns: TransparentUpgradeableProxy, UUPSUpgradeableProxy, and BeaconProxy.

Set the auto-populate flag

Under the hood the plugin drives @nomicfoundation/hardhat-verify with the @openzeppelin/hardhat-upgrades extension. Setting TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true lets the plugin populate @nomicfoundation/hardhat-verify’s verification URL for you.

TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true

Write deployment script

For a clearer view, you can check out this GitHub repo and go to scripts/proxy/ to see the full example.

Automatic

Deploy the proxy as usual using deployProxy from the @openzeppelin/hardhat-upgrades extension.

You must capture the object returned by the waitForDeployment function to interact with it further.

Under the hood, the automatic verification is implemented by wrapping the deployProxy, and waiting for completion of the deployment.

async function main() {
    console.log(
        "🖖🏽[ethers] Deploying TransparentUpgradeableProxy with VotingLogic as implementation on Tenderly.",
    );

    const VotingLogic = await ethers.getContractFactory("VotingLogic");
    let proxyContract = await upgrades.deployProxy(VotingLogic);
    proxyContract = await proxyContract.waitForDeployment();

    const proxyAddress = await proxyContract.getAddress();

    console.log("VotingLogic proxy deployed to:", proxyAddress);
    console.log(
        "VotingLogic impl deployed to:",
        await getImplementationAddress(ethers.provider, proxyAddress),
    );
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

Manual

Verifying the proxy with the manual verification method is done after the proxy contract has been deployed, by calling the tenderly.verify() function.

async function main() {
    console.log(
        "🖖🏽[ethers] Deploying TransparentUpgradeableProxy with VotingLogic as implementation on Tenderly.",
    );

    const VotingLogic = await ethers.getContractFactory("VotingLogic");
    let proxyContract = await upgrades.deployProxy(VotingLogic);
    proxyContract = await proxyContract.waitForDeployment();

    const proxyAddress = await proxyContract.getAddress();

    console.log("VotingLogic proxy deployed to:", proxyAddress);
    console.log(
        "VotingLogic impl deployed to:",
        await getImplementationAddress(ethers.provider, proxyAddress),
    );

    await tenderly.verify({
        name: ProxyPlaceholderName,
        address: proxyAddress,
    });
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});

Run the script

Virtual Environment

TENDERLY_AUTOMATIC_VERIFICATION=true \
TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true \
npx hardhat run scripts/deploy.ts

Public network

When deploying to a public mainnet or testnet, specify whether you want public or private verification.

TENDERLY_AUTOMATIC_VERIFICATION=true \
TENDERLY_AUTOMATIC_POPULATE_HARDHAT_VERIFY_CONFIG=true \
TENDERLY_PRIVATE_VERIFICATION=true \
npx hardhat run scripts/deploy.ts --network mainnet_base

Workaround for lower versions

When using @tenderly/hardhat-tenderly at versions < 1.10.0 and < 2.1.0, this workaround will enable automatic verification. You need to verify the following:

The proxy contract (e.g. OpenZeppelin’s proxies)
Implementation behind the proxy
Any dependencies the implementation has
New implementation instances deployed with upgrades

The verification process varies depending on the proxy contract type and the implementation.

Overview

In this guide, we’ll use an example Hardhat project and the @tenderly/hardhat-tenderly plugin to demonstrate the verification of OpenZeppelin’s UUPSUpgradeable, TransparentUpgradeableProxy, and BeaconProxy alternatives.

Proxy contracts need to be verified manually. Turn off automatic verification like so:

example.ts

// use manual verification
tenderly.setup({ automaticVerifications: false });

To obtain the address of the deployed implementation, use the @openzeppelin/upgrades-core package and getImplementationAddress function. Verifying the proxy implementation is usually straightforward; verify it just like any other contract.

example.ts

await tenderly.verify({
  // the new implementation contract
  name: 'VaultV2',
  // the address where implementation is deployed
  address: await getImplementationAddress(ethers.provider, await proxy.getAddress()),
});

To verify the proxy instance, you need to complete these two preliminary steps:

Load the exact smart contract of the proxy depending on the type of proxy you’re using, so it gets compiled. You’ll need to import the proxy contracts through the compiler by creating a dummy .sol file.
Modify hardhat.config.ts to specify the settings OpenZepplin contracts were compiled with.

Once these steps are completed, you can proceed to verify the proxy just as you would any other contract.

example.ts

await tenderly.verify({
  name: 'ERC1967Proxy', // or TransparentUpgradeableProxy or BeaconProxy
  address: await proxy.getAddress(),
});

Clone the example repo

git clone git@github.com:Tenderly/tenderly-examples.git
cd contract-verifications
npm i

Set up the Tenderly CLI

brew tap tenderly/tenderly && brew install tenderly
tenderly login

See the Tenderly CLI repo for non-Homebrew install options.

Configure Hardhat

In hardhat.config.ts, set tenderly.username and tenderly.project to your project and username slugs.

Create a Virtual Environment

The fastest way to deploy and verify contracts is on a Virtual Environment.

In the Tenderly Dashboard, open Virtual Environments and create a new one. Pick the base network to fork from and a Chain ID, then copy the Admin RPC URL from the Virtual Environment’s details page.

Add the RPC URL to your .env file:

TENDERLY_VIRTUAL_TESTNET_RPC=https://virtual.<network>.rpc.tenderly.co/<your-uuid>

Then reference it in hardhat.config.ts:

networks: {
  virtualMainnet: {
    url: process.env.TENDERLY_VIRTUAL_TESTNET_RPC!,
    chainId: 73571, // the Chain ID you set when creating the Virtual Environment
  },
},

For a full walkthrough see the Virtual Environment quickstart.

Run the tests

rm -rf .openzeppelin && npx hardhat test --network virtualMainnet

When redeploying contracts, remove the .openzeppelin folder first. It caches information about proxies and their implementations.

Load the proxy contracts

To verify the proxy contract, create a DummyProxy.sol file and import the OpenZepplin proxy contracts you’re working with. In doing so, these contracts are loaded and have passed through the compiler, enabling you to reference the exact contract source of the proxy during verification.

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


abstract contract ERC1967ProxyAccess is ERC1967Proxy {}
abstract contract UpgradableBeaconAccess is UpgradeableBeacon {}
abstract contract BeaconProxyAccess is BeaconProxy {}
abstract contract TransparentUpgradeableProxyAccess is TransparentUpgradeableProxy {}

Configure Solidity compiler overrides

The following overrides map was derived for @openzeppelin/contracts-upgradeable version 4.9.1. They may differ for other versions of the package.

After compiling Openzepplin’s proxy contracts, you also need to specify the following:

Version of the Solidity compiler that was used to compile the contracts

Optimization settings used by Openzepplin’s upgrades plugin when performing proxy deployment/upgrades

The hardhat-tenderly plugin uses both the source code of smart contracts and compiler settings for verification. If either of these settings is incorrect, the verification will fail.

Add the following overrides map to the config.solidity section of your Hardhat User config object.

const config: HardhatUserConfig = {
  solidity: {
    compilers: [{ version: '0.8.18' } /* OTHER COMPILER VERSIONS*/],
    overrides: {
      '@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol': {
        version: '0.8.9',
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
      '@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol': {
        version: '0.8.9',
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },

      '@openzeppelin/contracts/proxy/beacon/UpgradeableBeacon.sol': {
        version: '0.8.9',
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
      '@openzeppelin/contracts/proxy/beacon/BeaconProxy.sol': {
        version: '0.8.9',
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
      'contracts/proxy.sol': {
        version: '0.8.9',
        settings: {
          optimizer: {
            enabled: true,
            runs: 200,
          },
        },
      },
    },
  },
  /* OTHER CONFIG */
};

Verify by proxy type

These code samples show how to verify the implementation and the proxy for OpenZeppelin’s three proxy patterns. The examples use a proxied Vault contract that references an ERC-20 token (TToken).

UUPS proxy

To verify the UUPS proxy and the underlying information, call the hardhat-tenderly plugin twice:

To verify the implementation, you need to provide the following:

name of your proxied contract (in our case Vault)
Address where the contract was deployed using the getImplementationAddress method from @openzeppelin/upgrades-core.

To verify the proxy, provide the following:

ERC1967Proxy as the proxy contract name
Address of the proxy proxy.address

example.ts

await tenderly.verify(
  {
    name: 'Vault',
    address: await getImplementationAddress(ethers.provider, await proxy.getAddress()),
  },
  {
    name: 'ERC1967Proxy',
    address: await proxy.getAddress(),
  },
);

Complete Code Sample

Here’s a complete Hardhat test that does the following:

Deploys the TToken (needed for the vault)
Deploys Vault as a proxy, initialized with the TToken contract
Verifies the proxy (ERC1967Proxy) instance deployed at await proxy.getAddress()
Verifies the implementation instance Vault, deployed at getImplementationAddress(ethers.provider, await proxy.getAddress())
Upgrades the proxy to VaultV2

example.ts

describe('Vault', () => {
  it('uups proxy deployment and verification', async () => {
    const VaultFactory = await ethers.getContractFactory('Vault');
    const TokenFactory = await ethers.getContractFactory('TToken');

    let token = await ethers.deployContract('TToken');
    token = await token.waitForDeployment();
    const tokenAddress = await token.getAddress();

    await tenderly.verify({
      name: 'TToken',
      address: tokenAddress,
    });

    let proxy = await upgrades.deployProxy(VaultFactory, [tokenAddress], {
      kind: 'uups',
    });
    await proxy.waitForDeployment();
    const proxyAddress = await proxy.getAddress();

    console.log('Deployed UUPS ', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify(
      {
        name: 'Vault',
        address: await getImplementationAddress(ethers.provider, proxyAddress),
      },
      {
        name: 'ERC1967Proxy',
        address: proxyAddress,
      },
    );

    // upgrade
    const vaultV2Factory = await ethers.getContractFactory('VaultV2');
    proxy = (await upgrades.upgradeProxy(proxy, vaultV2Factory, {
      kind: 'uups',
    })) as Vault;

    await proxy.waitForDeployment();

    console.log('Upgraded UUPS ', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify({
      name: 'VaultV2',
      address: await getImplementationAddress(ethers.provider, proxyAddress),
    });
  });
});

Transparent proxy

To verify the UUPS proxy and the underlying information, call hardhat-tenderly while passing two contracts: Vault for the implementation, and TransparentUpgradeableProxy for the proxy itself.

example.ts

await tenderly.verify(
  {
    name: 'Vault',
    address: await getImplementationAddress(ethers.provider, await proxy.getAddress()),
  },
  {
    name: 'TransparentUpgradeableProxy',
    address: await proxy.getAddress(),
  },
);

To verify the implementation, provide the following:

name of your proxied contract (in our case Vault)
Address where the contract was deployed, using the getImplementationAddress method from @openzeppelin/upgrades-core.

To verify the proxy, provide the following:

TransparentUpgradeableProxy as the proxy contract name
Address of the proxy await proxy.getAddress()

Complete Code Sample

example.ts

describe('Vault', () => {
  it('transparent upgradable proxy deployment and verification', async () => {
    const VaultFactory = await ethers.getContractFactory('Vault');
    const TokenFactory = await ethers.getContractFactory('TToken');

    let token = await ethers.deployContract('TToken');
    token = await token.waitForDeployment();
    const tokenAddress = await token.getAddress();

    await tenderly.verify({
      name: 'TToken',
      address: tokenAddress,
    });

    let proxy = await upgrades.deployProxy(VaultFactory, [tokenAddress], {
      kind: 'transparent',
    });
    await proxy.waitForDeployment();
    const proxyAddress = await proxy.getAddress();

    console.log('Deployed transparent', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify(
      {
        name: 'Vault',
        address: await getImplementationAddress(ethers.provider, proxyAddress),
      },
      {
        name: 'TransparentUpgradeableProxy',
        address: proxyAddress,
      },
    );

    // upgrade
    const vaultV2Factory = await ethers.getContractFactory('VaultV2');

    proxy = (await upgrades.upgradeProxy(proxy, vaultV2Factory, {
      kind: 'transparent',
    })) as Vault;

    await proxy.waitForDeployment();

    console.log('Upgraded transparent ', {
      proxy: proxyAddress,
      implementation: await getImplementationAddress(ethers.provider, proxyAddress),
    });

    await tenderly.verify({
      name: 'VaultV2',
      address: await getImplementationAddress(ethers.provider, proxyAddress),
    });
  });
});

Beacon proxy

To verify the Beacon proxy and the underlying information, you have to verify two contracts: the Vault (implementation) and OpenZepplin’s UpgradableBeacon:

example.ts

await tenderly.verify(
  {
    name: 'Vault',
    address: await getImplementationAddressFromBeacon(ethers.provider, await beacon.getAddress()),
  },
  {
    name: 'UpgradeableBeacon',
    address: await beacon.getAddress(),
  },
);

Complete Code Sample

example.ts

describe('Vault', () => {
  it('beacon proxy deployment and verification', async () => {
    const VaultFactory = await ethers.getContractFactory('Vault');
    const TokenFactory = await ethers.getContractFactory('TToken');

    let token = await ethers.deployContract('TToken');
    token = await token.waitForDeployment();
    const tokenAddress = await token.getAddress();

    await tenderly.verify({
      name: 'TToken',
      address: tokenAddress,
    });

    let beacon = (await upgrades.deployBeacon(VaultFactory)) as UpgradeableBeacon;

    await beacon.waitForDeployment();
    const beaconAddress = await beacon.getAddress();

    let vault = await upgrades.deployBeaconProxy(beacon, VaultFactory, [tokenAddress], {
      initializer: 'initialize',
    });
    await vault.waitForDeployment();

    console.log('Deployed beacon ', {
      proxy: beaconAddress,
      implementation: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
      beacon: beaconAddress,
    });

    await tenderly.verify(
      {
        name: 'Vault',
        address: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
      },
      {
        name: 'UpgradeableBeacon',
        address: beaconAddress,
      },
    );

    const vaultV2Factory = await ethers.getContractFactory('VaultV2');

    // upgrade
    vault = await upgrades.deployBeaconProxy(beacon, vaultV2Factory, [tokenAddress]);

    await upgrades.upgradeBeacon(beaconAddress, vaultV2Factory, {});

    console.log('Upgraded beacon ', {
      proxy: beaconAddress,
      implementation: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
      beacon: beaconAddress,
    });

    await tenderly.verify({
      name: 'VaultV2',
      address: await getImplementationAddressFromBeacon(ethers.provider, beaconAddress),
    });
  });
});

​Requirements

​Automatic verification

​Workaround for lower versions

​Overview

​Verify by proxy type

​UUPS proxy

​Complete Code Sample

​Transparent proxy

​Complete Code Sample

​Beacon proxy

​Complete Code Sample

Requirements

Automatic verification

Workaround for lower versions

Overview

Verify by proxy type

UUPS proxy

Complete Code Sample

Transparent proxy

Complete Code Sample

Beacon proxy

Complete Code Sample