0
# Block Mining
1

2
Control block production and mining for deterministic test environments, allowing precise timing of blockchain operations and testing of block-dependent functionality.
3

4
## Capabilities
5

6
### Mine Blocks
7

8
Mines a specified number of blocks with configurable time intervals between them.
9

10
```typescript { .api }
11
/**
12
 * Mines a specified number of blocks with an optional time interval between them
13
 * @param blocks Number of blocks to mine (defaults to 1)
14
 * @param options Configuration options
15
 * @param options.interval Time interval in seconds between each mined block (defaults to 1)
16
 * @returns Promise that resolves once all blocks have been mined
17
 */
18
mine(blocks?: NumberLike, options?: { interval?: NumberLike }): Promise<void>;
19
```
20

21
**Usage Examples:**
22

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

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

28
// Mine a single block (default)
29
await networkHelpers.mine();
30

31
// Mine 5 blocks with default 1-second intervals
32
await networkHelpers.mine(5);
33

34
// Mine 10 blocks with 60-second intervals between each
35
await networkHelpers.mine(10, { interval: 60 });
36

37
// Mine blocks with custom timing
38
await networkHelpers.mine(3, { interval: networkHelpers.time.duration.minutes(5) });
39
```
40

41
### Mine Up To Block Number
42

43
Mines blocks continuously until reaching a target block number.
44

45
```typescript { .api }
46
/**
47
 * Mines new blocks until the latest block number reaches the specified blockNumber
48
 * @param blockNumber Target block number (must be greater than current block number)
49
 * @returns Promise that resolves once the target block number is reached
50
 */
51
mineUpTo(blockNumber: NumberLike): Promise<void>;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
const { networkHelpers } = await network.connect();
58

59
// Get current block number
60
const currentBlock = await networkHelpers.time.latestBlock();
61
console.log(`Current block: ${currentBlock}`);
62

63
// Mine until block 1000
64
await networkHelpers.mineUpTo(1000);
65

66
// Verify we reached the target
67
const newBlock = await networkHelpers.time.latestBlock();
68
console.log(`New block: ${newBlock}`); // Should be 1000
69
```
70

71
## Mining Patterns for Testing
72

73
### Block-Based Timing
74

75
```typescript
76
it("should work after specific block count", async () => {
77
  const { networkHelpers } = await network.connect();
78
  
79
  const contract = await ethers.deployContract("BlockBasedContract");
80
  const startBlock = await networkHelpers.time.latestBlock();
81
  
82
  // Contract requires 10 blocks to pass
83
  await networkHelpers.mine(10);
84
  
85
  const currentBlock = await networkHelpers.time.latestBlock();
86
  expect(currentBlock).to.equal(startBlock + 10);
87
  
88
  // Now contract function should be available
89
  await expect(contract.execute()).to.not.be.reverted;
90
});
91
```
92

93
### Gradual Block Mining
94

95
```typescript
96
it("should handle gradual progression", async () => {
97
  const { networkHelpers } = await network.connect();
98
  
99
  const contract = await ethers.deployContract("ProgressiveContract");
100
  
101
  // Mine blocks gradually with delays
102
  for (let i = 0; i < 5; i++) {
103
    await networkHelpers.mine(1, { interval: 30 }); // 30 seconds between blocks
104
    
105
    const reward = await contract.getReward();
106
    console.log(`Block ${i + 1}, Reward: ${reward}`);
107
  }
108
});
109
```
110

111
### Block Number Synchronization
112

113
```typescript
114
it("should synchronize multiple contracts", async () => {
115
  const { networkHelpers } = await network.connect();
116
  
117
  const contract1 = await ethers.deployContract("Contract1");
118
  const contract2 = await ethers.deployContract("Contract2");
119
  
120
  // Both contracts need to reach block 100
121
  await networkHelpers.mineUpTo(100);
122
  
123
  // Now both should be synchronized
124
  await expect(contract1.syncedFunction()).to.not.be.reverted;
125
  await expect(contract2.syncedFunction()).to.not.be.reverted;
126
});
127
```
128

129
### Testing Block Confirmations
130

131
```typescript
132
it("should handle block confirmations", async () => {
133
  const { networkHelpers } = await network.connect();
134
  
135
  const contract = await ethers.deployContract("MultiSig");
136
  
137
  // Submit transaction
138
  const tx = await contract.submitTransaction("0x123...", 1000, "0x");
139
  const txBlock = await tx.wait().then(r => r.blockNumber);
140
  
141
  // Contract requires 3 block confirmations
142
  await networkHelpers.mineUpTo(txBlock + 3);
143
  
144
  // Now transaction should be confirmed
145
  await expect(contract.executeTransaction(0)).to.not.be.reverted;
146
});
147
```
148

149
### Interval-Based Mining for Oracles
150

151
```typescript
152
it("should update oracle with timed intervals", async () => {
153
  const { networkHelpers } = await network.connect();
154
  
155
  const oracle = await ethers.deployContract("PriceOracle");
156
  
157
  // Oracle updates every 10 minutes (represented as blocks with intervals)
158
  const prices = [100, 105, 102, 98, 103];
159
  
160
  for (const price of prices) {
161
    await oracle.updatePrice(price);
162
    
163
    // Mine block with 10-minute interval
164
    await networkHelpers.mine(1, { 
165
      interval: networkHelpers.time.duration.minutes(10) 
166
    });
167
  }
168
  
169
  const finalPrice = await oracle.getLatestPrice();
170
  expect(finalPrice).to.equal(103);
171
});
172
```
173

174
## Advanced Mining Scenarios
175

176
### Combining Mining with Time Control
177

178
```typescript
179
it("should combine mining and time manipulation", async () => {
180
  const { networkHelpers } = await network.connect();
181
  
182
  // Set specific starting time
183
  const startTime = Math.floor(Date.now() / 1000);
184
  await networkHelpers.time.increaseTo(startTime);
185
  
186
  // Mine blocks with specific time intervals
187
  await networkHelpers.mine(5, { interval: 3600 }); // 1 hour per block
188
  
189
  // Verify final time
190
  const finalTime = await networkHelpers.time.latest();
191
  expect(finalTime).to.equal(startTime + (5 * 3600));
192
});
193
```