Foundry Chainlink Toolkit

The Foundry Chainlink toolkit allows users to seamlessly interact with Chainlink services in their Foundry-based projects. It provides atomic methods to interact with smart contracts related to Chainlink services: Data Feeds, VRF, Automation and Functions. This plugin offers a convenient way to integrate Chainlink functionality into your web3 development workflow.

Warning

This package is currently in the BETA testing phase and is not recommended for production usage yet.

Open issues to submit bugs.

Installation

Note
If you are starting a new Foundry project, we recommend following the Foundry Installation and Foundry Getting Started documentation first.

The Foundry Chainlink toolkit has been designed so that it can be installed as a Forge dependency.

To integrate it into your project, you need to run the following command:

forge install smartcontractkit/foundry-chainlink-toolkit

Usage

The Foundry Chainlink plugin offers multiple ways to interact with Chainlink services, giving you the flexibility to choose the approach that suits your workflow best.

Note
Due to complex nature of embedded Solidity Scripts, compilation pipeline set to go through the new IR optimizer. This is done to avoid stack too deep errors.
Please consider setting via_ir flag to true in your foundry.toml file.

1. Solidity Scripts

Interact with the Foundry Chainlink plugin using embedded Solidity Scripts:

import {Script} from "forge-std/Script.sol";
import "foundry-chainlink-toolkit/script/feeds/DataFeed.s.sol";

contract MyContract is Script {
  constructor() public {
    // Initialize a contract
  }

  function getLatestPrice(address dataFeedAddress) public returns (int256 latestPrice){
    DataFeedsScript automationScript = new DataFeedsScript(dataFeedAddress);

    vm.broadcast();
    (,latestPrice,,,) = DataFeedsScript.getLatestRoundData();
    return latestPrice;
  }
}

Note
Foundry Solidity Scripting and Foundry EVM have limitations on passing context to nested scripts. That's why it is necessary to broadcast signer before each call to Foundry Chainlink plugin.

2. CLI

Interact with the Foundry Chainlink plugin via CLI. For this purpose, special scripts have been prepared that allow user to use service methods in one call, initializing a script and invoking a method, e.g.:

import {Script} from "forge-std/Script.sol";
import "foundry-chainlink-toolkit/script/feeds/DataFeed.s.sol";

contract DataFeedsCLIScript is BaseScript {
  function getLatestRoundData(address dataFeedAddress) external returns(uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound){
    DataFeedsScript dataFeedScript = new DataFeedsScript(dataFeedAddress);
    return dataFeedScript.getLatestRoundData();
  }
}

It makes possible calling the script from the command line:

forge foundry-chainlink-toolkit/script/feeds/DataFeed.CLI.s.sol --sig "getLatestRoundData(address)" $$dataFeedAddress

Examples of shell scripts invoking Chainlink services can be found in the Make file makefile-external.

Note
In order to run scripts properly, RPC node url and signer private key should be set either in the foundry.toml or through the forge CLI parameters

Registries

The Foundry Chainlink toolkit provides registries that contain information about smart contracts related to various Chainlink services and other data. You can find them in the registries directory.
"In order to use it in your Solidity scripts, please utilize the Foundry Cheatcode to parse JSON files.

Sandbox

Note Install GNU make following the Make documentation. Install and run Docker; for convenience, the Chainlink nodes run in a container. Instructions: docs.docker.com/get-docker.

The sandbox module of Hardhat Chainlink plugin provides the ability to test dApps against Chainlink services locally. The functionality of the sandbox is wrapped in the sandbox makefile.

Configure your project

1. Give Forge permission to read the output directory of the plugin by adding this setting to the foundry.toml:

fs_permissions = [{ access = "read", path = "lib/foundry-chainlink-toolkit/out"}]

Note
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-sandbox into your project. To do this, create or update a makefile in the root of your project with:

-include ${FCT_PLUGIN_PATH}/makefile-sandbox

Configure RPC node

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

For more information on this command, see the sandbox documentation.

Note
If a local blockchain network has been restarted, you should run a clean restart of a Chainlink cluster to avoid possible synchronization errors.

Set up environment variables

Based on the env.template - 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.

Below are comments on some environment variables:

• FCT_PLUGIN_PATH - path to the Foundry Chainlink toolkit root directory
• 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, more on it: https://docs.docker.com/compose/environment-variables/envvars/#compose_project_name

Note
If any environment variable related to a running Chainlink node was changed, e.g. Link Token contract address, you should run the make fct-run-nodes command in order to apply it.

Manage local Chainlink node

Once local Chainlink node parameters are specified, Chainlink node could be started/restarted/stopped and managed with the plugin following the sandbox documentation. In order to login use credentials specified in chainlink_api_credentials.

Alternatively, you can manage a Chainlink node either with Chainlink CLI or Chainlink node GUI.

Chainlink CLI

Chainlink node CLI is available directly on a machine running Chainlink node, so first you have to connect with bash to a Docker container to be able to run commands.

Here are some of the things you can do with the CLI:

• Create/Delete Chainlink Jobs
• Manage Chainlink accounts' transactions
• Manage Chainlink External Initiators
• See/Create Chainlink node's keys: ETH, OCR, P2P
• and more...

Here is example command to get list of ETH keys that are used by a Chainlink node:

chainlink keys eth list 

The most useful commands to manage Chainlink node with CLI you can find here: https://docs.chain.link/chainlink-nodes/resources/miscellaneous.

Chainlink GUI

Ports on which Chainlink GUIs are available are described in the snadbox documentation, these ports are exposed with a docker-compose file to a host machine.

Here are some of the things you can do with the GUI:

• Create/Delete Chainlink Jobs
• Create Chainlink Bridge
• See Chainlink Jobs runs
• See Chainlink node's keys: ETH, OCR, P2P, VRF
• See Chainlink node's current configuration
• and more...

Documentation

For detailed usage instructions and more information, refer to:

• DOCUMENTATION.md for interaction with Chainlink services;
• SANDBOX.md for local testing in Sandbox.

Contribution

We welcome contributions from the community.

If you find any issues, have suggestions for improvements, or want to add new features to the plugin, please don't hesitate to open an issue or submit a pull request.

Your contributions help us improve the Foundry Chainlink toolkit and provide better tools for the entire community.

Note
Foundry-Chainlink toolkit intended to support different compiler versions in range [>=0.6.2 <0.9.0].
It was tested e2e with these solc versions:

• 0.6.2
• 0.6.12
• 0.7.6
• 0.8.9
• 0.8.19

Therefore, you can specify any supported Solidity compiler version in your foundry.toml.
In case you find any problems you are welcome to open an issue.