Deploying to the ZKcandy Testnet

Updated 28 June 2024

<aside> <img src="/icons/star_lightgray.svg" alt="/icons/star_lightgray.svg" width="40px" /> NEW: Contract verification on the ZKcandy Block Explorer is now working. Please update your hardhat.config.js file with the new one from this tutorial and Configure Your Environment with the new updated commands.

</aside>

There are multiple ways to deploy contracts to the ZKcandy Testnet. For this tutorial, 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.

<aside> <img src="/icons/book_lightgray.svg" alt="/icons/book_lightgray.svg" width="40px" /> This documentation is written with reference the the official zkSync Hardhat Plugin documentation.

</aside>

As this is a long document that covers setting up a development environment and subsequently the deployment of a contract to the ZKcandy Sepolia Testnet, this list will help you navigate through the steps

Prerequisites

A Node installation with package manager. We recommend yarn
zksync-cli to prepare your development environment
Your wallet private key
Sepolia Test Ether, bridged to the ZKcandy Sepolia Testnet

<aside> <img src="/icons/warning_lightgray.svg" alt="/icons/warning_lightgray.svg" width="40px" /> This method of deployment requires the use of your wallet private key in your project’s environment variables. For 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.

</aside>

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

NEW: If you had tried the following steps prior to 28 June 2024, please use the new commands and hardhat.config.ts file below so that your contract can get verified on the ZKcandy Block Explorer

</aside>

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 Sepolia Testnet RPC 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 ZKcandySepolia = {
  url: "<https://sepolia.rpc.zkcandy.io>",
  ethNetwork: "sepolia",
  zksync: true,
  verifyURL:
    "<https://sepolia.contract-verifier.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.4.1",
    // version: "latest",
    compilerSource: "binary",
    settings: {
      optimizer: {
        enabled: true,
        mode: "z",
      },
    },
  },
  defaultNetwork: "ZKcandySepolia",
  networks: {
    hardhat: {
      zksync: false,
    },
    zkCandySepolia: zkCandySepolia,
    zkcandysepolia2: zkcandysepolia2,
    zkSyncTestnetSepolia: zkSyncTestnetSepolia,
    zkSyncTestnetGoerli: zkSyncTestnetGoerli,
    zkSyncMainnet: zkSyncMainnet,
  },
  solidity: {
    version: "0.8.24",
  },
};

export default config;

zkCandySepoliaTestnet is a label for the ZKcandy Sepolia Testnet. You can select this as the default network using the defaultNetwork property.
url is a field containing the URL of the ZKcandy Sepolia Testnet public node in case of the ZKcandy Testnet (with zksync flag set to true), or the URL of the Ethereum node. This field is required for all ZKsync-type and Ethereum networks used by this plugin.
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.

Compiling and Preparing Your Contract

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.

Contract Deployment

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.

Run the following command to initiate the deployment process:

<aside> ⚠️ This command will deploy your contract.

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.

</aside>

yarn hardhat deploy-zksync --script deploy.ts

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.

<aside> 📝 Make a note of your contract address in the terminal printout.

As our block explorer is still undergoing some improvements to better verify deployed contracts, please copy the contract address from the terminal printout if your contract deployment is successful so that you are able to access and interact with it in the future.

</aside>

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

<aside> 🔧 Contract verification is currently experimental on the ZKcandy Sepolia Testnet.

If your contract verification fails to verify from the CLI, follow this link to perform manual verification.

</aside>

← Previous

Building on ZKcandy

Interacting with your Smart Contract

On this page

Deploying to the ZKcandy Testnet

Table of Contents

Prerequisites

Local Testing

Initialisation

Configuring Your Environment

Compiling and Preparing Your Contract

Compiling Your Contract

Deployment Script

Constructor Arguments

Contract Deployment