Merge pull request #180 from crytic/dev-optimization-mode

Add optimization mode tutorial

Author: montyly

program-analysis/echidna/README.md

@@ -19,6 +19,7 @@ Watch our [Fuzzing workshop](https://www.youtube.com/watch?v=QofNQxW_K08&list=PL
   - [Frequently Asked Questions](./frequently_asked_questions.md): Answers to common questions about Echidna
 - Advanced
   - [How to collect a corpus](./collecting-a-corpus.md): How to use Echidna to collect a corpus of transactions
+  - [How to use optimization mode](./optimization_mode.md): How to use Echidna to optimize a function
   - [How to detect high gas consumption](./finding-transactions-with-high-gas-consumption.md): How to find functions with high gas consumption.
   - [How to perform smart contract fuzzing at a large scale](./smart-contract-fuzzing-at-scale.md): How to use Echidna to run a long fuzzing campaign for complex smart contracts.
   - [How to test a library](https://blog.trailofbits.com/2020/08/17/using-echidna-to-test-a-smart-contract-library/): How Echidna was used to test the library in Set Protocol (blogpost)

program-analysis/echidna/example/opt.sol

@@ -0,0 +1,34 @@
+pragma solidity ^0.8.0;
+
+contract TestDutchAuctionOptimization {
+    int256 maxPriceDifference;
+
+    function setMaxPriceDifference(
+        uint256 startPrice,
+        uint256 endPrice,
+        uint256 startTime,
+        uint256 endTime
+    ) public {
+        if (endTime < (startTime + 900)) {
+            revert();
+        }
+        if (startPrice <= endPrice) {
+            revert();
+        }
+        uint256 numerator = (startPrice - endPrice) *
+            (block.timestamp - startTime);
+        uint256 denominator = endTime - startTime;
+        uint256 stepDecrease = numerator / denominator;
+        uint256 currentAuctionPrice = startPrice - stepDecrease;
+        if (currentAuctionPrice < endPrice) {
+            maxPriceDifference = int256(endPrice - currentAuctionPrice);
+        }
+        if (currentAuctionPrice > startPrice) {
+            maxPriceDifference = int256(currentAuctionPrice - startPrice);
+        }
+    }
+
+    function echidna_opt_price_difference() public view returns (int256) {
+        return maxPriceDifference;
+    }
+}

program-analysis/echidna/optimization_mode.md

@@ -0,0 +1,95 @@
+# Using optimization mode to find local maximums
+
+**Table of contents:**
+
+- [Introduction](#introduction)
+- [Optimizing with Echidna](#optimizing-with-echidna)
+
+## Introduction
+
+We will see how to perform function optimization using Echidna. This tutorial will require Echidna 2.0.5 or greater, 
+so make sure you have update it before starting.
+
+Optimization mode is a experimental feature that allows to define a special function which takes no arguments 
+and returns a `int256`. Echidna will try find a sequence of transactions to maximize the value returned:
+
+```solidity
+    function echidna_opt_function() public view returns (int256) {
+        // if it reverts, Echidna will assumed it returned type(int256).min
+        return ..;
+    }
+```
+
+## Optimizing with Echidna
+
+In this example, the target is the following smart contract (*[example/opt.sol](./example/opt.sol)*):
+
+```solidity
+contract TestDutchAuctionOptimization {
+    int256 maxPriceDifference;
+
+    function setMaxPriceDifference(
+        uint256 startPrice,
+        uint256 endPrice,
+        uint256 startTime,
+        uint256 endTime
+    ) public {
+        if (endTime < (startTime + 900)) {
+            revert();
+        }
+        if (startPrice <= endPrice) {
+            revert();
+        }
+        uint256 numerator = (startPrice - endPrice) *
+            (block.timestamp - startTime);
+        uint256 denominator = endTime - startTime;
+        uint256 stepDecrease = numerator / denominator;
+        uint256 currentAuctionPrice = startPrice - stepDecrease;
+        if (currentAuctionPrice < endPrice) {
+            maxPriceDifference = int256(endPrice - currentAuctionPrice);
+        }
+        if (currentAuctionPrice > startPrice) {
+            maxPriceDifference = int256(currentAuctionPrice - startPrice);
+        }
+    }
+
+    function echidna_opt_price_difference() public view returns (int256) {
+        return maxPriceDifference;
+    }
+}
+```
+
+This small example forces Echidna to maximize certain price difference given some preconditions. If the preconditions are not
+met, the function will revert, without changing the actual value.
+
+To run this example:
+
+```
+$ echidna-test opt.sol --test-mode optimization --test-limit 100000 --seq-len 1 --corpus-dir corpus --shrink-limit 50000
+...
+echidna_opt_price_difference: max value: 1076841
+
+  Call sequence, shrinking (42912/50000):
+    setMaxPriceDifference(1349752405,1155321,609,1524172858) Time delay: 603902 seconds Block delay: 21
+
+```
+
+The resulting max value is not unique, running in longer campaign will likely result in a larger value.
+
+Regarding the command line, the optimization mode is enabled using `--test-mode optimization`. additionally, we included the following tweaks: 
+
+1. Use only one transaction (we know that the function is stateless)
+2. Use a large shrink limit in order to obtain a better value during the minimization of the complexity of the input.
+
+Every time Echidna is executed using the corpus directory, the last input that produces the maximum value should be re-used from the `reproducers` directory:
+
+```
+$ echidna-test opt.sol --test-mode optimization --test-limit 100000 --seq-len 1 --corpus-dir corpus --shrink-limit 50000
+Loaded total of 1 transactions from corpus/reproducers/
+Loaded total of 9 transactions from corpus/coverage/
+Analyzing contract: /home/g/Code/echidna/opt.sol:TestDutchAuctionOptimization
+echidna_opt_price_difference: max value: 1146878
+
+  Call sequence:
+    setMaxPriceDifference(1538793592,1155321,609,1524172858) Time delay: 523701 seconds Block delay: 49387
+```