v1.0.0 - Rewrite Stable

⬡ ccip-sdk and ccip-cli stable v1.0.0 release 🚀

Important

v1.0 is a ground-up rewrite of the v0.2 series. Existing v0.2 users should treat this as a new SDK.

Highlights

• Monorepo with two packages: @chainlink/ccip-sdk (library) and @chainlink/ccip-cli (CLI tool)
• Multi-chain family support: unified interface across EVM, Solana, Aptos, Sui (WIP), and TON (WIP)
• Decentralized (RPC) or CCIP-API data sources
• Modern TypeScript DX: NodeJS, browser, Electron, mobile

Split packages in monorepo

ccip-tools-ts now isn't a single package anymore, but instead was split into (initially) 2 packages, both kept and developed in this monorepo and published in lockstep under same version to npmjs:

• Modern TypeScript, ESM, erasableSyntaxOnly and strict
• Node.js v20+ required. v24+ recommended for development (native TypeScript execution via node or tsx)
• node --test tests
• Tree-shakeable
• Semver: we strive to not break backwards compatibility on existing interfaces, types and methods without major version bumps, but supporting new CCIP networks, options and minor contracts versions may require keeping up-to-date with our patch releases

Tip

📚 Reference docs and complete examples can be found at https://docs.chain.link/ccip/tools/

🛠️ ccip-sdk: the developer's toolkit

• ccip-sdk is the library with which to interact with CCIP on all supported blockchain families, on any JS/TS environment (tested on NodeJS, browsers and Electron)
• Install as dependency in your project with npm install @chainlink/ccip-sdk (or equivalent pnpm, yarn, etc)
• Many different chain families supported under a single interface, with common types and interoperability:
  • EVMChain
  • SolanaChain
  • AptosChain
  • SuiChain (WIP)
  • TONChain (WIP)
• Import like import { EVMChain, type CCIPRequest } from '@chainlink/ccip-sdk'
• Instantiating classes:
  • From https/wss RPC endpoint:
    • const source = await EVMChain.fromUrl('https://<your_rpc_endpoint>')
  • From provider (chain-family-dependent async constructors):
    • const dest = await EVMChain.fromProvider(ethers.BrowserProvider(window.ethereum))
• Example: check details of CCIP message:
  • const request: CCIPRequest = (await source.getMessagesInTx('0xYourCcipSendTxHash'))[0]
  • const request: CCIPRequest = await source.getMessageById('0xYourMessageId')
• Or query the API directly:
  • const api = CCIPAPIClient.fromUrl()
  • const request = await api.getMessageById('0xYourMessageId')
  • const messageIds: string[] = await api.getMessageIdsInTx('0xYourCcipSendTxHash')

🔪 ccip-cli: the poweruser's swiss-army knife

• ccip-cli is the advanced tool and reference implementation for the sdk
• Can be installed with npm install -g @chainlink/ccip-cli or run ad-hoc with npx @chainlink/ccip-cli
• Auto-detect networks from multiple RPCs passed through --rpc options, --rpcs-file=./rpcs.txt or RPC_* environment variables
• Read CCIP_ prefixed environment variables as options, e.g.: CCIP_VERBOSE=true
• Example commands:
  • ccip-cli show <request-tx-hash-or-message-id> to inspect message's details; messageId fetches info from CCIP-API, and transaction hash from RPC)
  • ccip-cli send --source ethereum-testnet-sepolia --router 0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59 --dest ethereum-testnet-sepolia-arbitrum-1 --receiver=0xReceiver --data="hello ccip-cli" --wallet=ledger:1 sends a ccip message on given router and lane
  • ccip-cli manual-exec <request-tx-hash> manually executes a failed message
  • ccip-cli get-supported-tokens -n ethereum-mainnet -a 0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D list tokens and their configs (searchable!)

v0.97.0 - Major refactoring beta.7

Changelog:

• SDK: v2.0 support:
  • new Chain.getExecutionInput method, which consolidates getMessagesInBatch, calculateManualExecProof and getOffchainTokenData
  • Breaking: rename generateUnsignedExecuteReport, executeReport to generateUnsignedExecute, execute
  • Breaking: generateUnsignedExecute, execute receives input: ExecutionInput instead of execReport
  • Breaking: rename Chain.getCommitReport to getValidations
  • Breaking: deprecate Chain.getCommitStoreForOffRamp: needed, available and used internally only in EVMChain; getVerifications (fka getCommitReport) now receives offRamp address instead of commitStore
