0
# Time Control
1

2
Blockchain time manipulation enables testing of time-dependent smart contract functionality by controlling block timestamps and advancing time on the simulated network.
3

4
## Capabilities
5

6
### Increase Time
7

8
Advances blockchain time by a specified number of seconds and mines a new block.
9

10
```typescript { .api }
11
/**
12
 * Mines a new block whose timestamp is amountInSeconds after the latest block's timestamp
13
 * @param amountInSeconds Number of seconds to increase the next block's timestamp by
14
 * @returns Promise resolving to the timestamp of the mined block
15
 */
16
increase(amountInSeconds: NumberLike): Promise<number>;
17
```
18

19
**Usage Example:**
20

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

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

26
// Advance time by 1 hour (3600 seconds)
27
const newTimestamp = await networkHelpers.time.increase(3600);
28
console.log(`New block timestamp: ${newTimestamp}`);
29

30
// Using duration helpers for readability
31
await networkHelpers.time.increase(networkHelpers.time.duration.days(7));
32
```
33

34
### Increase To Timestamp
35

36
Sets blockchain time to a specific timestamp and mines a new block.
37

38
```typescript { .api }
39
/**
40
 * Mines a new block whose timestamp is the specified timestamp
41
 * @param timestamp Target timestamp (Date object or epoch seconds). Must be greater than latest block timestamp
42
 * @returns Promise that resolves when the block is successfully mined
43
 */
44
increaseTo(timestamp: NumberLike | Date): Promise<void>;
45
```
46

47
**Usage Example:**
48

49
```typescript
50
const { networkHelpers } = await network.connect();
51

52
// Set time to specific date
53
const targetDate = new Date('2024-12-31T23:59:59Z');
54
await networkHelpers.time.increaseTo(targetDate);
55

56
// Or using epoch timestamp
57
await networkHelpers.time.increaseTo(1735689599);
58
```
59

60
### Get Latest Timestamp
61

62
Retrieves the timestamp of the most recent block.
63

64
```typescript { .api }
65
/**
66
 * Returns the timestamp of the latest block
67
 * @returns Promise resolving to the latest block timestamp in epoch seconds
68
 */
69
latest(): Promise<number>;
70
```
71

72
**Usage Example:**
73

74
```typescript
75
const { networkHelpers } = await network.connect();
76

77
const currentTime = await networkHelpers.time.latest();
78
console.log(`Current blockchain time: ${new Date(currentTime * 1000)}`);
79
```
80

81
### Get Latest Block Number
82

83
Retrieves the number of the most recent block.
84

85
```typescript { .api }
86
/**
87
 * Retrieves the latest block number
88
 * @returns Promise resolving to the latest block number
89
 */
90
latestBlock(): Promise<number>;
91
```
92

93
**Usage Example:**
94

95
```typescript
96
const { networkHelpers } = await network.connect();
97

98
const blockNumber = await networkHelpers.time.latestBlock();
99
console.log(`Current block number: ${blockNumber}`);
100
```
101

102
### Set Next Block Timestamp
103

104
Configures the timestamp for the next block without immediately mining it.
105

106
```typescript { .api }
107
/**
108
 * Sets the timestamp of the next block but doesn't mine one
109
 * @param timestamp Target timestamp (Date object or epoch seconds). Must be greater than latest block timestamp
110
 * @returns Promise that resolves when timestamp is set
111
 */
112
setNextBlockTimestamp(timestamp: NumberLike | Date): Promise<void>;
113
```
114

115
**Usage Example:**
116

117
```typescript
118
const { networkHelpers } = await network.connect();
119

120
// Set next block timestamp
121
await networkHelpers.time.setNextBlockTimestamp(Date.now() / 1000 + 3600);
122

123
// Next mined block will have the specified timestamp
124
await networkHelpers.mine();
125
```
126

127
## Duration Helpers
128

129
The `duration` property provides convenient time conversion utilities.
130

131
```typescript { .api }
132
interface Duration {
133
  /** Converts years to seconds */
134
  years(n: number): number;
135
  /** Converts weeks to seconds */
136
  weeks(n: number): number;
137
  /** Converts days to seconds */
138
  days(n: number): number;
139
  /** Converts hours to seconds */
140
  hours(n: number): number;
141
  /** Converts minutes to seconds */
142
  minutes(n: number): number;
143
  /** Returns seconds as-is */
144
  seconds(n: number): number;
145
  /** Converts milliseconds to seconds (floor) */
146
  millis(n: number): number;
147
}
148
```
149

150
**Usage Examples:**
151

152
```typescript
153
const { networkHelpers } = await network.connect();
154

155
// Using duration helpers for clarity
156
await networkHelpers.time.increase(networkHelpers.time.duration.hours(2)); // 2 hours
157
await networkHelpers.time.increase(networkHelpers.time.duration.days(30)); // 30 days
158
await networkHelpers.time.increase(networkHelpers.time.duration.weeks(1)); // 1 week
159

160
// Chain multiple durations
161
const timeToAdvance = 
162
  networkHelpers.time.duration.days(1) + 
163
  networkHelpers.time.duration.hours(12) + 
164
  networkHelpers.time.duration.minutes(30);
165

166
await networkHelpers.time.increase(timeToAdvance);
167
```
168

169
## Time Testing Patterns
170

171
### Testing Time Locks
172

173
```typescript
174
it("should respect time lock", async () => {
175
  const { networkHelpers } = await network.connect();
176
  
177
  // Deploy contract with 1 week time lock
178
  const contract = await ethers.deployContract("TimeLocked");
179
  
180
  // Try to execute too early (should fail)
181
  await expect(contract.execute()).to.be.revertedWith("Too early");
182
  
183
  // Advance time by 1 week
184
  await networkHelpers.time.increase(networkHelpers.time.duration.weeks(1));
185
  
186
  // Now should succeed
187
  await expect(contract.execute()).to.not.be.reverted;
188
});
189
```
190

191
### Testing Deadlines
192

193
```typescript
194
it("should handle deadline expiry", async () => {
195
  const { networkHelpers } = await network.connect();
196
  
197
  const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour from now
198
  const contract = await ethers.deployContract("Auction", [deadline]);
199
  
200
  // Should accept bids before deadline
201
  await expect(contract.bid({ value: 100 })).to.not.be.reverted;
202
  
203
  // Advance past deadline
204
  await networkHelpers.time.increaseTo(deadline + 1);
205
  
206
  // Should reject bids after deadline
207
  await expect(contract.bid({ value: 200 })).to.be.revertedWith("Auction ended");
208
});
209
```