@chainlink/ccip-sdk 0.96.0 → 1.0.0

package/dist/errors/specialized.d.ts

@@ -1,59 +1,205 @@
 import { type CCIPErrorOptions, CCIPError } from './CCIPError.ts';
-/** Thrown when chain not found by chainId, selector, or name. */
+/**
+ * Thrown when chain not found by chainId, selector, or name.
+ *
+ * @example
+ * ```typescript
+ * import { networkInfo } from '@chainlink/ccip-sdk'
+ *
+ * try {
+ *   const info = networkInfo(999999) // Unknown chain
+ * } catch (error) {
+ *   if (error instanceof CCIPChainNotFoundError) {
+ *     console.log(`Chain not found: ${error.context.chainIdOrSelector}`)
+ *     console.log(`Recovery: ${error.recovery}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPChainNotFoundError extends CCIPError {
     readonly name = "CCIPChainNotFoundError";
     /** Creates a chain not found error. */
     constructor(chainIdOrSelector: string | number | bigint, options?: CCIPErrorOptions);
 }
-/** Thrown when chain family is not supported. */
+/**
+ * Thrown when chain family is not supported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const chain = await createChain('unsupported-family')
+ * } catch (error) {
+ *   if (error instanceof CCIPChainFamilyUnsupportedError) {
+ *     console.log(`Unsupported family: ${error.context.family}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPChainFamilyUnsupportedError extends CCIPError {
     readonly name = "CCIPChainFamilyUnsupportedError";
     /** Creates a chain family unsupported error. */
     constructor(family: string, options?: CCIPErrorOptions);
 }
-/** Thrown when some method/operation is not supported on a given implementation class. */
+/**
+ * Thrown when a method or operation is not supported on a given implementation class.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.someUnsupportedMethod()
+ * } catch (error) {
+ *   if (error instanceof CCIPMethodUnsupportedError) {
+ *     console.log(`Method not supported: ${error.context.class}.${error.context.method}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMethodUnsupportedError extends CCIPError {
     readonly name = "CCIPMethodUnsupportedError";
     /** Creates a method unsupported error. */
     constructor(klass: string, method: string, options?: CCIPErrorOptions);
 }
-/** Thrown when block not found. Transient: block may not be indexed yet. */
+/**
+ * Thrown when block not found. Transient: block may not be indexed yet.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const timestamp = await chain.getBlockTimestamp(999999999)
+ * } catch (error) {
+ *   if (error instanceof CCIPBlockNotFoundError) {
+ *     if (error.isTransient) {
+ *       console.log(`Block not indexed yet, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPBlockNotFoundError extends CCIPError {
     readonly name = "CCIPBlockNotFoundError";
     /** Creates a block not found error. */
     constructor(block: number | bigint | string, options?: CCIPErrorOptions);
 }
-/** Thrown when transaction not found. Transient: tx may be pending. */
+/**
+ * Thrown when transaction not found. Transient: tx may be pending.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tx = await chain.getTransaction('0x1234...')
+ * } catch (error) {
+ *   if (error instanceof CCIPTransactionNotFoundError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 5000)
+ *       // Retry the operation
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTransactionNotFoundError extends CCIPError {
     readonly name = "CCIPTransactionNotFoundError";
     /** Creates a transaction not found error. */
     constructor(hash: string, options?: CCIPErrorOptions);
 }
-/** Thrown when message format is invalid. */
+/**
+ * Thrown when message format is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = EVMChain.decodeMessage(invalidLog)
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageInvalidError) {
+ *     console.log(`Invalid message format: ${error.message}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageInvalidError extends CCIPError {
     readonly name = "CCIPMessageInvalidError";
     /** Creates a message invalid error. */
     constructor(data: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when no CCIPSendRequested event in tx. Transient: tx may not be indexed. */
+/**
+ * Thrown when no CCIPSendRequested event in tx. Transient: tx may not be indexed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const messages = await chain.getMessagesInTx('0x1234...')
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageNotFoundInTxError) {
+ *     if (error.isTransient) {
+ *       console.log(`Message not indexed yet, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageNotFoundInTxError extends CCIPError {
     readonly name = "CCIPMessageNotFoundInTxError";
     /** Creates a message not found in transaction error. */
     constructor(txHash: string, options?: CCIPErrorOptions);
 }
-/** Thrown when message with messageId not found. Transient: message may be in transit. */
+/**
+ * Thrown when message with messageId not found. Transient: message may be in transit.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const request = await getMessageById(chain, messageId, onRamp)
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageIdNotFoundError) {
+ *     if (error.isTransient) {
+ *       console.log(`Message in transit, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageIdNotFoundError extends CCIPError {
     readonly name = "CCIPMessageIdNotFoundError";
     /** Creates a message ID not found error. */
     constructor(messageId: string, options?: CCIPErrorOptions);
 }
-/** Thrown when messageId format is invalid. */
+/**
+ * Thrown when messageId format is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const request = await chain.getMessageById('invalid-format')
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageIdValidationError) {
+ *     console.log(`Invalid messageId: ${error.message}`)
+ *     // Not transient - fix the messageId format
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageIdValidationError extends CCIPError {
     readonly name = "CCIPMessageIdValidationError";
     /** Creates a message ID validation error. */
     constructor(message: string, options?: CCIPErrorOptions);
 }
-/** Thrown when not all messages in batch were found. Transient: may still be indexing. */
+/**
+ * Thrown when not all messages in batch were found. Transient: may still be indexing.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const messages = await getMessagesInBatch(chain, request, commit)
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageBatchIncompleteError) {
+ *     console.log(`Found ${error.context.foundSeqNums.length} of expected range`)
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 30000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageBatchIncompleteError extends CCIPError {
     readonly name = "CCIPMessageBatchIncompleteError";
     /** Creates a message batch incomplete error. */
@@ -62,7 +208,20 @@ export declare class CCIPMessageBatchIncompleteError extends CCIPError {
         max: bigint;
     }, foundSeqNums: bigint[], options?: CCIPErrorOptions);
 }
-/** Thrown when message not in expected batch. */
+/**
+ * Thrown when message not in expected batch.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const proof = calculateManualExecProof(messages, lane, messageId)
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageNotInBatchError) {
+ *     console.log(`Message ${error.context.messageId} not in batch range`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageNotInBatchError extends CCIPError {
     readonly name = "CCIPMessageNotInBatchError";
     /** Creates a message not in batch error. */
@@ -71,61 +230,195 @@ export declare class CCIPMessageNotInBatchError extends CCIPError {
         max: bigint;
     }, options?: CCIPErrorOptions);
 }
-/** Thrown when message retrieval fails via both API and RPC. */
+/**
+ * Thrown when message retrieval fails via both API and RPC.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const request = await chain.getMessageById('0xabc123...')
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageRetrievalError) {
+ *     console.log(`Failed to retrieve message: ${error.message}`)
+ *     console.log(`Recovery: ${error.recovery}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageRetrievalError extends CCIPError {
     readonly name = "CCIPMessageRetrievalError";
     /** Creates a message retrieval error with both API and RPC failure context. */
     constructor(messageId: string, apiError: CCIPError | undefined, rpcError: CCIPError | undefined, options?: CCIPErrorOptions);
 }
-/** Thrown when no offRamp found for lane. */
+/**
+ * Thrown when no offRamp found for lane.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const offRamp = await discoverOffRamp(source, dest, request)
+ * } catch (error) {
+ *   if (error instanceof CCIPOffRampNotFoundError) {
+ *     console.log(`No offRamp for ${error.context.onRamp} on ${error.context.destNetwork}`)
+ *     console.log(`Recovery: ${error.recovery}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPOffRampNotFoundError extends CCIPError {
     readonly name = "CCIPOffRampNotFoundError";
     /** Creates an offRamp not found error. */
     constructor(onRamp: string, destNetwork: string, options?: CCIPErrorOptions);
 }