• SDK: Breaking: Reduce bundle size by eliminating cross-chain imports
  • Move DEFAULT_GAS_LIMIT from evm/const.ts to shared/constants.ts
  • Move BCS codecs and encoding utils to shared/bcs-codecs.ts (shared by Aptos/Sui)
  • Remove DEFAULT_APPROVE_GAS_LIMIT (unused)
  • Non-EVM chains no longer bundle EVM ABIs (~500KB savings per chain)
  • Sui no longer bundles Aptos code (~300KB savings)
• API: make CCIPAPIClient.fromUrl memoized non-async
• CLI: Support messageId from API in show command

What's Changed

• docs: document chain-specific fields in getTokenPoolConfig by @aelmanaa in #135
• fix(sdk): use production CCIP API URL by @aelmanaa in #136
• TON->EVM Manual Exec by @Farber98 in #138
• evm: implement nonce cache and management per wallet address by @andrevmatos in #139
• docs: improve TSDoc and SDK documentation by @aelmanaa in #140
• Update generic extra args V3 tag with preimage by @PabloMansanet in #137
• feat(sdk): reduce bundle size by eliminating cross-chain imports by @aelmanaa in #141
• cli: show messageId by @andrevmatos in #142
• Apiref by @aelmanaa in #143
• feat(api-ref): add Chains Explorer page by @aelmanaa in #144
• CCIP v2.0 by @andrevmatos in #132

Full Changelog: v0.96.0...v0.97.0

v0.96.0 - Major refactoring beta.6

What's Changed

• Add basic API integration test suite by @PabloMansanet in #119
• update docs by @aelmanaa in #121
• fix(sdk): remove .unref() from sleep for browser compatibility by @aelmanaa in #122
• feat(sdk): add named types for token pool methods by @aelmanaa in #123
• fix(sdk): add optional metadata field to CCIPRequest for API-specific data by @aelmanaa in #126
• fix: estimateGas for tokens with allowlists by @andrevmatos in #120
• feat(cli): add kebab-case aliases and move fee tokens to send command by @aelmanaa in #129
• Support ExtraArgsV3 for EVM chains by @PabloMansanet in #128
• Add CCIP send message support for TON by @Farber98 in #113
• Chain-fork tests (prool + anvil) by @PabloMansanet in #130
• fix(sdk): move allSupportedChains to separate entry point by @aelmanaa in #134

Changelog:

• SDK: Breaking: Move allSupportedChains to @chainlink/ccip-sdk/all entry point (fixes tree-shaking in esbuild/Bun/Parcel)
• CLI: Add kebab-case aliases for multi-word commands (manual-exec, get-supported-tokens, parse-bytes, parse-data)
• CLI: Add --fee-tokens flag to getSupportedTokens command to list fee tokens instead of transferable tokens
• SDK: Breaking: CCIPRequest now includes optional metadata?: APICCIPRequestMetadata field
  • API fields (status, receiptTransactionHash, deliveryTime, etc.) moved under metadata
  • Migration: Change request.status to request.metadata?.status
• SDK: Breaking: Remove APICCIPRequest type - use CCIPRequest with metadata field instead
• SDK: Improve JSDoc for RateLimiterState - clarify that null means rate limiting is disabled
• SDK: Improve JSDoc for getTokenPoolRemotes and TokenPoolRemote - clarify Record keys are chain names
• SDK: Add named types TokenPoolConfig and RegistryTokenConfig for clearer IDE hints
• SDK: Rename getTokenPoolConfigs to getTokenPoolConfig for consistency (returns single config)
• SDK: Add Chain.getTokenPoolRemote for fetching single remote config by chainSelector
• SDK: Fix sleep() browser compatibility - use optional chaining for .unref() which is Node.js-only
• SDK: Add TOKEN_REMOTE_NOT_CONFIGURED error code for missing TokenPool remote chain configurations
• SDK: Fix EVM getTokenPoolRemotes to throw CCIPTokenPoolChainConfigNotFoundError when remote token is not configured
• SDK: Fix Aptos getTokenPoolRemotes to throw CCIPTokenPoolChainConfigNotFoundError when remote chain config is missing
• TON: Full send support

Full Changelog: v0.95.0...v0.96.0

