From 6f0ee879217b5ed2d1cc95a2ed3c4ad2f3b0d2bd Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 4 Nov 2024 12:24:20 -0500 Subject: [PATCH 1/3] modify README for foundry and remove HH references --- contracts/README.md | 63 +++++++++++++++++++++++++++++++++++++------- contracts/foundry.md | 27 ------------------- 2 files changed, 54 insertions(+), 36 deletions(-) delete mode 100644 contracts/foundry.md diff --git a/contracts/README.md b/contracts/README.md index 182891ceef7..b440d67f4fe 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -15,8 +15,9 @@ $ npm install @chainlink/contracts --save @chainlink/contracts ├── src # Solidity contracts │ └── v0.8 -└── abi # ABI json output - └── v0.8 +│── abi # ABI json output +│ └── v0.8 +└── gas-snapshots # gas metered results of available non-fuzz tests ``` ### Usage @@ -24,22 +25,66 @@ $ npm install @chainlink/contracts --save The solidity smart contracts themselves can be imported via the `src` directory of `@chainlink/contracts`: ```solidity -import '@chainlink/contracts/src/v0.8/AutomationCompatibleInterface.sol'; +import '@chainlink/contracts/src/v0.8/ChainSpecificUtil.sol'; ``` -## Local Development +## Foundry + +Chainlink supports Foundry testing for Solidity for its available products. Any new products or tests should only use Foundry +in the future. + +### Installation + +Please see the [official docs](https://book.getfoundry.sh/getting-started/installation) for the latest installation guide + +The foundry version used by the project may be different than your locally installed version, which +can result in different test results, so a series of alias commands with `GNUMakefile` is offered to help ensure the correct version is available. Please ensure your system supports makefiles before running them. -Note: Contracts in `dev/` directories are under active development and are likely unaudited. Please refrain from using these in production applications. +Depending on your foundry-profile, you may need to install external dependencies from libraries such as Openzeppelin. +This can be done efficiently with `pnpm` as well ```bash # Clone Chainlink repository $ git clone https://github.com/smartcontractkit/chainlink.git -# Continuing via pnpm -$ cd contracts/ -$ pnpm -$ pnpm test +$ cd chainlink/contracts/ +# Download and install the correct foundry version. +$ make foundry +# Download external dependencies +$ pnpm i +# Compile and run all tests using the default profile. +$ forge test +``` + + +### CI + +The Foundry CI will build, run tests and check the gas usage of all test functions against the version controlled `.gas-snapshot` file. +This snapshot should always be up-to-date and can be generated by running `make snapshot`. This will create a snapshot file in the current working dir, please make sure that you are in the root `chainlink/contracts` directory. + +We do not track the gas results of fuzz-tests as to not introduce too much variability in the snapshot file between executions. Using `forge snapshot` is therefore not encouraged, as it will record the gas metered results of these-fuzz tests, which may not reproducible exactly by the CI. If you wish to view the results of these fuzz tests, we recommend using normal `forge test` instead. + +```bash +$ make snapshot # Run the test files without fuzz tests and record results. +$ forge test # Run all tests, including fuzz. +``` + +### Configuration + +Foundry config lives in `foundry.toml` in the root, the docs can be found [here](https://book.getfoundry.sh/config/). +The remapping of libraries, both from Foundry and NPM packages, is done in `remapping.txt`. + +### Profiles + +Different Chainlink projects are organized by folder and unique [Foundry Profiles](https://book.getfoundry.sh/reference/config/overview?highlight=profiles#profiles). +Setting a profile can be used to restrict the compiler to specific files, reducing compilation time significantly. We +recommend configuring this by setting your `FOUNDRY_PROFILE` environment variable to the profile which best fits your need. + +```bash +$ export FOUNDRY_PROFILE=ccip # Set the profile to only apply only to CCIP specific contracts. ``` +The complete list of profiles and their associated tests can be found in the `foundry.toml` file. + ## Contributing Please try to adhere to [Solidity Style Guide](https://github.com/smartcontractkit/chainlink/blob/develop/contracts/STYLE.md). diff --git a/contracts/foundry.md b/contracts/foundry.md deleted file mode 100644 index 4795741e2dd..00000000000 --- a/contracts/foundry.md +++ /dev/null @@ -1,27 +0,0 @@ -## Foundry - -Chainlink supports Foundry testing for Solidity based on the Solidity version. - -- < 0.8.0 Hardhat tests only -- 0.8.x Hardhat and Foundry tests -- \> 0.9.0 Foundry tests only - -New projects should use Foundry but existing ones can keep using Hardhat if they want to; we will not be forcing any teams to rewrite their existing test suite. - -## Installation - -Please see the [official docs](https://book.getfoundry.sh/getting-started/installation) for the latest installation guide - -## CI - -The Foundry CI will build, run tests and check the gas usage of all test functions against the version controlled `.gas-snapshot` file. -This snapshot should always be up-to-date and can be generated by running `make snapshot`, and alias for `forge snapshot --match-test _gas`. -We only track gas for tests that have the `_gas` suffix as to not introduce too much noise in the snapshot file. -This will create a snapshot file in the current working dir, please make sure that you are in the root `chainlink` directory. - -## Configuration - -Foundry config lives in `foundry.toml` in the root, the docs can be found [here](https://book.getfoundry.sh/config/). -The remapping of libraries, both from Foundry and NPM packages, is done in `remapping.txt`. - - From 336ecd08e69e5e2620554d25fe2e2a2ba3d2326d Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 10 Dec 2024 10:04:32 -0500 Subject: [PATCH 2/3] remove unnec. CI stuff --- contracts/README.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/contracts/README.md b/contracts/README.md index b440d67f4fe..c98d46d7bb7 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -55,18 +55,7 @@ $ pnpm i $ forge test ``` - -### CI - -The Foundry CI will build, run tests and check the gas usage of all test functions against the version controlled `.gas-snapshot` file. -This snapshot should always be up-to-date and can be generated by running `make snapshot`. This will create a snapshot file in the current working dir, please make sure that you are in the root `chainlink/contracts` directory. - -We do not track the gas results of fuzz-tests as to not introduce too much variability in the snapshot file between executions. Using `forge snapshot` is therefore not encouraged, as it will record the gas metered results of these-fuzz tests, which may not reproducible exactly by the CI. If you wish to view the results of these fuzz tests, we recommend using normal `forge test` instead. - -```bash -$ make snapshot # Run the test files without fuzz tests and record results. -$ forge test # Run all tests, including fuzz. -``` +A complete guide on utilizing Foundry with this repository can be found in [FOUNDRY_GUIDE.md](./FOUNDRY_GUIDE.md) ### Configuration From 9faa4f294420c2084670f11c388ccdc86235bbcb Mon Sep 17 00:00:00 2001 From: Josh Weintraub <26035072+jhweintraub@users.noreply.github.com> Date: Tue, 10 Dec 2024 10:05:55 -0500 Subject: [PATCH 3/3] Update README.md remove reference to gas snapshot which isn't included in NPM release. --- contracts/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/contracts/README.md b/contracts/README.md index c98d46d7bb7..a06df68d7a1 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -17,7 +17,6 @@ $ npm install @chainlink/contracts --save │ └── v0.8 │── abi # ABI json output │ └── v0.8 -└── gas-snapshots # gas metered results of available non-fuzz tests ``` ### Usage @@ -106,4 +105,4 @@ An exception to this is the ccip folder, which defaults to be licensed under the - `src/v0.8/ccip/applications/*` is licensed under the [MIT](./src/v0.8/ccip/LICENSE-MIT.md) license - `src/v0.8/ccip/interfaces/*` is licensed under the [MIT](./src/v0.8/ccip/LICENSE-MIT.md) license -- `src/v0.8/ccip/libraries/{Client.sol, Internal.sol}` is licensed under the [MIT](./src/v0.8/ccip/LICENSE-MIT.md) license \ No newline at end of file +- `src/v0.8/ccip/libraries/{Client.sol, Internal.sol}` is licensed under the [MIT](./src/v0.8/ccip/LICENSE-MIT.md) license