From 4f33806de44a472ade6e40435f6d016e80d94db1 Mon Sep 17 00:00:00 2001 From: nje <8985830+Nalon@users.noreply.github.com> Date: Sun, 28 Sep 2025 17:17:03 -0700 Subject: [PATCH 1/4] Updated README for v1.5.0 Updated instructions for v1.5.0. v1.5.0 unvendors a number of contracts, which require the use of remappings to resolve import paths of package dependencies. Included instructions and information to support this. - Foundry - Hardhat 3 - Hardhat 2 - Remix - Supporting information --- contracts/README.md | 202 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 172 insertions(+), 30 deletions(-) diff --git a/contracts/README.md b/contracts/README.md index 48968f6dab..aff2324af5 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,25 +1,145 @@ # Chainlink Smart Contracts -> [!IMPORTANT] -> Since v1.4.0 of the Chainlink contracts, the contracts have been moved to their own repository: -> [chainlink-evm](https://github.com/smartcontractkit/chainlink-evm). +> [!IMPORTANT] +> Since `v1.5.0` of the Chainlink contracts package, some dependencies are no longer vendored and require the setup of remappings. +> See the setup instructions for use in Solidity projects. +> +> Since `v1.4.0` of the Chainlink contracts, the contracts have been moved to their own repository: +> [chainlink-evm](https://github.com/smartcontractkit/chainlink-evm). > Prior to that, the contracts were part of the [main Chainlink repository](https://github.com/smartcontractkit/chainlink) +## Table of Contents + +- [Installation](#installation) +- [Setup](#setup) + - [Foundry](#foundry) + - [Hardhat 3](#hardhat-3) + - [Hardhat 2](#hardhat-2) + - [Remix](#remix) +- [Package Directory Structure](#package-directory-structure) +- [Usage](#usage) +- [Local Development](#local-development) +- [Contributing](#contributing) + - [Changesets](#changesets) + + ## Installation -#### Foundry (git) +> [!WARNING] +> For use in Solidity project(s), see the setup instructions below. + +```sh +# pnpm +$ pnpm add @chainlink/contracts +``` + +```sh +# npm +$ npm install @chainlink/contracts --save +``` + +## Setup + +For use in Solidity projects, further configuration is required. + +This package relies on [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) to resolve import paths within your Solidity project(s). Each tool may handle [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) in a different manner. In the sections below, you will find detailed instructions on this process for popular tools. + +Refer to the [Solidity remapping documentation](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) for more information. + +
+Foundry + +### Step 1: Install the package + +For use in your Foundry project, it is recommended to utilize `npm` or `pnpm` as your package manager for the use of this package instead of `forge install`. + +```sh +# pnpm +$ pnpm add @chainlink/contracts +``` + +```sh +# npm +$ npm install @chainlink/contracts --save +``` + +If you wish to utilize `forge install`, please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). + +### Step 2: Define the external library directory + +As we are using `npm`/`pnpm` as our package manager, define `node_modules` as an external library directory. This ensures Foundry recognizes dependencies installed via `npm`/`pnpm`. + +In your project's `foundry.toml`, update the libs array to include the `node_modules` directory. + +``` +libs = ["lib", "node_modules"] +``` + +### Step 3: Setup remappings + +Setup your project's remappings. See the [Foundry documentation](https://getfoundry.sh/guides/project-setup/dependencies#remapping-dependencies) for more information. + +[Foundry](https://getfoundry.sh/guides/project-setup/project-layout#project-layout) consumes a `remappings.txt` file from the project root. Create or update `remappings.txt` with the following: + +``` +@chainlink/=node_modules/@chainlink +@openzeppelin/contracts@4.7.3=node_modules/@openzeppelin/contracts-4.7.3 +@openzeppelin/contracts@4.8.3=node_modules/@openzeppelin/contracts-4.8.3 +@openzeppelin/contracts@4.9.6=node_modules/@openzeppelin/contracts-4.9.6 +@openzeppelin/contracts@5.0.2=node_modules/@openzeppelin/contracts-5.0.2 +@openzeppelin/contracts@5.1.0=node_modules/@openzeppelin/contracts-5.1.0 +@openzeppelin/contracts-upgradeable/=node_modules/@openzeppelin/contracts-upgradeable/ +@arbitrum/=node_modules/@arbitrum/ +@eth-optimism/=node_modules/@eth-optimism/ +@scroll-tech/=node_modules/@scroll-tech/ +@zksync/=node_modules/@zksync/ +``` + +If your compilation reports unresolved imports from dependencies, add the corresponding additional remappings to `remappings.txt` (the format is `=/`). + +### Step 4: Usage -> [!WARNING] -> When installing via git, the ref defaults to master when no tag is given. +```solidity +import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; +``` + +See the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit) for working examples. + +
+ +
+Hardhat 3 +### Step 1: Install the package ```sh -$ forge install smartcontractkit/chainlink-evm@ +# pnpm +$ pnpm add @chainlink/contracts ``` -Add `@chainlink/contracts/=lib/smartcontractkit/chainlink-evm/contracts/` in remappings.txt. +```sh +# npm +$ npm install @chainlink/contracts --save +``` + +Hardhat 3 supports `remappings.txt` files in your project, as well as in git submodules and npm dependencies. Each `remappings.txt` file applies to the directory where it's located and all its subdirectories, similar to how .gitignore works. Hardhat 3 will utilize the `remappings.txt` file located within the root directory of the Chainlink contracts package. + +### Step 2: Usage + +```solidity +import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; +``` + +See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/) for working examples. + +
+ + +
+Hardhat 2 + +### Step 1: Install the package -#### NPM ```sh # pnpm $ pnpm add @chainlink/contracts @@ -30,40 +150,63 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -Add `@chainlink/contracts/=node_modules/@chainlink/contracts/` in remappings.txt. +### Step 2: Setup remappings +Hardhat 2 does not read `remappings.txt` natively as seen in Foundry/Hardhat 3. To remap import paths, you may use a preprocessor that handles this at compile time. To see remapping examples in Hardhat 2, review the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/). +### Step 3: Usage -### Directory Structure +```solidity +import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; +``` + +
+ + +
+Remix + +Remix works out of the box and requires no additional setup or installation. The imported dependencies will be automatically installed. + +```solidity +import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; +``` + +
+ + +## Package Directory Structure + +> [!IMPORTANT] +> Since v1.5.0 of the Chainlink contracts, ABI files have been reorganized into subdirectories. +> Additionally, ABI files now follow a slightly updated naming scheme. ```sh @chainlink/contracts ├── src # Solidity contracts │ └── v0.8 -└── abi # ABI json output +└── abi # ABI JSON output └── v0.8 ``` -### Usage +## Usage -The solidity smart contracts themselves can be imported via the `src` directory of `@chainlink/contracts`: +The Solidity smart contracts themselves can be imported via the `src` directory of `@chainlink/contracts`: -```solidity -import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; +``` +@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol ``` -### Remapping +The ABI files themselves can be imported via the `abi` directory of `@chainlink/contracts`: -This repository uses [Solidity remappings](https://docs.soliditylang.org/en/v0.8.20/using-the-compiler.html#compiler-remapping) to resolve imports. -The remapping is defined in the `remappings.txt` file. +``` +@chainlink/contracts/abi/v0.8/VRF/VRFCoordinatorV2_5.abi.json +``` ## Local Development -Note: -Contracts in `dev/` directories or with a typeAndVersion ending in `-dev` are under active development -and are likely unaudited. -Please refrain from using these in production applications. +**Note:** Contracts in `dev/` directories or with a typeAndVersion ending in `-dev` are under active development and are likely unaudited. Please refrain from using these in production applications. ```bash # Clone Chainlink repository @@ -72,8 +215,7 @@ $ cd contracts/ $ pnpm ``` -Each Chainlink project has its own directory under `src/` which can be targeted using Foundry profiles. -To test a specific project, run: +Each Chainlink project has its own directory under `src/` which can be targeted using Foundry profiles. To test a specific project, run: ```bash # Replace with the product you want to test @@ -81,7 +223,7 @@ export FOUNDRY_PROFILE= forge test ``` -To test the llo-feeds (data steams) project: +To test the llo-feeds (data streams) project: ```bash export FOUNDRY_PROFILE=llo-feeds @@ -102,15 +244,15 @@ Thank you! We use [changesets](https://github.com/changesets/changesets) to manage versioning the contracts. -Every PR that modifies any configuration or code, should most likely accompanied by a changeset file. +Every PR that modifies any configuration or code should most likely be accompanied by a changeset file. To install `changesets`: - 1. Install `pnpm` if it is not already installed - [docs](https://pnpm.io/installation). - 2. Run `pnpm install`. + +1. Install `pnpm` if it is not already installed - [docs](https://pnpm.io/installation). +2. Run `pnpm install`. Either after or before you create a commit, run the `pnpm changeset` command in the `contracts` directory to create an accompanying changeset entry which will reflect on the CHANGELOG for the next release. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - From c07a71bf0c26b608e20fd1bc934e70431a9e0ef3 Mon Sep 17 00:00:00 2001 From: Zubin Pratap Date: Mon, 29 Sep 2025 12:23:25 +1000 Subject: [PATCH 2/4] Minor updates to README. Update ToC --- contracts/README.md | 78 ++++++++++++++++++++++++--------------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/contracts/README.md b/contracts/README.md index aff2324af5..d38a2bdc5e 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,6 +1,6 @@ # Chainlink Smart Contracts -> [!IMPORTANT] +> [⚠️ __IMPORTANT__] > Since `v1.5.0` of the Chainlink contracts package, some dependencies are no longer vendored and require the setup of remappings. > See the setup instructions for use in Solidity projects. > @@ -10,22 +10,22 @@ ## Table of Contents -- [Installation](#installation) -- [Setup](#setup) - - [Foundry](#foundry) - - [Hardhat 3](#hardhat-3) +- [NPM Quick Install](#npm-quick-install) +- [Setup & Installation](#setup--installation) + - [Foundry & Forge](#foundry) - [Hardhat 2](#hardhat-2) + - [Hardhat 3](#hardhat-3) - [Remix](#remix) - [Package Directory Structure](#package-directory-structure) -- [Usage](#usage) + - [Usage](#usage) - [Local Development](#local-development) - [Contributing](#contributing) - [Changesets](#changesets) +// ...existing code... +## NPM Quick Install -## Installation - -> [!WARNING] +> [⚠️ __NOTE__ ] > For use in Solidity project(s), see the setup instructions below. ```sh @@ -38,16 +38,17 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -## Setup +## Setup & Installation For use in Solidity projects, further configuration is required. -This package relies on [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) to resolve import paths within your Solidity project(s). Each tool may handle [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) in a different manner. In the sections below, you will find detailed instructions on this process for popular tools. +This package relies on Solidity [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) to resolve import paths within your Solidity project(s). Each tool may handle [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) in a different manner. + +In the sections below, you will find detailed instructions on this process for supported tools. -Refer to the [Solidity remapping documentation](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) for more information.
-Foundry +Foundry & Forge ### Step 1: Install the package @@ -63,11 +64,14 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -If you wish to utilize `forge install`, please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). +#### If you don't want to use NPM... +If you wish to utilize `forge install`, you will need to install this package as a git submodule in your project, using its github url. This would put this package inside your Foundry Project's `./lib` folder. Please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). Note also the use of remappings.txt in the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). -### Step 2: Define the external library directory +Here is the [official guide book](https://getfoundry.sh/guides/project-setup/dependencies) on how to use Forge Install with Remappings. -As we are using `npm`/`pnpm` as our package manager, define `node_modules` as an external library directory. This ensures Foundry recognizes dependencies installed via `npm`/`pnpm`. +### Step 2: Tell Forge to Look inside `node_modules` + +As we are using `npm` as our package manager, we must define the `node_modules` folder as the external library directory. This ensures Foundry looks there for dependencies installed via `npm`/`pnpm`. In your project's `foundry.toml`, update the libs array to include the `node_modules` directory. @@ -79,7 +83,7 @@ libs = ["lib", "node_modules"] Setup your project's remappings. See the [Foundry documentation](https://getfoundry.sh/guides/project-setup/dependencies#remapping-dependencies) for more information. -[Foundry](https://getfoundry.sh/guides/project-setup/project-layout#project-layout) consumes a `remappings.txt` file from the project root. Create or update `remappings.txt` with the following: +[Foundry](https://getfoundry.sh/guides/project-setup/project-layout#project-layout) consumes a `remappings.txt` file from the project root. Create or update your project's `remappings.txt` with the following, to ensure that it loads the correct version of the dependencies you just installed into your `node_modules`: ``` @chainlink/=node_modules/@chainlink @@ -95,7 +99,6 @@ Setup your project's remappings. See the [Foundry documentation](https://getfoun @zksync/=node_modules/@zksync/ ``` -If your compilation reports unresolved imports from dependencies, add the corresponding additional remappings to `remappings.txt` (the format is `=/`). ### Step 4: Usage @@ -103,12 +106,18 @@ If your compilation reports unresolved imports from dependencies, add the corres import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; ``` +Run `forge compile` to test that everything compiles correctly. + +#### Troubleshooting unresolved imports +If your compilation reports unresolved imports from dependencies, add the corresponding additional remappings to `remappings.txt` (the format is `=/`). + See the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit) for working examples. +
-
-Hardhat 3 +
+Hardhat 2 ### Step 1: Install the package @@ -122,21 +131,20 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -Hardhat 3 supports `remappings.txt` files in your project, as well as in git submodules and npm dependencies. Each `remappings.txt` file applies to the directory where it's located and all its subdirectories, similar to how .gitignore works. Hardhat 3 will utilize the `remappings.txt` file located within the root directory of the Chainlink contracts package. +### Step 2: Setup remappings -### Step 2: Usage +Hardhat 2 does not read `remappings.txt` natively as seen in Foundry/Hardhat 3. To remap import paths, you may use a preprocessor that handles this at compile time. To see remapping examples in Hardhat 2, review the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/). + +### Step 3: Usage ```solidity import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; ``` -See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/) for working examples. -
- -
-Hardhat 2 +
+Hardhat 3 ### Step 1: Install the package @@ -150,16 +158,18 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -### Step 2: Setup remappings +Hardhat 3 supports `remappings.txt` files in your project, as well as in git submodules and npm dependencies. Each `remappings.txt` file applies to the directory where it's located and all its subdirectories, similar to how `.gitignore` works. -Hardhat 2 does not read `remappings.txt` natively as seen in Foundry/Hardhat 3. To remap import paths, you may use a preprocessor that handles this at compile time. To see remapping examples in Hardhat 2, review the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/). +Similar to Foundry, Hardhat 3 will utilize the `remappings.txt` file located within the root directory of this Chainlink contracts package. -### Step 3: Usage +### Step 2: Usage ```solidity import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; ``` +See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/) for working examples. +
@@ -189,13 +199,7 @@ import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfac └── v0.8 ``` -## Usage - -The Solidity smart contracts themselves can be imported via the `src` directory of `@chainlink/contracts`: - -``` -@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol -``` +#### Usage The ABI files themselves can be imported via the `abi` directory of `@chainlink/contracts`: From 9ce1d121f66bfeb58e9dc960572cb68d787bb1af Mon Sep 17 00:00:00 2001 From: nje <8985830+Nalon@users.noreply.github.com> Date: Mon, 29 Sep 2025 13:14:49 -0700 Subject: [PATCH 3/4] Updated HH starter kit information - Updated HH3 starter kit url to hardhat-3 branch - Updated link to remapping section of HH SK readme (HH2) - Added line for HH2 working examples for consistency - Minor phrasing changes --- contracts/README.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/contracts/README.md b/contracts/README.md index d38a2bdc5e..dd69ac5d5e 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,7 +1,7 @@ # Chainlink Smart Contracts > [⚠️ __IMPORTANT__] -> Since `v1.5.0` of the Chainlink contracts package, some dependencies are no longer vendored and require the setup of remappings. +> Since `v1.5.0` of the Chainlink contracts package, some dependencies are no longer vendored and require the use of remappings. > See the setup instructions for use in Solidity projects. > > Since `v1.4.0` of the Chainlink contracts, the contracts have been moved to their own repository: @@ -64,12 +64,13 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -#### If you don't want to use NPM... -If you wish to utilize `forge install`, you will need to install this package as a git submodule in your project, using its github url. This would put this package inside your Foundry Project's `./lib` folder. Please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). Note also the use of remappings.txt in the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). +#### If you don't want to use `npm`... -Here is the [official guide book](https://getfoundry.sh/guides/project-setup/dependencies) on how to use Forge Install with Remappings. +If you wish to utilize `forge install`, you will need to install this package as a Git submodule in your project, using its GitHub URL. This would put this package inside your Foundry project's `./lib` folder. Please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). Note also the use of `remappings.txt` in the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). -### Step 2: Tell Forge to Look inside `node_modules` +Here is the [official guidebook](https://getfoundry.sh/guides/project-setup/dependencies) on how to use `forge install` with remappings. + +### Step 2: Tell Forge to look in `node_modules` As we are using `npm` as our package manager, we must define the `node_modules` folder as the external library directory. This ensures Foundry looks there for dependencies installed via `npm`/`pnpm`. @@ -79,9 +80,9 @@ In your project's `foundry.toml`, update the libs array to include the `node_mod libs = ["lib", "node_modules"] ``` -### Step 3: Setup remappings +### Step 3: Set up remappings -Setup your project's remappings. See the [Foundry documentation](https://getfoundry.sh/guides/project-setup/dependencies#remapping-dependencies) for more information. +Set up your project's remappings. See the [Foundry documentation](https://getfoundry.sh/guides/project-setup/dependencies#remapping-dependencies) for more information. [Foundry](https://getfoundry.sh/guides/project-setup/project-layout#project-layout) consumes a `remappings.txt` file from the project root. Create or update your project's `remappings.txt` with the following, to ensure that it loads the correct version of the dependencies you just installed into your `node_modules`: @@ -131,9 +132,9 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -### Step 2: Setup remappings +### Step 2: Set up remappings -Hardhat 2 does not read `remappings.txt` natively as seen in Foundry/Hardhat 3. To remap import paths, you may use a preprocessor that handles this at compile time. To see remapping examples in Hardhat 2, review the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/). +Hardhat 2 does not handle remappings natively as seen in Foundry/Hardhat 3. To remap import paths, you may use a preprocessor that handles this at compile time. Refer to the remapping section of the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/?tab=readme-ov-file#remapping) for more information. ### Step 3: Usage @@ -141,6 +142,8 @@ Hardhat 2 does not read `remappings.txt` natively as seen in Foundry/Hardhat 3. import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; ``` +See the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/) for working examples. +
@@ -158,7 +161,7 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -Hardhat 3 supports `remappings.txt` files in your project, as well as in git submodules and npm dependencies. Each `remappings.txt` file applies to the directory where it's located and all its subdirectories, similar to how `.gitignore` works. +Hardhat 3 supports `remappings.txt` files in your project, as well as in Git submodules and npm dependencies. Each `remappings.txt` file applies to the directory where it's located and all its subdirectories, similar to how `.gitignore` works. Similar to Foundry, Hardhat 3 will utilize the `remappings.txt` file located within the root directory of this Chainlink contracts package. @@ -168,7 +171,7 @@ Similar to Foundry, Hardhat 3 will utilize the `remappings.txt` file located wit import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; ``` -See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/) for working examples. +See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/tree/hardhat-3) for working examples.
From c6d8a06cffee0d57033738eed6cbaa2344b9eb4e Mon Sep 17 00:00:00 2001 From: nje <8985830+Nalon@users.noreply.github.com> Date: Tue, 30 Sep 2025 12:29:58 -0700 Subject: [PATCH 4/4] Resolved feedback for #244 - Fixed markdown tags - Updated forge install text to reference forge starter kit - Removed libs step for foundry - Removed duplicate usage steps --- contracts/README.md | 58 ++++++++++----------------------------------- 1 file changed, 12 insertions(+), 46 deletions(-) diff --git a/contracts/README.md b/contracts/README.md index dd69ac5d5e..8893b9617a 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -1,6 +1,6 @@ # Chainlink Smart Contracts -> [⚠️ __IMPORTANT__] +> [!IMPORTANT] > Since `v1.5.0` of the Chainlink contracts package, some dependencies are no longer vendored and require the use of remappings. > See the setup instructions for use in Solidity projects. > @@ -21,11 +21,10 @@ - [Local Development](#local-development) - [Contributing](#contributing) - [Changesets](#changesets) -// ...existing code... - + ## NPM Quick Install -> [⚠️ __NOTE__ ] +> [!NOTE] > For use in Solidity project(s), see the setup instructions below. ```sh @@ -40,8 +39,6 @@ $ npm install @chainlink/contracts --save ## Setup & Installation -For use in Solidity projects, further configuration is required. - This package relies on Solidity [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) to resolve import paths within your Solidity project(s). Each tool may handle [remappings](https://docs.soliditylang.org/en/latest/path-resolution.html#import-remapping) in a different manner. In the sections below, you will find detailed instructions on this process for supported tools. @@ -64,23 +61,9 @@ $ pnpm add @chainlink/contracts $ npm install @chainlink/contracts --save ``` -#### If you don't want to use `npm`... - -If you wish to utilize `forge install`, you will need to install this package as a Git submodule in your project, using its GitHub URL. This would put this package inside your Foundry project's `./lib` folder. Please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). Note also the use of `remappings.txt` in the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit). - -Here is the [official guidebook](https://getfoundry.sh/guides/project-setup/dependencies) on how to use `forge install` with remappings. - -### Step 2: Tell Forge to look in `node_modules` - -As we are using `npm` as our package manager, we must define the `node_modules` folder as the external library directory. This ensures Foundry looks there for dependencies installed via `npm`/`pnpm`. - -In your project's `foundry.toml`, update the libs array to include the `node_modules` directory. - -``` -libs = ["lib", "node_modules"] -``` +If you wish to utilize `forge install`, please see the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit) for detailed information. -### Step 3: Set up remappings +### Step 2: Set up remappings Set up your project's remappings. See the [Foundry documentation](https://getfoundry.sh/guides/project-setup/dependencies#remapping-dependencies) for more information. @@ -100,13 +83,6 @@ Set up your project's remappings. See the [Foundry documentation](https://getfou @zksync/=node_modules/@zksync/ ``` - -### Step 4: Usage - -```solidity -import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; -``` - Run `forge compile` to test that everything compiles correctly. #### Troubleshooting unresolved imports @@ -114,7 +90,6 @@ If your compilation reports unresolved imports from dependencies, add the corres See the [Foundry starter kit](https://github.com/smartcontractkit/foundry-starter-kit) for working examples. -
@@ -136,12 +111,6 @@ $ npm install @chainlink/contracts --save Hardhat 2 does not handle remappings natively as seen in Foundry/Hardhat 3. To remap import paths, you may use a preprocessor that handles this at compile time. Refer to the remapping section of the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/?tab=readme-ov-file#remapping) for more information. -### Step 3: Usage - -```solidity -import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; -``` - See the [Hardhat 2 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/) for working examples.
@@ -165,12 +134,6 @@ Hardhat 3 supports `remappings.txt` files in your project, as well as in Git sub Similar to Foundry, Hardhat 3 will utilize the `remappings.txt` file located within the root directory of this Chainlink contracts package. -### Step 2: Usage - -```solidity -import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; -``` - See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-starter-kit/tree/hardhat-3) for working examples. @@ -181,10 +144,6 @@ See the [Hardhat 3 starter kit](https://github.com/smartcontractkit/hardhat-star Remix works out of the box and requires no additional setup or installation. The imported dependencies will be automatically installed. -```solidity -import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; -``` - @@ -204,6 +163,13 @@ import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfac #### Usage +The Solidity files themselves can be imported via the `src` directory of @chainlink/contracts: + +```solidity +import {IVerifier} from '@chainlink/contracts/src/v0.8/llo-feeds/v0.5.0/interfaces/IVerifier.sol'; +``` + + The ABI files themselves can be imported via the `abi` directory of `@chainlink/contracts`: ```