Merge pull request #263 from crytic/dev-library-support-echidna

Working with libraries in Echidna

Author: montyly

SUMMARY.md

@@ -80,6 +80,7 @@
       - [How to test bytecode-only contracts](./program-analysis/echidna/advanced/testing-bytecode.md)
       - [How to use hevm cheats to test permit](./program-analysis/echidna/advanced/hevm-cheats-to-test-permit.md)
       - [How to seed Echidna with unit tests](./program-analysis/echidna/advanced/end-to-end-testing.md)
+      - [How to fuzz contracts with external libraries](./program-analysis/echidna/advanced/working-with-libraries.md)
       - [Understanding and using `multi-abi`](./program-analysis/echidna/advanced/using-multi-abi.md)
     - [Fuzzing tips](./program-analysis/echidna/fuzzing_tips.md)
     - [Frequently Asked Questions](./program-analysis/echidna/frequently_asked_questions.md)

program-analysis/echidna/advanced/README.md

@@ -8,4 +8,5 @@
 - [How to test bytecode-only contracts](./testing-bytecode.md): How to fuzz a contract without bytecode or to perform differential fuzzing between Solidity and Vyper
 - [How to use hevm cheats to test permit](./hevm-cheats-to-test-permit.md): How to test code that depends on ecrecover signatures using hevm cheat codes
 - [How to seed Echidna with unit tests](./end-to-end-testing.md): How to use existing unit tests to seed Echidna
+- [How to fuzz contracts with external libraries](./working-with-libraries.md): How to fuzz a contract that has external libraries
 - [Understanding and using `multi-abi`](./using-multi-abi.md): What is `multi-abi` testing, and how can it be used

program-analysis/echidna/advanced/working-with-libraries.md

@@ -0,0 +1,78 @@
+# Working with external libraries
+
+**Table of contents:**
+
+- [Introduction](#introduction)
+- [Example code](#example-code)
+- [Deploying libraries](#deploying-libraries)
+- [Linking libraries](#linking-libraries)
+- [Summary](#summary)
+
+## Introduction
+
+Solidity support two types of libraries ([see the documentation](https://docs.soliditylang.org/en/v0.8.19/contracts.html#libraries)):
+
+- If all the functions are internal, the library is compiled into bytecode and added into the contracts that use it.
+- If there are some external functions, the library should be deployed into some address. Finally, the bytecode calling the library should be linked.
+
+The following is only needed if your codebase uses libraries that need to be linked.
+
+## Example code
+
+For this tutorial, we will use [the metacoin example](https://github.com/truffle-box/metacoin-box). Let's start compiling it:
+
+```
+$ git clone https://github.com/truffle-box/metacoin-box
+$ cd metacoin-box
+$ npm i
+```
+
+## Deploying libraries
+
+Libraries are contracts that need to be deployed first. Fortunately, Echidna allows us to do that easily, using the `deployContracts` option. In the metacoin example, we can use:
+
+```yaml
+deployContracts: [["0x1f", "ConvertLib"]]
+```
+
+The address where the library should be deployed is arbitrary, but it should be the same as the one in the used during the linking process.
+
+## Linking libraries
+
+Before a contract can use a deployed library, its bytecode requires to be linked (e.g set the address that points to the deployed library contract). Normally, a compilation framework (e.g. truffle) will take care of this. However, in our case, we will use `crytic-compile`, since it is easier to handle all cases from different frameworks just adding one new argument to pass to `crytic-compile` from Echidna:
+
+```yaml
+cryticArgs: ["--compile-libraries=(ConvertLib,0x1f)"]
+```
+
+Going back to the example, if we have both config options in a single config file (`echidna.yaml`), we can run the metacoin contract
+in `exploration` mode:
+
+```
+$ echidna . --test-mode exploration --corpus-dir corpus --contract MetaCoin --config echidna.yaml
+```
+
+We can use the coverage report to verify that function using the library (`getBalanceInEth`) is not reverting:
+
+```
+ 28 | *   |     function getBalanceInEth(address addr) public view returns(uint){
+ 29 | *   |             return ConvertLib.convert(getBalance(addr),2);
+ 30 |     |     }
+```
+
+However, the code of the library itself will not have their coverage displayed correctly:
+
+```
+ 6 |     | library ConvertLib{
+ 7 |     |     function convert(uint amount, uint conversionRate) public pure returns (uint convertedAmount)
+ 8 |     |     {
+ 9 |     |             return amount * conversionRate;
+10 |     |     }
+11 |     | }
+```
+
+This is caused by the usage of `delegatecall` to execute contract code and [unfortunately we do not have a workaround for it right now](https://github.com/crytic/echidna/issues/1042).
+
+## Summary
+
+Working with libraries in Echidna is supported. It involves to deploy the library to a particular address using `deployContracts` and then asking `crytic-compile` to link the bytecode with the same address using `--compile-libraries` command line.