Configuration options

The following is a list of all the options that may be provided in the Echidna configuration file. Whenever an option can also be set via the command line, the CLI equivalent flag is provided as a reference. Some flags are relatively new and only available on recent Echidna builds; in those cases, the minimum Echidna version required to use the feature is indicated in the table.

testMode

TypeDefaultAvailable inCLI equivalent
String"property"*--test-mode MODE

The test mode to run. It should be one of the following items:

  • "property": Run user-defined property tests.
  • "assertion": Detect assertion failures (previously checkAsserts).
  • "optimization": Find the maximum value for a function.
  • "overflow": Detect integer overflows (only available in Solidity 0.8.0 or greater).
  • "exploration": Run contract code without executing any tests.

Review the testing modes tutorial to select the one most suitable to your project.

testLimit

TypeDefaultAvailable inCLI equivalent
Int50000*--test-limit N

Number of transactions to generate during testing. The campaign will stop when the testLimit is reached or if a timeout is set and the execution time exceeds it.

seqLen

TypeDefaultAvailable inCLI equivalent
Int100*--seq-len N

Number of transactions that a transaction sequence will have during testing, and maximum length of transaction sequences in the corpus. After every N transactions, Echidna will reset the EVM to the initial post-deployment state.

timeout

TypeDefaultAvailable inCLI equivalent
Intnull*--timeout N

Campaign timeout, in seconds. By default it is not time-limited. If a value is set, the campaign will stop when the time is exhausted or the testLimit is reached, whichever happens first.

seed

TypeDefaultAvailable inCLI equivalent
Intrandom*--seed N

Seed used for random value generation. By default it is a random integer. The seed may not guarantee reproducibility if multiple workers are used, as the operating system thread scheduling may introduce additional randomness into the process.

shrinkLimit

TypeDefaultAvailable inCLI equivalent
Int5000*-shrink-limit N

Number of attempts to shrink a failing sequence of transactions.

contractAddr

TypeDefaultAvailable inCLI equivalent
Address"0x00a329c0648769a73af ac7f9381e08fb43dbea72"*--contract-addr ADDR

Address to deploy the contract to test.

coverage

TypeDefaultAvailable in
Booltrue*

Enable the use of coverage-guided fuzzing and corpus collection. We recommend keeping this enabled.

corpusDir

TypeDefaultAvailable inCLI equivalent
Stringnull*--corpus-dir PATH

Directory to save the corpus collected (requires coverage enabled).

deployer

TypeDefaultAvailable inCLI equivalent
Address"0x30000"*--deployer

Address of the deployer of the contract to test.

deployContracts

TypeDefaultAvailable in
[⁠[⁠Address, String⁠]⁠][]2.0.2+

Addresses and contract names to deploy using the available source code. The deployer address is the same as the contract to test. Echidna will error if the deployment fails.

deployBytecodes

TypeDefaultAvailable in
[⁠[⁠Address, String⁠]⁠][]2.0.2+

Addresses and bytecodes to deploy. The deployer address is the same as the contract to test. Echidna will error if the deployment fails.

sender

TypeDefaultAvailable inCLI equivalent
[Address]["0x10000", "0x20000", "0x30000"]*--sender

List of addresses to (randomly) use as msg.sender for the transactions sent during testing. These addresses are used as the sender for all transactions produced by Echidna, except for property evaluation in property mode (see psender below).

psender

TypeDefaultAvailable in
Address"0x10000"*

Address of msg.sender to use for property evaluation. This address is only used to evaluate properties (functions with the configured prefix) while executing Echidna in property mode.

prefix

TypeDefaultAvailable in
String"echidna_"*

Prefix of the function names used as properties in the contract to test.

propMaxGas

TypeDefaultAvailable in
Int12500000 (current max gas per block)*

Maximum amount of gas to consume when running function properties. If a property runs out of gas, it will be considered as a failure.

testMaxGas

TypeDefaultAvailable in
Int12500000 (current max gas per block)*

Maximum amount of gas to consume when running random transactions. A non-property transaction that runs out of gas (e.g. a transaction in assertion mode) will not be considered a failure.

maxGasprice

TypeDefaultAvailable in
Int0*

Maximum amount of gas price to randomly use in transactions. Do not change it unless you absolutely need it.

maxTimeDelay

TypeDefaultAvailable in
Int604800 (one week)*

Maximum amount of seconds of delay between transactions.

maxBlockDelay

TypeDefaultAvailable in
Int60480*

Maximum amount of block numbers between transactions.

solcArgs

TypeDefaultAvailable inCLI equivalent
String""*--solc-args ARGS

Additional arguments to use in solc for compiling the contract to test.

cryticArgs

TypeDefaultAvailable inCLI equivalent
[String][]*--crytic-args ARGS

Additional arguments to use in crytic-compile for compiling the contract to test.

quiet

TypeDefaultAvailable in
Boolfalse*

Hide solc stderr output and additional information during the testing.

format

TypeDefaultAvailable inCLI equivalent
Stringnull*--format FORMAT

