@chainlink/ccip-sdk 0.95.0 → 0.97.0

package/src/evm/index.ts

@@ -1,27 +1,23 @@
-import { parseAbi } from 'abitype'
 import {
   type BytesLike,
   type Interface,
   type JsonRpcApiProvider,
   type Log,
+  type Result,
   type Signer,
   type TransactionReceipt,
   type TransactionRequest,
   type TransactionResponse,
   Contract,
   JsonRpcProvider,
-  Result,
   WebSocketProvider,
   ZeroAddress,
-  concat,
-  dataSlice,
-  encodeBase58,
   getAddress,
   hexlify,
   isBytesLike,
   isHexString,
+  keccak256,
   toBeHex,
-  toBigInt,
   zeroPadValue,
 } from 'ethers'
 import type { TypedContract } from 'ethers-abitype'
@@ -37,43 +33,36 @@ import {
 } from '../chain.ts'
 import {
   CCIPAddressInvalidEvmError,
+  CCIPApiClientNotAvailableError,
   CCIPBlockNotFoundError,
   CCIPContractNotRouterError,
   CCIPContractTypeInvalidError,
   CCIPDataFormatUnsupportedError,
   CCIPExecTxNotConfirmedError,
   CCIPExecTxRevertedError,
-  CCIPExtraArgsParseError,
   CCIPHasherVersionUnsupportedError,
   CCIPLogDataInvalidError,
-  CCIPMessageDecodeError,
+  CCIPNotImplementedError,
   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 {
   type CCIPExecution,
   type CCIPMessage,
   type CCIPRequest,
+  type CCIPVerifications,
   type ChainTransaction,
   type CommitReport,
+  type ExecutionInput,
   type ExecutionReceipt,
   type ExecutionState,
   type Lane,
@@ -100,56 +89,44 @@ import type TokenPool_ABI from './abi/LockReleaseTokenPool_1_6_1.ts'
 import EVM2EVMOffRamp_1_2_ABI from './abi/OffRamp_1_2.ts'
 import EVM2EVMOffRamp_1_5_ABI from './abi/OffRamp_1_5.ts'
 import OffRamp_1_6_ABI from './abi/OffRamp_1_6.ts'
+import OffRamp_2_0_ABI from './abi/OffRamp_2_0.ts'
 import EVM2EVMOnRamp_1_2_ABI from './abi/OnRamp_1_2.ts'
 import EVM2EVMOnRamp_1_5_ABI from './abi/OnRamp_1_5.ts'
-import OnRamp_1_6_ABI from './abi/OnRamp_1_6.ts'
+import type OnRamp_1_6_ABI from './abi/OnRamp_1_6.ts'
+import type OnRamp_2_0_ABI from './abi/OnRamp_2_0.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,
+  CCV_INDEXER_URL,
+  VersionedContractABI,
   commitsFragments,
-  defaultAbiCoder,
   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'
 import {
   type CCIPMessage_V1_6_EVM,
+  type CCIPMessage_V2_0,
   type CleanAddressable,
-  parseSourceTokenData,
+  type MessageV1,
+  type TokenTransferV1,
+  decodeMessageV1,
 } from './messages.ts'
+export { decodeMessageV1 }
+export type { MessageV1, TokenTransferV1 }
 import { encodeEVMOffchainTokenData, fetchEVMOffchainTokenData } from './offchain.ts'
-import { buildMessageForDest, getMessagesInBatch } from '../requests.ts'
-import type { UnsignedEVMTx } from './types.ts'
+import { buildMessageForDest, decodeMessage, getMessagesInBatch } from '../requests.ts'
+import { type UnsignedEVMTx, resultToObject } from './types.ts'
 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
-  if (o.length === 0) return o.toArray() as T
-  try {
-    const obj = o.toObject()
-    if (!Object.keys(obj).every((k) => /^_+\d*$/.test(k)))
-      return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, resultToObject(v)])) as T
-  } catch (_) {
-    // fallthrough
-  }
-  return o.toArray().map(resultToObject) as T
-}
-
 /** typeguard for ethers Signer interface (used for `wallet`s)  */
 function isSigner(wallet: unknown): wallet is Signer {
   return (
@@ -180,6 +157,26 @@ async function submitTransaction(
 
 /**
  * EVM chain implementation supporting Ethereum-compatible networks.
+ *
+ * Provides methods for sending CCIP cross-chain messages, querying message
+ * status, fetching fee quotes, and manually executing pending messages on
+ * Ethereum Virtual Machine compatible chains.
+ *
+ * @example Create from RPC URL
+ * ```typescript
+ * import { EVMChain } from '@chainlink/ccip-sdk'
+ *
+ * const chain = await EVMChain.fromUrl('https://rpc.sepolia.org')
+ * console.log(`Connected to: ${chain.network.name}`)
+ * ```
+ *
+ * @example Query messages in a transaction
+ * ```typescript
+ * const requests = await chain.getMessagesInTx('0xabc123...')
+ * for (const req of requests) {
+ *   console.log(`Message ID: ${req.message.messageId}`)
+ * }
+ * ```
  */
 export class EVMChain extends Chain<typeof ChainFamily.EVM> {
   static {
@@ -190,6 +187,13 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
 
   provider: JsonRpcApiProvider
   readonly destroy$: Promise<void>
+  private noncesPromises: Record<string, Promise<unknown>>
+  /**
+   * Cache of current nonces per wallet address.
+   * Used internally by {@link sendMessage} and {@link execute} to manage transaction ordering.
+   * Can be inspected for debugging or manually adjusted if needed.
+   */
+  nonces: Record<string, number>
 
   /**
    * Creates a new EVMChain instance.
@@ -199,6 +203,9 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
   constructor(provider: JsonRpcApiProvider, network: NetworkInfo, ctx?: ChainContext) {
     super(network, ctx)
 
+    this.noncesPromises = {}
+    this.nonces = {}
+
     this.provider = provider
     this.destroy$ = new Promise<void>((resolve) => (this.destroy = resolve))
     void this.destroy$.finally(() => provider.destroy())
@@ -238,6 +245,22 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return (await this.provider.listAccounts()).map(({ address }) => address)
   }
 
+  /**
+   * Get the next nonce for a wallet address and increment the internal counter.
+   * Fetches from the network on first call, then uses cached value.
+   * @param address - Wallet address to get nonce for
+   * @returns The next available nonce
+   */
+  async nextNonce(address: string): Promise<number> {
+    await (this.noncesPromises[address] ??= this.provider
+      .getTransactionCount(address)
+      .then((nonce) => {
+        this.nonces[address] = nonce
+        return nonce
+      }))
+    return this.nonces[address]!++
+  }
+
   /**
    * Creates a JSON-RPC provider from a URL.
    * @param url - WebSocket (wss://) or HTTP (https://) endpoint URL.
@@ -282,9 +305,20 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
 
   /**
    * Creates an EVMChain instance from an RPC URL.
+   *
    * @param url - WebSocket (wss://) or HTTP (https://) endpoint URL.
-   * @param ctx - context containing logger.
-   * @returns A new EVMChain instance.
+   * @param ctx - Optional context containing logger and API client configuration.
+   * @returns A new EVMChain instance connected to the specified network.
+   * @throws {@link CCIPChainNotFoundError} if chain cannot be identified from chainId
+   *
+   * @example
+   * ```typescript
+   * // HTTP connection
+   * const chain = await EVMChain.fromUrl('https://rpc.sepolia.org')
+   *
+   * // With custom logger
+   * const chain = await EVMChain.fromUrl(url, { logger: customLogger })
+   * ```
    */
   static async fromUrl(url: string, ctx?: ChainContext): Promise<EVMChain> {
     return this.fromProvider(await this._getProvider(url), ctx)
@@ -320,15 +354,15 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
   }
 
   /** {@inheritDoc Chain.getMessagesInBatch} */
-  getMessagesInBatch<
+  override getMessagesInBatch<
     R extends PickDeep<
       CCIPRequest,
       'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.sequenceNumber'
     >,
   >(
     request: R,
-    commit: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>,
-    opts?: { page?: number },
+    range: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>,
+    opts?: Pick<LogFilter, 'page'>,
   ): Promise<R['message'][]> {
     let opts_: Parameters<EVMChain['getLogs']>[0] | undefined
     if (request.lane.version >= CCIPVersion.V1_6) {
@@ -338,7 +372,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         topics: [[request.log.topics[0]!], [toBeHex(request.lane.destChainSelector, 32)]],
       }
     }
-    return getMessagesInBatch(this, request, commit, opts_)
+    return getMessagesInBatch(this, request, range, opts_)
   }
 
   /** {@inheritDoc Chain.typeAndVersion} */
@@ -348,13 +382,17 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
       VersionedContractABI,
       this.provider,
     ) as unknown as TypedContract<typeof VersionedContractABI>
-    return parseTypeAndVersion(await contract.typeAndVersion())
+    const res = parseTypeAndVersion(await contract.typeAndVersion())
+    if (res[1].startsWith('1.7.')) res[1] = CCIPVersion.V2_0
+    return res
   }
 
   /**
    * 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[]
@@ -376,79 +414,16 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         const result = interfaces.OnRamp_v1_6.decodeEventLog(fragment, log.data, log.topics)
         message = resultToObject(result) as Record<string, unknown>
         if (message.message) message = message.message as Record<string, unknown> | undefined
+        else if (message.encodedMessage) {
+          Object.assign(message, decodeMessageV1(message.encodedMessage as BytesLike))
+        }
         if (message) break
       } catch (_) {
         // try next fragment
       }
     }
     if (!message) return
-    if (!isHexString(message.sender, 20)) throw new CCIPMessageDecodeError('invalid sender')
-
-    if (message.header) {
-      // CCIPMessage_V1_6
-      Object.assign(message, message.header)
-      delete message.header
-    }
-
-    const sourceFamily = networkInfo(
-      (message as { sourceChainSelector: bigint }).sourceChainSelector,
-    ).family
-    let destFamily: ChainFamily = ChainFamily.EVM
-    if ((message as { destChainSelector?: bigint }).destChainSelector) {
-      destFamily = networkInfo((message as { destChainSelector: bigint }).destChainSelector).family
-    }
-    // conversions to make any message version be compatible with latest v1.6
-    message.tokenAmounts = (message.tokenAmounts as Record<string, string | bigint | number>[]).map(
-      (tokenAmount, i) => {
-        if ('sourceTokenData' in message) {
-          // CCIPMessage_V1_2_EVM
-          try {
-            tokenAmount = {
-              ...parseSourceTokenData(
-                (message as { sourceTokenData: string[] }).sourceTokenData[i]!,
-              ),
-              ...tokenAmount,
-            }
-          } catch (_) {
-            // legacy sourceTokenData
-          }
-        }
-        if (typeof tokenAmount.destExecData === 'string' && tokenAmount.destGasAmount == null) {
-          // CCIPMessage_V1_6_EVM
-          tokenAmount.destGasAmount = toBigInt(getDataBytes(tokenAmount.destExecData))
-        }
-        // Can be undefined if the message is from before v1.5 and failed to parse sourceTokenData
-        if (tokenAmount.sourcePoolAddress) {
-          tokenAmount.sourcePoolAddress = decodeAddress(
-            tokenAmount.sourcePoolAddress as string,
-            sourceFamily,
-          )
-        }
-        if (tokenAmount.destTokenAddress) {
-          tokenAmount.destTokenAddress = decodeAddress(
-            tokenAmount.destTokenAddress as string,
-            destFamily,
-          )
-        }
-        return tokenAmount
-      },
-    )
-    message.sender = decodeAddress(message.sender, sourceFamily)
-    message.feeToken = decodeAddress(message.feeToken as string, sourceFamily)
-    message.receiver = decodeAddress(message.receiver as string, destFamily)
-    if (message.extraArgs) {
-      // v1.6+
-      const parsed = this.decodeExtraArgs(message.extraArgs as string)
-      if (!parsed) throw new CCIPExtraArgsParseError(message.extraArgs as string)
-      const { _tag, ...rest } = parsed
-      // merge parsed extraArgs to any family in message root object
-      Object.assign(message, rest)
-    } else if (message.nonce === 0n) {
-      // v1.2..v1.5 targets EVM only; extraArgs is not explicit, gasLimit is already in
-      // message body, allowOutOfOrderExecution (in v1.5) was present only as nonce=0
-      message.allowOutOfOrderExecution = true
-    }
-    return message as CCIPMessage
+    return decodeMessage(message)
   }
 
   /**
@@ -456,6 +431,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 +488,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 +520,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 +530,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 +564,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 +584,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
@@ -691,19 +604,32 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         return router as string
       }
       case CCIPVersion.V1_6: {
-        onRampABI = OnRamp_1_6_ABI
-        const contract = new Contract(onRamp, onRampABI, this.provider) as unknown as TypedContract<
-          typeof onRampABI
-        >
+        const contract = new Contract(
+          onRamp,
+          interfaces.OnRamp_v1_6,
+          this.provider,
+        ) as unknown as TypedContract<typeof OnRamp_1_6_ABI>
         const [, , router] = await contract.getDestChainConfig(destChainSelector)
         return router as string
       }
+      case CCIPVersion.V2_0: {
+        const contract = new Contract(
+          onRamp,
+          interfaces.OnRamp_v2_0,
+          this.provider,
+        ) as unknown as TypedContract<typeof OnRamp_2_0_ABI>
+        const { router } = await contract.getDestChainConfig(destChainSelector)
+        return router as string
+      }
       default:
         throw new CCIPVersionUnsupportedError(version)
     }
   }
 
-  /** {@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
@@ -721,8 +647,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         ;({ router } = await contract.getDynamicConfig())
         break
       }
-      case CCIPVersion.V1_6: {
+      case CCIPVersion.V1_6:
         offRampABI = OffRamp_1_6_ABI
+      // falls through
+      case CCIPVersion.V2_0: {
+        offRampABI = OffRamp_2_0_ABI
         const contract = new Contract(
           offRamp,
           offRampABI,
@@ -770,8 +699,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return contract.getOnRamp(destChainSelector) as Promise<string>
   }
 
-  /** {@inheritDoc Chain.getOnRampForOffRamp} */
-  async getOnRampForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
+  /**
+   * {@inheritDoc Chain.getOnRampsForOffRamp}
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
+   */
+  async getOnRampsForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string[]> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI
     switch (version) {
@@ -786,7 +718,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
           this.provider,
         ) as unknown as TypedContract<typeof offRampABI>
         const { onRamp } = await contract.getStaticConfig()
-        return onRamp as string
+        return [onRamp as string]
       }
       case CCIPVersion.V1_6: {
         offRampABI = OffRamp_1_6_ABI
@@ -796,14 +728,40 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
           this.provider,
         ) as unknown as TypedContract<typeof offRampABI>
         const { onRamp } = await contract.getSourceChainConfig(sourceChainSelector)
-        return decodeOnRampAddress(onRamp, networkInfo(sourceChainSelector).family)
+        if (!onRamp || onRamp.match(/^(0x)?0*$/i)) return []
+        return [decodeOnRampAddress(onRamp, networkInfo(sourceChainSelector).family)]
+      }
+      case CCIPVersion.V2_0: {
+        offRampABI = OffRamp_2_0_ABI
+        const contract = new Contract(
+          offRamp,
+          offRampABI,
+          this.provider,
+        ) as unknown as TypedContract<typeof offRampABI>
+        const { onRamps } = await contract.getSourceChainConfig(sourceChainSelector)
+        const sourceFamily = networkInfo(sourceChainSelector).family
+        return onRamps.map((onRamp) => decodeOnRampAddress(onRamp, sourceFamily))
       }
       default:
         throw new CCIPVersionUnsupportedError(version)
     }
   }
 
