@chainlink/ccip-sdk 0.96.0 → 1.0.0

package/dist/errors/specialized.js

@@ -2,7 +2,23 @@ import { CCIPError } from "./CCIPError.js";
 import { CCIPErrorCode } from "./codes.js";
 import { isTransientHttpStatus } from "../http-status.js";
 // Chain/Network
-/** 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 class CCIPChainNotFoundError extends CCIPError {
     name = 'CCIPChainNotFoundError';
     /** Creates a chain not found error. */
@@ -14,7 +30,20 @@ export class CCIPChainNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPChainFamilyUnsupportedError extends CCIPError {
     name = 'CCIPChainFamilyUnsupportedError';
     /** Creates a chain family unsupported error. */
@@ -26,7 +55,20 @@ export class CCIPChainFamilyUnsupportedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMethodUnsupportedError extends CCIPError {
     name = 'CCIPMethodUnsupportedError';
     /** Creates a method unsupported error. */
@@ -39,7 +81,22 @@ export class CCIPMethodUnsupportedError extends CCIPError {
     }
 }
 // Block & Transaction
-/** 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 class CCIPBlockNotFoundError extends CCIPError {
     name = 'CCIPBlockNotFoundError';
     /** Creates a block not found error. */
@@ -52,7 +109,23 @@ export class CCIPBlockNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTransactionNotFoundError extends CCIPError {
     name = 'CCIPTransactionNotFoundError';
     /** Creates a transaction not found error. */
@@ -66,7 +139,20 @@ export class CCIPTransactionNotFoundError extends CCIPError {
     }
 }
 // CCIP Message
-/** 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 class CCIPMessageInvalidError extends CCIPError {
     name = 'CCIPMessageInvalidError';
     /** Creates a message invalid error. */
@@ -79,20 +165,49 @@ export class CCIPMessageInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMessageNotFoundInTxError extends CCIPError {
     name = 'CCIPMessageNotFoundInTxError';
     /** Creates a message not found in transaction error. */
     constructor(txHash, options) {
-        super(CCIPErrorCode.MESSAGE_NOT_FOUND_IN_TX, `Could not find any CCIPSendRequested message in tx: ${txHash}`, {
+        super(CCIPErrorCode.MESSAGE_NOT_FOUND_IN_TX, `Could not find any CCIP request event in tx`, {
             ...options,
-            isTransient: true,
-            retryAfterMs: 30000,
+            isTransient: false,
             context: { ...options?.context, txHash },
         });
     }
 }
-/** 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 class CCIPMessageIdNotFoundError extends CCIPError {
     name = 'CCIPMessageIdNotFoundError';
     /** Creates a message ID not found error. */
@@ -105,7 +220,21 @@ export class CCIPMessageIdNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMessageIdValidationError extends CCIPError {
     name = 'CCIPMessageIdValidationError';
     /** Creates a message ID validation error. */
@@ -116,7 +245,23 @@ export class CCIPMessageIdValidationError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMessageBatchIncompleteError extends CCIPError {
     name = 'CCIPMessageBatchIncompleteError';
     /** Creates a message batch incomplete error. */
@@ -129,7 +274,20 @@ export class CCIPMessageBatchIncompleteError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMessageNotInBatchError extends CCIPError {
     name = 'CCIPMessageNotInBatchError';
     /** Creates a message not in batch error. */
@@ -141,7 +299,21 @@ export class CCIPMessageNotInBatchError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMessageRetrievalError extends CCIPError {
     name = 'CCIPMessageRetrievalError';
     /** Creates a message retrieval error with both API and RPC failure context. */
@@ -163,7 +335,21 @@ export class CCIPMessageRetrievalError extends CCIPError {
     }
 }
 // Lane & Routing
-/** 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 class CCIPOffRampNotFoundError extends CCIPError {
     name = 'CCIPOffRampNotFoundError';
     /** Creates an offRamp not found error. */
@@ -175,7 +361,20 @@ export class CCIPOffRampNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPOnRampRequiredError extends CCIPError {
     name = 'CCIPOnRampRequiredError';
     /** Creates an onRamp required error. */
@@ -186,7 +385,20 @@ export class CCIPOnRampRequiredError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLaneNotFoundError extends CCIPError {
     name = 'CCIPLaneNotFoundError';
     /** Creates a lane not found error. */
@@ -199,7 +411,22 @@ export class CCIPLaneNotFoundError extends CCIPError {
     }
 }
 // Commit & Merkle
-/** 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 class CCIPCommitNotFoundError extends CCIPError {
     name = 'CCIPCommitNotFoundError';
     /** Creates a commit not found error. */
@@ -212,7 +439,20 @@ export class CCIPCommitNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleRootMismatchError extends CCIPError {
     name = 'CCIPMerkleRootMismatchError';
     /** Creates a merkle root mismatch error. */
@@ -224,7 +464,20 @@ export class CCIPMerkleRootMismatchError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleTreeEmptyError extends CCIPError {
     name = 'CCIPMerkleTreeEmptyError';
     /** Creates a merkle tree empty error. */
@@ -236,7 +489,20 @@ export class CCIPMerkleTreeEmptyError extends CCIPError {
     }
 }
 // Version
-/** 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 class CCIPVersionUnsupportedError extends CCIPError {
     name = 'CCIPVersionUnsupportedError';
     /** Creates a version unsupported error. */
@@ -248,7 +514,20 @@ export class CCIPVersionUnsupportedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPHasherVersionUnsupportedError extends CCIPError {
     name = 'CCIPHasherVersionUnsupportedError';
     /** Creates a hasher version unsupported error. */
@@ -261,7 +540,20 @@ export class CCIPHasherVersionUnsupportedError extends CCIPError {
     }
 }
 // ExtraArgs
-/** 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 class CCIPExtraArgsParseError extends CCIPError {
     name = 'CCIPExtraArgsParseError';
     /** Creates an extraArgs parse error. */
@@ -278,6 +570,17 @@ export 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 class CCIPExtraArgsInvalidError extends CCIPError {
     name = 'CCIPExtraArgsInvalidError';
@@ -302,7 +605,20 @@ export class CCIPExtraArgsInvalidError extends CCIPError {
     }
 }
 // Token & Registry
-/** 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 class CCIPTokenNotInRegistryError extends CCIPError {
     name = 'CCIPTokenNotInRegistryError';
     /** Creates a token not in registry error. */
@@ -314,7 +630,20 @@ export class CCIPTokenNotInRegistryError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenNotConfiguredError extends CCIPError {
     name = 'CCIPTokenNotConfiguredError';
     /** Creates a token not configured error. */
@@ -326,7 +655,20 @@ export class CCIPTokenNotConfiguredError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenDecimalsInsufficientError extends CCIPError {
     name = 'CCIPTokenDecimalsInsufficientError';
     /** Creates a token decimals insufficient error. */
@@ -339,7 +681,20 @@ export class CCIPTokenDecimalsInsufficientError extends CCIPError {
     }
 }
 // Contract Type
-/** 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 class CCIPContractTypeInvalidError extends CCIPError {
     name = 'CCIPContractTypeInvalidError';
     /** Creates a contract type invalid error. */
@@ -352,7 +707,20 @@ export class CCIPContractTypeInvalidError extends CCIPError {
     }
 }
 // Wallet & Signer
-/** 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 class CCIPWalletNotSignerError extends CCIPError {
     name = 'CCIPWalletNotSignerError';
     /** Creates a wallet not signer error. */
@@ -365,7 +733,22 @@ export class CCIPWalletNotSignerError extends CCIPError {
     }
 }
 // Execution
-/** 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 class CCIPExecTxNotConfirmedError extends CCIPError {
     name = 'CCIPExecTxNotConfirmedError';
     /** Creates an exec transaction not confirmed error. */
@@ -378,7 +761,20 @@ export class CCIPExecTxNotConfirmedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPExecTxRevertedError extends CCIPError {
     name = 'CCIPExecTxRevertedError';
     /** Creates an exec transaction reverted error. */
@@ -391,7 +787,22 @@ export class CCIPExecTxRevertedError extends CCIPError {
     }
 }
 // Attestation (USDC/LBTC)
-/** 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 class CCIPUsdcAttestationError extends CCIPError {
     name = 'CCIPUsdcAttestationError';
     /** Creates a USDC attestation error. */
@@ -404,7 +815,22 @@ export class CCIPUsdcAttestationError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLbtcAttestationError extends CCIPError {
     name = 'CCIPLbtcAttestationError';
     /** Creates an LBTC attestation error. */
@@ -417,7 +843,23 @@ export class CCIPLbtcAttestationError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLbtcAttestationNotFoundError extends CCIPError {
     name = 'CCIPLbtcAttestationNotFoundError';
     /** Creates an LBTC attestation not found error. */
@@ -430,7 +872,23 @@ export class CCIPLbtcAttestationNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLbtcAttestationNotApprovedError extends CCIPError {
     name = 'CCIPLbtcAttestationNotApprovedError';
     /** Creates an LBTC attestation not approved error. */
@@ -444,7 +902,22 @@ export class CCIPLbtcAttestationNotApprovedError extends CCIPError {
     }
 }
 // Solana
-/** 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 class CCIPSolanaLookupTableNotFoundError extends CCIPError {
     name = 'CCIPSolanaLookupTableNotFoundError';
     /** Creates a Solana lookup table not found error. */
@@ -458,7 +931,20 @@ export class CCIPSolanaLookupTableNotFoundError extends CCIPError {
     }
 }
 // Aptos
-/** 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 class CCIPAptosTransactionInvalidError extends CCIPError {
     name = 'CCIPAptosTransactionInvalidError';
     /** Creates an Aptos transaction invalid error. */
@@ -471,7 +957,23 @@ export class CCIPAptosTransactionInvalidError extends CCIPError {
     }
 }
 // HTTP & Data
-/** 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 class CCIPHttpError extends CCIPError {
     name = 'CCIPHttpError';
     /** Creates an HTTP error. */
@@ -483,7 +985,23 @@ export class CCIPHttpError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTimeoutError extends CCIPError {
     name = 'CCIPTimeoutError';
     /** Creates a timeout error. */
@@ -496,7 +1014,20 @@ export class CCIPTimeoutError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPNotImplementedError extends CCIPError {
     name = 'CCIPNotImplementedError';
     /** Creates a not implemented error. */
@@ -509,7 +1040,20 @@ export class CCIPNotImplementedError extends CCIPError {
     }
 }
 // Data Format & Parsing
-/** 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 class CCIPDataFormatUnsupportedError extends CCIPError {
     name = 'CCIPDataFormatUnsupportedError';
     /** Creates a data format unsupported error. */
@@ -521,7 +1065,20 @@ export class CCIPDataFormatUnsupportedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTypeVersionInvalidError extends CCIPError {
     name = 'CCIPTypeVersionInvalidError';
     /** Creates a type version invalid error. */
@@ -533,7 +1090,20 @@ export class CCIPTypeVersionInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPBlockBeforeTimestampNotFoundError extends CCIPError {
     name = 'CCIPBlockBeforeTimestampNotFoundError';
     /** Creates a block before timestamp not found error. */
@@ -545,7 +1115,20 @@ export class CCIPBlockBeforeTimestampNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMessageDecodeError extends CCIPError {
     name = 'CCIPMessageDecodeError';
     /** Creates a message decode error. */
@@ -557,7 +1140,45 @@ export class CCIPMessageDecodeError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPNetworkFamilyUnsupportedError extends CCIPError {
+    name = 'CCIPNetworkFamilyUnsupportedError';
+    /** Creates a network family unsupported error. */
+    constructor(family, options) {
+        super(CCIPErrorCode.NETWORK_FAMILY_UNSUPPORTED, `Unsupported network family: ${family}`, {
+            ...options,
+            isTransient: false,
+            context: { ...options?.context, family },
+        });
+    }
+}
+/**
+ * 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 class CCIPRpcNotFoundError extends CCIPError {
     name = 'CCIPRpcNotFoundError';
     /** Creates an RPC not found error. */
@@ -569,7 +1190,22 @@ export class CCIPRpcNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLogsNotFoundError extends CCIPError {
     name = 'CCIPLogsNotFoundError';
     /** Creates a logs not found error. */
@@ -582,7 +1218,20 @@ export class CCIPLogsNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLogTopicsNotFoundError extends CCIPError {
     name = 'CCIPLogTopicsNotFoundError';
     /** Creates a log topics not found error. */
@@ -594,18 +1243,44 @@ export class CCIPLogTopicsNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLogsWatchRequiresFinalityError extends CCIPError {
     name = 'CCIPLogsWatchRequiresFinalityError';
-    /** Creates a watch requires finality error. */
+    /** Creates a logs watch requires finality error. */
     constructor(endBlock, options) {
         super(CCIPErrorCode.LOGS_WATCH_REQUIRES_FINALITY, `Watch mode requires finality config for endBlock (latest, finalized or block depth=negative)`, { ...options, isTransient: false, context: { ...options?.context, endBlock } });
     }
 }
-/** 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 class CCIPLogsWatchRequiresStartError extends CCIPError {
     name = 'CCIPLogsWatchRequiresStartError';
-    /** Creates a watch requires start error. */
+    /** Creates a logs watch requires start error. */
     constructor(options) {
         super(CCIPErrorCode.LOGS_WATCH_REQUIRES_START, `Watch mode requires startBlock or startTime`, {
             ...options,
@@ -613,7 +1288,20 @@ export class CCIPLogsWatchRequiresStartError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLogsAddressRequiredError extends CCIPError {
     name = 'CCIPLogsAddressRequiredError';
     /** Creates a Solana program address required error. */
@@ -625,7 +1313,20 @@ export class CCIPLogsAddressRequiredError extends CCIPError {
     }
 }
 // Chain Family
-/** 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 class CCIPChainFamilyMismatchError extends CCIPError {
     name = 'CCIPChainFamilyMismatchError';
     /** Creates a chain family mismatch error. */
@@ -637,8 +1338,46 @@ export class CCIPChainFamilyMismatchError extends CCIPError {
         });
     }
 }
+// Token Pool
+/**
+ * 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 class CCIPLegacyTokenPoolsUnsupportedError extends CCIPError {
+    name = 'CCIPLegacyTokenPoolsUnsupportedError';
+    /** Creates a legacy token pools unsupported error. */
+    constructor(options) {
+        super(CCIPErrorCode.LEGACY_TOKEN_POOLS_UNSUPPORTED, 'Legacy <1.5 token pools not supported', {
+            ...options,
+            isTransient: false,
+        });
+    }
+}
 // Merkle Validation
-/** Thrown when merkle proof is empty. */
+/**
+ * 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 class CCIPMerkleProofEmptyError extends CCIPError {
     name = 'CCIPMerkleProofEmptyError';
     /** Creates a merkle proof empty error. */
@@ -649,7 +1388,20 @@ export class CCIPMerkleProofEmptyError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleProofTooLargeError extends CCIPError {
     name = 'CCIPMerkleProofTooLargeError';
     /** Creates a merkle proof too large error. */
@@ -661,7 +1413,20 @@ export class CCIPMerkleProofTooLargeError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleHashesTooLargeError extends CCIPError {
     name = 'CCIPMerkleHashesTooLargeError';
     /** Creates a merkle hashes too large error. */
@@ -673,7 +1438,20 @@ export class CCIPMerkleHashesTooLargeError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleFlagsMismatchError extends CCIPError {
     name = 'CCIPMerkleFlagsMismatchError';
     /** Creates a merkle flags mismatch error. */
@@ -685,7 +1463,20 @@ export class CCIPMerkleFlagsMismatchError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleProofFlagsMismatchError extends CCIPError {
     name = 'CCIPMerkleProofFlagsMismatchError';
     /** Creates a merkle proof flags mismatch error. */
@@ -697,7 +1488,20 @@ export class CCIPMerkleProofFlagsMismatchError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleProofIncompleteError extends CCIPError {
     name = 'CCIPMerkleProofIncompleteError';
     /** Creates a merkle proof incomplete error. */
@@ -708,7 +1512,20 @@ export class CCIPMerkleProofIncompleteError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPMerkleInternalError extends CCIPError {
     name = 'CCIPMerkleInternalError';
     /** Creates a merkle internal error. */
@@ -720,7 +1537,20 @@ export class CCIPMerkleInternalError extends CCIPError {
     }
 }
 // Address Validation
-/** 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 class CCIPAddressInvalidEvmError extends CCIPError {
     name = 'CCIPAddressInvalidEvmError';
     /** Creates an EVM address invalid error. */
@@ -733,7 +1563,20 @@ export class CCIPAddressInvalidEvmError extends CCIPError {
     }
 }
 // Version Requirements
-/** 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 class CCIPVersionRequiresLaneError extends CCIPError {
     name = 'CCIPVersionRequiresLaneError';
     /** Creates a version requires lane error. */
@@ -745,7 +1588,20 @@ export class CCIPVersionRequiresLaneError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPVersionFeatureUnavailableError extends CCIPError {
     name = 'CCIPVersionFeatureUnavailableError';
     /** Creates a version feature unavailable error. */
@@ -761,7 +1617,20 @@ export class CCIPVersionFeatureUnavailableError extends CCIPError {
     }
 }
 // Contract Validation
-/** 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 class CCIPContractNotRouterError extends CCIPError {
     name = 'CCIPContractNotRouterError';
     /** Creates a contract not router error. */
@@ -774,7 +1643,20 @@ export class CCIPContractNotRouterError extends CCIPError {
     }
 }
 // Log Data
-/** 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 class CCIPLogDataInvalidError extends CCIPError {
     name = 'CCIPLogDataInvalidError';
     /** Creates a log data invalid error. */
@@ -787,7 +1669,20 @@ export class CCIPLogDataInvalidError extends CCIPError {
     }
 }
 // Wallet
-/** 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 class CCIPWalletInvalidError extends CCIPError {
     name = 'CCIPWalletInvalidError';
     /** Creates a wallet invalid error. */
@@ -799,7 +1694,20 @@ export class CCIPWalletInvalidError extends CCIPError {
     }
 }
 // Source Chain
-/** 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 class CCIPSourceChainUnsupportedError extends CCIPError {
     name = 'CCIPSourceChainUnsupportedError';
     /** Creates a source chain unsupported error. */
@@ -812,7 +1720,22 @@ export class CCIPSourceChainUnsupportedError extends CCIPError {
     }
 }
 // Solana-specific errors
-/** 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 class CCIPBlockTimeNotFoundError extends CCIPError {
     name = 'CCIPBlockTimeNotFoundError';
     /** Creates a block time not found error. */
@@ -825,7 +1748,20 @@ export class CCIPBlockTimeNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTopicsInvalidError extends CCIPError {
     name = 'CCIPTopicsInvalidError';
     /** Creates a Solana topics invalid error. */
@@ -837,7 +1773,22 @@ export class CCIPTopicsInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSolanaRefAddressesNotFoundError extends CCIPError {
     name = 'CCIPSolanaRefAddressesNotFoundError';
     /** Creates a reference addresses not found error. */
@@ -850,7 +1801,22 @@ export class CCIPSolanaRefAddressesNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSolanaOffRampEventsNotFoundError extends CCIPError {
     name = 'CCIPSolanaOffRampEventsNotFoundError';
     /** Creates an offRamp events not found error. */
@@ -863,7 +1829,20 @@ export class CCIPSolanaOffRampEventsNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenPoolInfoNotFoundError extends CCIPError {
     name = 'CCIPTokenPoolInfoNotFoundError';
     /** Creates a token pool info not found error. */
@@ -875,7 +1854,20 @@ export class CCIPTokenPoolInfoNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSplTokenInvalidError extends CCIPError {
     name = 'CCIPSplTokenInvalidError';
     /** Creates an SPL token invalid error. */
@@ -887,7 +1879,20 @@ export class CCIPSplTokenInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenDataParseError extends CCIPError {
     name = 'CCIPTokenDataParseError';
     /** Creates a token data parse error. */
@@ -899,7 +1904,20 @@ export class CCIPTokenDataParseError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPExtraArgsLengthInvalidError extends CCIPError {
     name = 'CCIPExtraArgsLengthInvalidError';
     /** Creates an extraArgs length invalid error. */
@@ -911,7 +1929,20 @@ export class CCIPExtraArgsLengthInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSolanaExtraArgsEncodingError extends CCIPError {
     name = 'CCIPSolanaExtraArgsEncodingError';
     /** Creates a Solana extraArgs encoding error. */
@@ -922,7 +1953,20 @@ export class CCIPSolanaExtraArgsEncodingError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPLogDataMissingError extends CCIPError {
     name = 'CCIPLogDataMissingError';
     /** Creates a log data missing error. */
@@ -933,7 +1977,20 @@ export class CCIPLogDataMissingError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPExecutionStateInvalidError extends CCIPError {
     name = 'CCIPExecutionStateInvalidError';
     /** Creates an execution state invalid error. */
@@ -945,7 +2002,20 @@ export class CCIPExecutionStateInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPExecutionReportChainMismatchError extends CCIPError {
     name = 'CCIPExecutionReportChainMismatchError';
     /** Creates an execution report chain mismatch error. */
@@ -957,7 +2027,20 @@ export class CCIPExecutionReportChainMismatchError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenPoolStateNotFoundError extends CCIPError {
     name = 'CCIPTokenPoolStateNotFoundError';
     /** Creates a token pool state not found error. */
@@ -969,7 +2052,20 @@ export class CCIPTokenPoolStateNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenPoolChainConfigNotFoundError extends CCIPError {
     name = 'CCIPTokenPoolChainConfigNotFoundError';
     /** Creates a token pool chain config not found error. */
@@ -982,7 +2078,20 @@ export class CCIPTokenPoolChainConfigNotFoundError extends CCIPError {
     }
 }
 // Aptos-specific errors
-/** 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 class CCIPAptosNetworkUnknownError extends CCIPError {
     name = 'CCIPAptosNetworkUnknownError';
     /** Creates an Aptos network unknown error. */
@@ -994,7 +2103,20 @@ export class CCIPAptosNetworkUnknownError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosTransactionTypeInvalidError extends CCIPError {
     name = 'CCIPAptosTransactionTypeInvalidError';
     /** Creates an Aptos transaction type invalid error. */
@@ -1005,7 +2127,20 @@ export class CCIPAptosTransactionTypeInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosRegistryTypeInvalidError extends CCIPError {
     name = 'CCIPAptosRegistryTypeInvalidError';
     /** Creates an Aptos registry type invalid error. */
@@ -1017,7 +2152,20 @@ export class CCIPAptosRegistryTypeInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosLogInvalidError extends CCIPError {
     name = 'CCIPAptosLogInvalidError';
     /** Creates an Aptos log invalid error. */
@@ -1029,7 +2177,22 @@ export class CCIPAptosLogInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosAddressInvalidError extends CCIPError {
     name = 'CCIPAptosAddressInvalidError';
     /** Creates an Aptos address invalid error. */
@@ -1041,7 +2204,20 @@ export class CCIPAptosAddressInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosExtraArgsEncodingError extends CCIPError {
     name = 'CCIPAptosExtraArgsEncodingError';
     /** Creates an Aptos extraArgs encoding error. */
@@ -1052,7 +2228,20 @@ export class CCIPAptosExtraArgsEncodingError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosWalletInvalidError extends CCIPError {
     name = 'CCIPAptosWalletInvalidError';
     /** Creates an Aptos wallet invalid error. */
@@ -1064,7 +2253,20 @@ export class CCIPAptosWalletInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosExtraArgsV2RequiredError extends CCIPError {
     name = 'CCIPAptosExtraArgsV2RequiredError';
     /** Creates an Aptos EVMExtraArgsV2 required error. */
@@ -1075,7 +2277,20 @@ export class CCIPAptosExtraArgsV2RequiredError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosTokenNotRegisteredError extends CCIPError {
     name = 'CCIPAptosTokenNotRegisteredError';
     /** Creates an Aptos token not registered error. */
@@ -1087,7 +2302,20 @@ export class CCIPAptosTokenNotRegisteredError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosTransactionTypeUnexpectedError extends CCIPError {
     name = 'CCIPAptosTransactionTypeUnexpectedError';
     /** Creates an Aptos transaction type unexpected error. */
@@ -1099,7 +2327,20 @@ export class CCIPAptosTransactionTypeUnexpectedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosAddressModuleRequiredError extends CCIPError {
     name = 'CCIPAptosAddressModuleRequiredError';
     /** Creates an Aptos address module required error. */
@@ -1110,8 +2351,46 @@ export class CCIPAptosAddressModuleRequiredError extends CCIPError {
         });
     }
 }
+/**
+ * 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 class CCIPAptosTopicInvalidError extends CCIPError {
+    name = 'CCIPAptosTopicInvalidError';
+    /** Creates an Aptos topic invalid error. */
+    constructor(topic, options) {
+        super(CCIPErrorCode.APTOS_TOPIC_INVALID, topic ? `Unknown topic event handler="${topic}"` : 'single string topic required', {
+            ...options,
+            isTransient: false,
+            context: { ...options?.context, topic },
+        });
+    }
+}
 // Borsh
-/** Thrown when Borsh type is unknown. */
+/**
+ * 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 class CCIPBorshTypeUnknownError extends CCIPError {
     name = 'CCIPBorshTypeUnknownError';
     /** Creates a Borsh type unknown error. */
@@ -1123,7 +2402,20 @@ export class CCIPBorshTypeUnknownError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPBorshMethodUnknownError extends CCIPError {
     name = 'CCIPBorshMethodUnknownError';
     /** Creates a Borsh method unknown error. */
@@ -1136,7 +2428,20 @@ export class CCIPBorshMethodUnknownError extends CCIPError {
     }
 }
 // CLI & Validation
-/** 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 class CCIPArgumentInvalidError extends CCIPError {
     name = 'CCIPArgumentInvalidError';
     /** Creates an argument invalid error. */
@@ -1148,7 +2453,22 @@ export class CCIPArgumentInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPReceiptNotFoundError extends CCIPError {
     name = 'CCIPReceiptNotFoundError';
     /** Creates a receipt not found error. */
@@ -1161,7 +2481,20 @@ export class CCIPReceiptNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPDataParseError extends CCIPError {
     name = 'CCIPDataParseError';
     /** Creates a data parse error. */
@@ -1174,7 +2507,20 @@ export class CCIPDataParseError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenNotFoundError extends CCIPError {
     name = 'CCIPTokenNotFoundError';
     /** Creates a token not found error. */
@@ -1199,7 +2545,20 @@ export class CCIPInsufficientBalanceError extends CCIPError {
     }
 }
 // Solana-specific (additional)
-/** 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 class CCIPSolanaRouterConfigNotFoundError extends CCIPError {
     name = 'CCIPSolanaRouterConfigNotFoundError';
     /** Creates a Solana router config not found error. */
@@ -1211,7 +2570,20 @@ export class CCIPSolanaRouterConfigNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSolanaFeeResultInvalidError extends CCIPError {
     name = 'CCIPSolanaFeeResultInvalidError';
     /** Creates a Solana fee result invalid error. */
@@ -1223,7 +2595,20 @@ export class CCIPSolanaFeeResultInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenMintNotFoundError extends CCIPError {
     name = 'CCIPTokenMintNotFoundError';
     /** Creates a token mint not found error. */
@@ -1235,7 +2620,22 @@ export class CCIPTokenMintNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenMintInvalidError extends CCIPError {
     name = 'CCIPTokenMintInvalidError';
     /** Creates a token mint invalid error. */
@@ -1248,7 +2648,20 @@ export class CCIPTokenMintInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenAmountInvalidError extends CCIPError {
     name = 'CCIPTokenAmountInvalidError';
     /** Creates a token amount invalid error. */
@@ -1259,7 +2672,21 @@ export class CCIPTokenAmountInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTokenAccountNotFoundError extends CCIPError {
     name = 'CCIPTokenAccountNotFoundError';
     /** Creates a token account not found error. */
@@ -1271,7 +2698,22 @@ export class CCIPTokenAccountNotFoundError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPTransactionNotFinalizedError extends CCIPError {
     name = 'CCIPTransactionNotFinalizedError';
     /** Creates a transaction not finalized error. */
@@ -1284,7 +2726,20 @@ export class CCIPTransactionNotFinalizedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPCctpDecodeError extends CCIPError {
     name = 'CCIPCctpDecodeError';
     /** Creates a CCTP decode error. */
@@ -1296,7 +2751,20 @@ export class CCIPCctpDecodeError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSuiHasherVersionUnsupportedError extends CCIPError {
     name = 'CCIPSuiHasherVersionUnsupportedError';
     /** Creates a Sui hasher version unsupported error. */
@@ -1308,7 +2776,20 @@ export class CCIPSuiHasherVersionUnsupportedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSuiMessageVersionInvalidError extends CCIPError {
     name = 'CCIPSuiMessageVersionInvalidError';
     /** Creates a Sui message version invalid error. */
@@ -1319,10 +2800,31 @@ export class CCIPSuiMessageVersionInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSuiLogInvalidError extends CCIPError {
     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, options) {
         super(CCIPErrorCode.LOG_DATA_INVALID, `Invalid sui log: ${String(log)}`, {
             ...options,
@@ -1331,7 +2833,20 @@ export class CCIPSuiLogInvalidError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSolanaLaneVersionUnsupportedError extends CCIPError {
     name = 'CCIPSolanaLaneVersionUnsupportedError';
     /** Creates a Solana lane version unsupported error. */
@@ -1343,7 +2858,20 @@ export class CCIPSolanaLaneVersionUnsupportedError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPCctpMultipleEventsError extends CCIPError {
     name = 'CCIPCctpMultipleEventsError';
     /** Creates a CCTP multiple events error. */
@@ -1355,7 +2883,20 @@ export class CCIPCctpMultipleEventsError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPSolanaComputeUnitsExceededError extends CCIPError {
     name = 'CCIPSolanaComputeUnitsExceededError';
     /** Creates a compute units exceeded error. */
@@ -1367,7 +2908,20 @@ export class CCIPSolanaComputeUnitsExceededError extends CCIPError {
         });
     }
 }
-/** 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 class CCIPAptosHasherVersionUnsupportedError extends CCIPError {
     name = 'CCIPAptosHasherVersionUnsupportedError';
     /** Creates an Aptos hasher version unsupported error. */
@@ -1380,7 +2934,21 @@ export class CCIPAptosHasherVersionUnsupportedError extends CCIPError {
     }
 }
 // API Client
-/** 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 class CCIPApiClientNotAvailableError extends CCIPError {
     name = 'CCIPApiClientNotAvailableError';
     /**
@@ -1391,15 +2959,24 @@ export class CCIPApiClientNotAvailableError extends CCIPError {
         super(CCIPErrorCode.API_CLIENT_NOT_AVAILABLE, 'CCIP API client is not available. Initialize with an apiClient or remove the explicit opt-out (apiClient: null).', { ...options, isTransient: false });
     }
 }
-/** 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 class CCIPUnexpectedPaginationError extends CCIPError {
     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, messageCount, options) {
         super(CCIPErrorCode.API_UNEXPECTED_PAGINATION, `Transaction ${txHash} contains more CCIP messages than expected (${messageCount}+ returned with hasNextPage=true)`, {
             ...options,
@@ -1409,7 +2986,22 @@ export class CCIPUnexpectedPaginationError extends CCIPError {
     }
 }
 // Viem Adapter
-/** 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 class CCIPViemAdapterError extends CCIPError {
     name = 'CCIPViemAdapterError';
     /**