Deploying to the ZKcandy Testnet

Updated 30 October 2024

Our new Block Explorer Contract Verification endpoint is now at https://sepolia.contracts.zkcandy.io/contract_verification. Please update your development environment to use this endpoint. Find out more about supported versions of zksolc here. You can also use the hardhat.config.js file available here.

The ZKcandy Testnet was reset on 21 October 2024. As such, any Smart Contracts deployed prior to 20 October 2024 need to be re-deployed. This is because the ZKcandy Sepolia Testnet was upgraded to the latest version of the ZKsync Elastic Chain codebase. We regret the inconvenience caused. Read-only archival access to the old ZKcandy Sepolia Testnet blockchain is available here.

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.

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

Table of Contents

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

1. Prerequisites
2. Local Testing
3. Initialisation
4. Configuring Your Environment
5. Compiling & Preparing Your Contract

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

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.

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

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.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: "ZKcandySepolia",
  networks: {
    hardhat: {
      zksync: false,
    },
    ZKcandySepolia: ZKcandySepolia,
    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.

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://sepolia.contracts.zkcandy.io/contract_verification/zksolc_versions

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:

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.

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

← Previous

Building on ZKcandy

Next →

Interacting with your Smart Contract

On this page