@chainlink/ccip-sdk 0.90.2 → 0.91.0

package/src/types.ts

@@ -1,7 +1,6 @@
 import type { AbiParametersToPrimitiveTypes, ExtractAbiEvent } from 'abitype'
 import type { BytesLike, Log } from 'ethers'
 
-import type { ChainFamily, ChainTransaction } from './chain.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'
@@ -11,24 +10,28 @@ import type { CCIPMessage_V1_6_Sui } from './sui/types.ts'
 export type { CCIPMessage_V1_6 } from './evm/messages.ts'
 
 /**
- * DeepReadonly is a type that recursively makes all properties of an object readonly.
+ * Logger interface for logging messages (compatible with console)
  */
-export type DeepReadonly<T> = Readonly<{
-  [K in keyof T]: T[K] extends number | string | symbol // Is it a primitive? Then make it readonly
-    ? Readonly<T[K]>
-    : // Is it an array of items? Then make the array readonly and the item as well
-      T[K] extends Array<infer A>
-      ? Readonly<Array<DeepReadonly<A>>>
-      : // It is some other object, make it readonly as well
-        DeepReadonly<T[K]>
-}>
+export type Logger = {
+  debug: (...args: unknown[]) => void
+  info: (...args: unknown[]) => void
+  warn: (...args: unknown[]) => void
+  error: (...args: unknown[]) => void
+}
+
+/**
+ * An options object which may have a logger
+ */
+export type WithLogger = {
+  logger?: Logger
+}
 
 /**
- * "Fix" for deeply intersecting types containing arrays: A[] & B[] => (A & B)[]
- * Usually, if you intersect { arr: A[] } & { arr: B[] }, arr will have type A[] & B[],
+ * "Fix" for deeply intersecting types containing arrays: converts `A[] & B[]` to `(A & B)[]`.
+ * Usually, if you intersect `\{ arr: A[] \} & \{ arr: B[] \}`, arr will have type `A[] & B[]`,
  * i.e. all/each *index* of A[] and B[] should be present in the intersection, with quite undefined
- * types of the elements themselves, oftentimes assigning only one of A or B to the element type;
- * This converts deeply to (A & B)[], i.e. each *element* should have all properties of A & B
+ * types of the elements themselves, oftentimes assigning only one of A or B to the element type.
+ * This converts deeply to `(A & B)[]`, i.e. each *element* should have all properties of A & B.
  */
 export type MergeArrayElements<T, U> = {
   [K in keyof (T & U)]: K extends keyof T & keyof U
@@ -52,13 +55,30 @@ export type MergeArrayElements<T, U> = {
         : never
 }
 
+/**
+ * Enumeration of supported blockchain families.
+ */
+export const ChainFamily = {
+  EVM: 'evm',
+  Solana: 'solana',
+  Aptos: 'aptos',
+  Sui: 'sui',
+} as const
+/** Type representing one of the supported chain families. */
+export type ChainFamily = (typeof ChainFamily)[keyof typeof ChainFamily]
+
+/**
+ * Enumeration of supported CCIP protocol versions.
+ */
 export const CCIPVersion = {
   V1_2: '1.2.0',
   V1_5: '1.5.0',
   V1_6: '1.6.0',
 } as const
+/** Type representing one of the supported CCIP versions. */
 export type CCIPVersion = (typeof CCIPVersion)[keyof typeof CCIPVersion]
 
+/** Helper type that maps chain family to its chain ID format. */
 type ChainFamilyWithId<F extends ChainFamily> = F extends typeof ChainFamily.EVM
   ? { readonly family: F; readonly chainId: number }
   : F extends typeof ChainFamily.Solana
@@ -67,87 +87,179 @@ type ChainFamilyWithId<F extends ChainFamily> = F extends typeof ChainFamily.EVM
       ? { readonly family: F; readonly chainId: `${F}:${number}` }
       : never
 
+/**
+ * Network information including chain selector and metadata.
+ */
 export type NetworkInfo<F extends ChainFamily = ChainFamily> = {
+  /** Unique chain selector used by CCIP. */
   readonly chainSelector: bigint
+  /** Human-readable network name. */
   readonly name: string
+  /** Whether this is a testnet. */
   readonly isTestnet: boolean
 } & ChainFamilyWithId<F>
 
+/**
+ * CCIP lane configuration connecting source and destination chains.
+ */
 export interface Lane<V extends CCIPVersion = CCIPVersion> {
+  /** Source chain selector. */
   sourceChainSelector: bigint
+  /** Destination chain selector. */
   destChainSelector: bigint
+  /** OnRamp contract address on source chain. */
   onRamp: string
+  /** CCIP protocol version for this lane. */
   version: V
 }
 
+/**
+ * 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
 
+/**
+ * Generic log structure compatible across chain families.
+ */
 export type Log_ = Pick<Log, '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
 }
 
