or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdnetwork-helpers.mdplugin-configuration.md
tile.json

tessl/npm-nomicfoundation--hardhat-toolbox

Nomic Foundation's recommended bundle of Hardhat plugins for Ethereum smart contract development with ethers.js integration

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@nomicfoundation/hardhat-toolbox@6.1.x

To install, run

npx @tessl/cli install tessl/npm-nomicfoundation--hardhat-toolbox@6.1.0

index.mddocs/

Hardhat Toolbox

The Hardhat Toolbox is a comprehensive plugin bundle that provides all the essential tools for Ethereum smart contract development with Hardhat. It bundles commonly used plugins and packages into a single installation, providing contract interaction via ethers.js, testing frameworks, deployment tools, verification capabilities, gas reporting, coverage analysis, and TypeScript integration.

Package Information

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

Core Imports

// Main plugin bundle (import in hardhat.config.ts)
import "@nomicfoundation/hardhat-toolbox";

// Network helpers (import in tests/scripts)
import helpers from "@nomicfoundation/hardhat-toolbox/network-helpers";

// Or use destructured imports
import {
  loadFixture,
  time,
  mine,
  impersonateAccount,
  setBalance
} from "@nomicfoundation/hardhat-toolbox/network-helpers";

For CommonJS:

// Main plugin bundle (import in hardhat.config.js)
require("@nomicfoundation/hardhat-toolbox");

// Network helpers
const helpers = require("@nomicfoundation/hardhat-toolbox/network-helpers");

// Or destructured
const {
  loadFixture,
  time,
  mine,
  impersonateAccount,
  setBalance
} = require("@nomicfoundation/hardhat-toolbox/network-helpers");

Basic Usage

// hardhat.config.ts
import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

const config: HardhatUserConfig = {
  solidity: "0.8.20",
  // All toolbox plugins are now automatically available
};

export default config;
// test/Lock.test.ts
import { expect } from "chai";
import { ethers } from "hardhat";
import {
  loadFixture,
  time,
  mine
} from "@nomicfoundation/hardhat-toolbox/network-helpers";

describe("Lock", function () {
  async function deployLockFixture() {
    const [owner, otherAccount] = await ethers.getSigners();
    
    const unlockTime = (await time.latest()) + time.duration.years(1);
    const lockedAmount = ethers.parseEther("1");

    const Lock = await ethers.getContractFactory("Lock");
    const lock = await Lock.deploy(unlockTime, { value: lockedAmount });

    return { lock, unlockTime, lockedAmount, owner, otherAccount };
  }

  it("Should set the right unlock time", async function () {
    const { lock, unlockTime } = await loadFixture(deployLockFixture);
    expect(await lock.unlockTime()).to.equal(unlockTime);
  });

  it("Should be able to advance time", async function () {
    const { lock, unlockTime } = await loadFixture(deployLockFixture);
    
    // Advance time to after unlock time
    await time.increaseTo(unlockTime);
    await mine(); // Mine a block to make the time change take effect
    
    // Now withdrawal should work
    await expect(lock.withdraw()).not.to.be.reverted;
  });
});

Architecture

The Hardhat Toolbox is built around two main components:

  • Plugin Bundle: Automatically imports and configures essential Hardhat plugins including ethers integration, chai matchers, deployment tools, verification, gas reporting, coverage analysis, and TypeScript support
  • Network Helpers: Re-exports comprehensive blockchain testing utilities for fixture management, time manipulation, account impersonation, and state control

When imported, the toolbox automatically registers all plugins with Hardhat and applies sensible default configurations, making all plugin tasks and functionality immediately available in the Hardhat Runtime Environment.

Capabilities

Plugin Configuration

Core plugin bundle that automatically configures the Hardhat development environment with essential tools for smart contract development.

// Plugin registration happens automatically on import
import "@nomicfoundation/hardhat-toolbox";

// Configuration extension function (internal)
function extendConfig(config: HardhatConfig, userConfig: HardhatUserConfig): void;

The plugin bundle automatically provides:

  • Contract interaction: ethers.js integration via @nomicfoundation/hardhat-ethers
  • Testing: Mocha/Chai with blockchain-specific matchers via @nomicfoundation/hardhat-chai-matchers
  • Deployment: Hardhat Ignition integration via @nomicfoundation/hardhat-ignition-ethers
  • Verification: Source code verification via @nomicfoundation/hardhat-verify
  • TypeScript: Contract type generation via @typechain/hardhat
  • Gas reporting: Usage analysis via hardhat-gas-reporter
  • Coverage: Test coverage measurement via solidity-coverage

Plugin Configuration

Network Helpers

Comprehensive blockchain testing utilities for fixture management, time manipulation, account impersonation, and network state control.

// Core fixture management
function loadFixture<T>(fixture: () => Promise<T>): Promise<T>;
function clearSnapshots(): Promise<void>;

// Time manipulation namespace
namespace time {
  function latest(): Promise<number>;
  function increase(seconds: number): Promise<void>;
  function increaseTo(timestamp: number): Promise<void>;
  function advanceBlock(): Promise<void>;
  function setNextBlockTimestamp(timestamp: number): Promise<void>;
  
  namespace duration {
    function seconds(amount: number): number;
    function minutes(amount: number): number;
    function hours(amount: number): number;
    function days(amount: number): number;
    function weeks(amount: number): number;
    function years(amount: number): number;
  }
}

// Account and state manipulation
function impersonateAccount(address: string): Promise<void>;
function setBalance(address: string, balance: bigint): Promise<void>;
function mine(blocks?: number): Promise<void>;

Network Helpers

Types

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

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

interface ValidationError {
  message: string;
  path: string;
}