Socket
Socket
Sign inDemoInstall

hardhat-gas-reporter

Package Overview
Dependencies
298
Maintainers
1
Versions
31
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

    hardhat-gas-reporter

Gas Analytics plugin for Hardhat


Version published
Weekly downloads
90K
increased by3.37%
Maintainers
1
Created
Weekly downloads
 

Readme

Source

npm version Build Status buidler

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

Screen Shot 2024-04-02 at 6 04 53 PM

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

:bulb: 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
  }
}

:mag: 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

OptionsTypeDefaultDescription
currencystringUSDNational currency to represent gas costs in. Exchange rates are loaded at runtime from the coinmarketcap api. Available currency codes can be found here
coinmarketcapstring-API key to use when fetching live token price data
enabledbooltrueProduce gas reports with hardhat test
excludeAutoGeneratedGettersboolfalseExclude solc generated public state vars when reporting gas for pure and view methods. (Incurs a performance penalty on test startup when true) ⚠️ SLOW ⚠️
excludeContractsstring[][]Names of contracts to exclude from report. Ex: ["MyContract"]
includeIntrinsicGasbooltrueInclude standard 21_000 + calldata bytes overhead in method gas usage data. (Setting to false can be useful for modelling contract infra that will never be called by an EOA)
L1stringethereumAuto-configure reporter to emulate an L1 network. (See supported networks)
L2string-Auto-configure reporter to emulate an L2 network (See supported networks)
L1Etherscanstring-API key to use when fetching live gasPrice, baseFee, and blobBaseFee data from an L1 network. (Optional, see Supported Networks)
L2Etherscanstring-API key to use when fetching live gasPrice data from an L2 network (Optional, see Supported Networks)
offlineboolfalseTurn off remote calls to fetch data
optimismHardforkstringecotoneOptimism hardfork to emulate L1 & L2 gas costs for.
proxyResolverClass-User-defined class which helps reporter identify contract targets of proxied calls. (See Advanced Usage)
remoteContractsArray-List of forked-network deployed contracts to track execution costs for.(See Advanced Usage)
reportPureAndViewMethodsboolfalseTrack gas usage for methods invoked via eth_call. (Incurs a performance penalty that can be significant for large test suites)
:high_brightness: DISPLAY
currencyDisplayPrecisionnumber2Decimal precision to show nation state currency costs in
darkModeboolfalseUse colors better for dark backgrounds when printing to stdout
forceTerminalOutputboolfalseWrite to terminal even when saving output to file
forceTerminalOutputFormatstring-Table format to output forced terminal output in ("legacy" / "terminal" / "markdown")
noColorsboolfalseOmit terminal color in output
reportFormatstringterminalReport formats ("legacy" / "terminal" / "markdown")
showMethodSigboolfalseDisplay the complete function signature of methods. (Useful if you have overloaded methods)
showUncalledMethodsboolfalseList all methods and deployments, even if no transactions were recorded for them
suppressTerminalOutputboolfalseSkip writing the table to stdout. (Useful if you only want to write JSON to file)
:floppy_disk: OUTPUT
includeBytecodeInJSONboolfalseInclude bytecode and deployedBytecode blobs in JSON output
outputFilestring-Relative path to a file to output text table to (instead of stdout)
outputJSONFilestring-Relative path to a file to output gas data in JSON format to. (See Advanced Usage)
outputJSONboolfalseWrite options, methods, deployment data in JSON format to file. (See Advanced Usage)
rstboolfalseOutput with a reStructured text code-block directive. (Useful if you want to include report in ReadTheDocs or Sphinx docs)
rstTitlestring-Title for reStructured text header
:mag: LOW-LEVEL CONFIG
gasPricenumber-Gwei price per gas unit (Ex: 25). By default, this is fetched from live network when coinmarketcap option is defined
baseFeenumber-Gwei base fee per gas unit used to calculate L1 calldata costs for L2 transactions (Ex: 25). By default, this is fetched from live network when L2 & coinmarketcap options are defined
baseFeePerBytenumber-Gwei fee per byte used to calculate L1 calldata costs for Arbitrum transactions (Ex: 25). See arbitrum gas estimation docs for details. By default, this is fetched from live network when L2 is set to 'arbitrum' & coinmarketcap options are defined
blobBaseFeenumber-Gwei blob base fee per gas unit used to calculate post-EIP-7516 L1 calldata costs for L2 transactions (Ex: 25). By default, this is fetched from live network when L2 & coinmarketcap options are defined
blobBaseFeeApistring-URL to fetch live execution network blob base fee from. (By default, this is auto-configured based on the L1 or L2 setting)
gasPriceApistring-URL to fetch live execution network gas price from. (By default, this is auto-configured based on the L1 or L2 setting)
getBlockApistring-URL to fetch L1 block header from when simulating L2. (By default, this is auto-configured based on the L2 setting)
opStackBaseFeeScalarnumber-Scalar applied to L1 base fee when calculating L1 data cost (see Advanced Usage)
opStackBlobBaseFeeScalarnumber-Scalar applied to L1 blob base fee when calculating L1 data cost (see Advanced Usage)
tokenstring-Network token gas fees are denominated in (ex:"ETH"). (By default, this is auto-configured based on the L1 or L2 setting)
tokenPricestring-Network token price per nation state currency unit. (To denominate costs in network token set this to "1")

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

Funding

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

Keywords

FAQs

Last updated on 06 Apr 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc