@chainlink/ccip-sdk 0.94.0 → 0.95.0

package/src/sui/objects.ts

@@ -5,9 +5,17 @@ import type { SuiClient } from '@mysten/sui/client'
 import { Transaction } from '@mysten/sui/transactions'
 import { normalizeSuiAddress } from '@mysten/sui/utils'
 import { blake2b } from '@noble/hashes/blake2.js'
+import { hexlify, toUtf8Bytes } from 'ethers'
+import { memoize } from 'micro-memoize'
 
 import { CCIPDataFormatUnsupportedError } from '../errors/index.ts'
 import type { CCIPMessage, CCIPVersion } from '../types.ts'
+import { toLeArray } from '../utils.ts'
+
+const bcsBytes = (bytes: Uint8Array) => bcs.vector(bcs.u8()).serialize(bytes).toBytes()
+
+const HASHING_INTENT_SCOPE_CHILD_OBJECT_ID = 0xf0
+const SUI_FRAMEWORK_ADDRESS = '0x2'
 
 /**
  * Derive a dynamic field object ID using the Sui algorithm
@@ -19,27 +27,24 @@ export function deriveObjectID(parentAddress: string, keyBytes: Uint8Array): str
   const parentBytes = bcs.Address.serialize(normalizedParent).toBytes()
 
   // BCS serialize the key (vector<u8>)
-  const bcsKeyBytes = bcs.vector(bcs.u8()).serialize(Array.from(keyBytes)).toBytes()
+  const bcsKeyBytes = bcsBytes(keyBytes)
+  const keyLenBytes = toLeArray(bcsKeyBytes.length, 8) // uint64
 
   // Construct TypeTag for DerivedObjectKey<vector<u8>>
-  const suiFrameworkAddress = bcs.Address.serialize('0x2').toBytes()
+  const suiFrameworkAddress = bcs.Address.serialize(SUI_FRAMEWORK_ADDRESS).toBytes()
   const typeTagBytes = new Uint8Array([
     0x07, // TypeTag::Struct
     ...suiFrameworkAddress,
-    0x0e, // module length
-    ...new TextEncoder().encode('derived_object'),
-    0x10, // struct name length
-    ...new TextEncoder().encode('DerivedObjectKey'),
+    ...bcsBytes(toUtf8Bytes('derived_object')), //module
+    ...bcsBytes(toUtf8Bytes('DerivedObjectKey')), // struct name
     0x01, // type params count
-    ...[0x06, 0x01], // vector<u8> TypeTag
+    0x06, // TypeTag::Vector
+    0x01, // TypeTag::U8
   ])
 
   // Build the hash input
-  const keyLenBytes = new Uint8Array(8)
-  new DataView(keyLenBytes.buffer).setBigUint64(0, BigInt(bcsKeyBytes.length), true)
-
   const hashInput = new Uint8Array([
-    0xf0, // HashingIntentScope::ChildObjectId
+    HASHING_INTENT_SCOPE_CHILD_OBJECT_ID,
     ...parentBytes,
     ...keyLenBytes,
     ...bcsKeyBytes,
@@ -49,101 +54,72 @@ export function deriveObjectID(parentAddress: string, keyBytes: Uint8Array): str
   // Hash with Blake2b-256
   const hash = blake2b(hashInput, { dkLen: 32 })
 
-  // Convert to address string
-  return normalizeSuiAddress('0x' + Buffer.from(hash).toString('hex'))
+  return hexlify(hash)
 }
 
 /**
- * Get the CCIPObjectRef ID for a CCIP package
+ * Finds the StatePointer object owned by a package.
+ * The StatePointer contains a reference to the parent object used for derivation.
  */
