@chainlink/ccip-sdk 0.95.0 → 0.96.0

package/src/evm/index.ts

@@ -13,9 +13,6 @@ import {
   Result,
   WebSocketProvider,
   ZeroAddress,
-  concat,
-  dataSlice,
-  encodeBase58,
   getAddress,
   hexlify,
   isBytesLike,
@@ -49,23 +46,14 @@ import {
   CCIPMessageDecodeError,
   CCIPSourceChainUnsupportedError,
   CCIPTokenNotConfiguredError,
+  CCIPTokenPoolChainConfigNotFoundError,
   CCIPTransactionNotFoundError,
   CCIPVersionFeatureUnavailableError,
   CCIPVersionRequiresLaneError,
   CCIPVersionUnsupportedError,
   CCIPWalletInvalidError,
 } from '../errors/index.ts'
-import {
-  type EVMExtraArgsV1,
-  type EVMExtraArgsV2,
-  type ExtraArgs,
-  type SVMExtraArgsV1,
-  type SuiExtraArgsV1,
-  EVMExtraArgsV1Tag,
-  EVMExtraArgsV2Tag,
-  SVMExtraArgsV1Tag,
-  SuiExtraArgsV1Tag,
-} from '../extra-args.ts'
+import type { ExtraArgs } from '../extra-args.ts'
 import type { LeafHasher } from '../hasher/common.ts'
 import { supportedChains } from '../supported-chains.ts'
 import {
@@ -105,15 +93,12 @@ import EVM2EVMOnRamp_1_5_ABI from './abi/OnRamp_1_5.ts'
 import OnRamp_1_6_ABI from './abi/OnRamp_1_6.ts'
 import type Router_ABI from './abi/Router.ts'
 import type TokenAdminRegistry_1_5_ABI from './abi/TokenAdminRegistry_1_5.ts'
-import {
-  DEFAULT_GAS_LIMIT,
-  commitsFragments,
-  defaultAbiCoder,
-  interfaces,
-  receiptsFragments,
-  requestsFragments,
-} from './const.ts'
+import { commitsFragments, interfaces, receiptsFragments, requestsFragments } from './const.ts'
 import { parseData } from './errors.ts'
+import {
+  decodeExtraArgs as decodeExtraArgs_,
+  encodeExtraArgs as encodeExtraArgs_,
+} from './extra-args.ts'
 import { estimateExecGas } from './gas.ts'
 import { getV12LeafHasher, getV16LeafHasher } from './hasher.ts'
 import { getEvmLogs } from './logs.ts'
@@ -129,13 +114,6 @@ export type { UnsignedEVMTx }
 
 const VersionedContractABI = parseAbi(['function typeAndVersion() view returns (string)'])
 
-const EVMExtraArgsV1 = 'tuple(uint256 gasLimit)'
-const EVMExtraArgsV2 = 'tuple(uint256 gasLimit, bool allowOutOfOrderExecution)'
-const SVMExtraArgsV1 =
-  'tuple(uint32 computeUnits, uint64 accountIsWritableBitmap, bool allowOutOfOrderExecution, bytes32 tokenReceiver, bytes32[] accounts)'
-const SuiExtraArgsV1 =
-  'tuple(uint256 gasLimit, bool allowOutOfOrderExecution, bytes32 tokenReceiver, bytes32[] receiverObjectIds)'
-
 function resultToObject<T>(o: T): T {
   if (o instanceof Promise) return o.then(resultToObject) as T
   if (!(o instanceof Result)) return o
@@ -355,6 +333,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * Decodes a CCIP message from a log event.
    * @param log - Log event with topics and data.
    * @returns Decoded CCIPMessage or undefined if not a valid CCIP message.
+   * @throws {@link CCIPLogDataInvalidError} if log data is not valid bytes
+   * @throws {@link CCIPMessageDecodeError} if message cannot be decoded
    */
   static decodeMessage(log: {
     topics?: readonly string[]
@@ -456,6 +436,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * @param log - Log event with topics and data.
    * @param lane - Lane info (required for CCIP v1.5 and earlier).
    * @returns Array of CommitReport or undefined if not a valid commit event.
+   * @throws {@link CCIPLogDataInvalidError} if log data is not valid bytes
+   * @throws {@link CCIPVersionRequiresLaneError} if CCIP v1.5 event but no lane provided
    */
   static decodeCommits(
     log: { topics?: readonly string[]; data: unknown },
@@ -511,6 +493,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * Decodes an execution receipt from a log event.
    * @param log - Log event with topics and data.
    * @returns ExecutionReceipt or undefined if not a valid execution event.
+   * @throws {@link CCIPLogDataInvalidError} if log data is not valid bytes
    */
   static decodeReceipt(log: {
     topics?: readonly string[]
@@ -542,43 +525,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * @param extraArgs - Encoded extra arguments bytes.
    * @returns Decoded extra arguments with tag, or undefined if unknown format.
    */
-  static decodeExtraArgs(
-    extraArgs: BytesLike,
-  ):
-    | (EVMExtraArgsV1 & { _tag: 'EVMExtraArgsV1' })
-    | (EVMExtraArgsV2 & { _tag: 'EVMExtraArgsV2' })
-    | (SVMExtraArgsV1 & { _tag: 'SVMExtraArgsV1' })
-    | (SuiExtraArgsV1 & { _tag: 'SuiExtraArgsV1' })
-    | undefined {
-    const data = getDataBytes(extraArgs),
-      tag = dataSlice(data, 0, 4)
-    switch (tag) {
-      case EVMExtraArgsV1Tag: {
-        const args = defaultAbiCoder.decode([EVMExtraArgsV1], dataSlice(data, 4))
-        return { ...(resultToObject(args[0]) as EVMExtraArgsV1), _tag: 'EVMExtraArgsV1' }
-      }
-      case EVMExtraArgsV2Tag: {
-        const args = defaultAbiCoder.decode([EVMExtraArgsV2], dataSlice(data, 4))
-        return { ...(resultToObject(args[0]) as EVMExtraArgsV2), _tag: 'EVMExtraArgsV2' }
-      }
-      case SVMExtraArgsV1Tag: {
-        const args = defaultAbiCoder.decode([SVMExtraArgsV1], dataSlice(data, 4))
-        const parsed = resultToObject(args[0]) as SVMExtraArgsV1
-        parsed.tokenReceiver = encodeBase58(parsed.tokenReceiver)
-        parsed.accounts = parsed.accounts.map((a: string) => encodeBase58(a))
-        return { ...parsed, _tag: 'SVMExtraArgsV1' }
-      }
-      case SuiExtraArgsV1Tag: {
-        const args = defaultAbiCoder.decode([SuiExtraArgsV1], dataSlice(data, 4))
-        const parsed = resultToObject(args[0]) as SuiExtraArgsV1
-        return {
-          ...parsed,
-          _tag: 'SuiExtraArgsV1',
-        }
-      }
-      default:
-        return undefined
-    }
+  static decodeExtraArgs(extraArgs: BytesLike) {
+    return decodeExtraArgs_(extraArgs)
   }
 
   /**
@@ -587,48 +535,14 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * @returns Encoded extra arguments as hex string.
    */
   static encodeExtraArgs(args: ExtraArgs | undefined): string {
-    if (!args) return '0x'
-    if ('computeUnits' in args) {
-      return concat([
-        SVMExtraArgsV1Tag,
-        defaultAbiCoder.encode(
-          [SVMExtraArgsV1],
-          [
-            {
-              ...args,
-              tokenReceiver: getAddressBytes(args.tokenReceiver),
-              accounts: args.accounts.map((a) => getAddressBytes(a)),
-            },
-          ],
-        ),
-      ])
-    } else if ('receiverObjectIds' in args) {
-      return concat([
-        SuiExtraArgsV1Tag,
-        defaultAbiCoder.encode(
-          [SuiExtraArgsV1],
-          [
-            {
-              ...args,
-              tokenReceiver: zeroPadValue(getAddressBytes(args.tokenReceiver), 32),
-              receiverObjectIds: args.receiverObjectIds.map((a) => getDataBytes(a)),
-            },
-          ],
-        ),
-      ])
-    } else if ('allowOutOfOrderExecution' in args) {
-      if ((args as Partial<typeof args>).gasLimit == null) args.gasLimit = DEFAULT_GAS_LIMIT
-      return concat([EVMExtraArgsV2Tag, defaultAbiCoder.encode([EVMExtraArgsV2], [args])])
-    } else if ((args as Partial<typeof args>).gasLimit != null) {
-      return concat([EVMExtraArgsV1Tag, defaultAbiCoder.encode([EVMExtraArgsV1], [args])])
-    }
-    return '0x'
+    return encodeExtraArgs_(args)
   }
 
   /**
    * Converts bytes to a checksummed EVM address.
    * @param bytes - Bytes to convert (must be 20 bytes or 32 bytes with leading zeros).
    * @returns Checksummed EVM address.
+   * @throws {@link CCIPAddressInvalidEvmError} if bytes cannot be converted to a valid EVM address
    */
   static getAddress(bytes: BytesLike): string {
     if (isHexString(bytes, 20)) return getAddress(bytes)
@@ -655,6 +569,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * Gets lane configuration from an OnRamp contract.
    * @param onRamp - OnRamp contract address.
    * @returns Lane configuration.
+   * @throws {@link CCIPContractTypeInvalidError} if contract doesn't have destChainSelector
    */
   async getLaneForOnRamp(onRamp: string): Promise<Lane> {
     const [, version] = await this.typeAndVersion(onRamp)
@@ -674,7 +589,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
-  /** {@inheritDoc Chain.getRouterForOnRamp} */
+  /**
+   * {@inheritDoc Chain.getRouterForOnRamp}
+   * @throws {@link CCIPVersionUnsupportedError} if OnRamp version is not supported
+   */
   async getRouterForOnRamp(onRamp: string, destChainSelector: bigint): Promise<string> {
     const [, version] = await this.typeAndVersion(onRamp)
     let onRampABI
@@ -703,7 +621,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
-  /** {@inheritDoc Chain.getRouterForOffRamp} */
+  /**
+   * {@inheritDoc Chain.getRouterForOffRamp}
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
+   */
   async getRouterForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI, router
@@ -770,7 +691,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return contract.getOnRamp(destChainSelector) as Promise<string>
   }
 
-  /** {@inheritDoc Chain.getOnRampForOffRamp} */
+  /**
+   * {@inheritDoc Chain.getOnRampForOffRamp}
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
+   */
   async getOnRampForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI
@@ -803,7 +727,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
-  /** {@inheritDoc Chain.getCommitStoreForOffRamp} */
+  /**
+   * {@inheritDoc Chain.getCommitStoreForOffRamp}
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
+   */
   async getCommitStoreForOffRamp(offRamp: string): Promise<string> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI
@@ -875,6 +802,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * @param lane - Lane configuration.
    * @param ctx - Context object containing logger.
    * @returns Leaf hasher function.
+   * @throws {@link CCIPSourceChainUnsupportedError} if source chain is not EVM for v1.2/v1.5
+   * @throws {@link CCIPHasherVersionUnsupportedError} if lane version is not supported
    */
   static getDestLeafHasher(
     { sourceChainSelector, destChainSelector, onRamp, version }: Lane,
@@ -911,7 +840,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return this.getOnRampForRouter(router, networkInfo(someOtherNetwork).chainSelector)
   }
 
-  /** {@inheritDoc Chain.getTokenAdminRegistryFor} */
+  /**
+   * {@inheritDoc Chain.getTokenAdminRegistryFor}
+   * @throws {@link CCIPContractNotRouterError} if address is not a Router, OnRamp, or OffRamp
+   */
   async getTokenAdminRegistryFor(address: string): Promise<string> {
     let [type, version, typeAndVersion] = await this.typeAndVersion(address)
     if (type === 'TokenAdminRegistry') {
@@ -942,6 +874,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
    * @internal
    * @param address - Router or Ramp contract address.
    * @returns FeeQuoter contract address.
+   * @throws {@link CCIPContractNotRouterError} if address is not a Router, OnRamp, or OffRamp
+   * @throws {@link CCIPVersionFeatureUnavailableError} if contract version is below v1.6
    */
   async getFeeQuoterFor(address: string): Promise<string> {
     let [type, version, typeAndVersion] = await this.typeAndVersion(address)
@@ -1064,7 +998,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
-  /** {@inheritDoc Chain.sendMessage} */
+  /**
+   * {@inheritDoc Chain.sendMessage}
+   * @throws {@link CCIPWalletInvalidError} if wallet is not a valid Signer
+   */
   async sendMessage(opts: Parameters<Chain['sendMessage']>[0]): Promise<CCIPRequest> {
     const wallet = opts.wallet
     if (!isSigner(wallet)) throw new CCIPWalletInvalidError(wallet)
@@ -1106,6 +1043,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
   /**
    * {@inheritDoc Chain.generateUnsignedExecuteReport}
    * @returns array containing one unsigned `manuallyExecute` TransactionRequest object
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
    */
   async generateUnsignedExecuteReport({
     offRamp,
@@ -1220,7 +1158,12 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return { family: ChainFamily.EVM, transactions: [manualExecTx] }
   }
 
-  /** {@inheritDoc Chain.executeReport} */
+  /**
+   * {@inheritDoc Chain.executeReport}
+   * @throws {@link CCIPWalletInvalidError} if wallet is not a valid Signer
+   * @throws {@link CCIPExecTxNotConfirmedError} if execution transaction fails to confirm
+   * @throws {@link CCIPExecTxRevertedError} if execution transaction reverts
+   */
   async executeReport(opts: Parameters<Chain['executeReport']>[0]) {
     const wallet = opts.wallet
     if (!isSigner(wallet)) throw new CCIPWalletInvalidError(wallet)
@@ -1272,7 +1215,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return res as string[]
   }
 
-  /** {@inheritDoc Chain.getRegistryTokenConfig} */
+  /**
+   * {@inheritDoc Chain.getRegistryTokenConfig}
+   * @throws {@link CCIPTokenNotConfiguredError} if token is not configured in registry
+   */
   async getRegistryTokenConfig(
     registry: string,
     token: string,
@@ -1301,8 +1247,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
-  /** {@inheritDoc Chain.getTokenPoolConfigs} */
-  async getTokenPoolConfigs(tokenPool: string): Promise<{
+  /** {@inheritDoc Chain.getTokenPoolConfig} */
+  async getTokenPoolConfig(tokenPool: string): Promise<{
     token: string
     router: string
     typeAndVersion: string
@@ -1387,23 +1333,28 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return Promise.all([supportedChains, remotePools, remoteInfo]).then(
       ([supportedChains, remotePools, remoteInfo]) =>
         Object.fromEntries(
-          supportedChains.map(
-            (chain, i) =>
-              [
-                chain.name,
-                {
-                  remoteToken: decodeAddress(remoteInfo[i]![0], chain.family),
-                  remotePools: remotePools[i]!.map((pool) => decodeAddress(pool, chain.family)),
-                  inboundRateLimiterState: remoteInfo[i]![1].isEnabled ? remoteInfo[i]![1] : null,
-                  outboundRateLimiterState: remoteInfo[i]![2].isEnabled ? remoteInfo[i]![2] : null,
-                },
-              ] as const,
-          ),
+          supportedChains.map((chain, i) => {
+            const remoteTokenRaw = remoteInfo[i]![0]
+            if (!remoteTokenRaw || remoteTokenRaw.match(/^(0x)?0*$/))
+              throw new CCIPTokenPoolChainConfigNotFoundError(tokenPool, tokenPool, chain.name)
+            return [
+              chain.name,
+              {
+                remoteToken: decodeAddress(remoteTokenRaw, chain.family),
+                remotePools: remotePools[i]!.map((pool) => decodeAddress(pool, chain.family)),
+                inboundRateLimiterState: remoteInfo[i]![1].isEnabled ? remoteInfo[i]![1] : null,
+                outboundRateLimiterState: remoteInfo[i]![2].isEnabled ? remoteInfo[i]![2] : null,
+              },
+            ] as const
+          }),
         ),
     )
   }
 
-  /** {@inheritDoc Chain.getFeeTokens} */
+  /**
+   * {@inheritDoc Chain.getFeeTokens}
+   * @throws {@link CCIPVersionUnsupportedError} if OnRamp version is not supported
+   */
   async getFeeTokens(router: string) {
     const onRamp = await this._getSomeOnRampFor(router)
     const [_, version] = await this.typeAndVersion(onRamp)

package/src/execution.ts

@@ -77,11 +77,27 @@ export const discoverOffRamp = memoize(
       dest.network.chainSelector,
     )
     for (const offRamp of sourceOffRamps) {
-      const destOnRamp = await source.getOnRampForOffRamp(offRamp, dest.network.chainSelector)
+      let destOnRamp: string
+      try {
+        destOnRamp = await source.getOnRampForOffRamp(offRamp, dest.network.chainSelector)
+      } catch {
+        logger.debug('discoverOffRamp: skipping offRamp', offRamp, '(no valid source chain config)')
+        continue
+      }
       const destRouter = await dest.getRouterForOnRamp(destOnRamp, source.network.chainSelector)
       const destOffRamps = await dest.getOffRampsForRouter(destRouter, source.network.chainSelector)
       for (const offRamp of destOffRamps) {
-        const offRampsOnRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector)
+        let offRampsOnRamp: string
+        try {
+          offRampsOnRamp = await dest.getOnRampForOffRamp(offRamp, source.network.chainSelector)
+        } catch {
+          logger.debug(
+            'discoverOffRamp: skipping dest offRamp',
+            offRamp,
+            '(no valid source chain config)',
+          )
+          continue
+        }
         logger.debug(
           'discoverOffRamp: found, from',
           {

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

@@ -10,7 +10,7 @@ import { discoverOffRamp } from './execution.ts'
 import { sourceToDestTokenAddresses } from './requests.ts'
 
 /**
- * A subset of [[MessageInput]] for estimating receive execution gas.
+ * A subset of {@link MessageInput} for estimating receive execution gas.
  */
 export type EstimateMessageInput = {
   /** receiver contract address */
@@ -19,7 +19,7 @@ export type EstimateMessageInput = {
   messageId?: string
   /** optional sender: zero address will be used if omitted */
   sender?: string
-  /** optional data: zero bytes will be used if ommitted */
+  /** optional data: zero bytes will be used if omitted */
   data?: BytesLike
   /**
    * optional tokenAmounts; `amount` with either source `token` (as in MessageInput) or
@@ -35,7 +35,7 @@ export type EstimateMessageInput = {
 }
 
 /**
- * Options for [[estimateReceiveExecution]] function.
+ * Options for {@link estimateReceiveExecution} function.
  */
 export type EstimateReceiveExecutionOpts = {
   /** Source chain instance (for token data retrieval) */
@@ -52,6 +52,9 @@ export type EstimateReceiveExecutionOpts = {
  * Estimate CCIP gasLimit needed to execute a request on a contract receiver.
  * @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 estimateReceiveExecution({
   source,
@@ -69,12 +72,16 @@ export async function estimateReceiveExecution({
       onRamp = await source.getOnRampForRouter(routerOrRamp, dest.network.chainSelector)
     else onRamp = routerOrRamp
     offRamp = await discoverOffRamp(source, dest, onRamp, source)
-  } catch {
-    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 (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 destTokenAmounts = await Promise.all(

package/src/index.ts

@@ -1,5 +1,14 @@
+/**
+ * \@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 {
-  APICCIPRequest,
+  APICCIPRequestMetadata,
   APIErrorResponse,
   CCIPAPIClientContext,
   LaneLatencyResponse,
@@ -15,7 +24,9 @@ export type {
   GetBalanceOpts,
   LogFilter,
   RateLimiterState,
+  RegistryTokenConfig,
   TokenInfo,
+  TokenPoolConfig,
   TokenPoolRemote,
 } from './chain.ts'
 export { DEFAULT_API_RETRY_CONFIG } from './chain.ts'
@@ -87,11 +98,3 @@ 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,
-}