@chainlink/ccip-cli 0.95.0 → 0.97.0

package/src/commands/manual-exec.ts

@@ -1,7 +1,26 @@
+/**
+ * CCIP CLI Manual Execution Command
+ *
+ * Manually executes pending or failed CCIP messages on the destination chain.
+ * Use this when automatic execution fails or is delayed.
+ *
+ * @example
+ * ```bash
+ * # Execute a stuck message
+ * ccip-cli manualExec 0xSourceTxHash... --wallet $PRIVATE_KEY
+ *
+ * # Execute with custom gas limit
+ * ccip-cli manualExec 0xSourceTxHash... --gas-limit 500000
+ *
+ * # Execute all messages in sender queue
+ * ccip-cli manualExec 0xSourceTxHash... --sender-queue
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import {
-  type ExecutionReport,
   bigIntReplacer,
-  calculateManualExecProof,
   discoverOffRamp,
   estimateReceiveExecution,
   isSupportedTxHash,
@@ -13,9 +32,9 @@ import { type Ctx, Format } from './types.ts'
 import {
   getCtx,
   logParsedError,
-  prettyCommit,
   prettyReceipt,
   prettyRequest,
+  prettyVerifications,
   selectRequest,
   withDateTimestamp,
 } from './utils.ts'
@@ -25,7 +44,7 @@ import { fetchChainsFromRpcs, loadChainWallet } from '../providers/index.ts'
 // const MAX_EXECS_IN_BATCH = 1
 // const MAX_PENDING_TXS = 25
 
-export const command = 'manualExec <tx-hash>'
+export const command = ['manualExec <tx-hash>', 'manual-exec <tx-hash>']
 export const describe = 'Execute manually pending or failed messages'
 
 /**
@@ -134,7 +153,7 @@ async function manualExec(
       break
     }
     case Format.pretty:
-      await prettyRequest.call(ctx, source, request)
+      await prettyRequest.call(ctx, request, source)
       break
     case Format.json:
       logger.info(JSON.stringify(request, bigIntReplacer, 2))
@@ -143,38 +162,21 @@ async function manualExec(
 
   const dest = await getChain(request.lane.destChainSelector)
   const offRamp = await discoverOffRamp(source, dest, request.lane.onRamp, source)
-  const commitStore = await dest.getCommitStoreForOffRamp(offRamp)
-  const commit = await dest.getCommitReport({ ...argv, commitStore, request })
 
+  const verifications = await dest.getVerifications({ ...argv, offRamp, request })
   switch (argv.format) {
     case Format.log:
-      logger.log('commit =', commit)
+      logger.log('commit =', verifications)
       break
     case Format.pretty:
       logger.info('Commit (dest):')
-      await prettyCommit.call(ctx, dest, commit, request)
+      await prettyVerifications.call(ctx, dest, verifications, request)
       break
     case Format.json:
-      logger.info(JSON.stringify(commit, bigIntReplacer, 2))
+      logger.info(JSON.stringify(verifications, bigIntReplacer, 2))
       break
   }
 
-  const messagesInBatch = await source.getMessagesInBatch(request, commit.report, argv)
-  const execReportProof = calculateManualExecProof(
-    messagesInBatch,
-    request.lane,
-    request.message.messageId,
-    commit.report.merkleRoot,
-    dest,
-  )
-
-  const offchainTokenData = await source.getOffchainTokenData(request)
-  const execReport: ExecutionReport = {
-    ...execReportProof,
-    message: request.message,
-    offchainTokenData,
-  }
-
   if (argv.estimateGasLimit != null) {
     let estimated = await estimateReceiveExecution({
       source,
@@ -185,7 +187,11 @@ async function manualExec(
     logger.info('Estimated gasLimit override:', estimated)
     estimated += Math.ceil((estimated * argv.estimateGasLimit) / 100)
     const origLimit = Number(
-      'gasLimit' in request.message ? request.message.gasLimit : request.message.computeUnits,
+      'ccipReceiveGasLimit' in request.message
+        ? request.message.ccipReceiveGasLimit
+        : 'gasLimit' in request.message
+          ? request.message.gasLimit
+          : request.message.computeUnits,
     )
     if (origLimit >= estimated) {
       logger.warn(
@@ -202,8 +208,10 @@ async function manualExec(
     }
   }
 
+  const input = await source.getExecutionInput({ ...argv, request, verifications })
+
   const [, wallet] = await loadChainWallet(dest, argv)
-  const receipt = await dest.executeReport({ ...argv, offRamp, execReport, wallet })
+  const receipt = await dest.execute({ ...argv, offRamp, input, wallet })
 
   switch (argv.format) {
     case Format.log:

package/src/commands/parse.ts

@@ -1,3 +1,21 @@
+/**
+ * CCIP CLI Parse Command
+ *
+ * Parses and decodes various data formats including errors, revert reasons,
+ * function calls, and event data. Supports hex, base64, and chain-specific formats.
+ *
+ * @example
+ * ```bash
+ * # Parse a revert reason
+ * ccip-cli parse 0x08c379a0...
+ *
+ * # Parse event data
+ * ccip-cli parse 0xEventData...
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import {
   CCIPDataParseError,
   bigIntReplacer,
@@ -9,7 +27,13 @@ import type { GlobalOpts } from '../index.ts'
 import { type Ctx, Format } from './types.ts'
 import { getCtx, logParsedError, prettyTable } from './utils.ts'
 
-export const command = ['parse <data>', 'parseBytes <data>', 'parseData <data>']
+export const command = [
+  'parse <data>',
+  'parseBytes <data>',
+  'parse-bytes <data>',
+  'parseData <data>',
+  'parse-data <data>',
+]
 export const describe =
   'Try to parse and print errors, revert reasons or function call or event data'
 
@@ -22,7 +46,7 @@ export const builder = (yargs: Argv) =>
   yargs.positional('data', {
     type: 'string',
     demandOption: true,
-    describe: 'router contract address on source',
+    describe: 'Data to parse (hex, base64, or chain-specific format)',
   })
 
 /**

package/src/commands/send.ts

@@ -1,8 +1,30 @@
+/**
+ * CCIP CLI Send Command
+ *
+ * Sends a cross-chain message via CCIP. Supports data payloads, token transfers,
+ * custom gas limits, and various fee payment options.
+ *
+ * @example
+ * ```bash
+ * # Send a message with data
+ * ccip-cli send -s sepolia -d fuji -r 0xRouter... --to 0xReceiver... --data "hello"
+ *
+ * # Send tokens
+ * ccip-cli send -s sepolia -d fuji -r 0xRouter... -t 0xToken=1.5
+ *
+ * # Pay fee in LINK
+ * ccip-cli send -s sepolia -d fuji -r 0xRouter... --fee-token LINK
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import {
   type ChainStatic,
   type ExtraArgs,
   type MessageInput,
   CCIPArgumentInvalidError,
+  CCIPInsufficientBalanceError,
   CCIPTokenNotFoundError,
   ChainFamily,
   estimateReceiveExecution,
@@ -287,6 +309,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,
@@ -305,10 +348,8 @@ async function sendMessage(
   )
   await showRequests(ctx, {
     ...argv,
-    txHash: request.tx.hash,
-    'tx-hash': request.tx.hash,
-    'id-from-source': undefined,
-    idFromSource: undefined,
+    txHashOrId: request.tx.hash,
+    'tx-hash-or-id': request.tx.hash,
     'log-index': undefined,
     logIndex: undefined,
   })

package/src/commands/show.ts

@@ -1,14 +1,37 @@
+/**
+ * CCIP CLI Show Command
+ *
+ * Displays detailed information about a CCIP message, including its status,
+ * commit report, and execution receipts across source and destination chains.
+ *
+ * @example
+ * ```bash
+ * # Show message details
+ * ccip-cli show 0xSourceTxHash...
+ *
+ * # Wait for execution
+ * ccip-cli show 0xSourceTxHash... --wait
+ *
+ * # Output as JSON
+ * ccip-cli show 0xSourceTxHash... --format json
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import {
-  type CCIPRequest,
-  type ChainTransaction,
+  type Chain,
+  CCIPAPIClient,
   CCIPExecTxRevertedError,
+  CCIPMessageIdNotFoundError,
+  CCIPTransactionNotFoundError,
   ExecutionState,
   MessageStatus,
   bigIntReplacer,
   discoverOffRamp,
   isSupportedTxHash,
-  networkInfo,
 } from '@chainlink/ccip-sdk/src/index.ts'
+import { isHexString } from 'ethers'
 import type { Argv } from 'yargs'
 
 import type { GlobalOpts } from '../index.ts'
@@ -16,16 +39,16 @@ import { type Ctx, Format } from './types.ts'
 import {
   getCtx,
   logParsedError,
-  prettyCommit,
   prettyReceipt,
   prettyRequest,
   prettyTable,
+  prettyVerifications,
   selectRequest,
   withDateTimestamp,
 } from './utils.ts'
 import { fetchChainsFromRpcs } from '../providers/index.ts'
 
-export const command = ['show <tx-hash>', '* <tx-hash>']
+export const command = ['show <tx-hash-or-id>', '* <tx-hash-or-id>']
 export const describe = 'Show details of a CCIP request'
 
 /**
@@ -35,23 +58,18 @@ export const describe = 'Show details of a CCIP request'
  */
 export const builder = (yargs: Argv) =>
   yargs
