Deploying to ZKcandy

This document will cover deploying to both the ZKcandy Mainnet and the ZKcandy Sepolia Testnet. We strongly encourage testing your contracts on the ZKcandy 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.

This documentation is written with reference to the official zkSync Hardhat Plugin documentation.

Prerequisites

A Node installation with package manager. We recommend yarn

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.


yarn add zksync-cli

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.


yarn zksync-cli create projectFolder --template hardhat_solidity

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 yarn.

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

Configuring Your Environment

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


yarn add -D @matterlabs/hardhat-zksync-deploy @nomiclabs/hardhat-ethers ethers zksync-ethers

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 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://sepolia.rpc.zkcandy.io",
  ethNetwork: "mainnet",
  zksync: true,
  verifyURL: "https://contracts.zkcandy.io/contract_verification",
};

const ZKcandySepolia = {
  url: "https://sepolia.rpc.zkcandy.io",
  ethNetwork: "sepolia",
  zksync: true,
  verifyURL: "https://sepolia.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 ZKsyncTestnetGoerli = {
  url: "https://testnet.era.zksync.dev",
  ethNetwork: "goerli",
  zksync: true,
  verifyURL: "https://zksync2-testnet-explorer.zksync.dev/contract_verification",
};

const ZKsyncMainnet = {
  url: "https://mainnet.era.zksync.io",
  ethNetwork: "mainnet",
  zksync: true,
  verifyURL: "https://zksync2-mainnet-explorer.zksync.io/contract_verification",
};

const config: HardhatUserConfig = {
  zksolc: {
    version: "1.5.3",
    compilerSource: "binary",
    settings: {
      optimizer: {
        enabled: true,
        mode: "z",
      },
    },
  },
  defaultNetwork: "ZKcandyMainnet",
  networks: {
    hardhat: {
      zksync: false,
    },
    ZKcandyMainnet: ZKcandyMainnet,
    ZKcandySepolia: ZKcandySepolia,
    ZKsyncTestnetSepolia: ZKsyncTestnetSepolia,
    ZKsyncTestnetGoerli: ZKsyncTestnetGoerli,
    ZKsyncMainnet: ZKsyncMainnet,
  },
  solidity: {
    version: "0.8.24",
  },
};

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:


yarn 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

Navigate to the deploy folder in the root of your project folder. Here you will find a deploy.ts file. For complete documentation on how to use this file, please refer to the official documentation from ZKsync. For the purposes of this document, your deploy.ts should look like this:


import { deployContract } from "./utils";

export default async function () {
  const contractArtifactName = "MyContract";
  await deployContract(contractArtifactName);
}

Replace the values of contractArtifactName with the name of the contract you compiled (this is not necessarily the contract filename).

Constructor Arguments

If your contract has a constructor, declare a constructorArguments variable with your contract’s constructor arguments in array format as its value, then add the constructorArguments variable as a parameter to the deployContract function.


import { deployContract } from "./utils";

export default async function () {
  const contractArtifactName = "MyContract";
  const constructorArguments = ["Argument1", "Argument2"];
  await deployContract(contractArtifactName, constructorArguments);
}

You are now ready to deploy your contract using the wallet whose private key is in your project’s .env file.

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.

You will need Test Ether on the ZKcandy 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 ZKcandy 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 ZKcandySepolia

Your machine will now attempt to deploy the contract to the ZKcandy 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 ZKcandy Sepolia Testnet block explorer.

You can now call functions and test your contract on the ZKcandy 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 Prerequisites Local Testing Initialisation Configuring Your Environment Compiling and Preparing Your Contract(s)Compiling Your Contract Deployment Script Constructor Arguments Deploying Your Contract(s)Deploying to Testnet Deploying to Mainnet