foundry-template/README.md

199 lines
6.0 KiB
Markdown
Raw Normal View History

# Foundry Template [![Open in Gitpod][gitpod-badge]][gitpod] [![Github Actions][gha-badge]][gha] [![Foundry][foundry-badge]][foundry] [![License: MIT][license-badge]][license]
2022-07-16 11:36:29 +00:00
[gitpod]: https://gitpod.io/#https://github.com/paulrberg/foundry-template
[gitpod-badge]: https://img.shields.io/badge/Gitpod-Open%20in%20Gitpod-FFB45B?logo=gitpod
2022-07-16 11:36:29 +00:00
[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, debug and deploy smart
contracts
2022-07-19 15:54:57 +00:00
- [PRBTest](https://github.com/paulrberg/prb-test): modern collection of testing assertions and logging utilities
2022-07-16 11:36:29 +00:00
- [Forge Std](https://github.com/foundry-rs/forge-std): collection of helpful contracts and cheatcodes for testing
- [Solhint](https://github.com/protofire/solhint): code linter
- [Prettier Plugin Solidity](https://github.com/prettier-solidity/prettier-plugin-solidity): code formatter
## 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.
2022-07-16 11:36:29 +00:00
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 and prettier and other goodies
```
If this is your first time with Foundry, check out the
[installation](https://github.com/foundry-rs/foundry#installation) instructions.
2022-07-16 11:36:29 +00:00
## Features
This template builds upon the frameworks and libraries mentioned above, so for details about their specific features,
please consult their respective documentations.
2022-07-16 11:36:29 +00:00
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.
2022-07-16 11:36:29 +00:00
### Sensible Defaults
This template comes with sensible default configurations in the following files:
```text
├── .commitlintrc.yml
├── .editorconfig
├── .gitignore
├── .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).
2022-07-16 11:36:29 +00:00
### 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.
2022-07-16 11:36:29 +00:00
### 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 Prettier when making a git
commit.
2022-07-16 11:36:29 +00:00
## 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 `-vvvv` flag.
2022-07-16 11:36:29 +00:00
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
```
2022-07-16 11:36:29 +00:00
### Deploy
Deploy to Anvil:
```sh
$ forge script script/Foo.s.sol:FooScript --fork-url http://localhost:8545 \
--broadcast --private-key $PRIVATE_KEY
```
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).
2022-07-16 11:36:29 +00:00
### Format
Format the contracts:
2022-07-16 11:36:29 +00:00
```sh
$ forge fmt
2022-07-16 11:36:29 +00:00
```
### 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.
2022-07-16 11:36:29 +00:00
## 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