@chainlink/ccip-cli 0.90.2 → 0.91.0

package/src/commands/utils.ts

@@ -1,3 +1,5 @@
+import { Console } from 'node:console'
+
 import {
   type CCIPCommit,
   type CCIPExecution,
@@ -21,7 +23,17 @@ import {
   parseUnits,
   toUtf8String,
 } from 'ethers'
+import type { PickDeep } from 'type-fest'
+
+import type { Ctx } from './types.ts'
 
+/**
+ * Prompts user to select a CCIP request from a list.
+ * @param requests - List of CCIP requests to choose from.
+ * @param promptSuffix - Optional suffix for the prompt message.
+ * @param hints - Optional hints for pre-filtering requests.
+ * @returns Selected CCIP request.
+ */
 export async function selectRequest(
   requests: readonly CCIPRequest[],
   promptSuffix?: string,
@@ -55,17 +67,29 @@ tokenTransfers =\t[${req.message.tokenAmounts.map((ta) => ('token' in ta ? ta.to
   return requests[answer]
 }
 
-export function withDateTimestamp<T extends { readonly timestamp: number }>(
-  obj: T,
-): Omit<T, 'timestamp'> & { timestamp: Date } {
-  return { ...obj, timestamp: new Date(obj.timestamp * 1e3) }
+/**
+ * Converts a Unix timestamp to a Date object.
+ * @param obj - Object with timestamp property.
+ * @returns Object with Date timestamp.
+ */
+export function withDateTimestamp<
+  T extends { readonly timestamp: number } | { readonly tx: { readonly timestamp: number } },
+>(obj: T): Omit<T, 'timestamp'> & { timestamp: Date } {
+  return {
+    ...obj,
+    timestamp: new Date(('timestamp' in obj ? obj.timestamp : obj.tx.timestamp) * 1e3),
+  }
 }
 
-export function prettyLane(lane: Lane) {
-  console.info('Lane:')
+/**
+ * Prints lane information in a human-readable format.
+ * @param lane - Lane configuration.
+ */
+export function prettyLane(this: Ctx, lane: Lane) {
+  this.logger.info('Lane:')
   const source = networkInfo(lane.sourceChainSelector),
     dest = networkInfo(lane.destChainSelector)
-  console.table({
+  this.logger.table({
     name: { source: source.name, dest: dest.name },
     chainId: { source: source.chainId, dest: dest.chainId },
     chainSelector: { source: source.chainSelector, dest: dest.chainSelector },
@@ -86,6 +110,12 @@ async function formatToken(
   return `${formatUnits(ta.amount, decimals)} ${symbol}`
 }
 
+/**
+ * Formats an array into a record with indexed keys.
+ * @param name - Base name for the keys.
+ * @param values - Array values to format.
+ * @returns Record with indexed keys.
+ */
 export function formatArray<T>(name: string, values: readonly T[]): Record<string, T> {
   if (values.length <= 1) return { [name]: values[0] }
   return Object.fromEntries(values.map((v, i) => [`${name}[${i}]`, v] as const))
@@ -126,6 +156,11 @@ function formatDate(timestamp: number) {
   return new Date(timestamp * 1e3).toISOString().substring(0, 19).replace('T', ' ')
 }
 
+/**
+ * Formats duration in seconds to human-readable string.
+ * @param secs - Duration in seconds.
+ * @returns Formatted duration string (e.g., "1h 30m").
+ */
 export function formatDuration(secs: number) {
   if (secs < 0) secs = -secs
   if (secs >= 3540 && Math.floor(secs) % 60 >= 50)
@@ -154,13 +189,20 @@ function omit<T extends Record<string, unknown>, K extends string>(
   return result
 }
 
+/**
+ * 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[],
 ) {
-  prettyLane(request.lane)
-  console.info('Request (source):')
+  prettyLane.call(this, request.lane)
+  this.logger.info('Request (source):')
 
   let finalized
   try {
@@ -184,7 +226,7 @@ export async function prettyRequest(
     'extraArgs',
     'accounts',
   )
-  prettyTable({
+  prettyTable.call(this, {
     messageId: request.message.header.messageId,
     ...(request.tx.from ? { origin: request.tx.from } : {}),
     sender: request.message.sender,
@@ -199,11 +241,11 @@ export async function prettyRequest(
     transactionHash: request.log.transactionHash,
     logIndex: request.log.index,
     blockNumber: request.log.blockNumber,
-    timestamp: `${formatDate(request.timestamp)} (${formatDuration(Date.now() / 1e3 - request.timestamp)} ago)`,
+    timestamp: `${formatDate(request.tx.timestamp)} (${formatDuration(Date.now() / 1e3 - request.tx.timestamp)} ago)`,
     finalized:
       finalized &&
-      (finalized < request.timestamp
-        ? formatDuration(request.timestamp - finalized) + ' left'
+      (finalized < request.tx.timestamp
+        ? formatDuration(request.tx.timestamp - finalized) + ' left'
         : true),
     fee: await formatToken(source, {
       token: request.message.feeToken,
@@ -223,21 +265,28 @@ export async function prettyRequest(
   })
 
   if (!offchainTokenData?.length || offchainTokenData.every((d) => !d)) return
-  console.info('Attestations:')
+  this.logger.info('Attestations:')
   for (const attestation of offchainTokenData) {
     const { _tag: type, ...rest } = attestation!
-    prettyTable({ type, ...rest })
+    prettyTable.call(this, { type, ...rest })
   }
 }
 
+/**
+ * Prints a CCIP commit in a human-readable format.
+ * @param dest - Destination chain instance.
+ * @param commit - CCIP commit to print.
+ * @param request - CCIP request for timestamp comparison.
+ */
 export async function prettyCommit(
+  this: Ctx,
   dest: Chain,
   commit: CCIPCommit,
-  request: { timestamp: number },
+  request: PickDeep<CCIPRequest, 'tx.timestamp'>,
 ) {
-  console.info('Commit (dest):')
+  this.logger.info('Commit (dest):')
   const timestamp = await dest.getBlockTimestamp(commit.log.blockNumber)
-  prettyTable({
+  prettyTable.call(this, {
     merkleRoot: commit.report.merkleRoot,
     min: Number(commit.report.minSeqNr),
     max: Number(commit.report.maxSeqNr),
@@ -245,7 +294,7 @@ export async function prettyCommit(
     contract: commit.log.address,
     transactionHash: commit.log.transactionHash,
     blockNumber: commit.log.blockNumber,
-    timestamp: `${formatDate(timestamp)} (${formatDuration(timestamp - request.timestamp)} after request)`,
+    timestamp: `${formatDate(timestamp)} (${formatDuration(timestamp - request.tx.timestamp)} after request)`,
   })
 }
 
@@ -305,7 +354,13 @@ function wrapText(text: string, maxWidth: number, threshold: number = 0.1): stri
   return lines
 }
 
+/**
+ * Prints a formatted table of key-value pairs.
+ * @param args - Key-value pairs to print.
+ * @param opts - Formatting options.
+ */
 export function prettyTable(
+  this: Ctx,
   args: Record<string, unknown>,
   opts = { parseErrorKeys: ['returnData'], spcount: 0 },
 ) {
@@ -329,15 +384,22 @@ export function prettyTable(
       out.push(...Object.entries(value).map(([k, v]) => [`${key}.${k}`, v] as const))
     } else out.push([key, value])
   }
-  return console.table(Object.fromEntries(out))
+  return this.logger.table(Object.fromEntries(out))
 }
 
+/**
+ * Prints a CCIP execution receipt in a human-readable format.
+ * @param receipt - CCIP execution receipt to print.
+ * @param request - CCIP request for timestamp comparison.
+ * @param origin - Optional transaction origin address.
+ */
 export function prettyReceipt(
+  this: Ctx,
   receipt: CCIPExecution,
-  request: { timestamp: number },
+  request: PickDeep<CCIPRequest, 'tx.timestamp'>,
   origin?: string,
 ) {
-  prettyTable({
+  prettyTable.call(this, {
     state: receipt.receipt.state === ExecutionState.Success ? '✅ success' : '❌ failed',
     ...(receipt.receipt.state !== ExecutionState.Success ||
     (receipt.receipt.returnData && receipt.receipt.returnData !== '0x')
@@ -349,24 +411,29 @@ export function prettyReceipt(
     transactionHash: receipt.log.transactionHash,
     logIndex: receipt.log.index,
     blockNumber: receipt.log.blockNumber,
-    timestamp: `${formatDate(receipt.timestamp)} (${formatDuration(receipt.timestamp - request.timestamp)} after request)`,
+    timestamp: `${formatDate(receipt.timestamp)} (${formatDuration(receipt.timestamp - request.tx.timestamp)} after request)`,
   })
 }
 
-export function logParsedError(err: unknown): boolean {
+/**
+ * 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 {
   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) {
-      console.error(
+      this.logger.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 {
-      console.error('🛑 Error:', parsed)
+      this.logger.error('🛑 Error:', parsed)
     }
     return true
   }
@@ -402,3 +469,22 @@ export async function* yieldResolved<T>(promises: readonly Promise<T>[]): AsyncG
     yield res
   }
 }
+
+/**
+ * Create context for command execution
+ * @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
+
+  const logger = new Console(process.stdout, process.stderr, true)
+  if (argv.verbose) {
+    logger.debug('Verbose mode enabled')
+  } else {
+    logger.debug = () => {}
+  }
+
+  return [controller, { destroy$, logger }]
+}

package/src/index.ts

@@ -9,7 +9,7 @@ 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.90.2-e2dea99'
+const VERSION = '0.91.0-b8bd948'
 // generate:end
 
 const globalOpts = {
@@ -43,6 +43,7 @@ const globalOpts = {
   },
 } as const
 
+/** Type for global CLI options. */
 export type GlobalOpts = InferredOptionTypes<typeof globalOpts>
 
 async function main() {
@@ -50,11 +51,6 @@ async function main() {
     .scriptName(process.env.CLI_NAME || 'ccip-cli')
     .env('CCIP')
     .options(globalOpts)
-    .middleware((argv) => {
-      if (!argv.verbose) {
-        console.debug = () => {}
-      }
-    })
     .commandDir('commands', {
       extensions: [new URL(import.meta.url).pathname.split('.').pop()!],
       exclude: /\.test\.[tj]s$/,
@@ -67,4 +63,22 @@ async function main() {
     .parse()
 }
 
-await main()
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const later = setTimeout(() => {}, 2 ** 31 - 1) // keep event-loop alive
+  await main()
+    .catch((err) => {
+      console.error(err)
+      throw err
+    })
+    .finally(() => {
+      clearTimeout(later)
+      setTimeout(() => {
+        util.inspect.defaultOptions.depth = 2
+        console.debug(
+          'Pending handles after main completion:',
+          (process as any)._getActiveHandles().length, // eslint-disable-line
+        )
+        process.exit()
+      }, 5e3).unref()
+    })
+}

package/src/providers/aptos.ts

@@ -12,20 +12,25 @@ import {
   Ed25519Signature,
   generateSigningMessageForTransaction,
 } from '@aptos-labs/ts-sdk'
-import { AptosChain } 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'
 
-// A LedgerSigner object represents a signer for a private key on a Ledger hardware wallet.
-// This object is initialized alongside a LedgerClient connection, and can be used to sign
-// transactions via a ledger hardware wallet.
+/**
+ * A LedgerSigner object represents a signer for a private key on a Ledger hardware wallet.
+ * This object is initialized alongside a LedgerClient connection, and can be used to sign
+ * transactions via a ledger hardware wallet.
+ */
 export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
   derivationPath: string
   readonly client: AptosLedger.default
   readonly publicKey: Ed25519PublicKey
   readonly accountAddress: AccountAddress
 
+  /**
+   * Private constructor - use static `create` method instead.
+   * @internal
+   */
   private constructor(
     ledgerClient: AptosLedger.default,
     derivationPath: string,
@@ -40,6 +45,11 @@ export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
     this.accountAddress = authKey.derivedAddress()
   }
 
+  /**
+   * Creates a new AptosLedgerSigner instance.
+   * @param derivationPath - BIP44 derivation path.
+   * @returns A new AptosLedgerSigner instance.
+   */
   static async create(derivationPath: string) {
     const transport = await HIDTransport.default.create()
     const client = new AptosLedger.default(transport)
@@ -47,7 +57,11 @@ export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
     return new AptosLedgerSigner(client, derivationPath, publicKey)
   }
 
-  // Prompts user to sign associated transaction on their Ledger hardware wallet.
+  /**
+   * Prompts user to sign associated transaction on their Ledger hardware wallet.
+   * @param txn - Raw transaction to sign.
+   * @returns Account authenticator with the signature.
+   */
   async signTransactionWithAuthenticator(txn: AnyRawTransaction) {
     const signingMessage = generateSigningMessageForTransaction(txn)
 
@@ -55,7 +69,11 @@ export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
     return new AccountAuthenticatorEd25519(this.publicKey, signature)
   }
 
-  // Sign a message - returns just the signature
+  /**
+   * Signs a message - returns just the signature.
+   * @param message - Message bytes to sign.
+   * @returns Ed25519 signature.
+   */
   async sign(message: BytesLike): Promise<Ed25519Signature> {
     const messageBytes = getBytes(message)
     // This line prompts the user to sign the transaction on their Ledger hardware wallet
@@ -66,13 +84,20 @@ export class AptosLedgerSigner /*implements AptosAsyncAccount*/ {
     return new Ed25519Signature(signature)
   }
 
-  // Terminates the LedgerClient connection.
+  /**
+   * Terminates the LedgerClient connection.
+   */
   async close() {
     await this.client.transport.close()
   }
 }
 
-AptosChain.getWallet = async function loadAptosWallet({ wallet: walletOpt }: { wallet?: unknown }) {
+/**
+ * Loads an Aptos wallet from the provided options.
+ * @param wallet - wallet options (as passed from yargs argv)
+ * @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)}`)

package/src/providers/evm.ts

@@ -2,11 +2,17 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import util from 'util'
 
-import { EVMChain } 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'
-import { type Provider, type Signer, BaseWallet, SigningKey, Wallet } from 'ethers'
+import {
+  type JsonRpcApiProvider,
+  type Provider,
+  type Signer,
+  BaseWallet,
+  SigningKey,
+  Wallet,
+} from 'ethers'
 
 // monkey-patch @ethers-ext/signer-ledger to preserve path when `.connect`ing provider
 Object.assign(LedgerSigner.prototype, {
@@ -18,14 +24,25 @@ Object.assign(LedgerSigner.prototype, {
 /**
  * Overwrite EVMChain.getWallet to support reading private key from file, env var or Ledger
  * @param provider - provider instance to be connected to signers
- * @param opts - wallet options (as passed to yargs argv)
+ * @param wallet - wallet options (as passed to yargs argv)
  * @returns Promise to Signer instance
  */
-EVMChain.getWallet = async function loadEvmWallet(
-  provider: Provider,
+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})$/))
+  ) {
+    // if given a number, numeric string or address, use ethers `provider.getSigner` (e.g. geth or MM)
+    return provider.getSigner(
+      typeof walletOpt === 'string' && walletOpt.match(/^0x[a-fA-F0-9]{40}$/)
+        ? walletOpt
+        : Number(walletOpt),
+    )
+  }
   if (typeof walletOpt !== 'string')
     throw new Error(`Invalid wallet option: ${util.inspect(walletOpt)}`)
   if ((walletOpt ?? '').startsWith('ledger')) {

package/src/providers/index.ts

@@ -4,16 +4,43 @@ import {
   type Chain,
   type ChainGetter,
   type ChainTransaction,
+  type EVMChain,
+  ChainFamily,
   networkInfo,
   supportedChains,
 } from '@chainlink/ccip-sdk/src/index.ts'
 
-import './aptos.ts'
-import './evm.ts'
-import './solana.ts'
+import { loadAptosWallet } from './aptos.ts'
+import { loadEvmWallet } from './evm.ts'
+import { loadSolanaWallet } from './solana.ts'
+import type { Ctx } from '../commands/index.ts'
 
 const RPCS_RE = /\b(?:http|ws)s?:\/\/[\w/\\@&?%~#.,;:=+-]+/
 
+const signalToPromiseMap = new WeakMap<AbortSignal, Promise<void>>()
+function signalToPromise(signal: AbortSignal) {
+  let promise = signalToPromiseMap.get(signal)
+  if (!promise) {
+    signalToPromiseMap.set(
+      signal,
+      (promise = new Promise((_, reject) => {
+        signal.throwIfAborted()
+        signal.addEventListener(
+          'abort',
+          () =>
+            reject(
+              signal.reason instanceof Error
+                ? signal.reason
+                : new Error(`Aborted: ${signal.reason as string}`),
+            ),
+          { once: true },
+        )
+      })),
+    )
+  }
+  return promise
+}
+
 async function collectEndpoints({
   rpcs,
   'rpcs-file': rpcsFile,
@@ -40,47 +67,49 @@ async function collectEndpoints({
 }
 
 export function fetchChainsFromRpcs(
+  ctx: Ctx,
   argv: { rpcs?: string[]; 'rpcs-file'?: string },
-  txHash?: undefined,
-  destroy?: Promise<unknown>,
 ): ChainGetter
 export function fetchChainsFromRpcs(
+  ctx: Ctx,
   argv: { rpcs?: string[]; 'rpcs-file'?: string },
   txHash: string,
-  destroy?: Promise<unknown>,
-): [ChainGetter, Promise<ChainTransaction>]
+): [ChainGetter, Promise<[Chain, ChainTransaction]>]
 
 /**
  * Receives a list of rpcs and/or rpcs file, and loads them all concurrently
  * Returns a ChainGetter function and optinoally a ChainTransaction promise
+ * @param ctx - Context object containing destroy$ promise and logger properties
  * @param argv - Options containing rpcs (list) and/or rpcs file
  * @param txHash - Optional txHash to fetch concurrently; causes the function to return a [ChainGetter, Promise<ChainTransaction>]
- * @param destroy - A promise to signal when to stop fetching chains
  * @returns a ChainGetter (alone if no txHash was provided), or a tuple of [ChainGetter, Promise<ChainTransaction>]
  */
 export function fetchChainsFromRpcs(
+  ctx: Ctx,
   argv: { rpcs?: string[]; 'rpcs-file'?: string },
   txHash?: string,
-  destroy?: Promise<unknown>,
 ) {
+  const { destroy$ } = ctx
   const chains: Record<string, Promise<Chain>> = {}
   const chainsCbs: Record<
     string,
     readonly [resolve: (value: Chain) => void, reject: (reason?: unknown) => void]
   > = {}
   let finished = false
-  const txs: Promise<ChainTransaction>[] = []
+  const txs: Promise<[Chain, ChainTransaction]>[] = []
 
   const init$ = collectEndpoints(argv).then((endpoints) => {
     const pendingPromises: Promise<unknown>[] = []
     let txFound = false
     for (const C of Object.values(supportedChains)) {
       for (const url of endpoints) {
-        const chain$ = C.fromUrl(url)
+        const chain$ = C.fromUrl(url, ctx)
         if (txHash) {
-          const tx$ = chain$.then((chain) => chain.getTransaction(txHash))
+          const tx$ = chain$.then((chain) =>
+            chain.getTransaction(txHash).then<[Chain, ChainTransaction]>((tx) => [chain, tx]),
+          )
           void tx$.then(
-            ({ chain }) => {
+            ([chain]) => {
               if (txFound) return
               txFound = true
               // in case tx is found, prefer it over any previously found chain
@@ -96,7 +125,7 @@ export function fetchChainsFromRpcs(
           chain$.then((chain) => {
             if (chain.network.name in chains && !(chain.network.name in chainsCbs))
               return chain.destroy?.() // lost race
-            void destroy?.finally(() => {
+            destroy$.addEventListener('abort', () => {
               void chain.destroy?.() // cleanup
             })
             if (!(chain.network.name in chains)) {
@@ -110,7 +139,7 @@ export function fetchChainsFromRpcs(
       }
     }
     const res = Promise.allSettled(pendingPromises)
-    void (destroy ? Promise.race([res, destroy]) : res).finally(() => {
+    void (destroy$ ? Promise.race([res, signalToPromise(destroy$)]) : res).finally(() => {
       finished = true
       Object.entries(chainsCbs).forEach(([name, [_, reject]]) =>
         reject(new Error(`No provider/chain found for network=${name}`)),
@@ -139,3 +168,26 @@ export function fetchChainsFromRpcs(
     return chainGetter
   }
 }
+
+/**
+ * Load chain-specific wallet for given chain
+ * @param chain - Chain instance to load wallet for
+ * @param opts - Wallet options (as passed from yargs argv)
+ * @returns Promise to chain-specific wallet instance
+ */
+export async function loadChainWallet(chain: Chain, opts: { wallet?: unknown }) {
+  let wallet
+  switch (chain.network.family) {
+    case ChainFamily.EVM:
+      wallet = await loadEvmWallet((chain as EVMChain).provider, opts)
+      return [await wallet.getAddress(), wallet] as const
+    case ChainFamily.Solana:
+      wallet = await loadSolanaWallet(opts)
+      return [wallet.publicKey.toBase58(), wallet] as const
+    case ChainFamily.Aptos:
+      wallet = await loadAptosWallet(opts)
+      return [wallet.accountAddress.toString(), wallet] as const
+    default:
+      throw new Error(`Unsupported chain family: ${chain.network.family}`)
+  }
+}