@chainlink/ccip-sdk 1.0.0 → 1.1.1

package/src/api/index.ts

@@ -2,23 +2,26 @@ import { memoize } from 'micro-memoize'
 import type { SetRequired } from 'type-fest'
 
 import {
+  CCIPApiClientNotAvailableError,
   CCIPHttpError,
   CCIPLaneNotFoundError,
   CCIPMessageIdNotFoundError,
   CCIPMessageNotFoundInTxError,
-  CCIPNotImplementedError,
   CCIPTimeoutError,
   CCIPUnexpectedPaginationError,
 } from '../errors/index.ts'
 import { HttpStatus } from '../http-status.ts'
+import { decodeMessageV1 } from '../messages.ts'
 import { decodeMessage } from '../requests.ts'
 import {
   type CCIPMessage,
   type CCIPRequest,
   type ChainLog,
   type ExecutionInput,
+  type Lane,
   type Logger,
   type NetworkInfo,
+  type OffchainTokenData,
   type WithLogger,
   CCIPVersion,
   ChainFamily,
@@ -29,11 +32,13 @@ import { bigIntReviver, parseJson } from '../utils.ts'
 import type {
   APIErrorResponse,
   LaneLatencyResponse,
+  RawExecutionInputsResult,
   RawLaneLatencyResponse,
   RawMessageResponse,
   RawMessagesResponse,
   RawNetworkInfo,
 } from './types.ts'
+import { calculateManualExecProof } from '../execution.ts'
 
 export type { APICCIPRequestMetadata, APIErrorResponse, LaneLatencyResponse } from './types.ts'
 
@@ -46,7 +51,7 @@ export const DEFAULT_TIMEOUT_MS = 30000
 /** SDK version string for telemetry header */
 // generate:nofail
 // `export const SDK_VERSION = '${require('./package.json').version}-${require('child_process').execSync('git rev-parse --short HEAD').toString().trim()}'`
-export const SDK_VERSION = '1.0.0-4cc6ccc'
+export const SDK_VERSION = '1.1.1-593a607'
 // generate:end
 
 /** SDK telemetry header name */
@@ -134,7 +139,7 @@ export class CCIPAPIClient {
   static {
     CCIPAPIClient.fromUrl = memoize(
       (baseUrl?: string, ctx?: CCIPAPIClientContext) => new CCIPAPIClient(baseUrl, ctx),
-      { maxArgs: 1 },
+      { maxArgs: 1, transformKey: ([baseUrl]) => [baseUrl ?? DEFAULT_API_BASE_URL] },
     )
   }
 
@@ -144,10 +149,26 @@ export class CCIPAPIClient {
    * @param ctx - Optional context with logger and custom fetch
    */
   constructor(baseUrl?: string, ctx?: CCIPAPIClientContext) {
+    if (typeof baseUrl === 'boolean' || (baseUrl as unknown) === null)
+      throw new CCIPApiClientNotAvailableError({ context: { baseUrl } }) // shouldn't happen
     this.baseUrl = baseUrl ?? DEFAULT_API_BASE_URL
     this.logger = ctx?.logger ?? console
     this.timeoutMs = ctx?.timeoutMs ?? DEFAULT_TIMEOUT_MS
     this._fetch = ctx?.fetch ?? globalThis.fetch.bind(globalThis)
+
+    this.getMessageById = memoize(this.getMessageById.bind(this), {
+      async: true,
+      expires: 4_000,
+      maxArgs: 1,
+      maxSize: 100,
+    })
+
+    this.getExecutionInput = memoize(this.getExecutionInput.bind(this), {
+      async: true,
+      expires: 4_000,
+      maxArgs: 1,
+      maxSize: 100,
+    })
   }
 
   /**
@@ -437,15 +458,109 @@ export class CCIPAPIClient {
   /**
    * Fetches the execution input for a given message by id.
    * @param messageId - The ID of the message to fetch the execution input for.
-   * @returns Either `{ encodedMessage, verifications }` or `{ message, offchainTokenData, ...proof }`, and offRamp
+   * @returns Either `{ encodedMessage, verifications }` or `{ message, offchainTokenData, ...proof }`, offRamp and lane
    */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  getExecutionInput(messageId: string): Promise<ExecutionInput & { offRamp: string }> {
-    throw new CCIPNotImplementedError(`CCIPAPIClient.getExecutionInput`)
-    // TODO: fetch (memoized) request with metadata from `getMessageById`
-    // TODO: if request doesn't contain everything needed (e.g. <v2.0), fetch `batch` and
-    // `offchainTokenData` from `/execution-input`
-    // TODO: if <v2.0, `calculateManualExecProof` and return `offRamp` and `input`
+  async getExecutionInput(messageId: string): Promise<ExecutionInput & Lane & { offRamp: string }> {
+    const url = `${this.baseUrl}/v2/messages/${encodeURIComponent(messageId)}/execution-inputs`
+
+    this.logger.debug(`CCIPAPIClient: GET ${url}`)
+
+    const response = await this._fetchWithTimeout(url, 'getExecutionInput')
+    if (!response.ok) {
+      // Try to parse structured error response from API
+      let apiError: APIErrorResponse | undefined
+      try {
+        apiError = parseJson<APIErrorResponse>(await response.text())
+      } catch {
+        // Response body not JSON, use HTTP status only
+      }
+
+      // 404 - Message not found
+      if (response.status === HttpStatus.NOT_FOUND) {
+        throw new CCIPMessageIdNotFoundError(messageId, {
+          context: apiError
+            ? {
+                apiErrorCode: apiError.error,
+                apiErrorMessage: apiError.message,
+              }
+            : undefined,
+        })
+      }
+
+      // Generic HTTP error for other cases
+      throw new CCIPHttpError(response.status, response.statusText, {
+        context: apiError
+          ? {
+              apiErrorCode: apiError.error,
+              apiErrorMessage: apiError.message,
+            }
+          : undefined,
+      })
+    }
+
+    const raw = JSON.parse(await response.text(), bigIntReviver) as RawExecutionInputsResult
+    this.logger.debug('getExecutionInput raw response:', raw)
+
+    const offRamp = raw.offramp
+    let lane: Lane
+    if ('encodedMessage' in raw) {
+      // CCIP 2.0 messages use MessageV1Codec, which is chain-independent serialization
+      const {
+        sourceChainSelector,
+        destChainSelector,
+        onRampAddress: onRamp,
+      } = decodeMessageV1(raw.encodedMessage)
+      return {
+        sourceChainSelector,
+        destChainSelector,
+        onRamp,
+        offRamp,
+        version: CCIPVersion.V2_0,
+        encodedMessage: raw.encodedMessage,
+        verifications: (raw.ccvData ?? []).map((ccvData, i) => ({
+          ccvData,
+          destAddress: raw.verifierAddresses[i]!,
+        })),
+      }
+    }
+
+    const messagesInBatch = raw.messageBatch.map(decodeMessage)
+    const message = messagesInBatch.find((message) => message.messageId === messageId)!
+    if ('onramp' in raw && raw.onramp && raw.version) {
+      lane = {
+        sourceChainSelector: raw.sourceChainSelector,
+        destChainSelector: raw.destChainSelector,
+        onRamp: raw.onramp,
+        version: raw.version as CCIPVersion,
+      }
+    } else {
+      ;({ lane } = await this.getMessageById(messageId))
+    }
+
+    const proof = calculateManualExecProof(messagesInBatch, lane, messageId, raw.merkleRoot, this)
+
+    const rawMessage = raw.messageBatch.find((message) => message.messageId === messageId)!
+    const offchainTokenData: OffchainTokenData[] = rawMessage.tokenAmounts.map(() => undefined)
+    if (rawMessage.usdcData?.status === 'complete')
+      offchainTokenData[0] = {
+        _tag: 'usdc',
+        message: rawMessage.usdcData.message_bytes_hex!,
+        attestation: rawMessage.usdcData.attestation!,
+      }
+    else if (rawMessage.lbtcData?.status === 'NOTARIZATION_STATUS_SESSION_APPROVED')
+      offchainTokenData[0] = {
+        _tag: 'lbtc',
+        message_hash: rawMessage.lbtcData.message_hash!,
+        attestation: rawMessage.lbtcData.attestation!,
+      }
+
+    return {
+      offRamp,
+      ...lane,
+      message,
+      offchainTokenData,
+      ...proof,
+    } as ExecutionInput & Lane & { offRamp: string }
   }
 
   /**

package/src/api/types.ts

@@ -182,3 +182,46 @@ export type APICCIPRequestMetadata = {
   /** Destination network metadata. */
   destNetworkInfo: NetworkInfo
 }
+
+// ============================================================================
+// GET /v2/messages/${messageId}/execution-inputs search endpoint types
+// ============================================================================
+
+/** Raw API response from GET /v2/messages/:messageId/execution-inputs */
+export type RawExecutionInputsResult = {
+  offramp: string
+} & (
+  | {
+      onramp: string
+      sourceChainSelector: bigint
+      destChainSelector: bigint
+      version: string
+    }
+  | object
+) &
+  (
+    | {
+        merkleRoot?: string
+        messageBatch: {
+          [key: string]: unknown
+          messageId: string
+          tokenAmounts: { token: string; amount: string }[]
+          usdcData?: {
+            status: 'pending_confirmations' | 'complete'
+            attestation?: string
+            message_bytes_hex?: string
+          }
+          lbtcData?: {
+            status: 'NOTARIZATION_STATUS_SESSION_APPROVED' | 'NOTARIZATION_STATUS_SESSION_PENDING'
+            attestation?: string
+            message_hash?: string
+          }
+        }[]
+      }
+    | {
+        encodedMessage: string
+        verificationComplete?: boolean
+        ccvData?: string[]
+        verifierAddresses: string[]
+      }
+  )

package/src/aptos/index.ts

@@ -560,13 +560,11 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
     payer,
     ...opts
   }: Parameters<Chain['generateUnsignedExecute']>[0]): Promise<UnsignedAptosTx> {
+    const resolved = await this.resolveExecuteOpts(opts)
     if (
-      !(
-        'input' in opts &&
-        'message' in opts.input &&
-        'allowOutOfOrderExecution' in opts.input.message &&
-        'gasLimit' in opts.input.message
-      )
+      !('message' in resolved.input) ||
+      !('allowOutOfOrderExecution' in resolved.input.message) ||
+      !('gasLimit' in resolved.input.message)
     ) {
       throw new CCIPAptosExtraArgsV2RequiredError()
     }
@@ -574,9 +572,9 @@ export class AptosChain extends Chain<typeof ChainFamily.Aptos> {
     const tx = await generateUnsignedExecuteReport(
       this.provider,
       payer,
-      opts.offRamp,
-      opts.input as ExecutionInput<CCIPMessage_V1_6_EVM>,
-      opts,
+      resolved.offRamp,
+      resolved.input as ExecutionInput<CCIPMessage_V1_6_EVM>,
+      resolved,
     )
     return {
       family: ChainFamily.Aptos,

package/src/chain.ts

@@ -6,8 +6,10 @@ import type { UnsignedAptosTx } from './aptos/types.ts'
 import { getOnchainCommitReport } from './commits.ts'
 import {
   CCIPApiClientNotAvailableError,
+  CCIPArgumentInvalidError,
   CCIPChainFamilyMismatchError,
   CCIPExecTxRevertedError,
+  CCIPNotImplementedError,
   CCIPTokenPoolChainConfigNotFoundError,
   CCIPTransactionNotFinalizedError,
 } from './errors/index.ts'
@@ -26,6 +28,7 @@ import { getOffchainTokenData } from './offchain.ts'
 import { getMessagesInTx } from './requests.ts'
 import { DEFAULT_GAS_LIMIT } from './shared/constants.ts'
 import type { UnsignedSolanaTx } from './solana/types.ts'
+import type { UnsignedSuiTx } from './sui/types.ts'
 import type { UnsignedTONTx } from './ton/types.ts'
 import {
   type AnyMessage,
@@ -50,8 +53,12 @@ import {
 } from './types.ts'
 import { networkInfo, util, withRetry } from './utils.ts'
 
-/** Field names unique to GenericExtraArgsV3 (not present in V2). */
-const V3_ONLY_FIELDS = [
+/** All valid field names for GenericExtraArgsV2. */
+const V2_FIELDS = new Set(['gasLimit', 'allowOutOfOrderExecution'])
+
+/** All valid field names for GenericExtraArgsV3. */
+const V3_FIELDS = new Set([
+  'gasLimit',
   'blockConfirmations',
   'ccvs',
   'ccvArgs',
@@ -59,12 +66,26 @@ const V3_ONLY_FIELDS = [
   'executorArgs',
   'tokenReceiver',
   'tokenArgs',
-] as const
+])
+
+/** Throw if any key in extraArgs is not in the allowed set. */
+function assertNoUnknownFields(
+  extraArgs: Partial<ExtraArgs>,
+  allowed: Set<string>,
+  variant: string,
+): void {
+  const unknown = Object.keys(extraArgs).filter((k) => !allowed.has(k))
+  if (unknown.length)
+    throw new CCIPArgumentInvalidError(
+      'extraArgs',
+      `unknown field(s) for ${variant}: ${unknown.map((k) => JSON.stringify(k)).join(', ')}`,
+    )
+}
 
-/** Check if extraArgs contains any V3-only fields. */
+/** Check if extraArgs contains any V3-only fields (i.e. fields in V3 but not in V2). */
 function hasV3ExtraArgs(extraArgs: Partial<ExtraArgs> | undefined): boolean {
   if (!extraArgs) return false
-  return V3_ONLY_FIELDS.some((field) => field in extraArgs)
+  return Object.keys(extraArgs).some((k) => V3_FIELDS.has(k) && !V2_FIELDS.has(k))
 }
 
 /**
@@ -94,12 +115,13 @@ export type ChainContext = WithLogger & {
    * CCIP API client instance for lane information queries.
    *
    * - `undefined` (default): Creates CCIPAPIClient with {@link DEFAULT_API_BASE_URL}
+   * - `string`: Creates CCIPAPIClient with provided URL
    * - `CCIPAPIClient`: Uses provided instance (allows custom URL, fetch, etc.)
    * - `null`: Disables API client entirely (getLaneLatency() will throw)
    *
    * Default: `undefined` (auto-create with production endpoint)
    */
-  apiClient?: CCIPAPIClient | null
+  apiClient?: CCIPAPIClient | string | null
 
   /**
    * Retry configuration for API fallback operations.
@@ -173,6 +195,52 @@ export type TokenInfo = {
   readonly name?: string
 }
 
+/**
+ * Available lane feature keys.
+ * These represent features or thresholds that can be configured per-lane.
+ */
+export const LaneFeature = {
+  /**
+   * Minimum block confirmations for Faster Time to Finality (FTF).
+   * - **absent**: the lane does not support FTF (pre-v2.0 lane).
+   * - **0**: the lane supports FTF, but it is not enabled for this
+   *   token (e.g. the token pool predates FTF, or FTF is configured
+   *   to use default finality only).
+   * - **\> 0**: FTF is enabled; this is the minimum number of block
+   *   confirmations required to use it.
+   */
+  MIN_BLOCK_CONFIRMATIONS: 'MIN_BLOCK_CONFIRMATIONS',
+  /**
+   * Rate limiter bucket state for the lane/token with default finality.
+   */
+  RATE_LIMITS: 'RATE_LIMITS',
+  /**
+   * Rate limiter bucket state when using non-default finality (FTF).
+   * Only meaningful when FTF is supported on this lane, i.e.
+   * {@link LaneFeature.MIN_BLOCK_CONFIRMATIONS} is present and \> 0.
+   * If absent, the default rate limits ({@link LaneFeature.RATE_LIMITS}) apply even when using custom finality.
+   */
+  CUSTOM_BLOCK_CONFIRMATIONS_RATE_LIMITS: 'CUSTOM_BLOCK_CONFIRMATIONS_RATE_LIMITS',
+} as const
+/** Type representing one of the lane feature keys. */
+export type LaneFeature = (typeof LaneFeature)[keyof typeof LaneFeature]
+
+/**
+ * Lane features record.
+ * Maps feature keys to their values.
+ */
+export interface LaneFeatures extends Record<LaneFeature, unknown> {
+  /** Minimum block confirmations for FTF. */
+  MIN_BLOCK_CONFIRMATIONS: number
+  /** Rate limiter bucket state for the lane/token with default finality. */
+  RATE_LIMITS: RateLimiterState
+  /**
+   * Rate limiter bucket state when using non-default finality (FTF).
+   * If absent, the default rate limits ({@link LaneFeatures.RATE_LIMITS}) apply even when using custom finality.
+   */
+  CUSTOM_BLOCK_CONFIRMATIONS_RATE_LIMITS: RateLimiterState
+}
+
 /**
  * Options for getBalance query.
  */
@@ -231,11 +299,19 @@ export type TokenPoolRemote = {
    * - Version management (different pool implementations)
    */
   remotePools: string[]
-  /** Inbound rate limiter state for tokens coming into this chain. */
-  inboundRateLimiterState: RateLimiterState
   /** Outbound rate limiter state for tokens leaving this chain. */
   outboundRateLimiterState: RateLimiterState
-}
+  /** Inbound rate limiter state for tokens coming into this chain. */
+  inboundRateLimiterState: RateLimiterState
+} & (
+  | {
+      /** Outbound rate limiter state for tokens leaving this chain (FTF/v2). */
+      customBlockConfirmationsOutboundRateLimiterState: RateLimiterState
+      /** Inbound rate limiter state for tokens coming into this chain (FTF/v2). */
+      customBlockConfirmationsInboundRateLimiterState: RateLimiterState
+    }
+  | object
+)
 
 /**
  * Token pool configuration returned by {@link Chain.getTokenPoolConfig}.
@@ -256,6 +332,13 @@ export type TokenPoolConfig = {
    * May be undefined for older pool implementations that don't expose this method.
    */
   typeAndVersion?: string
+  /**
+   * Min custom block confirmations for Faster Time to Finality (FTF),
+   * if TokenPool version \>= v2.0.0 and FTF is supported on this lane.
+   * `0` indicates FTF is supported but not enabled for this token; `>0` indicates FTF is enabled
+   *  with this many minimum confirmations.
+   */
+  minBlockConfirmations?: number
 }
 
 /**
@@ -282,7 +365,7 @@ export type UnsignedTx = {
   [ChainFamily.Solana]: UnsignedSolanaTx
   [ChainFamily.Aptos]: UnsignedAptosTx
   [ChainFamily.TON]: UnsignedTONTx
-  [ChainFamily.Sui]: never // TODO
+  [ChainFamily.Sui]: UnsignedSuiTx
   [ChainFamily.Unknown]: never
 }
 
@@ -362,11 +445,11 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
     if (apiClient === null) {
       this.apiClient = null // Explicit opt-out
       this.apiRetryConfig = null // No retry config needed without API client
-    } else if (apiClient !== undefined) {
+    } else if (apiClient && typeof apiClient !== 'string') {
       this.apiClient = apiClient // Use provided instance
       this.apiRetryConfig = { ...DEFAULT_API_RETRY_CONFIG, ...apiRetryConfig }
     } else {
-      this.apiClient = CCIPAPIClient.fromUrl(undefined, { logger }) // Default
+      this.apiClient = CCIPAPIClient.fromUrl(apiClient, ctx) // default=undefined or provided string as URL
       this.apiRetryConfig = { ...DEFAULT_API_RETRY_CONFIG, ...apiRetryConfig }
     }
   }
@@ -929,6 +1012,25 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
     return getOffchainTokenData(request, this)
   }
 
+  /**
+   * Resolves {@link ExecuteOpts} that may contain a `messageId` (API shorthand) into the
+   * canonical `{ offRamp, input }` form required by {@link generateUnsignedExecute}.
+   *
+   * When `opts` already contains `input` the method is a no-op and returns it unchanged.
+   * When `opts` contains only a `messageId` it calls `apiClient.getExecutionInput` and merges
+   * the result back with any extra opts fields (e.g. `gasLimit`).
+   *
+   * @throws {@link CCIPApiClientNotAvailableError} if `messageId` is provided but no apiClient
+   */
+  protected async resolveExecuteOpts(
+    opts: ExecuteOpts,
+  ): Promise<Omit<ExecuteOpts, 'messageId'> & { offRamp: string; input: ExecutionInput }> {
+    if ('input' in opts) return opts
+    if (!this.apiClient) throw new CCIPApiClientNotAvailableError()
+    const { offRamp, ...input } = await this.apiClient.getExecutionInput(opts.messageId)
+    return { ...opts, offRamp, input }
+  }
+
   /**
    * Generate unsigned tx to manuallyExecute a message.
    *
@@ -1050,6 +1152,41 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
     return this.apiClient.getLaneLatency(this.network.chainSelector, destChainSelector)
   }
 
+  /**
+   * Retrieve features for a lane (router/destChainSelector/token triplet).
+   *
+   * @param _opts - Options containing router address, destChainSelector, and optional token
+   *   address (the token to be transferred in a hypothetical message on this lane)
+   * @returns Promise resolving to partial lane features record
+   *
+   * @throws {@link CCIPNotImplementedError} if not implemented for this chain family
+   *
+   * @example Get lane features
+   * ```typescript
+   * const features = await chain.getLaneFeatures({
+   *   router: '0x...',
+   *   destChainSelector: 4949039107694359620n,
+   * })
+   * // MIN_BLOCK_CONFIRMATIONS has three states:
+   * // - undefined: FTF is not supported on this lane (pre-v2.0)
+   * // - 0: the lane supports FTF, but it is not enabled for this token
+   * // - > 0: FTF is enabled with this many block confirmations
+   * const ftf = features.MIN_BLOCK_CONFIRMATIONS
+   * if (ftf != null && ftf > 0) {
+   *   console.log(`FTF enabled with ${ftf} confirmations`)
+   * } else if (ftf === 0) {
+   *   console.log('FTF supported on this lane but not enabled for this token')
+   * }
+   * ```
+   */
+  getLaneFeatures(_opts: {
+    router: string
+    destChainSelector: bigint
+    token?: string
+  }): Promise<Partial<LaneFeatures>> {
+    return Promise.reject(new CCIPNotImplementedError('getLaneFeatures'))
+  }
+
   /**
    * Default/generic implementation of getExecutionReceipts.
    * Yields execution receipts for a given offRamp.
@@ -1311,6 +1448,8 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
 
     // Detect if user wants V3 by checking for any V3-only field
     if (hasV3ExtraArgs(message.extraArgs)) {
+      if (message.extraArgs)
+        assertNoUnknownFields(message.extraArgs, V3_FIELDS, 'GenericExtraArgsV3')
       // V3 defaults (GenericExtraArgsV3)
       return {
         ...message,
@@ -1328,6 +1467,7 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
       }
     }
 
+    if (message.extraArgs) assertNoUnknownFields(message.extraArgs, V2_FIELDS, 'EVMExtraArgsV2')
     // Default to V2 (GenericExtraArgsV2, aka EVMExtraArgsV2)
     return {
       ...message,

package/src/errors/codes.ts

@@ -27,6 +27,7 @@ export const CCIPErrorCode = {
   MESSAGE_NOT_IN_BATCH: 'MESSAGE_NOT_IN_BATCH',
   MESSAGE_CHAIN_MISMATCH: 'MESSAGE_CHAIN_MISMATCH',
   MESSAGE_RETRIEVAL_FAILED: 'MESSAGE_RETRIEVAL_FAILED',
+  MESSAGE_NOT_VERIFIED_YET: 'MESSAGE_NOT_VERIFIED_YET',
 
   // Lane & Routing
   OFFRAMP_NOT_FOUND: 'OFFRAMP_NOT_FOUND',
@@ -109,7 +110,6 @@ export const CCIPErrorCode = {
   LBTC_ATTESTATION_NOT_FOUND: 'LBTC_ATTESTATION_NOT_FOUND',
   LBTC_ATTESTATION_NOT_APPROVED: 'LBTC_ATTESTATION_NOT_APPROVED',
   CCTP_DECODE_FAILED: 'CCTP_DECODE_FAILED',
-  CCTP_MULTIPLE_EVENTS: 'CCTP_MULTIPLE_EVENTS',
 
   // Log & Event
   LOG_DATA_INVALID: 'LOG_DATA_INVALID',
@@ -178,6 +178,7 @@ export const TRANSIENT_ERROR_CODES = new Set<CCIPErrorCode>([
   CCIPErrorCode.TRANSACTION_NOT_FINALIZED,
   CCIPErrorCode.MESSAGE_ID_NOT_FOUND,
   CCIPErrorCode.MESSAGE_BATCH_INCOMPLETE,
+  CCIPErrorCode.MESSAGE_NOT_VERIFIED_YET,
   CCIPErrorCode.COMMIT_NOT_FOUND,
   CCIPErrorCode.RECEIPT_NOT_FOUND,
   CCIPErrorCode.USDC_ATTESTATION_FAILED,

package/src/errors/index.ts

@@ -31,6 +31,7 @@ export {
   CCIPMessageInvalidError,
   CCIPMessageNotFoundInTxError,
   CCIPMessageNotInBatchError,
+  CCIPMessageNotVerifiedYetError,
   CCIPMessageRetrievalError,
 } from './specialized.ts'
 
@@ -100,7 +101,6 @@ export {
 export {
   CCIPBlockTimeNotFoundError,
   CCIPCctpDecodeError,
-  CCIPCctpMultipleEventsError,
   CCIPExecutionReportChainMismatchError,
   CCIPExecutionStateInvalidError,
   CCIPExtraArgsLengthInvalidError,

package/src/errors/recovery.ts

@@ -37,6 +37,7 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
     'Verify you are using the correct destination chain. Check that sourceChainSelector and destChainSelector match your lane.',
   MESSAGE_RETRIEVAL_FAILED:
     'Both API and RPC failed to retrieve the message. Verify the transaction hash is correct and the transaction is confirmed. Check RPC and network connectivity.',
+  MESSAGE_NOT_VERIFIED_YET: 'Message not yet committed or verified; wait and retry.',
   MESSAGE_VERSION_INVALID:
     'Ensure the source chain onRamp uses CCIP v1.6. Older message versions are not compatible with this destination.',
 
@@ -129,7 +130,6 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
   LBTC_ATTESTATION_NOT_APPROVED: 'LBTC attestation not yet approved. Wait for notarization.',
   CCTP_DECODE_FAILED:
     'Ensure the transaction contains a valid CCTP MessageSent event. Verify this is a USDC transfer.',
-  CCTP_MULTIPLE_EVENTS: 'Multiple CCTP events found. Expected only one per transaction.',
 
   LOG_DATA_INVALID: 'Ensure the log data is a valid hex string from a transaction receipt.',
   LOG_DATA_MISSING: 'Log data is missing or not a string.',

package/src/errors/specialized.ts

@@ -380,6 +380,41 @@ export class CCIPMessageRetrievalError extends CCIPError {
   }
 }
 
+/**
+ * Thrown when a CCIP message has not been verified yet by the offchain system.
+ * This is a transient error - the message needs time to be verified before execution input can be retrieved.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const execInput = await api.getExecutionInput(messageId)
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageNotVerifiedYetError) {
+ *     console.log(`Message not verified yet, retry after ${error.retryAfterMs}ms`)
+ *     await sleep(error.retryAfterMs ?? 15000)
+ *     // Retry the request
+ *   }
+ * }
+ * ```
+ */
+export class CCIPMessageNotVerifiedYetError extends CCIPError {
+  override readonly name = 'CCIPMessageNotVerifiedYetError'
+  /** Creates a message not verified yet error. */
+  constructor(messageId: string, options?: CCIPErrorOptions) {
+    super(
+      CCIPErrorCode.MESSAGE_NOT_VERIFIED_YET,
+      `Message ${messageId} has not been verified yet. The offchain verification system needs time to process this message.`,
+      {
+        ...options,
+        isTransient: true,
+        retryAfterMs: 15000,
+        recovery: 'Wait for the message to be verified by the offchain system, then retry.',
+        context: { ...options?.context, messageId },
+      },
+    )
+  }
+}
+
 // Lane & Routing
 
 /**
@@ -3238,36 +3273,6 @@ export class CCIPSolanaLaneVersionUnsupportedError extends CCIPError {
   }
 }
 
-/**
- * Thrown when multiple CCTP events found in transaction.
- *
- * @example
- * ```typescript
- * try {
- *   const cctpData = await chain.getOffchainTokenData(request)
- * } catch (error) {
- *   if (error instanceof CCIPCctpMultipleEventsError) {
- *     console.log(`Found ${error.context.count} events, expected 1`)
- *   }
- * }
- * ```
- */
-export class CCIPCctpMultipleEventsError extends CCIPError {
-  override readonly name = 'CCIPCctpMultipleEventsError'
-  /** Creates a CCTP multiple events error. */
-  constructor(count: number, txSignature: string, options?: CCIPErrorOptions) {
-    super(
-      CCIPErrorCode.CCTP_MULTIPLE_EVENTS,
-      `Expected only 1 CcipCctpMessageSentEvent, found ${count} in transaction ${txSignature}`,
-      {
-        ...options,
-        isTransient: false,
-        context: { ...options?.context, count, txSignature },
-      },
-    )
-  }
-}
-
 /**
  * Thrown when compute units exceed limit.
  *