v0.95.0 - Major refactoring beta.5

PRs

• feat: add Chain.getBalance() for token balance queries by @aelmanaa in #99
• Fix generateUnsignedExecuteReport for solana by @marek-sadura in #109
• Add token transfer documentation to SDK docs by @aelmanaa in #110
• Expose message retrieval by ID or TxHash (API) by @PabloMansanet in #97
• SDK: fix EVM estimate gas for token transfers with balance slot!=0 by @andrevmatos in #114
• improve estimateReceiveExecution options by @andrevmatos in #115
• Enable Sui -> Any manual exec by @RodrigoAD in #107
• adapt commands cli by @aelmanaa in #116
• Fallback to API with retries for getMessagesInTx by @PabloMansanet in #112
• Add Sui getTokenForTokenPool by @RodrigoAD in #118
• Sui: working show, improve events fetching by @andrevmatos in #117

Changelog

• SDK: Chain.getBalance() method for querying native and token balances (EVM, Solana, Aptos)
• SDK: Solana resolveATA() utility for ATA derivation with automatic SPL Token vs Token-2022 detection
• CLI: token command for balance queries
• SDK: fix EVM estimate gas for token transfers with balance slot!=0 (e.g. USDC)
• SDK: Add NetworkType enum ('MAINNET' | 'TESTNET') and networkType property to NetworkInfo, in place of isTestnet boolean
• SDK: Selector generation scripts now validate network_type presence from upstream chain-selectors
• CLI: Breaking: send, getSupportedTokens, and token commands now use named arguments instead of positional (e.g., send -s <source> -d <dest> -r <router>)
• CLI: Breaking: -r alias removed from global --rpcs option (use --rpc instead); -r now used for --router in send command

Full Changelog: v0.94.0...v0.95.0

v0.94.0 - Major refactoring beta.4

What's Changed

• add cross-platform browser compatibility by @aelmanaa in #95
• Fix from Sui extra args by @RodrigoAD in #103
• implement Chain.buildMessageForDest and allow partial extraArgs by @andrevmatos in #102
• Rename RequestMessage by @PabloMansanet in #105
• Add missing dependencies by @PabloMansanet in #106

Changelog

• SDK: Browser compatibility - explicit buffer dependency and imports for cross-platform support
• CI: Added publint and @arethetypeswrong/cli validation for package exports
• ESLint: import/no-nodejs-modules rule prevents Node.js-only imports in SDK
• Docs: Cross-Platform Portability guidelines in CONTRIBUTING.md
• SDK: Populate default extraArgs for getFee, sendMessage methods, requiring minimal parameters to use these methods

Full Changelog: v0.93.0...v0.94.0

v0.93.0 - Major refactoring beta.3

What's Changed

• feat: add lane-latency command and CCIP API client by @aelmanaa in #89
• feat(sdk,cli): add MessageStatus/IntentStatus enums and enhance CLI logging by @aelmanaa in #91
• decode receipts for TON by @Farber98 in #90
• feat(sdk): add viem client and wallet adapters by @aelmanaa in #92
• refactor: rename fetch to get, object arguments for >2 args methods by @andrevmatos in #93
• TON: ledger support, TonClient v2, noUncheckedIndexedAccess by @andrevmatos in #94

• SDK: CCIPAPIClient and Chain.getLaneLatency() for querying lane delivery times via CCIP API
• CLI: lane-latency <source> <dest> command; --no-api flag for decentralized mode
• SDK: MessageStatus enum for message lifecycle tracking
• CLI: show --wait displays status progression during message tracking
• SDK: Rename fetch* to get* for message methods (getMessagesInTx, getMessageById, getMessagesForSender)
• SDK: Viem adapter via @chainlink/ccip-sdk/viem - use fromViemClient() and viemWallet() for viem users
• SDK: getCCIPExplorerUrl() and getCCIPExplorerLinks() for CCIP Explorer URL generation
• CLI: send and show commands now display CCIP Explorer links for visual transaction tracking
• SDK: Added sideEffects: false to package.json for improved tree-shaking support
• SDK: Breaking: Rename fetch* to get* for message methods (getMessagesInTx, getMessageById, getMessagesForSender, getAllMessagesInBatch, getOffchainTokenData, getCommitReport, getExecutionReceipts)
• SDK: Breaking: Convert methods with >2 arguments (besides opts/ctx) to single destructured object argument (getFee, generateUnsignedSendMessage, sendMessage, generateUnsignedExecuteReport, executeReport, getCommitReport, getExecutionReceipts, waitFinalized)
• SDK: simplify getExecutionReceipts filters (accept messageId and sourceChainSelector, instead of whole request)
• SDK: executeReport resolves to CCIPExecution, instead of generic ChainTransaction
• SDK: rename getAllMessagesInBatch to getMessagesInBatch (for consistency with other method names)
• SDK: migrate TONChain to TonClient (from TonClient4) and TON HTTP V2 endpoints (more common)
• CLI: implement Ledger hardwallet support for TON

