Using Chainlink Local to Test CCIP in Your Foundry Project

Integrate Chainlink Local into your project

If you use NPM, install the @chainlink/local NPM package:

npm install @chainlink/local@0.3.1

If you use Yarn, install the @chainlink/local NPM package:

yarn add @chainlink/local@0.3.1

If you use Foundry:

forge install smartcontractkit/chainlink-local@v0.3.1

and then set remappings to: @chainlink/local/=lib/chainlink-local/ in either remappings.txt or foundry.toml file

Import the CCIPLocalSimulator contract from the @chainlink/local package:

import {CCIPLocalSimulator} from "@chainlink/local@0.3.1/src/ccip/CCIPLocalSimulator.sol";

There are four guides to help you test Chainlink CCIP 2.0 in your Foundry project using Chainlink Local - two for each mode (with and without forking), plus the CCT tutorials. The guides use the CCIP Foundry Starter Kit, whose CCIP 2.0 examples (Example01-Example10) cover token transfers, Fast Transfers, programmable token transfers, and Cross-Chain Token (CCT) setup on the Ethereum Sepolia → Polygon Amoy lane.

Read CCIP 2.0 behavior in Chainlink Local to understand what the simulator enforces in each mode, or the CCIP starter kit examples map for an index of every kit example.

Guides

Using the Chainlink Local Simulator in your Foundry project

This guide helps you set up and run CCIP 2.0 in a localhost environment within your Foundry project. It provides step-by-step instructions on:

Cloning the CCIP Foundry Starter Kit
Installing necessary dependencies
Running tests for token transfers between two accounts using ExtraArgsV3 with Fast Transfers

Using the local simulator without forking is ideal for initial development and testing in an isolated environment.

Sending data to a receiver with CCV config

This guide covers the receiver-side finality rules in local mode: a data-only message to a BasicMessageReceiverWithCCVs contract, where the local router enforces the receiver's minimum block depth for Fast Transfers.

Using the Chainlink Local Simulator in your Foundry project with forked environments

This guide extends your testing capabilities by demonstrating how to use the Chainlink Local Simulator in a forked environment. It includes instructions on:

Setting up forks of real blockchain networks (Ethereum Sepolia and Polygon Amoy, a live CCIP 2.0 lane)
Routing messages across forks with CCIPLocalSimulatorFork for every CCIP era
Running the CCT fork tests (token and pool deployment, registration, Faster Than Finality gates)

Using the local simulator with forked environments is ideal for testing in a more realistic yet controlled setting.

Forking mainnets

This guide covers forking mainnet lanes: reading mainnet network details from Register, adding or overriding chains with setNetworkDetails, and routing messages across mainnet forks, following Chainlink Local's own Ethereum → Arbitrum One e2e test.

CCT tutorials

Three tutorials cover the fork-mode CCT examples: CCT burn and mint, CCT lock and release, and pool-based CCVs on AdvancedPoolHooks.