#Reference

# Supported hardforks

byzantium
constantinople
petersburg
istanbul
muirGlacier
berlin
london
arrowGlacier
grayGlacier
merge
shanghai
cancun

# Config

#Supported Fields

You can set the following fields on the networks.hardhat config:

#`chainId`

The chain ID number used by Hardhat Network's blockchain. Default value: 31337.

#`from`

The address to use as default sender. If not present the first account of the Hardhat Network is used.

Its value should be "auto" or a number. If a number is used, it will be the gas limit used by default in every transaction. If "auto" is used, the gas limit will be automatically estimated. Default value: the same value as blockGasLimit.

Note that when using ethers this value will not be applied.

#`gasPrice`

Its value should be "auto" or a number (in wei). This parameter behaves like gas. Default value: "auto".

Note that when using ethers this value will not be applied.

#`gasMultiplier`

A number used to multiply the results of gas estimation to give it some slack due to the uncertainty of the estimation process. Default value: 1.

Note that when using ethers this value will not be applied.

#`accounts`

This field can be configured as one of these:

An object describing an HD wallet. This is the default. It can have any of the following fields:
- mnemonic: a 12 or 24 word mnemonic phrase as defined by BIP39. Default value: "test test test test test test test test test test test junk"
- initialIndex: The initial index to derive. Default value: 0.
- path: The HD parent of all the derived keys. Default value: "m/44'/60'/0'/0".
- count: The number of accounts to derive. Default value: 20.
- accountsBalance: string with the balance (in wei) assigned to every account derived. Default value: "10000000000000000000000" (10000 ETH).
- passphrase: The passphrase for the wallet. Default value: empty string.
An array of the initial accounts that the Hardhat Network will create. Each of them must be an object with privateKey and balance fields.

#`blockGasLimit`

The block gas limit to use in Hardhat Network's blockchain. Default value: 30_000_000

#`hardfork`

This setting changes how Hardhat Network works, to mimic Ethereum's mainnet at a given hardfork. It must be one of "byzantium", "constantinople", "petersburg", "istanbul", "muirGlacier", "berlin", "london", "arrowGlacier", "grayGlacier", "merge", "shanghai" and "cancun". Default value: "shanghai"

#`throwOnTransactionFailures`

A boolean that controls if Hardhat Network throws on transaction failures. If this value is true, Hardhat Network will throw combined JavaScript and Solidity stack traces on transaction failures. If it is false, it will return the failing transaction hash. In both cases the transactions are added into the blockchain. Default value: true

#`throwOnCallFailures`

A boolean that controls if Hardhat Network throws on call failures. If this value is true, Hardhat Network will throw combined JavaScript and Solidity stack traces when a call fails. If it is false, it will return the call's return data, which can contain a revert reason. Default value: true

#`loggingEnabled`

A boolean that controls if Hardhat Network logs every request or not. Default value: false for the in-process Hardhat Network provider, true for the Hardhat Network backed JSON-RPC server (i.e. the node task).

#`initialDate`

An optional string setting the date of the blockchain. Valid values are Javascript's date time strings. Default value: the current date and time if not forking another network. When forking another network, the timestamp of the block you forked from, plus one second, is used.

#`allowUnlimitedContractSize`

An optional boolean that disables the contract size limit imposed by the EIP 170. Default value: false

#`allowBlocksWithSameTimestamp`

A boolean to allow mining blocks that have the same timestamp. This is not allowed by default because Ethereum's consensus rules specify that each block should have a different timestamp. Default value: false

#`forking`

An object that describes the forking configuration that can have the following fields:

url: a URL that points to a JSON-RPC node with state that you want to fork off. There's no default value for this field. It must be provided for the fork to work.
blockNumber: an optional number to pin which block to fork from. If no value is provided, the latest block is used.
enabled: an optional boolean to switch on or off the fork functionality. Default value: true if url is set, false otherwise.

#`chains`

An object that configures chain-specific options. Each key is a number representing a chain ID, and each value is an object configuring the chain with that ID. In the inner object, the following fields are supported:

hardforkHistory: an object whose keys are strings representing hardfork names (eg "london", "berlin") and whose values are numbers specifying the block at which that hardfork was activated.

