v0.2.9

v0.2.9 Release - 19 May 2026

This release fixes the address encoding/decoding 20/32 bytes issue in ccipLocalSimulatorFork

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Fixed

• CCIPLocalSimulatorFork.switchChainAndRouteMessage now pairs the destination OffRamp with the source OnRamp by reading getSourceChainConfig (v1.6+) and getStaticConfig (pre-v1.6), and falls back to trying other OffRamps with the same sourceChainSelector when execution fails or no deterministic match is found.
• CCIPLocalSimulatorFork.switchChainAndRouteMessage now correctly decodes destTokenAddress for v1.6 token transfers. The 32-byte abi.encode(address) value was previously truncated via a bytes20 cast, yielding a garbage address and causing the destination OffRamp's TokenAdminRegistry.getPool lookup to revert. Decoding now handles both 32-byte ABI-encoded and 20-byte packed forms, matching production OffRamp behavior, and is shared with receiver decoding via a single internal _decodeEVMAddress helper.
• For v1.6 token transfers, sourcePoolAddress is now passed to Internal.Any2EVMTokenTransfer as abi.encode(address) (32-byte word), matching production OnRamp output and destination pool validation. The simulator previously used abi.encodePacked(address) (20 bytes), which caused compatible pools to revert with InvalidSourcePoolAddress during fork testing.

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.9

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

Hardhat (npm)

npm install @chainlink/local@v0.2.9

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.9/src/ccip/CCIPLocalSimulator.sol";

PRs included

• fix: remove the npm install -g step by @andrejrakic in #57
• Upgrade GitHub Actions to latest versions by @andrejrakic in #58
• Prepare repo for v0.2.9 release by @andrejrakic in #61

Full Changelog: v0.2.8...v0.2.9

v0.2.9-beta.0

v0.2.9-beta.0 Release - 7 May 2026

This release fixes the address encoding/decoding 20/32 bytes issue in ccipLocalSimulatorFork

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Fixed

• CCIPLocalSimulatorFork.switchChainAndRouteMessage now correctly decodes destTokenAddress for v1.6 token transfers. The 32-byte abi.encode(address) value was previously truncated via a bytes20 cast, yielding a garbage address and causing the destination OffRamp's TokenAdminRegistry.getPool lookup to revert. Decoding now handles both 32-byte ABI-encoded and 20-byte packed forms, matching production OffRamp behavior, and is shared with receiver decoding via a single internal _decodeEVMAddress helper.
• For v1.6 token transfers, sourcePoolAddress is now passed to Internal.Any2EVMTokenTransfer as abi.encode(address) (32-byte word), matching production OnRamp output and destination pool validation. The simulator previously used abi.encodePacked(address) (20 bytes), which caused compatible pools to revert with InvalidSourcePoolAddress during fork testing.

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.9-beta.0

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

Hardhat (npm)

npm install @chainlink/local@v0.2.9-beta.0

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.9-beta.0/src/ccip/CCIPLocalSimulator.sol";

PRs included

• Correct v1.6 destTokenAddress and sourcePoolAddress encoding by @andrejrakic in #60

Full Changelog: v0.2.9-beta...v0.2.9-beta.0

v0.2.9-beta

v0.2.9-beta Release - 6 May 2026

This release fixes the algorithm for handling multiple offramps in ccipLocalSimulatorFork

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Fixed

• CCIPLocalSimulatorFork.switchChainAndRouteMessage now pairs the destination OffRamp with the source OnRamp by reading getSourceChainConfig (v1.6+) and getStaticConfig (pre-v1.6), and falls back to trying other OffRamps with the same sourceChainSelector when execution fails or no deterministic match is found.

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.9-beta

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

Hardhat (npm)

npm install @chainlink/local@v0.2.9-beta

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.9-beta/src/ccip/CCIPLocalSimulator.sol";

PRs included

• Improve the algorithm for handling multiple offramps in ccipLocalSimulatorFork by @andrejrakic in #59

Full Changelog: v0.2.8...v0.2.9-beta

v0.2.8

v0.2.8 Release - 5 May 2026

This release adds Data Streams Report Schema versions V1, and V5-V13

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Added

• Data Streams Report versions V1, V5-V13
• CCIP Network Details Update Script to fetch and update CCIP network details from Chainlink's API

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.8

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

Hardhat (npm)

npm install @chainlink/local@v0.2.8

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.8/src/ccip/CCIPLocalSimulator.sol";

PRs included

• v0.2.8 Release by @andrejrakic in #56

Full Changelog: v0.2.7...v0.2.8

v0.2.8-beta

v0.2.8-beta Release - 14 January 2026