Select a textual output format. By default, interactive TUI is run or text if a terminal is absent.

  • "text": simple textual interface.
  • "json": JSON output.
  • "none": no output.

balanceContract

TypeDefaultAvailable in
Int0*

Initial Ether balance of contractAddr. See our tutorial on working with ETH for more details.

balanceAddr

TypeDefaultAvailable in
Int0xffffffff*

Initial Ether balance of deployer and each of the sender accounts. See our tutorial on working with ETH for more details.

maxValue

TypeDefaultAvailable in
Int100000000000000000000 (100 ETH)*

Max amount of value in each randomly generated transaction. See our tutorial on working with ETH for more details.

testDestruction

TypeDefaultAvailable in
Boolfalse*

Add a special test that fails if a contract is self-destructed.

stopOnFail

TypeDefaultAvailable in
Boolfalse*

Stops the fuzzing campaign when the first test fails.

allContracts

TypeDefaultAvailable inCLI equivalent
Boolfalse2.1.0+ (previously multi-abi)--all-contracts

Makes Echidna fuzz the provided test contracts and any other deployed contract whose ABI is known at runtime.

filterBlacklist

TypeDefaultAvailable in
Booltrue*

Allows Echidna to avoid calling (when set to true) or only call (when set to false) a set of functions. The function allowlist or denylist should be provided in filterFunctions.

filterFunctions

TypeDefaultAvailable in
[String][]*

Configures the function allowlist or denylist from filterBlacklist. The list should contain strings in the format of "Contract.functionName(uint256,uint256)" following the signature convention.

allowFFI

TypeDefaultAvailable in
Boolfalse2.1.0+

Allows the use of the HEVM ffi cheatcode.

rpcUrl

TypeDefaultAvailable inCLI equivalentEnv. variable equivalent
Stringnull2.1.0+ (env), 2.2.0+ (config), 2.2.3+ (cli)--rpc-url URLECHIDNA_RPC_URL

URL to fetch contracts over RPC.

rpcBlock

TypeDefaultAvailable inCLI equivalentEnv. variable equivalent
Stringnull2.1.0+ (env), 2.2.0+ (config), 2.2.3+ (cli)--rpc-block NECHIDNA_RPC_BLOCK

Block number to use when fetching over RPC.

etherscanApiKey

TypeDefaultAvailable inEnv. variable equivalent
Stringnull2.1.0+ (env), 2.2.4+ (config)ETHERSCAN_API_KEY

Etherscan API key used to fetch contract code.

coverageFormats

TypeDefaultAvailable in
[String]["txt","html","lcov"]2.2.0+

List of file formats to save coverage reports in; default is all possible formats.

workers

TypeDefaultAvailable inCLI equivalent
Int12.2.0+--workers

Number of workers.

server

TypeDefaultAvailable inCLI equivalent
Intnull2.2.2+--server PORT

Run events server on the given port.

symExec

TypeDefaultAvailable in
Boolfalse2.2.4+

Whether to add an additional symbolic execution worker.

symExecConcolic

TypeDefaultAvailable in
Booltrue2.2.4+

Whether symbolic execution will be concolic (vs full symbolic execution). Only relevant if symExec is true.

symExecNSolvers

TypeDefaultAvailable in
Int12.2.4+

Number of SMT solvers used in symbolic execution. While there is a single symExec worker, N threads may be used to solve SMT queries. Only relevant if symExec is true.

symExecTimeout

TypeDefaultAvailable in
Int302.2.4+

Timeout for symbolic execution SMT solver. Only relevant if symExec is true. When the SMT solver used is Z3, this timeout applies per query, and is not global.

symExecMaxIters

TypeDefaultAvailable in
Int102.2.4+

Number of times we may revisit a particular branching point. Only relevant if symExec is true and symExecConcolic is false.

symExecAskSMTIters

TypeDefaultAvailable in
Int12.2.4+

Number of times we may revisit a particular branching point before we consult the smt solver to check reachability. Only relevant if symExec is true and symExecConcolic is false.

Experimental options

There are some options in Echidna that are meant for advanced debugging and experimenting. Those are listed below.

estimateGas

TypeDefaultAvailable in
Boolfalse*

Enables the collection of worst-case gas usage. The information is stored as part of the corpus on the gas_info field. This functionality is experimental.

dictfreq

TypeDefaultAvailable in
Float0.40*

This parameter controls how often Echidna uses its internal dictionary versus a random value when generating a transaction. We do not recommend changing the default value.

mutConsts

TypeDefaultAvailable in
[Int][1, 1, 1, 1]*

Echidna uses weighted probabilities to pick a mutator for a transaction sequence. This parameter configures the weights for each kind of mutation. The value consists of four integers, [c1, c2, c3, c4]. Refer to the implementation code for their meaning and impact. We do not recommend changing the default value.

Deprecated options

There are some options in Echidna that have been deprecated and will be removed soon. Those are listed below.

initialize

TypeDefaultAvailable in
Stringnull*

This allows initializing the chain state in Echidna with a series of transactions, typically captured with Etheno. Nowadays, with the introduction of on-chain fuzzing in Echidna, it has become deprecated.