@chainlink/ccip-cli 0.91.1 → 0.92.0

package/src/commands/parse.ts

@@ -1,9 +1,13 @@
-import { bigIntReplacer, supportedChains } from '@chainlink/ccip-sdk/src/index.ts'
+import {
+  CCIPDataParseError,
+  bigIntReplacer,
+  supportedChains,
+} from '@chainlink/ccip-sdk/src/index.ts'
 import type { Argv } from 'yargs'
 
 import type { GlobalOpts } from '../index.ts'
 import { type Ctx, Format } from './types.ts'
-import { getCtx, prettyTable } from './utils.ts'
+import { getCtx, logParsedError, prettyTable } from './utils.ts'
 
 export const command = ['parse <data>', 'parseBytes <data>', 'parseData <data>']
 export const describe =
@@ -26,12 +30,12 @@ export const builder = (yargs: Argv) =>
  * @param argv - Command line arguments.
  */
 export function handler(argv: Awaited<ReturnType<typeof builder>['argv']> & GlobalOpts) {
-  const [, ctx] = getCtx(argv)
+  const [ctx] = getCtx(argv)
   try {
     parseBytes(ctx, argv)
   } catch (err) {
     process.exitCode = 1
-    ctx.logger.error(err)
+    if (!logParsedError.call(ctx, err)) ctx.logger.error(err)
   }
 }
 
@@ -46,7 +50,7 @@ function parseBytes(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
       // pass
     }
   }
-  if (!parsed) throw new Error('Unknown data')
+  if (!parsed) throw new CCIPDataParseError(argv.data)
 
   switch (argv.format) {
     case Format.log: {

package/src/commands/send.ts

@@ -4,8 +4,10 @@ import {
   type ChainStatic,
   type EVMChain,
   type ExtraArgs,
+  CCIPArgumentInvalidError,
+  CCIPChainFamilyUnsupportedError,
+  CCIPTokenNotFoundError,
   ChainFamily,
-  bigIntReplacer,
   estimateExecGasForRequest,
   getDataBytes,
   networkInfo,
@@ -15,14 +17,9 @@ import { type BytesLike, dataLength, formatUnits, toUtf8Bytes } from 'ethers'
 import type { Argv } from 'yargs'
 
 import type { GlobalOpts } from '../index.ts'
-import { type Ctx, Format } from './types.ts'
-import {
-  getCtx,
-  logParsedError,
-  parseTokenAmounts,
-  prettyRequest,
-  withDateTimestamp,
-} from './utils.ts'
+import { showRequests } from './show.ts'
+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>'
@@ -127,6 +124,11 @@ export const builder = (yargs: Argv) =>
         describe:
           "Approve the maximum amount of tokens to transfer; default=false approves only what's needed",
       },
+      wait: {
+        type: 'boolean',
+        default: false,
+        describe: 'Wait for execution',
+      },
     })
     .check(
       ({ 'transfer-tokens': transferTokens }) =>
@@ -138,13 +140,13 @@ export const builder = (yargs: Argv) =>
  * @param argv - Command line arguments.
  */
 export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']> & GlobalOpts) {
-  const [controller, ctx] = getCtx(argv)
+  const [ctx, destroy] = getCtx(argv)
   return sendMessage(ctx, argv)
     .catch((err) => {
       process.exitCode = 1
       if (!logParsedError.call(ctx, err)) ctx.logger.error(err)
     })
-    .finally(() => controller.abort('Exited'))
+    .finally(destroy)
 }
 
 async function sendMessage(
@@ -185,7 +187,10 @@ async function sendMessage(
       tokenReceiver = receiver
       receiver = '11111111111111111111111111111111'
     } else {
-      throw new Error('--token-receiver is required when sending tokens with data')
+      throw new CCIPArgumentInvalidError(
+        'token-receiver',
+        'required when sending tokens with data to Solana',
+      )
     }
 
     if (argv.account) {
@@ -198,13 +203,16 @@ async function sendMessage(
       })
     } else accounts = [] as string[]
   } else if (argv.tokenReceiver || argv.account?.length) {
-    throw new Error('--token-receiver and --account intended only for Solana dest')
+    throw new CCIPArgumentInvalidError(
+      'token-receiver/account',
+      'only valid for Solana destination',
+    )
   }
 
   let walletAddress, wallet
   if (!receiver) {
     if (sourceNetwork.family !== destNetwork.family)
-      throw new Error('--receiver is required when sending to a different chain family')
+      throw new CCIPArgumentInvalidError('receiver', 'required for cross-family transfers')
     ;[walletAddress, wallet] = await loadChainWallet(source, argv)
     receiver = walletAddress // send to self if same family
   }
