@chainlink/ccip-cli 0.94.0 → 0.96.0

package/src/commands/send.ts

@@ -1,17 +1,14 @@
 import {
-  type CCIPVersion,
   type ChainStatic,
-  type EVMChain,
   type ExtraArgs,
   type MessageInput,
   CCIPArgumentInvalidError,
-  CCIPChainFamilyUnsupportedError,
+  CCIPInsufficientBalanceError,
   CCIPTokenNotFoundError,
   ChainFamily,
-  estimateExecGasForRequest,
+  estimateReceiveExecution,
   getDataBytes,
   networkInfo,
-  sourceToDestTokenAmounts,
 } from '@chainlink/ccip-sdk/src/index.ts'
 import { type BytesLike, formatUnits, toUtf8Bytes } from 'ethers'
 import type { Argv } from 'yargs'
@@ -22,8 +19,8 @@ import type { Ctx } from './types.ts'
 import { getCtx, logParsedError, parseTokenAmounts } from './utils.ts'
 import { fetchChainsFromRpcs, loadChainWallet } from '../providers/index.ts'
 
-export const command = 'send <source> <router> <dest>'
-export const describe = 'Send a CCIP message from router on source to dest'
+export const command = 'send'
+export const describe = 'Send a CCIP message from source to destination chain'
 
 /**
  * Yargs builder for the send command.
@@ -32,108 +29,107 @@ export const describe = 'Send a CCIP message from router on source to dest'
  */
 export const builder = (yargs: Argv) =>
   yargs
