@chainlink/ccip-sdk 1.1.0 → 1.2.0

package/src/chain.ts

@@ -1,4 +1,4 @@
-import { type BytesLike, dataLength } from 'ethers'
+import { type BytesLike, dataLength, keccak256 } from 'ethers'
 import type { PickDeep, SetOptional } from 'type-fest'
 
 import { type LaneLatencyResponse, CCIPAPIClient } from './api/index.ts'
@@ -24,10 +24,12 @@ import type {
   SuiExtraArgsV1,
 } from './extra-args.ts'
 import type { LeafHasher } from './hasher/common.ts'
+import { decodeMessageV1 } from './messages.ts'
 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,
@@ -67,7 +69,7 @@ const V3_FIELDS = new Set([
   'tokenArgs',
 ])
 
-/** Throw if any key in extraArgs is not in the allowed set. */
+/** Throw {@link CCIPArgumentInvalidError} if any key in extraArgs is not in the allowed set. */
 function assertNoUnknownFields(
   extraArgs: Partial<ExtraArgs>,
   allowed: Set<string>,
@@ -200,7 +202,7 @@ export type TokenInfo = {
  */
 export const LaneFeature = {
   /**
-   * Minimum block confirmations for Faster Time to Finality (FTF).
+   * Minimum block confirmations for Faster-Than-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
@@ -284,6 +286,11 @@ export type RateLimiterState = {
  * @remarks
  * Each entry represents the configuration needed to transfer tokens
  * from the current chain to a specific destination chain.
+ *
+ * The `customBlockConfirmationsOutboundRateLimiterState` and
+ * `customBlockConfirmationsInboundRateLimiterState` fields are present only for
+ * TokenPool v2.0+ contracts. These provide separate rate limits applied when
+ * Faster-Than-Finality (FTF) custom block confirmations are used.
  */
 export type TokenPoolRemote = {
   /** Address of the remote token on the destination chain. */
@@ -332,7 +339,7 @@ export type TokenPoolConfig = {
    */
   typeAndVersion?: string
   /**
-   * Min custom block confirmations for Faster Time to Finality (FTF),
+   * Min custom block confirmations for Faster-Than-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.
@@ -364,7 +371,7 @@ export type UnsignedTx = {
   [ChainFamily.Solana]: UnsignedSolanaTx
   [ChainFamily.Aptos]: UnsignedAptosTx
   [ChainFamily.TON]: UnsignedTONTx
-  [ChainFamily.Sui]: never // TODO
+  [ChainFamily.Sui]: UnsignedSuiTx
   [ChainFamily.Unknown]: never
 }
 
@@ -395,7 +402,7 @@ export type ExecuteOpts = (
   | {
       /**
        * messageId of message to execute; requires `apiClient`.
-       * @remarks Currently throws CCIPNotImplementedError - API endpoint pending.
+       * The SDK will fetch execution inputs (offRamp, proofs/verifications) from the CCIP API.
        */
       messageId: string
     }
@@ -1011,6 +1018,71 @@ 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`).
+   * If opts.gasLimit is undefined and `estimateReceiveExecution` is available, try to estimate gasLimitOverride
+   *
+   * @throws {@link CCIPApiClientNotAvailableError} if `messageId` is provided but no apiClient
+   */
+  protected async resolveExecuteOpts(
+    opts: ExecuteOpts,
+  ): Promise<Extract<ExecuteOpts, { input: unknown }>> {
+    let opts_: Extract<typeof opts, { input: unknown }>
+    if ('input' in opts) {
+      opts_ = opts
+    } else if (!this.apiClient) throw new CCIPApiClientNotAvailableError()
+    else {
+      const { offRamp, ...input } = await this.apiClient.getExecutionInput(opts.messageId)
+      opts_ = { ...opts, offRamp, input }
+    }
+
+    if (
+      opts_.gasLimit == null &&
+      this.estimateReceiveExecution &&
+      (!('message' in opts_.input) ||
+        !opts_.input.message.tokenAmounts.length ||
+        opts_.input.message.tokenAmounts.every((ta) => 'destTokenAddress' in ta))
+    ) {
+      let message
+      if ('message' in opts_.input) {
+        message = {
+          ...opts_.input.message,
+          // pass `tokenAmount` with `destTokenAddress` to estimate
+          destTokenAmounts: opts_.input.message.tokenAmounts,
+        }
+      } else {
+        const decoded = decodeMessageV1(opts_.input.encodedMessage)
+        message = {
+          ...decoded,
+          messageId: keccak256(opts_.input.encodedMessage),
+          destTokenAmounts: decoded.tokenTransfer,
+        }
+      }
+      try {
+        const estimated = await this.estimateReceiveExecution({
+          offRamp: opts_.offRamp,
+          message,
+        })
+        this.logger.debug('Estimated receiver execution:', estimated)
+        if (
+          ('gasLimit' in message && estimated > message.gasLimit) ||
+          ('ccipReceiveGasLimit' in message && estimated > message.ccipReceiveGasLimit)
+        )
+          opts_.gasLimit = estimated
+      } catch (err) {
+        // ignore if receiver fails, let estimation of execute method itself throw if needed
+        this.logger.debug('Failed to auto-estimateReceiveExecution for:', opts, err)
+      }
+    }
+
+    return opts_
+  }
+
   /**
    * Generate unsigned tx to manuallyExecute a message.
    *
@@ -1036,21 +1108,24 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
   /**
    * Execute messages in report in an offRamp.
    *
-   * @param opts - {@link ExecuteOpts} with chain-specific wallet to sign and send tx
-   * @returns Promise resolving to transaction of the execution
+   * @param opts - {@link ExecuteOpts} with chain-specific wallet to sign and send tx.
+   * @returns Promise resolving to transaction of the execution.
    *
-   * @throws {@link CCIPWalletNotSignerError} if wallet is not a valid signer
-   * @throws {@link CCIPExecTxRevertedError} if execution transaction reverts
-   * @throws {@link CCIPMerkleRootMismatchError} if merkle proof is invalid
+   * @throws {@link CCIPWalletNotSignerError} if wallet is not a valid signer.
+   * @throws {@link CCIPExecTxNotConfirmedError} if execution transaction fails to confirm.
+   * @throws {@link CCIPExecTxRevertedError} if execution transaction reverts.
+   * @throws {@link CCIPMerkleRootMismatchError} if merkle proof is invalid.
    *
-   * @example Manual execution of pending message
+   * @example Manual execution using message ID (simplified, requires API)
+   * ```typescript
+   * const receipt = await dest.execute({ messageId: '0x...', wallet })
+   * ```
+   *
+   * @example Manual execution using transaction hash
    * ```typescript
    * const input = await source.getExecutionInput({ request, verifications })
    * const receipt = await dest.execute({ offRamp, input, wallet })
-   * console.log(`Executed: ${receipt.log.transactionHash}`)
    * ```
-   * @throws {@link CCIPWalletNotSignerError} if wallet cannot sign transactions
-   * @throws {@link CCIPExecTxNotConfirmedError} if execution transaction fails to confirm
    */
   abstract execute(
     opts: ExecuteOpts & {
@@ -1098,10 +1173,10 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    * Uses this chain's selector as the source.
    *
    * @param destChainSelector - Destination CCIP chain selector (bigint)
+   * @param numberOfBlocks - Optional number of block confirmations to use for latency
+   *   calculation. When omitted or 0, uses the lane's default finality. When provided
+   *   as a positive integer, the API returns latency for that custom finality value.
    * @returns Promise resolving to {@link LaneLatencyResponse} containing:
-   *   - `lane.sourceNetworkInfo` - Source chain metadata (name, selector, chainId)
-   *   - `lane.destNetworkInfo` - Destination chain metadata
-   *   - `lane.routerAddress` - Router contract address on source chain
    *   - `totalMs` - Estimated delivery time in milliseconds
    *
    * @throws {@link CCIPApiClientNotAvailableError} if apiClient was disabled (set to `null`)
@@ -1117,19 +1192,31 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    * try {
    *   const latency = await chain.getLaneLatency(4949039107694359620n) // Arbitrum
    *   console.log(`Estimated delivery: ${Math.round(latency.totalMs / 60000)} minutes`)
-   *   console.log(`Router: ${latency.lane.routerAddress}`)
    * } catch (err) {
    *   if (err instanceof CCIPHttpError) {
    *     console.error(`API error: ${err.context.apiErrorCode}`)
    *   }
    * }
    * ```
+   *
+   * @example Get latency with custom block confirmations
+   * ```typescript
+   * const latency = await chain.getLaneLatency(4949039107694359620n, 10)
+   * console.log(`Latency with 10 confirmations: ${Math.round(latency.totalMs / 60000)} minutes`)
+   * ```
    */
-  async getLaneLatency(destChainSelector: bigint): Promise<LaneLatencyResponse> {
+  async getLaneLatency(
+    destChainSelector: bigint,
+    numberOfBlocks?: number,
+  ): Promise<LaneLatencyResponse> {
     if (!this.apiClient) {
       throw new CCIPApiClientNotAvailableError()
     }
-    return this.apiClient.getLaneLatency(this.network.chainSelector, destChainSelector)
+    return this.apiClient.getLaneLatency(
+      this.network.chainSelector,
+      destChainSelector,
+      numberOfBlocks,
+    )
   }
 
   /**
@@ -1418,8 +1505,15 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
    * Returns a copy of a message, populating missing fields like `extraArgs` with defaults.
    * It's expected to return a message suitable at least for basic token transfers.
    *
-   * @param message - AnyMessage (from source), containing at least `receiver`
-   * @returns A message suitable for `sendMessage` to this destination chain family
+   * @param message - AnyMessage (from source), containing at least `receiver`.
+   * @returns A message suitable for `sendMessage` to this destination chain family.
+   *
+   * @remarks
+   * V3 (GenericExtraArgsV3) is auto-detected when any V3-only field is present
+   * (e.g. `blockConfirmations`, `ccvs`, `ccvArgs`, `executor`, `executorArgs`,
+   * `tokenReceiver`, `tokenArgs`). Otherwise defaults to V2 (EVMExtraArgsV2).
+   *
+   * @throws {@link CCIPArgumentInvalidError} if extraArgs contains unknown fields for the detected version.
    */
   static buildMessageForDest(
     message: Parameters<ChainStatic['buildMessageForDest']>[0],
@@ -1461,23 +1555,27 @@ export abstract class Chain<F extends ChainFamily = ChainFamily> {
 
   /**
    * Estimate `ccipReceive` execution cost (gas, computeUnits) for this *dest*
-   * @param opts - estimation options
+   * @param opts - estimation options, either `messageId` (for api) or `offRamp`, `message` (with `destTokenAmounts`)
    * @returns estimated execution cost (gas or computeUnits)
    */
-  estimateReceiveExecution?(opts: {
-    offRamp: string
-    receiver: string
-    message: {
-      sourceChainSelector: bigint
-      messageId: string
-      sender?: string
-      data?: BytesLike
-      destTokenAmounts?: readonly {
-        token: string
-        amount: bigint
-      }[]
-    }
-  }): Promise<number>
+  estimateReceiveExecution?(
+    opts:
+      | {
+          offRamp: string
+          message: {
+            sourceChainSelector: bigint
+            messageId: string
+            receiver: string
+            sender?: string
+            data?: BytesLike
+            destTokenAmounts?: readonly ((
+              | { token: string }
+              | { destTokenAddress: string; extraData?: string }
+            ) & { amount: bigint })[]
+          }
+        }
+      | { messageId: string },
+  ): Promise<number>
 }
 
 /**

package/src/errors/codes.ts

@@ -144,6 +144,7 @@ export const CCIPErrorCode = {
   HTTP_ERROR: 'HTTP_ERROR',
   RPC_NOT_FOUND: 'RPC_NOT_FOUND',
   TIMEOUT: 'TIMEOUT',
+  ABORT: 'ABORT',
 
   // API Client
   API_CLIENT_NOT_AVAILABLE: 'API_CLIENT_NOT_AVAILABLE',

package/src/errors/index.ts

@@ -156,6 +156,7 @@ export { CCIPBorshMethodUnknownError, CCIPBorshTypeUnknownError } from './specia
 
 // Specialized errors - HTTP & Data
 export {
+  CCIPAbortError,
   CCIPBlockBeforeTimestampNotFoundError,
   CCIPDataFormatUnsupportedError,
   CCIPDataParseError,

package/src/errors/recovery.ts

@@ -170,6 +170,8 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
   RPC_NOT_FOUND: 'No RPC endpoint found. Configure an RPC URL.',
   TIMEOUT:
     'Request timed out. Check network connectivity and try again. Consider increasing timeoutMs if the server is slow.',
+  ABORT:
+    'Request was aborted. This is usually intentional (e.g. user cancellation or component unmount).',
 
   VIEM_ADAPTER_ERROR:
     'Check that your viem client has both account and chain defined. For WalletClient, use createWalletClient({ chain, account, ... }).',

package/src/errors/specialized.ts

@@ -1,6 +1,7 @@
 import { type CCIPErrorOptions, CCIPError } from './CCIPError.ts'
 import { CCIPErrorCode } from './codes.ts'
 import { isTransientHttpStatus } from '../http-status.ts'
+import { bigIntReplacer } from '../utils.ts'
 
 // Chain/Network
 
@@ -166,7 +167,10 @@ export class CCIPMessageInvalidError extends CCIPError {
   override readonly name = 'CCIPMessageInvalidError'
   /** Creates a message invalid error. */
   constructor(data: unknown, options?: CCIPErrorOptions) {
-    const dataStr = typeof data === 'object' && data !== null ? JSON.stringify(data) : String(data)
+    const dataStr =
+      typeof data === 'object' && data !== null
+        ? JSON.stringify(data, bigIntReplacer)
+        : String(data)
     super(CCIPErrorCode.MESSAGE_INVALID, `Invalid CCIP message format: ${dataStr}`, {
       ...options,
       isTransient: false,
@@ -1203,6 +1207,34 @@ export class CCIPTimeoutError extends CCIPError {
   }
 }
 
+/**
+ * Thrown when a request is aborted via an AbortSignal.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController()
+ * setTimeout(() => controller.abort(), 1000)
+ * try {
+ *   await api.searchMessages({ sender: '0x...' }, { signal: controller.signal })
+ * } catch (error) {
+ *   if (error instanceof CCIPAbortError) {
+ *     console.log(`Request was cancelled: ${error.context.operation}`)
+ *   }
+ * }
+ * ```
+ */
+export class CCIPAbortError extends CCIPError {
+  override readonly name = 'CCIPAbortError'
+  /** Creates an abort error. */
+  constructor(operation: string, options?: CCIPErrorOptions) {
+    super(CCIPErrorCode.ABORT, `Request aborted: ${operation}`, {
+      ...options,
+      isTransient: false,
+      context: { ...options?.context, operation },
+    })
+  }
+}
+
 /**
  * Thrown for not implemented features.
  *

package/src/evm/abi/OffRamp_2_0.ts

@@ -222,9 +222,13 @@ export default [
     name: 'getAllSourceChainConfigs',
     inputs: [],
     outputs: [
-      { name: '', type: 'uint64[]', internalType: 'uint64[]' },
       {
-        name: '',
+        name: 'sourceChainSelectors',
+        type: 'uint64[]',
+        internalType: 'uint64[]',
+      },
+      {
+        name: 'sourceChainConfigs',
         type: 'tuple[]',
         internalType: 'struct OffRamp.SourceChainConfig[]',
         components: [
@@ -418,25 +422,6 @@ export default [
     ],
     anonymous: false,
   },
-  {
-    type: 'event',
-    name: 'MaxGasBufferToUpdateStateUpdated',
-    inputs: [
-      {
-        name: 'oldMaxGasBufferToUpdateState',
-        type: 'uint32',
-        indexed: false,
-        internalType: 'uint32',
-      },
-      {
-        name: 'newMaxGasBufferToUpdateState',
-        type: 'uint32',
-        indexed: false,
-        internalType: 'uint32',
-      },
-    ],
-    anonymous: false,
-  },
   {
     type: 'event',
     name: 'OwnershipTransferRequested',
@@ -611,6 +596,19 @@ export default [
     name: 'InvalidEncodingVersion',
     inputs: [{ name: 'version', type: 'uint8', internalType: 'uint8' }],
   },
+  {
+    type: 'error',
+    name: 'InvalidFinalityForReceiver',
+    inputs: [
+      { name: 'receiver', type: 'address', internalType: 'address' },
+      { name: 'msgBlockDepth', type: 'uint16', internalType: 'uint16' },
+      {
+        name: 'requiredBlockDepth',
+        type: 'uint16',
+        internalType: 'uint16',
+      },
+    ],
+  },
   {
     type: 'error',
     name: 'InvalidGasLimitOverride',

package/src/evm/abi/TokenPool_2_0.ts

@@ -1546,7 +1546,6 @@ export default [
     name: 'InvalidTransferFeeBps',
     inputs: [{ name: 'bps', type: 'uint256', internalType: 'uint256' }],
   },
-  { type: 'error', name: 'MismatchedArrayLengths', inputs: [] },
   { type: 'error', name: 'MustBeProposedOwner', inputs: [] },
   {
     type: 'error',

package/src/evm/gas.ts

@@ -1,4 +1,5 @@
 import {
+  type BytesLike,
   type JsonRpcApiProvider,
   Contract,
   FunctionFragment,
@@ -14,7 +15,6 @@ import {
 import type { TypedContract } from 'ethers-abitype'
 import { memoize } from 'micro-memoize'
 
-import type { Chain } from '../chain.ts'
 import TokenABI from './abi/BurnMintERC677Token.ts'
 import RouterABI from './abi/Router.ts'
 import { defaultAbiCoder, interfaces } from './const.ts'
@@ -77,13 +77,17 @@ const findBalancesSlot = memoize(
   { maxArgs: 1 },
 )
 
-type EstimateExecGasOpts = Pick<
-  Parameters<NonNullable<Chain['estimateReceiveExecution']>>[0],
-  'message' | 'receiver'
-> & {
-  /*  */
+type EstimateExecGasOpts = {
   provider: JsonRpcApiProvider
   router: string
+  message: {
+    sourceChainSelector: bigint
+    messageId: string
+    receiver: string
+    sender?: string
+    data?: BytesLike
+    destTokenAmounts?: readonly { token: string; amount: bigint }[]
+  }
 }
 
 /**
@@ -91,12 +95,7 @@ type EstimateExecGasOpts = Pick<
  * @param opts - Options for estimation: provider, destRouter, receiver address and message
  * @returns Estimated gasLimit
  */
-export async function estimateExecGas({
-  provider,
-  router,
-  receiver,
-  message,
-}: EstimateExecGasOpts) {
+export async function estimateExecGas({ provider, router, message }: EstimateExecGasOpts) {
   // we need to override the state, increasing receiver's balance for each token, to simulate the
   // state after tokens were transferred by the offRamp just before calling `ccipReceive`
   const destAmounts: Record<string, bigint> = {}
@@ -106,25 +105,24 @@ export async function estimateExecGas({
       const tokenContract = new Contract(token, TokenABI, provider) as unknown as TypedContract<
         typeof TokenABI
       >
-      const currentBalance = await tokenContract.balanceOf(receiver)
+      const currentBalance = await tokenContract.balanceOf(message.receiver)
       destAmounts[token] = currentBalance
     }
     destAmounts[token]! += amount
-    const balancesSlot = await findBalancesSlot(token, provider, receiver, router)
+    const balancesSlot = await findBalancesSlot(token, provider, message.receiver, router)
     stateOverrides[token] = {
       stateDiff: {
-        [solidityPackedKeccak256(['uint256', 'uint256'], [receiver, balancesSlot])]: toBeHex(
-          destAmounts[token]!,
-          32,
-        ),
+        [solidityPackedKeccak256(['uint256', 'uint256'], [message.receiver, balancesSlot])]:
+          toBeHex(destAmounts[token]!, 32),
       },
     }
   }
 
+  const senderBytes = getAddressBytes(message.sender ?? '0x')
   const receiverMsg: Any2EVMMessage = {
     ...message,
     destTokenAmounts: message.destTokenAmounts ?? [],
-    sender: zeroPadValue(getAddressBytes(message.sender ?? '0x'), 32),
+    sender: senderBytes.length < 32 ? zeroPadValue(senderBytes, 32) : hexlify(senderBytes),
     data: hexlify(getDataBytes(message.data || '0x')),
     sourceChainSelector: message.sourceChainSelector,
   }
@@ -138,7 +136,7 @@ export async function estimateExecGas({
       (await provider.send('eth_estimateGas', [
         {
           from: router,
-          to: receiver,
+          to: message.receiver,
           data: calldata,
         },
         'latest',