Foundry Book

forge script

NAME

forge-script - Run a smart contract as a script, building transactions that can be sent onchain.

SYNOPSIS

forge script [options] path [args...]

DESCRIPTION

Run a smart contract as a script, building transactions that can be sent onchain.

Scripts can be used to apply state transitions on live contracts, or deploy and initialize a complex set of smart contracts using Solidity.

OPTIONS

--broadcast
Broadcasts the transactions.

--debug
Open the script in the debugger. Takes precedence over broadcast.

--legacy
Use legacy transactions instead of EIP1559 ones. This is auto-enabled for common networks without EIP1559.

--resume
Resumes submitting transactions that failed or timed-out previously.

-s
--sig signature
The signature of the function you want to call in the contract, or raw calldata.
Default: run()

--slow
Makes sure a transaction is sent, only after its previous one has been confirmed and succeeded.

--target-contract contract_name
The name of the contract you want to run.

--etherscan-api-key key
Etherscan API key.
Environment: ETHERSCAN_API_KEY

--with-gas-price price
Sets the gas price for broadcasted legacy transactions, or the max fee for broadcasted EIP1559 transactions.
Note: To set the gas price in the execution environment of the script use --gas-price instead (see below).

--json
Output results in JSON format.
Note: The output is under development and prone to change.

Verification Options

--verify
If it finds a matching broadcast log, it tries to verify every contract found in the receipts.

--delay seconds
An optional delay to apply in between verification attempts (in seconds)

--retries count
Number of attempts to retry verifying the contracts.
Default: 1.

Cache Options

--force
Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
Set pre-linked libraries.

The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
Active the Solidity optimizer.

--optimizer-runs runs
The number of optimizer runs.

--via-ir
Use the Yul intermediate representation compilation pipeline.

--revert-strings
How to treat revert and require reason strings.

--use solc_version
Specify the solc version, or a path to a local solc, to build with.

Valid values are in the format x.y.z, solc:x.y.z or path/to/solc.

--offline
Do not access the network. Missing solc versions will not be installed.

--no-auto-detect
Do not auto-detect solc.

--ignored-error-codes error_codes
Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
Extra output to include in the contract's artifact.

Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

For a full description, see the Solidity docs.

---extra-output-files selector
Extra output to write to separate files.

Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

For a full description, see the Solidity docs.

--evm-version version
The target EVM version.

Project Options

--build-info
Generate build info files.

--build-info-path path
Output path to directory that build info files will be written to.

--root path
The project's root path. By default, this is the root directory of the current git repository, or the current working directory.

-c path
--contracts path
The contracts source directory.
Environment: DAPP_SRC

--lib-paths path
The path to the library folder.

-r remappings
--remappings remappings
The project's remappings.

The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
The path to the compiler cache.

--config-path file
Path to the config file.

--hh
--hardhat
This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
The project's artifacts directory.

--silent
Suppress all output

Build Options

--names
Print compiled contract names.

--sizes
Print compiled non-test contract sizes, exiting with code 1 if any of them are above the size limit.

Watch Options

-w [path...]
--watch [path...]
Watch specific file(s) or folder(s)

By default, the project's source directory is watched.

-d delay
--delay delay
File update debounce delay

During the delay, incoming change events are accumulated and only once the delay has passed, is an action taken.
Note that this does not mean a command will be started: if --no-restart is given and a command is already running, the outcome of the action will be to do nothing.

Defaults to 50ms. Parses as decimal seconds by default, but using an itneger with the ms suffix may be more convenient.

When using --poll mode, you'll want a larger duration, or risk overloading disk I/O.

--no-restart
Do not restart the command while it's running.

--run-all
Explicitly re-run the command on all files when a change is made.

Wallet Options - Raw

-i --interactives num
Open an interactive prompt to enter your private key. Takes a value for the number of keys to enter.
Default: 0

--mnemonic-indexes indexes
Use the private key from the given mnemonic index. Used with --mnemonic-path.
Default: 0

--mnemonic-paths paths
Use the mnemonic file at the specified path(s).

--private-key raw_private_key
Use the provided private key.

--private-keys raw_private_keys
Use the provided private keys.

Wallet Options - Keystore

--keystores paths
Use the keystores in the given folders or files.
Environment: ETH_KEYSTORE

--password passwords
The keystore passwords. Used with --keystore.

Wallet Options - Hardware Wallet

-t
--trezor
Use a Trezor hardware wallet.

-l
--ledger
Use a Ledger hardware wallet.

--hd-paths paths
The derivation paths to use with hardware wallets.

Wallet Options - Remote

-a addresses
--froms addresses
Sign the transaction with the specified accounts on the RPC.
Environment: ETH_FROM

EVM Options

-f url
--fork-url url
Fetch state over a remote endpoint instead of starting from an empty state.

If you want to fetch state from a specific block number, see --fork-block-number.

--fork-block-number block
Fetch state from a specific block number over a remote endpoint. See --fork-url.

--no-storage-caching
Explicitly disables the use of RPC caching.

All storage slots are read entirely from the endpoint. See --fork-url.

-v
--verbosity
Verbosity of the EVM.

Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
The address which will be executing tests

--initial-balance balance
The initial balance of deployed contracts

--ffi
Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
The base fee in a block (in wei)

--block-coinbase address
The coinbase of the block

--block-difficulty difficulty
The block difficulty

--block-gas-limit gas_limit
The block gas limit

--block-number block
The block number

--block-timestamp timestamp
The timestamp of the block (in seconds)

--chain-id chain_id
The chain ID

--gas-limit gas_limit
The block gas limit

--gas-price gas_price
The gas price (in wei)

--tx-origin address
The transaction origin

Common Options

-h
--help
Prints help information.

EXAMPLES

Run BroadcastTest as a script, broadcasting generated transactions on-chain

forge script ./test/Broadcast.t.sol --tc BroadcastTest --sig "deploy()" \
             -vvv --fork-url $GOERLI_RPC_URL