Validium Docs
  • Overview
  • Connect to Validium
  • Start Coding 🚀
    • Quickstart
      • Overview
      • Deploy using Validium CLI
      • Deploy using Quickstart Repository
      • Deploy your first contract
      • Create an ERC20 token
  • Tooling
    • Block Explorers
    • Hardhat-Validium
      • Overview
      • Installation
      • Guides
        • Getting started
        • Migrating Hardhat project to Validium
        • Compiling non-inlinable libraries
      • Plugins
        • hardhat-zksync
        • hardhat-zksync-solc
        • hardhat-zksync-vyper
        • hardhat-zksync-deploy
        • hardhat-zksync-upgradable
        • hardhat-zksync-verify
        • hardhat-zksync-verify-vyper
        • hardhat-zksync-ethers
        • hardhat-zksync-node
        • Hardhat Community Plugins
    • Foundary
      • Overview
      • Installation
      • Getting Started
      • Migration Guide
        • Overview
        • Compilation
        • Deployment
        • Testing
  • Test and Debug
    • Getting Started
    • Docker L1 - L2 Nodes
    • In-Memory Node
    • Continuous Integration
    • Hardhat
    • Foundry
  • API Reference
    • Overview
    • Conventions
    • ZKs JSON-RPC API
    • Debug JSON-RPC API
    • Ethereum JSON-RPC API
    • PubSub JSON-RPC API
  • Concepts
    • Transaction Lifecycle
    • Blocks and Batches
    • Validium Network Fee Mechanism
    • Finality
    • System Upgrades
    • ZK Chains
    • Data Availability
      • Overview
      • Recreating L2 state from L1 pubdata
      • Validiums
    • Account Abstraction
    • L1 <-> L2 Communication
  • Components
    • Overview
    • Smart & System Contracts
      • Smart Contracts
      • System Contracts
    • Shared Bridges
    • Sequencer / Server
    • Validium Network EVM
      • Overview
      • Bootloader
      • Precompiles
      • Virtual Machine Specification
        • ZKsync Virtual Machine primer
        • VM Formal Specification
    • Prover
      • Overview
      • ZK Terminology
      • Running the Prover
      • Circuits
        • Overview
        • Circuit Testing
        • CodeDecommitter
        • DemuxLogQueue
        • ECRecover
        • KeccakRoundFunction
        • L1MessagesHasher
        • LogSorter
        • Main VM
        • RAMPermutation
        • Sha256RoundFunction
        • StorageApplication
        • Sorting and Deduplicating
          • Overview
          • SortDecommitments
          • StorageSorter
          • LogSorter
      • Boojum Gadgets
      • Boojum Function - `check_if_satisfied`
    • Compiler
      • Compiler Toolchain Overview
        • Compiler Toolchain Overview
        • Solidity Compiler
        • Vyper Compiler
        • LLVM Framework
      • Specification
        • Overview
        • Code Separation
        • System Contracts
        • Exception Handling
        • EVM Legacy Assembly Translator
        • Instructions
          • Instruction Reference
          • EVM
            • Native EVM Instructions
            • Arithmetic
            • Bitwise
            • Block
            • Call
            • Create
            • Environment
            • Logging
            • Logical
            • Memory
            • Return
            • Sha3
            • Stack
          • Extensions
            • Overview
            • Validium Network Extension Simulation (call)
            • Validium Network Extension Simulation (verbatim)
          • EVM Legacy Assembly
          • Yul
        • EraVM Binary Layout
    • Fee Withdrawer
    • Portal - Wallet + Bridge
    • Block Explorer
    • Transaction filtering
Powered by GitBook
On this page
  • Installation
  • Running Hardhat's test Task with hardhat-zksync-node
  1. Tooling
  2. Hardhat-Validium
  3. Plugins

hardhat-zksync-node

Guide on using the hardhat-zksync-node plugin.

Previoushardhat-zksync-ethersNextHardhat Community Plugins

Last updated 7 months ago


This plugin is used to provide a convenient way to run ZKsync Era locally using hardhat.

The ZKsync Era In-memory node binaries are not supported on Windows at the moment. As an alternative, users can utilize the Windows Subsystem for Linux (WSL).

Ensure you are using the correct version of the plugin with ethers:

  • For plugin version <1.0.0:

    • Compatible with ethers v5.

  • For plugin version ≥1.0.0:

    • Compatible with ethers v6 (⭐ Recommended)

Installation

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

yarn add -D @matterlabs/hardhat-zksync-node zksync-ethers ethers
npm i -D @matterlabs/hardhat-zksync-node
bun add @matterlabs/hardhat-zksync-node zksync-ethers ethers --dev

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 ZKsync In-memory 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 era_test_node.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 an In-memory 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 In-memory 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.

Provider URL Mismatch:When running tests, be aware that the In-memory node attempts to allocate free ports (starting from the default 8011). This can lead to situations where the provider's URL does not match your expectations. It's strongly recommended to use the network config URL from the hardhat runtime environment to instantiate the Provider instance from the JS SDK, like this:

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

If TypeScript marks the 'url' property indicating a potential issue (even though it works), simply add the following import to your project:

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

Accessing the Network Provider in HardhatApart from the previously described method of instantiating the Provider, you can also directly access it from the Hardhat runtime environment. Due to incompatibilities between Hardhat's EthereumProvider and the JS SDK Provider, we've introduced a new adapter (ZkSyncProviderAdapter). This adapter bridges the gap and ensures that all the necessary functionalities are seamlessly integrated. If you wish to access the JS SDK Provider directly, you can do so in TypeScript with:

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

Parameter Restrictions: The --replay-tx and --fork-block-number parameters cannot be specified simultaneously. The --replay-tx is used for replaying a remote transaction locally for deep debugging, while --fork-block-number is used for forking the blockchain at a specified block number. Combining these actions is not supported.Additionally, if either --replay-tx or --fork-block-number is specified, the --fork parameter must also be provided.Learn More: If you wish to learn more about replaying transactions or forking, check out the .Supported APIs:To see a list of all supported APIs, visit .

In-memory node
@matterlabs/hardhat-zksync-node
In-memory node documentation
this link