Full Changelog: v0.92.1...v0.93.0

v0.92.1 - Major refactoring beta.2

What's Changed

• Basic TON Chain support for CCIP SDK by @Farber98 in #69
• TON follow ups by @Farber98 in #79
• Decoding unit tests by @PabloMansanet in #78
• Feat/error handling by @aelmanaa in #77
• cli improvements, getLogs watch by @andrevmatos in #76
• docs: add chain implementation guide, refactor evm types for consistency by @aelmanaa in #84
• merge CCIPMessage.header into message root by @andrevmatos in #85
• central docs by @aelmanaa in #87
• ton manual exec work + tests by @Farber98 in #80
• Sui manual exec by @RodrigoAD in #83

SDK:

• typed Error classes
• Chain.getLogs can receive watch boolean or cancel promise, to enter continuous logs fetching
• Chain.waitFinality method to receive a log and wait for its tx to finalize
• Chain.isTxHash static method to typeguard chain-specific txHash string format
• isSupportedTxHash function exported to check any supported chain
• Breaking::CCIPMessage loses header; properties now are merged to message root (e.g. message.messageId)

CLI:

• show --wait and send --wait waits for finality, commit and first execution of pending requests
• RPC endpoint url racer now triggers chain-families on-demand
• --rpcs/-r now can split CSV strings
• if --wallet is omitted and --rpcs-file=['./.env] has a USER_KEY= or PRIVATE_KEY= variable, it will be used as wallet

Full Changelog: v0.91.1...v0.92.1

v0.91.1 - Major refactoring beta.1

What's Changed (from v0.90.2 - beta.0)

• EVM: fix getFeeTokens in v1.5 lanes by @andrevmatos in #68
• Sui basic hasher support by @RodrigoAD in #71
• docs: enforce TSDoc/JSDoc quality gates via ESLint by @aelmanaa in #72
• Chain.sendMessage now calls getFee by itself, if not provided; it also returns a CCIPRequest
• Fix USDC/CCTP attestation fetching in Solana
• CCIPRequest loses timestamp property, available in request.tx.timestamp instead
• Rename Chain.listFeeTokens to getFeeTokens, fix for v1.5 lanes
• Move fetchCCIPRequestsInTx function to Chain.fetchRequestsInTx method
• Move fetchCCIPRequestById function to Chain.fetchRequestById method; it now can optionally receive OnRamp address to narrow search, required in non-EVM chains (which can't scan whole chain); cli's show --id-from-source receives <address>@<network> onramp address format in these cases
• Move fetchAllMessagesInBatch function to Chain.fetchAllMessagesInBatch method
• getWallet static and cached methods are gone; wallet compatible signer instance should be passed directly as option to the read-write methods, sendMessage and executeReport
• Chains now expose generateUnsignedSendMessage and generateUnsignedExecuteReport, which expose raw/unsigned tx data for sendMessage and executeReport respectively, in case one needs to sign and broadcast manually
• All methods which logs now may receive a { logger } context object, to inject a logger other than console (which is still the default)
• Remove some more node-isms from SDK (better browser compat)

Full Changelog: v0.90.2...v0.91.1

v0.90.2 - Major refactoring beta.0

• Major overhaul of the tool, split into ccip-sdk and ccip-cli packages
• SDK now exposes Chain family specific classes, with initial full support to EVM, Solana and Aptos
• NodeJS specific bits moved out of SDK and into the CLI, SDK now is environment agnostic
• CLI implements Ledger support for all 3 chains
• See each package's README for more details

v0.2.12

What's Changed

• Add Sui message hasher by @RodrigoAD in #59
• chore: bump actions and use new publish workflow by @andrevmatos in #60

Full Changelog: v0.2.11...v0.2.12