-export async function getCcipObjectRef(client: SuiClient, ccipPackageId: string): Promise<string> {
-  // Get the pointer to find the CCIPObject ID
-  const pointerResponse = await client.getOwnedObjects({
-    owner: ccipPackageId,
-    filter: {
-      StructType: `${ccipPackageId}::state_object::CCIPObjectRefPointer`,
-    },
-  })
-
-  if (!pointerResponse.data.length) {
-    throw new CCIPDataFormatUnsupportedError(
-      'No CCIPObjectRefPointer found for the given packageId',
-    )
-  }
-
-  // Get the pointer object to extract ccip_object_id
-  const pointerId = pointerResponse.data[0]!.data?.objectId
-  if (!pointerId) {
-    throw new CCIPDataFormatUnsupportedError('Pointer does not have objectId')
-  }
-
-  const pointerObject = await client.getObject({
-    id: pointerId,
-    options: { showContent: true },
-  })
-
-  if (pointerObject.data?.content?.dataType !== 'moveObject') {
-    throw new CCIPDataFormatUnsupportedError('Pointer object is not a Move object')
-  }
-
-  const ccipObjectId = (pointerObject.data.content.fields as Record<string, unknown>)[
-    'ccip_object_id'
-  ] as string
-
-  if (!ccipObjectId) {
-    throw new CCIPDataFormatUnsupportedError('Could not find ccip_object_id in pointer')
-  }
+export const getObjectRef = memoize(
+  async function getPackageIds_(address: string, client: SuiClient): Promise<string> {
+    let stateObjectName
+    if (address.endsWith('::onramp')) stateObjectName = 'OnRampState'
+    else if (address.endsWith('::offramp')) stateObjectName = 'OffRampState'
+    else stateObjectName = 'CCIPObjectRef'
+
+    const fullStatePointerType = `${address}::${stateObjectName}Pointer`
+
+    const ownedObjects = await client.getOwnedObjects({
+      owner: address.split('::')[0]!,
+      filter: { StructType: fullStatePointerType },
+      options: { showContent: true },
+    })
 
-  // Derive the CCIPObjectRef ID from the parent CCIPObject ID
-  return deriveObjectID(ccipObjectId, new TextEncoder().encode('CCIPObjectRef'))
-}
+    const pointer = ownedObjects.data[0]?.data
+    if (!pointer?.objectId || pointer.content!.dataType !== 'moveObject')
+      throw new CCIPDataFormatUnsupportedError(
+        'No CCIP ObjectRef Pointer found for the given packageId',
+        { context: { fullStatePointerType, pointer } },
+      )
+    // const statePointerObjectId = pointer.objectId
+    const parentObjectId = Object.entries(pointer.content!.fields).find(([key]) =>
+      key.endsWith('_object_id'),
+    )?.[1]
+    if (typeof parentObjectId !== 'string')
+      throw new CCIPDataFormatUnsupportedError('No parent object id found inthe given pointer', {
+        context: { fullStatePointerType, pointer },
+      })
+    return deriveObjectID(parentObjectId, toUtf8Bytes(stateObjectName))
+  },
+  { maxArgs: 1, expires: 300e3, async: true },
+)
 
 /**
- * Get the OffRampState object ID for an offramp package
+ * Finds the StatePointer object owned by a package.
+ * The StatePointer contains a reference to the parent object used for derivation.
  */
