Deploying to ZKcandy | ZKcandy Lite Paper

Prefer a more visual deployment process? Deploying contracts to ZKcandy ZKEVM is now easier with the Nethermind ZKsync Pugin for the Remix IDE. Read this blog post to find out more.

💡

This document addresses a more advanced way of deploying contracts to the native ZKEVM of ZKcandy. As of June 2025, you can now deploy contracts to ZKcandy using most EVM tooling. Follow this link for a simpler contract deployment method.

The ZKcandy Sepolia Testnet has been deprecated as of June 2025. Please use the ZKsync Sepolia Testnet for all testing purposes moving forward.

This document will cover deploying contracts to both the ZKcandy Mainnet and the ZKsync Sepolia Testnet. We strongly encourage testing your contracts on the ZKsync Sepolia Testnet before deploying to our mainnet.

There are multiple ways to deploy contracts to ZKcandy. As such, the methods covered in this document is not an exhaustive list.

We will be using @matterlabs/hardhat-zksync-deploy - part of the ZKsync plugin set for the Hardhat development environment.

This plugin provides utilities for deploying smart contracts on ZKsync Era and by extension, ZKcandy with artifacts built by the @matterlabs/hardhat-zksync-solc or @matterlabs/hardhat-zksync-vyper plugins.

Prerequisites

A Node installation with package manager. We recommend npm

zksync-cli to prepare your development environment

Your wallet private key

Ether for gas fees

This method of deployment requires the use of your wallet private key in your project’s environment variables. When testing, do not use a wallet with mainnet funds on any blockchain, not just ZKcandy or ZKsync Era. For the purposes of this document, this secret will be stored in a .env file. It is imperative that this file is never committed to any version control system.

Local Testing

To test your contract with a local node, refer to this page in the zkSync CLI Documentation on how to start a local node. zksync-cli will create both an Ethereum and ZKsync node on your machine. As ZKcandy is on parity with ZKsync Era, you should test your contracts on the local ZKsync node.

Initialisation

To initialise your deployment environment, install zksync-cli to prepare your environment with Hardhat.


npm install zksync-cli

You can use the -g flag to install zksync-cli globally onto your system.


npm install -g zksync-cli

If you have already installed zksync-cli on your system, update it to the latest version.


npm update -g zksync-cli

Setting Up

Replace the projectFolder in the command below with the name you wish to use for your project folder. You can also replace hardhat_solidity with hardhat_vyper if you are deploying a contract written in Vyper.


npx zksync-cli create projectFolder --template hardhat_solidity

The zksync-cli command requires that the path to your project folder as well as the name of the project folder itself does not contain spaces. If you get a git clone error, move your working folder to a location where its path contains no spaces. You can move your working folder back once the template is initialised.

You will be prompted to enter your wallet private key after entering the command. If you don’t have this available now, press Enter to proceed with installing the environment first. You can enter your wallet private key into the project environment variables later.

You may also be prompted to select your package manager for Node. For the purposes of this document we will be using npx.

This command will install hardhat and other dependencies, including the relevant contract compilers into your project folder.

From this point onwards, you will be operating from your project folder. Switch into your folder using the following command, once again replacing projectFolder with the name of your project folder.


cd projectFolder

Inside the project folder, there is contracts directory with some example contracts. To make your workflow faster, you can delete these example files and folders now.

Configuring Your Environment

Add the hardhat-zksync-deploy plugin to your project using the following command:


npm install --save-dev hardhat @matterlabs/hardhat-zksync-deploy@^0.11.0 @nomiclabs/hardhat-ethers ethers@^5.7.2 zksync-ethers@^5.10.0 --legacy-peer-deps

After adding the plugin, you will find a hardhat.config.ts file in the root of your project folder. Edit this file to add the ZKcandy Mainnet and ZKsync Testnet RPC endpoints as follows. You may also paste its contents and overwrite your existing hardhat.config.ts


import { HardhatUserConfig } from "hardhat/config";
import "@matterlabs/hardhat-zksync-deploy";
import "@matterlabs/hardhat-zksync-solc";
import "@matterlabs/hardhat-zksync-verify";
import "@nomiclabs/hardhat-ethers";

// Define the ZKsync networks

const ZKcandyMainnet = {
  url: "https://rpc.zkcandy.io",
  ethNetwork: "mainnet",
  zksync: true,
  verifyURL: "https://contracts.zkcandy.io/contract_verification",
};

const ZKsyncTestnetSepolia = {
  url: "https://sepolia.era.zksync.dev",
  ethNetwork: "sepolia",
  zksync: true,
  verifyURL: "https://explorer.sepolia.era.zksync.dev/contract_verification",
};

const config: HardhatUserConfig = {
  zksolc: {
    version: "1.5.10",
    compilerSource: "binary",
    settings: {
      codegen: "yul",
      optimizer: {
        enabled: true,
        mode: "z",
      },
    },
  },
  defaultNetwork: "ZKcandyMainnet",
  networks: {
    hardhat: {
      zksync: false,
    },
    ZKcandyMainnet: ZKcandyMainnet,
    ZKsyncTestnetSepolia: ZKsyncTestnetSepolia,
  },
  solidity: {
    version: "0.8.26",
  },
};

