Back to QuickStarts

Foundry Chainlink Toolkit

Test smart contracts and local Chainlink nodes using Foundry.

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

  1. Install Foundry toolchain. Reference the below commands or go to the Foundry documentation.

    • MacOS/Linux

      curl -L https://foundry.paradigm.xyz | bash

      This will download foundryup. Restart your terminal session, then install Foundry by running:

      foundryup

      You might see the following error on MacOS: dyld: Library not loaded: /usr/local/opt/libusb/lib/libusb-1.0.0.dylib To fix this, install libusb: brew install libusb See installation troubleshooting for details.

  2. 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

  3. Install and run Docker.

  4. 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

  5. Install the Forge Standard Library in your project:

    forge install foundry-rs/forge-std

  6. 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 root
  • ETH_URL - RPC node web socket used by the Chainlink node
  • RPC_URL - RPC node http endpoint used by Forge
  • PRIVATE_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 development
  • ROOT - root directory of the Chainlink node
  • CHAINLINK_CONTAINER_NAME - Chainlink node container name for the possibility of automating communication with it
  • COMPOSE_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 the make fct-run-nodes command in order for them to be applied.

  1. 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 moment foundry.toml cannot read all environment variables. Specify a different path if necessary.

  2. 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:

For authorization, you must use the credentials specified in the chainlink_api_credentials.

Project Structure

You can find the full project structure in the repository.

Get the latest Chainlink content straight to your inbox.