-  /** {@inheritDoc Chain.getCommitStoreForOffRamp} */
+  /**
+   * Fetch the CommitStore set in OffRamp config (CCIP v1.5 and earlier).
+   * For CCIP v1.6 and later, it should return the offRamp address.
+   *
+   * @param offRamp - OffRamp contract address
+   * @returns Promise resolving to CommitStore address
+   *
+   * @example Get commit store
+   * ```typescript
+   * const commitStore = await dest.getCommitStoreForOffRamp(offRampAddress)
+   * // For v1.6+, commitStore === offRampAddress
+   * ```
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
+   * @internal
+   */
   async getCommitStoreForOffRamp(offRamp: string): Promise<string> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI
@@ -821,11 +779,8 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         const { commitStore } = await contract.getStaticConfig()
         return commitStore as string
       }
-      case CCIPVersion.V1_6: {
-        return offRamp
-      }
       default:
-        throw new CCIPVersionUnsupportedError(version)
+        return offRamp
     }
   }
 
@@ -875,6 +830,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 +868,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 +902,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 +1026,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)
@@ -1075,27 +1040,37 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     let sendTx: TransactionRequest = txs.transactions[txs.transactions.length - 1]!
 
     // approve all tokens (including feeToken, if needed) in parallel
-    let nonce = await this.provider.getTransactionCount(sender)
     const responses = await Promise.all(
       approveTxs.map(async (tx: TransactionRequest) => {
-        tx.nonce = nonce++
-        tx = await wallet.populateTransaction(tx)
-        tx.from = undefined
-        const response = await submitTransaction(wallet, tx, this.provider)
-        this.logger.debug('approve =>', response.hash)
-        return response
+        tx.nonce = await this.nextNonce(sender)
+        try {
+          tx = await wallet.populateTransaction(tx)
+          tx.from = undefined
+          const response = await submitTransaction(wallet, tx, this.provider)
+          this.logger.debug('approve =>', response.hash)
+          return response
+        } catch (err) {
+          this.nonces[sender]!--
+          throw err
+        }
       }),
     )
     if (responses.length) await responses[responses.length - 1]!.wait(1, 60_000) // wait last tx nonce to be mined
 
