hardhat-gas-reporter

Gas Usage Analytics for Hardhat

• Get gas metrics for method calls and deployments on L1 and L2 by running your test suite.
• Get national currency costs of deploying and using your contract system.
• Output data in multiple formats including text, markdown, reStructuredText and JSON.

Example report

• See markdown format example

Installation

npm install --save-dev hardhat-gas-reporter

Add the following to your hardhat.config.ts:

import "hardhat-gas-reporter"

Configuration

Configuration is optional.

// Example
const config: HardhatUserConfig = {
  gasReporter: {
    currency: 'EUR',
    L1: "polygon",
    coinmarketcap: "abc123...",
  }
}

Usage

This plugin overrides the built-in test task. Gas reports are generated by default with:

npx hardhat test

💡 Turning the plugin on/off

The enabled option lets you toggle gas reporting on and off using shell environment variables. Tests run faster when the gas reporter is off because fewer calls are made to the client to read data.

const config: HardhatUserConfig = {
  gasReporter: {
    enabled: (process.env.REPORT_GAS) ? true : false
  }
}

🔍 Caveats about Accuracy:

• Gas readings for pure and view methods are only a lower bound of their real world cost. Actual gas usage will depend on the way the methods are called and the storage/memory state of the EVM at the moment of invocation. For more information on this see the excellent summary at wolfio/evm/gas
• L1 gas readings for Arbitrum & OPStack chains are approximations - some variance is expected.
  • Optimism estimates should be within 1% of observed usage on optimistic-etherscan.
  • Arbitrum estimates should be within 10% of observed usage on arbiscan
• The Hardhat client implements the Ethereum Foundation EVM. To get accurate measurements for other EVM-based chains you may need to run your tests against development clients developed specifically for those networks.

Options

• Option setups for common and advanced use cases can be seen in the Config Examples docs.
• Get a free tier Coinmarketcap API key if you want price data

Utility Tasks

The plugin also provides additional utility commands for managing gas reporter output

hhgas:merge

Merges several JSON formatted gas reports into a single object. This is useful if you're post-processing the data and running your tests in a parallelized CI environment.

Usage

npx hardhat hhgas:merge "gasReporterOutput-*.json"

Supported Networks

API keys for the networks this plugin auto-configures via the L1 and L2 options are available from the links below. In many cases these aren't equired - you'll only need to set them if you start seeing rate-limit warnings.

L2

• arbitrum (live baseFeePerByte prices require an API key)
• base (live blobBaseFee prices require an API key)
• optimism (live blobBaseFee prices require an API key)

L1

• ethereum (gasPrice and baseFee prices require an API key)
• polygon
• binance
• fantom
• moonbeam
• moonriver
• gnosis
• avalanche

Funding

You can support hardhat-gas-reporter via DRIPS, a public goods protocol that helps you direct funding to packages in your dependency tree.