The default value includes configurations for several well known chains (eg mainnet, chain ID 1); using this field is only useful when forking unusual networks. The user may override the defaults for some chain ID's while leaving the defaults in place for other chain ID's. Overriding the default for a chain ID will replace the entire configuration for that chain.

For more details, see Using a custom hardfork history.

#`minGasPrice`

The minimum gasPrice that a transaction must have. This field must not be present if the "hardfork" is "london" or a later one. Default value: "0".

#`initialBaseFeePerGas`

The baseFeePerGas of the first block. Note that when forking a remote network, the "first block" is the one immediately after the block you forked from. This field must not be present if the "hardfork" is not "london" or a later one. Default value: "1000000000" if not forking. When forking a remote network, if the remote network uses EIP-1559, the first local block will use the right baseFeePerGas according to the EIP, otherwise "10000000000" is used.

#`coinbase`

The address used as coinbase in new blocks. Default value: "0xc014ba5ec014ba5ec014ba5ec014ba5ec014ba5e".

#Mining modes

You can configure the mining behavior under your Hardhat Network settings:

networks: {
  hardhat: {
    mining: {
      auto: false,
      interval: 5000
    }
  }
}

In this example, automining is disabled and interval mining is set so that a new block is generated every 5 seconds. You can also configure interval mining to generate a new block after a random delay:

networks: {
  hardhat: {
    mining: {
      auto: false,
      interval: [3000, 6000]
    }
  }
}

In this case, a new block will be mined after a random delay of between 3 and 6 seconds. For example, the first block could be mined after 4 seconds, the second block 5.5 seconds after that, and so on.

#Manual mining

You can disable both mining modes like this:

networks: {
  hardhat: {
    mining: {
      auto: false,
      interval: 0
    }
  }
}

This means that no new blocks will be mined by the Hardhat Network, but you can manually mine new blocks using the evm_mine RPC method. This will generate a new block that will include as many pending transactions as possible.

#Transaction ordering

Hardhat Network can sort mempool transactions in two different ways. How they are sorted will alter which transactions from the mempool get included in the next block, and in which order.

The first ordering mode, called "priority", mimics Geth's behavior. This means that it prioritizes transactions based on the fees paid to the miner. This is the default.

The second ordering mode, called "fifo", keeps the mempool transactions sorted in the order they arrive.

You can change the ordering mode with:

networks: {
  hardhat: {
    mining: {
      mempool: {
        order: "fifo"
      }
    }
  }
}

# `console.log`

You can use it in calls and transactions. It works with view functions, but not in pure ones.
It always works, regardless of the call or transaction failing or being successful.
To use it you need to import hardhat/console.sol.
You can call console.log with up to 4 parameters in any order of following types:
- uint
- string
- bool
- address
There's also the single parameter API for the types above, and additionally bytes, bytes1... up to bytes32:
- console.logInt(int i)
- console.logUint(uint i)
- console.logString(string memory s)
- console.logBool(bool b)
- console.logAddress(address a)
- console.logBytes(bytes memory b)
- console.logBytes1(bytes1 b)
- console.logBytes2(bytes2 b)
- ...
- console.logBytes32(bytes32 b)
console.log implements the same formatting options that can be found in Node.js' console.log, which in turn uses util.format.
- Example: console.log("Changing owner from %s to %s", currentOwner, newOwner)
console.log is implemented in standard Solidity and then detected in Hardhat Network. This makes its compilation work with any other tools (like Remix, Waffle or Truffle).
console.log calls can run in other networks, like mainnet, sepolia, goerli, etc. They do nothing in those networks, but do spend a minimal amount of gas.
console.log output can also be viewed for testnets and mainnet via Tenderly.
console.log works by sending static calls to a well-known contract address. At runtime, Hardhat Network detects calls to that address, decodes the input data to the calls, and writes it to the console.

# Initial State

Hardhat Network is initialized by default in this state:

