Skip to content

Commit f1b0a8f

Browse files
authored
Update README.md (#712)
1 parent aa99405 commit f1b0a8f

File tree

1 file changed

+44
-47
lines changed

1 file changed

+44
-47
lines changed

README.md

+44-47
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,6 @@ More seriously, Echidna is a Haskell program designed for fuzzing/property-based
2020

2121
.. and [a beautiful high-resolution handcrafted logo](https://raw.githubusercontent.com/crytic/echidna/master/echidna.png).
2222

23-
## Screenshot
24-
2523
<a href="https://trailofbits.files.wordpress.com/2020/03/image5.png"><img src="https://trailofbits.files.wordpress.com/2020/03/image5.png" width="650"/></a>
2624

2725
## Usage
@@ -77,10 +75,6 @@ Our tool signals each execution trace in the corpus with the following "line mar
7775
- `o` if an execution ended with an out-of-gas error
7876
- `e` if an execution ended with any other error (zero division, assertion failure, etc)
7977

80-
### Crash course on Echidna
81-
82-
Our [Building Secure Smart Contracts](https://github.com/crytic/building-secure-contracts) repository contains a crash course on Echidna, including examples, lessons and exercises. You should [start here](https://github.com/crytic/building-secure-contracts/tree/master/program-analysis/echidna#echidna-tutorial).
83-
8478
### Support for smart contract build systems
8579

8680
Echidna can test contracts compiled with different smart contract build systems, including [Truffle](https://truffleframework.com/), [Embark](https://framework.embarklabs.io/) and even [Vyper](https://vyper.readthedocs.io), using [crytic-compile](https://github.com/crytic/crytic-compile). For instance,
@@ -118,7 +112,6 @@ Echidna supports three different output drivers. There is the default `text`
118112
driver, a `json` driver, and a `none` driver, which should suppress all
119113
`stdout` output. The JSON driver reports the overall campaign as follows.
120114

121-
122115
```json
123116
Campaign = {
124117
"success" : bool,
@@ -159,7 +152,26 @@ GitHub Actions workflow. Please refer to the
159152
[crytic/echidna-action](https://github.com/crytic/echidna-action) repository for
160153
usage instructions and examples.
161154

162-
## Limitations and known issues
155+
### Debugging Performance Problems
156+
157+
The best way to deal with an Echidna performance issue is to run `echidna-test` with profiling on.
158+
This creates a text file, `echidna-test.prof`, which shows which functions take up the most CPU and memory usage.
159+
160+
To build a version of `echidna-test` that supports profiling, either Stack or Nix should be used.
161+
With Stack, adding the flag `--profile` will make the build support profiling.
162+
With Nix, running `nix-build --arg profiling true` will make the build support profiling.
163+
164+
To run with profiling on, add the flags `+RTS -p` to your original `echidna-test` command.
165+
166+
Performance issues in the past have been because of functions getting called repeatedly when they could be memoized,
167+
and memory leaks related to Haskell's lazy evaluation;
168+
checking for these would be a good place to start.
169+
170+
### Crash course on Echidna
171+
172+
Our [Building Secure Smart Contracts](https://github.com/crytic/building-secure-contracts/tree/master/program-analysis/echidna#echidna-tutorial) repository contains a crash course on Echidna, including examples, lessons and exercises.
173+
174+
### Limitations and known issues
163175

164176
EVM emulation and testing is hard. Echidna has a number of limitations in the latest release. Some of these are inherited from [hevm](https://github.com/dapphub/dapptools/tree/master/src/hevm) while some are results from design/performance decisions or simply bugs in our code. We list them here including their corresponding issue and the status ("wont fix", "in review", "fixed"). Issues that are "fixed" are expected to be included in the next Echidna release.
165177

@@ -225,21 +237,9 @@ Running the test suite:
225237
nix-shell --run 'cabal test'
226238
```
227239

228-
## Getting help
240+
## Public use of Echidna
229241

230-
Feel free to stop by our #ethereum slack channel in [Empire Hacking](https://empireslacking.herokuapp.com/) for help using or extending Echidna.
231-
232-
* Get started by reviewing these simple [Echidna invariants](examples/solidity/basic/flags.sol)
233-
234-
* Review the [Solidity examples](examples/solidity) directory for more extensive Echidna use cases
235-
236-
* Considering [emailing](mailto:[email protected]) the Echidna development team directly for more detailed questions
237-
238-
## License
239-
240-
Echidna is licensed and distributed under the [AGPLv3 license](https://github.com/crytic/echidna/blob/master/LICENSE).
241-
242-
## Projects using Echidna
242+
### Property testing suites
243243

244244
This is a partial list of smart contracts projects that use Echidna for testing:
245245

@@ -255,11 +255,9 @@ This is a partial list of smart contracts projects that use Echidna for testing:
255255
* [Tokencard](https://github.com/tokencard/contracts/tree/master/tools/echidna)
256256
* [Minimalist USD Stablecoin](https://github.com/usmfum/USM/pull/41)
257257

258-
## Trophies
259-
260-
### Security Issues
258+
### Trophies
261259

262-
The following lists security vulnerabilities that were found by Echidna. If you found a security vulnerability using our tool, please submit a PR with the relevant information.
260+
The following security vulnerabilities were found by Echidna. If you found a security vulnerability using our tool, please submit a PR with the relevant information.
263261

264262
| Project | Vulnerability | Date |
265263
|--|--|--|
@@ -270,17 +268,17 @@ The following lists security vulnerabilities that were found by Echidna. If you
270268
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | An attacker cannot generate free pool tokens with joinPool | Jan 2020
271269
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | Calling joinPool-exitPool does not lead to free pool tokens | Jan 2020
272270
[Balancer Core](https://github.com/trailofbits/publications/blob/master/reviews/BalancerCore.pdf) | Calling exitswapExternAmountOut does not lead to free assets | Jan 2020
273-
[Yield Protocol](https://github.com/trailofbits/publications/blob/master/reviews/YieldProtocol.pdf) | Arithmetic computation for buying and selling tokens is imprecise | Aug 2020
274-
[Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf) | Users are allowed to transfer more tokens that they have | Nov 2020
275-
[Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf) | User balances can be larger than total supply | Nov 2020
276271
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | [Closing troves require to hold the full amount of LUSD minted](https://github.com/liquity/dev/blob/echidna_ToB_final/packages/contracts/contracts/TestContracts/E2E.sol#L242-L298) | Dec 2020
277272
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | [Troves can be improperly removed](https://github.com/liquity/dev/blob/echidna_ToB_final/packages/contracts/contracts/TestContracts/E2E.sol#L242-L298) | Dec 2020
278273
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | Initial redeem can revert unexpectedly | Dec 2020
279274
[Liquity Dollar](https://github.com/trailofbits/publications/blob/master/reviews/Liquity.pdf) | Redeem without redemptions might still return success | Dec 2020
275+
[Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf) | Users are allowed to transfer more tokens that they have | Nov 2020
276+
[Origin Dollar](https://github.com/trailofbits/publications/blob/master/reviews/OriginDollar.pdf) | User balances can be larger than total supply | Nov 2020
277+
[Yield Protocol](https://github.com/trailofbits/publications/blob/master/reviews/YieldProtocol.pdf) | Arithmetic computation for buying and selling tokens is imprecise | Aug 2020
280278

281-
### Research Examples
279+
### Research
282280

283-
We can also use Echidna to reproduce a number of research examples from smart contract fuzzing papers to show how quickly it can find the solution:
281+
We can also use Echidna to reproduce research examples from smart contract fuzzing papers to show how quickly it can find the solution. All these can be solved, from a few seconds to one or two minutes on a laptop computer.
284282

285283
| Source | Code
286284
|--|--
@@ -289,27 +287,26 @@ We can also use Echidna to reproduce a number of research examples from smart co
289287
[Learning to Fuzz from Symbolic Execution with Application to Smart Contracts](https://files.sri.inf.ethz.ch/website/papers/ccs19-ilf.pdf) | [Crowdsale](https://github.com/crytic/echidna/blob/master/examples/solidity/research/ilf_crowdsale.sol)
290288
[Harvey: A Greybox Fuzzer for Smart Contracts](https://arxiv.org/abs/1905.06944) | [Foo](https://github.com/crytic/echidna/blob/master/examples/solidity/research/harvey_foo.sol), [Baz](https://github.com/crytic/echidna/blob/master/examples/solidity/research/harvey_baz.sol)
291289

292-
All these can be solved, from a few seconds to one or two minutes on a laptop computer.
290+
### Academic Publications
293291

294-
## Publications
292+
| Paper Title | Venue | Publication Date |
293+
| --- | --- | --- |
294+
| [echidna-parade: Diverse multicore smart contract fuzzing](https://agroce.github.io/issta21.pdf) | [ISSTA 2021](https://conf.researchr.org/home/issta-2021) | July 2021 |
295+
| [Echidna: Effective, usable, and fast fuzzing for smart contracts](papers/echidna_issta2020.pdf) | [ISSTA 2020](https://conf.researchr.org/home/issta-2020) | July 2020 |
296+
| [Echidna: A Practical Smart Contract Fuzzer](papers/echidna_fc_poster.pdf) | [FC 2020](https://fc20.ifca.ai/program.html) | Feb 2020 |
295297

296-
### Trail of Bits
297-
- [Echidna: effective, usable, and fast fuzzing for smart contracts](https://github.com/trailofbits/publications/blob/master/papers/echidna_issta2020.pdf), Gustavo Grieco, Will Song, Artur Cygan, Josselin Feist, Alex Groce - ISSTA '20
298-
- [echidna-parade: A Tool for Diverse Multicore Smart Contract Fuzzing](https://agroce.github.io/issta21.pdf), Alex Groce, Gustavo Grieco - ISSTA '21
298+
If you are using Echidna for academic work, consider applying to the [Crytic $10k Research Prize](https://blog.trailofbits.com/2019/11/13/announcing-the-crytic-10k-research-prize/).
299299

300-
If you are using Echidna on an academic work, consider applying to the [Crytic $10k Research Prize](https://blog.trailofbits.com/2019/11/13/announcing-the-crytic-10k-research-prize/).
300+
## Getting help
301301

302-
## Debugging Performance Problems
302+
Feel free to stop by our #ethereum slack channel in [Empire Hacking](https://empireslacking.herokuapp.com/) for help using or extending Echidna.
303303

304-
The best way to deal with an Echidna performance issue is to run `echidna-test` with profiling on.
305-
This creates a text file, `echidna-test.prof`, which shows which functions take up the most CPU and memory usage.
304+
* Get started by reviewing these simple [Echidna invariants](examples/solidity/basic/flags.sol)
306305

307-
To build a version of `echidna-test` that supports profiling, either Stack or Nix should be used.
308-
With Stack, adding the flag `--profile` will make the build support profiling.
309-
With Nix, running `nix-build --arg profiling true` will make the build support profiling.
306+
* Review the [Solidity examples](examples/solidity) directory for more extensive Echidna use cases
310307

311-
To run with profiling on, add the flags `+RTS -p` to your original `echidna-test` command.
308+
* Considering [emailing](mailto:[email protected]) the Echidna development team directly for more detailed questions
312309

313-
Performance issues in the past have been because of functions getting called repeatedly when they could be memoized,
314-
and memory leaks related to Haskell's lazy evaluation;
315-
checking for these would be a good place to start.
310+
## License
311+
312+
Echidna is licensed and distributed under the [AGPLv3 license](https://github.com/crytic/echidna/blob/master/LICENSE).

0 commit comments

Comments
 (0)