This release adds automated tooling to fetch and update CCIP network details from Chainlink's API, ensuring the Register.sol contract always contains the latest network configurations.

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Added

• CCIP Network Details Update Script to fetch and update CCIP network details from Chainlink's API

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.8-beta

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

Hardhat (npm)

npm install @chainlink/local@v0.2.8-beta

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.8-beta/src/ccip/CCIPLocalSimulator.sol";

PRs included

• Fix publish workflow by @andrejrakic in #49
• DEVREL-155: Auto populate Register.sol by @Nalon in #51

New Contributors

• @Nalon made their first contribution in #51

Full Changelog: v0.2.7-beta.0...v0.2.8-beta

v0.2.7

v0.2.7 Release - 9 November 2025

This release adds support for a new Data Streams billing mechanism.

⚠️ Important: This release updates the version of the @chainlink/contracts dependency to v1.5.0 and the @chainlink/contracts-ccip dependency to v1.6.2, in which the remappings related to OpenZeppelin contracts have been changed. If you experience any issues with Chainlink Local after upgrading to this release (v0.2.7), please report them by opening a GitHub issue.

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Added

• Data Streams billing mechanism toggle in DataStreamsLocalSimulator.sol
• enableOffChainBilling() and enableOnChainBilling() functions
• getBillingMechanism() helper function
• Developer-friendly error messages for billing mechanism mismatches
• Comprehensive test suite for billing mechanisms
• Trusted publishing workflow with OIDC authentication
• Automatic version and branch validation in CI/CD

Changed

• Bumped @chainlink/contracts-ccip to 1.6.2 version
• Bumped @chainlink/contracts to 1.5.0 version
• Updated import paths to use vendored OpenZeppelin contracts
• Enhanced configuration() function to return current fee manager state
• Unified publish workflows into single automated workflow

Fixed

• Fixed Hardhat 2 compilation issues by vendoring OpenZeppelin contracts
• Fixed import path issues that occurred with updated dependency versions

Basic usage

This PR adds support for toggling between on-chain and off-chain billing mechanisms in the DataStreamsLocalSimulator contract.

// Existing users - no changes needed!
DataStreamsLocalSimulator simulator = new DataStreamsLocalSimulator();
// Defaults to an old on-chain billing (existing behavior)

// For a new off-chain billing
simulator.enableOffChainBilling();

// Switch back to on-chain billing if needed
simulator.enableOnChainBilling();

// User contracts can check current state
address feeManager = address(verifierProxy.s_feeManager());
if (feeManager != address(0)) {
    // On-chain billing active
} else {
    // Off-chain billing active
}

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.7

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

Hardhat (npm)

npm install @chainlink/local@v0.2.7

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.7/src/ccip/CCIPLocalSimulator.sol";

PRs included

• DEVREL-144 : Data Streams billing mechanism by @andrejrakic in #47
• v0.2.7 Release by @andrejrakic in #50

Full Changelog: v0.2.6...v0.2.7

v0.2.7-beta.0

v0.2.7-beta.0 Release - 9 October 2025

This release adds support for a new Data Streams billing mechanism.

⚠️ Important: This release updates the version of the @chainlink/contracts dependency to v1.5.0 and the @chainlink/contracts-ccip dependency to v1.6.2, in which the remappings related to OpenZeppelin contracts have been changed. If you experience any issues with Chainlink Local after upgrading to this release (v0.2.7-beta.0), please report them by opening a GitHub issue.

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.2
@chainlink/contracts	1.5.0

Added

• Data Streams billing mechanism toggle in DataStreamsLocalSimulator.sol
• enableOffChainBilling() and enableOnChainBilling() functions
• getBillingMechanism() helper function
• Developer-friendly error messages for billing mechanism mismatches
• Comprehensive test suite for billing mechanisms
• Trusted publishing workflow with OIDC authentication
• Automatic version and branch validation in CI/CD

Changed

• Bumped @chainlink/contracts-ccip to 1.6.2 version
• Bumped @chainlink/contracts to 1.5.0 version
• Updated import paths to use vendored OpenZeppelin contracts
• Enhanced configuration() function to return current fee manager state
• Unified publish workflows into single automated workflow

Fixed

• Fixed Hardhat 2 compilation issues by vendoring OpenZeppelin contracts
• Fixed import path issues that occurred with updated dependency versions

Basic usage

This PR adds support for toggling between on-chain and off-chain billing mechanisms in the DataStreamsLocalSimulator contract.

// Existing users - no changes needed!
DataStreamsLocalSimulator simulator = new DataStreamsLocalSimulator();
// Defaults to an old on-chain billing (existing behavior)

// For a new off-chain billing
simulator.enableOffChainBilling();

