@chainlink/ccip-sdk 0.95.0 → 0.97.0

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,24 @@ 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
+ *
+ * @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,
@@ -204,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') {
@@ -217,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)) {
@@ -236,8 +273,26 @@ export function parseJson<T = unknown>(text: string): T {
 }
 
 /**
- * Decode address from a 32-byte hex string
- **/
+ * 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]
   if (!chain) throw new CCIPChainFamilyUnsupportedError(family)
@@ -246,7 +301,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 +368,21 @@ 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
+ *
+ * @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)
@@ -358,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)
@@ -409,7 +491,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 +601,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,

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),
-  ])