@@ -212,7 +220,9 @@ async function sendMessage(
   if (argv.estimateGasLimit != null || argv.onlyEstimate) {
     // TODO: implement for all chain families
     if (destNetwork.family !== ChainFamily.EVM)
-      throw new Error(`Estimating gasLimit supported only on EVM, got=${destNetwork.family}`)
+      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 = {
@@ -270,7 +280,7 @@ async function sendMessage(
         feeTokenInfo = info
         break
       }
-      if (!feeTokenInfo) throw new Error(`Fee token "${argv.feeToken}" not found`)
+      if (!feeTokenInfo) throw new CCIPTokenNotFoundError(argv.feeToken)
     }
   } else {
     const nativeToken = await source.getNativeTokenForRouter(argv.router)
@@ -316,18 +326,16 @@ async function sendMessage(
     ', tx =>',
     request.tx.hash,
     ', messageId =>',
-    request.message.header.messageId,
+    request.message.messageId,
   )
 
-  switch (argv.format) {
-    case Format.log:
-      logger.log(`message ${request.log.index} =`, withDateTimestamp(request))
-      break
-    case Format.pretty:
-      await prettyRequest.call(ctx, source, request)
-      break
-    case Format.json:
-      logger.info(JSON.stringify(request, bigIntReplacer, 2))
-      break
-  }
+  await showRequests(ctx, {
+    ...argv,
+    txHash: request.tx.hash,
+    'tx-hash': request.tx.hash,
+    'id-from-source': undefined,
+    idFromSource: undefined,
+    'log-index': undefined,
+    logIndex: undefined,
+  })
 }

package/src/commands/show.ts

@@ -1,10 +1,11 @@
-import util from 'util'
-
 import {
   type CCIPRequest,
   type ChainTransaction,
+  CCIPExecTxRevertedError,
+  CCIPNotImplementedError,
   bigIntReplacer,
   discoverOffRamp,
+  isSupportedTxHash,
   networkInfo,
 } from '@chainlink/ccip-sdk/src/index.ts'
 import type { Argv } from 'yargs'
@@ -17,6 +18,7 @@ import {
   prettyCommit,
   prettyReceipt,
   prettyRequest,
+  prettyTable,
   selectRequest,
   withDateTimestamp,
 } from './utils.ts'
@@ -37,6 +39,7 @@ export const builder = (yargs: Argv) =>
       demandOption: true,
       describe: 'transaction hash of the request (source) message',
     })
+    .check(({ txHash }) => isSupportedTxHash(txHash))
     .options({
       'log-index': {
         type: 'number',
@@ -48,6 +51,10 @@ export const builder = (yargs: Argv) =>
         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',
+      },
     })
 
 /**
@@ -55,16 +62,19 @@ export const builder = (yargs: Argv) =>
  * @param argv - Command line arguments.
  */
 export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']> & GlobalOpts) {
-  const [controller, ctx] = getCtx(argv)
+  const [ctx, destroy] = getCtx(argv)
   return showRequests(ctx, argv)
     .catch((err) => {
       process.exitCode = 1
       if (!logParsedError.call(ctx, err)) ctx.logger.error(err)
     })
-    .finally(() => controller.abort('Exited'))
+    .finally(destroy)
 }
 
