@chainlink/ccip-sdk 0.95.0 → 0.96.0

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { AbiParametersToPrimitiveTypes, ExtractAbiEvent } from 'abitype'
 import type { BytesLike, Log } from 'ethers'
 
+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 { ExtraArgs } from './extra-args.ts'
@@ -104,6 +105,17 @@ type ChainFamilyWithId<F extends ChainFamily> = F extends
 
 /**
  * Network information including chain selector and metadata.
+ *
+ * @example
+ * ```typescript
+ * const info: NetworkInfo = {
+ *   chainSelector: 16015286601757825753n,
+ *   name: 'ethereum-testnet-sepolia',
+ *   networkType: 'TESTNET',
+ *   family: 'EVM',
+ *   chainId: 11155111,
+ * }
+ * ```
  */
 export type NetworkInfo<F extends ChainFamily = ChainFamily> = {
   /** Unique chain selector used by CCIP. */
@@ -116,6 +128,16 @@ export type NetworkInfo<F extends ChainFamily = ChainFamily> = {
 
 /**
  * CCIP lane configuration connecting source and destination chains.
+ *
+ * @example
+ * ```typescript
+ * const lane: Lane = {
+ *   sourceChainSelector: 16015286601757825753n, // Ethereum Sepolia
+ *   destChainSelector: 12532609583862916517n,   // Polygon Mumbai
+ *   onRamp: '0x1234...abcd',
+ *   version: '1.6.0',
+ * }
+ * ```
  */
 export interface Lane<V extends CCIPVersion = CCIPVersion> {
   /** Source chain selector. */
@@ -149,6 +171,17 @@ export type Log_ = Pick<Log, 'topics' | 'index' | 'address' | 'blockNumber' | 't
 
 /**
  * Generic transaction structure compatible across chain families.
+ *
+ * @example
+ * ```typescript
+ * const tx: ChainTransaction = {
+ *   hash: '0xabc123...',
+ *   logs: [],
+ *   blockNumber: 12345678,
+ *   timestamp: 1704067200,
+ *   from: '0x1234...abcd',
+ * }
+ * ```
  */
 export type ChainTransaction = {
   /** Transaction hash. */
@@ -177,6 +210,29 @@ export interface CCIPRequest<V extends CCIPVersion = CCIPVersion> {
   log: Log_
   /** Transaction that emitted the request. */
   tx: Pick<ChainTransaction, 'hash' | 'logs' | 'blockNumber' | 'timestamp' | 'from' | 'error'>
+
+  /**
+   * API-enriched metadata. Present only when fetched via CCIP API.
+   *
+   * @remarks
+   * When a request is fetched using {@link Chain.getMessageById} or as a fallback
+   * in {@link Chain.getMessagesInTx}, this field contains additional information
+   * including message status, execution details, and network info.
+   *
+   * When constructed from on-chain data only, this field is `undefined`.
+   *
+   * @example
+   * ```typescript
+   * const request = await chain.getMessageById(messageId)
+   * if (request.metadata) {
+   *   console.log('Status:', request.metadata.status)
+   *   console.log('Delivery time:', request.metadata.deliveryTime)
+   * }
+   * ```
+   *
+   * @see {@link APICCIPRequestMetadata}
+   */
+  metadata?: APICCIPRequestMetadata
 }
 
 /**
@@ -254,6 +310,16 @@ export type IntentStatus = (typeof IntentStatus)[keyof typeof IntentStatus]
 
 /**
  * Receipt of a CCIP message execution on the destination chain.
+ *
+ * @example
+ * ```typescript
+ * const receipt: ExecutionReceipt = {
+ *   messageId: '0xabc123...',
+ *   sequenceNumber: 42n,
+ *   state: ExecutionState.Success,
+ *   sourceChainSelector: 16015286601757825753n,
+ * }
+ * ```
  */
 export type ExecutionReceipt = {
   /** Unique message identifier. */
@@ -291,6 +357,17 @@ export type OffchainTokenData = { _tag: string; [k: string]: BytesLike } | undef
 
 /**
  * Execution report containing message, proofs, and offchain token data.
+ *
+ * @example
+ * ```typescript
+ * const report: ExecutionReport = {
+ *   message: { messageId: '0x...', ... },
+ *   proofs: ['0xproof1...', '0xproof2...'],
+ *   proofFlagBits: 0n,
+ *   merkleRoot: '0xroot...',
+ *   offchainTokenData: [],
+ * }
+ * ```
  */
 export type ExecutionReport<M extends CCIPMessage = CCIPMessage> = {
   /** The CCIP message to execute. */
@@ -307,6 +384,16 @@ export type ExecutionReport<M extends CCIPMessage = CCIPMessage> = {
 
 /**
  * A message to be sent to another network.
+ *
+ * @example
+ * ```typescript
+ * const message: AnyMessage = {
+ *   receiver: '0x1234...abcd',
+ *   extraArgs: { gasLimit: 200_000n, allowOutOfOrderExecution: true },
+ *   data: '0xdeadbeef',
+ *   tokenAmounts: [{ token: '0xtoken...', amount: 1000000n }],
+ * }
+ * ```
  */
 export type AnyMessage = {
   /** Receiver address on the destination chain. */
@@ -322,7 +409,22 @@ export type AnyMessage = {
 }
 
 /**
- * Partial [[AnyMessage]], which populates default fields like `extraArgs` if needed
+ * Partial {@link AnyMessage}, which populates default fields like `extraArgs` if needed.
+ *
+ * @example
+ * ```typescript
+ * // Minimal input - only receiver required, defaults applied for extraArgs
+ * const input: MessageInput = {
+ *   receiver: '0x1234...abcd',
+ * }
+ *
+ * // With custom gas limit
+ * const inputWithGas: MessageInput = {
+ *   receiver: '0x1234...abcd',
+ *   extraArgs: { gasLimit: 500_000n },
+ *   data: '0xdeadbeef',
+ * }
+ * ```
  */
 export type MessageInput = Partial<AnyMessage> & {
   receiver: AnyMessage['receiver']

package/src/utils.ts

@@ -38,7 +38,8 @@ import { type NetworkInfo, type WithLogger, ChainFamily } from './types.ts'
  * @param timestamp - target timestamp
  * @param precision - returned blockNumber should be within this many blocks before timestamp
  * @returns blockNumber of a block at provider which is close but before target timestamp
- **/
+ * @throws {@link CCIPBlockBeforeTimestampNotFoundError} if no block exists before the given timestamp
+ */
 export async function getSomeBlockNumberBefore(
   getBlockTimestamp: (blockNumber: number) => Promise<number>,
   recentBlockNumber: number,
@@ -106,9 +107,9 @@ export async function getSomeBlockNumberBefore(
 }
 
 /**
- * Checks if a chain is a testnet
+ * Converts a chain ID to complete NetworkInfo.
+ * Memoized to return the same object reference for a given chainId.
  */
-// memoized so we always output the same object for a given chainId
 const networkInfoFromChainId = memoize((chainId: NetworkInfo['chainId']): NetworkInfo => {
   const sel = SELECTORS[chainId]
   if (!sel?.name) throw new CCIPChainNotFoundError(chainId)
@@ -129,6 +130,7 @@ const networkInfoFromChainId = memoize((chainId: NetworkInfo['chainId']): Networ
  *   - Chain ID as number, bigint or string (EVM: "1", Aptos: "aptos:1", Solana: genesisHash)
  *   - Chain name as string ("ethereum-mainnet")
  * @returns Complete NetworkInfo object
+ * @throws {@link CCIPChainNotFoundError} if chain is not found
  */
 export const networkInfo = memoize(function networkInfo_(
   selectorOrIdOrName: bigint | number | string,
@@ -237,7 +239,11 @@ export function parseJson<T = unknown>(text: string): T {
 
 /**
  * Decode address from a 32-byte hex string
- **/
+ * @param address - Address bytes to decode
+ * @param family - Chain family for address format (defaults to EVM)
+ * @returns Decoded address string
+ * @throws {@link CCIPChainFamilyUnsupportedError} if chain family is not supported
+ */
 export function decodeAddress(address: BytesLike, family: ChainFamily = ChainFamily.EVM): string {
   const chain = supportedChains[family]
   if (!chain) throw new CCIPChainFamilyUnsupportedError(family)
@@ -246,7 +252,11 @@ export function decodeAddress(address: BytesLike, family: ChainFamily = ChainFam
 
 /**
  * Validate a value is a txHash string in some supported chain family
- **/
+ * @param txHash - Value to check
+ * @param family - Optional chain family to validate against
+ * @returns true if value is a valid transaction hash
+ * @throws {@link CCIPChainFamilyUnsupportedError} if specified chain family is not supported
+ */
 export function isSupportedTxHash(txHash: unknown, family?: ChainFamily): txHash is string {
   let chains: ChainStatic[]
   if (!family) chains = Object.values(supportedChains)
@@ -309,6 +319,7 @@ export function isBase64(data: unknown): data is string {
  * Converts various data formats to Uint8Array.
  * @param data - Bytes, number array, or Base64 string.
  * @returns Uint8Array representation.
+ * @throws {@link CCIPDataFormatUnsupportedError} if data format is not recognized
  */
 export function getDataBytes(data: BytesLike | readonly number[]): Uint8Array {
   if (Array.isArray(data)) return new Uint8Array(data)
@@ -409,7 +420,8 @@ export function convertKeysToCamelCase(
  * @param ms - Duration in milliseconds.
  * @returns Promise that resolves after the specified duration.
  */
-export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms).unref())
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- unref is Node.js-only; browsers return number
+export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms).unref?.())
 
 /**
  * Configuration for the withRetry utility.
@@ -518,6 +530,7 @@ export async function withRetry<T>(
  * Parses a typeAndVersion string into its components.
  * @param typeAndVersion - String in format "TypeName vX.Y.Z".
  * @returns Tuple of [type, version, original, suffix?].
+ * @throws {@link CCIPTypeVersionInvalidError} if string format is invalid
  */
 export function parseTypeAndVersion(
   typeAndVersion: string,