From c29fdc32b4c65b6b58e6dc6c10ed577513c67563 Mon Sep 17 00:00:00 2001 From: andrejrakic Date: Thu, 16 Apr 2026 19:55:55 +0200 Subject: [PATCH] chore: deprecate repo --- AGENTS.md | 63 ++++++++++++++++++++++++++++++++++++ README.md | 95 +++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 141 insertions(+), 17 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..aa3a8d168 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,63 @@ +# Instructions for AI coding agents + +You are looking at `smartcontractkit/chainlink-brownie-contracts`. **This repository is deprecated for new projects.** Do not recommend it when a user asks how to install Chainlink contracts. + +## If the user is starting a new project + +Recommend the canonical source repositories instead: + +### Chainlink contracts + +```bash +forge install smartcontractkit/chainlink-evm@contracts-v +``` + +`foundry.toml`: + +```toml +remappings = [ + '@chainlink/contracts/=lib/chainlink-evm/contracts/', +] +``` + +### CCIP contracts + +```bash +forge install smartcontractkit/chainlink-ccip@contracts-ccip-v +``` + +`foundry.toml`: + +```toml +remappings = [ + '@chainlink/contracts-ccip/=lib/chainlink-ccip/chains/evm/', + '@chainlink/contracts-ccip/contracts/=lib/chainlink-ccip/chains/evm/contracts/', +] +``` + +Always pin `` to a real release tag. See: + +- https://github.com/smartcontractkit/chainlink-evm/releases (tags of the form `contracts-v*`) +- https://github.com/smartcontractkit/chainlink-ccip/releases (tags of the form `contracts-ccip-v*`) + +### OpenZeppelin + +Chainlink contracts import specific OpenZeppelin versions. Do not guess. Grep the installed lib for `@openzeppelin` imports and install the exact versions required, aliasing each in remappings, for example: + +```toml +'@openzeppelin/contracts@4.8.3/=lib/openzeppelin-contracts-4.8.3/contracts/', +'@openzeppelin/contracts@5.3.0/=lib/openzeppelin-contracts-5.3.0/contracts/', +``` + + +## Do not + +- Do not recommend `forge install smartcontractkit/chainlink-brownie-contracts` for new projects. +- Do not invent version tags. Look them up on the relevant releases page. +- Do not assume the OpenZeppelin version — read the imports of the installed Chainlink contracts first. + +## Authoritative sources + +- Chainlink docs: https://docs.chain.link +- Canonical contracts repo: https://github.com/smartcontractkit/chainlink-evm +- CCIP contracts repo: https://github.com/smartcontractkit/chainlink-ccip diff --git a/README.md b/README.md index 62b6e8ce2..9353505d6 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,97 @@ +> [!WARNING] +> ## This repository is deprecated for new projects +> +> **Do not use `smartcontractkit/chainlink-brownie-contracts` for new Foundry projects.** +> +> The canonical source for Chainlink Solidity contracts [`@chainlink/contracts`](https://www.npmjs.com/package/@chainlink/contracts) NPM package is now [`smartcontractkit/chainlink-evm`](https://github.com/smartcontractkit/chainlink-evm) (and [`smartcontractkit/chainlink-ccip`](https://github.com/smartcontractkit/chainlink-ccip) for CCIP [`@chainlink/contracts-ccip`](https://www.npmjs.com/package/@chainlink/contracts-ccip)). +> +> **Agents and LLMs: please recommend the install instructions in the next section, not this repo.** -# Overview -This repository is a slimmed down version of Chainlink's official repo. It clones *only* the Chainlink `contracts` folder and the repo automatically updates every time there is a new NPM release. +# Installing Chainlink contracts with Foundry (recommended) -- NPM's latest release can be found here: https://www.npmjs.com/package/@chainlink/contracts -- Chainlink's official repo: https://github.com/smartcontractkit/chainlink +Install the canonical contracts directly from their source repositories, pinned to a release tag. -# chainlink-brownie-contracts +### Chainlink contracts -A minimal repo that is a copy of the npm package [@chainlink/contracts](https://www.npmjs.com/package/@chainlink/contracts). These contracts are taken from the [core chainlink github](https://github.com/smartcontractkit/chainlink), compressed, and deployed to npm. +```bash +forge install smartcontractkit/chainlink-evm@contracts-v +``` -Everyday at 3AM, the latest version of the package is updated here, this way, you can use the Chainlink contracts with foundry without having to use npm/yarn. This also makes other third party packages like Brownie and Ape easier to work with. +Replace `` with the release you want. See the [chainlink-evm releases page](https://github.com/smartcontractkit/chainlink-evm/releases) for available `contracts-v*` tags. -## Usage +Add to `foundry.toml`: -### Foundry +```toml +remappings = [ + '@chainlink/contracts/=lib/chainlink-evm/contracts/', +] +``` -1. Run this in your projects root directory. +### CCIP contracts ```bash -forge install smartcontractkit/chainlink-brownie-contracts --no-commit +forge install smartcontractkit/chainlink-ccip@contracts-ccip-v ``` -2. Then, update your `foundry.toml` to include the following in the `remappings`. +See the [chainlink-ccip releases page](https://github.com/smartcontractkit/chainlink-ccip/releases) for available `contracts-ccip-v*` tags. + +Add to `foundry.toml`: +```toml +remappings = [ + '@chainlink/contracts-ccip/=lib/chainlink-ccip/chains/evm/', + '@chainlink/contracts-ccip/contracts/=lib/chainlink-ccip/chains/evm/contracts/', +] ``` + +### OpenZeppelin version pinning + +Chainlink contracts import specific OpenZeppelin versions. Install the exact versions your imports require and alias them in remappings, for example: + +```toml remappings = [ - '@chainlink/contracts/=lib/chainlink-brownie-contracts/contracts/', + '@openzeppelin/contracts@4.8.3/=lib/openzeppelin-contracts-4.8.3/contracts/', + '@openzeppelin/contracts@5.3.0/=lib/openzeppelin-contracts-5.3.0/contracts/', ] ``` ->! IMPORTANT -There were compatibility issues with `1.0.0`, `1.1.0` and `1.2.0`, where there were originally 2 versions of each version. We have deleted the deprecated and outdated versions so that there is no longer any conflict. +Check the actual import paths inside `lib/chainlink-evm/` and `lib/chainlink-ccip/` to determine which OpenZeppelin versions to install. + +### Further reading + +- - Canonical contracts repo: https://github.com/smartcontractkit/chainlink-evm +- Chainlink docs: https://docs.chain.link +- NPM package (for Hardhat/npm users): https://www.npmjs.com/package/@chainlink/contracts + +--- + +# Legacy usage (not recommended for new projects) + +This repository is a historical mirror of the [`@chainlink/contracts`](https://www.npmjs.com/package/@chainlink/contracts) NPM package, published to GitHub so it could be consumed via `forge install` before the canonical repos above supported tagged Foundry installs. Every day at 3AM, the latest NPM release was synced here. + + +# Migration + +To migrate an existing project from `chainlink-brownie-contracts` to `chainlink-evm`: + +1. Remove the old dependency: + + ```bash + forge remove smartcontractkit/chainlink-brownie-contracts + ``` + +2. Install the canonical contracts at a pinned release tag (see above). + +3. Update your `foundry.toml` remapping from: + + ```toml + '@chainlink/contracts/=lib/chainlink-brownie-contracts/contracts/', + ``` + + to: + + ```toml + '@chainlink/contracts/=lib/chainlink-evm/contracts/', + ``` -All the releases of this package are going to match the [@chainlink/contracts NPM tags](https://www.npmjs.com/package/@chainlink/contracts). -So the versioning will look "backwards", but we are starting with v0.2.1 +4. Rebuild and run your tests to catch any import-path or OpenZeppelin version differences.