-/** Thrown when onRamp required but not provided. */
+/**
+ * Thrown when onRamp required but not provided.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const lane = await chain.getLaneForOnRamp(undefined)
+ * } catch (error) {
+ *   if (error instanceof CCIPOnRampRequiredError) {
+ *     console.log('onRamp address is required for this operation')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPOnRampRequiredError extends CCIPError {
     readonly name = "CCIPOnRampRequiredError";
     /** Creates an onRamp required error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when lane not found between source and destination chains. */
+/**
+ * Thrown when lane not found between source and destination chains.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const lane = await discoverLane(sourceChainSelector, destChainSelector)
+ * } catch (error) {
+ *   if (error instanceof CCIPLaneNotFoundError) {
+ *     console.log(`No lane: ${error.context.sourceChainSelector} → ${error.context.destChainSelector}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLaneNotFoundError extends CCIPError {
     readonly name = "CCIPLaneNotFoundError";
     /** Creates a lane not found error. */
     constructor(sourceChainSelector: bigint, destChainSelector: bigint, options?: CCIPErrorOptions);
 }
-/** Thrown when commit report not found. Transient: DON may not have committed yet. */
+/**
+ * Thrown when commit report not found. Transient: DON may not have committed yet.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const verifications = await chain.getVerifications({ offRamp, request })
+ * } catch (error) {
+ *   if (error instanceof CCIPCommitNotFoundError) {
+ *     if (error.isTransient) {
+ *       console.log(`Commit pending, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPCommitNotFoundError extends CCIPError {
     readonly name = "CCIPCommitNotFoundError";
     /** Creates a commit not found error. */
     constructor(startBlock: number | string, sequenceNumber: bigint, options?: CCIPErrorOptions);
 }
-/** Thrown when merkle root verification fails. */
+/**
+ * Thrown when merkle root verification fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const proof = calculateManualExecProof(messages, lane, messageId, merkleRoot)
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleRootMismatchError) {
+ *     console.log(`Root mismatch: expected=${error.context.expected}, got=${error.context.got}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleRootMismatchError extends CCIPError {
     readonly name = "CCIPMerkleRootMismatchError";
     /** Creates a merkle root mismatch error. */
     constructor(expected: string, got: string, options?: CCIPErrorOptions);
 }
-/** Thrown when attempting to create tree without leaves. */
+/**
+ * Thrown when attempting to create tree without leaves.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const root = createMerkleTree([])
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleTreeEmptyError) {
+ *     console.log('Cannot create merkle tree without messages')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleTreeEmptyError extends CCIPError {
     readonly name = "CCIPMerkleTreeEmptyError";
     /** Creates a merkle tree empty error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when CCIP version not supported. */
+/**
+ * Thrown when CCIP version not supported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const [type, version] = await chain.typeAndVersion(contractAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPVersionUnsupportedError) {
+ *     console.log(`Version ${error.context.version} not supported`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPVersionUnsupportedError extends CCIPError {
     readonly name = "CCIPVersionUnsupportedError";
     /** Creates a version unsupported error. */
     constructor(version: string, options?: CCIPErrorOptions);
 }
-/** Thrown when hasher version not supported for chain. */
+/**
+ * Thrown when hasher version not supported for chain.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const hasher = getLeafHasher(lane)
+ * } catch (error) {
+ *   if (error instanceof CCIPHasherVersionUnsupportedError) {
+ *     console.log(`Hasher not available for ${error.context.chain} v${error.context.version}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPHasherVersionUnsupportedError extends CCIPError {
     readonly name = "CCIPHasherVersionUnsupportedError";
     /** Creates a hasher version unsupported error. */
     constructor(chain: string, version: string, options?: CCIPErrorOptions);
 }
-/** Thrown when extraArgs cannot be parsed. */
+/**
+ * Thrown when extraArgs cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const args = decodeExtraArgs(invalidData)
+ * } catch (error) {
+ *   if (error instanceof CCIPExtraArgsParseError) {
+ *     console.log(`Cannot parse extraArgs: ${error.context.from}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPExtraArgsParseError extends CCIPError {
     readonly name = "CCIPExtraArgsParseError";
     /** Creates an extraArgs parse error. */
@@ -136,439 +429,1475 @@ export declare class CCIPExtraArgsParseError extends CCIPError {
  *
  * @param chainFamily - Display name for the chain family (user-facing, differs from ChainFamily enum)
  * @param extraArgs - The actual invalid extraArgs value (for debugging)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const encoded = encodeExtraArgs({ gasLimit: -1n }, 'EVM')
+ * } catch (error) {
+ *   if (error instanceof CCIPExtraArgsInvalidError) {
+ *     console.log(`Invalid extraArgs for ${error.context.chainFamily}`)
+ *   }
+ * }
+ * ```
  */
 export declare class CCIPExtraArgsInvalidError extends CCIPError {
     readonly name = "CCIPExtraArgsInvalidError";
     /** Creates an extraArgs invalid error. */
     constructor(chainFamily: 'EVM' | 'SVM' | 'Sui' | 'Aptos' | 'TON', extraArgs?: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token not found in registry. */
+/**
+ * Thrown when token not found in registry.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const config = await chain.getRegistryTokenConfig(registry, tokenAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenNotInRegistryError) {
+ *     console.log(`Token ${error.context.token} not in ${error.context.registry}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenNotInRegistryError extends CCIPError {
     readonly name = "CCIPTokenNotInRegistryError";
     /** Creates a token not in registry error. */
     constructor(token: string, registry: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token not configured in registry. */
+/**
+ * Thrown when token not configured in registry.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const pool = await chain.getTokenPoolConfigs(tokenPool)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenNotConfiguredError) {
+ *     console.log(`Token ${error.context.token} not configured`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenNotConfiguredError extends CCIPError {
     readonly name = "CCIPTokenNotConfiguredError";
     /** Creates a token not configured error. */
     constructor(token: string, registry: string, options?: CCIPErrorOptions);
 }
-/** Thrown when destination token decimals insufficient. */
+/**
+ * Thrown when destination token decimals insufficient.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const amounts = await sourceToDestTokenAmounts(source, dest, tokenAmounts)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenDecimalsInsufficientError) {
+ *     console.log(`Cannot express ${error.context.amount} with ${error.context.destDecimals} decimals`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenDecimalsInsufficientError extends CCIPError {
     readonly name = "CCIPTokenDecimalsInsufficientError";
     /** Creates a token decimals insufficient error. */
     constructor(token: string, destDecimals: number, destChain: string, amount: string, options?: CCIPErrorOptions);
 }
-/** Thrown when contract type is not as expected. */
+/**
+ * Thrown when contract type is not as expected.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const router = await chain.getRouterForOnRamp(address)
+ * } catch (error) {
+ *   if (error instanceof CCIPContractTypeInvalidError) {
+ *     console.log(`${error.context.address} is "${error.context.actualType}", expected ${error.context.expectedTypes}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPContractTypeInvalidError extends CCIPError {
     readonly name = "CCIPContractTypeInvalidError";
     /** Creates a contract type invalid error. */
     constructor(address: string, actualType: string, expectedTypes: string[], options?: CCIPErrorOptions);
 }
-/** Thrown when wallet must be Signer but isn't. */
+/**
+ * Thrown when wallet must be Signer but isn't.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.sendMessage({ ...opts, wallet: provider })
+ * } catch (error) {
+ *   if (error instanceof CCIPWalletNotSignerError) {
+ *     console.log('Wallet must be a Signer to send transactions')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPWalletNotSignerError extends CCIPError {
     readonly name = "CCIPWalletNotSignerError";
     /** Creates a wallet not signer error. */
     constructor(wallet: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when exec tx not confirmed. Transient: may need more time. */
+/**
+ * Thrown when exec tx not confirmed. Transient: may need more time.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.execute({ offRamp, input, wallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPExecTxNotConfirmedError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 5000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPExecTxNotConfirmedError extends CCIPError {
     readonly name = "CCIPExecTxNotConfirmedError";
     /** Creates an exec transaction not confirmed error. */
     constructor(txHash: string, options?: CCIPErrorOptions);
 }
