[![npm version](https://badge.fury.io/js/hardhat-gas-reporter.svg)](https://badge.fury.io/js/hardhat-gas-reporter) [![Build Status](https://travis-ci.org/cgewecke/hardhat-gas-reporter.svg?branch=master)](https://travis-ci.org/cgewecke/hardhat-gas-reporter) [![Codechecks](https://raw.githubusercontent.com/codechecks/docs/master/images/badges/badge-default.svg?sanitize=true)](https://codechecks.io) [![buidler](https://hardhat.org/buidler-plugin-badge.svg?1)](https://github.com/cgewecke/hardhat-gas-reporter) # hardhat-gas-reporter [eth-gas-reporter](https://github.com/cgewecke/eth-gas-reporter) plugin for [hardhat](http://gethardhat.com). ## 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 ![Screen Shot 2019-06-23 at 2 10 19 PM](https://user-images.githubusercontent.com/7332026/59982003-c30a4380-95c0-11e9-9d93-e3af979df227.png) ## Installation ```bash npm install hardhat-gas-reporter --save-dev ``` And add the following to your `hardhat.config.js`: ```js require("hardhat-gas-reporter"); ``` Or, if you are using TypeScript, add this to your hardhat.config.ts: ```ts import "hardhat-gas-reporter" ``` **Looking for buidler-gas-reporter docs?** [They moved here...][1] ## Configuration Configuration is optional. ```js module.exports = { gasReporter: { currency: 'CHF', gasPrice: 21 } } ``` :bulb: **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: ```js 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 :warning: **CoinMarketCap API change** :warning: 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][55] 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](https://coinmarketcap.com/api/documentation/v1/#section/Standards-and-Conventions). | | coinmarketcap | _String_ | (unprotected API key) | [API key][55] 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][45] 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][44] and [usage example][47]) | [44]: https://github.com/cgewecke/hardhat-gas-reporter/blob/master/src/types.ts#L27 [45]: https://github.com/cgewecke/hardhat-gas-reporter/releases/tag/v1.0.3 [47]: https://github.com/cgewecke/hardhat-gas-reporter/issues/46#issuecomment-728639165 [55]: https://coinmarketcap.com/api/pricing/ ## Documentation Other useful documentation can be found at [eth-gas-reporter](https://github.com/cgewecke/eth-gas-reporter) [1]: https://github.com/cgewecke/buidler-gas-reporter/tree/buidler-final#installation ## Parallelization This plugin also adds a Hardhat Task for merging several `gasReporterOutput.json` files, which are generated by [eth-gas-reporter](https://github.com/cgewecke/eth-gas-reporter) when [running your tests with in parallelized jobs in CI](https://github.com/cgewecke/eth-gas-reporter/blob/master/docs/gasReporterOutput.md). To use the task you just have to give it the filepaths or a glob pattern pointing to all of the reports: ```bash 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 ```yaml 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 ```