Migrate to mdbook

.github/workflows/deploy.yml

@@ -0,0 +1,38 @@
+name: Deploy GH Pages
+on:
+  push:
+    branches:
+      - docs
+
+jobs:
+  build:
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+
+    env:
+      CARGO_TERM_COLOR: always
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - run: cargo install --git https://github.com/montyly/mdBook.git mdbook || true
+      - run: cd docs && mdbook build
+      - uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./docs/book
+
+  deploy:
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -20,4 +20,7 @@
 *node_modules/
 
 # Medusa binary
-medusa
+medusa
+
+# Medusa docs
+docs/book

docs/book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["Trail of Bits"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Medusa"
+description = "This repository, brought to you by Trail of Bits, contains the source files for the Medusa documentation."
+
+[output.html]
+git-repository-url = "https://github.com/crytic/medusa"
+edit-url-template = "https://github.com/crytic/medusa/edit/master/docs/{path}"
+no-section-label = true
+default-theme = "light"

docs/src/README.md

@@ -0,0 +1,12 @@
+# Introduction
+
+`medusa` is a cross-platform go-ethereum-based smart contract fuzzer inspired by Echidna. It provides parallelized fuzz testing of smart contracts through CLI, or its Go API that allows custom user-extended testing methodology.
+
+## Table of Contents
+
+- [Project Configuration](./project-configuration.md): Learn how to set up `medusa` for your project as well as the vast number of configuration options that can be set up based on your project needs.
+- [Command Line Interface](./command-line-interface.md): Learn how to use `medusa`'s CLI.
+- [API Overview (WIP)](./api-overview.md): Learn about medusa's Go API that can be used to perform advanced testing methodologies and extend `medusa`'s capabilities.
+- [Testing with `medusa`](./writing-tests.md): Learn how to perform testing using property mode, assertion mode, and optimization mode. We will discuss what the benefits of each mode are and how to set `medusa` up for each one.
+- [Cheatcodes](./cheatcodes.md): Learn about the various cheatcodes that are supported by `medusa`. Using these cheatcodes will significantly improve the efficiency and code quality of your fuzz tests.
+- [FAQ](./faq.md)

docs/src/SUMMARY.md

@@ -0,0 +1,10 @@
+# Summary
+
+- [Introduction](./README.md)
+- [Project Configuration](./project-configuration.md)
+- [Example Project Configuration File](./example-config-file.md)
+- [Command Line Interface](./command-line-interface.md)
+- [API Overview (WIP)](./api-overview.md)
+- [Testing with `medusa`](./writing-tests.md)
+- [Cheatcodes](./cheatcodes.md)
+- [FAQ](./faq.md)

docs/src/cheatcodes.md

@@ -0,0 +1,3 @@
+# Cheatcodes
+
+TODO

docs/src/command-line-interface.md

@@ -0,0 +1,75 @@
+# Command Line Interface
+
+`medusa` can run parallelized fuzz testing of smart contracts through its Command Line Interface (CLI). The CLI supports three main commands and each command has a variety of flags:
+
+1. `medusa init [platform]` will initialize `medusa`'s project configuration file
+2. `medusa fuzz` will begin the fuzzing campaign.
+3. `medusa completion <shell>` will provide an autocompletion script for a given shell
+
+Let's look at each command.
+
+> **Note**: We highly recommend reading more about `medusa`'s [project configuration](./Project-Configuration.md) parameters before diving into `medusa`'s CLI capabilities.
+
+## Initializing a project configuration
+
+To create a `medusa` project configuration, invoke `medusa init [platform]` to create a [configuration file](./Example-Project-Configuration-File.md) for the provided platform within your current working directory. Invoking this command without a `platform` argument will result in `medusa` using `crytic-compile` as the default compilation platform.
+
+> Note that the output of `medusa init`, which is equivalent to `medusa init crytic-compile`, is considered the **default configuration** of `medusa`
+
+While running `medusa init`, you have access to two flags:
+
+1. `medusa init [platform] --out myConfig.json`: The `--out` value will determine the output path where your project configuration file will be outputted. Without `--out`, the default output path is `medusa.json` in the current working directory.
+2. `medusa init [platform] --target myContract.sol`: The `--target` value will determine the compilation target.
+
+## Running a fuzzing campaign
+
+After you have a project configuration setup, you can now run a fuzzing campaign.
+
+To run a fuzzing campaign, invoke `medusa fuzz`. The `fuzz` command supports a variety of flags:
+
+- `medusa fuzz --config myConfig.json`: Will use the configuration in `myConfig.json` as the project configuration. If `--config` is not set, `medusa` will look for a `medusa.json` file in the current working directory
+- `medusa fuzz --target myContract.sol`: Will set the compilation target to `myContract.sol`
+- `medusa fuzz --workers 20`: Will set the number of `workers` to 20 threads
+- `medusa fuzz --timeout 1000`: Will set the `timeout` to 1000 seconds
+- `medusa fuzz --test-limit 50000`: Will set the `testLimit` to 50000 function calls
+- `medusa fuzz --seq-len 50`: Will set the `callSequenceLength` to 50 transactions
+- `medusa fuzz --deployment-order "FirstContract,SecondContract"`: Will set the deployment order to `[FirstContract, SecondContract]`
+- `medusa fuzz --corpus-dir myCorpus`: Will set the corpus directory _path_ to `myCorpus`
+- `medusa fuzz --senders "0x10000,0x20000,0x30000"`: Will set the `senderAdddresses` to `[0x10000, 0x20000, 0x30000]`
+- `medusa fuzz --deployer "0x10000"`: Will set the `deployerAddress` to `0x10000`
+- `medusa fuzz --assertion-mode`: Will set `assertionTesting.enabled` to `true`
+- `medusa fuzz --optimization-mode`: Will set `optimizationTesting.enabled` to `true`
+- `medusa fuzz --trace-all`: Will set `traceAll` to `true`
+
+Note that the `fuzz` command will use both the project configuration file in addition to any flags to determine the _final_ project configuration. Thus, it uses both of them in tandem.
+
+This results in four different ways to run `medusa`:
+
+1. `medusa fuzz`: Run `medusa` using the configuration in `medusa.json` with no CLI updates.
+   > 🚩 If `medusa.json` is not found, we will use the **default configuration**.
+2. `medusa fuzz --workers 20 --test-limit 50000`: Run `medusa` using the configuration in `medusa.json` and override the `workers` and `testLimit` parameters.
+   > 🚩 If `medusa.json` is not found, we will use the **default configuration** and override the `workers` and `testLimit` parameters.
+3. `medusa fuzz --config myConfig.json`: Run `medusa` using the configuration in `myConfig.json` with no CLI updates.
+   > 🚩 If `myConfig.json` is not found, `medusa` will throw an error
+4. `medusa fuzz --config myConfig.json --workers 20 --test-limit 50000`: Run `medusa` using the configuration in `myConfig.json` and override the `workers` and `testLimit` parameters.
+   > 🚩 If `myConfig.json` is not found, `medusa` will throw an error
+
+## Autocompletion
+
+`medusa` also provides the ability to generate autocompletion scripts for a given shell. Once the autocompletion script is ran for a given shell, `medusa`'s commands and flags can now be tab-autocompleted. The following shells are supported:
+
+1. bash
+2. zsh
+3. Powershell
+
+To understand how to run the autocompletion script for a given shell, run the following command
+
+```bash
+medusa completion --help
+```
+
+Once you know how to run the autocompletion script, retrieve the script for that given shell using the following command.
+
+```bash
+medusa completion <shell>
+```

docs/src/example-config-file.md

@@ -0,0 +1,46 @@
+# Example Project Configuration File
+
+```json
+{
+  "fuzzing": {
+    "workers": 10,
+    "workerResetLimit": 50,
+    "timeout": 0,
+    "testLimit": 0,
+    "callSequenceLength": 100,
+    "corpusDirectory": "",
+    "coverageEnabled": true,
+    "deploymentOrder": [],
+    "deployerAddress": "0x1111111111111111111111111111111111111111",
+    "senderAddresses": [
+      "0x1111111111111111111111111111111111111111",
+      "0x2222222222222222222222222222222222222222",
+      "0x3333333333333333333333333333333333333333"
+    ],
+    "blockNumberDelayMax": 60480,
+    "blockTimestampDelayMax": 604800,
+    "blockGasLimit": 125000000,
+    "transactionGasLimit": 12500000,
+    "testing": {
+      "stopOnFailedTest": true,
+      "assertionTesting": {
+        "enabled": false,
+        "testViewMethods": false
+      },
+      "propertyTesting": {
+        "enabled": true,
+        "testPrefixes": ["fuzz_"]
+      }
+    }
+  },
+  "compilation": {
+    "platform": "crytic-compile",
+    "platformConfig": {
+      "target": ".",
+      "solcVersion": "",
+      "exportDirectory": "",
+      "args": []
+    }
+  }
+}
+```

docs/src/faq.md

@@ -0,0 +1,16 @@
+# Frequently Asked Questions
+
+**Why create a new fuzzer if Echidna is already a great fuzzer?**
+
+With medusa, we are exploring a different EVM implementation and language for our smart contract fuzzer. While Echidna is already doing an amazing job, medusa offers the following advantages:
+
+- It is written in Go, easing the maintenance and allowing the creation of a native API for future integration into other projects.
+- It uses geth as a base, ensuring the EVM equivalence.
+
+**Should I switch to medusa right away?**
+
+We do not recommend switching to medusa until it is extensively tested. However we encourage you to try it, and [let us know your experience](https://github.com/trailofbits/medusa/issues). In that sense, Echidna is our robust and well tested fuzzer, while medusa is our new exploratory fuzzer. [Follow us](https://twitter.com/trailofbits/) to hear updates about medusa as it grows in maturity.
+
+**Will all the previous available documentation from [secure-contracts.com](https://secure-contracts.com/) will apply to medusa?**
+
+In general, yes. All the information on testing approaches and techniques will apply for medusa. There are, however, different configuration options names and a few missing or different features in medusa from Echidna that we will be updating over time.