-    .positional('source', {
+    .option('source', {
+      alias: 's',
       type: 'string',
       demandOption: true,
-      describe: 'source network, chainId or name',
-      example: 'ethereum-testnet-sepolia',
+      describe: 'Source chain: chainId, selector, or name',
     })
-    .positional('router', {
+    .option('dest', {
+      alias: 'd',
       type: 'string',
       demandOption: true,
-      describe: 'router contract address on source',
+      describe: 'Destination chain: chainId, selector, or name',
     })
-    .positional('dest', {
+    .option('router', {
+      alias: 'r',
       type: 'string',
       demandOption: true,
-      describe: 'destination network, chainId or name',
-      example: 'ethereum-testnet-sepolia-arbitrum-1',
+      describe: 'Router contract address on source',
     })
     .options({
       receiver: {
-        alias: 'R',
+        alias: 'to',
         type: 'string',
-        describe:
-          'Receiver of the message; defaults to the sender wallet address if same network family',
+        describe: 'Receiver address on destination; defaults to sender if same chain family',
       },
       data: {
-        alias: 'd',
         type: 'string',
-        describe: 'Data to send in the message (non-hex will be utf-8 encoded)',
-        example: '0x1234',
+        describe: 'Data payload to send (non-hex will be UTF-8 encoded)',
       },
       'gas-limit': {
         alias: ['L', 'compute-units'],
         type: 'number',
-        describe:
-          'Gas limit for receiver callback execution; defaults to default configured on ramps',
+        describe: 'Gas limit for receiver callback; defaults to ramp config',
       },
       'estimate-gas-limit': {
         type: 'number',
-        describe:
-          'Estimate gas limit for receiver callback execution; argument is a % margin to add to the estimate',
-        example: '10',
+        describe: 'Estimate gas limit with % margin (e.g., 10 for +10%)',
         conflicts: 'gas-limit',
       },
       'allow-out-of-order-exec': {
         alias: 'ooo',
         type: 'boolean',
-        describe:
-          'Allow execution of messages out of order (i.e. sender nonce not enforced, only v1.5+ lanes, mandatory for some dests)',
+        describe: 'Allow out-of-order execution (v1.5+ lanes)',
       },
       'fee-token': {
         type: 'string',
-        describe:
-          'Address or symbol of the fee token (e.g. LINK address on source); if not provided, will pay in native',
+        describe: 'Fee token address or symbol (default: native)',
       },
       'transfer-tokens': {
         alias: 't',
         type: 'array',
         string: true,
-        describe: 'List of token amounts (on source) to transfer to the receiver',
-        example: '0xtoken=0.1',
+        describe: 'Token amounts to transfer: token=amount',
       },
       wallet: {
         alias: 'w',
         type: 'string',
-        describe:
-          'Wallet to send transactions with; pass `ledger[:index_or_derivation]` to use Ledger USB hardware wallet, or private key in `USER_KEY` environment variable',
+        describe: 'Wallet: ledger[:index] or private key',
       },
       'token-receiver': {
         type: 'string',
-        describe: "Address of the Solana tokenReceiver (if different than program's receiver)",
+        describe: 'Solana token receiver (if different from program receiver)',
       },
       account: {
         alias: 'receiver-object-id',
         type: 'array',
         string: true,
-        describe:
-          'List of accounts needed by Solana receiver program, or receiverObjectIds needed by Sui; On Solana, append `=rw` to specify account as writable; can be specified multiple times',
-        example: 'requiredPdaAddress=rw',
+        describe: 'Solana accounts (append =rw for writable) or Sui object IDs',
       },
       'only-get-fee': {
         type: 'boolean',
-        describe: 'Fetch and print the fee for the transaction, then exit',
+        describe: 'Print fee and exit',
       },
       'only-estimate': {
         type: 'boolean',
-        describe: 'Only estimate dest exec gasLimit',
+        describe: 'Print gas estimate and exit',
+        implies: 'estimate-gas-limit',
       },
       'approve-max': {
         type: 'boolean',
-        describe:
-          "Approve the maximum amount of tokens to transfer; default=false approves only what's needed",
+        describe: 'Approve max token amount instead of exact',
       },
       wait: {
         type: 'boolean',
         default: false,
-        describe: 'Wait for execution',
+        describe: 'Wait for execution on destination',
       },
     })
     .check(
       ({ 'transfer-tokens': transferTokens }) =>
         !transferTokens || transferTokens.every((t) => /^[^=]+=\d+(\.\d+)?$/.test(t)),
     )
+    .example([
+      [
+        'ccip-cli send -s ethereum-testnet-sepolia -d arbitrum-sepolia -r 0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59 --only-get-fee',
+        'Get fee estimate',
+      ],
+      [
+        'ccip-cli send -s ethereum-testnet-sepolia -d arbitrum-sepolia -r 0x0BF3... --to 0xABC... --data "Hello"',
+        'Send message with data',
+      ],
+    ])
 
 /**
  * Handler for the send command.
@@ -198,37 +194,34 @@ async function sendMessage(
 
   if (argv.estimateGasLimit != null || argv.onlyEstimate) {
     // TODO: implement for all chain families
-    if (destNetwork.family !== ChainFamily.EVM)
-      throw new CCIPChainFamilyUnsupportedError(destNetwork.family, {
-        context: { feature: 'gas estimation' },
-      })
-    const dest = (await getChain(destNetwork.chainSelector)) as unknown as EVMChain
-    const onRamp = await source.getOnRampForRouter(argv.router, destNetwork.chainSelector)
-    const lane = {
-      sourceChainSelector: source.network.chainSelector,
-      destChainSelector: destNetwork.chainSelector,
-      onRamp,
-      version: (await source.typeAndVersion(onRamp))[1] as CCIPVersion,
+    const dest = await getChain(destNetwork.chainSelector)
+
+    if (!walletAddress) {
+      try {
+        ;[walletAddress, wallet] = await loadChainWallet(source, argv)
+      } catch {
+        // pass undefined sender for default
+      }
     }
-    const destTokenAmounts = await sourceToDestTokenAmounts(
+    const estimated = await estimateReceiveExecution({
       source,
-      destNetwork.chainSelector,
-      onRamp,
-      tokenAmounts,
-    )
-
-    if (!walletAddress) [walletAddress, wallet] = await loadChainWallet(source, argv)
-    const estimated = await estimateExecGasForRequest(source, dest, {
-      lane,
+      dest,
+      routerOrRamp: argv.router,
       message: {
         sender: walletAddress,
         receiver,
-        data: data || '0x',
-        tokenAmounts: destTokenAmounts,
+        data,
+        tokenAmounts,
       },
     })
-    logger.log('Estimated gasLimit:', estimated)
     argv.gasLimit = Math.ceil(estimated * (1 + (argv.estimateGasLimit ?? 0) / 100))
+    logger.log(
+      'Estimated gasLimit for sender =',
+      walletAddress,
+      ':',
+      estimated,
+      ...(argv.estimateGasLimit ? ['+', argv.estimateGasLimit, '% =', argv.gasLimit] : []),
+    )
     if (argv.onlyEstimate) return
   }
 
@@ -295,6 +288,27 @@ async function sendMessage(
   if (argv.onlyGetFee) return
 
   if (!walletAddress) [walletAddress, wallet] = await loadChainWallet(source, argv)
+
+  // Check sender has sufficient balance for fee
+  try {
+    const balance = await source.getBalance({ holder: walletAddress, token: feeToken })
+    if (balance < fee) {
+      const symbol =
+        feeTokenInfo.symbol.startsWith('W') && !feeToken
+          ? feeTokenInfo.symbol.substring(1)
+          : feeTokenInfo.symbol
+      throw new CCIPInsufficientBalanceError(
+        formatUnits(balance, feeTokenInfo.decimals),
+        formatUnits(fee, feeTokenInfo.decimals),
+        symbol,
+      )
+    }
+  } catch (e) {
+    // may fail for chains that don't implement getBalance yet; log and continue
+    if (e instanceof CCIPInsufficientBalanceError) throw e
+    logger.debug('Balance check skipped:', e)
+  }
+
   const request = await source.sendMessage({
     ...argv,
     destChainSelector: destNetwork.chainSelector,

package/src/commands/show.ts

@@ -2,7 +2,6 @@ import {
   type CCIPRequest,
   type ChainTransaction,
   CCIPExecTxRevertedError,
-  CCIPNotImplementedError,
   ExecutionState,
   MessageStatus,
   bigIntReplacer,
@@ -88,9 +87,7 @@ export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]
     } else idFromSource = argv.idFromSource
     const sourceNetwork = networkInfo(idFromSource)
     source = await getChain(sourceNetwork.chainId)
-    if (!source.getMessageById)
-      throw new CCIPNotImplementedError(`getMessageById for ${source.constructor.name}`)
-    request = await source.getMessageById(argv.txHash, onRamp, argv)
+    request = await source.getMessageById(argv.txHash, { ...argv, onRamp })
   } else {
     const [getChain_, tx$] = fetchChainsFromRpcs(ctx, argv, argv.txHash)
     getChain = getChain_

package/src/commands/supported-tokens.ts

@@ -37,7 +37,7 @@ import { formatDuration, getCtx, logParsedError, prettyTable } from './utils.ts'
 import type { GlobalOpts } from '../index.ts'
 import { fetchChainsFromRpcs } from '../providers/index.ts'
 
-export const command = ['getSupportedTokens <source> <address> [token]']
+export const command = ['getSupportedTokens', 'get-supported-tokens']
 export const describe =
   'List supported tokens in a given Router/OnRamp/TokenAdminRegistry, and/or show info about token/pool'
 
@@ -48,23 +48,39 @@ export const describe =
  */
 export const builder = (yargs: Argv) =>
   yargs
-    .positional('source', {
+    .option('network', {
+      alias: 'n',
       type: 'string',
       demandOption: true,
-      describe: 'source network, chainId or name',
-      example: 'ethereum-testnet-sepolia',
+      describe: 'Source network: chainId or name (e.g., ethereum-mainnet)',
     })
-    .positional('address', {
+    .option('address', {
+      alias: 'a',
       type: 'string',
       demandOption: true,
-      describe: 'router/onramp/tokenAdminRegistry/tokenPool contract address on source',
+      describe: 'Router/OnRamp/TokenAdminRegistry/TokenPool contract address',
     })
-    .positional('token', {
+    .option('token', {
+      alias: 't',
       type: 'string',
       demandOption: false,
-      describe:
-        'If address is router/onramp/tokenAdminRegistry, token may be used to pre-select a token from the supported list',
+      describe: 'Token address to query (pre-selects from list if address is a registry)',
     })
+    .option('fee-tokens', {
+      type: 'boolean',
+      default: false,
+      describe: 'List fee tokens instead of transferable tokens',
+    })
+    .example([
+      [
+        'ccip-cli getSupportedTokens -n ethereum-mainnet -a 0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D',
+        'List all supported tokens from router',
+      ],
+      [
+        'ccip-cli getSupportedTokens -n ethereum-mainnet -a 0x80226fc... -t 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+        'Get details for specific token',
+      ],
+    ])
 
 /**
  * Handler for the supported-tokens command.
@@ -82,7 +98,7 @@ export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']>
 
 async function getSupportedTokens(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
   const { logger } = ctx
-  const sourceNetwork = networkInfo(argv.source)
+  const sourceNetwork = networkInfo(argv.network)
   const getChain = fetchChainsFromRpcs(ctx, argv)
   const source = await getChain(sourceNetwork.name)
   let registry
@@ -92,8 +108,8 @@ async function getSupportedTokens(ctx: Ctx, argv: Parameters<typeof handler>[0])
     // ignore
   }
 
-  let info, tokenPool, poolConfigs, registryConfig
-  if (registry && !argv.token) {
+  // Handle --fee-tokens flag
+  if (argv.feeTokens) {
     const feeTokens = await source.getFeeTokens(argv.address)
     switch (argv.format) {
       case Format.pretty:
@@ -106,19 +122,23 @@ async function getSupportedTokens(ctx: Ctx, argv: Parameters<typeof handler>[0])
       default:
         logger.log('feeTokens:', feeTokens)
     }
+    return
+  }
 
+  let info, tokenPool, poolConfigs, registryConfig
+  if (registry && !argv.token) {
     // router + interactive list
     info = await listTokens(ctx, source, registry, argv)
     if (!info) return // format != pretty
     registryConfig = await source.getRegistryTokenConfig(registry, info.token)
     tokenPool = registryConfig.tokenPool
     if (!tokenPool) throw new CCIPTokenNotConfiguredError(info.token, registry)
-    poolConfigs = await source.getTokenPoolConfigs(tokenPool)
+    poolConfigs = await source.getTokenPoolConfig(tokenPool)
   } else {
     if (!argv.token) {
       // tokenPool
       tokenPool = argv.address
-      poolConfigs = await source.getTokenPoolConfigs(tokenPool)
+      poolConfigs = await source.getTokenPoolConfig(tokenPool)
       registry ??= await source.getTokenAdminRegistryFor(poolConfigs.router)
       ;[info, registryConfig] = await Promise.all([
         source.getTokenInfo(poolConfigs.token),
@@ -132,7 +152,7 @@ async function getSupportedTokens(ctx: Ctx, argv: Parameters<typeof handler>[0])
       registryConfig = await source.getRegistryTokenConfig(registry, argv.token)
       tokenPool = registryConfig.tokenPool
       if (!tokenPool) throw new CCIPTokenNotConfiguredError(argv.token, registry)
-      poolConfigs = await source.getTokenPoolConfigs(tokenPool)
+      poolConfigs = await source.getTokenPoolConfig(tokenPool)
     }
 
     if (argv.format === Format.json) {

package/src/commands/token.ts

@@ -0,0 +1,132 @@
+/**
+ * Token balance query command.
+ * Queries native or token balance for an address.
+ */
+
+import { type ChainStatic, networkInfo } from '@chainlink/ccip-sdk/src/index.ts'
+import { formatUnits } from 'ethers'
+import type { Argv } from 'yargs'
+
+import { type Ctx, Format } from './types.ts'
+import { getCtx, logParsedError, prettyTable } from './utils.ts'
+import type { GlobalOpts } from '../index.ts'
+import { fetchChainsFromRpcs } from '../providers/index.ts'
+
+export const command = 'token'
+export const describe = 'Query token balance for an address'
+
+/**
+ * Yargs builder for the token command.
+ * @param yargs - Yargs instance.
+ * @returns Configured yargs instance with command options.
+ */
+export const builder = (yargs: Argv) =>
+  yargs
+    .option('network', {
+      alias: 'n',
+      type: 'string',
+      demandOption: true,
+      describe: 'Network: chainId or name (e.g., ethereum-mainnet, solana-devnet)',
+    })
+    .option('holder', {
+      alias: 'H',
+      type: 'string',
+      demandOption: true,
+      describe: 'Wallet address to query balance for',
+    })
+    .option('token', {
+      alias: 't',
+      type: 'string',
+      demandOption: false,
+      describe: 'Token address (omit for native token balance)',
+    })
+    .example([
+      ['ccip-cli token -n ethereum-mainnet -H 0x1234...abcd', 'Query native ETH balance'],
+      [
+        'ccip-cli token -n ethereum-mainnet -H 0x1234... -t 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+        'Query USDC token balance',
+      ],
+      [
+        'ccip-cli token -n solana-devnet -H EPUjBP3Xf76K1VKsDSc6GupBWE8uykNksCLJgXZn87CB',
+        'Query native SOL balance',
+      ],
+    ])
+
+/**
+ * Handler for the token command.
+ * @param argv - Command line arguments.
+ */
+export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']> & GlobalOpts) {
+  const [ctx, destroy] = getCtx(argv)
+  return queryTokenBalance(ctx, argv)
+    .catch((err) => {
+      process.exitCode = 1
+      if (!logParsedError.call(ctx, err)) ctx.logger.error(err)
+    })
+    .finally(destroy)
+}
+
+async function queryTokenBalance(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
+  const { logger } = ctx
+  const networkName = networkInfo(argv.network).name
+  const getChain = fetchChainsFromRpcs(ctx, argv)
+  const chain = await getChain(networkName)
+
+  const balance = await chain.getBalance({
+    holder: argv.holder,
+    token: argv.token,
+  })
+
+  // Get token info for formatting (only for tokens, not native)
+  let tokenInfo
+  if (argv.token) {
+    argv.token = (chain.constructor as ChainStatic).getAddress(argv.token)
+    tokenInfo = await chain.getTokenInfo(argv.token)
+  }
+
+  const tokenLabel = tokenInfo?.symbol ?? 'native'
+  const formatted = formatUnits(
+    balance,
+    tokenInfo ? tokenInfo.decimals : (chain.constructor as ChainStatic).decimals,
+  )
+
+  switch (argv.format) {
+    case Format.json:
+      logger.log(
+        JSON.stringify(
+          {
+            network: networkName,
+            holder: argv.holder,
+            token: tokenLabel,
+            balance: balance.toString(),
+            formatted,
+            ...tokenInfo,
+          },
+          null,
+          2,
+        ),
+      )
+      return
+    case Format.log:
+      logger.log(
+        `Balance of`,
+        tokenInfo ? argv.token : tokenLabel,
+        ':',
+        balance,
+        `=`,
+        tokenInfo ? `${formatted} ${tokenLabel}` : formatted,
+      )
+      return
+    case Format.pretty:
+    default:
+      prettyTable.call(ctx, {
+        network: networkName,
+        holder: argv.holder,
+        token: argv.token ?? tokenLabel,
+        balance,
+        formatted,
+        ...tokenInfo,
+      })
+      return
+  }
+}

package/src/commands/utils.ts

@@ -12,6 +12,7 @@ import {
   CCIPErrorCode,
   ExecutionState,
   getCCIPExplorerUrl,
+  getDataBytes,
   networkInfo,
   supportedChains,
 } from '@chainlink/ccip-sdk/src/index.ts'
@@ -19,11 +20,11 @@ import { select } from '@inquirer/prompts'
 import {
   dataLength,
   formatUnits,
-  getBytes,
   hexlify,
   isBytesLike,
   isHexString,
   parseUnits,
+  toBigInt,
   toUtf8String,
 } from 'ethers'
 import type { PickDeep } from 'type-fest'
@@ -215,6 +216,26 @@ function omit<T extends Record<string, unknown>, K extends string>(
   return result
 }
 
+// while formatData just breaks 0x bytes into 32B chunks for readability, this function first
+// tests if the data looks like a UTF-8 string (with length prefix) and decode that before
+function formatDataString(data: string): Record<string, string> {
+  const bytes = getDataBytes(data)
+  const isPrintableChars = (bytes_: Uint8Array) => bytes_.every((b) => 32 <= b && b <= 126)
+  if (bytes.length > 64 && toBigInt(bytes.subarray(0, 32)) === 32n) {
+    const len = toBigInt(bytes.subarray(32, 64))
+    if (
+      len < 512 &&
+      bytes.length - 64 === Math.ceil(Number(len) / 32) * 32 &&
+      isPrintableChars(bytes.subarray(64, 64 + Number(len))) &&
+      bytes.subarray(64 + Number(len)).every((b) => b === 0)
+    ) {
+      return { data: toUtf8String(bytes.subarray(64, 64 + Number(len))) }
+    }
+  }
+  if (bytes.length > 0 && isPrintableChars(bytes)) return { data: toUtf8String(bytes) }
+  return formatData('data', data)
+}
+
 /**
  * Prints a CCIP request in a human-readable format.
  * @param source - Source chain instance.
@@ -289,11 +310,7 @@ export async function prettyRequest(this: Ctx, source: Chain, request: CCIPReque
       'tokens',
       await Promise.all(request.message.tokenAmounts.map(formatToken.bind(null, source))),
     ),
-    ...(isBytesLike(request.message.data) &&
-    dataLength(request.message.data) > 0 &&
-    getBytes(request.message.data).every((b) => 32 <= b && b <= 126) // printable characters
-      ? { data: toUtf8String(request.message.data) }
-      : formatData('data', request.message.data)),
+    ...formatDataString(request.message.data),
     ...('accounts' in request.message ? formatArray('accounts', request.message.accounts) : {}),
     ...rest,
   })

package/src/index.ts

@@ -11,13 +11,13 @@ import { Format } from './commands/index.ts'
 util.inspect.defaultOptions.depth = 6 // print down to tokenAmounts in requests
 // generate:nofail
 // `const VERSION = '${require('./package.json').version}-${require('child_process').execSync('git rev-parse --short HEAD').toString().trim()}'`
-const VERSION = '0.94.0-aac4ae6'
+const VERSION = '0.96.0-983178a'
 // generate:end
 
 const globalOpts = {
   rpcs: {
     type: 'array',
-    alias: ['r', 'rpc'],
+    alias: 'rpc',
     describe: 'List of RPC endpoint URLs, ws[s] or http[s]',
     string: true,
   },

package/src/providers/index.ts

@@ -8,10 +8,10 @@ import {
   type EVMChain,
   type TONChain,
   CCIPChainFamilyUnsupportedError,
-  CCIPNetworkFamilyUnsupportedError,
   CCIPRpcNotFoundError,
   CCIPTransactionNotFoundError,
   ChainFamily,
+  NetworkType,
   networkInfo,
   supportedChains,
 } from '@chainlink/ccip-sdk/src/index.ts'
@@ -94,7 +94,7 @@ export function fetchChainsFromRpcs(
   const loadChainFamily = (F: ChainFamily, txHash?: string) =>
     (initFamily$[F] ??= (endpoints$ ??= collectEndpoints.call(ctx, argv)).then((endpoints) => {
       const C = supportedChains[F]
-      if (!C) throw new CCIPNetworkFamilyUnsupportedError(F)
+      if (!C) throw new CCIPChainFamilyUnsupportedError(F)
       ctx.logger.debug('Racing', endpoints.size, 'RPC endpoints for', F)
 
       const chains$: Promise<Chain>[] = []
@@ -214,7 +214,11 @@ export async function loadChainWallet(chain: Chain, argv: { wallet?: unknown; rp
       wallet = loadSuiWallet(argv)
       return [wallet.toSuiAddress(), wallet] as const
     case ChainFamily.TON:
-      wallet = await loadTonWallet((chain as TONChain).provider, argv, chain.network.isTestnet)
+      wallet = await loadTonWallet(
+        (chain as TONChain).provider,
+        argv,
+        chain.network.networkType === NetworkType.Testnet,
+      )
       return [wallet.getAddress(), wallet] as const
     default:
       // TypeScript exhaustiveness check - this should never be reached