aj242424 / solidity-audit-template

Combines Hardhat, TypeChain, Ethers, Waffle, Solhint, Solcover, Prettier, Tracer, storage layout analysis, EVM network forking, Immunefi/Etherscan contract download and external contract testing

Solidity Coding, Testing and Audit Template

My favorite setup for writing Solidity smart contracts as well as auditing/testing external contracts.

• Hardhat: compile and run the smart contracts on a local development network
• TypeChain: generate TypeScript types for smart contracts
• Ethers: renowned Ethereum library and wallet implementation
• Waffle: tooling for writing comprehensive smart contract tests
• Solhint: linter
• Solcover: code coverage
• Prettier Plugin Solidity: code formatter
• Tracer: trace events, calls and storage operations
• Storage Layout: generate smart contract storage layout
• Fork the mainnet or another EVM based network as a Hardhat Network instance
• Download external contracts and their dependencies (via Python script)
• Gather contracts in scope from Immuenfi bug bounty (via Python script)
• Attach tests to external contracts (in mainnet fork)

This is a GitHub template, which means you can reuse it as many times as you want. You can do that by clicking the "Use this template" button at the top of the page.

Usage

Pre Requisites

Before running any command, you need to create a .env file and set a BIP-39 compatible mnemonic as an environment variable. Follow the example in .env.example. If you don't already have a mnemonic, use this website to generate one.

Then, proceed with installing dependencies:

$ yarn install
$ pip install -r contract-downloader/requirements.txt  # for Python contract downloader

Example usage: External contract testing

1. Download external contract + dependencies or download contracts from Immunefi bug bounty

$ yarn clone <contract address>
# OR
$ yarn immunefi <bug bounty URL>

2. Set Solidity version in hardhat.config.ts
3. Compile contract(s) and generate typings

$ yarn compile

4. Export the contracts' storage layouts

$ yarn storage

5. Fork the mainnet as a local Hardhat Network instance

$ yarn fork

6. Adapt the test templates to break/exploit the external contract in the local Hardhat Network instance

$ yarn attach <contract address>
$ yarn attachContract <contract address>

Compile

Compile the smart contracts with Hardhat:

$ yarn compile

TypeChain

Compile the smart contracts and generate TypeChain artifacts:

$ yarn typechain

Lint Solidity

Lint the Solidity code:

$ yarn lint:sol

Lint TypeScript

Lint the TypeScript code:

$ yarn lint:ts

Test

Run the Mocha test for the example Greeter contract:

$ yarn test

Coverage

Generate the code coverage report:

$ yarn coverage

Report Gas

See the gas usage per unit test and average gas per method call:

$ REPORT_GAS=true
$ yarn test

Tracer

Shows events, calls and storage operations when running the tests:

$ yarn test --trace      # shows logs + calls
$ yarn test --fulltrace  # shows logs + calls + sloads + sstores

Storage Layout

Shows the compiled contracts' storage layouts:

$ yarn storage

Mainnet Fork

Starts an instance of Hardhat Network that forks mainnet. This means that it will simulate having the same state as mainnet, but it will work as a local development network. That way you can interact with deployed protocols and test complex interactions locally.

To use this feature you need to set your Infura API key in the .env file.

$ yarn fork
$ yarn fork --fork-block-number <num>  # pin the block number

Network Fork

Starts an instance of Hardhat Network that forks an EVM based network. Supported networks are given by chainIds[] in hardhat.config.ts.

$ yarn forkNetwork --network <chain>  # e.g. rinkeby or polygon-mainnet

Clone (with Python contract downloader)

Downloads a verified smart contract and its dependencies from Etherscan, etc. To use this feature you need to set the relevant API keys in the .env file.

$ yarn clone <contract address>
$ yarn clone <contract address> --network <chain>  # e.g. polygon or bsc

In order to remove a previously downloaded smart contract and its dependencies from the local filesystem, run:

$ yarn clone <contract address> --remove

Furthermore, implementation contracts can be downloaded through proxies by:

$ yarn clone <proxy contract address> --impl

Immunefi (with Python contract downloader)

Gathers all block explorer links to verified smart contracts in scope from an Immunefi bug bounty page and forwards them to the downloader, see Clone.

$ yarn immunefi <bug bounty URL>
$ yarn immunefi <bug bounty URL> --remove  #  delete contracts

Attach test to external contract

Attaches the Mocha test external/Attach to a deployed contract in your local Hardhat Network (e.g. mainnet fork). The test contains sample code for the Greeter contract and therefore needs to be adapted according to your needs.

$ yarn attach <contract address>

Features like Report Gas and Tracer can also be used with this test.

Attach test contract to external contract

Attaches the Mocha test external/AttachContract and the contract test/Test to a deployed contract in your local Hardhat Network (e.g. mainnet fork). The test contains sample code for the Greeter contract and therefore needs to be adapted according to your needs.

$ yarn attachContract <contract address>

Features like Report Gas and Tracer can also be used with this test.

Clean

Delete the smart contract artifacts, the coverage reports and the Hardhat cache:

$ yarn clean

Deploy

Deploy the example Greeter contract to the Hardhat Network:

$ yarn deploy --greeting "Hello, world!"

Syntax Highlighting

If you use VSCode, you can enjoy syntax highlighting for your Solidity code via the hardhat-vscode extension.

Caveats

Ethers and Waffle

If you can't get the Waffle matchers to work, try to make your ethers package version match the version used by the @ethereum-waffle/chai package. Seem #111 for more details.