-/** Thrown when exec tx reverted. */
+/**
+ * Thrown when exec tx reverted.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.execute({ offRamp, input, wallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPExecTxRevertedError) {
+ *     console.log(`Execution reverted: ${error.context.txHash}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPExecTxRevertedError extends CCIPError {
     readonly name = "CCIPExecTxRevertedError";
     /** Creates an exec transaction reverted error. */
     constructor(txHash: string, options?: CCIPErrorOptions);
 }
-/** Thrown when USDC attestation fetch fails. Transient: attestation may not be ready. */
+/**
+ * Thrown when USDC attestation fetch fails. Transient: attestation may not be ready.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const offchainData = await chain.getOffchainTokenData(request)
+ * } catch (error) {
+ *   if (error instanceof CCIPUsdcAttestationError) {
+ *     if (error.isTransient) {
+ *       console.log(`USDC attestation pending, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPUsdcAttestationError extends CCIPError {
     readonly name = "CCIPUsdcAttestationError";
     /** Creates a USDC attestation error. */
     constructor(messageHash: string, response: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when LBTC attestation fetch fails. Transient: attestation may not be ready. */
+/**
+ * Thrown when LBTC attestation fetch fails. Transient: attestation may not be ready.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const offchainData = await chain.getOffchainTokenData(request)
+ * } catch (error) {
+ *   if (error instanceof CCIPLbtcAttestationError) {
+ *     if (error.isTransient) {
+ *       console.log(`LBTC attestation pending, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLbtcAttestationError extends CCIPError {
     readonly name = "CCIPLbtcAttestationError";
     /** Creates an LBTC attestation error. */
     constructor(response: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when LBTC attestation not found for payload hash. Transient: may not be processed yet. */
+/**
+ * Thrown when LBTC attestation not found for payload hash. Transient: may not be processed yet.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const offchainData = await chain.getOffchainTokenData(request)
+ * } catch (error) {
+ *   if (error instanceof CCIPLbtcAttestationNotFoundError) {
+ *     console.log(`Attestation not found for hash: ${error.context.payloadHash}`)
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 30000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLbtcAttestationNotFoundError extends CCIPError {
     readonly name = "CCIPLbtcAttestationNotFoundError";
     /** Creates an LBTC attestation not found error. */
     constructor(payloadHash: string, response: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when LBTC attestation is not yet approved. Transient: may be pending notarization. */
+/**
+ * Thrown when LBTC attestation is not yet approved. Transient: may be pending notarization.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const offchainData = await chain.getOffchainTokenData(request)
+ * } catch (error) {
+ *   if (error instanceof CCIPLbtcAttestationNotApprovedError) {
+ *     console.log(`Attestation pending approval for: ${error.context.payloadHash}`)
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 30000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLbtcAttestationNotApprovedError extends CCIPError {
     readonly name = "CCIPLbtcAttestationNotApprovedError";
     /** Creates an LBTC attestation not approved error. */
     constructor(payloadHash: string, attestation: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when lookup table not found. Transient: may not be synced yet. */
+/**
+ * Thrown when lookup table not found. Transient: may not be synced yet.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const lookupTable = await solanaChain.getLookupTable(address)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaLookupTableNotFoundError) {
+ *     if (error.isTransient) {
+ *       console.log(`Lookup table not synced, retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaLookupTableNotFoundError extends CCIPError {
     readonly name = "CCIPSolanaLookupTableNotFoundError";
     /** Creates a Solana lookup table not found error. */
     constructor(address: string, options?: CCIPErrorOptions);
 }
-/** Thrown for invalid Aptos transaction hash or version. */
+/**
+ * Thrown for invalid Aptos transaction hash or version.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tx = await aptosChain.getTransaction('invalid-hash')
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosTransactionInvalidError) {
+ *     console.log(`Invalid tx: ${error.context.hashOrVersion}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosTransactionInvalidError extends CCIPError {
     readonly name = "CCIPAptosTransactionInvalidError";
     /** Creates an Aptos transaction invalid error. */
     constructor(hashOrVersion: string | number, options?: CCIPErrorOptions);
 }
-/** Thrown for HTTP errors. Transient if 429 or 5xx. */
+/**
+ * Thrown for HTTP errors. Transient if 429 or 5xx.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const latency = await chain.getLaneLatency(destChainSelector)
+ * } catch (error) {
+ *   if (error instanceof CCIPHttpError) {
+ *     console.log(`HTTP ${error.context.status}: ${error.context.statusText}`)
+ *     if (error.isTransient) {
+ *       // 429 or 5xx - safe to retry
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPHttpError extends CCIPError {
     readonly name = "CCIPHttpError";
     /** Creates an HTTP error. */
     constructor(status: number, statusText: string, options?: CCIPErrorOptions);
 }
-/** Thrown when a request times out. Transient: network may recover. */
+/**
+ * Thrown when a request times out. Transient: network may recover.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tx = await chain.getTransaction('0x1234...')
+ * } catch (error) {
+ *   if (error instanceof CCIPTimeoutError) {
+ *     console.log(`Operation timed out: ${error.context.operation}`)
+ *     if (error.isTransient) {
+ *       console.log(`Retry in ${error.retryAfterMs}ms`)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTimeoutError extends CCIPError {
     readonly name = "CCIPTimeoutError";
     /** Creates a timeout error. */
     constructor(operation: string, timeoutMs: number, options?: CCIPErrorOptions);
 }
-/** Thrown for not implemented features. */
+/**
+ * Thrown for not implemented features.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.someUnimplementedMethod()
+ * } catch (error) {
+ *   if (error instanceof CCIPNotImplementedError) {
+ *     console.log(`Feature not implemented: ${error.context.feature}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPNotImplementedError extends CCIPError {
     readonly name = "CCIPNotImplementedError";
     /** Creates a not implemented error. */
     constructor(feature?: string, options?: CCIPErrorOptions);
 }
-/** Thrown when data format is not supported. */
+/**
+ * Thrown when data format is not supported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const parsed = parseData(unknownFormat)
+ * } catch (error) {
+ *   if (error instanceof CCIPDataFormatUnsupportedError) {
+ *     console.log(`Unsupported format: ${error.context.data}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPDataFormatUnsupportedError extends CCIPError {
     readonly name = "CCIPDataFormatUnsupportedError";
     /** Creates a data format unsupported error. */
     constructor(data: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when typeAndVersion string cannot be parsed. */
+/**
+ * Thrown when typeAndVersion string cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const [type, version] = await chain.typeAndVersion(contractAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPTypeVersionInvalidError) {
+ *     console.log(`Cannot parse: ${error.context.typeAndVersion}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTypeVersionInvalidError extends CCIPError {
     readonly name = "CCIPTypeVersionInvalidError";
     /** Creates a type version invalid error. */
     constructor(typeAndVersion: string, options?: CCIPErrorOptions);
 }
-/** Thrown when no block found before timestamp. */
+/**
+ * Thrown when no block found before timestamp.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const block = await chain.getBlockBeforeTimestamp(timestamp)
+ * } catch (error) {
+ *   if (error instanceof CCIPBlockBeforeTimestampNotFoundError) {
+ *     console.log(`No block before timestamp: ${error.context.timestamp}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPBlockBeforeTimestampNotFoundError extends CCIPError {
     readonly name = "CCIPBlockBeforeTimestampNotFoundError";
     /** Creates a block before timestamp not found error. */
     constructor(timestamp: number, options?: CCIPErrorOptions);
 }
