0
# Hardhat Network Helpers
1

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

4
## Package Information
5

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

11
## Core Imports
12

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

15
```typescript
16
// In your hardhat.config.ts, the plugin is imported by default
17
import "@nomicfoundation/hardhat-network-helpers";
18
```
19

20
Access helpers through Hardhat's network connection:
21

22
```typescript
23
import { network } from "hardhat";
24

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

29
Type imports for TypeScript development:
30

31
```typescript
32
import type { NetworkHelpers, Time, Duration } from "@nomicfoundation/hardhat-network-helpers/types";
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { network } from "hardhat";
39

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

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

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

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

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

54
// Restore to the snapshot
55
await snapshot.restore();
56
```
57

58
## Architecture
59

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

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

69
## Capabilities
70

71
### Blockchain Snapshots
72

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

75
```typescript { .api }
76
takeSnapshot(): Promise<SnapshotRestorer>;
77
clearSnapshots(): void;
78
loadFixture<T>(fixture: Fixture<T>): Promise<T>;
79

80
interface SnapshotRestorer {
81
  restore(): Promise<void>;
82
  snapshotId: string;
83
}
84

85
type Fixture<T> = () => Promise<T>;
86
```
87

88
[Snapshot Management](./snapshots.md)
89

90
### Time Manipulation
91

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

94
```typescript { .api }
95
interface Time {
96
  increase(amountInSeconds: NumberLike): Promise<number>;
97
  increaseTo(timestamp: NumberLike | Date): Promise<void>;
98
  latest(): Promise<number>;
99
  latestBlock(): Promise<number>;
100
  setNextBlockTimestamp(timestamp: NumberLike | Date): Promise<void>;
101
  readonly duration: Duration;
102
}
103
```
104

105
[Time Control](./time.md)
106

107
### Block Mining
108

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

111
```typescript { .api }
112
mine(blocks?: NumberLike, options?: { interval?: NumberLike }): Promise<void>;
113
mineUpTo(blockNumber: NumberLike): Promise<void>;
114
```
115

116
[Block Mining](./mining.md)
117

118
### Account Management
119

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

122
```typescript { .api }
123
impersonateAccount(address: string): Promise<void>;
124
stopImpersonatingAccount(address: string): Promise<void>;
125
setBalance(address: string, balance: NumberLike): Promise<void>;
126
setNonce(address: string, nonce: NumberLike): Promise<void>;
127
```
128

129
[Account Management](./accounts.md)
130

131
### Storage Operations
132

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

135
```typescript { .api }
136
getStorageAt(address: string, index: NumberLike, block?: NumberLike | BlockTag): Promise<string>;
137
setStorageAt(address: string, index: NumberLike, value: NumberLike): Promise<void>;
138
setCode(address: string, code: string): Promise<void>;
139
```
140

141
[Storage Operations](./storage.md)
142

143
### Block Properties
144

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

147
```typescript { .api }
148
setBlockGasLimit(blockGasLimit: NumberLike): Promise<void>;
149
setNextBlockBaseFeePerGas(baseFeePerGas: NumberLike): Promise<void>;
150
setPrevRandao(prevRandao: NumberLike): Promise<void>;
151
setCoinbase(address: string): Promise<void>;
152
```
153

154
[Block Configuration](./block-config.md)
155

156
### Transaction Management
157

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

160
```typescript { .api }
161
dropTransaction(txHash: string): Promise<boolean>;
162
```
163

164
[Transaction Management](./transactions.md)
165

166
## Common Types
167

168
```typescript { .api }
169
type NumberLike = number | bigint | string;
170
type BlockTag = "latest" | "earliest" | "pending";
171

172
interface Duration {
173
  /** Converts years to seconds (365 days per year) */
174
  years(n: number): number;
175
  /** Converts weeks to seconds (7 days per week) */
176
  weeks(n: number): number;
177
  /** Converts days to seconds (24 hours per day) */
178
  days(n: number): number;
179
  /** Converts hours to seconds (60 minutes per hour) */
180
  hours(n: number): number;
181
  /** Converts minutes to seconds (60 seconds per minute) */
182
  minutes(n: number): number;
183
  /** Returns seconds as-is */
184
  seconds(n: number): number;
185
  /** Converts milliseconds to seconds (floor division by 1000) */
186
  millis(n: number): number;
187
}
188
```