eth-gas-reporter: Gas Usage for Ethereum Tests

Common errors

• CoinMarketCap API Key is not set or invalid.

  cause The reporter attempted to fetch cryptocurrency prices but found a missing or invalid CoinMarketCap API key.
  fix Obtain a valid API key from CoinMarketCap and set it using the `coinmarketcap` option in your `reporterOptions` configuration or as an environment variable.

• Error: Reporter 'eth-gas-reporter' not found.

  cause Mocha could not locate the `eth-gas-reporter` package, often due to incorrect installation or an improper path.
  fix Ensure `eth-gas-reporter` is installed as a dev dependency (`npm install --save-dev eth-gas-reporter`) and that your Mocha configuration correctly specifies its name: `reporter: 'eth-gas-reporter'`.

• Error: Cannot find module 'hardhat-gas-reporter'

  cause When using Hardhat/Buidler, the dedicated plugin `hardhat-gas-reporter` is missing, not `eth-gas-reporter` directly.
  fix Install the specific plugin for Hardhat/Buidler: `npm install --save-dev hardhat-gas-reporter` and include it in your configuration file using `require('hardhat-gas-reporter');`.

Warnings

• breaking Starting March 2020, the CoinMarketCap API requires a valid API key for fetching cryptocurrency market price data. Using the reporter for national currency conversions without this key will result in failures.
  Fix: Obtain a free API key from CoinMarketCap and set it via the `coinmarketcap` option in `reporterOptions` or as an environment variable (e.g., `process.env.COINMARKETCAP_API_KEY`).
• breaking The underlying Mocha dependency was updated to v10. This update may introduce compatibility issues with older Mocha test suites or custom Mocha configurations if not managed correctly.
  Fix: Ensure your project's Mocha version is compatible with v10. Refer to Mocha's official migration guide for potential breaking changes and necessary adjustments.
• gotcha When integrating with Hardhat (formerly Buidler), the `eth-gas-reporter` package is not configured directly. Instead, you must install and utilize the separate `hardhat-gas-reporter` plugin.
  Fix: Install `hardhat-gas-reporter` (`npm install --save-dev hardhat-gas-reporter`) and configure it in your `hardhat.config.js` using `require('hardhat-gas-reporter');` or `import 'hardhat-gas-reporter';`.
• breaking Internal changes in v0.2.27 removed `@ethersproject/abi` in favor of `ethers.utils`. This primarily affects maintainers or developers who might have been interacting with the reporter's internal `ethers` dependencies directly.
  Fix: No direct user action is required for typical usage. If you were extending or deeply integrating with internal `ethers` utilities, review your code for compatibility with `ethers` v5 or newer's `utils` module.
• gotcha The reporter makes synchronous RPC calls during data collection. Running your test suite with an in-process provider like `ganache-core` can cause tests to hang.
  Fix: Launch your Ethereum client (e.g., Ganache, Hardhat Network) as a separate process and connect to it over RPC. Avoid in-process providers for test execution with this reporter.

Install

• npm install eth-gas-reporter npm
• yarn add eth-gas-reporter yarn
• pnpm add eth-gas-reporter pnpm

Imports

• reporter configuration string
  wrong:

  import EthGasReporter from 'eth-gas-reporter'

  correct:

  mocha: { reporter: 'eth-gas-reporter' }

  The `eth-gas-reporter` library is primarily consumed as a string identifier within a Mocha test runner's configuration, not directly imported as a JavaScript/TypeScript module into user code for its core functionality. It is loaded by Mocha itself.
• reporterOptions object
  wrong:

  import { reporterOptions } from 'eth-gas-reporter'

  correct:

  mocha: { reporterOptions: { currency: 'USD', token: 'ETH' } }

  Configuration options are passed as a plain JavaScript object within the Mocha configuration. These options are not exported symbols for direct import but rather properties of a configuration object.
• Hardhat/Buidler Plugin
  wrong:

  require('eth-gas-reporter'); // directly in hardhat.config.js

  correct:

  require('hardhat-gas-reporter'); // in hardhat.config.js or buidler.config.js

  For Hardhat and Buidler projects, a separate plugin (`hardhat-gas-reporter`, formerly `buidler-gas-reporter`) is required and imported to integrate this reporter. The core `eth-gas-reporter` package is then used by that plugin.

Quickstart

Demonstrates how to configure `eth-gas-reporter` within a `truffle-config.js` file, including example network setup and various reporter options for currency, token, and output format.

/* truffle-config.js */
const HDWalletProvider = require('@truffle/hdwallet-provider'); // Example dependency for network config

module.exports = {
  networks: {
    development: {
      host: '127.0.0.1',
      port: 8545,
      network_id: '*',
    },
    goerli: {
      provider: () => new HDWalletProvider(
        process.env.MNEMONIC ?? 'your_mnemonic_here',
        `https://goerli.infura.io/v3/${process.env.INFURA_PROJECT_ID ?? ''}`
      ),
      network_id: 5,
      gasPrice: 10000000000, // 10 Gwei
      confirmations: 2,
      timeoutBlocks: 200,
      skipDryRun: true
    },
  },
  mocha: {
    reporter: 'eth-gas-reporter',
    reporterOptions : {
      currency: 'USD',
      token: 'ETH',
      gasPrice: 20, // Example fixed gas price in Gwei
      coinmarketcap: process.env.COINMARKETCAP_API_KEY ?? '', // Required for currency conversions
      outputFile: 'gas-report.txt',
      noColors: false,
      rst: true, // Use ReStructuredText format for output
      rstTitle: 'Gas Usage Report'
    }
  },
  compilers: {
    solc: {
      version: '0.8.0', // Specify your Solidity compiler version
    },
  },
};