-export async function getOffRampStateObject(
-  client: SuiClient,
-  offrampPackageId: string,
-): Promise<string> {
-  const offrampPointerResponse = await client.getOwnedObjects({
-    owner: offrampPackageId,
-    filter: {
-      StructType: `${offrampPackageId}::offramp::OffRampStatePointer`,
-    },
-  })
-
-  if (!offrampPointerResponse.data.length) {
-    throw new CCIPDataFormatUnsupportedError(
-      'No OffRampStatePointer found for the given offramp package',
-    )
-  }
-
-  const offrampPointerId = offrampPointerResponse.data[0]!.data?.objectId
-
-  if (!offrampPointerId) {
-    throw new CCIPDataFormatUnsupportedError('OffRampStatePointer does not have a valid objectId')
-  }
-
-  const offrampPointerObject = await client.getObject({
-    id: offrampPointerId,
-    options: { showContent: true },
-  })
-
-  if (offrampPointerObject.data?.content?.dataType !== 'moveObject') {
-    throw new CCIPDataFormatUnsupportedError('OffRamp pointer object is not a Move object')
-  }
-
-  const offrampObjectId = (offrampPointerObject.data.content.fields as Record<string, unknown>)[
-    'off_ramp_object_id'
-  ] as string
-
-  if (!offrampObjectId) {
-    throw new CCIPDataFormatUnsupportedError('Could not find off_ramp_object_id in pointer')
-  }
-
-  // Derive the OffRampState ID from the parent OffRamp Object ID
-  return deriveObjectID(offrampObjectId, new TextEncoder().encode('OffRampState'))
-}
+export const getLatestPackageId = memoize(
+  async function getLatestPackageId_(address: string, client: SuiClient): Promise<string> {
+    const suffix = address.split('::')[1]
+    try {
+      const stateObjectId = await getObjectRef(address, client)
+      const stateObject = await client.getObject({
+        id: stateObjectId,
+        options: { showContent: true },
+      })
+      const stateContent = stateObject.data?.content
+      if (stateContent?.dataType !== 'moveObject') return address
+      const packageIdsField = (stateContent.fields as Record<string, unknown>)['package_ids']
+      if (!Array.isArray(packageIdsField) || packageIdsField.length === 0) return address
+      const latest = packageIdsField[packageIdsField.length - 1] as string
+      return suffix ? `${latest}::${suffix}` : latest
+    } catch {
+      return address
+    }
+  },
+  { maxArgs: 1, expires: 60e3, async: true },
+)
 
 /**
  * Get the receiver module configuration from the receiver registry.

package/src/sui/types.ts

@@ -15,6 +15,16 @@ export const SuiExtraArgsV1Codec = bcs.struct('SuiExtraArgsV1', {
   receiverObjectIds: bcs.vector(bcs.vector(bcs.u8())),
 })
 
+/** Token amount data structure for Sui CCIP messages. */
+export type SuiTokenAmount = {
+  source_pool_address?: string
+  dest_token_address?: number[]
+  extra_data?: number[]
+  amount?: string | number
+  dest_exec_data?: number[]
+  dest_gas_amount?: string | number
+}
+
 /**
  * Encodes Sui v1 extra arguments using BCS encoding.
  * @param args - Sui extra arguments to encode.
@@ -26,3 +36,28 @@ export function encodeSuiExtraArgsV1(args: SuiExtraArgsV1): string {
   const bcsData = SuiExtraArgsV1Codec.serialize({ ...args, tokenReceiver, receiverObjectIds })
   return concat([SuiExtraArgsV1Tag, bcsData.toBytes()])
 }
+
+/**
+ * Sui-specific CCIP message log structure from events.
+ */
+export type SuiCCIPMessageLog = {
+  dest_chain_selector: string
+  message: {
+    data: number[]
+    extra_args: number[]
+    fee_token: string
+    fee_token_amount: string
+    fee_value_juels: string
+    header: {
+      dest_chain_selector: string
+      message_id: number[]
+      nonce: string
+      sequence_number: string
+      source_chain_selector: string
+    }
+    receiver: number[]
+    sender: string
+    token_amounts: SuiTokenAmount[]
+  }
+  sequence_number: string
+}

package/src/ton/index.ts

@@ -8,7 +8,7 @@ import { type Memoized, memoize } from 'micro-memoize'
 import type { PickDeep } from 'type-fest'
 
 import { streamTransactionsForAddress } from './logs.ts'
