0
# Hardhat Toolbox
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @nomicfoundation/hardhat-toolbox
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @nomicfoundation/hardhat-toolbox`
10

11
## Core Imports
12

13
```typescript
14
// Main plugin bundle (import in hardhat.config.ts)
15
import "@nomicfoundation/hardhat-toolbox";
16

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

20
// Or use destructured imports
21
import {
22
  loadFixture,
23
  time,
24
  mine,
25
  impersonateAccount,
26
  setBalance
27
} from "@nomicfoundation/hardhat-toolbox/network-helpers";
28
```
29

30
For CommonJS:
31

32
```javascript
33
// Main plugin bundle (import in hardhat.config.js)
34
require("@nomicfoundation/hardhat-toolbox");
35

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

39
// Or destructured
40
const {
41
  loadFixture,
42
  time,
43
  mine,
44
  impersonateAccount,
45
  setBalance
46
} = require("@nomicfoundation/hardhat-toolbox/network-helpers");
47
```
48

49
## Basic Usage
50

51
```typescript
52
// hardhat.config.ts
53
import { HardhatUserConfig } from "hardhat/config";
54
import "@nomicfoundation/hardhat-toolbox";
55

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

61
export default config;
62
```
63

64
```typescript
65
// test/Lock.test.ts
66
import { expect } from "chai";
67
import { ethers } from "hardhat";
68
import {
69
  loadFixture,
70
  time,
71
  mine
72
} from "@nomicfoundation/hardhat-toolbox/network-helpers";
73

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

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

84
    return { lock, unlockTime, lockedAmount, owner, otherAccount };
85
  }
86

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

92
  it("Should be able to advance time", async function () {
93
    const { lock, unlockTime } = await loadFixture(deployLockFixture);
94
    
95
    // Advance time to after unlock time
96
    await time.increaseTo(unlockTime);
97
    await mine(); // Mine a block to make the time change take effect
98
    
99
    // Now withdrawal should work
100
    await expect(lock.withdraw()).not.to.be.reverted;
101
  });
102
});
103
```
104

105
## Architecture
106

107
The Hardhat Toolbox is built around two main components:
108

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

112
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.
113

114
## Capabilities
115

116
### Plugin Configuration
117

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

120
```typescript { .api }
121
// Plugin registration happens automatically on import
122
import "@nomicfoundation/hardhat-toolbox";
123

124
// Configuration extension function (internal)
125
function extendConfig(config: HardhatConfig, userConfig: HardhatUserConfig): void;
126
```
127

128
The plugin bundle automatically provides:
129
- **Contract interaction**: ethers.js integration via `@nomicfoundation/hardhat-ethers`
130
- **Testing**: Mocha/Chai with blockchain-specific matchers via `@nomicfoundation/hardhat-chai-matchers`
131
- **Deployment**: Hardhat Ignition integration via `@nomicfoundation/hardhat-ignition-ethers`
132
- **Verification**: Source code verification via `@nomicfoundation/hardhat-verify`
133
- **TypeScript**: Contract type generation via `@typechain/hardhat`
134
- **Gas reporting**: Usage analysis via `hardhat-gas-reporter`
135
- **Coverage**: Test coverage measurement via `solidity-coverage`
136

137
[Plugin Configuration](./plugin-configuration.md)
138

139
### Network Helpers
140

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

143
```typescript { .api }
144
// Core fixture management
145
function loadFixture<T>(fixture: () => Promise<T>): Promise<T>;
146
function clearSnapshots(): Promise<void>;
147

148
// Time manipulation namespace
149
namespace time {
150
  function latest(): Promise<number>;
151
  function increase(seconds: number): Promise<void>;
152
  function increaseTo(timestamp: number): Promise<void>;
153
  function advanceBlock(): Promise<void>;
154
  function setNextBlockTimestamp(timestamp: number): Promise<void>;
155
  
156
  namespace duration {
157
    function seconds(amount: number): number;
158
    function minutes(amount: number): number;
159
    function hours(amount: number): number;
160
    function days(amount: number): number;
161
    function weeks(amount: number): number;
162
    function years(amount: number): number;
163
  }
164
}
165

166
// Account and state manipulation
167
function impersonateAccount(address: string): Promise<void>;
168
function setBalance(address: string, balance: bigint): Promise<void>;
169
function mine(blocks?: number): Promise<void>;
170
```
171

172
[Network Helpers](./network-helpers.md)
173

174
## Types
175

176
```typescript { .api }
177
type Fixture<T> = () => Promise<T>;
178

179
interface SnapshotRestorer {
180
  snapshotId: string;
181
  restore(): Promise<void>;
182
}
183

184
interface ValidationError {
185
  message: string;
186
  path: string;
187
}
188
```