Reusable properties for Ethereum contracts

As sensible contract safety continually evolves, property-based fuzzing has turn into a go-to method for builders and safety engineers. This system depends on the creation of code properties – usually known as invariants – which describe what the code is meant to do. To assist the neighborhood outline properties, we’re releasing a set of 168 pre-built properties that can be utilized to information Echidna, our sensible contract fuzzing instrument, or immediately by way of unit assessments. Properties lined embrace compliance with the most typical ERC token interfaces, generically testable safety properties, and properties for testing mounted level math operations.

Since mastering these instruments takes time and follow, we will probably be holding two livestreams on our Twitch and YouTube channels that can present hands-on expertise with these invariants:

• March 7 – ERC20 Properties, Instance Utilization, and Echidna Cheat Codes (Guillermo Larregay)
• March 14 – ERC4626 properties, instance utilization, and tips about fuzzing successfully (Benjamin Samuels)

Why ought to I exploit this?

The repository and associated workshops will reveal how fuzzing can present a a lot larger degree of safety assurance than unit assessments alone. This assortment of properties is straightforward to combine with tasks that use well-known requirements or commonly-used libraries. This launch comprises assessments for the ABDKMath64x64 library, ERC-20 token standardand ERC-4626 tokenized vaults standard:

ERC20

• Properties for normal interface features
• Inferred sanity properties (ex: no person steadiness needs to be higher than token provide)
• Properties for extensions comparable to burnable, mintable, and pausable tokens.

ERC4626

• Properties that confirm rounding instructions are compliant with spec
• Reversion properties for features that mustn’t ever revert
• Differential testing properties (ex: deposit() should match performance predicted by previewDeposit())
• Performance properties (ex: redeem() deducts shares from the proper account)
• Non-spec safety properties (share inflation assault, token approval checks, and so forth.)

ABDKMath64x64

• Communicative, associative, distributive, and identification properties for related features
• Differential testing properties (ex: 2^(-x) == 1/2^(x))
• Reversion properties for features which ought to revert for sure ranges of enter
• Unfavourable reversion properties for features that ought to not revert for sure ranges of enter
• Interval properties (ex: min(x,y) <= avg(x,y) <= max(x,y))

The aim of those properties is to detect vulnerabilities or deviations from anticipated outcomes, guarantee adherence to requirements, and supply steerage to builders writing invariants. By following this workshop, builders will have the ability to establish complicated safety points that can not be detected with typical unit and parameterized assessments. Moreover, utilizing this repository will allow builders to give attention to deeper systemic points as a substitute of losing time on low-hanging fruit.

As a bonus, whereas creating and testing these properties, we discovered a bug within the ABDKMath64x64 library: for a particular vary of inputs to the divuu operate, an assertion might be triggered within the library. Extra details about the bug, from one of many library’s authors, will be discovered right here.

Do It Your self!

Should you don’t wish to look ahead to the livestream, you will get began proper now. Right here’s how one can add the properties to your individual repo:

• Set up Echidna.
• Import the properties into to your venture:
  • In case of utilizing Hardhat, use: npm set up https://github.com/crytic/properties.git or yarn add https://github.com/crytic/properties.git
    In case of utilizing Foundry, use: forge set up crytic/properties
• Create a take a look at contract in accordance to the documentation.

Let’s say you wish to create a brand new ERC20 contract known as YetAnotherCashEquivalentTokenand test that it’s compliant with the usual. Following the earlier steps, you create the next take a look at contract for performing an exterior take a look at:

pragma solidity ^0.8.0;
import "./path/to/YetAnotherCashEquivalentToken.sol";
import {ICryticTokenMock} from "@crytic/properties/contracts/ERC20/external/util/ITokenMock.sol";
import {CryticERC20ExternalBasicProperties} from "@crytic/properties/contracts/ERC20/external/properties/ERC20ExternalBasicProperties.sol";
import {PropertiesConstants} from "@crytic/properties/contracts/util/PropertiesConstants.sol";


contract CryticERC20ExternalHarness is CryticERC20ExternalBasicProperties {   
    constructor() {
        // Deploy ERC20
        token = ICryticTokenMock(handle(new CryticTokenMock()));
    }
}

contract CryticTokenMock is YetAnotherCashEquivalentToken, PropertiesConstants {

    bool public isMintableOrBurnable;
    uint256 public initialSupply;
    constructor () {
        _mint(USER1, INITIAL_BALANCE);
        _mint(USER2, INITIAL_BALANCE);
        _mint(USER3, INITIAL_BALANCE);
        _mint(msg.sender, INITIAL_BALANCE);

        initialSupply = totalSupply();
        isMintableOrBurnable = false;
    }
}

Then, a configuration file is required to set the fuzzing parameters to run in Echidna:

corpusDir: "tests/crytic/erc20/echidna-corpus-internal"
testMode: assertion
testLimit: 100000
deployer: "0x10000"
sender: ["0x10000", "0x20000", "0x30000"]
multi-abi: true

Lastly, run Echidna on the take a look at contract:

echidna-test . --contract CryticERC20ExternalHarness --config assessments/echidna-external.yaml

Moreover, this effort is fluid. Some concepts for future work embrace:

• Take a look at extra of the widely-used mathematical libraries with our properties, comparable to PRBMath (properties/issues/2).
• Add assessments for extra ERC requirements (properties/issues/5).
• Create a corpus of assessments for different generally used features or contracts that aren’t requirements, comparable to AMMs or liquidity swimming pools (properties/issues/4).

Associated