-    sendTx.nonce = nonce++
-    // sendTx.gasLimit = await this.provider.estimateGas(sendTx)
-    sendTx = await wallet.populateTransaction(sendTx)
-    sendTx.from = undefined // some signers don't like receiving pre-populated `from`
-    const response = await submitTransaction(wallet, sendTx, this.provider)
+    sendTx.nonce = await this.nextNonce(sender)
+    let response
+    try {
+      // sendTx.gasLimit = await this.provider.estimateGas(sendTx)
+      sendTx = await wallet.populateTransaction(sendTx)
+      sendTx.from = undefined // some signers don't like receiving pre-populated `from`
+      response = await submitTransaction(wallet, sendTx, this.provider)
+    } catch (err) {
+      this.nonces[sender]!--
+      throw err
+    }
     this.logger.debug('ccipSend =>', response.hash)
-    await response.wait(1, 60_000)
-    return (await this.getMessagesInTx(await this.getTransaction(response.hash)))[0]!
+    const tx = (await response.wait(1, 60_000))!
+    return (await this.getMessagesInTx(await this.getTransaction(tx)))[0]!
   }
 
   /** {@inheritDoc Chain.getOffchainTokenData} */
@@ -1104,32 +1079,70 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
   }
 
   /**
-   * {@inheritDoc Chain.generateUnsignedExecuteReport}
+   * {@inheritDoc Chain.generateUnsignedExecute}
    * @returns array containing one unsigned `manuallyExecute` TransactionRequest object
+   * @throws {@link CCIPVersionUnsupportedError} if OffRamp version is not supported
    */
