@chainlink/ccip-sdk 0.96.0 → 1.0.0

package/dist/chain.d.ts

@@ -7,7 +7,7 @@ import type { EVMExtraArgsV1, EVMExtraArgsV2, ExtraArgs, GenericExtraArgsV3, SVM
 import type { LeafHasher } from './hasher/common.ts';
 import type { UnsignedSolanaTx } from './solana/types.ts';
 import type { UnsignedTONTx } from './ton/types.ts';
-import { type AnyMessage, type CCIPCommit, type CCIPExecution, type CCIPMessage, type CCIPRequest, type ChainFamily, type ChainTransaction, type CommitReport, type ExecutionReceipt, type ExecutionReport, type Lane, type Log_, type Logger, type MessageInput, type NetworkInfo, type OffchainTokenData, type WithLogger } from './types.ts';
+import { type AnyMessage, type CCIPExecution, type CCIPMessage, type CCIPRequest, type CCIPVerifications, type ChainFamily, type ChainLog, type ChainTransaction, type CommitReport, type ExecutionInput, type ExecutionReceipt, type Lane, type Logger, type MessageInput, type NetworkInfo, type OffchainTokenData, type WithLogger } from './types.ts';
 import { util } from './utils.ts';
 /**
  * Context for Chain class initialization.
@@ -21,7 +21,7 @@ import { util } from './utils.ts';
  *
  * @example Custom API endpoint
  * ```typescript
- * const api = new CCIPAPIClient('https://staging-api.example.com', { logger })
+ * const api = CCIPAPIClient.fromUrl('https://staging-api.example.com', { logger })
  * const chain = await EVMChain.fromUrl(rpcUrl, { apiClient: api, logger })
  * ```
  *
@@ -220,13 +220,20 @@ export type SendMessageOpts = {
     approveMax?: boolean;
 };
 /**
- * Common options for {@link Chain.generateUnsignedExecuteReport} and {@link Chain.executeReport} methods.
+ * Common options for {@link Chain.generateUnsignedExecute} and {@link Chain.execute} methods.
  */
-export type ExecuteReportOpts = {
+export type ExecuteOpts = ({
     /** address of the OffRamp contract */
     offRamp: string;
-    /** execution report */
-    execReport: ExecutionReport;
+    /** input payload to execute message; contains proofs for v1 and verifications for v2 */
+    input: ExecutionInput;
+} | {
+    /**
+     * messageId of message to execute; requires `apiClient`.
+     * @remarks Currently throws CCIPNotImplementedError - API endpoint pending.
+     */
+    messageId: string;
+}) & {
     /** gasLimit or computeUnits limit override for the ccipReceive call */
     gasLimit?: number;
     /** For EVM, overrides gasLimit on tokenPool call */
@@ -259,24 +266,63 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
     /** Cleanup method to release resources (e.g., close connections). */
     destroy?(): void | Promise<void>;
     /**
-     * Fetch the timestamp of a given block
-     * @param block - positive block number, negative finality depth or 'finalized' tag
-     * @returns timestamp of the block, in seconds
+     * Fetch the timestamp of a given block.
+     *
+     * @param block - Positive block number, negative finality depth, or 'finalized' tag
+     * @returns Promise resolving to timestamp of the block, in seconds
+     *
      * @throws {@link CCIPBlockNotFoundError} if block does not exist
+     *
+     * @example Get finalized block timestamp
+     * ```typescript
+     * const chain = await EVMChain.fromUrl('https://eth-mainnet.example.com')
+     * const timestamp = await chain.getBlockTimestamp('finalized')
+     * console.log(`Finalized at: ${new Date(timestamp * 1000).toISOString()}`)
+     * ```
      */
     abstract getBlockTimestamp(block: number | 'finalized'): Promise<number>;
     /**
-     * Fetch a transaction by its hash
-     * @param hash - transaction hash
-     * @returns generic transaction details
-     * @throws {@link CCIPTransactionNotFoundError} if transaction not found
+     * Fetch a transaction by its hash.
+     *
+     * @param hash - Transaction hash
+     * @returns Promise resolving to generic transaction details
+     *
+     * @throws {@link CCIPTransactionNotFoundError} if transaction does not exist (transient)
+     *
+     * @example Fetch transaction details
+     * ```typescript
+     * const chain = await EVMChain.fromUrl('https://eth-mainnet.example.com')
+     * try {
+     *   const tx = await chain.getTransaction('0xabc123...')
+     *   console.log(`Block: ${tx.blockNumber}, Timestamp: ${tx.timestamp}`)
+     * } catch (err) {
+     *   if (err instanceof CCIPTransactionNotFoundError && err.isTransient) {
+     *     // Transaction may be pending
+     *   }
+     * }
+     * ```
      */
     abstract getTransaction(hash: string): Promise<ChainTransaction>;
     /**
      * Confirm a log tx is finalized or wait for it to be finalized.
+     *
      * @param opts - Options containing the request, finality level, and optional cancel promise
      * @returns true when the transaction is finalized
+     *
      * @throws {@link CCIPTransactionNotFinalizedError} if the transaction is not included (e.g., due to a reorg)
+     *
+     * @example Wait for message finality
+     * ```typescript
+     * const request = await source.getMessagesInTx(txHash)
+     * try {
+     *   await source.waitFinalized({ request: request[0] })
+     *   console.log('Transaction finalized')
+     * } catch (err) {
+     *   if (err instanceof CCIPTransactionNotFinalizedError) {
+     *     console.log('Transaction not yet finalized')
+     *   }
+     * }
+     * ```
      */
     waitFinalized({ request: { log, tx }, finality, cancel$, }: {
         request: SetOptional<PickDeep<CCIPRequest, `log.${'address' | 'blockNumber' | 'transactionHash' | 'topics' | 'tx.timestamp'}` | 'tx.timestamp'>, 'tx'>;
@@ -307,12 +353,24 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
      * @throws {@link CCIPLogsWatchRequiresStartError} if watch mode is used without startBlock or startTime
      * @throws {@link CCIPLogsAddressRequiredError} if address is required but not provided (chain-specific)
      */
-    abstract getLogs(opts: LogFilter): AsyncIterableIterator<Log_>;
+    abstract getLogs(opts: LogFilter): AsyncIterableIterator<ChainLog>;
     /**
-     * Fetch all CCIP requests in a transaction
+     * Fetch all CCIP requests in a transaction.
+     *
      * @param tx - ChainTransaction or txHash to fetch requests from
-     * @returns CCIP messages in the transaction (at least one)
-     * @throws {@link CCIPMessageNotFoundInTxError} if no CCIP messages found in transaction
+     * @returns Promise resolving to CCIP messages in the transaction (at least one)
+     *
+     * @throws {@link CCIPTransactionNotFoundError} if transaction does not exist
+     * @throws {@link CCIPMessageNotFoundInTxError} if no CCIPSendRequested events in tx
+     *
+     * @example Get messages from transaction
+     * ```typescript
+     * const chain = await EVMChain.fromUrl('https://eth-mainnet.example.com')
+     * const requests = await chain.getMessagesInTx('0xabc123...')
+     * for (const req of requests) {
+     *   console.log(`Message ID: ${req.message.messageId}`)
+     * }
+     * ```
      */
     getMessagesInTx(tx: string | ChainTransaction): Promise<CCIPRequest[]>;
     /**
@@ -340,94 +398,183 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
      * @returns CCIPRequest with `metadata` populated from API
      * @throws {@link CCIPApiClientNotAvailableError} if API disabled
      * @throws {@link CCIPMessageIdNotFoundError} if message not found
+     * @throws {@link CCIPOnRampRequiredError} if onRamp is required but not provided
      * @throws {@link CCIPHttpError} if API request fails
-     **/
+     */
     getMessageById(messageId: string, _opts?: {
         page?: number;
         onRamp?: string;
     }): Promise<CCIPRequest>;
     /**
      * Fetches all CCIP messages contained in a given commit batch.
-     * @param request - CCIPRequest to fetch batch for.
-     * @param commit - CommitReport range (min, max).
-     * @param opts - Optional parameters (e.g., `page` for pagination width).
-     * @returns Array of messages in the batch.
+     * To be implemented for chains supporting CCIPVersion &lt;= v1.6.0
+     *
+     * @param request - CCIPRequest to fetch batch for
+     * @param range - batch range \{ minSeqnr, maxSeqNr \}, e.g. from [[CommitReport]]
+     * @param opts - Optional parameters (e.g., `page` for pagination width)
+     * @returns Array of messages in the batch
+     *
      * @throws {@link CCIPMessageBatchIncompleteError} if not all messages in range could be fetched
+     *
+     * @example Get all messages in a batch
+     * ```typescript
+     * const verifications = await dest.getVerifications({ offRamp, request })
+     * const messages = await source.getMessagesInBatch(request, verifications.report)
+     * console.log(`Found ${messages.length} messages in batch`)
+     * ```
      */
-    abstract getMessagesInBatch<R extends PickDeep<CCIPRequest, 'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.sequenceNumber'>>(request: R, commit: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>, opts?: {
+    getMessagesInBatch?<R extends PickDeep<CCIPRequest, 'lane' | `log.${'topics' | 'address' | 'blockNumber'}` | 'message.sequenceNumber'>>(request: R, range: Pick<CommitReport, 'minSeqNr' | 'maxSeqNr'>, opts?: {
         page?: number;
     }): Promise<R['message'][]>;
     /**
-     * Fetch typeAndVersion for a given CCIP contract address
+     * Fetch input data needed for executing messages
+     * Should be called on the *source* instance
+     * @param opts - getExecutionInput options containing request and verifications
+     * @returns `input` payload to be passed to [[execute]]
+     * @see {@link execute} - method to execute a message
+     */
+    getExecutionInput({ request, verifications, ...opts }: {
+        request: CCIPRequest;
+        verifications: CCIPVerifications;
+    } & Pick<LogFilter, 'page'>): Promise<ExecutionInput>;
+    /**
+     * Fetch typeAndVersion for a given CCIP contract address.
+     *
      * @param address - CCIP contract address
-     * @returns type - parsed type of the contract, e.g. `OnRamp`
-     * @returns version - parsed version of the contract, e.g. `1.6.0`
-     * @returns typeAndVersion - original (unparsed) typeAndVersion() string
-     * @returns suffix - suffix of the version, if any (e.g. `-dev`)
-     * @throws {@link CCIPTypeVersionInvalidError} if contract doesn't have valid typeAndVersion
+     * @returns Promise resolving to tuple:
+     *   - `type` - Parsed type of the contract, e.g. `OnRamp`
+     *   - `version` - Parsed version of the contract, e.g. `1.6.0`
+     *   - `typeAndVersion` - Original (unparsed) typeAndVersion() string
+     *   - `suffix` - Suffix of the version, if any (e.g. `-dev`)
+     *
+     * @throws {@link CCIPTypeVersionInvalidError} if typeAndVersion string cannot be parsed
+     *
+     * @example Check contract version
+     * ```typescript
+     * const [type, version] = await chain.typeAndVersion(contractAddress)
+     * console.log(`Contract: ${type} v${version}`)
+     * if (version < '1.6.0') {
+     *   console.log('Legacy contract detected')
+     * }
+     * ```
      */
     abstract typeAndVersion(address: string): Promise<[type: string, version: string, typeAndVersion: string, suffix?: string]>;
     /**
-     * Fetch the Router address set in OnRamp config
-     * Used to discover OffRamp connected to OnRamp
+     * Fetch the Router address set in OnRamp config.
+     * Used to discover OffRamp connected to OnRamp.
+     *
      * @param onRamp - OnRamp contract address
-     * @param destChainSelector - destination chain selector
-     * @returns Router address
+     * @param destChainSelector - Destination chain selector
+     * @returns Promise resolving to Router address
+     *
+     * @throws {@link CCIPContractTypeInvalidError} if address is not an OnRamp
+     *
+     * @example Get router from onRamp
+     * ```typescript
+     * const router = await chain.getRouterForOnRamp(onRampAddress, destSelector)
+     * console.log(`Router: ${router}`)
+     * ```
      */
     abstract getRouterForOnRamp(onRamp: string, destChainSelector: bigint): Promise<string>;
     /**
-     * Fetch the Router address set in OffRamp config
+     * Fetch the Router address set in OffRamp config.
+     *
      * @param offRamp - OffRamp contract address
-     * @param sourceChainSelector - source chain selector
-     * @returns Router address
+     * @param sourceChainSelector - Source chain selector
+     * @returns Promise resolving to Router address
+     *
+     * @throws {@link CCIPContractTypeInvalidError} if address is not an OffRamp
+     *
+     * @example Get router from offRamp
+     * ```typescript
+     * const router = await chain.getRouterForOffRamp(offRampAddress, sourceSelector)
+     * console.log(`Router: ${router}`)
+     * ```
      */
     abstract getRouterForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string>;
     /**
-     * Get the native token address for a Router
-     * @param router - router contract address
-     * @returns native token address (usually wrapped)
+     * Get the native token address for a Router.
+     *
+     * @param router - Router contract address
+     * @returns Promise resolving to native token address (usually wrapped)
+     *
+     * @example Get wrapped native token
+     * ```typescript
+     * const weth = await chain.getNativeTokenForRouter(routerAddress)
+     * console.log(`Wrapped native: ${weth}`)
+     * ```
      */
     abstract getNativeTokenForRouter(router: string): Promise<string>;
     /**
-     * Fetch the OffRamps allowlisted in a Router
-     * Used to discover OffRamp connected to an OnRamp
+     * Fetch the OffRamps allowlisted in a Router.
+     * Used to discover OffRamp connected to an OnRamp.
+     *
      * @param router - Router contract address
-     * @param sourceChainSelector - source chain selector
-     * @returns array of OffRamp addresses
+     * @param sourceChainSelector - Source chain selector
+     * @returns Promise resolving to array of OffRamp addresses
+     *
+     * @example Get offRamps for a source chain
+     * ```typescript
+     * const offRamps = await dest.getOffRampsForRouter(routerAddress, sourceSelector)
+     * console.log(`Found ${offRamps.length} offRamp(s)`)
+     * ```
      */
     abstract getOffRampsForRouter(router: string, sourceChainSelector: bigint): Promise<string[]>;
     /**
-     * Fetch the OnRamp registered in a Router for a destination chain
+     * Fetch the OnRamp registered in a Router for a destination chain.
+     *
      * @param router - Router contract address
-     * @param destChainSelector - destination chain selector
-     * @returns OnRamp addresses
+     * @param destChainSelector - Destination chain selector
+     * @returns Promise resolving to OnRamp address
+     *
+     * @throws {@link CCIPLaneNotFoundError} if no lane exists to destination
+     *
+     * @example Get onRamp for destination
+     * ```typescript
+     * const onRamp = await source.getOnRampForRouter(routerAddress, destSelector)
+     * console.log(`OnRamp: ${onRamp}`)
+     * ```
      */
     abstract getOnRampForRouter(router: string, destChainSelector: bigint): Promise<string>;
     /**
-     * Fetch the OnRamp address set in OffRamp config
-     * Used to discover OffRamp connected to an OnRamp
+     * Fetch the OnRamps addresses set in OffRamp config.
+     * Used to discover OffRamp connected to an OnRamp.
+     *
      * @param offRamp - OffRamp contract address
-     * @param sourceChainSelector - source chain selector
-     * @returns OnRamp address
-     */
-    abstract getOnRampForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string>;
-    /**
-     * 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 CommitStore address.
+     * @param sourceChainSelector - Source chain selector
+     * @returns Promise resolving to OnRamps addresses
+     *
+     * @example Get onRamp from offRamp config
+     * ```typescript
+     * const [onRamp] = await dest.getOnRampsForOffRamp(offRampAddress, sourceSelector)
+     * console.log(`OnRamp: ${onRamp}`)
+     * ```
      */
-    abstract getCommitStoreForOffRamp(offRamp: string): Promise<string>;
+    abstract getOnRampsForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string[]>;
     /**
-     * Fetch the TokenPool's token/mint
+     * Fetch the TokenPool's token/mint.
+     *
      * @param tokenPool - TokenPool address
-     * @returns Token or mint address
+     * @returns Promise resolving to token or mint address
+     *
+     * @example Get token for pool
+     * ```typescript
+     * const token = await chain.getTokenForTokenPool(tokenPoolAddress)
+     * console.log(`Token: ${token}`)
+     * ```
      */
     abstract getTokenForTokenPool(tokenPool: string): Promise<string>;
     /**
-     * Fetch token metadata
+     * Fetch token metadata.
+     *
      * @param token - Token address
-     * @returns Token symbol and decimals, and optionally name
+     * @returns Promise resolving to token symbol, decimals, and optionally name
+     *
+     * @example Get token info
+     * ```typescript
+     * const info = await chain.getTokenInfo(tokenAddress)
+     * console.log(`${info.symbol}: ${info.decimals} decimals`)
+     * ```
      */
     abstract getTokenInfo(token: string): Promise<TokenInfo>;
     /**
@@ -439,14 +586,14 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
      *
      * @example Query native token balance
      * ```typescript
-     * const balance = await chain.getBalance({ address: '0x123...' })
+     * const balance = await chain.getBalance({ holder: '0x123...' })
      * console.log(`Native balance: ${balance}`) // balance in wei
      * ```
      *
      * @example Query ERC20 token balance
      * ```typescript
      * const balance = await chain.getBalance({
-     *   address: '0x123...',
+     *   holder: '0x123...',
      *   token: '0xLINK...'
      * })
      * console.log(`LINK balance: ${balance}`) // balance in smallest units
@@ -454,22 +601,52 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
      */
     abstract getBalance(opts: GetBalanceOpts): Promise<bigint>;
     /**
-     * Fetch TokenAdminRegistry configured in a given OnRamp, Router, etc
-     * Needed to map a source token to its dest counterparts
-     * @param address - Some contract for which we can fetch a TokenAdminRegistry (OnRamp, Router, etc.)
-     * @returns TokenAdminRegistry address
+     * Fetch TokenAdminRegistry configured in a given OnRamp, Router, etc.
+     * Needed to map a source token to its dest counterparts.
+     *
+     * @param address - Contract address (OnRamp, Router, etc.)
+     * @returns Promise resolving to TokenAdminRegistry address
+     *
+     * @example Get token registry
+     * ```typescript
+     * const registry = await chain.getTokenAdminRegistryFor(onRampAddress)
+     * console.log(`Registry: ${registry}`)
+     * ```
      */
     abstract getTokenAdminRegistryFor(address: string): Promise<string>;
     /**
-     * Fetch the current fee for a given intended message
+     * Fetch the current fee for a given intended message.
+     *
      * @param opts - {@link SendMessageOpts} without approveMax
      * @returns Fee amount in the feeToken's smallest units
+     *
+     * @example Calculate message fee
+     * ```typescript
+     * const fee = await chain.getFee({
+     *   router: routerAddress,
+     *   destChainSelector: destSelector,
+     *   message: { receiver: '0x...', data: '0x' },
+     * })
+     * console.log(`Fee: ${fee} wei`)
+     * ```
      */
     abstract getFee(opts: Omit<SendMessageOpts, 'approveMax'>): Promise<bigint>;
     /**
-     * Generate unsigned txs for ccipSend'ing a message
+     * Generate unsigned txs for ccipSend'ing a message.
+     *
      * @param opts - {@link SendMessageOpts} with sender address
-     * @returns chain-family specific unsigned txs
+     * @returns Promise resolving to chain-family specific unsigned txs
+     *
+     * @example Generate unsigned transaction
+     * ```typescript
+     * const unsignedTx = await chain.generateUnsignedSendMessage({
+     *   router: routerAddress,
+     *   destChainSelector: destSelector,
+     *   message: { receiver: '0x...', data: '0x1337' },
+     *   sender: walletAddress,
+     * })
+     * // Sign and send with external wallet
+     * ```
      */
     abstract generateUnsignedSendMessage(opts: SendMessageOpts & {
         /** Sender address (address of wallet which will send the message) */
@@ -477,11 +654,14 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
     }): Promise<UnsignedTx[F]>;
     /**
      * Send a CCIP message through a router using provided wallet.
+     *
      * @param opts - {@link SendMessageOpts} with chain-specific wallet for signing
-     * @returns CCIP request
-     * @throws {@link CCIPWalletNotSignerError} if wallet cannot sign transactions
+     * @returns Promise resolving to CCIP request with message details
      *
-     * @example
+     * @throws {@link CCIPWalletNotSignerError} if wallet is not a valid signer
+     * @throws {@link CCIPLaneNotFoundError} if no lane exists to destination
+     *
+     * @example Send cross-chain message
      * ```typescript
      * const request = await chain.sendMessage({
      *   router: '0x...',
@@ -502,64 +682,86 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
         wallet: unknown;
     }): Promise<CCIPRequest>;
     /**
-     * Fetch supported offchain token data for a request from this network
-     * @param request - CCIP request, with tx, logs and message
-     * @returns array with one offchain token data for each token transfer in request
+     * Fetch supported offchain token data for a request from this network.
+     * It logs but doesn't throw in case it can't fetch attestation, as the transfers may not be
+     * from the expected attestation providers. It returns default offchainData=undefined for those.
+     *
+     * @param request - CCIP request, with tx.hash and message
+     * @returns Promise resolving to array with one offchain token data for each token transfer
+     *
+     * @example Get offchain token data for USDC transfer
+     * ```typescript
+     * const offchainData = await source.getOffchainTokenData(request)
+     * // Use in execution report
+     * ```
      */
-    abstract getOffchainTokenData(request: CCIPRequest): Promise<OffchainTokenData[]>;
+    getOffchainTokenData(request: PickDeep<CCIPRequest, 'tx.hash' | `message`>): Promise<OffchainTokenData[]>;
     /**
-     * Generate unsigned tx to manuallyExecute a message
-     * @param opts - {@link ExecuteReportOpts} with payer address which will send the exec tx
-     * @returns chain-family specific unsigned txs
+     * Generate unsigned tx to manuallyExecute a message.
+     *
+     * @param opts - {@link ExecuteOpts} with payer address which will send the exec tx
+     * @returns Promise resolving to chain-family specific unsigned txs
+     *
+     * @example Generate unsigned execution tx
+     * ```typescript
+     * const unsignedTx = await dest.generateUnsignedExecute({
+     *   offRamp: offRampAddress,
+     *   input,
+     *   payer: walletAddress,
+     * })
+     * // Sign and send with external wallet
+     * ```
      */
-    abstract generateUnsignedExecuteReport(opts: ExecuteReportOpts & {
+    abstract generateUnsignedExecute(opts: ExecuteOpts & {
         /** address which will be used to send the report tx */
         payer: string;
     }): Promise<UnsignedTx[F]>;
     /**
-     * Execute messages in report in an offRamp
-     * @param opts - {@link ExecuteReportOpts} with chain-specific wallet to sign and send tx
-     * @returns transaction of the execution
+     * Execute messages in report in an offRamp.
      *
-     * @example
+     * @param opts - {@link ExecuteOpts} with chain-specific wallet to sign and send tx
+     * @returns Promise resolving to transaction of the execution
+     *
+     * @throws {@link CCIPWalletNotSignerError} if wallet is not a valid signer
+     * @throws {@link CCIPExecTxRevertedError} if execution transaction reverts
+     * @throws {@link CCIPMerkleRootMismatchError} if merkle proof is invalid
+     *
+     * @example Manual execution of pending message
      * ```typescript
-     * const execReportProof = calculateManualExecProof(
-     *   messagesInBatch: await source.getMessagesInBatch(request, commit.report),
-     *   request.lane,
-     *   request.message.messageId,
-     *   commit.report.merkleRoot,
-     *   dest,
-     * )
-     * const receipt = await dest.executeReport({
-     *   offRamp,
-     *   execReport: {
-     *     ...execReportProof,
-     *     message: request.message,
-     *     offchainTokenData: await source.getOffchainTokenData(request),
-     *   },
-     *   wallet,
-     * })
-     * console.log(`Message ID: ${request.message.messageId}`)
+     * const input = await source.getExecutionInput({ request, verifications })
+     * const receipt = await dest.execute({ offRamp, input, wallet })
+     * console.log(`Executed: ${receipt.log.transactionHash}`)
      * ```
      * @throws {@link CCIPWalletNotSignerError} if wallet cannot sign transactions
      * @throws {@link CCIPExecTxNotConfirmedError} if execution transaction fails to confirm
      */
-    abstract executeReport(opts: ExecuteReportOpts & {
+    abstract execute(opts: ExecuteOpts & {
         wallet: unknown;
     }): Promise<CCIPExecution>;
     /**
-     * Look for a CommitReport at dest for given CCIP request
-     * May be specialized by some subclasses
-     * @param opts - getCommitReport options
-     * @returns CCIPCommit info
-     * @throws {@link CCIPCommitNotFoundError} if no commit found for the request
+     * Look for a CommitReport at dest for given CCIP request.
+     * May be specialized by some subclasses.
+     *
+     * @param opts - getVerifications options
+     * @returns CCIPVerifications
+     *
+     * @throws {@link CCIPCommitNotFoundError} if no commit found for the request (transient)
+     *
+     * @example Get commit for a request
+     * ```typescript
+     * const verifications = await dest.getVerifications({
+     *   offRamp: offRampAddress,
+     *   request,
+     * })
+     * console.log(`Committed at block: ${verifications.log.blockNumber}`)
+     * ```
      */
-    getCommitReport({ commitStore, request, ...hints }: {
-        /** address of commitStore (OffRamp in \>=v1.6) */
-        commitStore: string;
+    getVerifications({ offRamp, request, ...hints }: {
+        /** address of offRamp or commitStore contract */
+        offRamp: string;
         /** CCIPRequest subset object */
-        request: PickDeep<CCIPRequest, 'lane' | 'message.sequenceNumber' | 'tx.timestamp'>;
-    } & Pick<LogFilter, 'page' | 'watch' | 'startBlock'>): Promise<CCIPCommit>;
+        request: PickDeep<CCIPRequest, 'lane' | `message.${'sequenceNumber' | 'messageId'}` | 'tx.timestamp'>;
+    } & Pick<LogFilter, 'page' | 'watch' | 'startBlock'>): Promise<CCIPVerifications>;
     /**
      * Fetches estimated lane latency to a destination chain.
      * Uses this chain's selector as the source.
@@ -594,11 +796,25 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
      */
     getLaneLatency(destChainSelector: bigint): Promise<LaneLatencyResponse>;
     /**
-     * Default/generic implementation of getExecutionReceipts
+     * Default/generic implementation of getExecutionReceipts.
+     * Yields execution receipts for a given offRamp.
+     *
      * @param opts - getExecutionReceipts options
      * @returns Async generator of CCIPExecution receipts
+     *
+     * @example Watch for execution receipts
+     * ```typescript
+     * for await (const exec of dest.getExecutionReceipts({
+     *   offRamp: offRampAddress,
+     *   messageId: request.message.messageId,
+     *   startBlock: commit.log.blockNumber,
+     * })) {
+     *   console.log(`State: ${exec.receipt.state}`)
+     *   if (exec.receipt.state === ExecutionState.Success) break
+     * }
+     * ```
      */
-    getExecutionReceipts({ offRamp, messageId, sourceChainSelector, commit, ...hints }: {
+    getExecutionReceipts({ offRamp, messageId, sourceChainSelector, verifications, ...hints }: {
         /** address of OffRamp contract */
         offRamp: string;
         /** filter: yield only executions for this message */
@@ -606,21 +822,36 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
         /** filter: yield only executions for this source chain */
         sourceChainSelector?: bigint;
         /** optional commit associated with the request, can be used for optimizations in some families */
-        commit?: CCIPCommit;
+        verifications?: CCIPVerifications;
     } & Pick<LogFilter, 'page' | 'watch' | 'startBlock' | 'startTime'>): AsyncIterableIterator<CCIPExecution>;
     /**
      * Fetch first execution receipt inside a transaction.
+     *
      * @internal
-     * @param tx - transaction hash or transaction object
+     * @param tx - Transaction hash or transaction object
      * @returns CCIP execution object
+     *
      * @throws {@link CCIPExecTxRevertedError} if no execution receipt found in transaction
+     *
+     * @example Get receipt from execution tx
+     * ```typescript
+     * const exec = await dest.getExecutionReceiptInTx(execTxHash)
+     * console.log(`State: ${exec.receipt.state}`)
+     * ```
      */
     getExecutionReceiptInTx(tx: string | ChainTransaction): Promise<CCIPExecution>;
     /**
      * List tokens supported by given TokenAdminRegistry contract.
+     *
      * @param address - Usually TokenAdminRegistry, but chain may support receiving Router, OnRamp, etc.
-     * @param opts - Optional parameters (e.g., `page` for pagination range).
-     * @returns Array of supported token addresses.
+     * @param opts - Optional parameters (e.g., `page` for pagination range)
+     * @returns Promise resolving to array of supported token addresses
+     *
+     * @example Get all supported tokens
+     * ```typescript
+     * const tokens = await chain.getSupportedTokens(registryAddress)
+     * console.log(`${tokens.length} tokens supported`)
+     * ```
      */
     abstract getSupportedTokens(address: string, opts?: {
         page?: number;
@@ -651,21 +882,27 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
      * Fetch configuration of a token pool.
      *
      * @remarks
-     * Returns the core configuration of a token pool including which token it manages
-     * and which router it's registered with.
+     * Return type varies by chain:
+     * - **EVM**: `typeAndVersion` is always present (required)
+     * - **Solana**: Includes extra `tokenPoolProgram` field
+     * - **Aptos**: Standard fields only
+     * - **Sui/TON**: Throws {@link CCIPNotImplementedError}
      *
-     * @example Query pool configuration
+     * @example Type-safe access to chain-specific fields
      * ```typescript
-     * const config = await chain.getTokenPoolConfig(poolAddress)
-     * console.log(`Manages token: ${config.token}`)
-     * console.log(`Router: ${config.router}`)
-     * if (config.typeAndVersion) {
-     *   console.log(`Version: ${config.typeAndVersion}`)
+     * // Use instanceof to narrow the chain type
+     * if (chain instanceof SolanaChain) {
+     *   const config = await chain.getTokenPoolConfig(poolAddress)
+     *   console.log(config.tokenPoolProgram) // TypeScript knows this exists!
+     * } else if (chain instanceof EVMChain) {
+     *   const config = await chain.getTokenPoolConfig(poolAddress)
+     *   console.log(config.typeAndVersion) // TypeScript knows this is required!
      * }
      * ```
      *
      * @param tokenPool - Token pool contract address.
      * @returns {@link TokenPoolConfig} containing token, router, and version info.
+     * @throws {@link CCIPNotImplementedError} on Sui or TON chains
      */
     abstract getTokenPoolConfig(tokenPool: string): Promise<TokenPoolConfig>;
     /**
@@ -731,11 +968,26 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
     getTokenPoolRemote(tokenPool: string, remoteChainSelector: bigint): Promise<TokenPoolRemote>;
     /**
      * Fetch list and info of supported feeTokens.
-     * @param router - Router address on this chain.
-     * @returns Mapping of token addresses to respective TokenInfo objects.
+     *
+     * @param router - Router address on this chain
+     * @returns Promise resolving to mapping of token addresses to TokenInfo objects
+     *
+     * @example Get available fee tokens
+     * ```typescript
+     * const feeTokens = await chain.getFeeTokens(routerAddress)
+     * for (const [addr, info] of Object.entries(feeTokens)) {
+     *   console.log(`${info.symbol}: ${addr}`)
+     * }
+     * ```
      */
     abstract getFeeTokens(router: string): Promise<Record<string, TokenInfo>>;
-    /** {@inheritDoc ChainStatic.buildMessageForDest} */
+    /**
+     * Returns a copy of a message, populating missing fields like `extraArgs` with defaults.
+     * It's expected to return a message suitable at least for basic token transfers.
+     *
+     * @param message - AnyMessage (from source), containing at least `receiver`
+     * @returns A message suitable for `sendMessage` to this destination chain family
+     */
     static buildMessageForDest(message: Parameters<ChainStatic['buildMessageForDest']>[0]): AnyMessage;
     /**
      * Estimate `ccipReceive` execution cost (gas, computeUnits) for this *dest*
@@ -757,29 +1009,71 @@ export declare abstract class Chain<F extends ChainFamily = ChainFamily> {
         };
     }): Promise<number>;
 }
-/** Static methods and properties available on Chain class constructors. */
+/**
+ * Static methods and properties available on Chain class constructors.
+ *
+ * @example Using static methods
+ * ```typescript
+ * // Create chain from URL
+ * const chain = await EVMChain.fromUrl('https://eth-mainnet.example.com')
+ *
+ * // Decode message from log
+ * const message = EVMChain.decodeMessage(log)
+ *
+ * // Validate address format
+ * const normalized = EVMChain.getAddress('0xABC...')
+ * ```
+ */
 export type ChainStatic<F extends ChainFamily = ChainFamily> = Function & {
     readonly family: F;
     readonly decimals: number;
     /**
-     * async constructor: builds a Chain from a rpc endpoint url
-     * @param url - rpc endpoint url
-     * @param ctx - optional context with logger and API client configuration
+     * Async constructor: builds a Chain from an RPC endpoint URL.
+     *
+     * @param url - RPC endpoint URL
+     * @param ctx - Optional context with logger and API client configuration
+     * @returns Promise resolving to Chain instance
+     *
+     * @throws {@link CCIPChainNotFoundError} if chain cannot be identified
+     *
+     * @example Create chain from RPC
+     * ```typescript
+     * const chain = await EVMChain.fromUrl('https://eth-mainnet.example.com')
+     * console.log(`Connected to: ${chain.network.name}`)
+     * ```
      */
     fromUrl(url: string, ctx?: ChainContext): Promise<Chain<F>>;
     /**
-     * Try to decode a CCIP message *from* a log/event *originated* from this *source* chain,
-     * but which may *target* other dest chain families
-     * iow: the parsing is specific to this chain family, but content may be intended to alien chains
-     * e.g: EVM-born (abi.encoded) bytearray may output message.computeUnits for Solana
+     * Try to decode a CCIP message from a log/event originated from this source chain.
+     * The parsing is specific to this chain family, but content may target other chains.
+     *
      * @param log - Chain generic log
-     * @returns decoded CCIP message with merged extraArgs
+     * @returns Decoded CCIP message with merged extraArgs, or undefined if not a CCIP message
+     *
+     * @example Decode message from log
+     * ```typescript
+     * const message = EVMChain.decodeMessage(log)
+     * if (message) {
+     *   console.log(`Message ID: ${message.messageId}`)
+     * }
+     * ```
      */
-    decodeMessage(log: Pick<Log_, 'data'>): CCIPMessage | undefined;
+    decodeMessage(log: Pick<ChainLog, 'data'>): CCIPMessage | undefined;
     /**
-     * Try to decode an extraArgs array serialized for this chain family
-     * @param extraArgs - extra args bytes (Uint8Array, HexString or base64)
-     * @returns object containing decoded extraArgs and their tags
+     * Try to decode an extraArgs array serialized for this chain family.
+     *
+     * @param extraArgs - Extra args bytes (Uint8Array, HexString or base64)
+     * @returns Object containing decoded extraArgs and their tag, or undefined
+     *
+     * @throws {@link CCIPExtraArgsParseError} if bytes cannot be decoded
+     *
+     * @example Decode extra args
+     * ```typescript
+     * const decoded = EVMChain.decodeExtraArgs(message.extraArgs)
+     * if (decoded?._tag === 'EVMExtraArgsV2') {
+     *   console.log(`Gas limit: ${decoded.gasLimit}`)
+     * }
+     * ```
      */
     decodeExtraArgs(extraArgs: BytesLike): (EVMExtraArgsV1 & {
         _tag: 'EVMExtraArgsV1';
@@ -792,54 +1086,140 @@ export type ChainStatic<F extends ChainFamily = ChainFamily> = Function & {
     }) | (SuiExtraArgsV1 & {
         _tag: 'SuiExtraArgsV1';
     }) | undefined;
+    /**
+     * Encode extraArgs for this chain family.
+     *
+     * @param extraArgs - Extra args object to encode
+     * @returns Encoded hex string
+     *
+     * @example Encode extra args
+     * ```typescript
+     * const encoded = EVMChain.encodeExtraArgs({
+     *   gasLimit: 200000n,
+     *   strict: false,
+     * })
+     * ```
+     */
     encodeExtraArgs(extraArgs: ExtraArgs): string;
     /**
-     * Decode a commit (CommitReportAccepted) event
+     * Decode a commit (CommitReportAccepted) event.
+     *
      * @param log - Chain generic log
-     * @param lane - if passed, filter or validate reports by lane
-     * @returns Array of commit reports contained in the log
+     * @param lane - If passed, filter or validate reports by lane
+     * @returns Array of commit reports contained in the log, or undefined
+     *
+     * @example Decode commit from log
+     * ```typescript
+     * const commits = EVMChain.decodeCommits(log, lane)
+     * if (commits) {
+     *   console.log(`Found ${commits.length} commit(s)`)
+     * }
+     * ```
      */
-    decodeCommits(log: Pick<Log_, 'data'>, lane?: Lane): CommitReport[] | undefined;
+    decodeCommits(log: Pick<ChainLog, 'data'>, lane?: Lane): CommitReport[] | undefined;
     /**
-     * Decode a receipt (ExecutionStateChanged) event
+     * Decode a receipt (ExecutionStateChanged) event.
+     *
      * @param log - Chain generic log
      * @returns ExecutionReceipt or undefined if not a recognized receipt
+     *
+     * @example Decode execution receipt
+     * ```typescript
+     * const receipt = EVMChain.decodeReceipt(log)
+     * if (receipt) {
+     *   console.log(`State: ${receipt.state}, Message: ${receipt.messageId}`)
+     * }
+     * ```
      */
-    decodeReceipt(log: Pick<Log_, 'data'>): ExecutionReceipt | undefined;
+    decodeReceipt(log: Pick<ChainLog, 'data'>): ExecutionReceipt | undefined;
     /**
-     * Receive a bytes array and try to decode and normalize it as an address of this chain family
+     * Receive a bytes array and try to decode and normalize it as an address of this chain family.
+     *
      * @param bytes - Bytes array (Uint8Array, HexString or Base64)
      * @returns Address in this chain family's format
+     *
+     * @throws {@link CCIPAddressInvalidEvmError} if invalid EVM address
+     * @throws {@link CCIPDataFormatUnsupportedError} if invalid Aptos/Sui address
+     *
+     * @example Normalize address
+     * ```typescript
+     * const normalized = EVMChain.getAddress('0xABC123...')
+     * console.log(normalized) // checksummed address
+     * ```
      */
     getAddress(bytes: BytesLike): string;
     /**
-     * Validates a transaction hash format for this chain family
+     * Validates a transaction hash format for this chain family.
+     *
+     * @param v - Value to validate
+     * @returns True if value is a valid transaction hash format
+     *
+     * @example Validate transaction hash
+     * ```typescript
+     * if (EVMChain.isTxHash(userInput)) {
+     *   const tx = await chain.getTransaction(userInput)
+     * }
+     * ```
      */
     isTxHash(v: unknown): v is string;
     /**
      * Format an address for human-friendly display.
      * Defaults to getAddress if not overridden.
+     *
      * @param address - Address string in any recognized format
      * @returns Human-friendly address string for display
+     *
+     * @example Format address for display
+     * ```typescript
+     * const display = EVMChain.formatAddress?.(rawAddress) ?? rawAddress
+     * console.log(display)
+     * ```
      */
     formatAddress?(address: string): string;
     /**
      * Format a transaction hash for human-friendly display.
+     *
      * @param hash - Transaction hash string
      * @returns Human-friendly hash string for display
+     *
+     * @example Format tx hash for display
+     * ```typescript
+     * const display = EVMChain.formatTxHash?.(rawHash) ?? rawHash
+     * console.log(display)
+     * ```
      */
     formatTxHash?(hash: string): string;
     /**
-     * Create a leaf hasher for this dest chain and lane
-     * @param lane - source, dest and onramp lane info
-     * @param ctx - context object containing logger
-     * @returns LeafHasher is a function that takes a message and returns a hash of it
+     * Create a leaf hasher for this dest chain and lane.
+     *
+     * @param lane - Source, dest and onramp lane info
+     * @param ctx - Context object containing logger
+     * @returns LeafHasher function that takes a message and returns its hash
+     *
+     * @throws {@link CCIPHasherVersionUnsupportedError} if hasher version unsupported
+     *
+     * @example Create leaf hasher
+     * ```typescript
+     * const hasher = EVMChain.getDestLeafHasher(lane, { logger })
+     * const leafHash = hasher(message)
+     * ```
      */
     getDestLeafHasher(lane: Lane, ctx?: WithLogger): LeafHasher;
     /**
-     * Try to parse an error or bytearray generated by this chain family
+     * Try to parse an error or bytearray generated by this chain family.
+     *
      * @param data - Caught object, string or bytearray
-     * @returns Ordered record with messages/properties, or undefined if not a recognized error
+     * @returns Ordered record with messages/properties, or undefined/null if not recognized
+     *
+     * @example Parse contract error
+     * ```typescript
+     * try {
+     *   await chain.sendMessage(opts)
+     * } catch (err) {
+     *   const parsed = EVMChain.parse?.(err)
+     *   if (parsed) console.log('Contract error:', parsed)
+     * }
+     * ```
      */
     parse?(data: unknown): Record<string, unknown> | undefined | null;
     /**