-/** Thrown when message decoding fails. */
+/**
+ * Thrown when message decoding fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = EVMChain.decodeMessage(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPMessageDecodeError) {
+ *     console.log(`Decode failed: ${error.context.reason}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMessageDecodeError extends CCIPError {
     readonly name = "CCIPMessageDecodeError";
     /** Creates a message decode error. */
     constructor(reason?: string, options?: CCIPErrorOptions);
 }
-/** Thrown when RPC endpoint not found. */
+/**
+ * Thrown when network family is not supported for an operation.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const chain = await Chain.fromUrl(rpcUrl)
+ * } catch (error) {
+ *   if (error instanceof CCIPNetworkFamilyUnsupportedError) {
+ *     console.log(`Unsupported family: ${error.context.family}`)
+ *   }
+ * }
+ * ```
+ */
+export declare class CCIPNetworkFamilyUnsupportedError extends CCIPError {
+    readonly name = "CCIPNetworkFamilyUnsupportedError";
+    /** Creates a network family unsupported error. */
+    constructor(family: string, options?: CCIPErrorOptions);
+}
+/**
+ * Thrown when RPC endpoint not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const chain = await EVMChain.fromUrl(rpcUrl)
+ * } catch (error) {
+ *   if (error instanceof CCIPRpcNotFoundError) {
+ *     console.log(`No RPC for chainId: ${error.context.chainId}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPRpcNotFoundError extends CCIPError {
     readonly name = "CCIPRpcNotFoundError";
     /** Creates an RPC not found error. */
     constructor(chainId: string | number, options?: CCIPErrorOptions);
 }
-/** Thrown when logs not found for filter criteria. */
+/**
+ * Thrown when logs not found for filter criteria. Transient: logs may not be indexed yet.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const logs = await chain.getLogs(filter)
+ * } catch (error) {
+ *   if (error instanceof CCIPLogsNotFoundError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 5000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogsNotFoundError extends CCIPError {
     readonly name = "CCIPLogsNotFoundError";
     /** Creates a logs not found error. */
     constructor(filter?: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when log topics not found. */
+/**
+ * Thrown when log topics not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const logs = await chain.getLogs({ topics: ['0xunknown'] })
+ * } catch (error) {
+ *   if (error instanceof CCIPLogTopicsNotFoundError) {
+ *     console.log(`Topics not matched: ${error.context.topics}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogTopicsNotFoundError extends CCIPError {
     readonly name = "CCIPLogTopicsNotFoundError";
     /** Creates a log topics not found error. */
     constructor(topics: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when trying to `watch` logs but giving a fixed `endBlock` */
+/**
+ * Thrown when trying to `watch` logs but giving a fixed `endBlock`.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.watchLogs({ endBlock: 1000 }) // Fixed endBlock not allowed
+ * } catch (error) {
+ *   if (error instanceof CCIPLogsWatchRequiresFinalityError) {
+ *     console.log('Use "latest" or "finalized" for endBlock in watch mode')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogsWatchRequiresFinalityError extends CCIPError {
     readonly name = "CCIPLogsWatchRequiresFinalityError";
-    /** Creates a watch requires finality error. */
+    /** Creates a logs watch requires finality error. */
     constructor(endBlock?: number | string, options?: CCIPErrorOptions);
 }
-/** Thrown when trying to `watch` logs without a start point. */
+/**
+ * Thrown when trying to `watch` logs but no start position provided.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.watchLogs({}) // Missing startBlock or startTime
+ * } catch (error) {
+ *   if (error instanceof CCIPLogsWatchRequiresStartError) {
+ *     console.log('Provide startBlock or startTime for watch mode')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogsWatchRequiresStartError extends CCIPError {
     readonly name = "CCIPLogsWatchRequiresStartError";
-    /** Creates a watch requires start error. */
+    /** Creates a logs watch requires start error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when address is required for logs filtering, but not provided. */
+/**
+ * Thrown when address is required for logs filtering, but not provided.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getLogs({ topics: [...] }) // Missing address
+ * } catch (error) {
+ *   if (error instanceof CCIPLogsAddressRequiredError) {
+ *     console.log('Contract address is required for this chain')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogsAddressRequiredError extends CCIPError {
     readonly name = "CCIPLogsAddressRequiredError";
     /** Creates a Solana program address required error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when network family does not match expected for a Chain constructor. */
+/**
+ * Thrown when network family does not match expected for a Chain constructor.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const chain = new EVMChain(provider, solanaNetworkInfo) // Wrong family
+ * } catch (error) {
+ *   if (error instanceof CCIPChainFamilyMismatchError) {
+ *     console.log(`Expected ${error.context.expected}, got ${error.context.actual}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPChainFamilyMismatchError extends CCIPError {
     readonly name = "CCIPChainFamilyMismatchError";
     /** Creates a chain family mismatch error. */
     constructor(chainName: string, expected: string, actual: string, options?: CCIPErrorOptions);
 }
-/** Thrown when merkle proof is empty. */
+/**
+ * Thrown when legacy (pre-1.5) token pools are not supported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getTokenPoolConfigs(legacyPool)
+ * } catch (error) {
+ *   if (error instanceof CCIPLegacyTokenPoolsUnsupportedError) {
+ *     console.log('Upgrade to CCIP v1.5+ token pools')
+ *   }
+ * }
+ * ```
+ */
+export declare class CCIPLegacyTokenPoolsUnsupportedError extends CCIPError {
+    readonly name = "CCIPLegacyTokenPoolsUnsupportedError";
+    /** Creates a legacy token pools unsupported error. */
+    constructor(options?: CCIPErrorOptions);
+}
+/**
+ * Thrown when merkle proof is empty.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   verifyMerkleProof({ leaves: [], proofs: [] })
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleProofEmptyError) {
+ *     console.log('Cannot verify empty merkle proof')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleProofEmptyError extends CCIPError {
     readonly name = "CCIPMerkleProofEmptyError";
     /** Creates a merkle proof empty error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when merkle leaves or proofs exceed max limit. */
+/**
+ * Thrown when merkle leaves or proofs exceed max limit.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   verifyMerkleProof({ leaves: largeArray, proofs })
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleProofTooLargeError) {
+ *     console.log(`Proof exceeds limit: ${error.context.limit}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleProofTooLargeError extends CCIPError {
     readonly name = "CCIPMerkleProofTooLargeError";
     /** Creates a merkle proof too large error. */
     constructor(limit: number, options?: CCIPErrorOptions);
 }
-/** Thrown when total hashes exceed max merkle tree size. */
+/**
+ * Thrown when total hashes exceed max merkle tree size.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   createMerkleTree(hashes)
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleHashesTooLargeError) {
+ *     console.log(`${error.context.totalHashes} exceeds limit ${error.context.limit}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleHashesTooLargeError extends CCIPError {
     readonly name = "CCIPMerkleHashesTooLargeError";
     /** Creates a merkle hashes too large error. */
     constructor(totalHashes: number, limit: number, options?: CCIPErrorOptions);
 }
-/** Thrown when source flags count does not match expected total. */
+/**
+ * Thrown when source flags count does not match expected total.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   verifyMerkleProof({ hashes, sourceFlags })
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleFlagsMismatchError) {
+ *     console.log(`Hashes: ${error.context.totalHashes}, Flags: ${error.context.flagsLength}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleFlagsMismatchError extends CCIPError {
     readonly name = "CCIPMerkleFlagsMismatchError";
     /** Creates a merkle flags mismatch error. */
     constructor(totalHashes: number, flagsLength: number, options?: CCIPErrorOptions);
 }
