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

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

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

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

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

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

Number of attempts to shrink a failing sequence of transactions.

contractAddr

Address to deploy the contract to test.

coverage

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

corpusDir

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

deployer

Address of the deployer of the contract to test.

deployContracts

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

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

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

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

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

propMaxGas

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

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

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

maxTimeDelay

Maximum amount of seconds of delay between transactions.

maxBlockDelay

Maximum amount of block numbers between transactions.

solcArgs

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

cryticArgs

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

quiet

Hide solc stderr output and additional information during the testing.

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

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

balanceAddr

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

maxValue

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

testDestruction

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

stopOnFail

Stops the fuzzing campaign when the first test fails.

allContracts

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

filterBlacklist

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

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

Allows the use of the HEVM ffi cheatcode.

rpcUrl

URL to fetch contracts over RPC.

rpcBlock

Block number to use when fetching over RPC.

etherscanApiKey

Etherscan API key used to fetch contract code.

coverageFormats

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

workers

Number of workers.

server

Run events server on the given port.

symExec

Whether to add an additional symbolic execution worker.

symExecConcolic

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

symExecNSolvers

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

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

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

symExecAskSMTIters

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

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

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

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

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.