Overview
This toolkit makes spinning up, managing, and testing smart contracts and local Chainlink nodes easier using Foundry to deploy and test smart contracts. It can be integrated into existing Foundry projects.
Objective
This project shows you how to install and run the simplify the development and testing of smart contracts that use Chainlink oracles. This project is aimed primarily at those who use the Foundry toolchain.
Before you begin
-
Install Foundry toolchain. Reference the below commands or go to the Foundry documentation.
-
MacOS/Linux
curl -L https://foundry.paradigm.xyz | bashThis will download foundryup. Restart your terminal session, then install Foundry by running:
foundryupYou might see the following error on MacOS:
dyld: Library not loaded: /usr/local/opt/libusb/lib/libusb-1.0.0.dylibTo fix this, install libusb:brew install libusbSee installation troubleshooting for details.
-
-
Install GNU make. The functionality of the project is wrapped in the makefile. Reference the below commands based on your OS or go to Make documentation.
-
MacOS: install Homebrew first, then run
brew install make -
Debian/Ubuntu
apt install make -
Fedora/RHEL
yum install make
-
-
Integrate the toolkit into your project. The Foundry-Chainlink toolkit is designed to be installed as a Forge dependency:
forge install smartcontractkit/foundry-chainlink-toolkit --no-commit -
Install the Forge Standard Library in your project:
forge install foundry-rs/forge-std -
If you need to run this toolkit as a demo standalone application, install the dependencies:
git submodule update
Steps to implement
1 Set up environment variables
Use the env.template file, create or update an .env file in the root directory of your project.
In most cases, you will not need to modify the default values specified in this file.
The following environment variables are available:
FCT_PLUGIN_PATH- path to the Foundry-Chainlink toolkit rootETH_URL- RPC node web socket used by the Chainlink nodeRPC_URL- RPC node http endpoint used by ForgePRIVATE_KEY- private key of an account used for deployment and interaction with smart contracts. Once Anvil is started, a set of private keys for local usage is provided. Use one of these for local developmentROOT- root directory of the Chainlink nodeCHAINLINK_CONTAINER_NAME- Chainlink node container name for the possibility of automating communication with itCOMPOSE_PROJECT_NAME- Docker network project name for the possibility of automating communication with it. See the Docker Documentation to learn more. If environment variables related to a Chainlink node, including a Link Token contract address, were changed during your work you should run themake fct-run-nodescommand in order for them to be applied.
-
Give Forge permission to read the output directory of the toolkit by adding this setting to the foundry.toml:
fs_permissions = [{ access = "read", path = "lib/foundry-chainlink-toolkit/out"}]The default path to the root of the Foundry-Chainlink toolkit is
lib/foundry-chainlink-toolkit. Unfortunately at the momentfoundry.tomlcannot read all environment variables. Specify a different path if necessary. -
Incorporate the makefile-external into your project. To do this, create or update a makefile in the root of your project with:
-include ${FCT_PLUGIN_PATH}/makefile-external
2 Set up chain RPC node
In order for a Chainlink node to be able to interact with the blockchain, and to interact with the blockchain using the Forge, you have to know an RPC node http endpoint and web socket for a chosen network compatible with Chainlink. In addition to the networks listed in this list, Chainlink is compatible with any EVM-compatible networks.
For local testing, we recommend using Anvil, which is a part of the Foundry toolchain.
You can run it using the following command:
make fct-anvil
If the local Ethereum node is restarted, re-initialize the Chainlink cluster or perform a clean spin-up of the Chainlink nodes to avoid possible synchronization errors.
3 Run the example
Scripts for automating the initialization of the test environment and setting up Chainlink jobs will be described below.
To display autogenerated help with a brief description of the most commonly used scripts, run:
make fct-help
For a more detailed description of the available scripts, you can refer to DOCUMENTATION.md in the repository.
4 Initialize testing environment
make fct-init
This command automatically initializes the test environment, in particular, it makes clean spin-up of a Chainlink cluster of 5 Chainlink nodes.
Once Chainlink cluster is launched, a Chainlink nodes' Operator GUI will be available at:
- http://127.0.0.1:6711 - Chainlink node 1
- http://127.0.0.1:6722 - Chainlink node 2
- http://127.0.0.1:6733 - Chainlink node 3
- http://127.0.0.1:6744 - Chainlink node 4
- http://127.0.0.1:6755 - Chainlink node 5
For authorization, you must use the credentials specified in the chainlink_api_credentials.
5 Set up Chainlink Jobs
make fct-setup-job
This command displays a list of available Chainlink jobs and sets up the selected one.
You can also set up a Chainlink job by calling the respective command. Manual set up of a Chainlink Job is recommended when using a custom Consumer or Aggregator contract, or when a different job configuration is desired. You can create a custom TOML file and use it to create a Chainlink Job instance through the Operator GUI or develop a custom script using the existing scripts provided by this toolkit. Manual setup steps are documented repository for each job type.
Direct Request Job
make fct-setup-direct-request-job
This command automatically sets up a Direct Request job.
Cron Job
make fct-setup-cron-job
This command automatically sets up a Cron job.
Webhook Job
make fct-setup-webhook-job
This command automatically sets up a Webhook job.
Keeper Job
make fct-setup-keeper-job
This command automatically sets up a Keeper job.
OCR Job
make fct-setup-ocr-job
This command automatically sets up an OCR job.
Project Structure
You can find the full project structure in the repository.