#Reference

WARNING

This package is in beta. While we don't expect major changes to its API, some details could change.

This is the reference for the Hardhat Network Helpers library. This library contains utility functions to interact with the Hardhat Network in an easier and safer way.

# Mining blocks

#`mine([blocks], [options])`

Mines a specified number of blocks at a given interval.

Parameters:

blocks: Number of blocks to mine. Defaults to 1.
options.interval: Configures the interval (in seconds) between the timestamps of each mined block. Defaults to 1.

Example:

// mine a new block
await helpers.mine();

// mine several blocks
await helpers.mine(1000);

// mine several blocks with a given interval between their timestamps
await helpers.mine(1000, { interval: 15 });

#`mineUpTo(blockNumber)`

Mines new blocks until the latest block number is blockNumber.

Parameters:

blockNumber: Must be greater than the latest block's number.

Example:

await helpers.mineUpTo(1234);

# Manipulating accounts

#`setBalance(address, balance)`

Sets the balance for the given address.

Parameters:

address: The address whose balance will be edited.
balance: The new balance to set for the given address, in wei.

Example:

await helpers.setBalance(address, 100n ** 18n);

#`setCode(address, code)`

Modifies the contract bytecode stored at an account's address.

Parameters:

address: The address where the given code should be stored.
code: The code to store.

Example:

await helpers.setCode(address, "0x1234...");

#`setNonce(address, nonce)`

Modifies an account's nonce by overwriting it.

Parameters:

address: The address whose nonce is to be changed.
nonce: The new nonce.

Example:

await helpers.setNonce(address, 100);

#`setStorageAt(address, index, value)`

Writes a single position of an account's storage.

Parameters:

address: The address where the code should be stored.
index: The index in storage.
value: The value to store.

Example:

await helpers.setStorageAt(address, storageSlot, newValue);

#`getStorageAt(address, index, [block])`

Retrieves the data located at the given address, index, and block number.

Parameters:

address: The address to retrieve storage from.
index: The position in storage.
block: The block number, or one of "latest", "earliest", or "pending". Defaults to "latest".

Returns: A string containing the hexadecimal value retrieved.

Example:

await helpers.getStorageAt(address, storageSlot);

#`impersonateAccount(address)`

Allows Hardhat Network to sign subsequent transactions as the given address.

Parameters:

address: The address to impersonate.

Example:

await helpers.impersonateAccount(address);

#`stopImpersonatingAccount(address)`

Stops Hardhat Network from impersonating the given address.

Parameters:

address: The address to stop impersonating.

Example:

await helpers.stopImpersonatingAccount(address);

# Time helpers

#`latest()`

Returns the timestamp of the latest block.

Example:

await helpers.time.latest();

#`latestBlock()`

Returns the number of the latest block.

Example:

await helpers.time.latestBlock();

#`increase(amountInSeconds)`

Mines a new block whose timestamp is amountInSeconds after the latest block's timestamp.

Parameters:

amountInSeconds: Number of seconds to increase the next block's timestamp by.

Returns: The timestamp of the mined block.

Example:

// advance time by one hour and mine a new block
await helpers.time.increase(3600);

#`increaseTo(timestamp)`

Mines a new block whose timestamp is timestamp.

Parameters:

timestamp: Must be bigger than the latest block's timestamp.

Example:

await helpers.time.increaseTo(newTimestamp);

#`setNextBlockTimestamp(timestamp)`

Sets the timestamp of the next block but doesn't mine one.

Parameters:

timestamp: Can be Date or Epoch seconds. Must be greater than the latest block's timestamp.

Example:

// set the timestamp of the next block but don't mine a new block
await helpers.time.setNextBlockTimestamp(newTimestamp);

# Snapshots

#`takeSnapshot()`

Takes a snapshot of the state of the blockchain at the current block.

Returns: An object with a restore method that can be used to reset the network to the state in the snapshot.

Example:

// take a snapshot of the current state of the blockchain
const snapshot = await helpers.takeSnapshot();

// after doing some changes, you can restore to the state of the snapshot
await snapshot.restore();

# Fixtures

#`loadFixture()`

Useful for beforeEach hooks that setup the desired state of the network.

Executes the given function and takes a snapshot of the blockchain. Upon subsequent calls to loadFixture with the same function, rather than executing the function again, the blockchain will be restored to that snapshot.

Warning: don't use loadFixture with an anonymous function, otherwise the function will be executed each time instead of using snapshots:

Correct usage: loadFixture(deployTokens)
Incorrect usage: loadFixture(async () => { ... })

Parameters:

fixture: The function that will be used to set up the fixture.

Example:

async function deployContractsFixture() {
  const token = await Token.deploy(...);
  const exchange = await Exchange.deploy(...);

  return { token, exchange };
}

it("test", async function () {
  const { token, exchange } = await loadFixture(deployContractsFixture);

  // use token and exchanges contracts
})