-/** Thrown when proof source flags count does not match proof hashes. */
+/**
+ * Thrown when proof source flags count does not match proof hashes.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   verifyMerkleProof({ sourceFlags, proofs })
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleProofFlagsMismatchError) {
+ *     console.log(`Flags: ${error.context.sourceProofCount}, Proofs: ${error.context.proofsLength}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleProofFlagsMismatchError extends CCIPError {
     readonly name = "CCIPMerkleProofFlagsMismatchError";
     /** Creates a merkle proof flags mismatch error. */
     constructor(sourceProofCount: number, proofsLength: number, options?: CCIPErrorOptions);
 }
-/** Thrown when not all proofs were consumed during verification. */
+/**
+ * Thrown when not all proofs were consumed during verification.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   verifyMerkleProof({ leaves, proofs, root })
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleProofIncompleteError) {
+ *     console.log('Merkle proof verification incomplete')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleProofIncompleteError extends CCIPError {
     readonly name = "CCIPMerkleProofIncompleteError";
     /** Creates a merkle proof incomplete error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown on internal merkle computation error. */
+/**
+ * Thrown on internal merkle computation error.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   computeMerkleRoot(hashes)
+ * } catch (error) {
+ *   if (error instanceof CCIPMerkleInternalError) {
+ *     console.log(`Internal merkle error: ${error.message}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPMerkleInternalError extends CCIPError {
     readonly name = "CCIPMerkleInternalError";
     /** Creates a merkle internal error. */
     constructor(message: string, options?: CCIPErrorOptions);
 }
-/** Thrown when EVM address is invalid. */
+/**
+ * Thrown when EVM address is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   EVMChain.getAddress('not-an-address')
+ * } catch (error) {
+ *   if (error instanceof CCIPAddressInvalidEvmError) {
+ *     console.log(`Invalid address: ${error.context.address}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAddressInvalidEvmError extends CCIPError {
     readonly name = "CCIPAddressInvalidEvmError";
     /** Creates an EVM address invalid error. */
     constructor(address: string, options?: CCIPErrorOptions);
 }
-/** Thrown when CCIP version requires lane info. */
+/**
+ * Thrown when CCIP version requires lane info.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   EVMChain.decodeCommits(log) // Missing lane for v1.6
+ * } catch (error) {
+ *   if (error instanceof CCIPVersionRequiresLaneError) {
+ *     console.log(`Version ${error.context.version} requires lane parameter`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPVersionRequiresLaneError extends CCIPError {
     readonly name = "CCIPVersionRequiresLaneError";
     /** Creates a version requires lane error. */
     constructor(version: string, options?: CCIPErrorOptions);
 }
-/** Thrown when version feature is unavailable. */
+/**
+ * Thrown when version feature is unavailable.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getFeature(oldVersion)
+ * } catch (error) {
+ *   if (error instanceof CCIPVersionFeatureUnavailableError) {
+ *     console.log(`${error.context.feature} requires v${error.context.minVersion}+`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPVersionFeatureUnavailableError extends CCIPError {
     readonly name = "CCIPVersionFeatureUnavailableError";
     /** Creates a version feature unavailable error. */
     constructor(feature: string, version: string, minVersion?: string, options?: CCIPErrorOptions);
 }
-/** Thrown when contract is not a Router or expected CCIP contract. */
+/**
+ * Thrown when contract is not a Router or expected CCIP contract.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getRouterForOnRamp(address)
+ * } catch (error) {
+ *   if (error instanceof CCIPContractNotRouterError) {
+ *     console.log(`${error.context.address} is "${error.context.typeAndVersion}"`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPContractNotRouterError extends CCIPError {
     readonly name = "CCIPContractNotRouterError";
     /** Creates a contract not router error. */
     constructor(address: string, typeAndVersion: string, options?: CCIPErrorOptions);
 }
-/** Thrown when log data is invalid. */
+/**
+ * Thrown when log data is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = EVMChain.decodeMessage(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPLogDataInvalidError) {
+ *     console.log(`Invalid log data: ${error.context.data}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogDataInvalidError extends CCIPError {
     readonly name = "CCIPLogDataInvalidError";
     /** Creates a log data invalid error. */
     constructor(data: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when wallet is not a valid signer. */
+/**
+ * Thrown when wallet is not a valid signer.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.sendMessage({ ...opts, wallet: invalidWallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPWalletInvalidError) {
+ *     console.log('Provide a valid signer wallet')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPWalletInvalidError extends CCIPError {
     readonly name = "CCIPWalletInvalidError";
     /** Creates a wallet invalid error. */
     constructor(wallet: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when source chain is unsupported for EVM hasher. */
+/**
+ * Thrown when source chain is unsupported for EVM hasher.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const hasher = chain.getDestLeafHasher(lane)
+ * } catch (error) {
+ *   if (error instanceof CCIPSourceChainUnsupportedError) {
+ *     console.log(`Unsupported source: ${error.context.chainSelector}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSourceChainUnsupportedError extends CCIPError {
     readonly name = "CCIPSourceChainUnsupportedError";
     /** Creates a source chain unsupported error. */
     constructor(chainSelector: bigint, options?: CCIPErrorOptions);
 }
-/** Thrown when block time cannot be retrieved for a slot. */
+/**
+ * Thrown when block time cannot be retrieved for a slot. Transient: slot may not be indexed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const timestamp = await solanaChain.getBlockTimestamp(slot)
+ * } catch (error) {
+ *   if (error instanceof CCIPBlockTimeNotFoundError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 5000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPBlockTimeNotFoundError extends CCIPError {
     readonly name = "CCIPBlockTimeNotFoundError";
     /** Creates a block time not found error. */
     constructor(block: number | string, options?: CCIPErrorOptions);
 }
-/** Thrown when topics are not valid strings. */
+/**
+ * Thrown when topics are not valid strings.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getLogs({ topics: [123] }) // Invalid topic type
+ * } catch (error) {
+ *   if (error instanceof CCIPTopicsInvalidError) {
+ *     console.log('Topics must be string values')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTopicsInvalidError extends CCIPError {
     readonly name = "CCIPTopicsInvalidError";
     /** Creates a Solana topics invalid error. */
     constructor(topics: unknown[], options?: CCIPErrorOptions);
 }
-/** Thrown when reference addresses account not found for offRamp. */
+/**
+ * Thrown when reference addresses account not found for offRamp. Transient: may not be synced.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.getOffRampForRouter(router)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaRefAddressesNotFoundError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 5000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaRefAddressesNotFoundError extends CCIPError {
     readonly name = "CCIPSolanaRefAddressesNotFoundError";
     /** Creates a reference addresses not found error. */
     constructor(offRamp: string, options?: CCIPErrorOptions);
 }
-/** Thrown when OffRamp events not found in feeQuoter transactions. */
+/**
+ * Thrown when OffRamp events not found in feeQuoter transactions. Transient: events may not be indexed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.getOffRampsForRouter(router)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaOffRampEventsNotFoundError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 10000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaOffRampEventsNotFoundError extends CCIPError {
     readonly name = "CCIPSolanaOffRampEventsNotFoundError";
     /** Creates an offRamp events not found error. */
     constructor(feeQuoter: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token pool info not found. */
+/**
+ * Thrown when token pool info not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getTokenPoolConfigs(tokenPool)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenPoolInfoNotFoundError) {
+ *     console.log(`TokenPool not found: ${error.context.tokenPool}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenPoolInfoNotFoundError extends CCIPError {
     readonly name = "CCIPTokenPoolInfoNotFoundError";
     /** Creates a token pool info not found error. */
     constructor(tokenPool: string, options?: CCIPErrorOptions);
 }