// Switch back to on-chain billing if needed
simulator.enableOnChainBilling();

// User contracts can check current state
address feeManager = address(verifierProxy.s_feeManager());
if (feeManager != address(0)) {
    // On-chain billing active
} else {
    // Off-chain billing active
}

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.7-beta.0

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

Hardhat (npm)

npm install @chainlink/local@v0.2.7-beta.0

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.7-beta.0/src/ccip/CCIPLocalSimulator.sol";

PRs included

• DEVREL-144 : Data Streams billing mechanism by @andrejrakic in #47

Full Changelog: v0.2.7-beta...v0.2.7-beta.0

v0.2.6

v0.2.6 Release - 18 September 2025

This release refactors CCIPLocalSimulatorFork.sol so it can deliver more than one message to more than one chain in a same call.

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.0
@chainlink/contracts	1.4.0

Added

• Added switchChainAndRouteMessage(uint256[] memory chainIds) function which is an overlap of already existing switchChainAndRouteMessage(chainId) in the CCIPLocalSimulatorFork.sol contract. This new function can be used to route multiple CCIP messages to multiple chains in a single call.

Changed

• Refactored CCIPLocalSimulatorFork.sol so it can route all CCIP messages sent from a loop and not just the first one

Basic usage

The main change is that now one can:

• Simulate sending one message to destination chain (was already possible)
• Simulate sending multiple messages to a single destination chain at once
• Simulate sending multiple messages to multiple destination chains at once

We accomplished that by introducing the new switchChainAndRouteMessage(uint256[] forkIds) function which is an overlap of an existing switchChainAndRouteMessage(uint256 forkId) function.

How to use it?

• Simulate sending one message to destination chain (was already possible)
  • => call switchChainAndRouteMessage(uint256 forkId)
• Simulate sending multiple messages to a single destination chain at once
  • => call switchChainAndRouteMessage(uint256 forkId) (it will deliver all messages, not just the first one)
• Simulate sending multiple messages to multiple destination chains at once
  • => call switchChainAndRouteMessage(uint256[] forkIds) (one can pass chains A, B, C here, it will deliver all messages to their target chains without duplication)

Basically no matter when one calls it, it will loop through all unprocessed CCIP messages and try to deliver them to appropriate destination chains. However, keep in mind that if one doesn’t pass correct forkIds, undelivered messages would be lost due to nature of Foundry.

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.6

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

Hardhat (npm)

npm install @chainlink/local@v0.2.6

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.6/src/ccip/CCIPLocalSimulator.sol";

PRs included

• Add codeowners file by @andrejrakic in #44
• 0.2.6 Release by @andrejrakic in #46

Full Changelog: v0.2.5...v0.2.6

v0.2.6-beta.0

v0.2.6-beta.0 Release - 10 September 2025

This release refactors CCIPLocalSimulatorFork.sol so it can deliver more than one message to more than one chain in a same call.

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.0
@chainlink/contracts	1.4.0

Services

• Chainlink CCIP v1.6

Changed

• Refactored CCIPLocalSimulatorFork.sol to deliver more than one message to more than one chain in a same call

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.6-beta.0

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

Hardhat (npm)

npm install @chainlink/local@v0.2.6-beta.0

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.6-beta.0/src/ccip/CCIPLocalSimulator.sol";

PRs included

• CCIP Fork: Route multiple messages to multiple chains at once by @andrejrakic in #45

Full Changelog: v0.2.6-beta...v0.2.6-beta.0

v0.2.6-beta

v0.2.6-beta Release - 11 June 2025

This release refactors CCIPLocalSimulatorFork.sol so it can route all CCIP messages sent from a loop and not just the first one.

Changelog

Dependencies

Package	Version
@chainlink/contracts-ccip	1.6.0
@chainlink/contracts	1.4.0

Services

• Chainlink CCIP v1.6

Changed

• Refactored CCIPLocalSimulatorFork.sol so it can route all CCIP messages sent
  from a loop and not just the first one

Testing the release

To test this release install @chainlink-local using the following commands:

Foundry (git)

forge install smartcontractkit/chainlink-local@v0.2.6-beta

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

Hardhat (npm)

npm install @chainlink/local@v0.2.6-beta

and then create the following contract and compile it:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

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

Remix IDE

// SPDX-License-Identifier: MIT
pragma solidity 0.8.24;

import {CCIPLocalSimulator} from "https://github.com/smartcontractkit/chainlink-local/blob/v0.2.6-beta/src/ccip/CCIPLocalSimulator.sol";

PRs included

• V0.2.6-beta release by @andrejrakic in #41

Full Changelog: v0.2.5...v0.2.6-beta