gas-forecaster

A framework-agnostic CLI for forecasting smart contract deployment and transaction costs in USD across multiple EVM networks.

How It Works

gas-forecaster is designed to work seamlessly with both Foundry and Hardhat projects. It does not compile your Solidity code itself. Instead, it intelligently finds the compiled JSON artifacts your framework has already generated.

Important: You must compile your project before running any command.

  • For Foundry: Run forge build
  • For Hardhat: Run npx hardhat compile

The tool automatically searches for artifacts in the standard output directories (out/ for Foundry, artifacts/ for Hardhat).

Usage

The main commands accept a contract name as their primary argument, not a file path.

deploy <CONTRACT_NAME>

Forecasts the cost to deploy a contract.


# For a Foundry or Hardhat project, after compiling:
# Forecast deployment of "MyNFT" across default networks
gas-forecaster deploy MyNFT

# Specify networks and provide constructor arguments
gas-forecaster deploy MyToken --networks ethereum,base --args "My Token" "TKN" 18 1000000

call <CONTRACT_NAME>

Forecasts the cost to call a specific function on a contract.


# Forecast a simple transfer call on the "MyToken" contract
gas-forecaster call MyToken --function transfer --args 0xAb58... 1000000000000000000

report <CONTRACT_NAME> (Pro Feature)

Generates a comprehensive gas report for every function in a contract, using a local Anvil node for simulation.


# Generate a full report for "MyNFT" using Ethereum for price estimates
gas-forecaster report MyNFT --network ethereum

Options

  • --networks <NETWORKS>: A comma-separated list of networks to run the forecast on. Defaults to ethereum,polygon,arbitrum,optimism,bsc.
  • --api-key <KEY>: Your Alchemy API key. Can also be set via the ALCHEMY_API_KEY environment variable or config file.
  • --budget <USD_AMOUNT>: (Pro Feature) Sets a deployment budget in USD. The command will exit with an error if the estimated cost on any network exceeds this budget, making it useful for CI/CD pipelines.
  • --args <ARGS...>: A space-separated list of arguments for the function or constructor.