@chainlink/ccip-sdk 0.90.2 → 0.91.0

package/src/evm/index.ts

@@ -1,19 +1,15 @@
-import util from 'util'
-
 import { parseAbi } from 'abitype'
 import {
   type BytesLike,
+  type Interface,
   type JsonRpcApiProvider,
   type Log,
-  type Provider,
   type Signer,
   type TransactionReceipt,
-  AbstractSigner,
-  BaseWallet,
+  type TransactionRequest,
   Contract,
   JsonRpcProvider,
   Result,
-  SigningKey,
   WebSocketProvider,
   ZeroAddress,
   concat,
@@ -24,19 +20,15 @@ import {
   hexlify,
   isBytesLike,
   isHexString,
+  toBeHex,
   toBigInt,
   zeroPadValue,
 } from 'ethers'
 import type { TypedContract } from 'ethers-abitype'
-import moize, { type Key } from 'moize'
+import { memoize } from 'micro-memoize'
+import type { PickDeep, SetRequired } from 'type-fest'
 
-import {
-  type ChainTransaction,
-  type LogFilter,
-  type TokenPoolRemote,
-  Chain,
-  ChainFamily,
-} from '../chain.ts'
+import { type LogFilter, type TokenPoolRemote, Chain } from '../chain.ts'
 import {
   type EVMExtraArgsV1,
   type EVMExtraArgsV2,
@@ -52,8 +44,11 @@ import type { LeafHasher } from '../hasher/common.ts'
 import { supportedChains } from '../supported-chains.ts'
 import {
   type AnyMessage,
+  type CCIPCommit,
+  type CCIPExecution,
   type CCIPMessage,
   type CCIPRequest,
+  type ChainTransaction,
   type CommitReport,
   type ExecutionReceipt,
   type ExecutionReport,
@@ -62,17 +57,18 @@ import {
   type Log_,
   type NetworkInfo,
   type OffchainTokenData,
+  type WithLogger,
   CCIPVersion,
+  ChainFamily,
 } from '../types.ts'
 import {
-  blockRangeGenerator,
   decodeAddress,
   decodeOnRampAddress,
   getAddressBytes,
   getDataBytes,
-  getSomeBlockNumberBefore,
   networkInfo,
   parseTypeAndVersion,
+  util,
 } from '../utils.ts'
 import type Token_ABI from './abi/BurnMintERC677Token.ts'
 import type FeeQuoter_ABI from './abi/FeeQuoter_1_6.ts'
@@ -87,23 +83,35 @@ 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_APPROVE_GAS_LIMIT,
   DEFAULT_GAS_LIMIT,
   commitsFragments,
   defaultAbiCoder,
-  getAllFragmentsMatchingEvents,
   interfaces,
   receiptsFragments,
   requestsFragments,
 } from './const.ts'
 import { parseData } from './errors.ts'
 import { getV12LeafHasher, getV16LeafHasher } from './hasher.ts'
+import { getEvmLogs } from './logs.ts'
 import {
   type CCIPMessage_V1_6_EVM,
   type CleanAddressable,
   parseSourceTokenData,
 } from './messages.ts'
 import { encodeEVMOffchainTokenData, fetchEVMOffchainTokenData } from './offchain.ts'
+import {
+  fetchAllMessagesInBatch,
+  fetchCCIPRequestById,
+  fetchCCIPRequestsInTx,
+} from '../requests.ts'
+
+/**
+ * Type representing a set of unsigned EVM transactions
+ */
+export type UnsignedEVMTx = {
+  family: typeof ChainFamily.EVM
+  transactions: Pick<TransactionRequest, 'from' | 'to' | 'data'>[]
+}
 
 const VersionedContractABI = parseAbi(['function typeAndVersion() view returns (string)'])
 
@@ -134,81 +142,67 @@ function resultsToMessage(result: Result): Record<string, unknown> {
   } as unknown as CCIPMessage
 }
 
+/** typeguard for ethers Signer interface (used for `wallet`s)  */
+function isSigner(wallet: unknown): wallet is Signer {
+  return (
+    typeof wallet === 'object' &&
+    wallet !== null &&
+    'signTransaction' in wallet &&
+    'getAddress' in wallet
+  )
+}
+
+/**
+ * EVM chain implementation supporting Ethereum-compatible networks.
+ */
 export class EVMChain extends Chain<typeof ChainFamily.EVM> {
+  static {
+    supportedChains[ChainFamily.EVM] = EVMChain
+  }
   static readonly family = ChainFamily.EVM
   static readonly decimals = 18
 
-  readonly network: NetworkInfo<typeof ChainFamily.EVM>
-  readonly provider: JsonRpcApiProvider
+  provider: JsonRpcApiProvider
+  readonly destroy$: Promise<void>
 
-  constructor(provider: JsonRpcApiProvider, network: NetworkInfo) {
-    if (network.family !== ChainFamily.EVM)
-      throw new Error(`Invalid network family for EVMChain: ${network.family}`)
-    super()
+  /**
+   * Creates a new EVMChain instance.
+   * @param provider - JSON-RPC provider for the EVM network.
+   * @param network - Network information for this chain.
+   */
+  constructor(provider: JsonRpcApiProvider, network: NetworkInfo, ctx?: WithLogger) {
+    super(network, ctx)
 
-    this.network = network
     this.provider = provider
+    this.destroy$ = new Promise<void>((resolve) => (this.destroy = resolve))
+    void this.destroy$.finally(() => provider.destroy())
 
-    this.typeAndVersion = moize.default(this.typeAndVersion.bind(this))
-    this.getBlockTimestamp = moize.default(this.getBlockTimestamp.bind(this), {
+    this.typeAndVersion = memoize(this.typeAndVersion.bind(this))
+
+    this.provider.getBlock = memoize(provider.getBlock.bind(provider), {
       maxSize: 100,
-      updateCacheForKey: (key: Key[]) => typeof key[key.length - 1] !== 'number',
+      maxArgs: 1,
+      async: true,
+      forceUpdate: ([block]) => typeof block !== 'number',
     })
-    this.getTransaction = moize.default(this.getTransaction.bind(this), {
+    this.getTransaction = memoize(this.getTransaction.bind(this), {
       maxSize: 100,
-      transformArgs: (args: Key[]) =>
+      transformKey: (args) =>
         typeof args[0] !== 'string'
           ? [(args[0] as unknown as TransactionReceipt).hash]
           : (args as unknown as string[]),
     })
-    this.getTokenForTokenPool = moize.default(this.getTokenForTokenPool.bind(this))
-    this.getNativeTokenForRouter = moize.default(this.getNativeTokenForRouter.bind(this), {
+    this.getTokenForTokenPool = memoize(this.getTokenForTokenPool.bind(this))
+    this.getNativeTokenForRouter = memoize(this.getNativeTokenForRouter.bind(this), {
       maxArgs: 1,
-      isPromise: true,
+      async: true,
     })
-    this.getTokenInfo = moize.default(this.getTokenInfo.bind(this))
-    this.getWallet = moize.default(this.getWallet.bind(this), { maxSize: 1, maxArgs: 0 })
-    this.getTokenAdminRegistryFor = moize.default(this.getTokenAdminRegistryFor.bind(this), {
-      isPromise: true,
+    this.getTokenInfo = memoize(this.getTokenInfo.bind(this))
+    this.getTokenAdminRegistryFor = memoize(this.getTokenAdminRegistryFor.bind(this), {
+      async: true,
       maxArgs: 1,
     })
-  }
-
-  // overwrite EVMChain.getWallet to implement custom wallet loading
-  // some signers don't like to be `.connect`ed, so pass provider as first param
-  static getWallet(_provider: Provider, _opts: { wallet?: unknown }): Promise<Signer> {
-    throw new Error('static EVM wallet loading not available')
-  }
-
-  // cached wallet/signer getter
-  async getWallet(opts: { wallet?: unknown } = {}): Promise<Signer> {
-    if (
-      typeof opts.wallet === 'number' ||
-      (typeof opts.wallet === 'string' && opts.wallet.match(/^(\d+|0x[a-fA-F0-9]{40})$/))
-    ) {
-      // if given a number, numeric string or address, use ethers `provider.getSigner` (e.g. geth or MM)
-      return this.provider.getSigner(
-        typeof opts.wallet === 'string' && opts.wallet.match(/^0x[a-fA-F0-9]{40}$/)
-          ? opts.wallet
-          : Number(opts.wallet),
-      )
-    } else if (typeof opts.wallet === 'string') {
-      // support receiving private key directly (not recommended)
-      try {
-        return Promise.resolve(
-          new BaseWallet(
-            new SigningKey((opts.wallet.startsWith('0x') ? '' : '0x') + opts.wallet),
-            this.provider,
-          ),
-        )
-      } catch (_) {
-        // pass
-      }
-    } else if (opts.wallet instanceof AbstractSigner) {
-      // if given a signer, return/cache it
-      return opts.wallet
-    }
-    return (this.constructor as typeof EVMChain).getWallet(this.provider, opts)
+    this.getFeeTokens = memoize(this.getFeeTokens.bind(this), { async: true, maxArgs: 1 })
   }
 
   /**
@@ -218,10 +212,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return (await this.provider.listAccounts()).map(({ address }) => address)
   }
 
-  async getWalletAddress(opts?: { wallet?: unknown }): Promise<string> {
-    return (await this.getWallet(opts)).getAddress()
-  }
-
+  /**
+   * Creates a JSON-RPC provider from a URL.
+   * @param url - WebSocket (wss://) or HTTP (https://) endpoint URL.
+   * @returns A ready JSON-RPC provider.
+   */
   static async _getProvider(url: string): Promise<JsonRpcApiProvider> {
     let provider: JsonRpcApiProvider
     let providerReady: Promise<JsonRpcApiProvider>
@@ -246,37 +241,45 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return providerReady
   }
 
-  static async fromProvider(provider: JsonRpcApiProvider): Promise<EVMChain> {
+  /**
+   * Creates an EVMChain instance from an existing provider.
+   * @param provider - JSON-RPC provider instance.
+   * @param ctx - context containing logger.
+   * @returns A new EVMChain instance.
+   */
+  static async fromProvider(provider: JsonRpcApiProvider, ctx?: WithLogger): Promise<EVMChain> {
     try {
-      return new EVMChain(provider, networkInfo(Number((await provider.getNetwork()).chainId)))
+      return new EVMChain(provider, networkInfo(Number((await provider.getNetwork()).chainId)), ctx)
     } catch (err) {
       provider.destroy()
       throw err
     }
   }
 
-  static async fromUrl(url: string): Promise<EVMChain> {
-    return this.fromProvider(await this._getProvider(url))
-  }
-
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async destroy(): Promise<void> {
-    this.provider.destroy()
+  /**
+   * 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.
+   */
+  static async fromUrl(url: string, ctx?: WithLogger): Promise<EVMChain> {
+    return this.fromProvider(await this._getProvider(url), ctx)
   }
 
+  /** {@inheritDoc Chain.getBlockTimestamp} */
   async getBlockTimestamp(block: number | 'finalized'): Promise<number> {
-    const res = await this.provider.getBlock(block)
+    const res = await this.provider.getBlock(block) // cached
     if (!res) throw new Error(`Block not found: ${block}`)
     return res.timestamp
   }
 
+  /** {@inheritDoc Chain.getTransaction} */
   async getTransaction(hash: string | TransactionReceipt): Promise<ChainTransaction> {
     const tx = typeof hash === 'string' ? await this.provider.getTransactionReceipt(hash) : hash
     if (!tx) throw new Error(`Transaction not found: ${hash as string}`)
     const timestamp = await this.getBlockTimestamp(tx.blockNumber)
     const chainTx = {
       ...tx,
-      chain: this,
       timestamp,
       logs: [] as Log_[],
     }
@@ -285,47 +288,62 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return chainTx
   }
 
-  async *getLogs(filter: LogFilter): AsyncIterableIterator<Log> {
-    const endBlock = filter.endBlock ?? (await this.provider.getBlockNumber())
-    if (
-      filter.topics?.length &&
-      filter.topics.every((t: string | string[]): t is string => typeof t === 'string')
-    ) {
-      const topics = new Set(
-        filter.topics
-          .filter(isHexString)
-          .concat(Object.keys(getAllFragmentsMatchingEvents(filter.topics)) as `0x${string}`[])
-          .flat(),
-      )
-      if (!topics.size) {
-        // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-        throw new Error(`Could not find matching topics: ${filter.topics}`)
+  /** {@inheritDoc Chain.getLogs} */
+  async *getLogs(filter: LogFilter & { onlyFallback?: boolean }): AsyncIterableIterator<Log> {
+    yield* getEvmLogs(filter, this)
+  }
+
+  /** {@inheritDoc Chain.fetchRequestsInTx} */
+  async fetchRequestsInTx(tx: string | ChainTransaction): Promise<CCIPRequest[]> {
+    return fetchCCIPRequestsInTx(this, typeof tx === 'string' ? await this.getTransaction(tx) : tx)
+  }
+
+  /** {@inheritDoc Chain.fetchRequestById} */
+  override fetchRequestById(
+    messageId: string,
+    onRamp?: string,
+    opts?: { page?: number },
+  ): Promise<CCIPRequest> {
+    return fetchCCIPRequestById(this, messageId, { address: onRamp, ...opts })
+  }
+
+  /** {@inheritDoc Chain.fetchAllMessagesInBatch} */
+  async fetchAllMessagesInBatch<
+    R extends PickDeep<
+      CCIPRequest,
+      'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.header.sequenceNumber'
+    >,
+  >(
+    request: R,
+    commit: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>,
+    opts?: { page?: number },
+  ): Promise<R['message'][]> {
+    let opts_: Parameters<EVMChain['getLogs']>[0] | undefined
+    if (request.lane.version >= CCIPVersion.V1_6) {
+      // specialized getLogs filter for v1.6 CCIPMessageSent events, to filter by dest
+      opts_ = {
+        ...opts,
+        topics: [[request.log.topics[0]], [toBeHex(request.lane.destChainSelector, 32)]],
       }
-      filter.topics = [Array.from(topics)]
-    }
-    if (!filter.startBlock && filter.startTime) {
-      filter.startBlock = await getSomeBlockNumberBefore(
-        this.getBlockTimestamp.bind(this),
-        endBlock,
-        filter.startTime,
-      )
-    }
-    for (const blockRange of blockRangeGenerator({ ...filter, endBlock })) {
-      console.debug('evm getLogs:', {
-        ...blockRange,
-        ...(filter.address ? { address: filter.address } : {}),
-        ...(filter.topics?.length ? { topics: filter.topics } : {}),
-      })
-      const logs = await this.provider.getLogs({
-        ...blockRange,
-        ...(filter.address ? { address: filter.address } : {}),
-        ...(filter.topics?.length ? { topics: filter.topics } : {}),
-      })
-      if (!filter.startBlock) logs.reverse()
-      yield* logs
     }
+    return fetchAllMessagesInBatch(this, request, commit, opts_)
+  }
+
+  /** {@inheritDoc Chain.typeAndVersion} */
+  async typeAndVersion(address: string) {
+    const contract = new Contract(
+      address,
+      VersionedContractABI,
+      this.provider,
+    ) as unknown as TypedContract<typeof VersionedContractABI>
+    return parseTypeAndVersion(await contract.typeAndVersion())
   }
 
+  /**
+   * 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.
+   */
   static decodeMessage(log: {
     topics?: readonly string[]
     data: unknown
@@ -383,11 +401,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
               ...tokenAmount,
             }
           } catch (_) {
-            console.debug(
-              'legacy sourceTokenData:',
-              i,
-              (message as { sourceTokenData: string[] }).sourceTokenData[i],
-            )
+            // legacy sourceTokenData
           }
         }
         if (typeof tokenAmount.destExecData === 'string' && tokenAmount.destGasAmount == null) {
@@ -428,6 +442,12 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return message as CCIPMessage
   }
 
+  /**
+   * Decodes commit reports from a log event.
+   * @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.
+   */
   static decodeCommits(
     log: { topics?: readonly string[]; data: unknown },
     lane?: Omit<Lane, 'destChainSelector'>,
@@ -478,6 +498,11 @@ 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.
+   */
   static decodeReceipt(log: {
     topics?: readonly string[]
     data: unknown
@@ -502,6 +527,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /**
+   * Decodes extra arguments from a CCIP message.
+   * @param extraArgs - Encoded extra arguments bytes.
+   * @returns Decoded extra arguments with tag, or undefined if unknown format.
+   */
   static decodeExtraArgs(
     extraArgs: BytesLike,
   ):
@@ -542,6 +572,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /**
+   * Encodes extra arguments for a CCIP message.
+   * @param args - Extra arguments to encode.
+   * @returns Encoded extra arguments as hex string.
+   */
   static encodeExtraArgs(args: ExtraArgs): string {
     if (!args) return '0x'
     if ('computeUnits' in args) {
@@ -581,6 +616,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return '0x'
   }
 
+  /**
+   * 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.
+   */
   static getAddress(bytes: BytesLike): string {
     bytes = getBytes(bytes)
     if (bytes.length < 20) throw new Error(`Invalid address: ${hexlify(bytes)}`)
@@ -594,15 +634,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return getAddress(hexlify(bytes))
   }
 
-  async typeAndVersion(address: string) {
-    const contract = new Contract(
-      address,
-      VersionedContractABI,
-      this.provider,
-    ) as unknown as TypedContract<typeof VersionedContractABI>
-    return parseTypeAndVersion(await contract.typeAndVersion())
-  }
-
+  /**
+   * Gets lane configuration from an OnRamp contract.
+   * @param onRamp - OnRamp contract address.
+   * @returns Lane configuration.
+   */
   async getLaneForOnRamp(onRamp: string): Promise<Lane> {
     const [, version] = await this.typeAndVersion(onRamp)
     const onRampABI = version === CCIPVersion.V1_2 ? EVM2EVMOnRamp_1_2_ABI : EVM2EVMOnRamp_1_5_ABI
@@ -623,6 +659,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /** {@inheritDoc Chain.getRouterForOnRamp} */
   async getRouterForOnRamp(onRamp: string, destChainSelector: bigint): Promise<string> {
     const [, version] = await this.typeAndVersion(onRamp)
     let onRampABI
@@ -651,6 +688,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /** {@inheritDoc Chain.getRouterForOffRamp} */
   async getRouterForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI, router
@@ -684,6 +722,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return router as string
   }
 
+  /** {@inheritDoc Chain.getNativeTokenForRouter} */
   async getNativeTokenForRouter(router: string): Promise<string> {
     const contract = new Contract(
       router,
@@ -693,6 +732,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return contract.getWrappedNative() as Promise<string>
   }
 
+  /** {@inheritDoc Chain.getOffRampsForRouter} */
   async getOffRampsForRouter(router: string, sourceChainSelector: bigint): Promise<string[]> {
     const contract = new Contract(
       router,
@@ -705,6 +745,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
       .map(({ offRamp }) => offRamp) as string[]
   }
 
+  /** {@inheritDoc Chain.getOnRampForRouter} */
   async getOnRampForRouter(router: string, destChainSelector: bigint): Promise<string> {
     const contract = new Contract(
       router,
@@ -714,6 +755,7 @@ 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> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI
@@ -746,6 +788,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /** {@inheritDoc Chain.getCommitStoreForOffRamp} */
   async getCommitStoreForOffRamp(offRamp: string): Promise<string> {
     const [, version] = await this.typeAndVersion(offRamp)
     let offRampABI
@@ -771,6 +814,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /** {@inheritDoc Chain.getTokenForTokenPool} */
   async getTokenForTokenPool(tokenPool: string): Promise<string> {
     const contract = new Contract(
       tokenPool,
@@ -780,6 +824,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return contract.getToken() as Promise<string>
   }
 
+  /** {@inheritDoc Chain.getTokenInfo} */
   async getTokenInfo(token: string): Promise<{ decimals: number; symbol: string; name: string }> {
     const contract = new Contract(
       token,
@@ -794,12 +839,16 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return { symbol, decimals: Number(decimals), name }
   }
 
-  static getDestLeafHasher({
-    sourceChainSelector,
-    destChainSelector,
-    onRamp,
-    version,
-  }: Lane): LeafHasher {
+  /**
+   * Gets the leaf hasher for computing Merkle proofs on the destination chain.
+   * @param lane - Lane configuration.
+   * @param ctx - Context object containing logger.
+   * @returns Leaf hasher function.
+   */
+  static getDestLeafHasher(
+    { sourceChainSelector, destChainSelector, onRamp, version }: Lane,
+    ctx?: WithLogger,
+  ): LeafHasher {
     switch (version) {
       case CCIPVersion.V1_2:
       case CCIPVersion.V1_5:
@@ -807,12 +856,17 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
           throw new Error(`Unsupported source chain: ${sourceChainSelector}`)
         return getV12LeafHasher(sourceChainSelector, destChainSelector, onRamp) as LeafHasher
       case CCIPVersion.V1_6:
-        return getV16LeafHasher(sourceChainSelector, destChainSelector, onRamp) as LeafHasher
+        return getV16LeafHasher(sourceChainSelector, destChainSelector, onRamp, ctx) as LeafHasher
       default:
         throw new Error(`Unsupported hasher version for EVM: ${version as string}`)
     }
   }
 
+  /**
+   * Gets any available OnRamp for the given router.
+   * @param router - Router contract address.
+   * @returns OnRamp contract address.
+   */
   async _getSomeOnRampFor(router: string): Promise<string> {
     // when given a router, we take any onRamp we can find, as usually they all use same registry
     const someOtherNetwork = this.network.isTestnet
@@ -825,6 +879,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return this.getOnRampForRouter(router, networkInfo(someOtherNetwork).chainSelector)
   }
 
+  /** {@inheritDoc Chain.getTokenAdminRegistryFor} */
   async getTokenAdminRegistryFor(address: string): Promise<string> {
     let [type, version, typeAndVersion] = await this.typeAndVersion(address)
     if (type === 'TokenAdminRegistry') {
@@ -850,6 +905,11 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return tokenAdminRegistry as string
   }
 
+  /**
+   * Gets the FeeQuoter contract address for a given Router or Ramp.
+   * @param address - Router or Ramp contract address.
+   * @returns FeeQuoter contract address.
+   */
   async getFeeQuoterFor(address: string): Promise<string> {
     let [type, version, typeAndVersion] = await this.typeAndVersion(address)
     if (type === 'FeeQuoter') {
@@ -872,6 +932,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return feeQuoter as string
   }
 
+  /** {@inheritDoc Chain.getFee} */
   async getFee(router_: string, destChainSelector: bigint, message: AnyMessage): Promise<bigint> {
     const router = new Contract(
       router_,
@@ -887,12 +948,24 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     })
   }
 
-  async sendMessage(
-    router_: string,
+  /**
+   * Generate unsigned txs for ccipSend'ing a message
+   * @param sender - sender address
+   * @param router - address of the Router contract
+   * @param destChainSelector - chainSelector of destination chain
+   * @param message - AnyMessage to send; if `fee` is not present, it'll be calculated
+   * @param approveMax - if tokens approvals are needed, opt into approving maximum allowance
+   * @returns Array containing 0 or more unsigned token approvals txs (if needed at the time of
+   *   generation), followed by a ccipSend TransactionRequest
+   */
+  async generateUnsignedSendMessage(
+    sender: string,
+    router: string,
     destChainSelector: bigint,
-    message: AnyMessage & { fee: bigint },
-    opts?: { wallet?: unknown; approveMax?: boolean },
-  ): Promise<ChainTransaction> {
+    message: AnyMessage & { fee?: bigint },
+    opts?: { approveMax?: boolean },
+  ): Promise<UnsignedEVMTx> {
+    if (!message.fee) message.fee = await this.getFee(router, destChainSelector, message)
     const feeToken = message.feeToken ?? ZeroAddress
     const receiver = zeroPadValue(getAddressBytes(message.receiver), 32)
     const data = hexlify(message.data)
@@ -908,34 +981,28 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     if (feeToken !== ZeroAddress)
       amountsToApprove[feeToken] = (amountsToApprove[feeToken] ?? 0n) + message.fee
 
-    const wallet = await this.getWallet(opts) // moized wallet arg (if called previously)
-
-    // approve all tokens (including fee token) in parallel
-    let nonce = await this.provider.getTransactionCount(await this.getWalletAddress())
-    await Promise.all(
-      Object.entries(amountsToApprove).map(async ([token, amount]) => {
-        const contract = new Contract(token, interfaces.Token, wallet) as unknown as TypedContract<
-          typeof Token_ABI
-        >
-        const allowance = await contract.allowance(await wallet.getAddress(), router_)
-        if (allowance < amount) {
+    const approveTxs = (
+      await Promise.all(
+        Object.entries(amountsToApprove).map(async ([token, amount]) => {
+          const contract = new Contract(
+            token,
+            interfaces.Token,
+            this.provider,
+          ) as unknown as TypedContract<typeof Token_ABI>
+          const allowance = await contract.allowance(sender, router)
+          if (allowance >= amount) return
           const amnt = opts?.approveMax ? 2n ** 256n - 1n : amount
-          // optimization: hardcode nonce and gasLimit to send all approvals in parallel without estimating
-          console.info('Approving', amnt, 'of', token, 'tokens for router', router_)
-          const tx = await contract.approve(router_, amnt, {
-            nonce: nonce++,
-            gasLimit: DEFAULT_APPROVE_GAS_LIMIT,
-          })
-          console.info('=>', tx.hash)
-          await tx.wait(1, 60_000)
-        }
-      }),
-    )
+          return contract.approve.populateTransaction(router, amnt, { from: sender })
+        }),
+      )
+    ).filter((tx) => tx != null)
 
-    const router = new Contract(router_, interfaces.Router, wallet) as unknown as TypedContract<
-      typeof Router_ABI
-    >
-    const tx = await router.ccipSend(
+    const contract = new Contract(
+      router,
+      interfaces.Router,
+      this.provider,
+    ) as unknown as TypedContract<typeof Router_ABI>
+    const sendTx = await contract.ccipSend.populateTransaction(
       destChainSelector,
       {
         receiver,
@@ -945,26 +1012,85 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         feeToken,
       },
       {
-        nonce: nonce++,
+        from: sender,
         // if native fee, include it in value; otherwise, it's transferedFrom feeToken
-        ...(feeToken === ZeroAddress ? { value: message.fee } : {}),
+        ...(feeToken === ZeroAddress && { value: message.fee }),
       },
     )
-    const receipt = await tx.wait(1)
-    return this.getTransaction(receipt!)
+    const txRequests = [...approveTxs, sendTx] as SetRequired<typeof sendTx, 'from'>[]
+    return {
+      family: ChainFamily.EVM,
+      transactions: txRequests,
+    }
+  }
+
+  /** {@inheritDoc Chain.sendMessage} */
+  async sendMessage(
+    router_: string,
+    destChainSelector: bigint,
+    message: AnyMessage & { fee?: bigint },
+    opts: { wallet: unknown; approveMax?: boolean },
+  ): Promise<CCIPRequest> {
+    const wallet = opts.wallet
+    if (!isSigner(wallet)) throw new Error(`Wallet must be a Signer, got=${util.inspect(wallet)}`)
+
+    const sender = await wallet.getAddress()
+    const txs = await this.generateUnsignedSendMessage(
+      sender,
+      router_,
+      destChainSelector,
+      message,
+      opts,
+    )
+    const approveTxs = txs.transactions.slice(0, txs.transactions.length - 1)
+    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 signed = await wallet.signTransaction(tx)
+        const response = await this.provider.broadcastTransaction(signed)
+        this.logger.debug('approve =>', response.hash)
+        return response
+      }),
+    )
+    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 signed = await wallet.signTransaction(sendTx)
+    const response = await this.provider.broadcastTransaction(signed)
+    this.logger.debug('ccipSend =>', response.hash)
+    await response.wait(1, 60_000)
+    return (await this.fetchRequestsInTx(await this.getTransaction(response.hash)))[0]
   }
 
+  /** {@inheritDoc Chain.fetchOffchainTokenData} */
   fetchOffchainTokenData(request: CCIPRequest): Promise<OffchainTokenData[]> {
-    return fetchEVMOffchainTokenData(request)
+    return fetchEVMOffchainTokenData(request, this)
   }
 
-  async executeReport(
+  /**
+   * Generate unsigned tx to manuallyExecute a message
+   * @param _payer - not used in EVM
+   * @param offRamp - address of the OffRamp contract
+   * @param execReport - execution report
+   * @param opts - gas limit overrides for ccipReceive and tokenPool calls options
+   * @returns array containing one unsigned `manuallyExecute` TransactionRequest object
+   */
+  async generateUnsignedExecuteReport(
+    _payer: string,
     offRamp: string,
     execReport: ExecutionReport,
-    opts?: { wallet?: string; gasLimit?: number; tokensGasLimit?: number },
-  ) {
+    opts: { gasLimit?: number; tokensGasLimit?: number },
+  ): Promise<UnsignedEVMTx> {
     const [_, version] = await this.typeAndVersion(offRamp)
-    const wallet = await this.getWallet(opts)
 
     let manualExecTx
     const offchainTokenData = execReport.offchainTokenData.map(encodeEVMOffchainTokenData)
@@ -974,10 +1100,10 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         const contract = new Contract(
           offRamp,
           EVM2EVMOffRamp_1_2_ABI,
-          wallet,
+          this.provider,
         ) as unknown as TypedContract<typeof EVM2EVMOffRamp_1_2_ABI>
         const gasOverride = BigInt(opts?.gasLimit ?? 0)
-        manualExecTx = await contract.manuallyExecute(
+        manualExecTx = await contract.manuallyExecute.populateTransaction(
           {
             ...execReport,
             proofs: execReport.proofs.map((d) => hexlify(d)),
@@ -992,9 +1118,9 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         const contract = new Contract(
           offRamp,
           EVM2EVMOffRamp_1_5_ABI,
-          wallet,
+          this.provider,
         ) as unknown as TypedContract<typeof EVM2EVMOffRamp_1_5_ABI>
-        manualExecTx = await contract.manuallyExecute(
+        manualExecTx = await contract.manuallyExecute.populateTransaction(
           {
             ...execReport,
             proofs: execReport.proofs.map((d) => hexlify(d)),
@@ -1027,10 +1153,12 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
           sender,
           tokenAmounts,
         }
-        const contract = new Contract(offRamp, OffRamp_1_6_ABI, wallet) as unknown as TypedContract<
-          typeof OffRamp_1_6_ABI
-        >
-        manualExecTx = await contract.manuallyExecute(
+        const contract = new Contract(
+          offRamp,
+          OffRamp_1_6_ABI,
+          this.provider,
+        ) as unknown as TypedContract<typeof OffRamp_1_6_ABI>
+        manualExecTx = await contract.manuallyExecute.populateTransaction(
           [
             {
               ...execReport,
@@ -1056,20 +1184,48 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
       default:
         throw new Error(`Unsupported version: ${version}`)
     }
-    const receipt = await this.provider.waitForTransaction(manualExecTx.hash, 1, 60e3)
-    if (!receipt?.hash) throw new Error(`Could not confirm exec tx: ${manualExecTx.hash}`)
-    if (!receipt.status) throw new Error(`Exec transaction reverted: ${manualExecTx.hash}`)
+    return { family: ChainFamily.EVM, transactions: [manualExecTx] }
+  }
+
+  /** {@inheritDoc Chain.executeReport} */
+  async executeReport(
+    offRamp: string,
+    execReport: ExecutionReport,
+    opts: { wallet: unknown; gasLimit?: number; tokensGasLimit?: number },
+  ) {
+    const wallet = opts.wallet
+    if (!isSigner(wallet)) throw new Error(`Wallet must be a Signer, got=${util.inspect(wallet)}`)
+
+    const unsignedTxs = await this.generateUnsignedExecuteReport(
+      await wallet.getAddress(),
+      offRamp,
+      execReport,
+      opts,
+    )
+    const unsignedTx = await wallet.populateTransaction(unsignedTxs.transactions[0])
+    unsignedTx.from = undefined // some signers don't like receiving pre-populated `from`
+    const signed = await wallet.signTransaction(unsignedTx)
+    const response = await this.provider.broadcastTransaction(signed)
+    this.logger.debug('ccipSend =>', response.hash)
+    const receipt = await response.wait(1, 60_000)
+    if (!receipt?.hash) throw new Error(`Could not confirm exec tx: ${response.hash}`)
+    if (!receipt.status) throw new Error(`Exec transaction reverted: ${response.hash}`)
     return this.getTransaction(receipt)
   }
 
+  /**
+   * Parses raw data into typed structures.
+   * @param data - Raw data to parse.
+   * @returns Parsed data.
+   */
   static parse(data: unknown) {
     return parseData(data)
   }
 
   /**
-   * Get the supported tokens for a given contract address
-   *
-   * @param address Router, OnRamp, OffRamp or TokenAdminRegistry contract
+   * Get the supported tokens for a given contract address.
+   * @param registry - Router, OnRamp, OffRamp or TokenAdminRegistry contract address.
+   * @param opts - Optional parameters.
    * @returns An array of supported token addresses.
    */
   async getSupportedTokens(registry: string, opts?: { page?: number }): Promise<string[]> {
@@ -1089,6 +1245,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     return res as string[]
   }
 
+  /** {@inheritDoc Chain.getRegistryTokenConfig} */
   async getRegistryTokenConfig(
     registry: string,
     token: string,
@@ -1117,6 +1274,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     }
   }
 
+  /** {@inheritDoc Chain.getTokenPoolConfigs} */
   async getTokenPoolConfigs(tokenPool: string): Promise<{
     token: string
     router: string
@@ -1141,6 +1299,7 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
     })
   }
 
+  /** {@inheritDoc Chain.getTokenPoolRemotes} */
   async getTokenPoolRemotes(
     tokenPool: string,
     remoteChainSelector?: bigint,
@@ -1216,24 +1375,36 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
         ),
     )
   }
-  async listFeeTokens(router: string) {
+
+  /** {@inheritDoc Chain.getFeeTokens} */
+  async getFeeTokens(router: string) {
     const onRamp = await this._getSomeOnRampFor(router)
     const [_, version] = await this.typeAndVersion(onRamp)
     let tokens
-    let onRampABI
+    let onRampIface: Interface
     switch (version) {
       case CCIPVersion.V1_2:
-        onRampABI = EVM2EVMOnRamp_1_2_ABI
+        onRampIface = interfaces.EVM2EVMOnRamp_v1_2
       // falls through
       case CCIPVersion.V1_5: {
-        onRampABI ??= EVM2EVMOnRamp_1_5_ABI
-        const contract = new Contract(onRamp, onRampABI, this.provider) as unknown as TypedContract<
-          typeof onRampABI
-        >
-        tokens = await Promise.all([
-          this.getNativeTokenForRouter(router),
-          contract.getStaticConfig().then(({ linkToken }) => linkToken),
-        ])
+        onRampIface ??= interfaces.EVM2EVMOnRamp_v1_5
+        const fragment = onRampIface.getEvent('FeeConfigSet')!
+        const tokens_ = new Set()
+        for await (const log of this.getLogs({
+          address: onRamp,
+          topics: [fragment.topicHash],
+          startBlock: 1,
+          onlyFallback: true,
+        })) {
+          ;(
+            onRampIface.decodeEventLog(fragment, log.data, log.topics) as unknown as {
+              feeConfig: { token: string; enabled: boolean }[]
+            }
+          ).feeConfig.forEach(({ token, enabled }) =>
+            enabled ? tokens_.add(token) : tokens_.delete(token),
+          )
+        }
+        tokens = Array.from(tokens_)
         break
       }
       case CCIPVersion.V1_6: {
@@ -1257,6 +1428,37 @@ export class EVMChain extends Chain<typeof ChainFamily.EVM> {
       ),
     )
   }
-}
 
-supportedChains[ChainFamily.EVM] = EVMChain
+  /** {@inheritDoc Chain.fetchExecutionReceipts} */
+  override async *fetchExecutionReceipts(
+    offRamp: string,
+    request: PickDeep<CCIPRequest, 'lane' | 'message.header.messageId' | 'tx.timestamp'>,
+    commit?: CCIPCommit,
+    opts?: { page?: number },
+  ): AsyncIterableIterator<CCIPExecution> {
+    let opts_: Parameters<EVMChain['getLogs']>[0] | undefined = opts
+    if (request.lane.version < CCIPVersion.V1_6) {
+      opts_ = {
+        ...opts,
+        topics: [
+          interfaces.EVM2EVMOffRamp_v1_5.getEvent('ExecutionStateChanged')!.topicHash,
+          null,
+          request.message.header.messageId,
+        ],
+        // onlyFallback: false,
+      }
+    } else /* >= V1.6 */ {
+      opts_ = {
+        ...opts,
+        topics: [
+          interfaces.OffRamp_v1_6.getEvent('ExecutionStateChanged')!.topicHash,
+          toBeHex(request.lane.sourceChainSelector, 32),
+          null,
+          request.message.header.messageId,
+        ],
+        // onlyFallback: false,
+      }
+    }
+    yield* super.fetchExecutionReceipts(offRamp, request, commit, opts_)
+  }
+}