{"id":19107493,"url":"https://github.com/smartcontractkit/foundry-chainlink-toolkit","last_synced_at":"2025-04-30T18:46:37.615Z","repository":{"id":65947026,"uuid":"587344314","full_name":"smartcontractkit/foundry-chainlink-toolkit","owner":"smartcontractkit","description":"A plugin to spin up local Chainlink node with Foundry","archived":false,"fork":false,"pushed_at":"2024-01-16T19:04:17.000Z","size":30245,"stargazers_count":38,"open_issues_count":0,"forks_count":33,"subscribers_count":25,"default_branch":"main","last_synced_at":"2024-01-17T03:36:22.628Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smartcontractkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-01-10T14:35:35.000Z","updated_at":"2023-12-18T18:15:58.000Z","dependencies_parsed_at":"2023-03-10T19:23:46.684Z","dependency_job_id":"ed56e1ca-0adb-4083-974a-9bb989eacc43","html_url":"https://github.com/smartcontractkit/foundry-chainlink-toolkit","commit_stats":null,"previous_names":["smartcontractkit/foundry-chainlink-plugin"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Ffoundry-chainlink-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Ffoundry-chainlink-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Ffoundry-chainlink-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartcontractkit%2Ffoundry-chainlink-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartcontractkit","download_url":"https://codeload.github.com/smartcontractkit/foundry-chainlink-toolkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223783093,"owners_count":17201915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T04:12:47.717Z","updated_at":"2024-11-09T04:12:48.307Z","avatar_url":"https://github.com/smartcontractkit.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Foundry Chainlink Toolkit\n\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://chain.link\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/smartcontractkit/foundry-starter-kit/main/img/chainlink-foundry.png\" width=\"225\" alt=\"Chainlink Foundry logo\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n\nThe Foundry Chainlink toolkit allows users to seamlessly interact with Chainlink services in their Foundry-based projects.\nIt provides atomic methods to interact with smart contracts related to Chainlink services: Data Feeds, VRF, Automation and Functions.\nThis plugin offers a convenient way to integrate Chainlink functionality into your web3 development workflow.\n\n\u003e **Warning**\n\u003e\n\u003e **This package is currently in the BETA testing phase and is not recommended for production usage yet.**\n\u003e\n\u003e **Open issues to submit bugs.**\n\n## Installation\n\u003e **Note**  \nIf you are starting a new Foundry project, we recommend following the [Foundry Installation](https://book.getfoundry.sh/getting-started/installation) and [Foundry Getting Started](https://book.getfoundry.sh/getting-started/first-steps) documentation first.\n\nThe Foundry Chainlink toolkit has been designed so that it can be installed as a Forge dependency.  \n\nTo integrate it into your project, you need to run the following command:\n```\nforge install smartcontractkit/foundry-chainlink-toolkit\n```\n\n## Usage\n\nThe Foundry Chainlink plugin offers multiple ways to interact with Chainlink services,\ngiving you the flexibility to choose the approach that suits your workflow best.\n\n\u003e **Note**  \n\u003e Due to complex nature of embedded Solidity Scripts, compilation pipeline set to go through the new IR optimizer.\n\u003e This is done to avoid [stack too deep](https://docs.soliditylang.org/en/v0.8.21/security-considerations.html#call-stack-depth) errors.  \n\u003e Please consider setting [`via_ir` flag](https://book.getfoundry.sh/reference/config/solidity-compiler#via_ir) to `true` in your `foundry.toml` file.\n\n### 1. Solidity Scripts\n\nInteract with the Foundry Chainlink plugin using embedded Solidity Scripts:\n```Solidity\nimport {Script} from \"forge-std/Script.sol\";\nimport \"foundry-chainlink-toolkit/script/feeds/DataFeed.s.sol\";\n\ncontract MyContract is Script {\n  constructor() public {\n    // Initialize a contract\n  }\n\n  function getLatestPrice(address dataFeedAddress) public returns (int256 latestPrice){\n    DataFeedsScript automationScript = new DataFeedsScript(dataFeedAddress);\n\n    vm.broadcast();\n    (,latestPrice,,,) = DataFeedsScript.getLatestRoundData();\n    return latestPrice;\n  }\n}\n```\n\n\u003e **Note**  \n\u003e Foundry Solidity Scripting and Foundry EVM have limitations on passing context to nested scripts.\n\u003e That's why it is necessary to [broadcast](https://book.getfoundry.sh/cheatcodes/broadcast?highlight=broadcast#broadcast) signer before **each** call to Foundry Chainlink plugin.\n\n### 2. CLI\n\nInteract with the Foundry Chainlink plugin via CLI. \nFor 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.:\n```Solidity\nimport {Script} from \"forge-std/Script.sol\";\nimport \"foundry-chainlink-toolkit/script/feeds/DataFeed.s.sol\";\n\ncontract DataFeedsCLIScript is BaseScript {\n  function getLatestRoundData(address dataFeedAddress) external returns(uint80 roundId, int256 answer, uint256 startedAt, uint256 updatedAt, uint80 answeredInRound){\n    DataFeedsScript dataFeedScript = new DataFeedsScript(dataFeedAddress);\n    return dataFeedScript.getLatestRoundData();\n  }\n}\n```\n\nIt makes possible calling the script from the command line:\n```shell\nforge foundry-chainlink-toolkit/script/feeds/DataFeed.CLI.s.sol --sig \"getLatestRoundData(address)\" $$dataFeedAddress\n```\n\nExamples of shell scripts invoking Chainlink services can be found in the Make file [makefile-external](makefile-external).\n\n\u003e **Note**  \n\u003e 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](https://book.getfoundry.sh/reference/forge/forge-script)\n\n## Registries\nThe Foundry Chainlink toolkit provides registries that contain information about smart contracts related\nto various Chainlink services and other data. You can find them in the [registries](src%2Fregistries%2Fjson) directory.  \n\"In order to use it in your Solidity scripts, please utilize the [Foundry Cheatcode to parse JSON files](https://book.getfoundry.sh/cheatcodes/parse-json?highlight=json#decoding-json-objects-into-solidity-structs).\n\n## Sandbox\n\u003e **Note**\n\u003e Install [GNU make](https://www.gnu.org/software/make/) following the [Make documentation](https://www.gnu.org/software/make/manual/make.html).\n\u003e Install and run Docker; for convenience, the Chainlink nodes run in a container. Instructions: [docs.docker.com/get-docker](https://docs.docker.com/get-docker/).\n\nThe `sandbox` module of Hardhat Chainlink plugin provides the ability to test dApps against Chainlink services locally.\nThe functionality of the sandbox is wrapped in the [sandbox makefile](makefile-sandbox).\n\n### Configure your project\n1. Give Forge permission to read the output directory of the plugin by adding this setting to the foundry.toml:\n  ```\n  fs_permissions = [{ access = \"read\", path = \"lib/foundry-chainlink-toolkit/out\"}]\n  ```\n  \u003e **Note**  \n  The default path to the root of the Foundry Chainlink toolkit is `lib/foundry-chainlink-toolkit`.  \n  Unfortunately at the moment `foundry.toml` cannot read all environment variables. Specify a different path if necessary.\n\n2. Incorporate the [makefile-sandbox](makefile-sandbox) into your project. To do this, create or update a makefile in the root of your project with:\n  ```\n  -include ${FCT_PLUGIN_PATH}/makefile-sandbox\n  ```\n\n### Configure RPC node\nFor local testing, we recommend using [Anvil](https://book.getfoundry.sh/anvil/), which is a part of the Foundry toolchain.  \nYou can run it using the following command:\n```\nmake fct-anvil\n```\n\nFor more information on this command, see the [sandbox documentation](SANDBOX.md#run-anvil).\n\n\u003e **Note**  \n\u003e If a local blockchain network has been restarted, you should run a [clean restart of a Chainlink cluster](SANDBOX#restart-a-chainlink-cluster) to avoid possible synchronization errors.\n\n### Set up environment variables\nBased on the [env.template](env.template) - create or update an `.env` file in the root directory of your project.\nIn most cases, you will not need to modify the default values specified in this file.\n\nBelow are comments on some environment variables:\n- `FCT_PLUGIN_PATH` - path to the Foundry Chainlink toolkit root directory\n- `ETH_URL` - RPC node web socket used by the Chainlink node\n- `RPC_URL` - RPC node http endpoint used by Forge\n- `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\n- `ROOT` - root directory of the Chainlink node\n- `CHAINLINK_CONTAINER_NAME` - Chainlink node container name for the possibility of automating communication with it\n- `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\n\n\u003e **Note**  \n\u003e 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.\n\n### Manage local Chainlink node\n\nOnce local Chainlink node parameters are specified, Chainlink node could be started/restarted/stopped and managed with the plugin following the [sandbox documentation](SANDBOX.md#chainlink-nodes-management-scripts).\nIn order to login use credentials specified in [chainlink_api_credentials](src%2Fsandbox%2Fclroot%2Fsettings%2Fchainlink_api_credentials).\n\nAlternatively, you can manage a Chainlink node either with Chainlink CLI or Chainlink node GUI.\n\n#### Chainlink CLI\n\nChainlink 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.\n\nHere are some of the things you can do with the CLI:\n* Create/Delete Chainlink Jobs\n* Manage Chainlink accounts' transactions\n* Manage Chainlink External Initiators\n* See/Create Chainlink node's keys: ETH, OCR, P2P\n* and more...\n\nHere is example command to get list of ETH keys that are used by a Chainlink node:\n```bash\nchainlink keys eth list \n```\nThe most useful commands to manage Chainlink node with CLI you can find here: https://docs.chain.link/chainlink-nodes/resources/miscellaneous.\n\n#### Chainlink GUI\n\nPorts on which Chainlink GUIs are available are described in the [snadbox documentation](SANDBOX.md#initialize-testing-environment),\nthese ports are exposed with a docker-compose file to a host machine.\n\nHere are some of the things you can do with the GUI:\n* Create/Delete Chainlink Jobs\n* Create Chainlink Bridge\n* See Chainlink Jobs runs\n* See Chainlink node's keys: ETH, OCR, P2P, VRF\n* See Chainlink node's current configuration\n* and more...\n\n## Documentation\n\nFor detailed usage instructions and more information, refer to:\n* [DOCUMENTATION.md](DOCUMENTATION.md) for interaction with Chainlink services;\n* [SANDBOX.md](SANDBOX.md) for local testing in Sandbox.\n\n## Contribution\nWe welcome contributions from the community.\n\nIf you find any issues, have suggestions for improvements, or want to add new features to the plugin,\nplease don't hesitate to open an issue or submit a pull request.\n\nYour contributions help us improve the Foundry Chainlink toolkit and provide better tools for the entire community.\n\n\u003e **Note**  \n\u003e Foundry-Chainlink toolkit intended to support different compiler versions in range `[\u003e=0.6.2 \u003c0.9.0]`.  \n\u003e It was tested e2e with these solc versions:\n\u003e - 0.6.2\n\u003e - 0.6.12\n\u003e - 0.7.6\n\u003e - 0.8.9\n\u003e - 0.8.19\n\u003e\n\u003e Therefore, you can specify any supported Solidity compiler version in your foundry.toml.  \n\u003e In case you find any problems you are welcome to open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Ffoundry-chainlink-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartcontractkit%2Ffoundry-chainlink-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartcontractkit%2Ffoundry-chainlink-toolkit/lists"}