Tutorial Information

Required Tools

Node.js (v16+)
Hardhat
zkSync Hardhat plugins
Browser wallet (e.g., MetaMask)

Materials

Laptop or desktop with internet access
Testnet wallet with a small amount of ETH on Goerli or Sepolia

Estimated cost: 0 USD

Steps

Get a feel for what ZK-rollups are and when to use them: Read through the core concepts so you know what you’re building on and why.
Set up a zkSync-ready development environment: Install Node.js, Hardhat, zkSync plugins, and create a clean project folder.
Write and understand a simple token contract for zkSync: Create a basic ERC‑20 style token and see what changes on a ZK-rollup versus L1.
Deploy your token to zkSync testnet: Use Hardhat and a funded testnet wallet to deploy and verify your contract.
Add batched operations to see rollup benefits: Deploy a batch processor contract to group multiple token operations into one transaction.
Wire in L1/L2 messaging concepts: Walk through a simple pattern for passing messages between Ethereum L1 and zkSync L2.

Step 1 – Get a feel for what ZK-rollups are and when to use them

Before we touch any code, it’s worth anchoring what you’re actually building on. When I help teams decide between L2 options, the questions are usually “how fast does it finalize?” and “how painful are withdrawals?” not “which proving system is used.”

Zero-knowledge rollups (ZK-rollups) are a type of Layer 2 that:

Bundle many L2 transactions into a single proof on Ethereum L1.
Use a succinct proof to show that all transactions were valid.
Keep Ethereum’s security assumptions while making each individual transaction cheaper.

At a high level, ZK-rollups are especially useful when:

You care about fast finality (no week-long withdrawal windows).
You expect a lot of complex transactions (DEXes, games, NFT mints).
You want cheaper transactions without leaving Ethereum’s security umbrella.

You don’t need to understand every math detail to build on zkSync, but you should be comfortable that you’re still “on Ethereum,” just via a higher-capacity lane.

Step 2 – Set up a zkSync-ready development environment

Let’s start by setting up everything we need to build on zkSync, one of the leading ZK-Rollup protocols.

Install Required Tools

First, ensure you have Node.js (v16+) and npm installed. Then create a new project directory:

mkdir zksync-demo
cd zksync-demo
npm init -y

Install the necessary dependencies:

npm install --save-dev typescript ts-node [email protected] zksync-web3 hardhat @matterlabs/hardhat-zksync-solc @matterlabs/hardhat-zksync-deploy

If hardhat isn’t found later, double-check that node_modules/.bin is on your path or call it via npx hardhat.

Configure Hardhat for zkSync

Create a hardhat.config.ts file. This file tells Hardhat how to compile contracts and which networks (including zkSync) it can talk to:

1
import { HardhatUserConfig } from "hardhat/config";
2
import "@matterlabs/hardhat-zksync-deploy";
3
import "@matterlabs/hardhat-zksync-solc";
4

5
const config: HardhatUserConfig = {
6
  zksolc: {
7
    version: "1.3.5",
8
    compilerSource: "binary",
9
    settings: {},
10
  },
11
  defaultNetwork: "zkSyncTestnet",
12
  networks: {
13
    hardhat: {
14
      zksync: true,
15
    },
16
    zkSyncTestnet: {
17
      url: "https://zksync2-testnet.zksync.dev",
18
      ethNetwork: "goerli", // or "sepolia"
19
      zksync: true,
20
    },
21
  },
22
  solidity: {
23
    version: "0.8.17",
24
  },
25
};
26

27
export default config;

Quick read-through:

zksolc block wires in zkSync’s Solidity compiler.
defaultNetwork is set to zkSyncTestnet so deploy-zksync knows where to go.
The zkSyncTestnet network uses ethNetwork: "goerli" (or sepolia); make sure that matches whichever testnet you actually use and have funds on.

Setup Project Structure

Create the following directories:

mkdir -p contracts deploy

At this point you should be able to run npx hardhat and see the zkSync-related tasks listed. If that works, you’re ready to write some contracts.

Step 3 – Write and understand a simple token contract for zkSync

Now, let’s create a simple token contract that will live on zkSync. The Solidity itself looks almost identical to an L1 token; the big differences are in where and how you deploy it.

Create the Token Contract

Create a file at contracts/ZkToken.sol:

1
// SPDX-License-Identifier: MIT
2
pragma solidity ^0.8.17;
3

