Time manipulation functions

README.md

@@ -377,6 +377,17 @@ Devnet can be restarted by calling `starknet.devnet.restart()`. All of the deplo
 await starknet.devnet.restart();
 ```
 
+#### Time Advancing
+
+The time offset for each generated block can be increased by calling `starknet.devnet.increaseTime()`, and the time for the next block can be set by calling  `starknet.devnet.setTime()` and subsequent blocks will keep the set offset.
+
+Warning: *block time can be set in the past and lead to unexpected behaviour!*
+
+```typescript
+await starknet.devnet.setTime(1000); // time in seconds
+await starknet.devnet.increaseTime(1000); // time in seconds
+```
+
 ## Configure the plugin
 
 Specify custom configuration by editing your project's `hardhat.config.ts` (or `hardhat.config.js`).

src/devnet-utils.ts

@@ -35,8 +35,16 @@ export interface LoadL1MessagingContractResponse {
     l1_provider: string;
 }
 
+export interface SetTimeResponse {
+    next_block_timestamp: number;
+}
+
+export interface IncreaseTimeResponse {
+    timestamp_increased_by: number;
+}
+
 export class DevnetUtils implements Devnet {
-    constructor(private hre: HardhatRuntimeEnvironment) {}
+    constructor(private hre: HardhatRuntimeEnvironment) { }
 
     private get endpoint() {
         return `${this.hre.config.starknet.networkUrl}`;
@@ -79,4 +87,26 @@ export class DevnetUtils implements Devnet {
             return response.data;
         }, "Request failed. Make sure your network has the /postman endpoint");
     }
+
+    public async increaseTime(seconds: number) {
+        return this.withErrorHandler<IncreaseTimeResponse>(async () => {
+            const response = await axios.post<IncreaseTimeResponse>(
+                `${this.endpoint}/increase_time`,
+                {
+                    time: seconds
+                });
+            return response.data;
+        }, "Request failed. Make sure your network has the /increase_time endpoint");
+    }
+
+    public async setTime(seconds: number) {
+        return this.withErrorHandler<SetTimeResponse>(async () => {
+            const response = await axios.post<SetTimeResponse>(
+                `${this.endpoint}/set_time`,
+                {
+                    time: seconds
+                });
+            return response.data;
+        }, "Request failed. Make sure your network has the /set_time endpoint");
+    }
 }

src/type-extensions.ts

@@ -9,7 +9,7 @@ import {
     StringMap
 } from "./types";
 import { StarknetWrapper } from "./starknet-wrappers";
-import { FlushResponse, LoadL1MessagingContractResponse } from "./devnet-utils";
+import { FlushResponse, IncreaseTimeResponse, LoadL1MessagingContractResponse, SetTimeResponse } from "./devnet-utils";
 import { Account, ArgentAccount, OpenZeppelinAccount } from "./account";
 import { Transaction, TransactionReceipt, Block } from "./starknet-types";
 import { HardhatNetworkConfig, NetworkConfig } from "hardhat/types/config";
@@ -121,6 +121,21 @@ declare module "hardhat/types/runtime" {
             address?: string,
             networkId?: string
         ) => Promise<LoadL1MessagingContractResponse>;
+
+
+        /**
+         * Increases the block timestamp offset.
+         * @param seconds the new timestamp in seconds
+         * @returns a timestamp
+         */
+        increaseTime: (seconds: number) => Promise<IncreaseTimeResponse>;
+
+        /**
+         * Sets the block timestamp offset.
+         * @param seconds the new timestamp offset in seconds
+         * @returns a timestamp offset
+         */
+        setTime: (seconds: number) => Promise<SetTimeResponse>;
     }
 
     interface HardhatRuntimeEnvironment {
@@ -213,7 +228,7 @@ declare module "hardhat/types/runtime" {
 
             /**
              * Returns an entire block and the transactions contained within it.
-             * @param optional block identifier (by block number or hash). To query the latest block, remove the identifier.
+             * @param identifier optional block identifier (by block number or hash). To query the latest block, remove the identifier.
              * @returns a block object
              */
             getBlock: (identifier?: BlockIdentifier) => Promise<Block>;