@chainlink/ccip-sdk 0.96.0 → 1.0.0

package/src/types.ts

@@ -1,13 +1,13 @@
 import type { AbiParametersToPrimitiveTypes, ExtractAbiEvent } from 'abitype'
-import type { BytesLike, Log } from 'ethers'
+import type { BytesLike, Log as EVMLog } from 'ethers'
+import type { SetOptional } from 'type-fest'
 
 import type { APICCIPRequestMetadata } from './api/types.ts'
 import type OffRamp_1_6_ABI from './evm/abi/OffRamp_1_6.ts'
-import type { CCIPMessage_EVM, CCIPMessage_V1_6_EVM } from './evm/messages.ts'
+import type { CCIPMessage_EVM, CCIPMessage_V1_6_EVM, CCIPMessage_V2_0 } from './evm/messages.ts'
 import type { ExtraArgs } from './extra-args.ts'
 import type { CCIPMessage_V1_6_Solana } from './solana/types.ts'
 import type { CCIPMessage_V1_6_Sui } from './sui/types.ts'
-import type { CCIPMessage_V1_6_TON } from './ton/types.ts'
 // v1.6 Base type from EVM contains the intersection of all other CCIPMessage v1.6 types
 export type { CCIPMessage_V1_6 } from './evm/messages.ts'
 
@@ -88,6 +88,7 @@ export const CCIPVersion = {
   V1_2: '1.2.0',
   V1_5: '1.5.0',
   V1_6: '1.6.0',
+  V2_0: '2.0.0',
 } as const
 /** Type representing one of the supported CCIP versions. */
 export type CCIPVersion = (typeof CCIPVersion)[keyof typeof CCIPVersion]