-  async generateUnsignedExecuteReport({
-    offRamp,
-    execReport,
-    ...opts
-  }: Parameters<Chain['generateUnsignedExecuteReport']>[0]): Promise<UnsignedEVMTx> {
-    const [_, version] = await this.typeAndVersion(offRamp)
+  async generateUnsignedExecute(
+    opts: Parameters<Chain['generateUnsignedExecute']>[0],
+  ): Promise<UnsignedEVMTx> {
+    let input: ExecutionInput, offRamp: string
+    if (!('input' in opts)) {
+      if (!this.apiClient) throw new CCIPApiClientNotAvailableError()
+      ;({ offRamp, ...input } = await this.apiClient.getExecutionInput(opts.messageId))
+    } else {
+      ;({ offRamp, input } = opts)
+    }
+    if ('verifications' in input) {
+      const contract = new Contract(
+        offRamp,
+        interfaces.OffRamp_v2_0,
+        this.provider,
+      ) as unknown as TypedContract<typeof OffRamp_2_0_ABI>
+
+      const message = decodeMessageV1(input.encodedMessage)
+      const messageId = keccak256(input.encodedMessage)
+      // `execute` doesn't revert on failure, so we need to estimate using `executeSingleMessage`
+      const txGasLimit = await contract.executeSingleMessage.estimateGas(
+        {
+          ...message,
+          executionGasLimit: BigInt(message.executionGasLimit),
+          ccipReceiveGasLimit: BigInt(message.ccipReceiveGasLimit),
+          finality: BigInt(message.finality),
+        },
+        messageId,
+        input.verifications.map(({ destAddress }) => destAddress),
+        input.verifications.map(({ ccvData }) => hexlify(ccvData)),
+        BigInt(opts.gasLimit ?? 0),
+        { from: offRamp }, // internal method
+      )
+      const execTx = await contract.execute.populateTransaction(
+        input.encodedMessage,
+        input.verifications.map(({ destAddress }) => destAddress),
+        input.verifications.map(({ ccvData }) => hexlify(ccvData)),
+        BigInt(opts.gasLimit ?? 0),
+      )
+      execTx.gasLimit = txGasLimit + 40000n // plus `execute`'s overhead
+      return { family: ChainFamily.EVM, transactions: [execTx] }
+    }
 
     let manualExecTx
-    const offchainTokenData = execReport.offchainTokenData.map(encodeEVMOffchainTokenData)
+    const [_, version] = await this.typeAndVersion(offRamp)
+    const offchainTokenData = input.offchainTokenData.map(encodeEVMOffchainTokenData)
 
     switch (version) {
       case CCIPVersion.V1_2: {
         const contract = new Contract(
           offRamp,
-          EVM2EVMOffRamp_1_2_ABI,
+          interfaces.EVM2EVMOffRamp_v1_2,
           this.provider,
         ) as unknown as TypedContract<typeof EVM2EVMOffRamp_1_2_ABI>
         const gasOverride = BigInt(opts.gasLimit ?? 0)
         manualExecTx = await contract.manuallyExecute.populateTransaction(
           {
-            ...execReport,
-            proofs: execReport.proofs.map((d) => hexlify(d)),
-            messages: [execReport.message as CCIPMessage<typeof CCIPVersion.V1_2>],
+            ...input,
+            proofs: input.proofs.map((d) => hexlify(d)),
+            messages: [input.message as CCIPMessage<typeof CCIPVersion.V1_2>],
             offchainTokenData: [offchainTokenData],
           },
           [gasOverride],
@@ -1139,20 +1152,20 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
       case CCIPVersion.V1_5: {
         const contract = new Contract(
           offRamp,
-          EVM2EVMOffRamp_1_5_ABI,
+          interfaces.EVM2EVMOffRamp_v1_5,
           this.provider,
         ) as unknown as TypedContract<typeof EVM2EVMOffRamp_1_5_ABI>
         manualExecTx = await contract.manuallyExecute.populateTransaction(
           {
-            ...execReport,
-            proofs: execReport.proofs.map((d) => hexlify(d)),
-            messages: [execReport.message as CCIPMessage<typeof CCIPVersion.V1_5>],
+            ...input,
+            proofs: input.proofs.map((d) => hexlify(d)),
+            messages: [input.message as CCIPMessage<typeof CCIPVersion.V1_5>],
             offchainTokenData: [offchainTokenData],
           },
           [
             {
               receiverExecutionGasLimit: BigInt(opts.gasLimit ?? 0),
-              tokenGasOverrides: execReport.message.tokenAmounts.map(() =>
+              tokenGasOverrides: input.message.tokenAmounts.map(() =>
                 BigInt(opts.tokensGasLimit ?? opts.gasLimit ?? 0),
               ),
             },
@@ -1162,30 +1175,32 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
       }
       case CCIPVersion.V1_6: {
         // normalize message
-        const sender = zeroPadValue(getAddressBytes(execReport.message.sender), 32)
-        const tokenAmounts = (execReport.message as CCIPMessage_V1_6_EVM).tokenAmounts.map(
-          (ta) => ({
-            ...ta,
-            sourcePoolAddress: zeroPadValue(getAddressBytes(ta.sourcePoolAddress), 32),
-            extraData: hexlify(getDataBytes(ta.extraData)),
-          }),
-        )
+        const senderBytes = getAddressBytes(input.message.sender)
+        // Addresses ≤32 bytes (EVM 20B, Aptos/Solana/Sui 32B) are zero-padded to 32 bytes;
+        // Addresses >32 bytes (e.g., TON 36B) are used as raw bytes without padding
+        const sender =
+          senderBytes.length <= 32 ? zeroPadValue(senderBytes, 32) : hexlify(senderBytes)
+        const tokenAmounts = (input.message as CCIPMessage_V1_6_EVM).tokenAmounts.map((ta) => ({
+          ...ta,
+          sourcePoolAddress: zeroPadValue(getAddressBytes(ta.sourcePoolAddress), 32),
+          extraData: hexlify(getDataBytes(ta.extraData)),
+        }))
         const message = {
-          ...(execReport.message as CCIPMessage_V1_6_EVM),
+          ...(input.message as CCIPMessage_V1_6_EVM),
           sender,
           tokenAmounts,
         }
         const contract = new Contract(
           offRamp,
-          OffRamp_1_6_ABI,
+          interfaces.OffRamp_v1_6,
           this.provider,
         ) as unknown as TypedContract<typeof OffRamp_1_6_ABI>
         manualExecTx = await contract.manuallyExecute.populateTransaction(
           [
             {
-              ...execReport,
-              proofs: execReport.proofs.map((p) => hexlify(p)),
-              sourceChainSelector: execReport.message.sourceChainSelector,
+              ...input,
+              proofs: input.proofs.map((p) => hexlify(p)),
+              sourceChainSelector: input.message.sourceChainSelector,
               messages: [
                 {
                   ...message,
@@ -1205,7 +1220,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
             [
               {
                 receiverExecutionGasLimit: BigInt(opts.gasLimit ?? 0),
-                tokenGasOverrides: execReport.message.tokenAmounts.map(() =>
+                tokenGasOverrides: input.message.tokenAmounts.map(() =>
                   BigInt(opts.tokensGasLimit ?? opts.gasLimit ?? 0),
                 ),
               },
@@ -1220,19 +1235,29 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return { family: ChainFamily.EVM, transactions: [manualExecTx] }
   }
 
-  /** {@inheritDoc Chain.executeReport} */
-  async executeReport(opts: Parameters<Chain['executeReport']>[0]) {
+  /**
+   * {@inheritDoc Chain.execute}
+   * @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 execute(opts: Parameters<Chain['execute']>[0]) {
     const wallet = opts.wallet
     if (!isSigner(wallet)) throw new CCIPWalletInvalidError(wallet)
 
-    const unsignedTxs = await this.generateUnsignedExecuteReport({
+    const unsignedTxs = await this.generateUnsignedExecute({
       ...opts,
       payer: await wallet.getAddress(),
     })
-    const unsignedTx = await wallet.populateTransaction(unsignedTxs.transactions[0]!)
-    unsignedTx.from = undefined // some signers don't like receiving pre-populated `from`
-    const response = await submitTransaction(wallet, unsignedTx, this.provider)
+
+    const unsignedTx: TransactionRequest = unsignedTxs.transactions[0]!
+    unsignedTx.nonce = await this.nextNonce(await wallet.getAddress())
+    const populatedTx = await wallet.populateTransaction(unsignedTx)
+    populatedTx.from = undefined // some signers don't like receiving pre-populated `from`
+
+    const response = await submitTransaction(wallet, populatedTx, this.provider)
     this.logger.debug('manuallyExecute =>', response.hash)
+
     const receipt = await response.wait(1, 60_000)
     if (!receipt?.hash) throw new CCIPExecTxNotConfirmedError(response.hash)
     if (!receipt.status) throw new CCIPExecTxRevertedError(response.hash)
@@ -1272,7 +1297,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 +1329,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 +1415,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)
@@ -1456,6 +1489,64 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     )
   }
 
+  /** {@inheritDoc Chain.getVerifications} */
+  override async getVerifications(
+    opts: Parameters<Chain['getVerifications']>[0],
+  ): Promise<CCIPVerifications> {
+    const { offRamp, request } = opts
+    if (request.lane.version >= CCIPVersion.V2_0) {
+      const message = request.message as CCIPMessage_V2_0
+      if (!message.encodedMessage)
+        throw new CCIPNotImplementedError(`CCIPAPIClient getMessageById v2 encodedMessage`)
+      const contract = new Contract(
+        offRamp,
+        interfaces.OffRamp_v2_0,
+        this.provider,
+      ) as unknown as TypedContract<typeof OffRamp_2_0_ABI>
+      const ccvs = await contract.getCCVsForMessage(message.encodedMessage)
+      const [requiredCCVs, optionalCCVs, optionalThreshold] = ccvs.map(
+        resultToObject,
+      ) as unknown as CleanAddressable<typeof ccvs>
+      const verificationPolicy = {
+        requiredCCVs,
+        optionalCCVs,
+        optionalThreshold: Number(optionalThreshold),
+      }
+
+      if (this.apiClient) {
+        const apiRes = await this.apiClient.getMessageById(request.message.messageId)
+        if ('verifiers' in apiRes.message) {
+          const verifiers = apiRes.message.verifiers as {
+            items: {
+              destAddress: string
+              sourceAddress: string
+              verification: { data: string; timestamp: string }
+            }[]
+          }
+          return {
+            verificationPolicy,
+            verifications: verifiers.items.map((item) => ({
+              destAddress: item.destAddress,
+              sourceAddress: item.sourceAddress,
+              ccvData: item.verification.data,
+              timestamp: new Date(item.verification.timestamp).getTime() / 1e3,
+            })),
+          }
+        }
+      }
+
+      const url = `${CCV_INDEXER_URL}/v1/verifierresults/${request.message.messageId}`
+      const res = await fetch(url)
+      const json = await res.json()
+      return json as CCIPVerifications
+    } else if (request.lane.version < CCIPVersion.V1_6) {
+      // v1.2..v1.5 EVM (only) have separate CommitStore
+      opts.offRamp = await this.getCommitStoreForOffRamp(opts.offRamp)
+    }
+    // fallback <=v1.6
+    return super.getVerifications(opts)
+  }
+
   /** {@inheritDoc Chain.getExecutionReceipts} */
   override async *getExecutionReceipts(
     opts: Parameters<Chain['getExecutionReceipts']>[0],
@@ -1475,10 +1566,14 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         // onlyFallback: false,
       }
     } else /* >= V1.6 */ {
+      const topicHash =
+        version === CCIPVersion.V1_6
+          ? interfaces.OffRamp_v1_6.getEvent('ExecutionStateChanged')!.topicHash
+          : interfaces.OffRamp_v2_0.getEvent('ExecutionStateChanged')!.topicHash
       opts_ = {
         ...opts,
         topics: [
-          interfaces.OffRamp_v1_6.getEvent('ExecutionStateChanged')!.topicHash,
+          topicHash,
           sourceChainSelector ? toBeHex(sourceChainSelector, 32) : null,
           null,
           messageId ?? null,