@chainlink/ccip-sdk 0.96.0 → 1.0.0

package/src/commits.ts

@@ -2,33 +2,33 @@ import type { PickDeep } from 'type-fest'
 
 import type { Chain, ChainStatic, LogFilter } from './chain.ts'
 import { CCIPCommitNotFoundError } from './errors/index.ts'
-import { type CCIPCommit, type CCIPRequest, CCIPVersion } from './types.ts'
+import { type CCIPRequest, type CCIPVerifications, CCIPVersion } from './types.ts'
 
 /**
  * Look for a CommitReport at dest for given CCIPRequest
  * Provides a basic/generic implementation, but subclasses of Chain may override with more specific
- * logic in Chain.getCommitReport method
+ * logic in Chain.getVerifications method
  *
  * @param dest - Destination network provider
- * @param commitStore - Commit store address
+ * @param offRamp - Commit store address
  * @param request - CCIP request info
  * @param hints - Additional filtering hints
  * @returns CCIP commit info
  **/
-export async function getCommitReport(
+export async function getOnchainCommitReport(
   dest: Chain,
-  commitStore: string,
+  offRamp: string,
   {
     lane,
     message,
     tx: { timestamp: requestTimestamp },
-  }: PickDeep<CCIPRequest, 'lane' | 'message.sequenceNumber' | 'tx.timestamp'>,
-  hints?: Pick<LogFilter, 'page' | 'watch'> & { startBlock?: number },
-): Promise<CCIPCommit> {
+  }: PickDeep<CCIPRequest, 'lane' | `message.${'sequenceNumber' | 'messageId'}` | 'tx.timestamp'>,
+  hints?: Pick<LogFilter, 'page' | 'watch' | 'startBlock'>,
+): Promise<CCIPVerifications> {
   for await (const log of dest.getLogs({
     ...hints,
     ...(!hints?.startBlock ? { startTime: requestTimestamp } : { startBlock: hints.startBlock }),
-    address: commitStore,
+    address: offRamp,
     topics: [lane.version < CCIPVersion.V1_6 ? 'ReportAccepted' : 'CommitReportAccepted'],
   })) {
     const reports = (dest.constructor as ChainStatic).decodeCommits(log, lane)

package/src/errors/CCIPError.ts

@@ -41,7 +41,13 @@ export class CCIPError extends Error {
 
   override readonly name: string = 'CCIPError'
 
-  /** Creates CCIPError with code, message, and options. */
+  /**
+   * Creates a CCIPError with code, message, and options.
+   *
+   * @param code - Machine-readable error code
+   * @param message - Human-readable error message
+   * @param options - Additional error options (cause, context, isTransient, etc.)
+   */
   constructor(code: CCIPErrorCode, message: string, options?: CCIPErrorOptions) {
     super(message, { cause: options?.cause })
     Object.setPrototypeOf(this, new.target.prototype)
@@ -55,7 +61,15 @@ export class CCIPError extends Error {
     Error.captureStackTrace(this, this.constructor)
   }
 
-  /** Type guard. Prefer over instanceof (handles dual package hazard). */
+  /**
+   * Type guard for CCIPError.
+   *
+   * Prefer this over `instanceof` to handle the dual package hazard
+   * when multiple versions of the SDK may be present.
+   *
+   * @param error - The error to check
+   * @returns True if the error is a CCIPError instance
+   */
   static isCCIPError(error: unknown): error is CCIPError {
     return (
       error instanceof CCIPError ||
@@ -63,7 +77,15 @@ export class CCIPError extends Error {
     )
   }
 
-  /** Wrap unknown catch value in CCIPError. */
+  /**
+   * Wraps an unknown caught value in a CCIPError.
+   *
+   * Useful for normalizing errors in catch blocks.
+   *
+   * @param error - The error to wrap
+   * @param code - Optional error code (defaults to 'UNKNOWN')
+   * @returns A CCIPError wrapping the original error
+   */
   static from(error: unknown, code?: CCIPErrorCode): CCIPError {
     if (error instanceof CCIPError) return error
     if (error instanceof Error) {
@@ -72,7 +94,14 @@ export class CCIPError extends Error {
     return new CCIPError(code ?? 'UNKNOWN', String(error))
   }
 
-  /** Serialize for logging (JSON.stringify loses non-enumerable props). */
+  /**
+   * Serializes the error for logging.
+   *
+   * Use this instead of `JSON.stringify(error)` directly, as Error properties
+   * are non-enumerable and would be lost.
+   *
+   * @returns An object containing all error properties
+   */
   toJSON(): Record<string, unknown> {
     return {
       name: this.name,

package/src/errors/codes.ts

@@ -4,6 +4,7 @@ export const CCIPErrorCode = {
   CHAIN_NOT_FOUND: 'CHAIN_NOT_FOUND',
   CHAIN_SELECTOR_NOT_FOUND: 'CHAIN_SELECTOR_NOT_FOUND',
   CHAIN_FAMILY_UNSUPPORTED: 'CHAIN_FAMILY_UNSUPPORTED',
+  NETWORK_FAMILY_UNSUPPORTED: 'NETWORK_FAMILY_UNSUPPORTED',
   METHOD_UNSUPPORTED: 'METHOD_UNSUPPORTED',
   CHAIN_FAMILY_MISMATCH: 'CHAIN_FAMILY_MISMATCH',
   APTOS_NETWORK_UNKNOWN: 'APTOS_NETWORK_UNKNOWN',
@@ -90,6 +91,7 @@ export const CCIPErrorCode = {
   TOKEN_POOL_STATE_NOT_FOUND: 'TOKEN_POOL_STATE_NOT_FOUND',
   TOKEN_POOL_INFO_NOT_FOUND: 'TOKEN_POOL_INFO_NOT_FOUND',
   TOKEN_ACCOUNT_NOT_FOUND: 'TOKEN_ACCOUNT_NOT_FOUND',
+  LEGACY_TOKEN_POOLS_UNSUPPORTED: 'LEGACY_TOKEN_POOLS_UNSUPPORTED',
 
   // Wallet & Signer
   WALLET_NOT_SIGNER: 'WALLET_NOT_SIGNER',
@@ -136,6 +138,7 @@ export const CCIPErrorCode = {
   APTOS_TX_TYPE_UNEXPECTED: 'APTOS_TX_TYPE_UNEXPECTED',
   APTOS_ADDRESS_MODULE_REQUIRED: 'APTOS_ADDRESS_MODULE_REQUIRED',
   APTOS_HASHER_VERSION_UNSUPPORTED: 'APTOS_HASHER_VERSION_UNSUPPORTED',
+  APTOS_TOPIC_INVALID: 'APTOS_TOPIC_INVALID',
 
   // HTTP & RPC
   HTTP_ERROR: 'HTTP_ERROR',
@@ -173,7 +176,6 @@ export const TRANSIENT_ERROR_CODES = new Set<CCIPErrorCode>([
   CCIPErrorCode.TRANSACTION_NOT_FOUND,
   CCIPErrorCode.BLOCK_TIME_NOT_FOUND,
   CCIPErrorCode.TRANSACTION_NOT_FINALIZED,
-  CCIPErrorCode.MESSAGE_NOT_FOUND_IN_TX,
   CCIPErrorCode.MESSAGE_ID_NOT_FOUND,
   CCIPErrorCode.MESSAGE_BATCH_INCOMPLETE,
   CCIPErrorCode.COMMIT_NOT_FOUND,

package/src/errors/index.ts

@@ -10,6 +10,7 @@ export {
   CCIPChainFamilyUnsupportedError,
   CCIPChainNotFoundError,
   CCIPMethodUnsupportedError,
+  CCIPNetworkFamilyUnsupportedError,
 } from './specialized.ts'
 
 // Specialized errors - Block & Transaction
@@ -67,6 +68,7 @@ export { CCIPExtraArgsInvalidError, CCIPExtraArgsParseError } from './specialize
 
 // Specialized errors - Token & Registry
 export {
+  CCIPLegacyTokenPoolsUnsupportedError,
   CCIPTokenDecimalsInsufficientError,
   CCIPTokenNotConfiguredError,
   CCIPTokenNotFoundError,
@@ -135,6 +137,7 @@ export {
   CCIPAptosNetworkUnknownError,
   CCIPAptosRegistryTypeInvalidError,
   CCIPAptosTokenNotRegisteredError,
+  CCIPAptosTopicInvalidError,
   CCIPAptosTransactionInvalidError,
   CCIPAptosTransactionTypeInvalidError,
   CCIPAptosTransactionTypeUnexpectedError,
@@ -144,6 +147,7 @@ export {
 // Specialized errors - Sui-specific
 export {
   CCIPSuiHasherVersionUnsupportedError,
+  CCIPSuiLogInvalidError,
   CCIPSuiMessageVersionInvalidError,
 } from './specialized.ts'
 

package/src/errors/recovery.ts

@@ -8,6 +8,8 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
     'Verify the chain selector is valid. Use networkInfo() to look up selectors.',
   CHAIN_FAMILY_UNSUPPORTED:
     'This chain family is not supported. Check the method documentation for supported chain families.',
+  NETWORK_FAMILY_UNSUPPORTED:
+    'This network family is not supported. Supported families: evm, solana, aptos, sui, ton.',
   CHAIN_FAMILY_MISMATCH:
     'Use the correct Chain class for this chain family (e.g., EVMChain for EVM, SolanaChain for Solana).',
   METHOD_UNSUPPORTED:
@@ -25,7 +27,7 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
     'Ensure the data is a valid CCIPSendRequested event log. Check the transaction on the source chain explorer.',
   MESSAGE_CCIP_DECODE_FAILED:
     'Ensure the log data is from a CCIPSendRequested event. Verify the source chain and transaction hash.',
-  MESSAGE_NOT_FOUND_IN_TX: 'No CCIPSendRequested event found. Verify the transaction hash.',
+  MESSAGE_NOT_FOUND_IN_TX: 'No CCIP request event found in tx. Verify the transaction hash.',
   MESSAGE_ID_NOT_FOUND: 'Wait and retry. The message may still be in transit (5-20 min typical).',
   MESSAGE_ID_INVALID:
     'Verify the message ID format. Must be a valid 32-byte hex string (0x-prefixed, 64 hex chars).',
@@ -110,6 +112,8 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
     'Check that the token pool is deployed and configured for this lane. Verify supported tokens: https://docs.chain.link/ccip/directory',
   TOKEN_ACCOUNT_NOT_FOUND:
     'The token account does not exist for this holder. The holder has never held this token. You may treat this as zero balance.',
+  LEGACY_TOKEN_POOLS_UNSUPPORTED:
+    'Legacy token pools (CCIP <1.5) are not supported. Upgrade to CCIP 1.5+ token pools.',
 
   WALLET_NOT_SIGNER: 'Provide a wallet with signing capability (Signer interface).',
   WALLET_INVALID: 'Provide a valid Wallet instance.',
@@ -159,6 +163,8 @@ export const DEFAULT_RECOVERY_HINTS: Partial<Record<CCIPErrorCode, string>> = {
     'Check that the transaction is a standard user transaction, not a script or module deployment.',
   APTOS_ADDRESS_MODULE_REQUIRED: 'Provide an address with module for Aptos log filtering.',
   APTOS_HASHER_VERSION_UNSUPPORTED: 'This hasher version is not supported for Aptos.',
+  APTOS_TOPIC_INVALID:
+    'Invalid Aptos event topic. Ensure the topic matches a known CCIP event type.',
 
   HTTP_ERROR: 'HTTP request failed. 429 indicates rate limiting.',
   RPC_NOT_FOUND: 'No RPC endpoint found. Configure an RPC URL.',