A brand new blockchain, just with the genesis block.
20 accounts with 10000 ETH each, generated with the mnemonic "test test test test test test test test test test test junk". Their addresses are:
- 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
- 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
- 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC
- 0x90F79bf6EB2c4f870365E785982E1f101E93b906
- 0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65
- 0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc
- 0x976EA74026E726554dB657fA54763abd0C3a0aa9
- 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955
- 0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f
- 0xa0Ee7A142d267C1f36714E4a8F75612F20a79720
- 0xBcd4042DE499D14e55001CcbB24a551F3b954096
- 0x71bE63f3384f5fb98995898A86B02Fb2426c5788
- 0xFABB0ac9d68B0B445fB7357272Ff202C5651694a
- 0x1CBd3b2770909D4e10f157cABC84C7264073C9Ec
- 0xdF3e18d64BC6A983f673Ab319CCaE4f1a57C7097
- 0xcd3B766CCDd6AE721141F452C550Ca635964ce71
- 0x2546BcD3c84621e976D8185a91A922aE77ECEc30
- 0xbDA5747bFD65F08deb54cb465eB87D40e51B197E
- 0xdD2FD4581271e230360230F9337D5c0430Bf44C0
- 0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199

To customise it, take a look at the configuration section.

# JSON-RPC methods support

#Standard methods

#`debug_traceCall`

Traces the execution of an eth_call within the context of a specific block's execution. See the Geth's documentation for more info.

Arguments:

transaction object
blockTag: optional, default value is "latest"
traceConfig: optional object with the following properties:
- disableMemory: optional boolean, default value is false
- disableStack: optional boolean, default value is false
- disableStorage: optional boolean, default value is false

Example without traceConfig:

const result = await network.provider.send("debug_traceCall", [
  {
    from: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    to: "0x4b23ad35Da73fEe8154CDc8b291c814028A4E743",
    data: "0xc0129d43",
  },
  "latest",
]);

Example with traceConfig:

const trace = await network.provider.send("debug_traceCall", [
  {
    from: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    to: "0x4b23ad35Da73fEe8154CDc8b291c814028A4E743",
    data: "0xc0129d43",
  },
  "latest",
  {
    disableMemory: true,
    disableStack: true,
    disableStorage: true,
  },
]);

#`debug_traceTransaction`

Get debug traces of already-mined transactions.

To get a trace, call this method with the hash of the transaction as its argument:

const trace = await hre.network.provider.send("debug_traceTransaction", [
  "0x123...",
]);

You can also selectively disable some properties in the list of steps:

const trace = await hre.network.provider.send("debug_traceTransaction", [
  "0x123...",
  {
    disableMemory: true,
    disableStack: true,
    disableStorage: true,
  },
]);

#Known limitations

You can't trace transactions that use a hardfork older than Spurious Dragon
The last step of a message is not guaranteed to have a correct value in the gasCost property

#`eth_accounts`

#`eth_blockNumber`

#`eth_call`

This method allows you to simulate a transaction without actually executing it. See the Geth's documentation for more info.

Example:

const result = await network.provider.send("eth_call", [
  {
    from: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    to: "0x4b23ad35Da73fEe8154CDc8b291c814028A4E743",
    data: "0xc0129d43",
  },
  "latest",
]);

You can optionally pass a state override object to modify the chain before running the call:

const result = await network.provider.send("eth_call", [
  {
    from: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
    to: "0x4b23ad35Da73fEe8154CDc8b291c814028A4E743",
    data: "0xc0129d43",
  },
  "latest",
  {
    "0x6eE6DE5a56910E5353933761305AEF6a414d97BA": {
      balance: "0xde0b6b3a7640000",
      nonce: "0x123",
      stateDiff: {
        "0x0000000000000000000000000000000000000000000000000000000000000002":
          "0x000000000000000000000000000000000000000000000000000000000000000c",
      },
    },
  },
]);

#`eth_chainId`

#`eth_coinbase`

#`eth_estimateGas`

#`eth_gasPrice`

#`eth_getBalance`

#`eth_getBlockByHash`

#`eth_getBlockByNumber`

#`eth_getBlockTransactionCountByHash`

#`eth_getBlockTransactionCountByNumber`

#`eth_getCode`

#`eth_getFilterChanges`

#`eth_getFilterLogs`

#`eth_getLogs`

#`eth_getStorageAt`

#`eth_getTransactionByBlockHashAndIndex`

#`eth_getTransactionByBlockNumberAndIndex`

#`eth_getTransactionByHash`

#`eth_getTransactionCount`

#`eth_getTransactionReceipt`

#`eth_mining`

#`eth_newBlockFilter`

#`eth_newFilter`

#`eth_newPendingTransactionFilter`

#`eth_pendingTransactions`

#`eth_sendRawTransaction`

#`eth_sendTransaction`

#`eth_sign`

#`eth_signTypedData_v4`