-    .positional('tx-hash', {
+    .positional('tx-hash-or-id', {
       type: 'string',
       demandOption: true,
-      describe: 'transaction hash of the request (source) message',
+      describe: 'transaction hash or message ID (32-byte hex) of the CCIP request',
     })
-    .check(({ txHash }) => isSupportedTxHash(txHash))
+    .check(({ txHashOrId }) => isSupportedTxHash(txHashOrId))
     .options({
       'log-index': {
         type: 'number',
         describe:
           'Pre-select a message request by logIndex, if more than one in tx; by default, a selection menu is shown',
       },
-      'id-from-source': {
-        type: 'string',
-        describe:
-          'Search by messageId instead of txHash; requires `[onRamp@]sourceNetwork` (onRamp address may be required in some chains)',
-      },
       wait: {
         type: 'boolean',
         describe: 'Wait for (first) execution',
@@ -77,22 +95,42 @@ export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']>
  */
 export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
   const { logger } = ctx
-  let source, getChain, tx: ChainTransaction, request: CCIPRequest
-  // messageId not yet implemented for Solana
-  if (argv.idFromSource) {
-    getChain = fetchChainsFromRpcs(ctx, argv)
-    let idFromSource, onRamp
-    if (argv.idFromSource.includes('@')) {
-      ;[onRamp, idFromSource] = argv.idFromSource.split('@') as [string, string]
-    } else idFromSource = argv.idFromSource
-    const sourceNetwork = networkInfo(idFromSource)
-    source = await getChain(sourceNetwork.chainId)
-    request = await source.getMessageById(argv.txHash, { ...argv, onRamp })
-  } else {
-    const [getChain_, tx$] = fetchChainsFromRpcs(ctx, argv, argv.txHash)
-    getChain = getChain_
-    ;[source, tx] = await tx$
-    request = await selectRequest(await source.getMessagesInTx(tx), 'to know more', argv)
+  const [getChain, tx$] = fetchChainsFromRpcs(ctx, argv, argv.txHashOrId)
+
+  let source: Chain | undefined
+  let request$ = (async () => {
+    const [source_, tx] = await tx$
+    source = source_
+    return selectRequest(await source_.getMessagesInTx(tx), 'to know more', argv)
+  })()
+
+  if (argv.noApi !== true) {
+    const apiClient = CCIPAPIClient.fromUrl(undefined, ctx)
+    if (isHexString(argv.txHashOrId, 32)) {
+      request$ = Promise.any([request$, apiClient.getMessageById(argv.txHashOrId)])
+    }
+  }
+  let request
+  try {
+    request = await request$
+  } catch (err) {
+    if (err instanceof AggregateError && err.errors.length === 2) {
+      if (!(err.errors[0] instanceof CCIPTransactionNotFoundError)) throw err.errors[0] as Error
+      else if (!(err.errors[1] instanceof CCIPMessageIdNotFoundError)) throw err.errors[1] as Error
+    }
+    throw err
+  }
+  if (!source) {
+    try {
+      source = await getChain(request.lane.sourceChainSelector)
+    } catch (err) {
+      logger.debug(
+        'Fetched messageId from API, but failed find a source',
+        request.lane.sourceChainSelector,
+        'RPC endpoint:',
+        err,
+      )
+    }
   }
 
   switch (argv.format) {
@@ -101,7 +139,7 @@ export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]
       break
     }
     case Format.pretty:
-      await prettyRequest.call(ctx, source, request)
+      await prettyRequest.call(ctx, request, source)
       break
     case Format.json:
       logger.info(JSON.stringify(request, bigIntReplacer, 2))
@@ -112,6 +150,7 @@ export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]
       context: { error: request.tx.error },
     })
 
+  if (!source) return
   if (argv.wait === false) return // `false` used by call at end of `send` command without `--wait`
 
   let cancelWaitFinalized: (() => void) | undefined
@@ -152,15 +191,14 @@ export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]
 
   const dest = await getChain(request.lane.destChainSelector)
   const offRamp = await discoverOffRamp(source, dest, request.lane.onRamp, source)
-  const commitStore = await dest.getCommitStoreForOffRamp(offRamp)
 
-  let cancelWaitCommit: (() => void) | undefined
-  const commit$ = (async () => {
-    const commit = await dest.getCommitReport({
-      commitStore,
+  let cancelWaitVerifications: (() => void) | undefined
+  const verifications$ = (async () => {
+    const verifications = await dest.getVerifications({
+      offRamp,
       request,
       ...argv,
-      watch: argv.wait && new Promise<void>((resolve) => (cancelWaitCommit = resolve)),
+      watch: argv.wait && new Promise<void>((resolve) => (cancelWaitVerifications = resolve)),
     })
     cancelWaitFinalized?.()
     await finalized$
@@ -168,20 +206,23 @@ export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]
       logger.info(`[${MessageStatus.Committed}] Commit report accepted on destination chain`)
     switch (argv.format) {
       case Format.log:
-        logger.log('commit =', commit)
+        logger.log('commit =', verifications)
         break
       case Format.pretty:
-        await prettyCommit.call(ctx, dest, commit, request)
+        await prettyVerifications.call(ctx, dest, verifications, request)
         break
       case Format.json:
-        logger.info(JSON.stringify(commit, bigIntReplacer, 2))
+        logger.info(JSON.stringify(verifications, bigIntReplacer, 2))
         break
     }
     if (argv.wait)
       logger.info(`[${MessageStatus.Blessed}] Waiting for execution on destination chain...`)
     else logger.info('Receipts (dest):')
-    return commit
-  })()
+    return verifications
+  })().catch((err) => {
+    logger.debug('getVerifications error:', err)
+    return undefined
+  })
 
   let found = false
   for await (const receipt of dest.getExecutionReceipts({
@@ -190,11 +231,11 @@ export async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]
     messageId: request.message.messageId,
     sourceChainSelector: request.message.sourceChainSelector,
     startTime: request.tx.timestamp,
-    commit: !argv.wait ? await commit$ : undefined,
+    verifications: !argv.wait ? await verifications$ : undefined,
     watch: argv.wait && ctx.destroy$,
   })) {
-    cancelWaitCommit?.()
-    await commit$
+    cancelWaitVerifications?.()
+    await verifications$
     const status =
       receipt.receipt.state === ExecutionState.Success
         ? MessageStatus.Success

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'
+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'
 
@@ -66,6 +66,11 @@ export const builder = (yargs: Argv) =>
       demandOption: false,
       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',
@@ -103,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:
@@ -117,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),
@@ -143,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) {