anvil

NAME

anvil - Create a local testnet node for deploying and testing smart contracts. It can also be used to fork other EVM compatible networks.

SYNOPSIS

anvil [options]

DESCRIPTION

Create a local testnet node for deploying and testing smart contracts. It can also be used to fork other EVM compatible networks.

This section covers an extensive list of information about Mining Modes, Supported Transport Layers, Supported RPC Methods, Anvil flags and their usages. You can run multiple flags at the same time.

Mining Modes

Mining modes refer to how frequent blocks are mined using Anvil. By default, it automatically generates a new block as soon as a transaction is submitted.

You can change this setting to interval mining if you will, which means that a new block will be generated in a given period of time selected by the user. If you want to go for this type of mining, you can do it by adding the --block-time <block-time-in-seconds> flag, like in the following example.

# Produces a new block every 10 seconds
anvil --block-time 10

There's also a third mining mode called never. In this case, it disables auto and interval mining, and mine on demand instead. You can do this by typing:

# Enables never mining mode
anvil --no-mining

Supported Transport Layers

HTTP and Websocket connections are supported. The server listens on port 8545 by default, but it can be changed by running the following command:

anvil --port <PORT>

Supported RPC Methods

Standard Methods

The standard methods are based on this reference.

  • web3_clientVersion

  • web3_sha3

  • eth_chainId

  • eth_networkId

  • eth_gasPrice

  • eth_accounts

  • eth_blockNumber

  • eth_getBalance

  • eth_getStorageAt

  • eth_getBlockByHash

  • eth_getBlockByNumber

  • eth_getTransactionCount

  • eth_getBlockTransactionCountByHash

  • eth_getBlockTransactionCountByNumber

  • eth_getUncleCountByBlockHash

  • eth_getUncleCountByBlockNumber

  • eth_getCode

  • eth_sign

  • eth_signTypedData_v4

  • eth_sendTransaction

  • eth_sendRawTransaction

  • eth_call

  • eth_createAccessList

  • eth_estimateGas

  • eth_getTransactionByHash

  • eth_getTransactionByBlockHashAndIndex

  • eth_getTransactionByBlockNumberAndIndex

  • eth_getTransactionReceipt

  • eth_getUncleByBlockHashAndIndex

  • eth_getUncleByBlockNumberAndIndex

  • eth_getLogs

  • eth_newFilter

  • eth_getFilterChanges

  • eth_newBlockFilter

  • eth_newPendingTransactionFilter

  • eth_getFilterLogs

  • eth_uninstallFilter

  • eth_getWork

  • eth_subscribe

  • eth_unsubscribe

  • eth_syncing

  • eth_submitWork

  • eth_submitHashrate

  • eth_feeHistory

  • eth_getProof

  • debug_traceTransaction
    Use anvil --steps-tracing to get structLogs

  • debug_traceCall Note that non-standard traces are not yet support. This means you can't pass any arguments to the trace parameter.

  • trace_transaction

  • trace_block

Custom Methods

The anvil_* namespace is an alias for hardhat. For more info, refer to the Hardhat documentation.

anvil_impersonateAccount
Send transactions impersonating an externally owned account or contract.

anvil_stopImpersonatingAccount
Stops impersonating an account or contract if previously set with anvil_impersonateAccount

anvil_autoImpersonateAccount
Accepts true to enable auto impersonation of accounts, and false to disable it. When enabled, any transaction's sender will be automatically impersonated. Same as anvil_impersonateAccount.

anvil_getAutomine
Returns true if automatic mining is enabled, and false if it is not

anvil_mine
Mines a series of blocks

anvil_dropTransaction
Removes transactions from the pool

anvil_reset
Reset the fork to a fresh forked state, and optionally update the fork config

anvil_setRpcUrl
Sets the backend RPC URL

anvil_setBalance
Modifies the balance of an account

anvil_setCode
Sets the code of a contract

anvil_setNonce
Sets the nonce of an address

anvil_setStorageAt
Writes a single slot of the account's storage

anvil_setCoinbase
Sets the coinbase address

anvil_setLoggingEnabled
Enable or disable logging

anvil_setMinGasPrice
Set the minimum gas price for the node

anvil_setNextBlockBaseFeePerGas
Sets the base fee of the next block

anvil_dumpState Returns a hex string representing the complete state of the chain. Can be re-imported into a fresh/restarted instance of Anvil to reattain the same state.

anvil_loadState When given a hex string previously returned by anvil_dumpState, merges the contents into the current chain state. Will overwrite any colliding accounts/storage slots.

anvil_nodeInfo Retrieves the configuration params for the currently running Anvil node.

Special Methods

The special methods come from Ganache. You can take a look at the documentation here.

evm_setAutomine
Enables or disables, based on the single boolean argument, the automatic mining of new blocks with each new transaction submitted to the network

evm_setIntervalMining
Sets the mining behavior to interval with the given interval (seconds)

evm_snapshot
Snapshot the state of the blockchain at the current block

evm_revert
Revert the state of the blockchain to a previous snapshot. Takes a single parameter, which is the snapshot id to revert to

