203 lines
6.1 KiB
Markdown
203 lines
6.1 KiB
Markdown
# Foundry Template [![Open in Gitpod][gitpod-badge]][gitpod] [![Github Actions][gha-badge]][gha] [![Foundry][foundry-badge]][foundry] [![License: MIT][license-badge]][license]
|
|
|
|
[gitpod]: https://gitpod.io/#https://github.com/PaulRBerg/foundry-template
|
|
[gitpod-badge]: https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-FFB45B?logo=gitpod
|
|
[gha]: https://github.com/PaulRBerg/foundry-template/actions
|
|
[gha-badge]: https://github.com/PaulRBerg/foundry-template/actions/workflows/ci.yml/badge.svg
|
|
[foundry]: https://getfoundry.sh/
|
|
[foundry-badge]: https://img.shields.io/badge/Built%20with-Foundry-FFDB1C.svg
|
|
[license]: https://opensource.org/licenses/MIT
|
|
[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
|
|
|
|
A Foundry-based template for developing Solidity smart contracts, with sensible defaults.
|
|
|
|
## What's Inside
|
|
|
|
- [Forge](https://github.com/foundry-rs/foundry/blob/master/forge): compile, test, fuzz, format, and deploy smart
|
|
contracts
|
|
- [PRBTest](https://github.com/PaulRBerg/prb-test): modern collection of testing assertions and logging utilities
|
|
- [Forge Std](https://github.com/foundry-rs/forge-std): collection of helpful contracts and cheatcodes for testing
|
|
- [Solhint](https://github.com/protofire/solhint): linter for Solidity code
|
|
- [Prettier Plugin Solidity](https://github.com/prettier-solidity/prettier-plugin-solidity): code formatter for
|
|
non-Solidity files
|
|
|
|
## Getting Started
|
|
|
|
Click the [`Use this template`](https://github.com/PaulRBerg/foundry-template/generate) button at the top of the page to
|
|
create a new repository with this repo as the initial state.
|
|
|
|
Or, if you prefer to install the template manually:
|
|
|
|
```sh
|
|
forge init my-project --template https://github.com/PaulRBerg/foundry-template
|
|
cd my-project
|
|
yarn install # install Solhint, Prettier, and other tools
|
|
```
|
|
|
|
If this is your first time with Foundry, check out the
|
|
[installation](https://github.com/foundry-rs/foundry#installation) instructions.
|
|
|
|
## Features
|
|
|
|
This template builds upon the frameworks and libraries mentioned above, so for details about their specific features,
|
|
please consult their respective documentation.
|
|
|
|
For example, for Foundry, you can refer to the [Foundry Book](https://book.getfoundry.sh/). You might be in particular
|
|
interested in reading the [Writing Tests](https://book.getfoundry.sh/forge/writing-tests.html) guide.
|
|
|
|
### Sensible Defaults
|
|
|
|
This template comes with sensible default configurations in the following files:
|
|
|
|
```text
|
|
├── .commitlintrc.yml
|
|
├── .editorconfig
|
|
├── .gitignore
|
|
├── .lintstagedrc.yml
|
|
├── .prettierignore
|
|
├── .prettierrc.yml
|
|
├── .solhintignore
|
|
├── .solhint.json
|
|
├── .yarnrc.yml
|
|
├── foundry.toml
|
|
└── remappings.txt
|
|
```
|
|
|
|
### VSCode Integration
|
|
|
|
This template is IDE agnostic, but for the best user experience, you may want to use it in VSCode with Juan Blanco's
|
|
[Solidity extension](https://github.com/juanfranblanco/vscode-solidity).
|
|
|
|
For guidance on how to integrate a Foundry project in VSCode, please refer to this
|
|
[guide](https://book.getfoundry.sh/config/vscode).
|
|
|
|
### GitHub Actions
|
|
|
|
This template comes with GitHub Actions pre-configured. Your contracts will be linted and tested on every push and pull
|
|
request made to the `main` branch.
|
|
|
|
You can edit the CI script in [.github/workflows/ci.yml](./.github/workflows/ci.yml).
|
|
|
|
### Conventional Commits
|
|
|
|
This template enforces the [Conventional Commits](https://www.conventionalcommits.org/) standard for git commit
|
|
messages. This is a lightweight convention that creates an explicit commit history, which makes it easier to write
|
|
automated tools on top of.
|
|
|
|
### Git Hooks
|
|
|
|
This template uses [Husky](https://github.com/typicode/husky) to run automated checks on commit messages, and
|
|
[Lint Staged](https://github.com/okonet/lint-staged) to automatically format the code with Forge and Prettier when
|
|
making a git commit.
|
|
|
|
## Writing Tests
|
|
|
|
To write a new test contract, you start by importing [PRBTest](https://github.com/PaulRBerg/prb-test) and inherit from
|
|
it in your test contract. PRBTest comes with a pre-instantiated [cheatcodes](https://book.getfoundry.sh/cheatcodes/)
|
|
environment accessible via the `vm` property. You can also use
|
|
[console.log](https://book.getfoundry.sh/faq?highlight=console.log#how-do-i-use-consolelog), whose logs you can see in
|
|
the terminal output by adding the `-vvv` flag.
|
|
|
|
This template comes with an example test contract [Foo.t.sol](./test/Foo.t.sol).
|
|
|
|
## Usage
|
|
|
|
Here's a list of the most frequently needed commands.
|
|
|
|
### Build
|
|
|
|
Build the contracts:
|
|
|
|
```sh
|
|
$ forge build
|
|
```
|
|
|
|
### Clean
|
|
|
|
Delete the build artifacts and cache directories:
|
|
|
|
```sh
|
|
$ forge clean
|
|
```
|
|
|
|
### Compile
|
|
|
|
Compile the contracts:
|
|
|
|
```sh
|
|
$ forge build
|
|
```
|
|
|
|
### Coverage
|
|
|
|
Get a test coverage report:
|
|
|
|
```sh
|
|
$ forge coverage
|
|
```
|
|
|
|
### Deploy
|
|
|
|
Deploy to Anvil:
|
|
|
|
```sh
|
|
$ forge script script/DeployFoo.s.sol --broadcast --fork-url http://localhost:8545
|
|
```
|
|
|
|
For this script to work, you need to have a `MNEMONIC` environment variable set to a valid
|
|
[BIP39 mnemonic](https://iancoleman.io/bip39/).
|
|
|
|
For instructions on how to deploy to a testnet or mainnet, check out the
|
|
[Solidity Scripting tutorial](https://book.getfoundry.sh/tutorials/solidity-scripting.html).
|
|
|
|
### Format
|
|
|
|
Format the contracts:
|
|
|
|
```sh
|
|
$ forge fmt
|
|
```
|
|
|
|
### Gas Usage
|
|
|
|
Get a gas report:
|
|
|
|
```sh
|
|
$ forge test --gas-report
|
|
```
|
|
|
|
### Lint
|
|
|
|
Lint the contracts:
|
|
|
|
```sh
|
|
$ yarn lint
|
|
```
|
|
|
|
### Test
|
|
|
|
Run the tests:
|
|
|
|
```sh
|
|
$ forge test
|
|
```
|
|
|
|
## Notes
|
|
|
|
1. Foundry piggybacks off [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to manage dependencies.
|
|
There's a [guide](https://book.getfoundry.sh/projects/dependencies.html) about how to work with dependencies in the
|
|
book.
|
|
2. You don't have to create a `.env` file, but filling in the environment variables may be useful when debugging and
|
|
testing against a mainnet fork.
|
|
|
|
## Related Efforts
|
|
|
|
- [abigger87/femplate](https://github.com/abigger87/femplate)
|
|
- [cleanunicorn/ethereum-smartcontract-template](https://github.com/cleanunicorn/ethereum-smartcontract-template)
|
|
- [foundry-rs/forge-template](https://github.com/foundry-rs/forge-template)
|
|
- [FrankieIsLost/forge-template](https://github.com/FrankieIsLost/forge-template)
|
|
|
|
## License
|
|
|
|
[MIT](./LICENSE.md) © Paul Razvan Berg
|