Add simple json report generation

.github/workflows/ci.yml

@@ -5,6 +5,8 @@ on:
   push:
     branches:
       - master
+    tags:
+      - "v*"
   pull_request:
     branches:
       - master
@@ -22,13 +24,16 @@ jobs:
     needs: [lint, test]
     strategy:
       matrix:
-        environment: [ubuntu-latest, macos-latest, windows-latest]
+        environment: [ubuntu-latest, macos-12, macos-14, windows-latest]
+    permissions:
+      contents: read
+      id-token: write
 
     runs-on: ${{ matrix.environment }}
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Speed up Go (Windows)
         if: runner.os == 'Windows'
@@ -44,41 +49,85 @@ jobs:
           printf 'TEMP=%s\\tmpdir\n' "$DIR" | tee -a "$GITHUB_ENV"
           go env
 
-      - uses: actions/setup-go@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: "^1.18.1"
+          # disable caching during release (tag) builds
+          cache: ${{ !startsWith(github.ref, 'refs/tags/') }}
 
       - name: Build (Linux and macOS)
         if: runner.os == 'Linux' || runner.os == 'macOS'
         run: go build -o medusa -v .
 
       - name: Compress (Linux and macOS)
         if: runner.os == 'Linux' || runner.os == 'macOS'
-        run: tar -czvf medusa.tar.gz medusa
+        run: tar -czvf medusa-${{ runner.os }}-${{ runner.arch }}.tar.gz medusa
 
       - name: Build (Windows)
         if: runner.os == 'Windows'
         run: go build -o medusa.exe -v .
 
       - name: Compress (Windows)
         if: runner.os == 'Windows'
-        run: tar -czvf medusa.tar.gz medusa.exe
+        run: tar -czvf medusa-${{ runner.os }}-${{ runner.arch }}.tar.gz medusa.exe
 
-      - name: Upload artifact on merge to master
-        if: github.ref == 'refs/heads/master'
-        uses: actions/upload-artifact@v3
+      - name: Rename for release
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        run: |
+          [ ! -f medusa-Linux-X64.tar.gz ] || mv medusa-Linux-X64.tar.gz medusa-linux-x64.tar.gz
+          [ ! -f medusa-macOS-X64.tar.gz ] || mv medusa-macOS-X64.tar.gz medusa-mac-x64.tar.gz
+          [ ! -f medusa-macOS-ARM64.tar.gz ] || mv medusa-macOS-ARM64.tar.gz medusa-mac-arm64.tar.gz
+          [ ! -f medusa-Windows-X64.tar.gz ] || mv medusa-Windows-X64.tar.gz medusa-win-x64.tar.gz
+
+      - name: Sign artifact
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+        uses: sigstore/[email protected]
+        with:
+          inputs: ./medusa-*.tar.gz
+
+      - name: Upload artifact
+        if: github.ref == 'refs/heads/master' || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/'))
+        uses: actions/upload-artifact@v4
         with:
-          name: medusa-${{ runner.os }}
-          path: medusa.tar.gz
+          name: medusa-${{ runner.os }}-${{ runner.arch }}
+          path: |
+            ./medusa-*.tar.gz
+            ./medusa-*.tar.gz.sigstore
+
+  release:
+    needs: [build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: write
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Download binaries
+        uses: actions/download-artifact@v4
+        with:
+          pattern: medusa-*
+          merge-multiple: true
+
+      - name: Create GitHub release and upload binaries
+        uses: softprops/action-gh-release@9d7c94cfd0a1f3ed45544c887983e9fa900f0564 # v2.0.4
+        with:
+          draft: true
+          name: "${{ github.ref_name }}"
+          files: |
+            ./medusa-*.tar.gz
+            ./medusa-*.tar.gz.sigstore
 
   lint:
     runs-on: ubuntu-latest
     timeout-minutes: 10
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-go@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: "^1.18.1"
 
@@ -110,13 +159,17 @@ jobs:
   test:
     strategy:
       matrix:
-        environment: [ubuntu-latest, macos-latest, windows-latest]
+        environment: [ubuntu-latest, macos-12, macos-14, windows-latest]
 
     runs-on: ${{ matrix.environment }}
     timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
 
       - name: Speed up Go, Python, Node (Windows)
         if: runner.os == 'Windows'
@@ -142,11 +195,11 @@ jobs:
           npm config set cache "$DIR\\npm-cache" --global
           echo "::endgroup::"
 
-      - uses: actions/setup-go@v4
+      - uses: actions/setup-go@v5
         with:
           go-version: "^1.18.1"
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
           node-version: 18.15
 
@@ -165,9 +218,14 @@ jobs:
         run: go test ./...
 
   all-checks:
-    needs: [lint, test, build]
+    if: always()
+    needs: [lint, test, build, release]
 
     runs-on: ubuntu-latest
 
     steps:
-      - run: true
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
+        with:
+          allowed-skips: release
+          jobs: ${{ toJSON(needs) }}

.gitignore

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

CONTRIBUTING.md

@@ -34,6 +34,47 @@ If any of these requirements are violated, you should expect your pull request t
 
 Pull request reviewers have a responsibility to uphold these standards. Even if a pull request is compliant with these requirements, a reviewer which identifies an opportunity to document some caveat (such as a `// TODO: ` comment) should request it be added prior to pull request approval.
 
+### Linters
+
+Several linters and security checkers are run on the PRs.
+
+#### Go
+
+To install
+
+- `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`
+
+To run
+
+- `go fmt ./...`
+- `golangci-lint run --timeout 5m0s`
+
+#### Markdown/Json/Yaml
+
+To install
+
+- `npm install -g prettier`
+- `npm install -g [email protected]`
+
+To run
+
+- `prettier '**.json' '**/*.md' '**/*.yml' '!(pkg)'`
+- `markdown-link-check --config .github/workflows/resources/markdown_link_check.json ./*.md`
+
+To format (overwrite files)
+
+- `prettier '**.json' '**/*.md' '**/*.yml' '!(pkg)' -w`
+
+#### Github action
+
+To install
+
+- `go install github.com/rhysd/actionlint/cmd/actionlint@latest`
+
+To run
+
+- `actionlint`
+
 ### Cross-platform considerations
 
 - Ensure file/directory names do not exceed 32 characters in length to minimize filepath length issues on Windows. File/directory names should be shorter than this where possible.

README.md

@@ -17,95 +17,18 @@ It provides parallelized fuzz testing of smart contracts through CLI, or its Go
 - ✔️**Extensible low-level testing API** through events and hooks provided throughout the fuzzer, workers, and test chains.
 - ❌ **Extensible high-level testing API** allowing for the addition of per-contract or global post call/event property tests with minimal effort.
 
-## Installation
+## Documentation
 
-### Precompiled binaries
+To learn more about how to install and use `medusa`, please refer to our [documentation](./docs/src/SUMMARY.md).
 
-To use `medusa`, first ensure you have [crytic-compile](https://github.com/crytic/crytic-compile) and a suitable compilation framework (e.g. `solc`, `hardhat`) installed on your machine.
+For a better viewing experience, we recommend you install [mdbook](https://rust-lang.github.io/mdBook/guide/installation.html)
+and then running the following steps from medusa's source directory:
 
-You can then fetch the latest binaries for your platform from our [GitHub Releases](https://github.com/crytic/medusa/releases) page.
-
-### Building from source
-
-#### Requirements
-
-- You must have at least go 1.18 installed.
-- [Windows only] The `go-ethereum` dependency may require [TDM-GCC](https://jmeubank.github.io/tdm-gcc/) to build.
-
-#### Steps
-
-- Clone the repository, then execute `go build` in the repository root.
-- Go will automatically fetch all dependencies and build a binary for you in the same folder when completed.
-
-## Usage
-
-Although we recommend users run `medusa` in a configuration file driven format for more customizability, you can also run `medusa` through the CLI directly.
-We provide instructions for both below.
-
-We recommend you familiarize yourself with writing [assertion](https://github.com/crytic/building-secure-contracts/blob/master/program-analysis/echidna/basic/assertion-checking.md) and [property](https://github.com/crytic/building-secure-contracts/blob/master/program-analysis/echidna/introduction/how-to-test-a-property.md) tests for Echidna. `medusa` supports Echidna-like property testing with config-defined function prefixes (default: `fuzz_`) and assertion testing using Solidity `assert(...)` statements.
-
-### Command-line only
-
-You can use the following command to run `medusa` against a contract:
-
-```console
-medusa fuzz --target contract.sol --deployment-order ContractName
-```
-
-Where:
-
-- `--target` specifies the path `crytic-compile` should use to compile contracts
-- `--deployment-order` specifies comma-separated names of contracts to be deployed for testing.
-
-**Note:** Check out the [command-line interface](https://github.com/crytic/medusa/wiki/Command-Line-Interface) wiki page, or run `medusa --help` for more information.
-
-### Configuration file driven
-
-The preferred method to use medusa is to enter your project directory (hardhat directory, or directory with your contracts),
-then execute the following command:
-
-```console
-medusa init
-```
-
-This will create a `medusa.json` in your current folder. There are two required fields that should be set correctly:
-
-- Set your `"target"` under `"compilation"` to point to the file/directory which `crytic-compile` should use to build your contracts.
-- Put the names of any contracts you wish to deploy and run tests against in the `"deploymentOrder"` field. This must be non-empty.
-
-After you have a configuration in place, you can execute:
-
-```console
-medusa fuzz
+```bash
+cd docs
+mdbook serve
 ```
 
-This will use the `medusa.json` configuration in the current directory and begin the fuzzing campaign.
-
-**Note:** Check out the [project configuration](https://github.com/crytic/medusa/wiki/Project-Configuration) wiki page, or run `medusa --help` for more information.
-
-## Running Unit Tests
-
-First, install [crytic-compile](https://github.com/crytic/crytic-compile), [solc-select](https://github.com/crytic/solc-select), and ensure you have `solc` (version >=0.8.7), and `hardhat` available on your system.
-
-- From the root of the repository, invoke `go test -v ./...` on through command-line to run tests from all packages at or below the root.
-  - Or enter each package directory to run `go test -v .` to test the immediate package.
-  - Note: the `-v` parameter provides verbose output.
-- Otherwise, use an IDE like [GoLand](https://www.jetbrains.com/go/) to visualize the tests and logically separate output.
-
-## FAQs
-
-**Why create `medusa` if Echidna is already working just fine?**
-
-With `medusa`, we are exploring a different EVM implementation and language for our smart contract fuzzer. We believe that
-experimenting with a new fuzzer provides us with the following benefits:
-
-- Since `medusa` is written in Go, we believe that this will **lower the barrier of entry for external contributions**.
-  We have taken great care in thoroughly commenting our code so that it is easy for new contributors to get up-to-speed and start contributing!
-- The use of Go allows us to build an API to hook into the various parts of the fuzzer to build custom testing methodologies. See the [API Overview (WIP)](<https://github.com/crytic/medusa/wiki/API-Overview-(WIP)>) section in the Wiki for more details.
-- Our forked version of go-ethereum, [`medusa-geth`](https://github.com/crytic/medusa-geth), exhibits behavior that is closer to that of the EVM in production environments.
-- We can take the lessons we learned while developing Echidna to create a fuzzer that is just as feature-rich but with additional capabilities to
-  create powerful and unique testing methodologies.
-
 ## Contributing
 
 For information about how to contribute to this project, check out the [CONTRIBUTING](./CONTRIBUTING.md) guidelines.

chain/cheat_code_contract.go

@@ -54,6 +54,30 @@ type cheatCodeRawReturnData struct {
 	Err error
 }
 
+// getCheatCodeProviders obtains a cheatCodeTracer (used to power cheat code analysis) and associated CheatCodeContract
+// objects linked to the tracer (providing on-chain callable methods as an entry point). These objects are attached to
+// the TestChain to enable cheat code functionality.
+// Returns the tracer and associated pre-compile contracts, or an error, if one occurred.
+func getCheatCodeProviders() (*cheatCodeTracer, []*CheatCodeContract, error) {
+	// Create a cheat code tracer and attach it to the chain.
+	tracer := newCheatCodeTracer()
+
+	// Obtain our standard cheat code pre-compile
+	stdCheatCodeContract, err := getStandardCheatCodeContract(tracer)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	// Obtain the console.log pre-compile
+	consoleCheatCodeContract, err := getConsoleLogCheatCodeContract(tracer)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	// Return the tracer and precompiles
+	return tracer, []*CheatCodeContract{stdCheatCodeContract, consoleCheatCodeContract}, nil
+}
+
 // newCheatCodeContract returns a new precompiledContract which uses the attached cheatCodeTracer for execution
 // context.
 func newCheatCodeContract(tracer *cheatCodeTracer, address common.Address, name string) *CheatCodeContract {
@@ -98,7 +122,7 @@ func (c *CheatCodeContract) Abi() *abi.ABI {
 }
 
 // addMethod adds a new method to the precompiled contract.
-// Returns an error if one occurred.
+// Throws a panic if either the name is the empty string or the handler is nil.
 func (c *CheatCodeContract) addMethod(name string, inputs abi.Arguments, outputs abi.Arguments, handler cheatCodeMethodHandler) {
 	// Verify a method name was provided
 	if name == "" {
@@ -117,7 +141,6 @@ func (c *CheatCodeContract) addMethod(name string, inputs abi.Arguments, outputs
 		method:  method,
 		handler: handler,
 	}
-
 	// Add the method to the ABI.
 	// Note: Normally the key here should be the method name, not sig. But cheat code contracts have duplicate
 	// method names with different parameter types, so we use this so they don't override.