-async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
+/**
+ * Show details of a request.
+ */
+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
@@ -77,7 +87,7 @@ async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
     const sourceNetwork = networkInfo(idFromSource)
     source = await getChain(sourceNetwork.chainId)
     if (!source.fetchRequestById)
-      throw new Error(`fetchRequestById not implemented for ${source.constructor.name}`)
+      throw new CCIPNotImplementedError(`fetchRequestById for ${source.constructor.name}`)
     request = await source.fetchRequestById(argv.txHash, onRamp, argv)
   } else {
     const [getChain_, tx$] = fetchChainsFromRpcs(ctx, argv, argv.txHash)
@@ -86,52 +96,104 @@ async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
     request = await selectRequest(await source.fetchRequestsInTx(tx), 'to know more', argv)
   }
 
-  const offchainTokenData = await source.fetchOffchainTokenData(request)
-
   switch (argv.format) {
     case Format.log: {
-      logger.log(
-        `message ${request.log.index} =`,
-        withDateTimestamp(request),
-        '\nattestations =',
-        offchainTokenData,
-      )
+      logger.log(`message ${request.log.index} =`, withDateTimestamp(request))
       break
     }
     case Format.pretty:
-      await prettyRequest.call(ctx, source, request, offchainTokenData)
+      await prettyRequest.call(ctx, source, request)
       break
     case Format.json:
-      logger.info(JSON.stringify({ ...request, offchainTokenData }, bigIntReplacer, 2))
+      logger.info(JSON.stringify(request, bigIntReplacer, 2))
       break
   }
-  if (request.tx.error) throw new Error(`Request tx reverted: ${util.inspect(request.tx.error)}`)
+  if (request.tx.error)
+    throw new CCIPExecTxRevertedError(request.log.transactionHash, {
+      context: { error: request.tx.error },
+    })
+
+  if (argv.wait === false) return // `false` used by call at end of `send` command without `--wait`
+
+  let cancelWaitFinalized: (() => void) | undefined
+  const finalized$ = (async () => {
+    if (argv.wait) {
+      logger.info('Waiting for finalization...')
+      await source.waitFinalized(
+        request,
+        undefined,
+        new Promise<void>((resolve) => (cancelWaitFinalized = resolve)),
+      )
+      logger.info(`Transaction "${request.log.transactionHash}" finalized ✅`)
+    }
+
+    const offchainTokenData = await source.fetchOffchainTokenData(request)
+    if (offchainTokenData?.length && offchainTokenData.some((d) => !!d)) {
+      switch (argv.format) {
+        case Format.log: {
+          logger.log('attestations =', offchainTokenData)
+          break
+        }
+        case Format.pretty:
+          logger.info('Attestations:')
+          for (const attestation of offchainTokenData) {
+            const { _tag: type, ...rest } = attestation!
+            prettyTable.call(ctx, { type, ...rest })
+          }
+          break
+        case Format.json:
+          logger.info(JSON.stringify({ attestations: offchainTokenData }, bigIntReplacer, 2))
+          break
+      }
+    }
+
+    if (argv.wait) logger.info('Waiting for Commit (dest)...')
+    else logger.info('Commit (dest):')
+  })()
 
   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.fetchCommitReport(commitStore, request, argv)
-  switch (argv.format) {
-    case Format.log:
-      logger.log('commit =', commit)
-      break
-    case Format.pretty:
-      await prettyCommit.call(ctx, dest, commit, request)
-      break
-    case Format.json:
-      logger.info(JSON.stringify(commit, bigIntReplacer, 2))
-      break
-  }
+  let cancelWaitCommit: (() => void) | undefined
+  const commit$ = (async () => {
+    const commit = await dest.fetchCommitReport(commitStore, request, {
+      ...argv,
+      watch: argv.wait && new Promise<void>((resolve) => (cancelWaitCommit = resolve)),
+    })
+    cancelWaitFinalized?.()
+    if (!commit) return
+    await finalized$
+    switch (argv.format) {
+      case Format.log:
+        logger.log('commit =', commit)
+        break
+      case Format.pretty:
+        await prettyCommit.call(ctx, dest, commit, request)
+        break
+      case Format.json:
+        logger.info(JSON.stringify(commit, bigIntReplacer, 2))
+        break
+    }
+    if (argv.wait) logger.info('Waiting for Receipt (dest):')
+    else logger.info('Receipts (dest):')
+    return commit
+  })()
 
   let found = false