+/**
+ * Generic transaction structure compatible across chain families.
+ */
+export type ChainTransaction = {
+  /** Transaction hash. */
+  hash: string
+  /** Logs emitted by this transaction. */
+  logs: readonly Log_[]
+  /** Block number containing this transaction. */
+  blockNumber: number
+  /** Unix timestamp of the block. */
+  timestamp: number
+  /** Sender address. */
+  from: string
+  /** Optional error if transaction failed. */
+  error?: unknown
+}
+
+/**
+ * Complete CCIP request containing lane, message, log, and transaction info.
+ */
 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_
-  tx: { logs: readonly Log_[]; from?: string; error?: unknown }
-  timestamp: number
+  /** Transaction that emitted the request. */
+  tx: Pick<ChainTransaction, 'hash' | 'logs' | 'blockNumber' | 'timestamp' | 'from' | 'error'>
 }
 
+/**
+ * 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.
+ */
 export interface CCIPCommit {
+  /** The commit report data. */
   report: CommitReport
+  /** Log event from the commit. */
   log: Log_
 }
 
+/**
+ * Enumeration of possible execution states for a CCIP message.
+ */
 export const ExecutionState = {
+  /** Execution is in progress. */
   InProgress: 1,
+  /** Execution completed successfully. */
   Success: 2,
+  /** Execution failed. */
   Failed: 3,
 } as const
+/** Type representing an execution state value. */
 export type ExecutionState = (typeof ExecutionState)[keyof typeof ExecutionState]
 
+/**
+ * Receipt of a CCIP message execution on the destination chain.
+ */
 export type ExecutionReceipt = {
+  /** Unique message identifier. */
   messageId: string
+  /** Sequence number of the message. */
   sequenceNumber: bigint
+  /** Current execution state. */
   state: ExecutionState
+  /** Source chain selector (if available). */
   sourceChainSelector?: bigint
+  /** Hash of the message (if available). */
   messageHash?: string
+  /** Return data from the receiver contract (if any). */
   returnData?: BytesLike | Record<string, string>
+  /** Gas consumed by execution (if available). */
   gasUsed?: bigint
 }
 
+/**
+ * Complete CCIP execution event with receipt, log, and timestamp.
+ */
 export interface CCIPExecution {
+  /** Execution receipt data. */
   receipt: ExecutionReceipt
+  /** Log event from the execution. */
   log: Log_
+  /** Unix timestamp of the execution. */
   timestamp: number
 }
 
+/**
+ * Offchain token data for CCTP or other bridge attestations.
+ */
 export type OffchainTokenData = { _tag: string; [k: string]: BytesLike } | undefined
 
+/**
+ * Execution report containing message, proofs, and offchain token data.
+ */
 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[]
 }
 
 /**
- * A message to be sent to another network
+ * A message to be sent to another network.
  */
 export type AnyMessage = {
+  /** Receiver address on the destination chain. */
   receiver: BytesLike
+  /** Arbitrary data payload. */
   data: BytesLike
+  /** Extra arguments for gas limits and other settings. */
   extraArgs: ExtraArgs
+  /** Optional token transfers. */
   tokenAmounts?: readonly { token: string; amount: bigint }[]
+  /** Optional fee token address (native if omitted). */
   feeToken?: string
 }

package/src/utils.ts