4
contract ZkToken {
5
    string public name = "ZkToken";
6
    string public symbol = "ZKT";
7
    uint8 public decimals = 18;
8
    uint256 public totalSupply = 1000000 * 10**18; // 1 million tokens
9

10
    mapping(address => uint256) private _balances;
11
    mapping(address => mapping(address => uint256)) private _allowances;
12

13
    event Transfer(address indexed from, address indexed to, uint256 value);
14
    event Approval(address indexed owner, address indexed spender, uint256 value);
15

16
    constructor() {
17
        _balances[msg.sender] = totalSupply;
18
    }
19

20
    function balanceOf(address account) public view returns (uint256) {
21
        return _balances[account];
22
    }
23

24
    function transfer(address recipient, uint256 amount) public returns (bool) {
25
        require(_balances[msg.sender] >= amount, "Insufficient balance");
26

27
        _balances[msg.sender] -= amount;
28
        _balances[recipient] += amount;
29

30
        emit Transfer(msg.sender, recipient, amount);
31
        return true;
32
    }
33

34
    function approve(address spender, uint256 amount) public returns (bool) {
35
        _allowances[msg.sender][spender] = amount;
36
        emit Approval(msg.sender, spender, amount);
37
        return true;
38
    }
39

40
    function allowance(address owner, address spender) public view returns (uint256) {
41
        return _allowances[owner][spender];
42
    }
43

44
    function transferFrom(address sender, address recipient, uint256 amount) public returns (bool) {
45
        require(_balances[sender] >= amount, "Insufficient balance");
46
        require(_allowances[sender][msg.sender] >= amount, "Insufficient allowance");
47

48
        _balances[sender] -= amount;
49
        _balances[recipient] += amount;
50
        _allowances[sender][msg.sender] -= amount;
51

52
        emit Transfer(sender, recipient, amount);
53
        return true;
54
    }
55
}

Understanding zkSync Optimizations

While this contract looks like a standard ERC-20, when deployed on zkSync it benefits from:

Lower Gas Costs: Transactions cost a fraction of L1 gas fees
Faster Confirmations: Near-instant finality once proofs are generated
Scalability: The same contract can support many more users and transactions simply by living on the rollup.

Key takeaway: you don’t need a “special” Solidity dialect to start; the main changes are in tooling and deployment targets, not the core language.

Step 4 – Deploy your token to zkSync testnet

Let’s deploy our contract to the zkSync testnet.

Create a Wallet and Get Testnet Funds

First, create a deployment script at deploy/deploy.ts. This script is what you actually run to push ZkToken to zkSync:

1
import { Wallet } from "zksync-web3";
2
import { HardhatRuntimeEnvironment } from "hardhat/types";
3
import { Deployer } from "@matterlabs/hardhat-zksync-deploy";
4
import * as dotenv from "dotenv";
5
dotenv.config();
6

7
export default async function (hre: HardhatRuntimeEnvironment) {
8
  console.log("Running deployment script for ZkToken");
9

10
  // Initialize the wallet.
11
  const privateKey = process.env.PRIVATE_KEY || "";
12
  if (!privateKey) throw new Error("Private key not provided");
13

14
  const wallet = new Wallet(privateKey);
15
  const deployer = new Deployer(hre, wallet);
16

17
  // Load artifact
18
  const artifact = await deployer.loadArtifact("ZkToken");
19

20
  // Deploy
21
  console.log("Deploying ZkToken...");
22
  const zkToken = await deployer.deploy(artifact, []);
23

24
  // Show contract info
25
  console.log(`ZkToken deployed to ${zkToken.address}`);
26

27
  // Verify contract
28
  console.log("Verification not yet available on testnet");
29
}

What’s happening:

We read PRIVATE_KEY from .env so the key never sits in the script.
Wallet (from zksync-web3) is a signer that knows how to talk to zkSync.
Deployer wraps Hardhat + zkSync deployment logic so you don’t have to handcraft transactions.

Create a .env file for your private key (never commit this to git):

1
PRIVATE_KEY=your_private_key_here

Install dotenv and set up environment loading:

npm install dotenv

Then, update your deployment script to load the environment:

1
import * as dotenv from "dotenv";
2
dotenv.config();
3

4
// Rest of the script...

Before deploying, get some testnet ETH from the zkSync faucet or bridge some from Goerli/Sepolia.

Deploy the Contract

Run the deployment script:

npx hardhat deploy-zksync

You should see output with your contract’s address on zkSync testnet.

Once you have that address, you can:

Add it to your wallet’s custom token list.
Try a small transfer on zkSync’s testnet block explorer.

This is usually the “aha” moment where teams realize they’re still just dealing with normal Ethereum-style contracts—just with different URLs and gas prices.

Step 5 – Add batched operations to see rollup benefits

