hardhat-zksync-node

This plugin is used to provide a convenient way to run anvil-zksync node locally using hardhat.

Prerequisite

To use hardhat-zksync-node in your project, ensure the following:

• Node.js version 18 or higher is installed.
• Hardhat version 2.18.0 or higher is installed as a dependency.

Installation

@matterlabs/hardhat-zksync-node

Add the latest version of this plugin to your project with the following command:

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

Configuration

Import the plugin in the hardhat.config.ts file:

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

Commands

yarn hardhat node-zksync

This command runs a local anvil-zksync node by initiating a JSON-RPC server. It uses the provided or default configurations to set up and run the ZKsync node, allowing for blockchain operations in a local environment. The command also handles tasks such as downloading the necessary JSON-RPC server binary if it's not already present.

• --port - Port on which the server should listen. Defaults to 8011.
• --log - Log filter level. Accepted values are: error, warn, info, and debug. Defaults to info.
• --log-file-path - Path to the file where logs should be written. Defaults to anvil_zksync.log.
• --cache - Type of cache to use. Accepted values are: none, disk, and memory. Defaults to disk.
• --cache-dir - Directory location for the disk cache. Defaults to .cache.
• --reset-cache - Flag to reset the local disk cache.
• --show-calls - Determines which call debug information to show. Accepted values are: none, user, system, and all. Defaults to none.
• --show-storage-logs - Determines which storage logs to show. Accepted values are: none, read, write, and all. Defaults to none.
• --show-vm-details - Specifies the level of Virtual Machine (VM) details to show. Accepted values are: none and all. Defaults to none.
• --show-gas-details - Specifies the level of gas details to show. Accepted values are: none and all. Defaults to none.
• --resolve-hashes - Flag to try contacting openchain to resolve the ABI & topic names. When enabled, it makes the debug log more readable but might decrease performance.
• --dev-use-local-contracts - Flag to load locally compiled system contracts. Useful when making changes to system contracts or bootloader.
• --fork - Starts a local network that is a fork of another network. Accepted values are: testnet, mainnet, or a specific URL.
• --fork-block-number - Specifies the block height at which to fork.
• --replay-tx - Transaction hash to replay.

Running Hardhat's test Task with hardhat-zksync-node

The hardhat-zksync-node plugin enhances Hardhat's test task, allowing all tests to run against anvil-zksync node operated in a separate process. By invoking the test task, ensure you are using the hardhat network and have set its zksync flag to true. Doing so will initiate the plugin's anvil-zksync node alongside the tests. After the tests conclude, the node shuts down gracefully. The plugin begins port allocation from the default 8011.

networks: {
  hardhat: {
    zksync: true,
  }
},

The network object in the Hardhat runtime environment is also updated to match the running node as follows:

• The network name is set to zkSyncEraTestNode.
• The network config is set as an HTTP network config, adopting default values.
• The network provider uses a provider adapter that implements EthereumProvider and wraps the zksync's JS SDK Provider implementation.

const provider = new Provider(hre.network.config.url);

import "@matterlabs/hardhat-zksync-node/dist/type-extensions";

// hre stands for hardhat runtime environment
(hre.network.provider as ZkSyncProviderAdapter)._zkSyncProvider;