@chainlink/ccip-cli 0.91.0 → 0.92.0

package/src/commands/utils.ts

@@ -5,9 +5,11 @@ import {
   type CCIPExecution,
   type CCIPRequest,
   type Chain,
+  type ChainFamily,
   type ChainStatic,
   type Lane,
-  type OffchainTokenData,
+  CCIPError,
+  CCIPErrorCode,
   ExecutionState,
   networkInfo,
   supportedChains,
@@ -46,7 +48,7 @@ export async function selectRequest(
     choices: [
       ...requests.map((req, i) => ({
         value: i,
-        name: `${req.log.index} => ${req.message.header.messageId}`,
+        name: `${req.log.index} => ${req.message.messageId}`,
         description:
           `sender =\t\t${req.message.sender}
 receiver =\t\t${req.message.receiver}
@@ -63,7 +65,7 @@ tokenTransfers =\t[${req.message.tokenAmounts.map((ta) => ('token' in ta ? ta.to
       },
     ],
   })
-  if (answer < 0) throw new Error('User requested exit')
+  if (answer < 0) throw new CCIPError(CCIPErrorCode.UNKNOWN, 'User requested exit')
   return requests[answer]
 }
 
@@ -93,10 +95,33 @@ export function prettyLane(this: Ctx, lane: Lane) {
     name: { source: source.name, dest: dest.name },
     chainId: { source: source.chainId, dest: dest.chainId },
     chainSelector: { source: source.chainSelector, dest: dest.chainSelector },
-    'onRamp/version': { source: lane.onRamp, dest: lane.version },
+    'onRamp/version': {
+      source: formatDisplayAddress(lane.onRamp, source.family),
+      dest: lane.version,
+    },
   })
 }
 
+/**
+ * Format an address for display using chain-specific formatting.
+ * @param address - Address string
+ * @param family - Chain family for formatting
+ * @returns Formatted address for display
+ */
+export function formatDisplayAddress(address: string, family: ChainFamily): string {
+  return supportedChains[family]?.formatAddress?.(address) ?? address
+}
+
+/**
+ * Format a transaction hash for display using chain-specific formatting.
+ * @param hash - Transaction hash string
+ * @param family - Chain family for formatting
+ * @returns Formatted hash for display
+ */
+export function formatDisplayTxHash(hash: string, family: ChainFamily): string {
+  return supportedChains[family]?.formatTxHash?.(hash) ?? hash
+}
+
 async function formatToken(
   source: Chain,
   ta: { amount: bigint } & ({ token: string } | { sourcePoolAddress: string }),
@@ -159,7 +184,7 @@ function formatDate(timestamp: number) {
 /**
  * Formats duration in seconds to human-readable string.
  * @param secs - Duration in seconds.
- * @returns Formatted duration string (e.g., "1h 30m").
+ * @returns Formatted duration string (e.g., "2d 1h30m").
  */
 export function formatDuration(secs: number) {
   if (secs < 0) secs = -secs
@@ -174,7 +199,7 @@ export function formatDuration(secs: number) {
   }
   return Object.entries(time)
     .filter((val) => val[1] !== 0)
-    .map(([key, val]) => `${val}${key}${key === 'd' ? ' ' : ''}`)
+    .map(([key, val], i, arr) => `${val}${key}${key === 'd' && i < arr.length - 1 ? ' ' : ''}`)
     .join('')
 }
 
@@ -193,14 +218,8 @@ function omit<T extends Record<string, unknown>, K extends string>(
  * Prints a CCIP request in a human-readable format.
  * @param source - Source chain instance.
  * @param request - CCIP request to print.
- * @param offchainTokenData - Optional offchain token data.
  */
-export async function prettyRequest(
-  this: Ctx,
-  source: Chain,
-  request: CCIPRequest,
-  offchainTokenData?: OffchainTokenData[],
-) {
+export async function prettyRequest(this: Ctx, source: Chain, request: CCIPRequest) {
   prettyLane.call(this, request.lane)
   this.logger.info('Request (source):')
 
@@ -210,11 +229,24 @@ export async function prettyRequest(
   } catch (_) {
     // no finalized tag support
   }
-  const nonce = Number(request.message.header.nonce)
+  const nonce = Number(request.message.nonce)
+
+  const sourceFamily = networkInfo(request.lane.sourceChainSelector).family
+  const destFamily = networkInfo(request.lane.destChainSelector).family
+
+  // Normalize receiver to destination chain format for display
+  const displaySender = formatDisplayAddress(request.message.sender, sourceFamily)
+  const displayReceiver = formatDisplayAddress(request.message.receiver, destFamily)
+  const displayOrigin = request.tx.from
+    ? formatDisplayAddress(request.tx.from, sourceFamily)
+    : undefined
+  const displayTxHash = formatDisplayTxHash(request.log.transactionHash, sourceFamily)
 
   const rest = omit(
     request.message,
-    'header',
+    'messageId',
+    'sequenceNumber',
+    'nonce',
     'sender',
     'receiver',
     'tokenAmounts',
@@ -223,22 +255,23 @@ export async function prettyRequest(
     'feeTokenAmount',
     'sourceTokenData',
     'sourceChainSelector',
+    'destChainSelector',
     'extraArgs',
     'accounts',
   )
   prettyTable.call(this, {
-    messageId: request.message.header.messageId,
-    ...(request.tx.from ? { origin: request.tx.from } : {}),
-    sender: request.message.sender,
-    receiver: request.message.receiver,
-    sequenceNumber: Number(request.message.header.sequenceNumber),
+    messageId: request.message.messageId,
+    ...(displayOrigin ? { origin: displayOrigin } : {}),
+    sender: displaySender,
+    receiver: displayReceiver,
+    sequenceNumber: Number(request.message.sequenceNumber),
     nonce: nonce === 0 ? '0 => allow out-of-order exec' : nonce,
     ...('gasLimit' in request.message
       ? { gasLimit: Number(request.message.gasLimit) }
       : 'computeUnits' in request.message
         ? { computeUnits: Number(request.message.computeUnits) }
         : {}),
-    transactionHash: request.log.transactionHash,
+    transactionHash: displayTxHash,
     logIndex: request.log.index,
     blockNumber: request.log.blockNumber,
     timestamp: `${formatDate(request.tx.timestamp)} (${formatDuration(Date.now() / 1e3 - request.tx.timestamp)} ago)`,
@@ -263,13 +296,6 @@ export async function prettyRequest(
     ...('accounts' in request.message ? formatArray('accounts', request.message.accounts) : {}),
     ...rest,
   })
-
-  if (!offchainTokenData?.length || offchainTokenData.every((d) => !d)) return
-  this.logger.info('Attestations:')
-  for (const attestation of offchainTokenData) {
-    const { _tag: type, ...rest } = attestation!
-    prettyTable.call(this, { type, ...rest })
-  }
 }
 
 /**
@@ -282,17 +308,19 @@ export async function prettyCommit(
   this: Ctx,
   dest: Chain,
   commit: CCIPCommit,
-  request: PickDeep<CCIPRequest, 'tx.timestamp'>,
+  request: PickDeep<CCIPRequest, 'tx.timestamp' | 'lane.destChainSelector'>,
 ) {
-  this.logger.info('Commit (dest):')
   const timestamp = await dest.getBlockTimestamp(commit.log.blockNumber)
+  const destFamily = networkInfo(request.lane.destChainSelector).family
+  const origin = commit.log.tx?.from ?? (await dest.getTransaction(commit.log.transactionHash)).from
+
   prettyTable.call(this, {
     merkleRoot: commit.report.merkleRoot,
     min: Number(commit.report.minSeqNr),
     max: Number(commit.report.maxSeqNr),
-    origin: commit.log.tx?.from ?? (await dest.getTransaction(commit.log.transactionHash)).from,
-    contract: commit.log.address,
-    transactionHash: commit.log.transactionHash,
+    origin: formatDisplayAddress(origin, destFamily),
+    contract: formatDisplayAddress(commit.log.address, destFamily),
+    transactionHash: formatDisplayTxHash(commit.log.transactionHash, destFamily),
     blockNumber: commit.log.blockNumber,
     timestamp: `${formatDate(timestamp)} (${formatDuration(timestamp - request.tx.timestamp)} after request)`,
   })
@@ -396,9 +424,11 @@ export function prettyTable(
 export function prettyReceipt(
   this: Ctx,
   receipt: CCIPExecution,
-  request: PickDeep<CCIPRequest, 'tx.timestamp'>,
+  request: PickDeep<CCIPRequest, 'tx.timestamp' | 'lane.destChainSelector'>,
   origin?: string,
 ) {
+  const destFamily = networkInfo(request.lane.destChainSelector).family
+
   prettyTable.call(this, {
     state: receipt.receipt.state === ExecutionState.Success ? '✅ success' : '❌ failed',
     ...(receipt.receipt.state !== ExecutionState.Success ||
@@ -406,34 +436,79 @@ export function prettyReceipt(
       ? { returnData: receipt.receipt.returnData }
       : {}),
     ...(receipt.receipt.gasUsed ? { gasUsed: Number(receipt.receipt.gasUsed) } : {}),
-    ...(origin ? { origin } : {}),
-    contract: receipt.log.address,
-    transactionHash: receipt.log.transactionHash,
+    ...(origin ? { origin: formatDisplayAddress(origin, destFamily) } : {}),
+    contract: formatDisplayAddress(receipt.log.address, destFamily),
+    transactionHash: formatDisplayTxHash(receipt.log.transactionHash, destFamily),
     logIndex: receipt.log.index,
     blockNumber: receipt.log.blockNumber,
     timestamp: `${formatDate(receipt.timestamp)} (${formatDuration(receipt.timestamp - request.tx.timestamp)} after request)`,
   })
 }
 
+/**
+ * Format a CCIPError with recovery hints for user-friendly display.
+ * @param err - Error to format.
+ * @param verbose - If true, include stack trace for debugging.
+ * @returns Formatted error string if CCIPError, null otherwise.
+ */
+export function formatCCIPError(err: unknown, verbose = false): string | null {
+  if (!CCIPError.isCCIPError(err)) return null
+
+  const lines: string[] = []
+
+  lines.push(`error[${err.code}]: ${err.message}`)
+
+  if (err.recovery) {
+    lines.push(`  help: ${err.recovery}`)
+  }
+
+  if (err.isTransient) {
+    let note = 'this error may resolve on retry'
+    if (err.retryAfterMs) {
+      note += ` (wait ${Math.round(err.retryAfterMs / 1000)}s)`
+    }
+    lines.push(`  note: ${note}`)
+  }
+
+  if (verbose && err.stack) {
+    lines.push('')
+    lines.push('  Stack trace:')
+    const stackLines = err.stack.split('\n').slice(1)
+    for (const line of stackLines) {
+      lines.push(`  ${line}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
 /**
  * Logs a parsed error message if the error can be decoded.
  * @param err - Error to parse and log.
  * @returns True if error was successfully parsed and logged.
  */
 export function logParsedError(this: Ctx, err: unknown): boolean {
+  // First check if it's a CCIPError with recovery hints
+  const formatted = formatCCIPError(err, this.verbose)
+  if (formatted) {
+    this.logger.error(formatted)
+    return true
+  }
+
+  // Then try chain-specific parsing for revert data
   for (const chain of Object.values<ChainStatic>(supportedChains)) {
     const parsed = chain.parse?.(err)
     if (!parsed) continue
     const { method, Instruction: instruction, ...rest } = parsed
     if (method || instruction) {
       this.logger.error(
-        `🛑 Failed to call "${(method || instruction) as string}"`,
+        `error: Failed to call "${(method || instruction) as string}"`,
         ...Object.entries(rest)
           .map(([k, e]) => [`\n${k.substring(0, 1).toUpperCase()}${k.substring(1)} =`, e])
           .flat(1),
       )
     } else {
-      this.logger.error('🛑 Error:', parsed)
+      this.logger.error('error:', parsed)
     }
     return true
   }
@@ -475,9 +550,9 @@ export async function* yieldResolved<T>(promises: readonly Promise<T>[]): AsyncG
  * @param argv - yargs argv containing verbose flag
  * @returns AbortController and context object with destroy$ signal and logger
  */
-export function getCtx(argv: { verbose?: boolean }): [controller: AbortController, ctx: Ctx] {
-  const controller = new AbortController()
-  const destroy$ = controller.signal
+export function getCtx(argv: { verbose?: boolean }): [ctx: Ctx, destroy: () => void] {
+  let destroy
+  const destroy$ = new Promise<void>((resolve) => (destroy = resolve))
 
   const logger = new Console(process.stdout, process.stderr, true)
   if (argv.verbose) {
@@ -486,5 +561,5 @@ export function getCtx(argv: { verbose?: boolean }): [controller: AbortControlle
     logger.debug = () => {}
   }
 
-  return [controller, { destroy$, logger }]
+  return [{ destroy$, logger, verbose: argv.verbose }, destroy!]
 }

package/src/index.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { realpathSync } from 'fs'
 import util from 'node:util'
+import { pathToFileURL } from 'url'
 
-import yargs, { type InferredOptionTypes } from 'yargs'
+import yargs, { type ArgumentsCamelCase, type InferredOptionTypes } from 'yargs'
 import { hideBin } from 'yargs/helpers'
 
 import { Format } from './commands/index.ts'
@@ -9,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.91.0-b8bd948'
+const VERSION = '0.92.0-bbb73be'
 // generate:end
 
 const globalOpts = {
   rpcs: {
     type: 'array',
-    alias: 'r',
+    alias: ['r', 'rpc'],
     describe: 'List of RPC endpoint URLs, ws[s] or http[s]',
     string: true,
   },
@@ -44,7 +46,7 @@ const globalOpts = {
 } as const
 
 /** Type for global CLI options. */
-export type GlobalOpts = InferredOptionTypes<typeof globalOpts>
+export type GlobalOpts = ArgumentsCamelCase<InferredOptionTypes<typeof globalOpts>>
 
 async function main() {
   await yargs(hideBin(process.argv))
@@ -63,7 +65,13 @@ async function main() {
     .parse()
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+function wasCalledAsScript() {
+  const realPath = realpathSync(process.argv[1])
+  const realPathAsUrl = pathToFileURL(realPath).href
+  return import.meta.url === realPathAsUrl
+}
+
+if (import.meta?.main || wasCalledAsScript()) {
   const later = setTimeout(() => {}, 2 ** 31 - 1) // keep event-loop alive
   await main()
     .catch((err) => {

package/src/providers/aptos.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from 'node:fs'
-import util from 'node:util'
 
 import {
   type AccountAddress,
@@ -12,6 +11,7 @@ import {
   Ed25519Signature,
   generateSigningMessageForTransaction,
 } from '@aptos-labs/ts-sdk'
+import { CCIPArgumentInvalidError } from '@chainlink/ccip-sdk/src/index.ts'
 import AptosLedger from '@ledgerhq/hw-app-aptos'
 import HIDTransport from '@ledgerhq/hw-transport-node-hid'
 import { type BytesLike, getBytes, hexlify } from 'ethers'
@@ -98,9 +98,7 @@ export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
  * @returns Promise to AptosAsyncAccount instance
  */
 export async function loadAptosWallet({ wallet: walletOpt }: { wallet?: unknown }) {
-  if (!walletOpt) walletOpt = process.env['USER_KEY'] || process.env['OWNER_KEY']
-  if (typeof walletOpt !== 'string')
-    throw new Error(`Invalid wallet option: ${util.inspect(walletOpt)}`)
+  if (typeof walletOpt !== 'string') throw new CCIPArgumentInvalidError('wallet', String(walletOpt))
   if ((walletOpt ?? '').startsWith('ledger')) {
     let derivationPath = walletOpt.split(':')[1]
     if (!derivationPath) derivationPath = "m/44'/637'/0'/0'/0'"
@@ -121,5 +119,5 @@ export async function loadAptosWallet({ wallet: walletOpt }: { wallet?: unknown
       privateKey: new Ed25519PrivateKey(walletOpt as string, false),
     })
   }
-  throw new Error('Wallet not specified')
+  throw new CCIPArgumentInvalidError('wallet', 'not specified')
 }

package/src/providers/evm.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
-import util from 'util'
 
+import { CCIPArgumentInvalidError } from '@chainlink/ccip-sdk/src/index.ts'
 import { LedgerSigner } from '@ethers-ext/signer-ledger'
 import { password } from '@inquirer/prompts'
 import HIDTransport from '@ledgerhq/hw-transport-node-hid'
@@ -31,7 +31,6 @@ export async function loadEvmWallet(
   provider: JsonRpcApiProvider,
   { wallet: walletOpt }: { wallet?: unknown },
 ): Promise<Signer> {
-  if (!walletOpt) walletOpt = process.env['USER_KEY'] || process.env['OWNER_KEY']
   if (
     typeof walletOpt === 'number' ||
     (typeof walletOpt === 'string' && walletOpt.match(/^(\d+|0x[a-fA-F0-9]{40})$/))
@@ -43,8 +42,7 @@ export async function loadEvmWallet(
         : Number(walletOpt),
     )
   }
-  if (typeof walletOpt !== 'string')
-    throw new Error(`Invalid wallet option: ${util.inspect(walletOpt)}`)
+  if (typeof walletOpt !== 'string') throw new CCIPArgumentInvalidError('wallet', String(walletOpt))
   if ((walletOpt ?? '').startsWith('ledger')) {
     let derivationPath = walletOpt.split(':')[1]
     if (derivationPath && !isNaN(Number(derivationPath)))