Stash Contracts

• Contract docs

Development

Setup

git submodule update --init --recursive --remote
yarn
curl -L https://foundry.paradigm.xyz | bash
foundryup

• Copy .env-example to .env, filling in the placeholders

Commands

• yarn build: Compile contracts & generate typechain artifacts
• yarn test: Run tests
• yarn gas: Check gas costs
  • Hardhat tests may save results with gasStory which are saved to ./generated/gas-stories.txt for PR diffs (auto-pushed via CI)
• yarn coverage: Run coverage tests
  • Summary in the console and a full report in ./generated/coverage/index.html (not checked in)
• yarn lint: Lint & prettier

Other commands and some sub-variants, such as test:hardhat, are also available -- see package.json for the full list.

Testing

Fork Testing

All Hardhat tests run as a fork against mainnet, allowing tests to use real examples where relevant. e.g. contracts.forked.dai to interact with the real DAI ERC20 contract.

Coverage

Hardhat tests which should be used to measure test coverage must be named <name>.test.ts, all others will be treated as supplemental tests which do not improve test coverage. This allows test files to be used for POC or happy case paths without implying that all the correct assertions have been confirmed.

Gas

Hardhat Gas Reporter:

yarn gas:hardhat will use Hardhat Gas Reporter to display the range of costs seen throughout tests for each function call.

Hardhat Gas "User Stories":

The Gas Reporter results can be misleading since tests often use very contrived examples. To supplement this, we use "Gas Stories" which allow us to capture very specific scenarios aimed to represent the core use case or critical calls -- these should be limited to common paths to ease comparing gas costs for important scenarios.

Slither

Slither will run in CI and commit issues to slither.md.

• To suppress a warning which need not be addressed, use // slither-disable-next-line <detector name>.
• Global exclusions can be added to slither.config.json.
  • solc-version: Excluded because we prefer the latest version.
  • timestamp: Excluded because we prefer time over block numbers for ease of use.

Deployments

CI should be used for all deployments. This provides an easy way to track changes and ensures the build is current (e.g. including the correct NPM package versions).

Contracts

Create a git tag off the main branch named deploy-<network>-<version>, e.g. deploy-goerli-v0.0.1. If a new upgradeable proxy or other top-level contract is deployed, add that address to the addresses file (this should be done before pushing the NPM package).

NPM package

Create a git tag off the main branch named v<version>, e.g. v0.0.1.