@@ -153,20 +154,23 @@ export interface Lane<V extends CCIPVersion = CCIPVersion> {
 /**
  * Union type representing a CCIP message across different versions and chain families.
  */
-export type CCIPMessage<V extends CCIPVersion = CCIPVersion> = V extends
-  | typeof CCIPVersion.V1_2
-  | typeof CCIPVersion.V1_5
-  ? CCIPMessage_EVM<V>
-  : CCIPMessage_V1_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui | CCIPMessage_V1_6_TON
+export type CCIPMessage<V extends CCIPVersion = CCIPVersion> = V extends typeof CCIPVersion.V2_0
+  ? CCIPMessage_V2_0
+  : V extends typeof CCIPVersion.V1_6
+    ? CCIPMessage_V1_6_EVM | CCIPMessage_V1_6_Solana | CCIPMessage_V1_6_Sui
+    : CCIPMessage_EVM<V>
 
 /**
  * Generic log structure compatible across chain families.
  */
-export type Log_ = Pick<Log, 'topics' | 'index' | 'address' | 'blockNumber' | 'transactionHash'> & {
+export type ChainLog = Pick<
+  EVMLog,
+  'topics' | 'index' | 'address' | 'blockNumber' | 'transactionHash'
+> & {
   /** Log data as bytes or parsed object. */
   data: BytesLike | Record<string, unknown>
   /** Optional reference to the containing transaction. */
-  tx?: ChainTransaction
+  tx?: SetOptional<ChainTransaction, 'logs'>
 }
 
 /**
@@ -187,7 +191,7 @@ export type ChainTransaction = {
   /** Transaction hash. */
   hash: string
   /** Logs emitted by this transaction. */
-  logs: readonly Log_[]
+  logs: readonly ChainLog[]
   /** Block number containing this transaction. */
   blockNumber: number
   /** Unix timestamp of the block. */
@@ -204,12 +208,10 @@ export type ChainTransaction = {
 export interface CCIPRequest<V extends CCIPVersion = CCIPVersion> {
   /** Lane configuration for this request. */
   lane: Lane<V>
-  /** The CCIP message being sent. */
   message: CCIPMessage<V>
-  /** Log event from the OnRamp. */
-  log: Log_
+  log: ChainLog
   /** Transaction that emitted the request. */
-  tx: Pick<ChainTransaction, 'hash' | 'logs' | 'blockNumber' | 'timestamp' | 'from' | 'error'>
+  tx: Omit<ChainTransaction, 'logs'>
 
   /**
    * API-enriched metadata. Present only when fetched via CCIP API.
@@ -236,22 +238,47 @@ export interface CCIPRequest<V extends CCIPVersion = CCIPVersion> {
 }
 
 /**
- * Commit report structure from the OffRamp CommitReportAccepted event.
+ * OnChain Commit report structure from the OffRamp CommitReportAccepted event.
  */
 export type CommitReport = AbiParametersToPrimitiveTypes<
   ExtractAbiEvent<typeof OffRamp_1_6_ABI, 'CommitReportAccepted'>['inputs']
 >[0][number]
 
 /**
- * CCIP commit information containing the report and its log.
+ * OffChain Verification result for a CCIP v2.0 message, returned by the indexer API.
  */
-export interface CCIPCommit {
-  /** The commit report data. */
-  report: CommitReport
-  /** Log event from the commit. */
-  log: Log_
+export type VerifierResult = {
+  /** Verification data required for destination execution (e.g. signatures). */
+  ccvData: BytesLike
+  /** Source CCV contract address. */
+  sourceAddress: string
+  /** Destination CCV contract address. */
+  destAddress: string
+  /** Timestamp of the attestation (Unix seconds). */
+  timestamp?: number
 }
 
+/**
+ * Verification data for a ccip message (onchain CommitReport, or offchain Verifications)
+ */
+export type CCIPVerifications =
+  | {
+      /** The commit report data. */
+      report: CommitReport
+      /** Log event from the commit. */
+      log: ChainLog
+    }
+  | {
+      /** Policy for this request */
+      verificationPolicy: {
+        optionalCCVs: readonly string[]
+        requiredCCVs: readonly string[]
+        optionalThreshold: number
+      }
+      /** Verifications array; one for each requiredCCV is needed for exec */
+      verifications: VerifierResult[]
+    }
+
 /**
  * Enumeration of possible execution states for a CCIP message.
  */
@@ -287,7 +314,11 @@ export const MessageStatus = {
   Verifying: 'VERIFYING',
   /** Message has been verified by the CCIP network */
   Verified: 'VERIFIED',
-  /** Unknown status returned by API */
+  /**
+   * API returned an unrecognized status value.
+   * This typically means the CCIP API has new status values that this SDK version
+   * doesn't recognize. Consider updating to the latest SDK version.
+   */
   Unknown: 'UNKNOWN',
 } as const
 /** Type representing a CCIP message lifecycle status. */
@@ -345,7 +376,7 @@ export interface CCIPExecution {
   /** Execution receipt data. */
   receipt: ExecutionReceipt
   /** Log event from the execution. */
-  log: Log_
+  log: ChainLog
   /** Unix timestamp of the execution. */
   timestamp: number
 }
@@ -369,18 +400,26 @@ export type OffchainTokenData = { _tag: string; [k: string]: BytesLike } | undef
  * }
  * ```
  */
-export type ExecutionReport<M extends CCIPMessage = CCIPMessage> = {
-  /** The CCIP message to execute. */
-  message: M
-  /** Merkle proofs for the message. */
-  proofs: readonly BytesLike[]
-  /** Bit flags for proof verification. */
-  proofFlagBits: bigint
-  /** Merkle root for verification. */
-  merkleRoot: string
-  /** Offchain token data for each token transfer. */
-  offchainTokenData: readonly OffchainTokenData[]
-}
+export type ExecutionInput<M extends CCIPMessage = CCIPMessage> =
+  M extends CCIPMessage<typeof CCIPVersion.V2_0>
+    ? {
+        /** encodedMessage as per CCIPv2 codec */
+        encodedMessage: M['encodedMessage']
+        /** Off-Chain verifications containing verifierResults' ccvData and ccvs addresses */
+        verifications: Pick<VerifierResult, 'ccvData' | 'destAddress'>[]
+      }
+    : {
+        /** The CCIP message to execute. */
+        message: M
+        /** Merkle proofs for the message. */
+        proofs: readonly BytesLike[]
+        /** Bit flags for proof verification. */
+        proofFlagBits: bigint
+        /** Merkle root for verification. */
+        merkleRoot: string
+        /** Offchain token data for each token transfer. */
+        offchainTokenData: readonly OffchainTokenData[]
+      }
 
 /**
  * A message to be sent to another network.
@@ -396,7 +435,12 @@ export type ExecutionReport<M extends CCIPMessage = CCIPMessage> = {
  * ```
  */
 export type AnyMessage = {
-  /** Receiver address on the destination chain. */
+  /**
+   * Receiver address on the destination chain.
+   * Must be a valid address for the destination chain family. For instance:
+   * - EVM: 20-byte hex (e.g., `0x6d1af98d635d3121286ddda1a0c2d7078b1523ed`)
+   * - Solana: Base58 public key (e.g., `7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV`)
+   */
   receiver: BytesLike
   /** Extra arguments for gas limits and other settings. */
   extraArgs: ExtraArgs

package/src/utils.ts

@@ -131,6 +131,23 @@ const networkInfoFromChainId = memoize((chainId: NetworkInfo['chainId']): Networ
  *   - Chain name as string ("ethereum-mainnet")
  * @returns Complete NetworkInfo object
  * @throws {@link CCIPChainNotFoundError} if chain is not found
+ *
+ * @example
+ * ```typescript
+ * import { networkInfo } from '@chainlink/ccip-sdk'
+ *
+ * // By chain name
+ * const sepolia = networkInfo('ethereum-testnet-sepolia')
+ * console.log('Selector:', sepolia.chainSelector)
+ *
+ * // By chain selector
+ * const fuji = networkInfo(14767482510784806043n)
+ * console.log('Name:', fuji.name) // 'avalanche-testnet-fuji'
+ *
+ * // By chain ID
+ * const mainnet = networkInfo(1)
+ * console.log('Family:', mainnet.family) // 'EVM'
+ * ```
  */
 export const networkInfo = memoize(function networkInfo_(
   selectorOrIdOrName: bigint | number | string,
@@ -206,6 +223,15 @@ export function* blockRangeGenerator(
  * @param _key - Property key (unused).
  * @param value - Value to transform.
  * @returns String representation if BigInt, otherwise unchanged value.
+ * @example
+ * ```typescript
+ * import { bigIntReplacer } from '@chainlink/ccip-sdk'
+ *
+ * const data = { amount: 1000000000000000000n }
+ * const json = JSON.stringify(data, bigIntReplacer)
+ * console.log(json) // '{"amount":"1000000000000000000"}'
+ * ```
+ * @see {@link bigIntReviver} - Revive BigInt values when parsing
  */
 export function bigIntReplacer(_key: string, value: unknown): unknown {
   if (typeof value === 'bigint') {
@@ -219,6 +245,15 @@ export function bigIntReplacer(_key: string, value: unknown): unknown {
  * @param _key - Property key (unused).
  * @param value - Value to transform.
  * @returns BigInt if numeric string, otherwise unchanged value.
+ * @example
+ * ```typescript
+ * import { bigIntReviver } from '@chainlink/ccip-sdk'
+ *
+ * const json = '{"amount":"1000000000000000000"}'
+ * const data = JSON.parse(json, bigIntReviver)
+ * console.log(typeof data.amount) // 'bigint'
+ * ```
+ * @see {@link bigIntReplacer} - Stringify BigInt values
  */
 export function bigIntReviver(_key: string, value: unknown): unknown {
   if (typeof value === 'string' && /^\d+$/.test(value)) {
@@ -238,11 +273,25 @@ export function parseJson<T = unknown>(text: string): T {
 }
 
 /**
- * Decode address from a 32-byte hex string
- * @param address - Address bytes to decode
+ * Decode address from a 32-byte hex string.
+ *
+ * @param address - Address bytes to decode (hex string or Uint8Array)
  * @param family - Chain family for address format (defaults to EVM)
  * @returns Decoded address string
  * @throws {@link CCIPChainFamilyUnsupportedError} if chain family is not supported
+ *
+ * @example
+ * ```typescript
+ * import { decodeAddress, ChainFamily } from '@chainlink/ccip-sdk'
+ *
+ * // Decode EVM address from 32-byte hex
+ * const evmAddr = decodeAddress('0x000000000000000000000000abc123...', ChainFamily.EVM)
+ * console.log(evmAddr) // '0xABC123...'
+ *
+ * // Decode Solana address
+ * const solAddr = decodeAddress(bytes, ChainFamily.Solana)
+ * console.log(solAddr) // Base58 encoded address
+ * ```
  */
 export function decodeAddress(address: BytesLike, family: ChainFamily = ChainFamily.EVM): string {
   const chain = supportedChains[family]
@@ -320,6 +369,20 @@ export function isBase64(data: unknown): data is string {
  * @param data - Bytes, number array, or Base64 string.
  * @returns Uint8Array representation.
  * @throws {@link CCIPDataFormatUnsupportedError} if data format is not recognized
+ *
+ * @example
+ * ```typescript
+ * import { getDataBytes } from '@chainlink/ccip-sdk'
+ *
+ * // From hex string
+ * const bytes1 = getDataBytes('0x1234abcd')
+ *
+ * // From number array
+ * const bytes2 = getDataBytes([0x12, 0x34, 0xab, 0xcd])
+ *
+ * // From Base64
+ * const bytes3 = getDataBytes('EjSrzQ==')
+ * ```
  */
 export function getDataBytes(data: BytesLike | readonly number[]): Uint8Array {
   if (Array.isArray(data)) return new Uint8Array(data)
@@ -369,6 +432,14 @@ export function getAddressBytes(address: BytesLike | readonly number[]): Uint8Ar
           ? '0x' + address
           : address,
     )
+  } else if (typeof address === 'string' && /^-?\d+:[0-9a-f]{64}$/i.test(address)) {
+    // TON raw format: "workchain:hash" → 36-byte CCIP format (4-byte BE workchain + 32-byte hash)
+    const [workchain, hash] = address.split(':')
+    const buf = new Uint8Array(36)
+    const view = new DataView(buf.buffer)
+    view.setInt32(0, parseInt(workchain!, 10), false) // big-endian
+    buf.set(getBytes('0x' + hash), 4)
+    bytes = buf
   } else {
     try {
       const bytes_ = bs58.decode(address as string)

package/dist/aptos/utils.d.ts

@@ -1,12 +0,0 @@
-import { type BigNumberish, type BytesLike } from 'ethers';
-/**
- * Encodes a numeric value as a 32-byte hex string.
- * @param value - Numeric value to encode.
- * @returns 32-byte hex string representation of the value.
- */
-export declare const encodeNumber: (value: BigNumberish) => string;
-/**
- * Encodes dynamic bytes without the struct offset prefix.
- */
-export declare const encodeRawBytes: (value: BytesLike) => string;
-//# sourceMappingURL=utils.d.ts.map

package/dist/aptos/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/aptos/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,SAAS,EAKf,MAAM,QAAQ,CAAA;AAEf;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,YAAY,KAAG,MAA4B,CAAA;AAE/E;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,SAAS,KAAG,MAI9C,CAAA"}

package/dist/aptos/utils.js

@@ -1,15 +0,0 @@
-import { concat, dataLength, toBeHex, zeroPadBytes, } from 'ethers';
-/**
- * Encodes a numeric value as a 32-byte hex string.
- * @param value - Numeric value to encode.
- * @returns 32-byte hex string representation of the value.
- */
-export const encodeNumber = (value) => toBeHex(value, 32);
-/**
- * Encodes dynamic bytes without the struct offset prefix.
- */
-export const encodeRawBytes = (value) => concat([
-    encodeNumber(dataLength(value)),
-    zeroPadBytes(value, Math.ceil(dataLength(value) / 32) * 32),
-]);
-//# sourceMappingURL=utils.js.map

package/dist/aptos/utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/aptos/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EACN,UAAU,EACV,OAAO,EACP,YAAY,GACb,MAAM,QAAQ,CAAA;AAEf;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAmB,EAAU,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;AAE/E;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAgB,EAAU,EAAE,CACzD,MAAM,CAAC;IACL,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/B,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;CAC5D,CAAC,CAAA"}

package/src/aptos/utils.ts

@@ -1,24 +0,0 @@
-import {
-  type BigNumberish,
-  type BytesLike,
-  concat,
-  dataLength,
-  toBeHex,
-  zeroPadBytes,
-} from 'ethers'
-
-/**
- * Encodes a numeric value as a 32-byte hex string.
- * @param value - Numeric value to encode.
- * @returns 32-byte hex string representation of the value.
- */
-export const encodeNumber = (value: BigNumberish): string => toBeHex(value, 32)
-
-/**
- * Encodes dynamic bytes without the struct offset prefix.
- */
-export const encodeRawBytes = (value: BytesLike): string =>
-  concat([
-    encodeNumber(dataLength(value)),
-    zeroPadBytes(value, Math.ceil(dataLength(value) / 32) * 32),
-  ])