hardhat-gas-reporter

What

A Mocha reporter for Ethereum test suites:

Gas usage per unit test.
Metrics for method calls and deployments.
National currency costs of deploying and using your contract system.

Example report

Installation

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

And add the following to your hardhat.config.js:

require("hardhat-gas-reporter");

Or, if you are using TypeScript, add this to your hardhat.config.ts:

import "hardhat-gas-reporter"

Looking for buidler-gas-reporter docs? They moved here...

Configuration

Configuration is optional.

module.exports = {
  gasReporter: {
    currency: 'CHF',
    gasPrice: 21
  }
}

💡 Pro Tips

Turning the plugin on/off

The options include an enabled key that lets you toggle gas reporting on and off using shell environment variables. When enabled is false, mocha's (faster) default spec reporter is used. Example:

module.exports = {
  gasReporter: {
    enabled: (process.env.REPORT_GAS) ? true : false
  }
}

Migrating from Truffle

If you already have eth-gas-reporter installed in your project, make sure you uninstall it before adding this plugin. hardhat-gas-reporter manages eth-gas-reporter as a dependency and having multiple versions in your lockfile can stop the reporter from working correctly.

Usage

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

npx hardhat test

Options

⚠️ CoinMarketCap API change ⚠️

Beginning March 2020, CoinMarketCap requires an API key to access currency market price data. The reporter uses an unprotected free tier key by default (10k reqs/mo). You can get your own API key here and set it with the coinmarketcap option.

Option	Type	Default	Description
enabled	Boolean	true	Always generate gas reports when running the hardhat test command.
currency	String	'EUR'	National currency to represent gas costs in. Exchange rates loaded at runtime from the `coinmarketcap` api. Available currency codes can be found here.
coinmarketcap	String	(unprotected API key)	API key to use when fetching current market price data. (Use this if you stop seeing price data)
gasPrice	Number	(varies)	Denominated in `gwei`. Default is loaded at runtime from the `eth gas station` api
outputFile	String	stdout	File path to write report output to
noColors	Boolean	false	Suppress report color. Useful if you are printing to file b/c terminal colorization corrupts the text.
onlyCalledMethods	Boolean	true	Omit methods that are never called from report.
rst	Boolean	false	Output with a reStructured text code-block directive. Useful if you want to include report in RTD
rstTitle	String	""	Title for reStructured text header (See Travis for example output)
showTimeSpent	Boolean	false	Show the amount of time spent as well as the gas consumed
excludeContracts	String[]	[]	Contracts (or folders) to exclude from report. Ex: `['Migrations.sol', 'Wallets/']`. (See v1.0.3 release notes for additional usage help)
src	String	"contracts"	Folder in root directory to begin search for `.sol` files. This can also be a path to a subfolder relative to the root, e.g. "planets/annares/contracts"
url	String	`http://localhost:8545` (or network value)	RPC client url
proxyResolver	Function	none	Custom method to resolve identity of methods managed by a proxy contract.
showMethodSig	Boolean	false	Display complete method signatures. Useful when you have overloaded methods you can't tell apart.
maxMethodDiff	Number	undefined	Codechecks failure threshold, triggered when the % diff for any method is greater than `number` (integer)
maxDeploymentDiff	Number	undefined	Codechecks failure threshold, triggered when the % diff for any deployment is greater than `number` (integer)
remoteContracts	RemoteContract[]	`[]`	Contracts pre-deployed to a (forked) network which the reporter should collect gas usage data for. (See RemoteContract type and usage example)

Documentation

Other useful documentation can be found at eth-gas-reporter

Parallelization

This plugin also adds a Hardhat Task for merging several gasReporterOutput.json files, which are generated by eth-gas-reporter when running your tests with in parallelized jobs in CI.

To use the task you just have to give it the filepaths or a glob pattern pointing to all of the reports:

npx hardhat gas-reporter:merge 'gasReporterOutput-*.json'

Here is an example config.yml file used by CircleCI to run the tests on parallel first, and then merge the reports

version: 2.1

jobs:
  test:
    docker:
      - image: circleci/node:14.15.1-stretch
    parallelism: 8
    steps:
      - attach_workspace:
          at: .
      - run:
          name: Run tests
          command: |
            circleci tests glob 'test/**/*.spec.ts' |
            circleci tests split |
            xargs npx hardhat test
      - run:
          name: Save gas report
          command: |
            mv gasReporterOutput.json ./gasReporterOutput-$CIRCLE_NODE_INDEX.json
      - persist_to_workspace:
          root: .
          paths:
            - gasReporterOutput-*.json
  test-gas-report:
    docker:
      - image: circleci/node:14.15.1-stretch
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Upload gas reports
          command: |
            npx hardhat gas-reporter:merge gasReporterOutput-*.json
            npx codechecks codechecks.unit.yml
      - store_artifacts:
          path: gasReporterOutput.json

workflows:
  workflow-all:
    jobs:
      - test
      - test-gas-report:
          requires:
            - test

lucaperret/hardhat-gas-reporter