#`eth_subscribe`

#`eth_syncing`

#`eth_uninstallFilter`

#`eth_unsubscribe`

#`net_listening`

#`net_peerCount`

#`net_version`

#`web3_clientVersion`

#`web3_sha3`

#Hardhat network methods

TIP

Most of these methods can be used more easily through the Hardhat Network Helpers library

#`hardhat_addCompilationResult`

Add information about compiled contracts

#`hardhat_dropTransaction`

Remove a transaction from the mempool

#`hardhat_impersonateAccount`

Hardhat Network allows you to send transactions impersonating specific account and contract addresses.

To impersonate an account use this method, passing the address to impersonate as its parameter:

await hre.network.provider.request({
  method: "hardhat_impersonateAccount",
  params: ["0x364d6D0333432C3Ac016Ca832fb8594A8cE43Ca6"],
});

If you are using hardhat-ethers, call getSigner after impersonating the account:

const signer = await ethers.getSigner("0x364d6D0333432C3Ac016Ca832fb8594A8cE43Ca6")
signer.sendTransaction(...)

Call hardhat_stopImpersonatingAccount to stop impersonating.

#`hardhat_getAutomine`

Returns true if automatic mining is enabled, and false otherwise. See Mining Modes to learn more.

#`hardhat_metadata`

Returns an object with metadata about the instance of the Hardhat Network. This object contains:

clientVersion: A string identifying the version of Hardhat, for debugging purposes, not meant to be displayed to users.
chainId: The chain's id. Used to sign transactions.
instanceId: A 0x-prefixed hex-encoded 32 bytes id which uniquely identifies an instance/run of Hardhat Network. Running Hardhat Network more than once (even with the same version and parameters) will always result in different instanceIds. Running hardhat_reset will change the instanceId of an existing Hardhat Network.
latestBlockNumber: The latest block's number in Hardhat Network.
latestBlockHash: The latest block's hash in Hardhat Network.
forkedNetwork: An object with information about the forked network. This field is only present when Hardhat Network is forking another chain. Its fields are:
- chainId: The chainId of the network that is being forked
- forkBlockNumber: The number of the block that the network forked from.
- forkBlockHash: The hash of the block that the network forked from.

#`hardhat_mine`

Sometimes you may want to advance the latest block number of the Hardhat Network by a large number of blocks. One way to do this would be to call the evm_mine RPC method multiple times, but this is too slow if you want to mine thousands of blocks. The hardhat_mine method can mine any number of blocks at once, in constant time. (It exhibits the same performance no matter how many blocks are mined.)

hardhat_mine accepts two parameters, both of which are optional. The first parameter is the number of blocks to mine, and defaults to 1. The second parameter is the interval between the timestamps of each block, in seconds, and it also defaults to 1. (The interval is applied only to blocks mined in the given method invocation, not to blocks mined afterwards.)

// mine 256 blocks
await hre.network.provider.send("hardhat_mine", ["0x100"]);

// mine 1000 blocks with an interval of 1 minute
await hre.network.provider.send("hardhat_mine", ["0x3e8", "0x3c"]);

Note that most blocks mined via this method (all except for the final one) may not technically be valid blocks. Specifically, they have an invalid parent hash, the coinbase account will not have been credited with block rewards, and the baseFeePerGas will be incorrect. (The final block in a sequence produced by hardhat_mine will always be fully valid.)

Also note that blocks created via hardhat_mine may not trigger new-block events, such as filters created via eth_newBlockFilter and WebSocket subscriptions to new-block events.

#`hardhat_reset`

You can manipulate forking during runtime to reset back to a fresh forked state, fork from another block number or disable forking by calling hardhat_reset:

Infura

Alchemy

await network.provider.request({
  method: "hardhat_reset",
  params: [
    {
      forking: {
        jsonRpcUrl: "https://mainnet.infura.io/v3/<key>",
        blockNumber: 14390000,
      },
    },
  ],
});

await network.provider.request({
  method: "hardhat_reset",
  params: [
    {
      forking: {
        jsonRpcUrl: "https://eth-mainnet.g.alchemy.com/v2/<key>",
        blockNumber: 14390000,
      },
    },
  ],
});

You can disable forking by passing empty params:

await network.provider.request({
  method: "hardhat_reset",
  params: [],
});