-/** Thrown when SPL token is invalid or not Token-2022. */
+/**
+ * Thrown when SPL token is invalid or not Token-2022.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.getTokenInfo(tokenAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPSplTokenInvalidError) {
+ *     console.log(`Invalid SPL token: ${error.context.token}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSplTokenInvalidError extends CCIPError {
     readonly name = "CCIPSplTokenInvalidError";
     /** Creates an SPL token invalid error. */
     constructor(token: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token data cannot be parsed. */
+/**
+ * Thrown when token data cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getTokenInfo(tokenAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenDataParseError) {
+ *     console.log(`Cannot parse token: ${error.context.token}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenDataParseError extends CCIPError {
     readonly name = "CCIPTokenDataParseError";
     /** Creates a token data parse error. */
     constructor(token: string, options?: CCIPErrorOptions);
 }
-/** Thrown when EVMExtraArgsV2 has unsupported length. */
+/**
+ * Thrown when EVMExtraArgsV2 has unsupported length.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   SolanaChain.decodeExtraArgs(data)
+ * } catch (error) {
+ *   if (error instanceof CCIPExtraArgsLengthInvalidError) {
+ *     console.log(`Unsupported length: ${error.context.length}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPExtraArgsLengthInvalidError extends CCIPError {
     readonly name = "CCIPExtraArgsLengthInvalidError";
     /** Creates an extraArgs length invalid error. */
     constructor(length: number, options?: CCIPErrorOptions);
 }
-/** Thrown when Solana can only encode EVMExtraArgsV2 but got different args. */
+/**
+ * Thrown when Solana can only encode EVMExtraArgsV2 but got different args.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   SolanaChain.encodeExtraArgs(unsupportedArgs)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaExtraArgsEncodingError) {
+ *     console.log('Use EVMExtraArgsV2 format for Solana')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaExtraArgsEncodingError extends CCIPError {
     readonly name = "CCIPSolanaExtraArgsEncodingError";
     /** Creates a Solana extraArgs encoding error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when log data is missing or not a string. */
+/**
+ * Thrown when log data is missing or not a string.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = Chain.decodeMessage(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPLogDataMissingError) {
+ *     console.log('Log data is missing or invalid')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPLogDataMissingError extends CCIPError {
     readonly name = "CCIPLogDataMissingError";
     /** Creates a log data missing error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when ExecutionState is invalid. */
