or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

accounts.mdblock-config.mdindex.mdmining.mdsnapshots.mdstorage.mdtime.mdtransactions.md
tile.json

tessl/npm-nomicfoundation--hardhat-network-helpers

Hardhat testing utilities for blockchain state manipulation including time control, snapshots, account impersonation, and block mining.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@nomicfoundation/hardhat-network-helpers@3.0.x

To install, run

npx @tessl/cli install tessl/npm-nomicfoundation--hardhat-network-helpers@3.0.0

index.mddocs/

Hardhat Network Helpers

Hardhat Network Helpers is a plugin that provides comprehensive testing utilities for blockchain development. It offers precise control over blockchain state including time manipulation, block mining, account impersonation, snapshots, and storage operations designed specifically for testing smart contracts on locally simulated Ethereum networks.

Package Information

  • Package Name: @nomicfoundation/hardhat-network-helpers
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @nomicfoundation/hardhat-network-helpers

Core Imports

The package is a Hardhat plugin that automatically extends the Hardhat runtime environment when installed:

// In your hardhat.config.ts, the plugin is imported by default
import "@nomicfoundation/hardhat-network-helpers";

Access helpers through Hardhat's network connection:

import { network } from "hardhat";

// The networkHelpers property is automatically available on network connections
const { networkHelpers } = await network.connect();

Type imports for TypeScript development:

import type { NetworkHelpers, Time, Duration } from "@nomicfoundation/hardhat-network-helpers/types";

Basic Usage

import { network } from "hardhat";

const { networkHelpers } = await network.connect();

// Take a blockchain snapshot
const snapshot = await networkHelpers.takeSnapshot();

// Mine some blocks
await networkHelpers.mine(5);

// Advance time by 1 hour
await networkHelpers.time.increase(networkHelpers.time.duration.hours(1));

// Impersonate an account
await networkHelpers.impersonateAccount("0x742d35Cc6635C0532925a3b8D23CAaF803C5C1b7");

// Restore to the snapshot
await snapshot.restore();

Architecture

Hardhat Network Helpers integrates with Hardhat's plugin system and extends the network connection with testing utilities:

  • Plugin Integration: Automatically adds networkHelpers property to Hardhat network connections
  • State Management: Snapshot and restore blockchain state for isolated test environments
  • Time Control: Manipulate blockchain time and block timestamps for time-dependent testing
  • Account Management: Impersonate accounts and manage balances for comprehensive testing scenarios
  • Block Mining: Control block production and mining for precise test timing
  • Storage Access: Direct read/write access to contract storage for advanced testing

Capabilities

Blockchain Snapshots

Create and restore blockchain state snapshots for test isolation and repeatability.

takeSnapshot(): Promise<SnapshotRestorer>;
clearSnapshots(): void;
loadFixture<T>(fixture: Fixture<T>): Promise<T>;

interface SnapshotRestorer {
  restore(): Promise<void>;
  snapshotId: string;
}

type Fixture<T> = () => Promise<T>;

Snapshot Management

Time Manipulation

Control blockchain time and block timestamps for testing time-dependent smart contract functionality.

interface Time {
  increase(amountInSeconds: NumberLike): Promise<number>;
  increaseTo(timestamp: NumberLike | Date): Promise<void>;
  latest(): Promise<number>;
  latestBlock(): Promise<number>;
  setNextBlockTimestamp(timestamp: NumberLike | Date): Promise<void>;
  readonly duration: Duration;
}

Time Control

Block Mining

Precise control over block production and mining for deterministic test environments.

mine(blocks?: NumberLike, options?: { interval?: NumberLike }): Promise<void>;
mineUpTo(blockNumber: NumberLike): Promise<void>;

Block Mining

Account Management

Impersonate accounts and manage balances for comprehensive testing scenarios without private keys.

impersonateAccount(address: string): Promise<void>;
stopImpersonatingAccount(address: string): Promise<void>;
setBalance(address: string, balance: NumberLike): Promise<void>;
setNonce(address: string, nonce: NumberLike): Promise<void>;

Account Management

Storage Operations

Direct read and write access to contract storage slots for advanced testing and state manipulation.

getStorageAt(address: string, index: NumberLike, block?: NumberLike | BlockTag): Promise<string>;
setStorageAt(address: string, index: NumberLike, value: NumberLike): Promise<void>;
setCode(address: string, code: string): Promise<void>;

Storage Operations

Block Properties

Configure block-level properties including gas limits, base fees, and coinbase addresses.

setBlockGasLimit(blockGasLimit: NumberLike): Promise<void>;
setNextBlockBaseFeePerGas(baseFeePerGas: NumberLike): Promise<void>;
setPrevRandao(prevRandao: NumberLike): Promise<void>;
setCoinbase(address: string): Promise<void>;

Block Configuration

Transaction Management

Control transaction mempool state for testing transaction lifecycle and failure scenarios.

dropTransaction(txHash: string): Promise<boolean>;

Transaction Management

Common Types

type NumberLike = number | bigint | string;
type BlockTag = "latest" | "earliest" | "pending";

interface Duration {
  /** Converts years to seconds (365 days per year) */
  years(n: number): number;
  /** Converts weeks to seconds (7 days per week) */
  weeks(n: number): number;
  /** Converts days to seconds (24 hours per day) */
  days(n: number): number;
  /** Converts hours to seconds (60 minutes per hour) */
  hours(n: number): number;
  /** Converts minutes to seconds (60 seconds per minute) */
  minutes(n: number): number;
  /** Returns seconds as-is */
  seconds(n: number): number;
  /** Converts milliseconds to seconds (floor division by 1000) */
  millis(n: number): number;
}