Create Chimera App

We've synthesized everything you need for invariant testing (tutorials, best practices, videos, and an invariant testing bootcamp) using this template in the Recon Book.

Table of Contents

• Prerequisites
• How it Works
• Example Projects
• Usage
  • Build
  • Property Testing
  • Foundry Testing
• Expanding Target Functions
• Uploading Fuzz Job To Recon
• Credits
• Help

This Foundry template allows you to bootstrap an invariant fuzz testing suite using a scaffolding provided by the Recon Handler Builder tool. You can generate a similar scaffolding for any existing project using the Handler Builder or the Recon Extension.

It extends the default Foundry template used when running forge init to include example property tests supported by Echidna and Medusa.

Prerequisites

To use this template you'll need to have Foundry and at least one fuzzer (Echidna or Medusa) or a symbolic testing tool (Halmos) installed:

• Foundry
• Echidna
• Medusa
• Halmos

How it Works

For a full explainer of the different contracts that make up the Chimera Framework and are used in this template, checkout this section of the Recon Book.

For an in-depth explanation of the configuration options that come with this template and how to use it, see this section of the Recon Book.

Example Projects

To see an end-to-end example of how to use this template to define properties on a contract and debug them when they break, checkout the example project in the Recon Book.

Usage

To initialize a new Foundry repo using this template run the following command in the terminal.

forge init --template https://github.com/Recon-Fuzz/create-chimera-app

Build

This template is configured to use Foundry as its build system for Echidna and Medusa so after making any changes the project must successfully compile using the following command before running either fuzzer:

forge build

Property Testing

This template comes with property tests defined for the Counter contract in the Properties contract and in the function handlers in the TargetFunctions contract.

See this section of the Recon Book to learn more about implementing properties.

Echidna Property Testing

To locally test properties using Echidna, run the following command in your terminal:

echidna . --contract CryticTester --config echidna.yaml

Medusa Property Testing

To locally test properties using Medusa, run the following command in your terminal:

medusa fuzz

Foundry Testing

Broken properties found when running Echidna and/or Medusa can be turned into unit tests for easier debugging with Recon (for Echidna/for Medusa) and added to the CryticToFoundry contract (you can also do this directly in your editor using the Recon VS Code extension).

forge test --match-contract CryticToFoundry -vv

You can then use optimization mode to increase the severity of findings as we've described here.

Foundry Invariant Testing

To run invariant tests directly in Foundry using the built-in invariant testing framework, use the invariants profile:

FOUNDRY_PROFILE=invariants forge test --match-contract CryticToFoundry -vv

The number of test runs can be modified by the runs parameter in the [profile.invariants.invariant] section of foundry.toml.

Halmos Invariant Testing

This template works out of the box for invariant testing with Halmos.

To run Halmos for invariant testing, run the halmos command in your terminal while in the root of this repository .

Expanding Target Functions

After you've added new contracts in the src directory, they can then be deployed in the Setup contract.

The ABIs of these contracts can be taken from the out directory and added to Recon's Handler Builder. The target functions that the builder generates can then be added to the existing TargetFunctions contract.

Uploading Fuzzing Job To Recon

You can offload your fuzzing job to Recon to run long duration jobs and share test results with collaborators using the jobs page.

Credits

This template implements the EnumerableSet contract from OpenZeppelin and the ERC20 contract from Solmate to reduce the number of dependencies and make it simpler to get started.

Limitations

• Echidna contractAddr must be hardcoded due to how Echidna works
• Medusa uses deployerAddress to deploy libraries, burning nonces, as a sidestep we use a random deployerAddress and set CryticTester address in predeployedContracts

Help

If you need help using the template or have question about any of our tools, join the Recon Discord.