@@ -1,4 +1,4 @@
-import util from 'util'
+import { Buffer } from 'buffer'
 
 import bs58 from 'bs58'
 import {
@@ -8,15 +8,15 @@ import {
   decodeBase64,
   getBytes,
   isBytesLike,
-  toBeHex,
+  toBeArray,
   toBigInt,
 } from 'ethers'
-import moize from 'moize'
+import { memoize } from 'micro-memoize'
 
-import { type Chain, ChainFamily } from './chain.ts'
+import type { Chain } from './chain.ts'
 import SELECTORS from './selectors.ts'
 import { supportedChains } from './supported-chains.ts'
-import type { NetworkInfo } from './types.ts'
+import { type NetworkInfo, type WithLogger, ChainFamily } from './types.ts'
 
 /**
  * Returns *some* block number with timestamp prior to `timestamp`
@@ -31,7 +31,7 @@ export async function getSomeBlockNumberBefore(
   getBlockTimestamp: (blockNumber: number) => Promise<number>,
   recentBlockNumber: number,
   timestamp: number,
-  precision = 10,
+  { precision = 10, logger = console }: { precision?: number } & WithLogger = {},
 ): Promise<number> {
   let beforeBlockNumber = Math.max(1, recentBlockNumber - precision * 1000)
   let beforeTimestamp = await getBlockTimestamp(beforeBlockNumber)
@@ -78,7 +78,7 @@ export async function getSomeBlockNumberBefore(
       beforeBlockNumber = pivot
       beforeTimestamp = pivotTimestamp
     }
-    console.debug('getSomeBlockNumberBefore: searching block before', {
+    logger.debug('getSomeBlockNumberBefore: searching block before', {
       beforeBlockNumber,
       beforeTimestamp,
       pivot,
@@ -94,7 +94,7 @@ export async function getSomeBlockNumberBefore(
 }
 
 // memoized so we always output the same object for a given chainId
-const networkInfoFromChainId = moize.default((chainId: NetworkInfo['chainId']): NetworkInfo => {
+const networkInfoFromChainId = memoize((chainId: NetworkInfo['chainId']): NetworkInfo => {
   const sel = SELECTORS[chainId]
   if (!sel?.name) throw new Error(`Chain not found: ${chainId}`)
   return {
@@ -115,7 +115,7 @@ const networkInfoFromChainId = moize.default((chainId: NetworkInfo['chainId']):
  *   - Chain name as string ("ethereum-mainnet")
  * @returns Complete NetworkInfo object
  */
-export const networkInfo = moize.default(function networkInfo_(
+export const networkInfo = memoize(function networkInfo_(
   selectorOrIdOrName: bigint | number | string,
 ): NetworkInfo {
   let chainId
@@ -181,6 +181,12 @@ export function* blockRangeGenerator(
   }
 }
 
+/**
+ * JSON replacer function that converts BigInt values to strings.
+ * @param _key - Property key (unused).
+ * @param value - Value to transform.
+ * @returns String representation if BigInt, otherwise unchanged value.
+ */
 export function bigIntReplacer(_key: string, value: unknown): unknown {
   if (typeof value === 'bigint') {
     return value.toString()
@@ -188,6 +194,12 @@ export function bigIntReplacer(_key: string, value: unknown): unknown {
   return value
 }
 
+/**
+ * JSON reviver function that converts numeric strings back to BigInt.
+ * @param _key - Property key (unused).
+ * @param value - Value to transform.
+ * @returns BigInt if numeric string, otherwise unchanged value.
+ */
 export function bigIntReviver(_key: string, value: unknown): unknown {
   if (typeof value === 'string' && /^\d+$/.test(value)) {
     return BigInt(value)
@@ -216,15 +228,31 @@ export function decodeOnRampAddress(
   return decoded
 }
 
+/**
+ * Converts little-endian bytes to BigInt.
+ * @param data - Little-endian byte data.
+ * @returns BigInt value.
+ */
 export function leToBigInt(data: BytesLike | readonly number[]): bigint {
   if (Array.isArray(data)) data = new Uint8Array(data)
   return toBigInt(getBytes(data as BytesLike).reverse())
 }
 
+/**
+ * Converts a BigNumber to little-endian byte array.
+ * @param value - Numeric value to convert.
+ * @param width - Optional byte width for padding.
+ * @returns Little-endian Uint8Array.
+ */
 export function toLeArray(value: BigNumberish, width?: Numeric): Uint8Array {
-  return getBytes(toBeHex(value, width)).reverse()
+  return toBeArray(value, width).reverse()
 }
 
+/**
+ * Checks if the given data is a valid Base64 encoded string.
+ * @param data - Data to check.
+ * @returns True if valid Base64 string.
+ */
 export function isBase64(data: unknown): data is string {
   return (
     typeof data === 'string' &&
@@ -232,6 +260,11 @@ 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.
+ */
 export function getDataBytes(data: BytesLike | readonly number[]): Uint8Array {
   if (Array.isArray(data)) {
     return new Uint8Array(data)
@@ -245,6 +278,11 @@ export function getDataBytes(data: BytesLike | readonly number[]): Uint8Array {
   }
 }
 
+/**
+ * Extracts address bytes, handling both hex and Base58 formats.
+ * @param address - Address in hex or Base58 format.
+ * @returns Address bytes as Uint8Array.
+ */
 export function getAddressBytes(address: BytesLike): Uint8Array {
   let bytes: Uint8Array
   if (isBytesLike(address)) {
@@ -295,8 +333,18 @@ export function convertKeysToCamelCase(
   return converted
 }
 
-export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
+/**
+ * Promise-based sleep utility.
+ * @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())
 
+/**
+ * Parses a typeAndVersion string into its components.
+ * @param typeAndVersion - String in format "TypeName vX.Y.Z".
+ * @returns Tuple of [type, version, original, suffix?].
+ */
 export function parseTypeAndVersion(
   typeAndVersion: string,
 ): Awaited<ReturnType<Chain['typeAndVersion']>> {
@@ -305,7 +353,7 @@ export function parseTypeAndVersion(
     throw new Error(
       `Invalid typeAndVersion: "${typeAndVersion}", len=${typeAndVersion.length}, hex=0x${Buffer.from(typeAndVersion).toString('hex')}`,
     )
-  const [_, typeRaw, version] = match
+  const [, typeRaw, version] = match
   // some string normalization
   const type = typeRaw
     .replaceAll(/-(\w)/g, (_, w: string) => w.toUpperCase()) // kebabToPascal
@@ -319,14 +367,26 @@ export function parseTypeAndVersion(
   else return [type, version, typeAndVersion, match[3]]
 }
 
-export function createRateLimitedFetch({
-  maxRequests = Number(process.env['RL_MAX_REQUESTS'] || 2),
-  windowMs = Number(process.env['RL_WINDOW_MS'] || 10000),
-  maxRetries = Number(process.env['RL_MAX_RETRIES'] || 5),
-}: { maxRequests?: number; windowMs?: number; maxRetries?: number } = {}): typeof fetch {
+/**
+ * Creates a rate-limited fetch function with retry logic.
+ * Configurable via maxRequests, windowMs, and maxRetries options.
+ * @returns Rate-limited fetch function.
+ */
+export function createRateLimitedFetch(
+  {
+    maxRequests = 40,
+    windowMs = 11e3,
+    maxRetries = 5,
+  }: { maxRequests?: number; windowMs?: number; maxRetries?: number } = {},
+  { logger = console }: WithLogger = {},
+): typeof fetch {
   // Custom fetch implementation with retry logic and rate limiting
   // Per-instance state
   const requestQueue: Array<{ timestamp: number }> = []
+  const methodRateLimits: Record<
+    string,
+    { limit: number; remaining: number; queue: Array<{ timestamp: number }> }
+  > = {}
 
   const isRateLimited = (): boolean => {
     const now = Date.now()
@@ -337,7 +397,31 @@ export function createRateLimitedFetch({
     return requestQueue.length >= maxRequests
   }
 
-  const waitForRateLimit = async (): Promise<void> => {
+  const isMethodRateLimited = (method: string): boolean => {
+    const methodLimit = methodRateLimits[method]
+    if (!methodLimit) return false
+
+    const now = Date.now()
+    // Remove old requests outside the window
+    while (methodLimit.queue.length > 0 && now - methodLimit.queue[0].timestamp > windowMs) {
+      methodLimit.queue.shift()
+    }
+    return methodLimit.queue.length >= methodLimit.limit
+  }
+
+  const waitForRateLimit = async (method?: string): Promise<void> => {
+    // Wait for method-specific rate limit if applicable
+    if (method && methodRateLimits[method]) {
+      while (isMethodRateLimited(method)) {
+        const oldestRequest = methodRateLimits[method].queue[0]
+        const waitTime = windowMs - (Date.now() - oldestRequest.timestamp)
+        if (waitTime > 0) {
+          await sleep(waitTime + 100) // Add small buffer
+        }
+      }
+    }
+
+    // Wait for global rate limit
     while (isRateLimited()) {
       const oldestRequest = requestQueue[0]
       const waitTime = windowMs - (Date.now() - oldestRequest.timestamp)
@@ -347,8 +431,39 @@ export function createRateLimitedFetch({
     }
   }
 
-  const recordRequest = (): void => {
-    requestQueue.push({ timestamp: Date.now() })
+  const recordRequest = (method?: string): void => {
+    const timestamp = Date.now()
+    requestQueue.push({ timestamp })
+    if (method && methodRateLimits[method]) {
+      methodRateLimits[method].queue.push({ timestamp })
+    }
+  }
+
+  const updateMethodRateLimits = (response: Response, method?: string): void => {
+    if (!method) return
+
+    const limit = Number(response.headers.get('x-ratelimit-method-limit'))
+    const remaining = Number(response.headers.get('x-ratelimit-method-remaining'))
+
+    if (isNaN(limit) || isNaN(remaining)) return
+    if (!methodRateLimits[method]) {
+      methodRateLimits[method] = { limit, remaining, queue: [] }
+    } else {
+      methodRateLimits[method].limit = limit
+      methodRateLimits[method].remaining = remaining
+    }
+  }
+
+  const extractMethod = (init?: RequestInit): string | undefined => {
+    if (!init?.body || (typeof init.body !== 'string' && typeof init.body !== 'object')) return
+    try {
+      const parsed = (typeof init.body === 'string' ? JSON.parse(init.body) : init.body) as {
+        method?: string
+      }
+      if (parsed && typeof parsed.method === 'string') return parsed.method
+    } catch {
+      // Not JSON or no method field
+    }
   }
 
   const isRateLimitError = (error: unknown): boolean => {
@@ -360,19 +475,23 @@ export function createRateLimitedFetch({
 
   return async (input, init?) => {
     let lastError: Error | null = null
+    const method = extractMethod(init)
 
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
         // Wait for rate limit before making request
-        await waitForRateLimit()
-        recordRequest()
-        // console.debug('__fetching', input, init?.body)
+        await waitForRateLimit(method)
+        recordRequest(method)
+        // logger.debug('__fetching', input, init?.body)
 
         const response = await fetch(input, init)
 
+        // Update method rate limits from response headers
+        updateMethodRateLimits(response, method)
+
         // If response is successful, return it
         if (response.ok) {
-          console.debug('fetched', input, response.status, init?.body)
+          logger.debug('fetched', input, response.status, init?.body)
           return response
         }
 
@@ -382,10 +501,10 @@ export function createRateLimitedFetch({
         }
 
         // For other non-2xx responses, don't retry
-        console.debug('fetch non-retryable error', input, response.status, init?.body)
+        logger.debug('fetch non-retryable error', input, response.status, init?.body)
         throw new Error(`HTTP ${response.status}: ${response.statusText}`)
       } catch (error) {
-        console.debug('fetch errored', attempt, error, input, init?.body)
+        logger.debug('fetch errored', attempt, error, input, init?.body)
         lastError = error instanceof Error ? error : new Error(String(error))
 
         // Only retry on rate limit errors
@@ -403,3 +522,26 @@ export function createRateLimitedFetch({
     throw lastError || new Error('Request failed after all retries')
   }
 }
+
+// barebones `node:util` backfill, if needed
+const util =
+  'util' in globalThis
+    ? (
+        globalThis as unknown as {
+          util: {
+            inspect: ((v: unknown) => string) & {
+              custom: symbol
+              defaultOptions: Record<string, unknown>
+            }
+          }
+        }
+      ).util
+    : {
+        inspect: Object.assign((v: unknown) => JSON.stringify(v), {
+          custom: Symbol('custom'),
+          defaultOptions: {
+            depth: 2,
+          } as Record<string, unknown>,
+        }),
+      }
+export { util }

package/tsconfig.json

@@ -13,6 +13,7 @@
     "rewriteRelativeImportExtensions": true,
     "verbatimModuleSyntax": true,
     "erasableSyntaxOnly": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "noImplicitOverride": true
   }
 }