Migrating Hardhat project to ZKsync Era

Learn how to migrate an existing Hardhat project to ZKsync Era.

Prerequisites

  • Node.js version 18 or newer is required.
  • To ensure compatibility with our plugins, make sure that Hardhat version 2.16.0 or newer is installed in your project.

Project setup

The @matterlabs/hardhat-zksync plugin includes all the necessary tools to compile, test, deploy, and verify contracts on ZKsync.

Under the hood, this plugin bundles together several plugins that focus on specific features like compilation, deployment, and verification. You can learn more about each plugin in the Getting started section.
  1. Install the @matterlabs/hardhat-zksync plugin with:
    npm i -D @matterlabs/hardhat-zksync
  2. Import the plugin in the hardhat.config.ts file. If your project has multiple plugins, import @matterlabs/hardhat-zksync last:
    // Other Hardhat plugin imports above
import '@matterlabs/hardhat-zksync';
  3. Remove conflicting plugin imports
    • @nomicfoundation/hardhat-ethers: @matterlabs/hardhat-zksync includes hardhat-ethers extended with with support for ZKsync and non-ZKsync networks.
    • @openzeppelin/hardhat-upgrades: @matterlabs/hardhat-zksync includes hardhat-upgrades extended with support for ZKsync and non-ZKsync networks.
    • @nomicfoundation/hardhat-toolbox: this plugin includes @nomicfoundation/hardhat-ethers which can cause conflicts. Import necessary components separately excluding @nomicfoundation/hardhat-ethers.
    // import "@nomicfoundation/hardhat-toolbox"
// import "@nomicfoundation/hardhat-ethers"
// import "@openzeppelin/hardhat-upgrades"
import '@matterlabs/hardhat-zksync';
  4. Add the preferred ZKsync networks to the hardhat.config.ts file:
      defaultNetwork: 'zkSyncSepoliaTestnet',
  networks: {
    zkSyncSepoliaTestnet: {
      url: 'https://sepolia.era.zksync.dev',
      ethNetwork: 'sepolia',
      zksync: true,
      verifyURL: 'https://explorer.sepolia.era.zksync.dev/contract_verification',
    },
    zkSyncMainnet: {
      url: 'https://mainnet.era.zksync.io',
      ethNetwork: 'mainnet',
      zksync: true,
      verifyURL: 'https://zksync2-mainnet-explorer.zksync.io/contract_verification',
    },
    dockerizedNode: {
      url: 'http://localhost:3050',
      ethNetwork: 'http://localhost:8545',
      zksync: true,
    },
    inMemoryNode: {
      url: 'http://127.0.0.1:8011',
      ethNetwork: 'localhost', // in-memory node doesn't support eth node; removing this line will cause an error
      zksync: true,
    },
    hardhat: {
      zksync: true,
    },
  },
You can also add the zksync:true flag to the hardhat network.

Compilation

ZKsync Era (as well as other chains built with ZK Stack) is operated by the EraVM, which executes a specific bytecode that differs from the EVM. This bytecode is generated by the zksolc (for Solidity contracts) and zkvyper (for Vyper contracts) compilers.

To compile your contracts with these compilers, follow these steps:

  1. Run the compilation task targeting one of the ZKsync networks, which contain zksync: true:
    npx hardhat compile --network zkSyncSepoliaTestnet
  2. The following output indicates the contracts are being compiled with the zksolc compiler:
    Compiling contracts for ZKsync Era with zksolc v1.5.1 and zkvm-solc v0.8.17-1.0.1
Compiling 42 Solidity files
  3. The compiler generates the /artifacts-zk and /cache-zk folders containing the smart contract correspondent artifacts, which follow the same structure as the ones generated by the solc compiler.

Compiler settings

You can modify different compiler settings in the zksolc or zkvyper property inside the hardhat.config.ts file.

Non-inline Libraries

