hardhat-zksync-verify

Description

The @matterlabs/hardhat-zksync-verify plugin enables smart contract verification on both ZkSync Era Explorer and Etherscan. It extends Hardhat's functionality to support ZKsync-specific contract verification workflows and integrates seamlessly with the ZKsync Era ecosystem.

Key features:

• Dual verification support for both ZkSync Era Explorer and Etherscan
• Automatic verification endpoint resolution
• Support for contracts with complex constructor arguments
• Programmatic verification capabilities

Resources:

• NPM Package
• GitHub Repository
• Changelog

Installation

Prerequisites

• Node.js version 18 or higher
• Hardhat version 2.16.0 or higher

Setup

Install the plugin and its dependencies:

yarn add -D @matterlabs/hardhat-zksync-verify @nomicfoundation/hardhat-verify

Import the package in your hardhat.config.ts file:

import "@matterlabs/hardhat-zksync-verify";

Configuration

Configuration Options

Example Configuration

// hardhat.config.ts
import { HardhatUserConfig } from "hardhat/config";
import "@matterlabs/hardhat-zksync-verify";

const config: HardhatUserConfig = {
  defaultNetwork: "zkTestnet",
  networks: {
    zkTestnet: {
      url: "https://sepolia.era.zksync.dev",
      ethNetwork: "sepolia",
      zksync: true
    }
  },
  // Etherscan verification configuration (optional)
  etherscan: {
    apiKey: "YOUR_API_KEY",
  }
};

export default config;

Verification Methods

Starting from version 1.7.0, the plugin supports both ZKsync Block Explorer and Etherscan verification. Earlier versions only support ZKsync Block Explorer verification.

ZkSync Block Explorer Verification

The plugin automatically verifies contracts on the ZKsync Block Explorer by default. This is the standard verification method when no Etherscan configuration is provided.

// hardhat.config.ts
const config: HardhatUserConfig = {
  networks: {
    zkTestnet: {
      url: "https://sepolia.era.zksync.dev",
      ethNetwork: "sepolia",
      zksync: true
    }
  }
};

You can customize the Block Explorer verification behavior using these optional parameters:

• verifyURL: Custom verification API endpoint
• browserVerifyURL: Custom verification result page URL
• enableVerifyURL: Force Block Explorer verification even when Etherscan is configured

Etherscan Verification

To enable Etherscan verification, add the Etherscan configuration to your hardhat.config.ts:

// hardhat.config.ts
const config: HardhatUserConfig = {
  networks: {
    zkTestnet: {
      url: "https://sepolia.era.zksync.dev",
      ethNetwork: "sepolia",
      zksync: true
    }
  },
  etherscan: {
    apiKey: "YOUR_API_KEY",
  }
};

The plugin provides pre-configured chain settings for:

• zksyncsepolia: ZKsync Era Sepolia testnet
• zksyncmainnet: ZKsync Era Mainnet

To obtain an API key:

1. Visit the ZKsync Etherscan
2. Create an account or sign in
3. Navigate to the API section
4. Generate a new API key

Additions

Added Tasks

• verify: Main verification task for contract verification
• verify:verify: Programmatic verification task

Added HRE Extensions

• Verification status checking functionality
• Constructor arguments handling

Commands

yarn hardhat verify [options] <contract-address> [constructor-arguments...]

Options:

• --network <network-name>: (Required) Network to verify the contract on
• --contract <fully-qualified-name>: (Optional) Specify contract to verify (format: "contracts/Contract.sol:ContractName")
• --constructor-args <file>: (Optional) File with constructor arguments
• --libraries <library-addresses>: (Optional) Specify library addresses

Usage

Basic Contract Verification

yarn hardhat verify --network zkTestnet 0x1234567890123456789012345678901234567890

Verification with Constructor Arguments

yarn hardhat verify --network zkTestnet 0x1234567890123456789012345678901234567890 "Constructor arg 1" "Constructor arg 2"

Using Constructor Arguments File

// arguments.js
module.exports = [
  "arg1",
  "0x242...",
  42
];

yarn hardhat verify --network zkTestnet 0x1234567890123456789012345678901234567890 --constructor-args arguments.js

Programmatic Verification

const verificationId = await hre.run("verify:verify", {
  address: contractAddress,
  contract: "contracts/MyContract.sol:MyContract",
  constructorArguments: ["arg1", "arg2"]
});

Verification Status Check

The verification process consists of two steps:

1. A verification request is sent to confirm if the given parameters for your contract are correct
2. The verification status of that request is checked

Both steps run automatically when you execute the verify task, and you'll receive a verification request ID for reference.

Troubleshooting

Unknown zksolc Version

If you encounter an "Unknown zksolc version" error:

• This indicates that the verification system doesn't support your compiler version
• Solution: Use a previous version of the compiler until the backend is updated

Common Issues

1. Verification Failure
   • Ensure contract source matches deployed bytecode exactly
   • Check constructor arguments are correct
   • Verify compiler version matches deployment
2. Network Configuration
   • Confirm RPC URLs are accessible
   • Verify network configuration matches deployment network
   • Check API keys are valid if using Etherscan verification
3. Compiler Version Mismatch
   • Make sure the compiler version used for deployment matches the verification
   • For zksolc compiler, use a supported version as specified in the error message
4. API Key Issues
   • Verify API key is valid and has not expired
   • Ensure you're using the correct API key for the target network

For more help, please refer to the GitHub issues.