+/**
+ * Thrown when ExecutionState is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const receipt = Chain.decodeReceipt(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPExecutionStateInvalidError) {
+ *     console.log(`Invalid state: ${error.context.state}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPExecutionStateInvalidError extends CCIPError {
     readonly name = "CCIPExecutionStateInvalidError";
     /** Creates an execution state invalid error. */
     constructor(state: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when execution report message is not for Solana. */
+/**
+ * Thrown when execution report message is not for the expected chain.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.execute({ offRamp, input, wallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPExecutionReportChainMismatchError) {
+ *     console.log(`Message not for ${error.context.chain}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPExecutionReportChainMismatchError extends CCIPError {
     readonly name = "CCIPExecutionReportChainMismatchError";
     /** Creates an execution report chain mismatch error. */
     constructor(chain: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token pool state PDA not found. */
+/**
+ * Thrown when token pool state PDA not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.getTokenPoolConfigs(tokenPool)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenPoolStateNotFoundError) {
+ *     console.log(`State not found at: ${error.context.tokenPool}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenPoolStateNotFoundError extends CCIPError {
     readonly name = "CCIPTokenPoolStateNotFoundError";
     /** Creates a token pool state not found error. */
     constructor(tokenPool: string, options?: CCIPErrorOptions);
 }
-/** Thrown when ChainConfig not found for token pool and remote chain. */
+/**
+ * Thrown when ChainConfig not found for token pool and remote chain.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.getTokenPoolRemotes(tokenPool, destChainSelector)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenPoolChainConfigNotFoundError) {
+ *     console.log(`No config for ${error.context.remoteNetwork}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenPoolChainConfigNotFoundError extends CCIPError {
     readonly name = "CCIPTokenPoolChainConfigNotFoundError";
     /** Creates a token pool chain config not found error. */
     constructor(address: string, tokenPool: string, remoteNetwork: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos network is unknown. */
+/**
+ * Thrown when Aptos network is unknown.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const chain = await AptosChain.fromUrl('https://unknown-network')
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosNetworkUnknownError) {
+ *     console.log(`Unknown network: ${error.context.url}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosNetworkUnknownError extends CCIPError {
     readonly name = "CCIPAptosNetworkUnknownError";
     /** Creates an Aptos network unknown error. */
     constructor(url: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos transaction type is invalid. */
+/**
+ * Thrown when Aptos transaction type is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.getMessagesInTx(txHash)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosTransactionTypeInvalidError) {
+ *     console.log('Expected user_transaction type')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosTransactionTypeInvalidError extends CCIPError {
     readonly name = "CCIPAptosTransactionTypeInvalidError";
     /** Creates an Aptos transaction type invalid error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos registry type is invalid. */
+/**
+ * Thrown when Aptos registry type is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.getTokenAdminRegistryFor(registry)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosRegistryTypeInvalidError) {
+ *     console.log(`Expected TokenAdminRegistry, got: ${error.context.actualType}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosRegistryTypeInvalidError extends CCIPError {
     readonly name = "CCIPAptosRegistryTypeInvalidError";
     /** Creates an Aptos registry type invalid error. */
     constructor(registry: string, actualType: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos log data is invalid. */
+/**
+ * Thrown when Aptos log data is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = AptosChain.decodeMessage(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosLogInvalidError) {
+ *     console.log(`Invalid log: ${error.context.log}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosLogInvalidError extends CCIPError {
     readonly name = "CCIPAptosLogInvalidError";
     /** Creates an Aptos log invalid error. */
     constructor(log: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos address is invalid. */
+/**
+ * Thrown when Aptos address is invalid.
+ *
+ * @example
+ * ```typescript
+ * import { CCIPDataFormatUnsupportedError } from '@chainlink/ccip-sdk'
+ *
+ * try {
+ *   AptosChain.getAddress('invalid-address')
+ * } catch (error) {
+ *   if (error instanceof CCIPDataFormatUnsupportedError) {
+ *     console.log(`Invalid address: ${error.message}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosAddressInvalidError extends CCIPError {
     readonly name = "CCIPAptosAddressInvalidError";
     /** Creates an Aptos address invalid error. */
     constructor(address: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos can only encode specific extra args types. */
+/**
+ * Thrown when Aptos can only encode specific extra args types.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   AptosChain.encodeExtraArgs(unsupportedArgs)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosExtraArgsEncodingError) {
+ *     console.log('Use EVMExtraArgsV2 or SVMExtraArgsV1 for Aptos')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosExtraArgsEncodingError extends CCIPError {
     readonly name = "CCIPAptosExtraArgsEncodingError";
     /** Creates an Aptos extraArgs encoding error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos wallet is invalid. */
+/**
+ * Thrown when Aptos wallet is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.sendMessage({ ...opts, wallet: invalidWallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosWalletInvalidError) {
+ *     console.log('Provide a valid Aptos account wallet')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosWalletInvalidError extends CCIPError {
     readonly name = "CCIPAptosWalletInvalidError";
     /** Creates an Aptos wallet invalid error. */
     constructor(className: string, wallet: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos expects EVMExtraArgsV2 reports. */
+/**
+ * Thrown when Aptos expects EVMExtraArgsV2 reports.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.execute({ offRamp, input, wallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosExtraArgsV2RequiredError) {
+ *     console.log('Aptos requires EVMExtraArgsV2 format')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosExtraArgsV2RequiredError extends CCIPError {
     readonly name = "CCIPAptosExtraArgsV2RequiredError";
     /** Creates an Aptos EVMExtraArgsV2 required error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when token is not registered in Aptos registry. */
+/**
+ * Thrown when token is not registered in Aptos registry.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.getRegistryTokenConfig(registry, token)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosTokenNotRegisteredError) {
+ *     console.log(`Token ${error.context.token} not in registry`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosTokenNotRegisteredError extends CCIPError {
     readonly name = "CCIPAptosTokenNotRegisteredError";
     /** Creates an Aptos token not registered error. */
     constructor(token: string, registry: string, options?: CCIPErrorOptions);
 }
-/** Thrown for unexpected Aptos transaction type. */
+/**
+ * Thrown for unexpected Aptos transaction type.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.getTransaction(txHash)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosTransactionTypeUnexpectedError) {
+ *     console.log(`Unexpected type: ${error.context.type}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosTransactionTypeUnexpectedError extends CCIPError {
     readonly name = "CCIPAptosTransactionTypeUnexpectedError";
     /** Creates an Aptos transaction type unexpected error. */
     constructor(type: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos address with module is required. */
+/**
+ * Thrown when Aptos address with module is required.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.getLogs({ address: '0x1' }) // Missing module
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosAddressModuleRequiredError) {
+ *     console.log('Provide address with module name')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosAddressModuleRequiredError extends CCIPError {
     readonly name = "CCIPAptosAddressModuleRequiredError";
     /** Creates an Aptos address module required error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when Borsh type is unknown. */
+/**
+ * Thrown when Aptos topic is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await aptosChain.getLogs({ topics: ['invalid'] })
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosTopicInvalidError) {
+ *     console.log(`Invalid topic: ${error.context.topic}`)
+ *   }
+ * }
+ * ```
+ */
+export declare class CCIPAptosTopicInvalidError extends CCIPError {
+    readonly name = "CCIPAptosTopicInvalidError";
+    /** Creates an Aptos topic invalid error. */
+    constructor(topic?: string, options?: CCIPErrorOptions);
+}
+/**
+ * Thrown when Borsh type is unknown.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   decodeBorsh(data, 'UnknownType')
+ * } catch (error) {
+ *   if (error instanceof CCIPBorshTypeUnknownError) {
+ *     console.log(`Unknown type: ${error.context.name}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPBorshTypeUnknownError extends CCIPError {
     readonly name = "CCIPBorshTypeUnknownError";
     /** Creates a Borsh type unknown error. */
     constructor(name: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Borsh method is unknown. */
+/**
+ * Thrown when Borsh method is unknown.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   callBorshMethod('unknownMethod')
+ * } catch (error) {
+ *   if (error instanceof CCIPBorshMethodUnknownError) {
+ *     console.log(`Unknown method: ${error.context.method}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPBorshMethodUnknownError extends CCIPError {
     readonly name = "CCIPBorshMethodUnknownError";
     /** Creates a Borsh method unknown error. */
     constructor(method: string, options?: CCIPErrorOptions);
 }
-/** Thrown when CLI argument is invalid. */
+/**
+ * Thrown when CLI argument is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   parseArguments(['--invalid-arg'])
+ * } catch (error) {
+ *   if (error instanceof CCIPArgumentInvalidError) {
+ *     console.log(`${error.context.argument}: ${error.context.reason}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPArgumentInvalidError extends CCIPError {
     readonly name = "CCIPArgumentInvalidError";
     /** Creates an argument invalid error. */
     constructor(argument: string, reason: string, options?: CCIPErrorOptions);
 }
-/** Thrown when execution receipt not found in tx logs. Transient: receipt may not be indexed yet. */
+/**
+ * Thrown when execution receipt not found in tx logs. Transient: receipt may not be indexed yet.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const receipt = await chain.getExecutionReceiptInTx(txHash)
+ * } catch (error) {
+ *   if (error instanceof CCIPReceiptNotFoundError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 5000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPReceiptNotFoundError extends CCIPError {
     readonly name = "CCIPReceiptNotFoundError";
     /** Creates a receipt not found error. */
     constructor(txHash: string, options?: CCIPErrorOptions);
 }
-/** Thrown when data cannot be parsed. */
+/**
+ * Thrown when data cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const parsed = Chain.parse(data)
+ * } catch (error) {
+ *   if (error instanceof CCIPDataParseError) {
+ *     console.log(`Parse failed for: ${error.context.data}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPDataParseError extends CCIPError {
     readonly name = "CCIPDataParseError";
     /** Creates a data parse error. */
     constructor(data: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token not found in supported tokens list. */
+/**
+ * Thrown when token not found in supported tokens list.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tokens = await chain.getSupportedTokens(router, destChainSelector)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenNotFoundError) {
+ *     console.log(`Token not found: ${error.context.token}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenNotFoundError extends CCIPError {
     readonly name = "CCIPTokenNotFoundError";
     /** Creates a token not found error. */
@@ -580,97 +1909,319 @@ export declare class CCIPInsufficientBalanceError extends CCIPError {
     /** Creates an insufficient balance error. */
     constructor(have: string, need: string, symbol: string, options?: CCIPErrorOptions);
 }
-/** Thrown when router config not found at PDA. */
+/**
+ * Thrown when router config not found at PDA.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.getOnRampForRouter(router, destChainSelector)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaRouterConfigNotFoundError) {
+ *     console.log(`Config not found at: ${error.context.configPda}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaRouterConfigNotFoundError extends CCIPError {
     readonly name = "CCIPSolanaRouterConfigNotFoundError";
     /** Creates a Solana router config not found error. */
     constructor(configPda: string, options?: CCIPErrorOptions);
 }
-/** Thrown when fee result from router is invalid. */
+/**
+ * Thrown when fee result from router is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const fee = await solanaChain.getFee(router, message)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaFeeResultInvalidError) {
+ *     console.log(`Invalid fee result: ${error.context.result}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaFeeResultInvalidError extends CCIPError {
     readonly name = "CCIPSolanaFeeResultInvalidError";
     /** Creates a Solana fee result invalid error. */
     constructor(result: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token mint not found. */
+/**
+ * Thrown when token mint not found.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.getTokenInfo(mintAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenMintNotFoundError) {
+ *     console.log(`Mint not found: ${error.context.token}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenMintNotFoundError extends CCIPError {
     readonly name = "CCIPTokenMintNotFoundError";
     /** Creates a token mint not found error. */
     constructor(token: string, options?: CCIPErrorOptions);
 }
-/** Thrown when token mint exists but is not a valid SPL token (wrong owner program). */
+/**
+ * Thrown when token mint exists but is not a valid SPL token (wrong owner program).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const tokenInfo = await solanaChain.getTokenInfo(mintAddress)
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenMintInvalidError) {
+ *     console.log(`Invalid mint: ${error.context.token}`)
+ *     console.log(`Owner: ${error.context.actualOwner}`)
+ *     console.log(`Expected: ${error.context.expectedOwners.join(' or ')}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenMintInvalidError extends CCIPError {
     readonly name = "CCIPTokenMintInvalidError";
     /** Creates a token mint invalid error. */
     constructor(token: string, actualOwner: string, expectedOwners: string[], options?: CCIPErrorOptions);
 }
-/** Thrown when token amount is invalid. */
+/**
+ * Thrown when token amount is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.sendMessage({ tokenAmounts: [{ token: '', amount: 0n }] })
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenAmountInvalidError) {
+ *     console.log('Token address and positive amount required')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenAmountInvalidError extends CCIPError {
     readonly name = "CCIPTokenAmountInvalidError";
     /** Creates a token amount invalid error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when token account (e.g., Solana ATA) does not exist for holder. */
+/**
+ * Thrown when token account (e.g., Solana ATA) does not exist for holder.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const balance = await solanaChain.getBalance({ address: holder, token: mint })
+ * } catch (error) {
+ *   if (error instanceof CCIPTokenAccountNotFoundError) {
+ *     console.log(`No ATA for token ${error.context.token}`)
+ *     console.log(`Holder: ${error.context.holder}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTokenAccountNotFoundError extends CCIPError {
     readonly name = "CCIPTokenAccountNotFoundError";
     /** Creates a token account not found error. */
     constructor(token: string, holder: string, options?: CCIPErrorOptions);
 }
-/** Thrown when transaction not finalized after timeout. */
+/**
+ * Thrown when transaction not finalized after timeout. Transient: may need more time.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await chain.waitFinalized(txHash)
+ * } catch (error) {
+ *   if (error instanceof CCIPTransactionNotFinalizedError) {
+ *     if (error.isTransient) {
+ *       await sleep(error.retryAfterMs ?? 10000)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPTransactionNotFinalizedError extends CCIPError {
     readonly name = "CCIPTransactionNotFinalizedError";
     /** Creates a transaction not finalized error. */
     constructor(signature: string, options?: CCIPErrorOptions);
 }
-/** Thrown when CCTP event decode fails. */
+/**
+ * Thrown when CCTP event decode fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const cctpData = decodeCctpEvent(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPCctpDecodeError) {
+ *     console.log(`CCTP decode failed: ${error.context.log}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPCctpDecodeError extends CCIPError {
     readonly name = "CCIPCctpDecodeError";
     /** Creates a CCTP decode error. */
     constructor(log: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Sui hasher version is unsupported. */
+/**
+ * Thrown when Sui hasher version is unsupported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const hasher = SuiChain.getDestLeafHasher(lane)
+ * } catch (error) {
+ *   if (error instanceof CCIPSuiHasherVersionUnsupportedError) {
+ *     console.log(`Unsupported hasher: ${error.context.version}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSuiHasherVersionUnsupportedError extends CCIPError {
     readonly name = "CCIPSuiHasherVersionUnsupportedError";
     /** Creates a Sui hasher version unsupported error. */
     constructor(version: string, options?: CCIPErrorOptions);
 }
-/** Thrown when Sui message version is invalid. */
+/**
+ * Thrown when Sui message version is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = SuiChain.decodeMessage(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPSuiMessageVersionInvalidError) {
+ *     console.log('Only CCIP v1.6 format is supported for Sui')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSuiMessageVersionInvalidError extends CCIPError {
     readonly name = "CCIPSuiMessageVersionInvalidError";
     /** Creates a Sui message version invalid error. */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when Sui log data is invalid. */
+/**
+ * Thrown when Sui log data is invalid.
+ *
+ * This error occurs when attempting to decode a Sui event log that doesn't
+ * conform to the expected CCIP message format.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const message = SuiChain.decodeMessage(log)
+ * } catch (error) {
+ *   if (error instanceof CCIPSuiLogInvalidError) {
+ *     console.log('Invalid Sui log format:', error.context.log)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSuiLogInvalidError extends CCIPError {
     readonly name = "CCIPSuiLogInvalidError";
-    /** Creates a Sui log invalid error. */
+    /**
+     * Creates a Sui log invalid error.
+     *
+     * @param log - The invalid log data
+     * @param options - Additional error options
+     */
     constructor(log: unknown, options?: CCIPErrorOptions);
 }
-/** Thrown when Solana lane version is unsupported. */
+/**
+ * Thrown when Solana lane version is unsupported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const lane = await solanaChain.getLane(onRamp, offRamp)
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaLaneVersionUnsupportedError) {
+ *     console.log(`Unsupported version: ${error.context.version}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaLaneVersionUnsupportedError extends CCIPError {
     readonly name = "CCIPSolanaLaneVersionUnsupportedError";
     /** Creates a Solana lane version unsupported error. */
     constructor(version: string, options?: CCIPErrorOptions);
 }
