Skip to main content
Version: 1.10.3

Multi-Chain

The SDK provides a unified Chain interface across all supported blockchain families. This guide covers connecting to each chain, cross-family messaging, and chain-specific details.

For EVM-only usage, see Sending Messages and Tracking Messages — they cover the full workflow without multi-chain considerations.

Supported Chains​

Chain ClassFamilyWallet TypeSendExecuteToken Pools
EVMChainEVMethers Signer or viemWallet(client)YesYesYes
SolanaChainSolanaAnchor-compatible WalletYesYesYes
AptosChainAptosAptosAsyncAccountYesYesYes
SuiChainSuiKeypairNoYesNo
TONChainTONTONWalletYesYesNo
CantonChainCantonCantonWalletYesYesNo
note

Sui is execution-only — it can execute incoming messages but cannot send cross-chain messages. Token pool queries are not implemented on Sui, TON, or Canton.

Canton is partial — it supports send and manual execution but requires a CantonConfig object (party IDs, JWT, EDS URLs). Fee estimation, balance queries, message tracking via getMessagesInTx, and registry/pool queries are not yet implemented.

Connecting​

TypeScript
import { EVMChain } from '@chainlink/ccip-sdk'

const chain = await EVMChain.fromUrl('https://rpc.sepolia.org')
console.log('Connected to:', chain.network.name)
console.log('Chain selector:', chain.network.chainSelector)

All chains accept the same ChainContext options:

TypeScript
const chain = await EVMChain.fromUrl('https://rpc.sepolia.org', {
  logger: console,        // Custom logger
  apiClient: null,         // Disable CCIP API (RPC-only mode)
})

Unified Interface​

All chain classes implement the Chain interface, so you can write chain-agnostic code:

TypeScript
import {
  type Chain,
  EVMChain,
  SolanaChain,
  AptosChain,
  CantonChain,
  networkInfo,
  ChainFamily,
} from '@chainlink/ccip-sdk'

function createChain(
  rpcUrl: string,
  family: ChainFamily,
  cantonConfig?: Parameters<typeof CantonChain.fromUrl>[1],
): Promise<Chain> {
  switch (family) {
    case ChainFamily.EVM:
      return EVMChain.fromUrl(rpcUrl)
    case ChainFamily.Solana:
      return SolanaChain.fromUrl(rpcUrl)
    case ChainFamily.Aptos:
      return AptosChain.fromUrl(rpcUrl)
    case ChainFamily.Canton:
      return CantonChain.fromUrl(rpcUrl, cantonConfig)
    default:
      throw new Error(`Unsupported family: ${family}`)
  }
}

// Works with any chain
async function getMessages(chain: Chain, txHash: string) {
  const requests = await chain.getMessagesInTx(txHash)
  for (const req of requests) {
    console.log('Message ID:', req.message.messageId)
  }
  return requests
}

Cross-Chain Token Transfers​

For token-only transfers (no data), the SDK auto-populates extraArgs with sensible defaults for the destination chain. You only need receiver and tokenAmounts:

TypeScript
import { EVMChain, networkInfo } from '@chainlink/ccip-sdk'
import { parseUnits } from 'viem'

const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
const router = '0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59'

// Same code works regardless of destination chain family
const destSelector = networkInfo('solana-devnet').chainSelector // or 'avalanche-testnet-fuji', 'aptos-testnet'

const tokenInfo = await source.getTokenInfo(tokenAddress)
const amount = parseUnits('10', tokenInfo.decimals)

const message = {
  receiver: 'RecipientAddressOnDestChain...',
  tokenAmounts: [{ token: tokenAddress, amount }],
}

const fee = await source.getFee({ router, destChainSelector: destSelector, message })
await source.sendMessage({
  router,
  destChainSelector: destSelector,
  message,
  wallet,
})

The SDK handles computeUnits (Solana), gasLimit (EVM/Aptos), tokenReceiver, allowOutOfOrderExecution, and other chain-specific fields automatically.

Cross-Family Messaging​

For messages with data (arbitrary messaging or programmable token transfers), you must provide chain-specific extraArgs. The SDK encodes them automatically — just pass the right fields.

For full details on receiver contract setup and account configuration, see the dedicated tutorials:

TypeScript
import { EVMChain, networkInfo } from '@chainlink/ccip-sdk'

const source = await EVMChain.fromUrl('https://rpc.sepolia.org')
const destSelector = networkInfo('solana-devnet').chainSelector

