@chainlink/ccip-sdk 0.94.0 → 0.96.0

package/src/extra-args.ts

@@ -8,6 +8,8 @@ import { ChainFamily } from './types.ts'
 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 GenericExtraArgsV3 encoding (tightly packed binary format). */
+export const GenericExtraArgsV3Tag = '0x302326cb' as const
 /** Tag identifier for SVMExtraArgsV1 encoding. */
 export const SVMExtraArgsV1Tag = id('CCIP SVMExtraArgsV1').substring(0, 10) as '0x1f3b3aba'
 /** Tag identifier for SuiExtraArgsV1 encoding. */
@@ -15,6 +17,13 @@ export const SuiExtraArgsV1Tag = id('CCIP SuiExtraArgsV1').substring(0, 10) as '
 
 /**
  * EVM extra arguments version 1 with gas limit only.
+ *
+ * @example
+ * ```typescript
+ * const args: EVMExtraArgsV1 = {
+ *   gasLimit: 200_000n,
+ * }
+ * ```
  */
 export type EVMExtraArgsV1 = {
   /** Gas limit for execution on the destination chain. */
@@ -24,14 +33,70 @@ export type EVMExtraArgsV1 = {
 /**
  * EVM extra arguments version 2 with out-of-order execution support.
  * Also known as GenericExtraArgsV2.
+ *
+ * @example
+ * ```typescript
+ * const args: EVMExtraArgsV2 = {
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ * }
+ * ```
  */
 export type EVMExtraArgsV2 = EVMExtraArgsV1 & {
   /** Whether to allow out-of-order message execution. */
   allowOutOfOrderExecution: boolean
 }
 
+/**
+ * Generic extra arguments version 3 with cross-chain verifiers and executor support.
+ * Uses tightly packed binary encoding (NOT ABI-encoded).
+ *
+ * @example
+ * ```typescript
+ * const args: GenericExtraArgsV3 = {
+ *   gasLimit: 200_000n,
+ *   blockConfirmations: 5,
+ *   ccvs: ['0x1234...'],
+ *   ccvArgs: ['0x010203'],
+ *   executor: '0x5678...',
+ *   executorArgs: '0x',
+ *   tokenReceiver: '0xReceiverAddress...',
+ *   tokenArgs: '0x',
+ * }
+ * ```
+ */
+export type GenericExtraArgsV3 = {
+  /** Gas limit for execution on the destination chain (uint32). */
+  gasLimit: bigint
+  /** Number of block confirmations required. */
+  blockConfirmations: number
+  /** Cross-chain verifier addresses (EVM addresses). */
+  ccvs: string[]
+  /** Per-CCV arguments (BytesLike). */
+  ccvArgs: BytesLike[]
+  /** Executor address (EVM address or empty string for none). */
+  executor: string
+  /** Executor-specific arguments (BytesLike). */
+  executorArgs: BytesLike
+  /** Token receiver address (checksummed EVM address or hex string). */
+  tokenReceiver: string
+  /** Token pool-specific arguments (BytesLike). */
+  tokenArgs: BytesLike
+}
+
 /**
  * Solana (SVM) extra arguments version 1.
+ *
+ * @example
+ * ```typescript
+ * const args: SVMExtraArgsV1 = {
+ *   computeUnits: 200_000n,
+ *   accountIsWritableBitmap: 0n,
+ *   allowOutOfOrderExecution: true,
+ *   tokenReceiver: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
+ *   accounts: [],
+ * }
+ * ```
  */
 export type SVMExtraArgsV1 = {
   /** Compute units for Solana execution. */
@@ -48,6 +113,16 @@ export type SVMExtraArgsV1 = {
 
 /**
  * Sui extra arguments version 1.
+ *
+ * @example
+ * ```typescript
+ * const args: SuiExtraArgsV1 = {
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ *   tokenReceiver: '0x1234...abcd',
+ *   receiverObjectIds: ['0xobject1...', '0xobject2...'],
+ * }
+ * ```
  */
 export type SuiExtraArgsV1 = EVMExtraArgsV2 & {
   /** Token receiver address on Sui. */
@@ -59,13 +134,31 @@ export type SuiExtraArgsV1 = EVMExtraArgsV2 & {
 /**
  * Union type of all supported extra arguments formats.
  */
-export type ExtraArgs = EVMExtraArgsV1 | EVMExtraArgsV2 | SVMExtraArgsV1 | SuiExtraArgsV1
+export type ExtraArgs =
+  | EVMExtraArgsV1
+  | EVMExtraArgsV2
+  | GenericExtraArgsV3
+  | SVMExtraArgsV1
+  | SuiExtraArgsV1
 
 /**
  * Encodes extra arguments for CCIP messages.
- * The args are *to* a dest network, but are encoded as a message *from* this source chain
- * e.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targetting EVM
- **/
+ * The args are *to* a dest network, but are encoded as a message *from* this source chain.
+ * E.g. Solana uses Borsh to encode extraArgs in its produced requests, even those targeting EVM.
+ * @param args - Extra arguments to encode
+ * @param from - Source chain family for encoding format (defaults to EVM)
+ * @returns Encoded extra arguments as hex string
+ * @throws {@link CCIPChainFamilyUnsupportedError} if chain family not supported
+ *
+ * @example
+ * ```typescript
+ * const encoded = encodeExtraArgs({
+ *   gasLimit: 200_000n,
+ *   allowOutOfOrderExecution: true,
+ * })
+ * // Returns: '0x181dcf10...'
+ * ```
+ */
 export function encodeExtraArgs(args: ExtraArgs, from: ChainFamily = ChainFamily.EVM): string {
   const chain = supportedChains[from]
   if (!chain) throw new CCIPChainFamilyUnsupportedError(from)
@@ -77,6 +170,16 @@ export function encodeExtraArgs(args: ExtraArgs, from: ChainFamily = ChainFamily
  * @param data - Extra arguments bytearray data.
  * @param from - Optional chain family to narrow decoding attempts.
  * @returns Extra arguments object if found, undefined otherwise.
+ * @throws {@link CCIPChainFamilyUnsupportedError} if specified chain family not supported
+ * @throws {@link CCIPExtraArgsParseError} if data cannot be parsed as valid extra args
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeExtraArgs('0x181dcf10...')
+ * if (decoded?._tag === 'EVMExtraArgsV2') {
+ *   console.log(decoded.gasLimit, decoded.allowOutOfOrderExecution)
+ * }
+ * ```
  */
 export function decodeExtraArgs(
   data: BytesLike,
@@ -84,6 +187,7 @@ export function decodeExtraArgs(
 ):
   | (EVMExtraArgsV1 & { _tag: 'EVMExtraArgsV1' })
   | (EVMExtraArgsV2 & { _tag: 'EVMExtraArgsV2' })
+  | (GenericExtraArgsV3 & { _tag: 'GenericExtraArgsV3' })
   | (SVMExtraArgsV1 & { _tag: 'SVMExtraArgsV1' })
   | (SuiExtraArgsV1 & { _tag: 'SuiExtraArgsV1' })
   | undefined {

package/src/gas.ts

@@ -1,140 +1,126 @@
-import {
-  type BytesLike,
-  Contract,
-  FunctionFragment,
-  concat,
-  formatUnits,
-  getNumber,
-  hexlify,
-  randomBytes,
-  solidityPackedKeccak256,
-  toBeHex,
-  zeroPadValue,
-} from 'ethers'
-import type { TypedContract } from 'ethers-abitype'
+import { type BytesLike, formatUnits, hexlify, randomBytes } from 'ethers'
 
 import type { Chain } from './chain.ts'
 import {
-  CCIPLegacyTokenPoolsUnsupportedError,
+  CCIPContractTypeInvalidError,
+  CCIPMethodUnsupportedError,
   CCIPTokenDecimalsInsufficientError,
 } from './errors/index.ts'
-import TokenABI from './evm/abi/BurnMintERC677Token.ts'
-import RouterABI from './evm/abi/Router.ts'
-import { defaultAbiCoder } from './evm/const.ts'
-import type { EVMChain } from './evm/index.ts'
 import { discoverOffRamp } from './execution.ts'
-import type { Lane } from './types.ts'
+import { sourceToDestTokenAddresses } from './requests.ts'
 
-const BALANCES_SLOT = 0
-const ccipReceive = FunctionFragment.from({
-  type: 'function',
-  name: 'ccipReceive',
-  stateMutability: 'nonpayable',
-  inputs: RouterABI.find((v) => v.type === 'function' && v.name === 'routeMessage')!.inputs.slice(
-    0,
-    1,
-  ),
-  outputs: [],
-})
-type Any2EVMMessage = Parameters<TypedContract<typeof RouterABI>['routeMessage']>[0]
+/**
+ * A subset of {@link MessageInput} for estimating receive execution gas.
+ */
+export type EstimateMessageInput = {
+  /** receiver contract address */
+  receiver: string
+  /** optional messageId; random hash will be passed if omitted */
+  messageId?: string
+  /** optional sender: zero address will be used if omitted */
+  sender?: string
+  /** optional data: zero bytes will be used if omitted */
+  data?: BytesLike
+  /**
+   * optional tokenAmounts; `amount` with either source `token` (as in MessageInput) or
+   * `{ sourceTokenAddress?, sourcePoolAddress, destTokenAddress }` (as in v1.5..v1.7 tokenAmounts)
+   * can be provided
+   */
+  tokenAmounts?: readonly ({
+    amount: bigint
+  } & (
+    | { token: string }
+    | { sourceTokenAddress?: string; sourcePoolAddress: string; destTokenAddress: string }
+  ))[]
+}
+
+/**
+ * Options for {@link estimateReceiveExecution} function.
+ */
+export type EstimateReceiveExecutionOpts = {
+  /** Source chain instance (for token data retrieval) */
+  source: Chain
+  /** Dest chain instance (for token and execution simulation) */
+  dest: Chain
+  /** source router or onRamp, or dest offRamp contract address */
+  routerOrRamp: string
+  /** message to be simulated */
+  message: EstimateMessageInput
+}
 
 /**
  * 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.
+ * @param opts - Options for estimation: source and dest chains, router or ramp address, and message
+ * @returns Estimated gasLimit.
+ * @throws {@link CCIPMethodUnsupportedError} if dest chain doesn't support estimation
+ * @throws {@link CCIPContractTypeInvalidError} if routerOrRamp is not a valid contract type
+ * @throws {@link CCIPTokenDecimalsInsufficientError} if dest token has insufficient decimals
  */
-export async function estimateExecGasForRequest(
-  source: Chain,
-  dest: EVMChain,
-  request: {
-    lane: Lane
-    message: {
-      sender: string
-      receiver: string
-      data: BytesLike
-      tokenAmounts: readonly {
-        sourcePoolAddress: string
-        destTokenAddress: string
-        amount: bigint
-      }[]
+export async function estimateReceiveExecution({
+  source,
+  dest,
+  routerOrRamp,
+  message,
+}: EstimateReceiveExecutionOpts) {
+  if (!dest.estimateReceiveExecution)
+    throw new CCIPMethodUnsupportedError(dest.constructor.name, 'estimateReceiveExecution')
+
+  let onRamp, offRamp: string
+  try {
+    const tnv = await source.typeAndVersion(routerOrRamp)
+    if (!tnv[0].includes('OnRamp'))
+      onRamp = await source.getOnRampForRouter(routerOrRamp, dest.network.chainSelector)
+    else onRamp = routerOrRamp
+    offRamp = await discoverOffRamp(source, dest, onRamp, source)
+  } catch (sourceErr) {
+    try {
+      const tnv = await dest.typeAndVersion(routerOrRamp)
+      if (!tnv[0].includes('OffRamp'))
+        throw new CCIPContractTypeInvalidError(routerOrRamp, tnv[2], ['OffRamp'])
+      offRamp = routerOrRamp
+      onRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector)
+    } catch {
+      throw sourceErr // re-throw original error
     }
-  },
-) {
-  const offRamp = await discoverOffRamp(source, dest, request.lane.onRamp, source)
-  const destRouter = await dest.getRouterForOffRamp(offRamp, request.lane.sourceChainSelector)
+  }
 
   const destTokenAmounts = await Promise.all(
-    request.message.tokenAmounts.map(async (ta) => {
-      if (!('destTokenAddress' in ta)) throw new CCIPLegacyTokenPoolsUnsupportedError()
+    (message.tokenAmounts ?? []).map(async (ta) => {
+      const tokenAmount =
+        'destTokenAddress' in ta
+          ? ta
+          : await sourceToDestTokenAddresses(source, dest.network.chainSelector, onRamp, ta)
+      const sourceTokenAddress =
+        'token' in ta
+          ? ta.token
+          : ta.sourceTokenAddress
+            ? ta.sourceTokenAddress
+            : await source.getTokenForTokenPool(tokenAmount.sourcePoolAddress)
       const [{ decimals: sourceDecimals }, { decimals: destDecimals }] = await Promise.all([
-        source
-          .getTokenForTokenPool(ta.sourcePoolAddress)
-          .then((token) => source.getTokenInfo(token)),
-        dest.getTokenInfo(ta.destTokenAddress),
+        source.getTokenInfo(sourceTokenAddress),
+        dest.getTokenInfo(tokenAmount.destTokenAddress),
       ])
       const destAmount =
-        (ta.amount * 10n ** BigInt(destDecimals - sourceDecimals + 36)) / 10n ** 36n
+        (tokenAmount.amount * 10n ** BigInt(destDecimals)) / 10n ** BigInt(sourceDecimals)
       if (destAmount === 0n)
         throw new CCIPTokenDecimalsInsufficientError(
-          ta.destTokenAddress,
+          tokenAmount.destTokenAddress,
           destDecimals,
           dest.network.name,
-          formatUnits(ta.amount, sourceDecimals),
+          formatUnits(tokenAmount.amount, sourceDecimals),
         )
-      return { token: ta.destTokenAddress, amount: destAmount }
+      return { token: tokenAmount.destTokenAddress, amount: destAmount }
     }),
   )
-
-  const message: Any2EVMMessage = {
-    messageId: hexlify(randomBytes(32)),
-    sender: zeroPadValue(request.message.sender, 32),
-    data: hexlify(request.message.data),
-    sourceChainSelector: request.lane.sourceChainSelector,
-    destTokenAmounts,
-  }
-
-  // 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> = {}
-  const stateOverrides: Record<string, { stateDiff: Record<string, string> }> = {}
-  for (const { token, amount } of destTokenAmounts) {
-    if (!(token in destAmounts)) {
-      const tokenContract = new Contract(token, TokenABI, dest) as unknown as TypedContract<
-        typeof TokenABI
-      >
-      const currentBalance = await tokenContract.balanceOf(request.message.receiver)
-      destAmounts[token] = currentBalance
-    }
-    destAmounts[token]! += amount
-    stateOverrides[token] = {
-      stateDiff: {
-        [solidityPackedKeccak256(
-          ['uint256', 'uint256'],
-          [request.message.receiver, BALANCES_SLOT],
-        )]: toBeHex(destAmounts[token]!, 32),
-      },
-    }
-  }
-
-  const calldata = concat([
-    ccipReceive.selector,
-    defaultAbiCoder.encode(ccipReceive.inputs, [message]),
-  ])
-
-  return (
-    getNumber(
-      (await dest.provider.send('eth_estimateGas', [
-        {
-          from: destRouter,
-          to: request.message.receiver,
-          data: calldata,
-        },
-        'latest',
-        ...(Object.keys(stateOverrides).length ? [stateOverrides] : []),
-      ])) as string,
-    ) -
-    (21_000 - 700) // 21k is the base gas cost for a transaction, 700 is the gas cost of the call
-  )
+  return dest.estimateReceiveExecution({
+    receiver: message.receiver,
+    offRamp,
+    message: {
+      messageId: message.messageId ?? hexlify(randomBytes(32)),
+      sender: message.sender,
+      data: message.data,
+      sourceChainSelector: source.network.chainSelector,
+      destTokenAmounts,
+    },
+  })
 }

package/src/index.ts

@@ -1,16 +1,35 @@
-export type { APIErrorResponse, CCIPAPIClientContext, LaneLatencyResponse } from './api/index.ts'
+/**
+ * \@chainlink/ccip-sdk - SDK for interacting with Chainlink CCIP (Cross-Chain Interoperability Protocol).
+ *
+ * This package provides tools for sending cross-chain messages, tracking message status,
+ * and executing manual message delivery across supported blockchain networks.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  APICCIPRequestMetadata,
+  APIErrorResponse,
+  CCIPAPIClientContext,
+  LaneLatencyResponse,
+} from './api/index.ts'
 export { CCIPAPIClient, DEFAULT_API_BASE_URL } from './api/index.ts'
 
 export type {
+  ApiRetryConfig,
   Chain,
   ChainContext,
   ChainGetter,
   ChainStatic,
+  GetBalanceOpts,
   LogFilter,
   RateLimiterState,
+  RegistryTokenConfig,
   TokenInfo,
+  TokenPoolConfig,
   TokenPoolRemote,
 } from './chain.ts'
+export { DEFAULT_API_RETRY_CONFIG } from './chain.ts'
 export { calculateManualExecProof, discoverOffRamp } from './execution.ts'
 export {
   type EVMExtraArgsV1,
@@ -21,8 +40,8 @@ export {
   decodeExtraArgs,
   encodeExtraArgs,
 } from './extra-args.ts'
-export { estimateExecGasForRequest } from './gas.ts'
-export { decodeMessage, getMessagesForSender, sourceToDestTokenAmounts } from './requests.ts'
+export { estimateReceiveExecution } from './gas.ts'
+export { decodeMessage, getMessagesForSender, sourceToDestTokenAddresses } from './requests.ts'
 export {
   type CCIPCommit,
   type CCIPExecution,
@@ -34,15 +53,16 @@ export {
   type ExecutionReport,
   type Lane,
   type Logger,
+  type MessageInput,
   type NetworkInfo,
   type OffchainTokenData,
-  type MessageInput,
   type WithLogger,
   CCIPVersion,
   ExecutionState,
   IntentStatus,
   MessageStatus,
 } from './types.ts'
+export type { WithRetryConfig } from './utils.ts'
 export {
   bigIntReplacer,
   bigIntReviver,
@@ -51,6 +71,7 @@ export {
   getDataBytes,
   isSupportedTxHash,
   networkInfo,
+  withRetry,
 } from './utils.ts'
 export {
   type CCIPExplorerLinks,
@@ -73,15 +94,7 @@ export type { UnsignedSolanaTx } from './solana/index.ts'
 import { SuiChain } from './sui/index.ts'
 import { TONChain } from './ton/index.ts'
 export type { UnsignedTONTx } from './ton/index.ts'
-import { ChainFamily } from './types.ts'
-export { AptosChain, ChainFamily, EVMChain, SolanaChain, SuiChain, TONChain }
+import { ChainFamily, NetworkType } from './types.ts'
+export { AptosChain, ChainFamily, EVMChain, NetworkType, SolanaChain, SuiChain, TONChain }
 // use `supportedChains` to override/register derived classes, if needed
 export { supportedChains } from './supported-chains.ts'
-// import `allSupportedChains` to get them all registered, in tree-shaken environments
-export const allSupportedChains = {
-  [ChainFamily.EVM]: EVMChain,
-  [ChainFamily.Solana]: SolanaChain,
-  [ChainFamily.Aptos]: AptosChain,
-  [ChainFamily.Sui]: SuiChain,
-  [ChainFamily.TON]: TONChain,
-}

package/src/offchain.ts

@@ -5,6 +5,7 @@ import {
   CCIPLbtcAttestationNotFoundError,
   CCIPUsdcAttestationError,
 } from './errors/index.ts'
+import { NetworkType } from './types.ts'
 
 const CIRCLE_API_URL = {
   mainnet: 'https://iris-api.circle.com/v1',
@@ -31,13 +32,17 @@ type LombardAttestationsResponse = { attestations: Array<LombardAttestation> }
  * https://developers.circle.com/stablecoins/reference/getattestation
  *
  * @param message - payload of USDC MessageSent(bytes message) event
- * @param isTestnet - true if this was from a testnet
+ * @param networkType - network type (mainnet or testnet)
  * @returns USDC/CCTP attestation bytes
  */
-export async function getUsdcAttestation(message: string, isTestnet: boolean): Promise<string> {
+export async function getUsdcAttestation(
+  message: string,
+  networkType: NetworkType,
+): Promise<string> {
   const msgHash = keccak256(message)
 
-  const circleApiBaseUrl = isTestnet ? CIRCLE_API_URL.testnet : CIRCLE_API_URL.mainnet
+  const circleApiBaseUrl =
+    networkType === NetworkType.Mainnet ? CIRCLE_API_URL.mainnet : CIRCLE_API_URL.testnet
   const res = await fetch(`${circleApiBaseUrl}/attestations/${msgHash}`)
   const json = (await res.json()) as CctpAttestationResponse
   if (!('status' in json) || json.status !== 'complete' || !json.attestation) {
@@ -50,16 +55,17 @@ export async function getUsdcAttestation(message: string, isTestnet: boolean): P
  * Returns the LBTC attestation for a given payload hash
  *
  * @param payloadHash - hash of the payload of the LBTC transfer
- * @param isTestnet - true if this was from a testnet
+ * @param networkType - network type (mainnet or testnet)
  * @returns LBTC attestation bytes
  */
 export async function getLbtcAttestation(
   payloadHash: string,
-  isTestnet: boolean,
+  networkType: NetworkType,
 ): Promise<{
   attestation: string
 }> {
-  const lbtcApiBaseUrl = isTestnet ? LOMBARD_API_URL.testnet : LOMBARD_API_URL.mainnet
+  const lbtcApiBaseUrl =
+    networkType === NetworkType.Mainnet ? LOMBARD_API_URL.mainnet : LOMBARD_API_URL.testnet
   const res = await fetch(`${lbtcApiBaseUrl}/api/bridge/v1/deposits/getByHash`, {
     method: 'POST',
     body: JSON.stringify({ messageHash: [payloadHash] }),