Setting Up Your ZKsync Development Environment with Web3.js Plugin

Setting Up Your ZKsync Development Environment with Web3.js Plugin

If you’re looking to develop on the ZKsync Era network and integrate it with Web3.js, you’re in the right place. This guide will walk you through the initial setup required to get your local environment ready for development and testing. We’ll cover cloning the necessary repositories, running a local instance of ZKsync, and preparing your environment for tests. By the end of this article, you’ll have everything in place to start building dApps using ZKsync.

What You’ll Learn

- How to clone and set up the ZKsync local environment
- How to configure the Web3.js plugin for ZKsync
- Preparing your setup for testing

Step 1: Clone the ZKsync Local Setup Repository

The first step is to clone the ZKsync local setup repository. This repository contains everything you need to run a local instance of the ZKsync network, allowing you to test and develop your dApps without relying on a live network.

To clone the repository, open your terminal and run the following command:

git clone git@github.com:matter-labs/local-setup.git zk-local-setup
# After the cloning is complete, navigate into the directory:
cd zk-local-setup
view raw zk.env.sh hosted with ❤ by GitHub

This directory contains all the files necessary for running ZKsync locally.

Step 2: Running the ZKsync Local Environment

Once you’re inside the zk-local-setup directory, the next step is to start up your local ZKsync environment. 

You need to have Docker to be installed.

docker compose up
# or
./start.sh
view raw zk.env.run.sh hosted with ❤ by GitHub

This will start the Docker containers needed to run ZKsync locally, including the ZKsync node and other related services.

Once this process is complete, your local ZKsync instance will be running, and you’re ready to connect to it in the next steps.

Step 3: Restarting the Environment

If at any point you need to restart the environment, you can easily do so. First, clear the existing setup by running:

./clear.sh
view raw zk.env.clear.sh hosted with ❤ by GitHub

This script resets your environment. After clearing, you can start again using either: ./start.sh or docker compose up

Step 4: Preparing Your Environment for Testing (Optional)

With the ZKsync environment up and running, the next step is to clone the Web3.js plugin. This plugin will be essential for building and testing your dApps.

git clone git@github.com:ChainSafe/web3-plugin-zksync.git web3-plugin-zksync
# After cloning the repository, navigate into the new directory:
cd web3-plugin-zksync
view raw zk.env.clone.sh hosted with ❤ by GitHub

To prepare your environment for tests, run the following command:

yarn test:prepare
# or
npm run test:prepare

What This Script Does:

  • Deploys a Paymaster Contract: The Paymaster allows for flexible fee payments, enabling users to pay for gas with tokens other than ETH.
  • Deploys an Approval Token Contract: This contract simplifies the token approval process, making token interactions easier to handle.
  • Deploys an Example ERC-20 Token: This ERC-20 token is a great tool for testing token transfers and other ERC-20 related features.
  • Refills Test Accounts with ETH: The script also refills your test accounts with ETH, giving you the ability to perform transactions and smart contract interactions without needing to request testnet ETH separately.

Example of the script result:

===== Minting and sending base token =====
Wallet address: 0x36615Cf349d7F6344891B1e7CA7C72883F5dc049
Base token L1: 0x0000000000000000000000000000000000000001
L1 base token balance before: 99999998999999999999995793144999820430
L2 base token balance before: 1000000000000003861773775000000
Send funds tx: 0xd7e59a74cfb7c4ab2b6aba52cf585d45bf2006cc6a2de385b02431df6d479bd1
L1 base token balance after: 99999998999999989999992807259387140908
L2 base token balance after: 1000000010000006592966312500000
===== Minting and sending DAI =====
DAI L1: 0x70a0F165d6f8054d0d0CF8dFd4DD2005f0AF6B55
DAI L2: 0x19823b3D0ccfe3393b50491502e07300E60dde02
L1 DAI balance before: 0
L2 DAI balance before: 0
Minted DAI on L1 successfully. Now sending the DAI token to L2...
Send funds tx: 0x7119cd1bc1fcdbe3ac4adeb83dc5f40e1b5c3182470c4439a2236abebf36af9c
L1 DAI balance after: 10000000000000000000000
L2 DAI balance after: 10000000000000000000000
===== Deploying token and paymaster =====
Token: 0x841c43Fa5d8fFfdB9efE3358906f7578d8700Dd4
Paymaster: 0xa222f0c183AFA73a8Bc1AFb48D34C88c9Bf7A174
Paymaster ETH balance: 100000000000000000000
Wallet Crown balance: 50

You can use this data to develop your application.

Final Thoughts

By following these steps, you now have a fully operational ZKsync development environment running on your local machine. You can now start building and testing your dApps using the Web3.js plugin.

In the next steps, you’ll learn how to connect to the ZKsync network using a provider, which is crucial for interacting with the blockchain. Stay tuned for more tutorials!

Here are the essential links to help you get started:

  • Web3.js Plugin for ZKsync: You can find the official plugin repository here.
  • Examples for Using the Plugin: I've also prepared a dedicated repository with all the code examples from this tutorial and more, which you can access here.
  • ZKsync Web3.js Documentation: For more detailed information and resources, check out the official documentation here.