-/** Thrown when multiple CCTP events found in transaction. */
+/**
+ * Thrown when multiple CCTP events found in transaction.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const cctpData = await chain.getOffchainTokenData(request)
+ * } catch (error) {
+ *   if (error instanceof CCIPCctpMultipleEventsError) {
+ *     console.log(`Found ${error.context.count} events, expected 1`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPCctpMultipleEventsError extends CCIPError {
     readonly name = "CCIPCctpMultipleEventsError";
     /** Creates a CCTP multiple events error. */
     constructor(count: number, txSignature: string, options?: CCIPErrorOptions);
 }
-/** Thrown when compute units exceed limit. */
+/**
+ * Thrown when compute units exceed limit.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await solanaChain.execute({ offRamp, input, wallet })
+ * } catch (error) {
+ *   if (error instanceof CCIPSolanaComputeUnitsExceededError) {
+ *     console.log(`CU: ${error.context.simulated} > limit ${error.context.limit}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPSolanaComputeUnitsExceededError extends CCIPError {
     readonly name = "CCIPSolanaComputeUnitsExceededError";
     /** Creates a compute units exceeded error. */
     constructor(simulated: number, limit: number, options?: CCIPErrorOptions);
 }
-/** Thrown when Aptos hasher version is unsupported. */
+/**
+ * Thrown when Aptos hasher version is unsupported.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const hasher = AptosChain.getDestLeafHasher(lane)
+ * } catch (error) {
+ *   if (error instanceof CCIPAptosHasherVersionUnsupportedError) {
+ *     console.log(`Unsupported hasher: ${error.context.version}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPAptosHasherVersionUnsupportedError extends CCIPError {
     readonly name = "CCIPAptosHasherVersionUnsupportedError";
     /** Creates an Aptos hasher version unsupported error. */
     constructor(version: string, options?: CCIPErrorOptions);
 }
-/** Thrown when API client is not available (explicitly opted out). */
+/**
+ * Thrown when API client is not available (explicitly opted out).
+ *
+ * @example
+ * ```typescript
+ * const chain = await EVMChain.fromUrl(rpc, { apiClient: null }) // Opt-out of API
+ * try {
+ *   await chain.getLaneLatency(destChainSelector)
+ * } catch (error) {
+ *   if (error instanceof CCIPApiClientNotAvailableError) {
+ *     console.log('API client disabled - initialize with apiClient or remove opt-out')
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPApiClientNotAvailableError extends CCIPError {
     readonly name = "CCIPApiClientNotAvailableError";
     /**
@@ -679,18 +2230,42 @@ export declare class CCIPApiClientNotAvailableError extends CCIPError {
      */
     constructor(options?: CCIPErrorOptions);
 }
-/** Thrown when API returns hasNextPage=true unexpectedly (more than 100 messages). */
+/**
+ * Thrown when API returns hasNextPage=true unexpectedly (more than 100 messages).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const messages = await chain.getMessagesInTx(txHash)
+ * } catch (error) {
+ *   if (error instanceof CCIPUnexpectedPaginationError) {
+ *     console.log(`Too many messages in tx: ${error.context.txHash}`)
+ *     console.log(`Message count: ${error.context.messageCount}+`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPUnexpectedPaginationError extends CCIPError {
     readonly name = "CCIPUnexpectedPaginationError";
-    /**
-     * Creates an unexpected pagination error.
-     * @param txHash - The transaction hash queried
-     * @param messageCount - Number of messages returned in the response
-     * @param options - Additional error options
-     */
+    /** Creates an unexpected pagination error. */
     constructor(txHash: string, messageCount: number, options?: CCIPErrorOptions);
 }
-/** Thrown when viem adapter encounters an issue. */
+/**
+ * Thrown when viem adapter encounters an issue.
+ *
+ * @example
+ * ```typescript
+ * import { fromViemClient } from '@chainlink/ccip-sdk/viem'
+ *
+ * try {
+ *   const chain = await fromViemClient(viemClient)
+ * } catch (error) {
+ *   if (error instanceof CCIPViemAdapterError) {
+ *     console.log(`Viem adapter error: ${error.message}`)
+ *   }
+ * }
+ * ```
+ */
 export declare class CCIPViemAdapterError extends CCIPError {
     readonly name = "CCIPViemAdapterError";
     /**