@chainlink/ccip-sdk 0.90.2 → 0.91.0

package/src/evm/logs.ts

@@ -0,0 +1,255 @@
+import {
+  type JsonRpcApiProvider,
+  type Log,
+  FetchRequest,
+  JsonRpcProvider,
+  isHexString,
+} from 'ethers'
+import { memoize } from 'micro-memoize'
+
+import type { LogFilter } from '../chain.ts'
+import { blockRangeGenerator, getSomeBlockNumberBefore, util } from '../utils.ts'
+import { getAllFragmentsMatchingEvents } from './const.ts'
+import type { WithLogger } from '../types.ts'
+
+const MAX_PARALLEL_JOBS = 24
+const PER_REQUEST_TIMEOUT = 5000
+
+const getFallbackRpcsList = memoize(
+  async () => {
+    const response = await fetch('https://chainlist.org/rpcs.json')
+    const data = await response.json()
+    return data as {
+      chainId: number
+      rpc: { url: string }[]
+      explorers: { url: string }[]
+    }[]
+  },
+  { async: true },
+)
+
+// like Promise.any, but receives Promise factories and spawn a maximum number of them in parallel
+function anyPromiseMax<T>(
+  promises: readonly (() => Promise<T>)[],
+  maxParallelJobs: number,
+  cancel?: Promise<unknown>,
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const errors: unknown[] = new Array(promises.length)
+    let index = 0
+    let inFlight = 0
+    let completed = 0
+
+    if (promises.length === 0) {
+      reject(new AggregateError([], 'All promises were rejected'))
+      return
+    }
+    let cancelled = false
+    void cancel?.finally(() => {
+      cancelled = true
+    })
+
+    const startNext = () => {
+      while (!cancelled && inFlight < maxParallelJobs && index < promises.length) {
+        const currentIndex = index++
+        inFlight++
+
+        void promises[currentIndex]()
+          .then(resolve)
+          .catch((error) => {
+            errors[currentIndex] = error
+            completed++
+            inFlight--
+
+            if (completed === promises.length) {
+              reject(new AggregateError(errors, 'All promises were rejected'))
+            } else {
+              startNext()
+            }
+          })
+      }
+    }
+
+    startNext()
+  })
+}
+
+// cache
+const archiveRpcs: Record<number, Promise<JsonRpcApiProvider>> = {}
+
+/**
+ * Like provider.getLogs, but from a public list of archive nodes and wide range, races the first to reply
+ * @param chainId - The chain ID of the network to query
+ * @param filter - Log filter options
+ * @param destroy$ - An optional promise that, when resolved, cancels the requests
+ * @returns Array of Logs
+ */
+async function getFallbackArchiveLogs(
+  chainId: number,
+  filter: {
+    address: string
+    topics: (string | string[] | null)[]
+    startBlock?: number
+    endBlock?: number | 'latest'
+  },
+  { logger = console, destroy$ }: { destroy$?: Promise<unknown> } & WithLogger = {},
+) {
+  const provider = archiveRpcs[chainId]
+  if (provider != null) {
+    return (await provider).getLogs({
+      ...filter,
+      fromBlock: filter.startBlock ?? 1,
+      toBlock: filter.endBlock ?? 'latest',
+    })
+  }
+  let cancel!: (_?: unknown) => void
+  let cancel$ = new Promise<unknown>((resolve) => (cancel = resolve))
+  if (destroy$) cancel$ = Promise.race([destroy$, cancel$])
+
+  let winner: string
+  const providerLogs$ = getFallbackRpcsList()
+    .then((rpcs) => {
+      const rpc = rpcs.find(({ chainId: id }) => id === chainId)
+      if (!rpc) throw new Error(`No RPC found for chainId=${chainId}`)
+      return Array.from(
+        new Set(rpc.rpc.map(({ url }) => url).filter((url) => url.match(/^https?:\/\//))),
+      )
+    })
+    .then((urls) =>
+      anyPromiseMax(
+        urls.map((url) => async () => {
+          const fetchReq = new FetchRequest(url)
+          fetchReq.timeout = PER_REQUEST_TIMEOUT
+          const provider = new JsonRpcProvider(fetchReq, chainId)
+          void cancel$.finally(() => {
+            if (url === winner) return
+            provider.destroy()
+            try {
+              fetchReq.cancel()
+            } catch (_) {
+              // ignore
+            }
+          })
+          return [
+            provider,
+            await provider
+              .getLogs({
+                ...filter,
+                fromBlock: filter.startBlock ?? 1,
+                toBlock: filter.endBlock ?? 'latest',
+              })
+              .then((logs) => {
+                if (!logs.length) throw new Error('No logs found')
+                logger.debug(
+                  'getFallbackArchiveLogs raced',
+                  url,
+                  'from',
+                  urls.length,
+                  'urls, got',
+                  logs.length,
+                  'logs for',
+                  filter,
+                )
+                winner ??= url
+                cancel()
+                return logs
+              }),
+          ] as const // return both winner provider and logs
+        }),
+        MAX_PARALLEL_JOBS,
+        cancel$,
+      ),
+    )
+    .finally(cancel)
+  archiveRpcs[chainId] = providerLogs$.then(([provider]) => provider) // cache provider
+  archiveRpcs[chainId].catch(() => {
+    delete archiveRpcs[chainId]
+  })
+  return providerLogs$.then(([, logs]) => logs) // return logs
+}
+
+/**
+ * Implements Chain.getLogs for EVM.
+ * If !(filter.startBlock|startTime), walks backwards from endBlock, otherwise forward from then.
+ * @param filter - Chain LogFilter. The `onlyFallback` option controls pagination behavior:
+ *   - If undefined (default): paginate main provider only by filter.page
+ *   - If false: first try whole range with main provider, then fallback to archive provider
+ *   - If true: don't paginate (throw if can't fetch wide range from either provider)
+ * @param ctx - Context object containing provider, logger and destry$ notify promise
+ * @returns Async iterator of logs.
+ */
+export async function* getEvmLogs(
+  filter: LogFilter & { onlyFallback?: boolean },
+  ctx: { provider: JsonRpcApiProvider; destroy$?: Promise<unknown> } & WithLogger,
+): AsyncIterableIterator<Log> {
+  const { provider, logger = console } = ctx
+  const endBlock = filter.endBlock ?? (await provider.getBlockNumber())
+  if (
+    filter.topics?.length &&
+    filter.topics.every((t: string | string[] | null): t is string => typeof t === 'string')
+  ) {
+    const topics = new Set(
+      filter.topics
+        .filter(isHexString)
+        .concat(Object.keys(getAllFragmentsMatchingEvents(filter.topics)) as `0x${string}`[])
+        .flat(),
+    )
+    if (!topics.size) {
+      throw new Error(`Could not find matching topics: ${util.inspect(filter.topics)}`)
+    }
+    filter.topics = [Array.from(topics)]
+  }
+  if (filter.startBlock == null && filter.startTime) {
+    filter.startBlock = await getSomeBlockNumberBefore(
+      async (block: number | 'finalized') => (await provider.getBlock(block))!.timestamp, // cached
+      endBlock,
+      filter.startTime,
+      ctx,
+    )
+  }
+  if (filter.onlyFallback != null && filter.address && filter.topics?.length) {
+    let logs
+    try {
+      logs = await provider.getLogs({
+        ...filter,
+        fromBlock: filter.startBlock ?? 1,
+        toBlock: filter.endBlock ?? 'latest',
+      })
+    } catch (_) {
+      try {
+        logs = await getFallbackArchiveLogs(
+          Number((await provider.getNetwork()).chainId),
+          {
+            address: filter.address,
+            topics: filter.topics,
+            startBlock: filter.startBlock ?? 1,
+            endBlock: filter.endBlock ?? 'latest',
+          },
+          ctx,
+        )
+      } catch (err) {
+        if (filter.onlyFallback === true) throw err
+      }
+    }
+    if (logs) {
+      if (!filter.startBlock) logs.reverse()
+      yield* logs
+      return
+    }
+  }
+  // paginate only if filter.onlyFallback is nullish
+  for (const blockRange of blockRangeGenerator({ ...filter, endBlock })) {
+    logger.debug('evm getLogs:', {
+      ...blockRange,
+      ...(filter.address ? { address: filter.address } : {}),
+      ...(filter.topics?.length ? { topics: filter.topics } : {}),
+    })
+    const logs = await provider.getLogs({
+      ...blockRange,
+      ...(filter.address ? { address: filter.address } : {}),
+      ...(filter.topics?.length ? { topics: filter.topics } : {}),
+    })
+    if (!filter.startBlock) logs.reverse()
+    yield* logs
+  }
+}

package/src/evm/messages.ts

@@ -7,7 +7,7 @@ import type EVM2EVMOnRamp_1_5_ABI from './abi/OnRamp_1_5.ts'
 import type OnRamp_1_6_ABI from './abi/OnRamp_1_6.ts'
 import { defaultAbiCoder } from './const.ts'
 
-// addresses often come as `string | Addressable`, this type cleans them up to just `string`
+/** Utility type that cleans up address types to just `string`. */
 export type CleanAddressable<T> = T extends string | Addressable
   ? string
   : T extends Record<string, unknown>
@@ -23,7 +23,7 @@ type EVM2AnyMessageRequested = CleanAddressable<
   >[0]
 >
 
-// v1.6+ Message Base (all other dests share this intersection)
+/** v1.6+ Message Base type (all other destinations share this intersection). */
 export type CCIPMessage_V1_6 = MergeArrayElements<
   CleanAddressable<
     AbiParametersToPrimitiveTypes<
@@ -33,6 +33,7 @@ export type CCIPMessage_V1_6 = MergeArrayElements<
   { tokenAmounts: readonly SourceTokenData[] }
 >
 
+/** CCIP v1.5 EVM message type. */
 export type CCIPMessage_V1_5_EVM = MergeArrayElements<
   EVM2AnyMessageRequested,
   {
@@ -41,13 +42,15 @@ export type CCIPMessage_V1_5_EVM = MergeArrayElements<
   }
 >
 
+/** CCIP v1.2 EVM message type. */
 export type CCIPMessage_V1_2_EVM = EVM2AnyMessageRequested & {
   header: Omit<CCIPMessage_V1_6['header'], 'destChainSelector'>
 }
 
-// v1.6 EVM specialization, extends CCIPMessage_V1_6, plus EVMExtraArgsV2 and tokenAmounts.*.destGasAmount
+/** v1.6 EVM specialization with EVMExtraArgsV2 and tokenAmounts.*.destGasAmount. */
 export type CCIPMessage_V1_6_EVM = CCIPMessage_V1_6 & EVMExtraArgsV2
 
+/** Union type for CCIP EVM messages across versions. */
 export type CCIPMessage_EVM<V extends CCIPVersion = CCIPVersion> = V extends typeof CCIPVersion.V1_2
   ? CCIPMessage_V1_2_EVM
   : V extends typeof CCIPVersion.V1_5
@@ -56,6 +59,7 @@ export type CCIPMessage_EVM<V extends CCIPVersion = CCIPVersion> = V extends typ
 
 const SourceTokenData =
   'tuple(bytes sourcePoolAddress, bytes destTokenAddress, bytes extraData, uint64 destGasAmount)'
+/** Token transfer data in a CCIP message. */
 export type SourceTokenData = {
   sourcePoolAddress: string
   destTokenAddress: string
@@ -64,8 +68,10 @@ export type SourceTokenData = {
 }
 
 /**
- * parse <=v1.5 `message.sourceTokenData`;
- * v1.6+ already contains this in `message.tokenAmounts`
+ * Parses v1.5 and earlier `message.sourceTokenData`.
+ * Version 1.6+ already contains this in `message.tokenAmounts`.
+ * @param data - The source token data string to parse.
+ * @returns The parsed SourceTokenData object.
  */
 export function parseSourceTokenData(data: string): SourceTokenData {
   const decoded = defaultAbiCoder.decode([SourceTokenData], data)

package/src/evm/offchain.ts

@@ -1,7 +1,7 @@
 import { type Addressable, type Log, EventFragment } from 'ethers'
 
 import { getLbtcAttestation, getUsdcAttestation } from '../offchain.ts'
-import type { CCIPMessage, CCIPRequest, OffchainTokenData } from '../types.ts'
+import type { CCIPMessage, CCIPRequest, OffchainTokenData, WithLogger } from '../types.ts'
 import { networkInfo } from '../utils.ts'
 import { defaultAbiCoder, interfaces, requestsFragments } from './const.ts'
 import { type SourceTokenData, parseSourceTokenData } from './messages.ts'
@@ -32,6 +32,7 @@ export async function fetchEVMOffchainTokenData(
     message: CCIPMessage
     log: Pick<CCIPRequest['log'], 'index'>
   },
+  ctx: WithLogger,
 ): Promise<OffchainTokenData[]> {
   const { isTestnet } = networkInfo(request.message.header.sourceChainSelector)
   // there's a chance there are other CCIPSendRequested in same tx,
@@ -52,6 +53,7 @@ export async function fetchEVMOffchainTokenData(
     request.message.tokenAmounts,
     usdcRequestLogs,
     isTestnet,
+    ctx,
   )
   let lbtcTokenData: OffchainTokenData[] = []
   try {
@@ -62,7 +64,7 @@ export async function fetchEVMOffchainTokenData(
       tokenAmounts = request.message.tokenAmounts
     }
     //for lbtc we distinguish logs by hash in event, so we can pass all of them
-    lbtcTokenData = await getLbtcTokenData(tokenAmounts, request.tx.logs as Log[], isTestnet)
+    lbtcTokenData = await getLbtcTokenData(tokenAmounts, request.tx.logs as Log[], isTestnet, ctx)
   } catch (_) {
     // pass
   }
@@ -78,6 +80,11 @@ export async function fetchEVMOffchainTokenData(
   return offchainTokenData
 }
 
+/**
+ * Encodes offchain token data for EVM execution.
+ * @param data - Offchain token data to encode.
+ * @returns ABI-encoded data or empty hex string.
+ */
 export function encodeEVMOffchainTokenData(data: OffchainTokenData): string {
   if (data?._tag === 'usdc') {
     return defaultAbiCoder.encode(['tuple(bytes message, bytes attestation)'], [data])
@@ -99,6 +106,7 @@ async function getUsdcTokenData(
   tokenAmounts: CCIPMessage['tokenAmounts'],
   allLogsInRequest: Pick<Log, 'topics' | 'address' | 'data'>[],
   isTestnet: boolean,
+  { logger = console }: WithLogger = {},
 ): Promise<OffchainTokenData[]> {
   const attestations: OffchainTokenData[] = []
 
@@ -151,7 +159,7 @@ async function getUsdcTokenData(
         // encoding of OffchainTokenData to be done as part of Chain.executeReceipt
       } catch (err) {
         // maybe not a USDC transfer, or not ready
-        console.warn(`❌ EVM CCTP: Failed to fetch attestation for message:`, message, err)
+        logger.warn(`❌ EVM CCTP: Failed to fetch attestation for message:`, message, err)
       }
     }
     attestations.push(tokenData)
@@ -167,6 +175,7 @@ async function getLbtcTokenData(
   tokenAmounts: readonly SourceTokenData[],
   allLogsInRequest: readonly Pick<Log, 'topics' | 'address' | 'data'>[],
   isTestnet: boolean,
+  { logger = console }: WithLogger = {},
 ): Promise<OffchainTokenData[]> {
   const lbtcDepositHashes = new Set(
     allLogsInRequest
@@ -181,7 +190,7 @@ async function getLbtcTokenData(
         try {
           return { _tag: 'lbtc', extraData, ...(await getLbtcAttestation(extraData, isTestnet)) }
         } catch (err) {
-          console.warn(`❌ EVM LBTC: Failed to fetch attestation for message:`, extraData, err)
+          logger.warn(`❌ EVM LBTC: Failed to fetch attestation for message:`, extraData, err)
         }
       }
     }),

package/src/execution.ts

@@ -1,14 +1,16 @@
-import moize from 'moize'
+import { memoize } from 'micro-memoize'
 
 import type { Chain, ChainStatic } from './chain.ts'
 import { Tree, getLeafHasher, proofFlagsToBits } from './hasher/index.ts'
 import {
+  type CCIPCommit,
   type CCIPExecution,
   type CCIPMessage,
+  type CCIPRequest,
   type CCIPVersion,
-  type CommitReport,
   type ExecutionReport,
   type Lane,
+  type WithLogger,
   ExecutionState,
 } from './types.ts'
 
@@ -16,9 +18,10 @@ import {
  * Pure/sync function to calculate/generate OffRamp.executeManually report for messageIds
  *
  * @param messagesInBatch - Array containing all messages in batch, ordered
- * @param lane - Arguments for leafeHasher (lane info)
- * @param messageIds - list of messages (from batch) to prove for manual execution
+ * @param lane - Arguments for leafHasher (lane info)
+ * @param messageId - Message ID to prove for manual execution
  * @param merkleRoot - Optional merkleRoot of the CommitReport, for validation
+ * @param ctx - Context for logging
  * @returns ManualExec report arguments
  **/
 export function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(
@@ -26,8 +29,9 @@ export function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(
   lane: Lane<V>,
   messageId: string,
   merkleRoot?: string,
+  ctx?: WithLogger,
 ): Omit<ExecutionReport, 'offchainTokenData' | 'message'> {
-  const hasher = getLeafHasher(lane)
+  const hasher = getLeafHasher(lane, ctx)
 
   const msgIdx = messagesInBatch.findIndex((message) => message.header.messageId === messageId)
   if (msgIdx < 0) {
@@ -56,8 +60,13 @@ export function calculateManualExecProof<V extends CCIPVersion = CCIPVersion>(
   }
 }
 
-export const discoverOffRamp = moize.default(
-  async function discoverOffRamp_(source: Chain, dest: Chain, onRamp: string): Promise<string> {
+export const discoverOffRamp = memoize(
+  async function discoverOffRamp_(
+    source: Chain,
+    dest: Chain,
+    onRamp: string,
+    { logger = console }: WithLogger = {},
+  ): Promise<string> {
     const sourceRouter = await source.getRouterForOnRamp(onRamp, dest.network.chainSelector)
     const sourceOffRamps = await source.getOffRampsForRouter(
       sourceRouter,
@@ -70,7 +79,7 @@ export const discoverOffRamp = moize.default(
       for (const offRamp of destOffRamps) {
         const offRampsOnRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector)
         if (offRampsOnRamp === onRamp) {
-          console.debug(
+          logger.debug(
             'discoverOffRamp: found, from',
             { sourceRouter, sourceOffRamps, destOnRamp, destOffRamps, offRampsOnRamp },
             '=',
@@ -83,49 +92,48 @@ export const discoverOffRamp = moize.default(
     throw new Error(`No matching offRamp found for "${onRamp}" on "${dest.network.name}"`)
   },
   {
-    transformArgs: ([source, dest, onRamp]) => [
-      (source as Chain).network.chainSelector,
-      (dest as Chain).network.chainSelector,
-      onRamp as string,
-    ],
+    transformKey: ([source, dest, onRamp]) =>
+      [source.network.chainSelector, dest.network.chainSelector, onRamp] as const,
   },
 )
 
 /**
- * Generic implementation for fetching ExecutionReceipts for given requests
- * If more than one request is given, may yield them interleaved
- * Completes as soon as there's no more work to be done
- * 2 possible behaviors:
+ * Generic implementation for fetching ExecutionReceipts for given requests.
+ * If more than one request is given, may yield them interleaved.
+ * Completes as soon as there's no more work to be done.
+ *
+ * Two possible behaviors:
  * - if `startBlock|startTime` is given, pages forward from that block up;
  *   completes when success (final) receipt is found for all requests (or reach latest block)
  * - otherwise, pages backwards and returns only the most recent receipt per request;
  *   completes when receipts for all requests were seen
  *
- * @param dest - provider to page through
- * @param requests - CCIP requests to search executions for
- * @param hints.fromBlock - A block from where to start paging forward;
- *  otherwise, page backwards and completes on first (most recent) receipt
- * @param hints.page - getLogs pagination range param
- * @param hints.commit - Special param to help narrow down search on suppported chains (e.g. Solana)
- **/
+ * @param dest - Provider to page through.
+ * @param offRamp - OffRamp contract address.
+ * @param request - CCIP request to search executions for.
+ * @param commit - Optional commit info to narrow down search.
+ * @param hints - Optional hints (e.g., `page` for getLogs pagination range).
+ */
 export async function* fetchExecutionReceipts(
   dest: Chain,
   offRamp: string,
-  messageIds: Set<string>,
-  hints?: { startBlock?: number; startTime?: number; page?: number; commit?: CommitReport },
+  request: CCIPRequest,
+  commit?: CCIPCommit,
+  hints?: { page?: number },
 ): AsyncGenerator<CCIPExecution> {
-  const onlyLast = !hints?.startBlock && !hints?.startTime // backwards
+  const onlyLast = !commit?.log.blockNumber && !request.tx.timestamp // backwards
   for await (const log of dest.getLogs({
-    ...hints,
+    startBlock: commit?.log.blockNumber,
+    startTime: request.tx.timestamp,
     address: offRamp,
     topics: ['ExecutionStateChanged'],
+    ...hints,
   })) {
     const receipt = (dest.constructor as ChainStatic).decodeReceipt(log)
-    if (!receipt || !messageIds.has(receipt.messageId)) continue
-    if (onlyLast || receipt.state === ExecutionState.Success) messageIds.delete(receipt.messageId)
+    if (!receipt || receipt.messageId !== request.message.header.messageId) continue
 
-    const timestamp = await dest.getBlockTimestamp(log.blockNumber)
+    const timestamp = log.tx?.timestamp ?? (await dest.getBlockTimestamp(log.blockNumber))
     yield { receipt, log, timestamp }
-    if (!messageIds.size) break
+    if (onlyLast || receipt.state === ExecutionState.Success) break
   }
 }

package/src/extra-args.ts

@@ -1,32 +1,63 @@
 import { type BytesLike, id } from 'ethers'
 
-import { ChainFamily } from './chain.ts'
 import { supportedChains } from './supported-chains.ts'
+import { ChainFamily } from './types.ts'
 
+/** Tag identifier for EVMExtraArgsV1 encoding. */
 export const EVMExtraArgsV1Tag = id('CCIP EVMExtraArgsV1').substring(0, 10) as '0x97a657c9'
+/** Tag identifier for EVMExtraArgsV2 encoding. */
 export const EVMExtraArgsV2Tag = id('CCIP EVMExtraArgsV2').substring(0, 10) as '0x181dcf10'
+/** Tag identifier for SVMExtraArgsV1 encoding. */
 export const SVMExtraArgsV1Tag = id('CCIP SVMExtraArgsV1').substring(0, 10) as '0x1f3b3aba'
+/** Tag identifier for SuiExtraArgsV1 encoding. */
 export const SuiExtraArgsV1Tag = id('CCIP SuiExtraArgsV1').substring(0, 10) as '0x21ea4ca9'
 
+/**
+ * EVM extra arguments version 1 with gas limit only.
+ */
 export type EVMExtraArgsV1 = {
+  /** Gas limit for execution on the destination chain. */
   gasLimit: bigint
 }
-// aka GenericExtraArgsV2
+
+/**
+ * EVM extra arguments version 2 with out-of-order execution support.
+ * Also known as GenericExtraArgsV2.
+ */
 export type EVMExtraArgsV2 = EVMExtraArgsV1 & {
+  /** Whether to allow out-of-order message execution. */
   allowOutOfOrderExecution: boolean
 }
+
+/**
+ * Solana (SVM) extra arguments version 1.
+ */
 export type SVMExtraArgsV1 = {
+  /** Compute units for Solana execution. */
   computeUnits: bigint
+  /** Bitmap indicating which accounts are writable. */
   accountIsWritableBitmap: bigint
+  /** Whether to allow out-of-order message execution. */
   allowOutOfOrderExecution: boolean
+  /** Token receiver address on Solana. */
   tokenReceiver: string
+  /** Additional account addresses required for execution. */
   accounts: string[]
 }
+
+/**
+ * Sui extra arguments version 1.
+ */
 export type SuiExtraArgsV1 = EVMExtraArgsV2 & {
+  /** Token receiver address on Sui. */
   tokenReceiver: string
+  /** Object IDs required for the receiver. */
   receiverObjectIds: string[]
 }
 
+/**
+ * Union type of all supported extra arguments formats.
+ */
 export type ExtraArgs = EVMExtraArgsV1 | EVMExtraArgsV2 | SVMExtraArgsV1 | SuiExtraArgsV1
 
 /**
@@ -41,10 +72,11 @@ export function encodeExtraArgs(args: ExtraArgs, from: ChainFamily = ChainFamily
 }
 
 /**
- * Parses extra arguments from CCIP messages
- * @param data - extra arguments bytearray data
- * @returns extra arguments object if found
- **/
+ * Parses extra arguments from CCIP messages.
+ * @param data - Extra arguments bytearray data.
+ * @param from - Optional chain family to narrow decoding attempts.
+ * @returns Extra arguments object if found, undefined otherwise.
+ */
 export function decodeExtraArgs(
   data: BytesLike,
   from?: ChainFamily,

package/src/gas.ts

@@ -35,14 +35,12 @@ const ccipReceive = FunctionFragment.from({
 type Any2EVMMessage = Parameters<TypedContract<typeof RouterABI>['routeMessage']>[0]
 
 /**
- * Estimate CCIP gasLimit needed to execute a request on a contract receiver
- *
- * @param dest - Provider for the destination chain
- * @param request - CCIP request info
- * @param request.lane - Lane info
- * @param request.message - Message info
- * @returns estimated gasLimit as bigint
- **/
+ * Estimate CCIP gasLimit needed to execute a request on a contract receiver.
+ * @param source - Provider for the source chain.
+ * @param dest - Provider for the destination chain.
+ * @param request - CCIP request info containing `lane` and `message` details.
+ * @returns Estimated gasLimit as bigint.
+ */
 export async function estimateExecGasForRequest(
   source: Chain,
   dest: EVMChain,
@@ -60,7 +58,7 @@ export async function estimateExecGasForRequest(
     }
   },
 ) {
-  const offRamp = await discoverOffRamp(source, dest, request.lane.onRamp)
+  const offRamp = await discoverOffRamp(source, dest, request.lane.onRamp, source)
   const destRouter = await dest.getRouterForOffRamp(offRamp, request.lane.sourceChainSelector)
 
   const destTokenAmounts = await Promise.all(

package/src/hasher/common.ts

@@ -2,6 +2,7 @@ import { concat, hexlify, keccak256, toBeHex } from 'ethers'
 
 import type { CCIPMessage, CCIPVersion } from '../types.ts'
 
+/** Function type for computing the leaf hash of a CCIP message. */
 export type LeafHasher<V extends CCIPVersion = CCIPVersion> = (message: CCIPMessage<V>) => string
 
 const INTERNAL_DOMAIN_SEPARATOR = toBeHex(1, 32)
@@ -10,8 +11,8 @@ export const ZERO_HASH = hexlify(new Uint8Array(32).fill(0xff))
 
 /**
  * Computes the Keccak-256 hash of the concatenation of two hash values.
- * @param a The first hash as a Hash type.
- * @param b The second hash as a Hash type.
+ * @param a - The first hash as a Hash type.
+ * @param b - The second hash as a Hash type.
  * @returns The Keccak-256 hash result as a Hash type.
  */
 export function hashInternal(a: string, b: string): string {