hardhat-zksync-node

Description

The hardhat-zksync-node plugin provides a convenient way to run anvil-zksync locally using Hardhat. It adds ZKSync-specific provider functionality to the Hardhat Runtime Environment (HRE) and provides helpers for running local nodes.

Resources:

• NPM Package
• GitHub Repository
• Changelog

Installation

Prerequisites

• Node.js version 18 or higher
• Hardhat version 2.18.0 or higher

Setup

Install the plugin using your preferred package manager:

yarn add -D @matterlabs/hardhat-zksync-node

Import the package in your hardhat.config.ts file:

import "@matterlabs/hardhat-zksync-node";

Configuration

Anvil-zksync Configuration

To configure a specific version of anvil-zksync or set a custom binary path, add the zksyncAnvil configuration to your hardhat.config.ts:

const config: HardhatUserConfig = {
  zksyncAnvil: {
    version: '0.3.*', // optional
    binaryPath: 'zksync/target/release/anvil-zksync', // optional
  },
  // ... rest of your config
};

Configuration Options

Network Configuration

Options

Example Configuration

import "@matterlabs/hardhat-zksync-node";

const config: HardhatUserConfig = {
  networks: {
    hardhat: {
      zksync: true,
    }
  },
};

export default config;

Additions

Added Tasks

• node-zksync: Runs a local anvil-zksync node
• Overrides hardhat node when zksync: true is set
• Overrides hardhat run and deployment tasks when zksync: true is set on the hardhat network

Added HRE Extensions

• network.provider: Extended with ZKSync-specific functionality
• network.config: Added ZKSync-specific configuration options

Commands

node-zksync

Runs a local anvil-zksync node.

hardhat node-zksync [options]

Options

Usage

Running a Local Node

Start a local ZKSync node using:

yarn hardhat node-zksync

Testing with hardhat-zksync-node

The plugin enhances Hardhat's test task to run against anvil-zksync node:

1. Use the hardhat network with zksync: true
2. Node starts automatically with tests
3. Node shuts down after test completion
4. Port allocation starts from 8011 to 8021 depends on availability

Troubleshooting

Configuration Issues

Problem: Configuration Issues

• Plugin import order is incorrect
• Network configuration is missing ZKSync settings
• Incompatible anvil-zksync version

Solution:

• Ensure hardhat-zksync-node is imported after hardhat-zksync-deploy in your config
• Verify network configuration has zksync: true set
• Check if anvil-zksync version is compatible with your setup

import "@matterlabs/hardhat-zksync-deploy";
import "@matterlabs/hardhat-zksync-node";

networks: {
  hardhat: {
    zksync: true
  }
}

Provider Connection Issues

Problem: Provider Connection Issues

• Node is not running
• Incorrect RPC URL
• Permission issues

Solution:

• Ensure the node is running before executing commands
• Verify RPC URL is correct and accessible
• Check if you have sufficient permissions to access the node

Compiler Version Issues

Problem: Invalid zksolc compiler version

Solution:

• Update your anvil-zksync version in config:

  zksyncAnvil: {
    version: "0.3.*" // Use latest compatible version
  }
  

• Check minimum required version in documentation

Port Issues

Problem: Port already in use

Solution:

• Change port using --port flag:

  hardhat node-zksync --port 8012
  

• Or stop other processes using the port

Node Startup Issues

Problem: Failed to start node

Solution:

• Check system requirements
• Verify binary path if using custom path
• Ensure sufficient system resources

For more help, please refer to the GitHub issues.