One of the key advantages of ZK-Rollups is the ability to batch multiple transactions. Let’s create a simple contract that demonstrates this capability.

Create a BatchProcessor Contract

Create a new file at contracts/BatchProcessor.sol:

1
// SPDX-License-Identifier: MIT
2
pragma solidity ^0.8.17;
3

4
interface IERC20 {
5
    function transfer(address recipient, uint256 amount) external returns (bool);
6
    function balanceOf(address account) external view returns (uint256);
7
}
8

9
contract BatchProcessor {
10
    address public owner;
11

12
    constructor() {
13
        owner = msg.sender;
14
    }
15

16
    // Batch transfer tokens to multiple recipients
17
    function batchTransfer(
18
        address token,
19
        address[] calldata recipients,
20
        uint256[] calldata amounts
21
    ) external {
22
        require(msg.sender == owner, "Only owner");
23
        require(recipients.length == amounts.length, "Arrays length mismatch");
24

25
        IERC20 tokenContract = IERC20(token);
26

27
        for (uint i = 0; i < recipients.length; i++) {
28
            tokenContract.transfer(recipients[i], amounts[i]);
29
        }
30
    }
31

32
    // Process multiple token operations in a single transaction
33
    function multiTokenTransfer(
34
        address[] calldata tokens,
35
        address[] calldata recipients,
36
        uint256[] calldata amounts
37
    ) external {
38
        require(msg.sender == owner, "Only owner");
39
        require(tokens.length == recipients.length, "Arrays length mismatch");
40
        require(recipients.length == amounts.length, "Arrays length mismatch");
41

42
        for (uint i = 0; i < tokens.length; i++) {
43
            IERC20 tokenContract = IERC20(tokens[i]);
44
            tokenContract.transfer(recipients[i], amounts[i]);
45
        }
46
    }
47
}

Deploy the BatchProcessor

Create a deployment script for the batch processor at deploy/deploy-batch.ts:

1
import { Wallet } from "zksync-web3";
2
import * as ethers from "ethers";
3
import { HardhatRuntimeEnvironment } from "hardhat/types";
4
import { Deployer } from "@matterlabs/hardhat-zksync-deploy";
5
import * as dotenv from "dotenv";
6
dotenv.config();
7

8
export default async function (hre: HardhatRuntimeEnvironment) {
9
  console.log("Running deployment script for BatchProcessor");
10

11
  // Initialize the wallet.
12
  const privateKey = process.env.PRIVATE_KEY || "";
13
  if (!privateKey) throw new Error("Private key not provided");
14

15
  const wallet = new Wallet(privateKey);
16
  const deployer = new Deployer(hre, wallet);
17

18
  // Load artifact
19
  const artifact = await deployer.loadArtifact("BatchProcessor");
20

21
  // Deploy
22
  console.log("Deploying BatchProcessor...");
23
  const batchProcessor = await deployer.deploy(artifact, []);
24

25
  // Show contract info
26
  console.log(`BatchProcessor deployed to ${batchProcessor.address}`);
27
}

Deploy with:

npx hardhat deploy-zksync --script deploy-batch.ts

Understanding the Benefits

This batched approach provides significant benefits on zkSync:

Cost Savings: Instead of paying for 10 separate L1 transactions, you pay for a single transaction with the cost of generating one ZK proof
Time Efficiency: All operations are processed together, reducing wait times
Atomic Execution: Either all transactions succeed or all fail, ensuring consistency

You don’t have to build batch logic into every app, but seeing it once helps you understand why rollups are a natural fit for high-throughput workflows.

Step 6 – Wire in L1/L2 messaging concepts

A powerful feature of zkSync is the ability to interact with Ethereum L1 contracts. Let’s implement a bridge pattern.

Create a Cross-Chain Messenger

Create a new contract at contracts/CrossChainMessenger.sol:

1
// SPDX-License-Identifier: MIT
2
pragma solidity ^0.8.17;
3

4
interface IL1Bridge {
5
    function receiveMessage(string calldata message) external;
6
}
7

8
contract CrossChainMessenger {
9
    address public owner;
10
    address public l1Target;
11

12
    event MessageSent(string message, uint256 timestamp);
13

14
    constructor(address _l1Target) {
15
        owner = msg.sender;
16
        l1Target = _l1Target;
17
    }
18

19
    function sendMessageToL1(string calldata message) external returns (bytes32) {
20
        require(msg.sender == owner, "Only owner can send messages");
21

22
        // This will initiate an L2->L1 message
23
        bytes32 messageHash = keccak256(abi.encodePacked(message, block.timestamp));
24

25
        // In a real implementation, we would use zkSync's native cross-layer messaging
26
        // This is a simplified example
27

28
        emit MessageSent(message, block.timestamp);
29
        return messageHash;
30
    }
31

32
    // This function would be called by the zkSync bridge system
33
    function receiveMessageFromL1(string calldata message) external {
34
        // In a real implementation, this would verify that the message came from L1
35
        // through the zkSync bridge system
36

37
        // Process the message
38
        emit MessageSent(message, block.timestamp);
39
    }
40
}