evm_increaseTime
Jump forward in time by the given amount of time, in seconds

evm_setNextBlockTimestamp
Similar to evm_increaseTime but takes the exact timestamp that you want in the next block

anvil_setBlockTimestampInterval
Similar to evm_increaseTime but sets a block timestamp interval. The timestamp of the next block will be computed as lastBlock_timestamp + interval

evm_setBlockGasLimit
Sets the block gas limit for the following blocks

anvil_removeBlockTimestampInterval
Removes an anvil_setBlockTimestampInterval if it exists

evm_mine
Mine a single block

anvil_enableTraces
Turn on call traces for transactions that are returned to the user when they execute a transaction (instead of just txhash/receipt)

eth_sendUnsignedTransaction
Execute a transaction regardless of signature status

For the next three methods, make sure to read Geth's documentation.

txpool_status
Returns the number of transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only

txpool_inspect
Returns a summary of all the transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only

txpool_content
Returns the details of all transactions currently pending for inclusion in the next block(s), as well as the ones that are being scheduled for future execution only

OPTIONS

General Options

-a, --accounts <ACCOUNTS>
     Set the number of accounts [default: 10]

-b, --block-time <block-time>
     Block time in seconds for interval mining

--balance <BALANCE>
     Set the balance of the accounts [default: 10000]

--derivation-path <DERIVATION_PATH>
     Set the derivation path of the child key to be derived [default: m/44'/60'/0'/0/]

-h, --help
     Print help information

--hardfork <HARDFORK>
     Choose the EVM hardfork to use      Choose the hardfork by name, e.g. shanghai, paris, london, etc...      [default: latest]

--init <PATH>
     Initialize the genesis block with the given genesis.json file.

-m, --mnemonic <MNEMONIC>
     BIP39 mnemonic phrase used for generating accounts

--no-mining
     Disable auto and interval mining, and mine on demand instead

--order <ORDER>
     How transactions are sorted in the mempool [default: fees]

-p, --port <PORT>
     Port number to listen on [default: 8545]

--steps-tracing
     Enable steps tracing used for debug calls returning geth-style traces [aliases: tracing]

--ipc [<PATH>]
     Starts an IPC endpoint at the given PATH argument or the default path: unix: tmp/anvil.ipc, windows: \\.\pipe\anvil.ipc

--silent
     Don't print anything on startup

--timestamp <TIMESTAMP>      Set the timestamp of the genesis block

-V, --version
     Print version information

EVM Options

-f, --fork-url <URL>
     Fetch state over a remote endpoint instead of starting from an empty state

--fork-block-number <BLOCK>
     Fetch state from a specific block number over a remote endpoint (Must pass --fork-url in the same command-line)

--fork-retry-backoff <BACKOFF>
     Initial retry backoff on encountering errors.

--retries <retries>
     Number of retry requests for spurious networks (timed out requests). [default value= 5]

--timeout <timeout>
     Timeout in ms for requests sent to remote JSON-RPC server in forking mode. [default value= 45000]

--compute-units-per-second <CUPS>
     Sets the number of assumed available compute units per second for this provider [default value=330]      See also, Alchemy Ratelimits

--no-rate-limit      Disables rate limiting for this node's provider. Will always override --compute-units-per-second if present. [default value= false]      See also, Alchemy Ratelimits

--no-storage-caching>
     Explicitly disables the use of RPC caching. All storage slots are read entirely from the endpoint. This flag overrides the project's configuration file (Must pass --fork-url in the same command-line)

Executor Environment Config

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

--chain-id <CHAIN_ID>
     The chain ID

--code-size-limit <CODE_SIZE>
     EIP-170: Contract code size limit in bytes. Useful to increase this because of tests. By default, it is 0x6000 (~25kb)

--gas-limit <GAS_LIMIT>
     The block gas limit

--gas-price <GAS_PRICE>
     The gas price

Server Options

--allow-origin <allow-origin>
     Set the CORS allow_origin [default: *]

--no-cors
     Disable CORS

--host <HOST>
     The IP address the server will listen on

--config-out <OUT_FILE>
     Writes output of anvil as json to user-specified file

--prune-history
     Don't keep full chain history

EXAMPLES

  1. Set the number of accounts to 15 and their balance to 300 ETH
anvil --accounts 15 --balance 300
  1. Choose the address which will execute the tests
anvil --sender 0xC8479C45EE87E0B437c09d3b8FE8ED14ccDa825E
  1. Change how transactions are sorted in the mempool to FIFO
anvil --order fifo

Shell Completions

anvil completions shell

Generates a shell completions script for the given shell.

Supported shells are:

  • bash
  • elvish
  • fish
  • powershell
  • zsh

EXAMPLES

  1. Generate shell completions script for zsh: 
    anvil completions zsh > $HOME/.oh-my-zsh/completions/_anvil

Usage within Docker

In order to run anvil as a service in Github Actions with the Docker container, where passing arguments to the entrypoint command is not possible, use the ANVIL_IP_ADDR environment variable to set the host's IP. ANVIL_IP_ADDR=0.0.0.0 is equivalent to providing the --host <ip> option.