-  for await (const receipt of dest.fetchExecutionReceipts(offRamp, request, commit, argv)) {
+  for await (const receipt of dest.fetchExecutionReceipts(
+    offRamp,
+    request,
+    !argv.wait ? await commit$ : undefined,
+    { ...argv, watch: argv.wait && ctx.destroy$ },
+  )) {
+    cancelWaitCommit?.()
+    await commit$
     switch (argv.format) {
       case Format.log:
         logger.log('receipt =', withDateTimestamp(receipt))
         break
       case Format.pretty:
-        if (!found) logger.info('Receipts (dest):')
         prettyReceipt.call(
           ctx,
           receipt,
@@ -145,6 +207,7 @@ async function showRequests(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
         break
     }
     found = true
+    if (argv.wait) break
   }
   if (!found) logger.warn(`No execution receipt found for request`)
 }

package/src/commands/supported-tokens.ts

@@ -24,6 +24,7 @@
 import {
   type Chain,
   type RateLimiterState,
+  CCIPTokenNotConfiguredError,
   bigIntReplacer,
   networkInfo,
 } from '@chainlink/ccip-sdk/src/index.ts'
@@ -70,13 +71,13 @@ export const builder = (yargs: Argv) =>
  * @param argv - Command line arguments.
  */
 export async function handler(argv: Awaited<ReturnType<typeof builder>['argv']> & GlobalOpts) {
-  const [controller, ctx] = getCtx(argv)
+  const [ctx, destroy] = getCtx(argv)
   return getSupportedTokens(ctx, argv)
     .catch((err) => {
       process.exitCode = 1
       if (!logParsedError.call(ctx, err)) ctx.logger.error(err)
     })
-    .finally(() => controller.abort('Exited'))
+    .finally(destroy)
 }
 
 async function getSupportedTokens(ctx: Ctx, argv: Parameters<typeof handler>[0]) {
@@ -111,8 +112,7 @@ async function getSupportedTokens(ctx: Ctx, argv: Parameters<typeof handler>[0])
     if (!info) return // format != pretty
     registryConfig = await source.getRegistryTokenConfig(registry, info.token)
     tokenPool = registryConfig.tokenPool
-    if (!tokenPool)
-      throw new Error(`TokenPool not set in tokenAdminRegistry=${registry} for token=${info.token}`)
+    if (!tokenPool) throw new CCIPTokenNotConfiguredError(info.token, registry)
     poolConfigs = await source.getTokenPoolConfigs(tokenPool)
   } else {
     if (!argv.token) {
@@ -131,10 +131,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 Error(
-          `TokenPool not set in tokenAdminRegistry=${registry} for token=${argv.token}`,
-        )
+      if (!tokenPool) throw new CCIPTokenNotConfiguredError(argv.token, registry)
       poolConfigs = await source.getTokenPoolConfigs(tokenPool)
     }
 
@@ -212,7 +209,7 @@ async function listTokens({ logger }: Ctx, source: Chain, registry: string, argv
   if (argv.format !== Format.pretty) return // Format.pretty interactive search and details
 
   return search({
-    message: 'Select a token to know more:',
+    message: 'Select a supported token to know more:',
     pageSize: 20,
     source: (term) => {
       const filtered = infos.filter(

package/src/commands/types.ts

@@ -13,9 +13,10 @@ export type Format = (typeof Format)[keyof typeof Format]
  * Command context
  */
 export type Ctx = {
-  destroy$: AbortSignal
+  destroy$: Promise<unknown>
   logger: Logger & {
-    table: (tabularData: unknown, properties?: readonly string[]) => void
+    table: (tabularData: unknown, properties?: string[]) => void
     log: (...args: unknown[]) => void
   }
+  verbose?: boolean
 }