add readme and top level helpers

.github/workflows/test.yml

@@ -39,5 +39,5 @@ jobs:
 
       - name: Run Forge tests
         run: |
-          forge test -vvv
+          FOUNDRY_PROFILE=CI forge test -vvv
         id: test

.gitignore

@@ -1,6 +1,7 @@
 # Compiler files
 cache/
 out/
+via_ir-out/
 
 # Ignores development broadcast logs
 !/broadcast
@@ -14,3 +15,7 @@ docs/
 .env
 
 .DS_Store
+
+# coverage
+coverage/
+lcov.info

README.md

@@ -0,0 +1,79 @@
+# Shipyard
+
+Shipyard is a Forge template for smart contract development.
+
+
+## Installation
+
+Shipyard requires Foundry. You can find specific install instructions [here](https://book.getfoundry.sh/getting-started/installation#using-foundryup).
+
+But most likely, you can install Foundry with the following commands:
+
+```bash
+# this installs Foundryup, the Foundry installer and updater
+curl -L https://foundry.paradigm.xyz | bash
+# follow the onscreen instructions output by the previous command to make Foundryup available in your CLI (or else restart your CLI), then run:
+foundryup
+```
+
+If you plan on generating coverage reports, you'll need to install [`lcov`](https://github.com/linux-test-project/lcov) as well.
+
+On macOS, you can do this with the following command:
+
+```bash
+brew install lcov
+```
+
+## Overview
+Shipyard comes with some batteries included
+
+- [OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts), [Solady](https://github.com/Vectorized/solady), and Shipyard-core smart contracts as dependencies, ready with [`solc` remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) so you can jump into writing your own contracts right away
+- `forge fmt` configured as the default formatter for VSCode projects
+- Github Actions workflows that run `forge fmt --check` and `forge test` on every push and PR
+  - A separate action to automatically fix formatting issues on PRs by commenting `!fix` on the PR
+- A pre-configured, but still minimal `foundry.toml` 
+  - high optimizer settings by default for gas-efficient smart contracts
+  - an explicit `solc` compiler version for reproducible builds
+  - no extra injected `solc` metadata for simpler Etherscan verification and [deterministic cross-chain deploys via CREATE2](https://0xfoobar.substack.com/p/vanity-addresses).
+  - a separate build profile for CI with increased fuzz runs for quicker local iteration, while still ensuring your contracts are well-tested
+
+## Usage
+
+### Reinitialize Submodules
+When working across branches with different dependencies, submodules may need to be reinitialized. Run
+```bash
+./reinit-submodules
+```
+
+### Coverage Reports
+Run
+```bash
+./coverage-report
+```
+
+
+
+## Roadmap
+
+- [x] Configure test.yml to run `forge test` on every push to main and PR
+- [x] Add a `forge fmt --check` workflow to the Github Actions
+- [x] Add an optional `forge fmt` fix workflow to the Github Actions
+- [ ]  Include base dependencies
+  - [x] OZ
+    - [ ] Pin to version
+  - [x] Solady
+    - [ ] Pin to version
+  - [ ] Shipyard-core (dependent on making public)
+- [ ] Include a base cross-chain deploy script
+- [ ] Figure out if there's a way we can make `forge verify-contract` more ergonomic
+- [ ] Top-level helpers:
+  - [x] PRB's `reinit-submodules` script as top-level helper
+  - [x] `coverage-report` script as top-level helper
+  - [ ] TODO: are there security concerns about these?
+
+Copilot suggests:
+- [ ] Additional github actions
+  - [ ] Add a `forge deploy` workflow to the Github Actions
+  - [ ] Add a `forge verify` workflow to the Github Actions
+- [ ] Add a `forge verify` script to the top-level helpers
+- [ ] 

coverage-report

@@ -0,0 +1,3 @@
+# "Forge coverage" - Generate a coverage summary report as well as an lcov.info, and generate an HTML report from the lcov.info
+# Requires the lcov package to be installed
+forge coverage --report summary --report lcov && genhtml lcov.info -o coverage --branch

foundry.toml

@@ -1,4 +1,6 @@
 [profile.default]
+auto_detect_solc = false
+solc = '0.8.20'
 src = "src"
 out = "out"
 libs = ["lib"]
@@ -9,15 +11,28 @@ remappings = [
     'openzeppelin-contracts/=lib/openzeppelin-contracts/contracts/',
     'shipyard-core/=lib/shipyard-core/src/',
 ]
+# use realistic numbers in tests
+block_number = 17722462
+block_timestamp = 1689711647
+# don't pollute bytecode with metadata
 bytecode_hash = 'none'
+cbor_metadata = false
+# grant access to read via_ir-out by default, if necessary
+fs_permissions = [{ access = "read", path = "./via_ir-out" }]
 # etherscan currently does not support contracts with more than 10 million optimizer runs;
 # bytecode is typically unaffected past ~1 million runs anyway
 optimizer_runs = 99_999_999
 
+# via_ir pipeline is very slow - use a separate profile to pre-compile and then use vm.getCode to deploy
 [profile.via_ir]
 via_ir = true
-# do not compile tests when compiling via ir
+# do not compile tests when compiling via-ir
 test = 'src'
 out = 'via_ir-out'
 
+# offload bulk of fuzz runs to CI
+[profile.CI.fuzz]
+fuzz_runs = 1024
+
+
 # See more config options https://github.com/foundry-rs/foundry/tree/master/config

reinit-submodules

@@ -0,0 +1,5 @@
+# when switching between git branches on forge projects, submodules may become
+# out-of-sync
+# h/t @PaulRBerg: https://twitter.com/PaulRBerg/status/1629425771457531905
+git submodule deinit -f .
+git submodule update --init --recursive

sample.env

@@ -0,0 +1,2 @@
+# see https://book.getfoundry.sh/reference/config/testing#verbosity
+FOUNDRY_VERBOSITY=3