-import { type ChainContext, type LogFilter, Chain } from '../chain.ts'
+import { type ChainContext, type GetBalanceOpts, type LogFilter, Chain } from '../chain.ts'
 import {
   CCIPArgumentInvalidError,
   CCIPExtraArgsInvalidError,
@@ -21,7 +21,6 @@ import {
   CCIPWalletInvalidError,
 } from '../errors/specialized.ts'
 import { type EVMExtraArgsV2, type ExtraArgs, EVMExtraArgsV2Tag } from '../extra-args.ts'
-import { getMessagesInTx } from '../requests.ts'
 import { supportedChains } from '../supported-chains.ts'
 import {
   type CCIPExecution,
@@ -164,13 +163,13 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     ctx?: ChainContext & { fetchFn?: typeof fetch },
   ): Promise<TONChain> {
     // Verify connection by getting the latest block
-    const isTestnet =
+    const isMainnet =
       (
         await client.getContractState(
           Address.parse('EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs'), // mainnet USDT
         )
-      ).state !== 'active'
-    return new TONChain(client, networkInfo(isTestnet ? 'ton-testnet' : 'ton-mainnet'), ctx)
+      ).state === 'active'
+    return new TONChain(client, networkInfo(isMainnet ? 'ton-mainnet' : 'ton-testnet'), ctx)
   }
 
   /**
@@ -264,7 +263,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
           )
         const txInfo = await lookupTxByRawHash(
           cleanHash,
-          this.network.isTestnet,
+          this.network.networkType,
           this.rateLimitedFetch,
           this,
         )
@@ -363,11 +362,6 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     }
   }
 
-  /** {@inheritDoc Chain.getMessagesInTx} */
-  override async getMessagesInTx(tx: string | ChainTransaction): Promise<CCIPRequest[]> {
-    return getMessagesInTx(this, typeof tx === 'string' ? await this.getTransaction(tx) : tx)
-  }
-
   /** {@inheritDoc Chain.getMessagesInBatch} */
   override async getMessagesInBatch<
     R extends PickDeep<
@@ -525,6 +519,11 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     }
   }
 