This will reset the Hardhat Network, starting a new instance in the state described here.

#`hardhat_setBalance`

Modifies the balance of an account.

For example:

await network.provider.send("hardhat_setBalance", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
  "0x1000",
]);

This will result in account 0x0d20...000B having a balance of 4096 wei.

#`hardhat_setCode`

Modifies the bytecode stored at an account's address.

For example:

await network.provider.send("hardhat_setCode", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
  "0xa1a2a3...",
]);

This will result in account 0x0d20...000B becoming a smart contract with bytecode a1a2a3.... If that address was already a smart contract, then its code will be replaced by the specified one.

#`hardhat_setCoinbase`

Sets the coinbase address to be used in new blocks.

For example:

await network.provider.send("hardhat_setCoinbase", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
]);

This will result in account 0x0d20...000B being used as miner/coinbase in every new block.

#`hardhat_setLoggingEnabled`

Enable or disable logging in Hardhat Network

#`hardhat_setMinGasPrice`

Change the minimum gas price accepted by the network (in wei)

#`hardhat_setNextBlockBaseFeePerGas`

Sets the base fee of the next block.

For example:

await network.provider.send("hardhat_setNextBlockBaseFeePerGas", [
  "0x2540be400", // 10 gwei
]);

This only affects the next block; the base fee will keep being updated in each subsequent block according to EIP-1559.

#`hardhat_setPrevRandao`

Sets the PREVRANDAO value of the next block.

For example:

await network.provider.send("hardhat_setPrevRandao", [
  "0x1234567812345678123456781234567812345678123456781234567812345678",
]);

This only affects the next block. The PREVRANDAO of the following blocks will continue to be computed as the keccak256 hash of the previous value.

#`hardhat_setNonce`

Modifies an account's nonce by overwriting it.

For example:

await network.provider.send("hardhat_setNonce", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
  "0x21",
]);

This will result in account 0x0d20...000B having a nonce of 33.

Throws an InvalidInputError if nonce is smaller than the current one. The reason for this restriction is to avoid collisions when deploying contracts using the same nonce more than once.

You can only use this method to increase the nonce of an account; you can't set a lower value than the account's current nonce.

#`hardhat_setStorageAt`

Writes a single position of an account's storage.

For example:

await network.provider.send("hardhat_setStorageAt", [
  "0x0d2026b3EE6eC71FC6746ADb6311F6d3Ba1C000B",
  "0x0",
  "0x0000000000000000000000000000000000000000000000000000000000000001",
]);

This will set the contract's first storage position (at index 0x0) to 1.

The mapping between a smart contract's variables and its storage position is not straightforward except in some very simple cases. For example, if you deploy this contract:

contract Foo {
  uint public x;
}

And you set the first storage position to 1 (as shown in the previous snippet), then calling foo.x() will return 1.

The storage position index must not exceed 2^256, and the value to write must be exactly 32 bytes long.

#`hardhat_stopImpersonatingAccount`

Use this method to stop impersonating an account after having previously used hardhat_impersonateAccount, like:

await hre.network.provider.request({
  method: "hardhat_stopImpersonatingAccount",
  params: ["0x364d6D0333432C3Ac016Ca832fb8594A8cE43Ca6"],
});

#Special testing/debugging methods

#`evm_increaseTime`

Same as Ganache.

#`evm_mine`

Same as Ganache

#`evm_revert`

Same as Ganache.

#`evm_setAutomine`

Enables or disables, based on the single boolean argument, the automatic mining of new blocks with each new transaction submitted to the network. You can use hardhat_getAutomine to get the current value. See also Mining Modes.

#`evm_setBlockGasLimit`

#`evm_setIntervalMining`

Enables (with a numeric argument greater than 0) or disables (with a numeric argument equal to 0), the automatic mining of blocks at a regular interval of milliseconds, each of which will include all pending transactions. See also Mining Modes.

#`evm_setNextBlockTimestamp`

This method works like evm_increaseTime, but takes the exact timestamp that you want in the next block, and increases the time accordingly.

#`evm_snapshot`

Same as Ganache.

Snapshot the state of the blockchain at the current block. Takes no parameters. Returns the id of the snapshot that was created. A snapshot can only be reverted once. After a successful evm_revert, the same snapshot id cannot be used again. Consider creating a new snapshot after each evm_revert if you need to revert to the same point multiple times.