Skip to content

Latest commit

 

History

History
147 lines (109 loc) · 13.3 KB

README.md

File metadata and controls

147 lines (109 loc) · 13.3 KB
Raw

eth-gas-reporter

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.
  • CI integration with codechecks
  • Simple installation for Truffle and Buidler
  • Use ETH, BNB, MATIC, AVAX, HT or MOVR price to calculate the gas price.

Example output

Screen Shot 2019-06-24 at 4 54 47 PM

Installation and Config

Truffle

npm install --save-dev eth-gas-reporter

/* truffle-config.js */
module.exports = {
  networks: { ... },
  mocha: {
    reporter: 'eth-gas-reporter',
    reporterOptions : { ... } // See options below
  }
};

Buidler was renamed to hardhat Use https://github.com/cgewecke/hardhat-gas-reporter for hardhat

Other

This reporter should work with any build platform that uses Mocha and connects to an Ethereum client running as a separate process. There's more on advanced use cases here.

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.

In order to retrieve the gas price of a particular blockchain, you can configure the token and gasPriceApi (API key rate limit may apply).

NOTE: HardhatEVM and ganache-cli implement the Ethereum blockchain. To get accurate gas measurements for other chains you may need to run your tests against development clients developed specifically for those networks.

Option Type Default Description
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
token String 'ETH' The reference token for gas price
gasPriceApi String Etherscan The API endpoint to retrieve the gas price. Find below other networks.
outputFile String stdout File path to write report output to
forceConsoleOutput Boolean false Print report output on console
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[] [] Contract names to exclude from report. Ex: ['Migrations']
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 web3.currentProvider.host RPC client url (ex: "http://localhost:8545")
proxyResolver Function none Custom method to resolve identity of methods managed by a proxy contract.
artifactType Function or String "truffle-v5" Compilation artifact format to consume. (See advanced use.)
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)

token and gasPriceApi options example

Network token gasPriceApi
Ethereum (default) ETH https://api.etherscan.io/api?module=proxy&action=eth_gasPrice
Binance BNB https://api.bscscan.com/api?module=proxy&action=eth_gasPrice
Polygon MATIC https://api.polygonscan.com/api?module=proxy&action=eth_gasPrice
Avalanche AVAX https://api.snowtrace.io/api?module=proxy&action=eth_gasPrice
Heco HT https://api.hecoinfo.com/api?module=proxy&action=eth_gasPrice
Moonriver MOVR https://api-moonriver.moonscan.io/api?module=proxy&action=eth_gasPrice

These APIs have rate limits. Depending on the usage, it might require an API Key.

NB: Any gas price API call which returns a JSON-RPC response formatted like this is supported: {"jsonrpc":"2.0","id":73,"result":"0x6fc23ac00"}.

Advanced Use

An advanced use guide is available here. Topics include:

  • Getting accurate gas data when using proxy contracts like EtherRouter or ZeppelinOS.
  • Configuring the reporter to work with non-truffle, non-buidler projects.

Example Reports

Usage Notes

  • Requires Node >= 8.
  • You cannot use ganache-core as an in-process provider for your test suite. The reporter makes sync RPC calls while collecting data and your tests will hang unless the client is launched as a separate process.
  • Method calls that throw are filtered from the stats.
  • Contracts that are only ever created by other contracts within Solidity are not shown in the deployments table.

Troubleshooting

Contributions

Feel free to open PRs or issues. There is an integration test and one of the mock test cases is expected to fail. If you're adding an option, you can vaildate it in CI by adding it to the mock options config located here.

Credits

All the ideas in this utility have been borrowed from elsewhere. Many thanks to:

  • @maurelian - Mocha reporting gas instead of time is his idea.
  • @cag - The table borrows from / is based his gas statistics work for the Gnosis contracts.
  • Neufund - Block limit size ratios for contract deployments and euro pricing are borrowed from their ico-contracts test suite.

Contributors