Deploying non-inline libraries on ZKsync differs from Ethereum.

On Ethereum, non-inlineable libraries must be deployed beforehand, and then referenced in the deployment transaction of the contract that imports them:

Ethereum non-inlineable libraries
const firstLibrary = await hre.ethers.deployContract("LibraryA");
await firstLibrary.waitForDeployment();
const firstLibraryAddress = await firstLibrary.getAddress()

const secondLibrary = await hre.ethers.deployContract("LibraryB");
await secondLibrary.waitForDeployment();
const secondLibraryAddress = await l2.getAddress();

const mainContract = await hre.ethers.deployContract("MainContract",{
  libraries:{
    LibraryA:firstLibraryAddress,
    LibraryB:secondLibraryAddress
  }
});

await mainContract.waitForDeployment();

On ZKsync, if your project contains non-inlineable libraries, the compilation command will throw an error.

To automatically deploy all non-inlineable libraries, follow these steps:

  1. Configure a deployer account in the ZKsync network you want to deploy by adding the accounts:[] property.
  2. Run the following command to deploy the libraries and auto-generate the libraries configuration in the hardhat.config.ts file:
    npx hardhat deploy-zksync:libraries

The command will add the libraries and their addresses to the hardhat.config.ts file.

  1. Now you can compile the main contract that imports the libraries and deploy the contract without the need to reference the libraries:
deploy.ts
import * as hre from 'hardhat';

export default async function () {
  const mainContract = await hre.ethers.deployContract('Main');
  await mainContract.waitForDeployment();
  console.log('Main contract deployed to:', mainContract.target);
}

Troubleshoting

Use of unsupported opcodes like SELFDESTRUCT or EXTCODECOPY. The compiler will throw an error if any unsupported opcodes is used in one of the contracts. See differences with EVM opcodes in EVM instructions.

Testing

ZKSync provides different EraVM node implementations to test smart contracts locally:

  • In-Memory Node: fast L2 node with non-persistent state.
  • Dockerized setup: L1 and L2 nodes with persistent state but slower performance.

Unless your project contains L1-L2 features, testing with the In-Memory Node is recommended, which is included in the @matterlabs/hardhat-zksync plugin.

In version 1.0.12, hardhat-network-helpers introduced support for both In-Memory Node and Dockerized setups, allowing methods such as loadFixture to be utilized in test files.

You can read more about each node in the Testing section of the docs.

Running unit tests on In-Memory Node

To run tests using In-Memory Node, follow these steps:

  1. Add the zksync:true flag to the hardhat network in the hardhat.config.ts file to override Hardhat's default node with ZKsync In-Memory Node.
  2. Run the test task with npx hardhat test --network hardhat (or make hardhat the default network).

You can find more info about testing with the In-Memory-Node in Hardhat-ZKsync node.

Running tests on Dockerized setup

To run tests on the Dockerized local setup, follow these steps:

  1. Run npx zksync-cli dev config and select the “Dockerized node” option.
  2. Run npx zksync-cli dev start to start the L1 and L2 nodes.
  3. Add the Dockerized nodes to the list of networks in the hardhat.config.ts file:
hardhat.config.ts
networks: {
    dockerizedNode: {
      url: 'http://localhost:3050',
      ethNetwork: 'http://localhost:8545',
      zksync: true,
    },
  // Other networks

}
  1. Make sure the providers in your test files target the correct url.
  2. Run the test task with npx hardhat test --network dockerizedNode.

Deployment

Smart contract deployment on ZKsync Era (and chains built with ZK Stack) differ from Ethereum as they are handled by the ContractDeployer system contract (see Ethereum differences).

There are different approaches for contract deployment:

Deployment with hardhat-ethers

The @matterlabs/hardhat-zksync includes @matterlabs/hardhat-zksync-ethers, a package that extends @nomiclabs/hardhat-ethers with all the necessary helper methods to deploy contracts on both ZKsync and EVM networks. The injected hre.ethers object provides methods like deployContract, getContractFactory or getContractAt so deployment scripts work out of the box.

To avoid typescript collision errors between @nomiclabs/hardhat-ethers and @matterlabs/hardhat-zksync-ethers make sure that only the latter (or the wrapper plugin @matterlabs/hardhat-zksync) is imported in the hardhat.config.ts file.

See below examples for hardhat-ethers and hardhat-zksync-ethers:

  const greeter = await hre.ethers.deployContract('Greeter', ['Hi there!']);
  await greeter.waitForDeployment();

When a custom deployment is needed, use ContractFactory.

  const GreeterFactory = await hre.ethers.getContractFactory('Greeter');
  const greeterContract = await GreeterFactory.deploy('Hi there!'); // if any, pass constructor arguments in deploy arguments
  await greeterContract.waitForDeployment();

Deployment with hardhat-deploy

The newest versions of the hardhat-deploy plugin (beginning with 0.11.26) now support ZKsync deployments out of the box. This means you don't need to modify your deployment scripts and methods like getNamedAccounts can be used on ZKsync.

Deployment with hardhat-viem

To be included.

Deployment with Hardhat ignition

Hardhat ignition scripts do not support deployments to ZKsync Era yet. Please use other options like hardhat-deploy or hardhat-ethers

Deploying proxy contracts

The @matterlabs/hardhat-zksync includes @matterlabs/hardhat-zksync-upgradable, which extends @openzeppelin/hardhat-upgrades with all the necessary methods to deploy and upgrade proxy contracts on ZKsync and EVM networks.

The injected hre.upgrades object provides methods like deployProxyor deployBeacon so deployment scripts work out of the box.

To avoid typescript collision errors between @openzeppelin/hardhat-upgrades and @matterlabs/hardhat-zksync-upgradable make sure that only the latter (or the wrapper plugin @matterlabs/hardhat-zksync) is imported in the hardhat.config.ts file.

See examples below:

Transparent proxy (deployment)

const constructorArguments = [...];
const initializerFunctionName = 'initialize'
const boxFactory = await hre.ethers.getContractFactory("Box");
const box = await hre.upgrades.deployProxy(boxFactory, constructorArguments, {
   initializer: initializerFunctionName,
});
await box.waitForDeployment();

Transparent proxy (upgrade)

const constructorArguments = [...];
const upgradableProxyAddress = "UPGRADEABLE_PROXY_ADDRESS";
const boxV2ContractFactory = await hre.ethers.getContractFactory("BoxV2");
const boxV2 = await hre.upgrades.upgradeProxy(upgradableProxyAddress,boxV2ContractFactory);
await boxV2.waitForDeployment();

Beacon proxy (deployment)

const constructorArguments = [...];
const boxFactory = await hre.ethers.getContractFactory("Box");
const box = await hre.upgrades.deployBeacon(boxFactory, constructorArguments);
await box.waitForDeployment();

Beacon proxy (upgrade)

const upgradableProxyAddress = "UPGRADEABLE_PROXY_ADDRESS";
const boxV2ContractFactory = await hre.ethers.getContractFactory("BoxV2");
const boxV2 = await hre.upgrades.upgradeBeacon(upgradableProxyAddress, boxV2ContractFactory);
await boxV2.waitForDeployment();

UUPS proxy (deployment)

const constructorArguments = [...];
const initializerFunctionName = 'initialize'
const boxFactory = await hre.ethers.getContractFactory("Box");
const box = await hre.upgrades.deployProxy(boxFactory, constructorArguments, {
   initializer: initializerFunctionName,
});
await box.waitForDeployment();

UUPS proxy (upgrade)

const constructorArguments = [...];
const upgradableProxyAddress = "UPGRADEABLE_PROXY_ADDRESS";
const boxV2ContractFactory = await hre.ethers.getContractFactory("BoxV2");
const boxV2 = await hre.upgrades.upgradeProxy(upgradableProxyAddress,boxV2ContractFactory);
await boxV2.waitForDeployment();