const message = {
  receiver: 'SolanaProgramAddress...',
  data: '0x1234...',
  tokenAmounts: [],
  extraArgs: {
    computeUnits: 200000n,
    accountIsWritableBitmap: 0n,
    allowOutOfOrderExecution: true,
    tokenReceiver: '',      // Required when sending data + tokens
    accounts: [],            // Additional accounts the program needs
  },
}

const fee = await source.getFee({ router, destChainSelector: destSelector, message })

When sending data + tokens, tokenReceiver must be set to the Solana wallet or PDA that will receive the tokens.

The extraArgs fields depend on the destination chain family:

DestinationExtra Args TypeKey Fields
EVMEVMExtraArgsV1/V2/V3gasLimit, allowOutOfOrderExecution
SolanaSVMExtraArgsV1computeUnits, accounts, accountIsWritableBitmap, tokenReceiver, allowOutOfOrderExecution
AptosEVMExtraArgsV2gasLimit, allowOutOfOrderExecution
SuiSuiExtraArgsV1gasLimit, allowOutOfOrderExecution, tokenReceiver, receiverObjectIds
TONEVMExtraArgsV2gasLimit, allowOutOfOrderExecution
Canton (source)CantonExtraArgsV1feeTokenHoldingCids, ccvRawAddresses, gasLimit, executorMode
Canton (destination)GenericExtraArgsV3finality (defaults to 'finalized')

For token-only transfers (no data), you can omit extraArgs entirely — the SDK fills in defaults.

Solana Notes​

Transaction Flow​

Solana uses transaction signatures (not hashes). Use getTransaction() to fetch details:

TypeScript
const chain = await SolanaChain.fromUrl('https://api.devnet.solana.com')

const tx = await chain.getTransaction(signature)
const messages = await chain.getMessagesInTx(tx)

Unsigned Transactions​

For browser wallets (Phantom, Solflare), generate unsigned transactions and let the wallet handle signing, compute budget, and priority fees:

TypeScript
import { SolanaChain } from '@chainlink/ccip-sdk'
import { TransactionMessage, VersionedTransaction } from '@solana/web3.js'

const chain = await SolanaChain.fromUrl('https://api.devnet.solana.com')

const unsignedTx = await chain.generateUnsignedSendMessage({
  sender: walletPublicKey.toBase58(),
  router: routerAddress,
  destChainSelector,
  message,
})

// Build versioned transaction
const { blockhash } = await connection.getLatestBlockhash()
const messageV0 = new TransactionMessage({
  payerKey: walletPublicKey,
  recentBlockhash: blockhash,
  instructions: unsignedTx.instructions,
}).compileToV0Message(unsignedTx.lookupTables)

const transaction = new VersionedTransaction(messageV0)
const signature = await sendTransaction(transaction, connection)

Canton Notes​

Configuration​

Canton requires a CantonConfig object passed via ChainContext.cantonConfig when calling CantonChain.fromUrl. Required fields: party, ccipParty, jwt, edsUrl, transferInstructionUrl. See Canton Configuration for the full schema.

Identity and Addresses​

  • Party IDs (hint::1220...) identify Canton participants on the ledger
  • CCIP wire addresses for Canton receivers are keccak256(partyId) as 32-byte hex
  • Transaction IDs are Canton ledger update IDs (1220 + 32-byte SHA-256 digest), not EVM tx hashes

Send Extras​

Canton source sends use CantonExtraArgsV1 (not on-wire encoded bytes):

FieldDescription
feeTokenHoldingCidsContract IDs for fee token holdings (Amulet or LINK). Optional on sendMessage (auto-discovered from the party's holdings via fillCantonSendDefaults); required when calling generateUnsignedSendMessage directly.
ccvRawAddressesCCV instance addresses in instanceId@party format
gasLimitGas limit for destination ccipReceive callback
executorMode'default' or 'none' (skip executor for no-execution lanes)

Fee Model​

getFee() returns 0n on Canton — fees are computed on-ledger during the send transaction. Fee tokens are instrument IDs (native Amulet or CCIP LINK).

Unsigned Transactions​

Canton unsigned sends return JsCommands (Daml exercise commands with disclosed contracts):

TypeScript
const unsignedTx = await source.generateUnsignedSendMessage({
  sender: cantonConfig.party,
  router: 'ccipsender',
  destChainSelector,
  message,
})
// unsignedTx.commands — submit via interactive submission (prepare → sign → execute)