202 lines
6.0 KiB
Markdown
202 lines
6.0 KiB
Markdown
# Foundry Template [![Github Actions][gha-badge]][gha] [![Foundry][foundry-badge]][foundry] [![License: MIT][license-badge]][license]
|
|
|
|
[gha]: https://github.com/vacp2p/foundry-template/actions
|
|
[gha-badge]: https://github.com/vacp2p/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.
|
|
|
|
This is a fork of [PaulRBerg's template](https://github.com/PaulRBerg/foundry-template) and adjusted to Vac's smart
|
|
contracts unit's needs. See [Upstream differences](#upstream-differences) to learn more about how this template differs
|
|
from Paul's.
|
|
|
|
## What's Inside
|
|
|
|
- [Forge](https://github.com/foundry-rs/foundry/blob/master/forge): compile, test, fuzz, format, and deploy smart
|
|
contracts
|
|
- [Forge Std](https://github.com/foundry-rs/forge-std): collection of helpful contracts and cheatcodes for testing
|
|
- [Solhint Community](https://github.com/solhint-community/solhint-community): linter for Solidity code
|
|
|
|
## Getting Started
|
|
|
|
Click the [`Use this template`](https://github.com/vacp2p/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
|
|
$ mkdir my-project
|
|
$ cd my-project
|
|
$ forge init --template vacp2p/foundry-template
|
|
$ pnpm install # install Solhint, Prettier, and other Node.js deps
|
|
```
|
|
|
|
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, if you're interested in exploring Foundry in more detail, you should look at the
|
|
[Foundry Book](https://book.getfoundry.sh/). In particular, you may be interested in reading the
|
|
[Writing Tests](https://book.getfoundry.sh/forge/writing-tests.html) tutorial.
|
|
|
|
### Upstream differences
|
|
|
|
As mentioned above, this template is a fork with adjustments specific to the needs of Vac's smart contract service unit.
|
|
These differences are:
|
|
|
|
- **Removal of [PRBTest](https://github.com/PaulRBerg/prb-test)** - In an attempt to keep dependence on third-party code
|
|
low, we've decided to remove this library as a standard dependency of every project within Vac. If we do see a need
|
|
for it, we might bring it back in the future.
|
|
- **PROPERTIES.md** - For invariant testing and formal verification, we've introduced a `PROPERTIES.md` to document all
|
|
protocol properties that must hold true.
|
|
|
|
### Sensible Defaults
|
|
|
|
This template comes with a set of sensible default configurations for you to use. These defaults can be found in the
|
|
following files:
|
|
|
|
```text
|
|
├── .editorconfig
|
|
├── .gitignore
|
|
├── .prettierignore
|
|
├── .prettierrc.yml
|
|
├── .solhint.json
|
|
├── foundry.toml
|
|
├── remappings.txt
|
|
└── slither.config.json
|
|
```
|
|
|
|
### VSCode Integration
|
|
|
|
This template is IDE agnostic, but for the best user experience, you may want to use it in VSCode alongside Nomic
|
|
Foundation's [Solidity extension](https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-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).
|
|
|
|
## Writing Tests
|
|
|
|
If you would like to view the logs in the terminal output you can add the `-vvv` flag and use
|
|
[console.log](https://book.getfoundry.sh/faq?highlight=console.log#how-do-i-use-consolelog).
|
|
|
|
This template comes with an example test contract [Foo.t.sol](./test/Foo.t.sol)
|
|
|
|
## Usage
|
|
|
|
This is 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/Deploy.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](https://book.getfoundry.sh/tutorials/solidity-scripting.html) tutorial.
|
|
|
|
### Format
|
|
|
|
Format the contracts:
|
|
|
|
```sh
|
|
$ forge fmt
|
|
```
|
|
|
|
### Gas Usage
|
|
|
|
Get a gas report:
|
|
|
|
```sh
|
|
$ forge test --gas-report
|
|
```
|
|
|
|
### Lint
|
|
|
|
Lint the contracts:
|
|
|
|
```sh
|
|
$ pnpm lint
|
|
```
|
|
|
|
#### Fixing linting issues
|
|
|
|
For any errors in solidity files, run `forge fmt`. For errors in any other file type, run `pnpm prettier:write`.
|
|
|
|
### Test
|
|
|
|
Run the tests:
|
|
|
|
```sh
|
|
$ forge test
|
|
```
|
|
|
|
## Notes
|
|
|
|
1. Foundry uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to manage dependencies. For
|
|
detailed instructions on working with dependencies, please refer to the
|
|
[guide](https://book.getfoundry.sh/projects/dependencies.html) 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 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
|
|
|
|
This project is licensed under MIT.
|