Custom deployment scripts with hardhat-zksync

Additionally, you can write custom deployment scripts for ZKsync leveraging the hre.deployer object which is injected automatically by @matterlabs/hardhat-zksync-deploy. The Deployer class provides helper methods to deploy smart contracts to ZKsync. Learn more on hardhat-zksync-deploy methods.

Troubleshoting

  • Contract size too large: if the size of the generated bytecode is too large and can not be deployed, try compiling the contract with the mode: 3 flag in the hardhat.config.ts file to optimize the bytecode size on compilation. Learn more on hardhat-zksync-solc configuration.

Smart contract verification

There are no differences in the verification of smart contracts on ZKsync.

By installing @matterlabs/hardhat-zksync, a verification plugin is provided.

You will have to add a verifyURL on the ZKsync networks in the hardhat.config.ts file:

  zkSyncSepoliaTestnet: {
    url: "https://sepolia.era.zksync.dev",
    ethNetwork: "sepolia",
    zksync: true,
    verifyURL: 'https://explorer.sepolia.era.zksync.dev/contract_verification'
  },
  zkSyncMainnet: {
    url: "https://mainnet.era.zksync.io",
    ethNetwork: "mainnet",
    zksync: true,
    verifyURL: "https://zksync2-mainnet-explorer.zksync.io/contract_verification",
  },

You can run the verification task programmatically inside a script as follows:

const verificationId = await hre.run("verify:verify", {
  address: contractAddress,
  contract: contractFullyQualifedName,
  constructorArguments: [...]
});

Alternatively you can execute the verification task from your terminal:

npx hardhat verify --network testnet 0x7cf08341524AAF292255F3ecD435f8EE1a910AbF "Hi there!"

Find more info in hardhat-zksync-verify.

Scripting

Most scripts will work out of the box as interacting with smart contracts deployed on ZKsync is exactly the same as on any EVM chain.

For ZKsync-specific features like native account abstraction or paymaster transactions, there are plugins or extensions for the most popular libraries:

For other programming languages, please refer to the SDK documentation.

Multichain projects

The following example project can be used as a reference to target both EVM and ZKsync chains.

Here are some recommendations for projects that target multiple chains:

  • Add the desired ZKsync networks with the zksync:true flag to the hardhat.config.ts.
  • Make sure to run the compilation task with the --network flag when targeting ZKsync networks to use the custom compiler.
  • When targeting ZKsync chains, the @matterlabs/hardhat-zksync plugin overrides the following plugins: @nomiclabs/hardhat-ethers, @openzeppelin/hardhat-upgrades.
  • To avoid typescript collision errors between @nomiclabs/hardhat-ethers and @openzeppelin/hardhat-upgrades with @matterlabs/hardhat-zksync make sure that only the latter is imported in the hardhat.config.ts file.
  • Your deployment scripts should not require any changes if you're using hardhat-deploy or hardhat-ethers.
  • If you have a separate directory for ZKsync deployment scripts, you can indicate the custom deployment folder for the ZKsync network using the deployPaths property:
const config: HardhatUserConfig = {
  networks: {
    zksyncTestnet: {
      url: "https://sepolia.era.zksync.dev",
      ethNetwork: "sepolia",
      zksync: true,
      // ADDITION
      deployPaths: "deploy-zksync", //single deployment directory
      deployPaths: ["deploy", "deploy-zksync"], //multiple deployment directories
    },
  },
};

Support

If you're having issues migrating a Hardhat project to ZKsync, please reach out to us by creating a GitHub discussion.

Getting started

Learn how to use Hardhat with ZKsync.

Compiling non-inlinable libraries

Learn how to handle compiling non-inlinable libraries.

Made with ❤️ by the ZKsync Community