+  /** {@inheritDoc Chain.getBalance} */
+  async getBalance(_opts: GetBalanceOpts): Promise<bigint> {
+    return Promise.reject(new CCIPNotImplementedError('TONChain.getBalance'))
+  }
+
   /** {@inheritDoc Chain.getTokenAdminRegistryFor} */
   getTokenAdminRegistryFor(_address: string): Promise<string> {
     return Promise.reject(new CCIPNotImplementedError('getTokenAdminRegistryFor'))

package/src/ton/utils.ts

@@ -2,7 +2,7 @@ import { Cell, Dictionary, beginCell } from '@ton/core'
 import { hexlify, toBeHex } from 'ethers'
 
 import { CCIPTransactionNotFoundError } from '../errors/specialized.ts'
-import type { WithLogger } from '../types.ts'
+import { type WithLogger, NetworkType } from '../types.ts'
 import { bytesToBuffer } from '../utils.ts'
 
 /**
@@ -340,14 +340,14 @@ export async function parseJettonContent(
  * TonCenter V3 provides an index that allows hash-only lookups.
  *
  * @param hash - Raw 64-char hex transaction hash
- * @param isTestnet - Whether to use testnet API
+ * @param networkType - Network type (mainnet or testnet)
  * @param fetch - Rate-limited fetch function
  * @param logger - Logger instance
  * @returns Transaction identifier components needed for V4 API lookup
  */
 export async function lookupTxByRawHash(
   hash: string,
-  isTestnet: boolean,
+  networkType: NetworkType,
   fetch = globalThis.fetch,
   { logger = console }: WithLogger = {},
 ): Promise<{
@@ -355,9 +355,10 @@ export async function lookupTxByRawHash(
   lt: string
   hash: string
 }> {
-  const baseUrl = isTestnet
-    ? 'https://testnet.toncenter.com/api/v3/transactions'
-    : 'https://toncenter.com/api/v3/transactions'
+  const baseUrl =
+    networkType === NetworkType.Mainnet
+      ? 'https://toncenter.com/api/v3/transactions'
+      : 'https://testnet.toncenter.com/api/v3/transactions'
 
   // TonCenter V3 accepts hex directly
   const cleanHash = bytesToBuffer(hash).toString('hex')

package/src/types.ts

@@ -60,15 +60,26 @@ export type MergeArrayElements<T, U> = {
  * Enumeration of supported blockchain families.
  */
 export const ChainFamily = {
-  EVM: 'evm',
-  Solana: 'solana',
-  Aptos: 'aptos',
-  Sui: 'sui',
-  TON: 'ton',
+  EVM: 'EVM',
+  Solana: 'SVM',
+  Aptos: 'APTOS',
+  Sui: 'SUI',
+  TON: 'TON',
+  Unknown: 'UNKNOWN',
 } as const
 /** Type representing one of the supported chain families. */
 export type ChainFamily = (typeof ChainFamily)[keyof typeof ChainFamily]
 
+/**
+ * Enumeration of network types (mainnet vs testnet).
+ */
+export const NetworkType = {
+  Mainnet: 'MAINNET',
+  Testnet: 'TESTNET',
+} as const
+/** Type representing the network environment type. */
+export type NetworkType = (typeof NetworkType)[keyof typeof NetworkType]
+
 /**
  * Enumeration of supported CCIP protocol versions.
  */
@@ -88,7 +99,7 @@ type ChainFamilyWithId<F extends ChainFamily> = F extends
   : F extends typeof ChainFamily.Solana
     ? { readonly family: F; readonly chainId: string }
     : F extends typeof ChainFamily.Aptos | typeof ChainFamily.Sui
-      ? { readonly family: F; readonly chainId: `${F}:${number}` }
+      ? { readonly family: F; readonly chainId: `${Lowercase<F>}:${number}` }
       : never
 
 /**
@@ -99,8 +110,8 @@ export type NetworkInfo<F extends ChainFamily = ChainFamily> = {
   readonly chainSelector: bigint
   /** Human-readable network name. */
   readonly name: string
-  /** Whether this is a testnet. */
-  readonly isTestnet: boolean
+  /** Network environment type. */
+  readonly networkType: NetworkType
 } & ChainFamilyWithId<F>
 
 /**
@@ -216,6 +227,12 @@ export const MessageStatus = {
   Success: 'SUCCESS',
   /** Message execution failed on destination. */
   Failed: 'FAILED',
+  /** Message is being verified by the CCIP network */
+  Verifying: 'VERIFYING',
+  /** Message has been verified by the CCIP network */
+  Verified: 'VERIFIED',
+  /** Unknown status returned by API */
+  Unknown: 'UNKNOWN',
 } as const
 /** Type representing a CCIP message lifecycle status. */
 export type MessageStatus = (typeof MessageStatus)[keyof typeof MessageStatus]

package/src/utils.ts

@@ -12,6 +12,7 @@ import {
   toBigInt,
 } from 'ethers'
 import { memoize } from 'micro-memoize'
+import yaml from 'yaml'
 
 import type { Chain, ChainStatic } from './chain.ts'
 import {
@@ -24,6 +25,7 @@ import {
   CCIPTypeVersionInvalidError,
   HttpStatus,
 } from './errors/index.ts'
+import { getRetryDelay, shouldRetry } from './errors/utils.ts'
 import SELECTORS from './selectors.ts'
 import { supportedChains } from './supported-chains.ts'
 import { type NetworkInfo, type WithLogger, ChainFamily } from './types.ts'
@@ -103,6 +105,9 @@ export async function getSomeBlockNumberBefore(
   return beforeBlockNumber
 }
 
+/**
+ * Checks if a chain is a testnet
+ */
 // memoized so we always output the same object for a given chainId
 const networkInfoFromChainId = memoize((chainId: NetworkInfo['chainId']): NetworkInfo => {
   const sel = SELECTORS[chainId]
@@ -112,7 +117,7 @@ const networkInfoFromChainId = memoize((chainId: NetworkInfo['chainId']): Networ
     chainSelector: sel.selector,
     name: sel.name,
     family: sel.family,
-    isTestnet: !sel.name.includes('-mainnet'),
+    networkType: sel.network_type,
   } as NetworkInfo
 })
 
@@ -220,13 +225,23 @@ export function bigIntReviver(_key: string, value: unknown): unknown {
   return value
 }
 
+/**
+ * Parses JSON text with BigInt support for large integers.
+ * Uses yaml parser which handles integers as BigInt when they exceed safe integer range.
+ * @param text - JSON string to parse
+ * @returns Parsed object with large integers as BigInt
+ */
+export function parseJson<T = unknown>(text: string): T {
+  return yaml.parse(text, { intAsBigInt: true }) as T
+}
+
 /**
  * Decode address from a 32-byte hex string
  **/
 export function decodeAddress(address: BytesLike, family: ChainFamily = ChainFamily.EVM): string {
   const chain = supportedChains[family]
   if (!chain) throw new CCIPChainFamilyUnsupportedError(family)
-  return chain.getAddress(getAddressBytes(address))
+  return chain.getAddress(address)
 }
 
 /**
@@ -255,7 +270,7 @@ export function decodeOnRampAddress(
   family: ChainFamily = ChainFamily.EVM,
 ): string {
   let decoded = decodeAddress(address, family)
-  if (family === ChainFamily.Aptos) decoded += '::onramp'
+  if (family === ChainFamily.Aptos || family === ChainFamily.Sui) decoded += '::onramp'
   return decoded
 }
 
@@ -299,6 +314,8 @@ export function getDataBytes(data: BytesLike | readonly number[]): Uint8Array {
   if (Array.isArray(data)) return new Uint8Array(data)
   if (typeof data === 'string' && data.match(/^[0-9a-f]+[a-f][0-9a-f]+$/i)) data = '0x' + data
   else if (typeof data === 'string' && data.match(/^0X[0-9a-fA-F]+$/)) data = data.toLowerCase()
+  if (typeof data === 'string' && data.startsWith('0x') && data.length % 2)
+    data = '0x0' + data.slice(2)
   if (isBytesLike(data)) {
     return getBytes(data)
   } else if (isBase64(data)) {
@@ -322,20 +339,33 @@ export function bytesToBuffer(bytes: BytesLike | readonly number[]): Buffer {
  * @param address - Address in hex or Base58 format.
  * @returns Address bytes as Uint8Array.
  */
-export function getAddressBytes(address: BytesLike): Uint8Array {
-  let bytes: Uint8Array
-  if (isBytesLike(address)) {
-    bytes = getBytes(address)
+export function getAddressBytes(address: BytesLike | readonly number[]): Uint8Array {
+  let bytes
+  if (address instanceof Uint8Array) {
+    bytes = address
+  } else if (Array.isArray(address)) {
+    bytes = new Uint8Array(address)
+  } else if (
+    typeof address === 'string' &&
+    address.match(/^((0x[0-9a-f]*)|[0-9a-f]{40,})(::.*)?$/i)
+  ) {
+    address = address.split('::')[0]! // discard possible Aptos/Sui module suffix
+    // supports with or without (long>=20B) 0x-prefix, odd or even length
+    bytes = getBytes(
+      address.length % 2
+        ? '0x0' + (address.toLowerCase().startsWith('0x') ? address.slice(2) : address)
+        : !address.toLowerCase().startsWith('0x')
+          ? '0x' + address
+          : address,
+    )
   } else {
-    bytes = bs58.decode(address)
-  }
-  if (bytes.length > 20) {
-    if (
-      bytes.slice(0, bytes.length - 20).every((b) => b === 0) &&
-      bytes.slice(-20).some((b) => b !== 0)
-    ) {
-      bytes = bytes.slice(-20)
+    try {
+      const bytes_ = bs58.decode(address as string)
+      if (bytes_.length % 32 === 0) bytes = bytes_
+    } catch (_) {
+      // pass
     }
+    if (!bytes) bytes = decodeBase64(address as string)
   }
   return bytes
 }
@@ -356,7 +386,9 @@ export function convertKeysToCamelCase(
   mapValues?: (value: unknown, key?: string) => unknown,
   key?: string,
 ): unknown {
-  if (Array.isArray(obj)) {
+  if (Array.isArray(obj) && obj.every((v) => typeof v === 'number')) {
+    return mapValues ? mapValues(obj, key) : obj
+  } else if (Array.isArray(obj)) {
     return obj.map((v) => convertKeysToCamelCase(v, mapValues, key))
   }
 
@@ -379,6 +411,109 @@ export function convertKeysToCamelCase(
  */
 export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms).unref())
 
+/**
+ * Configuration for the withRetry utility.
+ */
+export type WithRetryConfig = {
+  /** Maximum number of retry attempts */
+  maxRetries: number
+  /** Initial delay in milliseconds before the first retry */
+  initialDelayMs: number
+  /** Multiplier applied to delay after each retry */
+  backoffMultiplier: number
+  /** Maximum delay in milliseconds between retries */
+  maxDelayMs: number
+  /** Whether to respect the error's retryAfterMs hint */
+  respectRetryAfterHint: boolean
+  /** Optional logger for retry attempts */
+  logger?: { debug: (...args: unknown[]) => void; warn: (...args: unknown[]) => void }
+}
+
+/**
+ * Executes an async operation with retry logic and exponential backoff.
+ * Only retries on transient errors (as determined by shouldRetry from errors/utils).
+ *
+ * @param operation - Async function to execute
+ * @param config - Retry configuration
+ * @returns Promise resolving to the operation result
+ * @throws The last error encountered after all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => apiClient.getMessageById(id),
+ *   {
+ *     maxRetries: 3,
+ *     initialDelayMs: 1000,
+ *     backoffMultiplier: 2,
+ *     maxDelayMs: 30000,
+ *     respectRetryAfterHint: true,
+ *   }
+ * )
+ * ```
+ */
+export async function withRetry<T>(
+  operation: () => Promise<T>,
+  config: WithRetryConfig,
+): Promise<T> {
+  const {
+    maxRetries,
+    initialDelayMs,
+    backoffMultiplier,
+    maxDelayMs,
+    respectRetryAfterHint,
+    logger,
+  } = config
+
+  let lastError: CCIPError | undefined
+  let delay = initialDelayMs
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation()
+    } catch (err) {
+      lastError = CCIPError.isCCIPError(err) ? err : CCIPError.from(err, 'UNKNOWN')
+
+      // Only retry on transient errors
+      if (!shouldRetry(lastError)) {
+        throw lastError
+      }
+
+      // Don't sleep after the last attempt
+      if (attempt >= maxRetries) {
+        logger?.warn(`All ${maxRetries} retries exhausted:`, lastError.message)
+        break
+      }
+
+      // Calculate delay for next retry
+      let nextDelay = delay
+
+      // Respect error's retryAfterMs hint if configured
+      if (respectRetryAfterHint) {
+        const hintDelay = getRetryDelay(lastError)
+        if (hintDelay !== null) {
+          nextDelay = Math.max(delay, hintDelay)
+        }
+      }
+
+      // Cap at maxDelayMs
+      nextDelay = Math.min(nextDelay, maxDelayMs)
+
+      logger?.debug(
+        `Retry attempt ${attempt + 1}/${maxRetries} after ${nextDelay}ms:`,
+        lastError.message,
+      )
+
+      await sleep(nextDelay)
+
+      // Apply exponential backoff for next iteration
+      delay = Math.min(delay * backoffMultiplier, maxDelayMs)
+    }
+  }
+
+  throw lastError!
+}
+
 /**
  * Parses a typeAndVersion string into its components.
  * @param typeAndVersion - String in format "TypeName vX.Y.Z".