@chainlink/ccip-cli 0.96.0 → 0.97.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chainlink/ccip-cli",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "CCIP Command Line Interface, based on @chainlink/ccip-sdk",
   "author": "Chainlink devs",
   "license": "MIT",
@@ -31,27 +31,27 @@
     "!**/__mocks__"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@types/node": "25.2.2",
+    "@eslint/js": "^9.39.3",
+    "@types/node": "25.3.0",
     "@types/yargs": "17.0.35",
-    "eslint": "^9.39.2",
+    "eslint": "^9.39.3",
     "eslint-config-prettier": "10.1.8",
     "eslint-import-resolver-typescript": "4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsdoc": "^62.5.4",
+    "eslint-plugin-jsdoc": "^62.7.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-tsdoc": "^0.5.0",
     "prettier": "^3.8.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.55.0"
+    "typescript-eslint": "8.56.0"
   },
   "dependencies": {
     "@aptos-labs/ts-sdk": "^5.2.1",
-    "@chainlink/ccip-sdk": "^0.96.0",
+    "@chainlink/ccip-sdk": "^0.97.0",
     "@coral-xyz/anchor": "^0.29.0",
     "@ethers-ext/signer-ledger": "^6.0.0-beta.1",
-    "@inquirer/prompts": "8.2.0",
+    "@inquirer/prompts": "8.3.0",
     "@ledgerhq/hw-app-aptos": "^6.35.0",
     "@ledgerhq/hw-app-solana": "^7.7.0",
     "@ledgerhq/hw-transport-node-hid": "^6.30.0",

package/src/commands/lane-latency.ts

@@ -1,3 +1,21 @@
+/**
+ * CCIP CLI Lane Latency Command
+ *
+ * Queries real-time lane latency statistics between source and destination chains
+ * using the CCIP API. Shows average, median, and percentile latencies.
+ *
+ * @example
+ * ```bash
+ * # Get latency between Ethereum and Arbitrum
+ * ccip-cli laneLatency ethereum-mainnet arbitrum-mainnet
+ *
+ * # Use custom API URL
+ * ccip-cli laneLatency sepolia fuji --api-url https://custom-api.example.com
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 import {
   CCIPAPIClient,
   CCIPApiClientNotAvailableError,
@@ -67,7 +85,7 @@ export async function getLaneLatencyCmd(ctx: Ctx, argv: Parameters<typeof handle
   const sourceNetwork = networkInfo(argv.source)
   const destNetwork = networkInfo(argv.dest)
 
-  const apiClient = new CCIPAPIClient(argv.apiUrl, { logger })
+  const apiClient = CCIPAPIClient.fromUrl(argv.apiUrl, { logger })
 
   const result = await apiClient.getLaneLatency(
     sourceNetwork.chainSelector,

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'
@@ -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,

package/src/commands/send.ts

@@ -1,3 +1,24 @@
+/**
+ * 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,
@@ -327,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