Note: This is a simplified example. In a real zkSync application, you would use the zksync-web3 library’s specific cross-layer messaging functions.

Actual L1-L2 Communication Example

For actual L1-L2 communication on zkSync, you would use code like this:

1
// L1 to L2 messaging example
2
async function sendMessageFromL1ToL2() {
3
  // L1 provider and wallet
4
  const l1Provider = new ethers.providers.JsonRpcProvider(L1_RPC_URL);
5
  const wallet = new ethers.Wallet(PRIVATE_KEY, l1Provider);
6

7
  // Get zkSync provider
8
  const zksyncProvider = new Provider("https://zksync2-testnet.zksync.dev");
9

10
  // Bridge contracts are already deployed
11
  const l1Bridge = new ethers.Contract(L1_BRIDGE_ADDRESS, L1_BRIDGE_ABI, wallet);
12

13
  // Send a message from L1 to L2
14
  const tx = await l1Bridge.sendMessage(L2_RECEIVER_ADDRESS, "Hello from L1!");
15
  await tx.wait();
16

17
  // Get the L2 transaction and wait for it to be processed
18
  const l2Hash = await zksyncProvider.getL2TransactionFromPriorityOp(tx);
19

20
  // Wait for the L2 transaction
21
  const l2Receipt = await zksyncProvider.waitForTransaction(l2Hash);
22
  console.log("Message delivered to L2:", l2Receipt.transactionHash);
23
}

This snippet omits imports and constants to keep the focus on the flow. In a real file you would need:

1
import { Provider } from "zksync-web3";
2
import * as ethers from "ethers";
3

4
const L1_RPC_URL = "https://your-l1-rpc.example";
5
const L1_BRIDGE_ADDRESS = "0x..."; // from zkSync docs
6
const L1_BRIDGE_ABI = [...];
7
const L2_RECEIVER_ADDRESS = "0x...";
8
const PRIVATE_KEY = process.env.PRIVATE_KEY!;

Common pitfalls I see here:

Wrong RPC URLs or network mismatch (Goerli vs Sepolia) causing “network not supported” errors.
Not waiting for the L1 transaction to finalize before trying to look up the L2 side.
Using the wrong bridge contract address; always pull bridge addresses from the current zkSync docs.

Conclusion

In this tutorial, we’ve explored Zero-Knowledge Rollups and implemented several practical examples using zkSync. You’ve learned how to:

Understand ZK-Rollup technology and its advantages over other scaling solutions
Set up a development environment for zkSync
Build and deploy a token contract to zkSync’s testnet
Implement batch transactions for gas optimization
Create cross-layer communication between Ethereum L1 and zkSync L2

ZK-Rollups represent the cutting edge of blockchain scaling technology, offering a compelling combination of security, scalability, and user experience. By leveraging zero-knowledge proofs, they maintain the robust security guarantees of Ethereum while drastically improving transaction throughput and reducing costs.

As the ecosystem continues to evolve, we’ll see more sophisticated tooling, greater interoperability, and increased adoption of ZK-Rollup technology across the blockchain landscape.

For further exploration, consider:

Implementing a more complex application like a DEX or NFT marketplace on zkSync
Exploring account abstraction features unique to zkSync
Experimenting with other ZK-Rollup platforms like StarkNet or Polygon zkEVM

Happy building in the Zero-Knowledge world!

Resources and further reading

Source	Title
era.zksync.io	zkSync Era Docs – Getting Started Official zkSync documentation with up-to-date guides on deployment, tooling, and L1/L2 messaging.
ethereum.org	Ethereum.org – Layer 2 Rollups Overview of rollups on Ethereum, including the differences between optimistic and ZK-rollups.
en.wikipedia.org	Rollup (blockchain) – Wikipedia Neutral background on how rollups work and why they matter for scaling.
era.zksync.io	zkSync Era Hardhat Plugins Reference for the Hardhat plugins used in this tutorial, with configuration and usage examples.
portal.zksync.io	zkSync Testnet Faucet Source for testnet ETH to deploy and test your contracts on zkSync networks.

How to Build and Deploy a Simple App on a ZK-Rollup (zkSync) in 2025