export default config;

zksync is a flag that indicates if the network is using the ZK Stack (e.g. ZKsync Era, ZKcandy). This field needs to be set to true for ZKcandy as it is false by default.

ZKcandyMainnet is a label for the ZKcandy Mainnet. You can select this as the default network using the defaultNetwork property. This will be overridden by --network arguments passed when using the deploy command below.

If you wish to use a different version of zksolc to compile your smart contract, you may run the following command to retrieve the latest list of zksolc versions that are compatible with contract source code verification on our Block Explorer:

curl https://contracts.zkcandy.io/contract_verification/zksolc_versions

Compiling and Preparing Your Contract(s)

Load your contract into your environment by copying it to the contracts folder in the root of your project folder.

You will find some example contracts inside the contracts folder. You can safely delete these files and/or folders if you do not wish to use them.

Compiling Your Contract

Run the following command to compile your contract for ZKcandy:


npx hardhat compile

If successful, your contract bytecode should now be available in the in the artifacts-zk folder in the root of your project folder.

Deployment Script

Create a new folder called deploy in the root of your project folder, then create a new file called deploy.ts. Paste the following into the contents of this file you just created.


import { Wallet, Deployer } from "@matterlabs/hardhat-zksync-deploy";
import { HardhatRuntimeEnvironment } from "hardhat/types";
import * as hre from "hardhat";
import * as dotenv from "dotenv";
dotenv.config();

export default async function (hre: HardhatRuntimeEnvironment) {
  const wallet = new Wallet(process.env.WALLET_PRIVATE_KEY!);

  // Initialize deployer
  const deployer = new Deployer(hre, wallet);

  // Load the compiled artifact. Replace MyContract with your contract name.
  const artifact = await deployer.loadArtifact("MyContract");

  // Deploy the contract (pass constructor args if needed)
  const contract = await deployer.deploy(artifact, [
    // constructor arguments go here, e.g., "Hello"
  ]);

  console.log(`✅ Contract deployed at: ${contract.address}`);
}

Replace “MyContract” with the name of the contract you compiled (this is not necessarily the contract filename).

If you contract has a constructor, pass constructor arguments in the empty object pointed out in the script above.

You are now ready to deploy your contract.

For complete documentation on how to use deployment scripts, please refer to the official documentation from ZKsync.

Deploying Your Contract(s)

Deploying to Testnet

If you did not input your wallet private key during the setup or if you wish to change your wallet key, open the .env file in the root of your project folder and enter your private key as the value of the WALLET_PRIVATE_KEY variable.

Your .env file should look like the following:


WALLET_PRIVATE_KEY=0xfef8f1cde581a92798d908df430d9fe9aa90c59a0230b7e6361de4e0be698baf
// Make sure to replace the private key above with your deployment wallet private key.

If your private key does not start with 0x , you will need to append 0x in order for it to work.

You will need Test Ether on the ZKsync Sepolia Testnet in order to proceed. Please fund your wallet adequately before proceeding.

Run the following command to initiate the deployment process:

⚠️

This command will deploy your contract to the ZKsync Sepolia Testnet.

There is no confirmation prompt after executing this command. You cannot undo this step once your contract is deployed. Please make sure you have completed all desired unit testing and that the constructor arguments in your deploy.ts script are correct before proceeding.


yarn hardhat deploy-zksync --script deploy.ts --network ZKsyncTestnetSepolia

Your machine will now attempt to deploy the contract to the ZKsync Sepolia Testnet. If successful, the program will return the contract address of your newly deployed contract.

📝

Make a note of your contract address in the terminal printout.

If your contract source code does not pass verification for any reason, your deployed contract address may not be visible on the block explorer. Make sure you take note of your deployed contract addresses.

The deploy script will also attempt to upload verify your contract source code on the ZKsync Sepolia Testnet block explorer.

You can now call functions and test your contract on the ZKsync Sepolia Testnet.

Deploying to Mainnet

Once you are ready to deploy to the ZKcandy Mainnet, update the private key in the .env file in the root of your project folder and enter your private key as the value of the WALLET_PRIVATE_KEY variable.

You will need Ether on the ZKcandy Mainnet in order to proceed with deployment. Please fund your wallet adequately before proceeding.

Run the following command to initiate the deployment process:

⚠️

This command will deploy your contract to the ZKcandy Mainnet.

There is no confirmation prompt after executing this command. You cannot undo this step once your contract is deployed. Please make sure you have completed all desired unit testing and that the constructor arguments in your deploy.ts script are correct before proceeding.


yarn hardhat deploy-zksync --script deploy.ts --network ZKcandyMainnet

Your machine will now attempt to deploy the contract to the ZKcandy Mainnet. If successful, the program will return the contract address of your newly deployed contract.

📝

The deploy script will also attempt to upload verify your contract source code on the ZKcandy block explorer.

Deploying to ZKcandy ZKEVM Prerequisites Local Testing Initialisation Setting Up Configuring Your Environment Compiling and Preparing Your Contract(s)Compiling Your Contract Deployment Script Deploying Your Contract(s)Deploying to Testnet Deploying to Mainnet