@chainlink/ccip-sdk 1.3.1 → 1.4.1

package/src/solana/index.ts

@@ -35,10 +35,12 @@ import {
   type LogFilter,
   type TokenInfo,
   type TokenPoolRemote,
+  type TokenPrice,
   type TokenTransferFeeOpts,
   Chain,
 } from '../chain.ts'
 import {
+  CCIPAddressInvalidError,
   CCIPArgumentInvalidError,
   CCIPBlockTimeNotFoundError,
   CCIPContractNotRouterError,
@@ -112,6 +114,7 @@ import { IDL as BURN_MINT_TOKEN_POOL } from './idl/1.6.0/BURN_MINT_TOKEN_POOL.ts
 import { IDL as CCIP_CCTP_TOKEN_POOL } from './idl/1.6.0/CCIP_CCTP_TOKEN_POOL.ts'
 import { IDL as CCIP_OFFRAMP_IDL } from './idl/1.6.0/CCIP_OFFRAMP.ts'
 import { IDL as CCIP_ROUTER_IDL } from './idl/1.6.0/CCIP_ROUTER.ts'
+import { IDL as FEE_QUOTER_IDL } from './idl/1.6.0/FEE_QUOTER.ts'
 import { getTransactionsForAddress } from './logs.ts'
 import { generateUnsignedCcipSend, getFee } from './send.ts'
 import { type CCIPMessage_V1_6_Solana, type UnsignedSolanaTx, isWallet } from './types.ts'
@@ -1021,7 +1024,13 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     } catch (_) {
       // pass
     }
-    return encodeBase58(getDataBytes(bytes))
+    try {
+      const decoded = getDataBytes(bytes)
+      if (decoded.length === 32) return encodeBase58(decoded)
+    } catch {
+      // pass
+    }
+    throw new CCIPAddressInvalidError(bytes, this.family)
   }
 
   /**
@@ -1567,6 +1576,43 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     )
   }
 
+  /** {@inheritDoc Chain.getTokenPrice} */
+  override async getTokenPrice(opts: {
+    router: string
+    token: string
+    timestamp?: number
+  }): Promise<TokenPrice> {
+    if (opts.timestamp != null) {
+      this.logger.warn(
+        'getTokenPrice: timestamp parameter not yet supported on Solana, returning latest price',
+      )
+    }
+    const { feeQuoter } = await this._getRouterConfig(opts.router)
+
+    // Resolve native SOL to wrapped SOL (NATIVE_MINT)
+    const tokenMint =
+      !opts.token || opts.token === PublicKey.default.toBase58()
+        ? NATIVE_MINT
+        : new PublicKey(opts.token)
+
+    const feeQuoterProgram = new Program(FEE_QUOTER_IDL, feeQuoter, {
+      connection: this.connection,
+    })
+
+    const [billingTokenConfigPda] = PublicKey.findProgramAddressSync(
+      [Buffer.from('fee_billing_token_config'), tokenMint.toBuffer()],
+      feeQuoter,
+    )
+
+    const [billingTokenConfigWrapper, { decimals }] = await Promise.all([
+      feeQuoterProgram.account.billingTokenConfigWrapper.fetch(billingTokenConfigPda),
+      this.getTokenInfo(tokenMint.toBase58()),
+    ])
+
+    const usdPerToken = billingTokenConfigWrapper.config.usdPerToken
+    return { price: Number(toBigInt(Buffer.from(usdPerToken.value))) * 10 ** (decimals - 36) }
+  }
+
   /**
    * Gets the router configuration from the Config PDA.
    * @param router - Router program address.
@@ -1588,9 +1634,19 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * Returns a copy of a message, populating missing fields like `extraArgs` with defaults.
    * It's expected to return a message suitable at least for basic token transfers.
    *
+   * @remarks
+   * Solana-specific receiver/tokenReceiver handling:
+   * - Explicit `tokenReceiver` in extraArgs: both `receiver` and `tokenReceiver` are kept as provided.
+   * - Tokens but no explicit `tokenReceiver`: `receiver` is set to `PublicKey.default` and
+   *   `tokenReceiver` is set to `message.receiver`.
+   * - No tokens: `tokenReceiver` is set to `PublicKey.default` and `receiver` is `message.receiver`.
+   *
+   * Accepts `gasLimit` as an alias for `computeUnits` in extraArgs.
+   *
    * @param message - AnyMessage (from source), containing at least `receiver`
    * @returns A message suitable for `sendMessage` to this destination chain family
    * @throws {@link CCIPArgumentInvalidError} if tokenReceiver missing when sending tokens with data
+   * @throws {@link CCIPArgumentInvalidError} if extraArgs contains unknown fields for SVMExtraArgsV1
    */
   static override buildMessageForDest(
     message: Parameters<ChainStatic['buildMessageForDest']>[0],
@@ -1647,13 +1703,13 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
         : true
     const [tokenReceiver, receiver] =
       message.extraArgs && 'tokenReceiver' in message.extraArgs && !!message.extraArgs.tokenReceiver
-        ? [message.extraArgs.tokenReceiver, message.receiver] // explicit tokenReceiver, keep both
+        ? [this.getAddress(message.extraArgs.tokenReceiver), this.getAddress(message.receiver)] // explicit tokenReceiver, keep both
         : message.tokenAmounts?.length
           ? [this.getAddress(message.receiver), PublicKey.default.toBase58()] // if sending tokens without tokenReceiver, set receiver to default and tokenReceiver to message.receiver
-          : [PublicKey.default.toBase58(), message.receiver] // otherwise, tokenReceiver is default and receiver is message.receiver
+          : [PublicKey.default.toBase58(), this.getAddress(message.receiver)] // otherwise, tokenReceiver is default and receiver is message.receiver
     const accounts =
       message.extraArgs && 'accounts' in message.extraArgs && message.extraArgs.accounts != null
-        ? message.extraArgs.accounts
+        ? message.extraArgs.accounts.map(this.getAddress.bind(this))
         : []
     const accountIsWritableBitmap =
       message.extraArgs &&

package/src/solana/utils.ts

@@ -211,7 +211,7 @@ export function parseSolanaLogs(logs: readonly string[]): ParsedLog[] {
 
 /**
  * Extracts error information from Solana transaction logs.
- * @param logs_ - Raw log strings or parsed log objects.
+ * @param logs_ - Raw log strings or parsed log objects (may include `tx` field with error info).
  * @returns Parsed error info with program and error details.
  */
 export function getErrorFromLogs(
@@ -397,6 +397,7 @@ export function simulationProvider(
  *   - lookupTables - lookupTables to be used for main instruction
  * @param computeUnits - max computeUnits limit to be used for main instruction
  * @returns - signature of successful transaction including main instruction
+ * @throws {@link CCIPSolanaComputeUnitsExceededError} if simulation exceeds compute units limit
  */
 export async function simulateAndSendTxs(
   ctx: { connection: Connection } & WithLogger,
@@ -465,7 +466,9 @@ export async function simulateAndSendTxs(
 }
 
 /**
- * Convert TokenPool's rate limit to RateLimiterState object
+ * Convert TokenPool's rate limit to RateLimiterState object.
+ * @param input - On-chain rate limiter bucket from the TokenPool IDL.
+ * @returns RateLimiterState with capacity, rate, and current tokens, or null if disabled.
  */
 export function convertRateLimiter(
   input: IdlTypes<typeof BASE_TOKEN_POOL_IDL>['BaseChain']['inboundRateLimit'],

package/src/sui/index.ts

@@ -68,7 +68,6 @@ const DEFAULT_GAS_LIMIT = 1000000n
 
 /**
  * Sui chain implementation supporting Sui networks.
- * Note: This implementation is currently a placeholder.
  */
 export class SuiChain extends Chain<typeof ChainFamily.Sui> {
   static {
@@ -814,6 +813,7 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
    *
    * @param message - AnyMessage (from source), containing at least `receiver`
    * @returns A message suitable for `sendMessage` to this destination chain family
+   * @throws {@link CCIPArgumentInvalidError} if extraArgs contains unknown fields for SuiExtraArgsV1
    */
   static override buildMessageForDest(
     message: Parameters<ChainStatic['buildMessageForDest']>[0],
@@ -848,36 +848,38 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
       message.extraArgs.allowOutOfOrderExecution != null
         ? message.extraArgs.allowOutOfOrderExecution
         : true
-    const tokenReceiver =
-      message.extraArgs &&
-      'tokenReceiver' in message.extraArgs &&
-      message.extraArgs.tokenReceiver != null &&
-      typeof message.extraArgs.tokenReceiver === 'string'
-        ? message.extraArgs.tokenReceiver
+    const [tokenReceiver, receiver] =
+      message.extraArgs && 'tokenReceiver' in message.extraArgs && !!message.extraArgs.tokenReceiver
+        ? [this.getAddress(message.extraArgs.tokenReceiver), this.getAddress(message.receiver)] // explicit tokenReceiver, keep both
         : message.tokenAmounts?.length
-          ? this.getAddress(message.receiver)
-          : '0x0000000000000000000000000000000000000000000000000000000000000000'
+          ? [
+              this.getAddress(message.receiver),
+              '0x0000000000000000000000000000000000000000000000000000000000000000',
+            ] // if sending tokens without tokenReceiver, set receiver to default and tokenReceiver to message.receiver
+          : [
+              '0x0000000000000000000000000000000000000000000000000000000000000000',
+              this.getAddress(message.receiver),
+            ] // otherwise, tokenReceiver is default and receiver is message.receiver
     const receiverObjectIds =
       message.extraArgs &&
       'receiverObjectIds' in message.extraArgs &&
       message.extraArgs.receiverObjectIds?.length
-        ? message.extraArgs.receiverObjectIds
+        ? message.extraArgs.receiverObjectIds.map(this.getAddress.bind(this))
         : message.extraArgs && 'accounts' in message.extraArgs && message.extraArgs.accounts?.length
-          ? message.extraArgs.accounts // populates receiverObjectIds from accounts
+          ? message.extraArgs.accounts.map(this.getAddress.bind(this)) // populates receiverObjectIds from accounts
           : []
+
     const extraArgs: SuiExtraArgsV1 = {
       gasLimit,
       allowOutOfOrderExecution,
       tokenReceiver,
       receiverObjectIds,
     }
+
     return {
       ...message,
+      receiver,
       extraArgs,
-      // if tokenReceiver, then message.receiver can (must?) be default
-      ...(!!message.tokenAmounts?.length && {
-        receiver: '0x0000000000000000000000000000000000000000000000000000000000000000',
-      }),
     }
   }
 }

package/src/ton/index.ts

@@ -36,7 +36,6 @@ import {
 import {
   CCIPArgumentInvalidError,
   CCIPExecutionReportChainMismatchError,
-  CCIPExtraArgsInvalidError,
   CCIPHttpError,
   CCIPNotImplementedError,
   CCIPReceiptNotFoundError,
@@ -184,6 +183,9 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
 
   /**
    * Detect client network and instantiate a TONChain instance.
+   * @param client - TonClient instance connected to the TON network.
+   * @param ctx - Optional chain context with logger, API client, and fetch function.
+   * @returns TONChain instance configured for the detected network (mainnet or testnet).
    */
   static async fromClient(
     client: TonClient,
@@ -560,10 +562,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
     }
   }
 
-  /**
-   * {@inheritDoc Chain.getBalance}
-   * @throws {@link CCIPNotImplementedError} always (not implemented for TON)
-   */
+  /** {@inheritDoc Chain.getBalance} */
   async getBalance(opts: GetBalanceOpts): Promise<bigint> {
     const { holder, token } = opts
     const holderAddress = Address.parse(holder)
@@ -606,7 +605,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
   /**
    * Decodes a CCIP message from a TON log event.
    * @param log - Log with data field.
-   * @returns Decoded CCIPMessage or undefined if not valid.
+   * @returns Decoded CCIPMessage, or undefined if the data is not a valid CCIP message (parse errors are caught and silently return undefined).
    */
   static decodeMessage({
     data,
@@ -711,6 +710,7 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    *
    * @param args - Extra arguments containing gas limit and execution flags
    * @returns Hex string of BOC-encoded extra args (0x-prefixed)
+   * @throws {@link CCIPExtraArgsInvalidError} if args contains fields other than `gasLimit` and `allowOutOfOrderExecution`
    */
   static encodeExtraArgs(args: ExtraArgs): string {
     const cell = encodeExtraArgsCell(args)
@@ -718,15 +718,16 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
   }
 
   /**
-   * Decodes BOC-encoded extra arguments from TON messages.
-   * Parses the BOC format and extracts extra args, validating the magic tag
-   * to ensure correct type. Returns undefined if parsing fails or tag doesn't match.
+   * Decodes extra arguments from TON messages.
+   * Handles both raw bit-packed data (starts with EVMExtraArgsV2 tag directly)
+   * and BOC-wrapped data (starts with TON BOC magic `0xb5ee9c72`, unwrapped first).
+   * Returns undefined if parsing fails or the tag doesn't match.
    *
    * Currently only supports EVMExtraArgsV2 (GenericExtraArgsV2) encoding since TON
    * lanes are only connected to EVM chains. When new lanes are planned to be added,
    * this should be extended to support them (eg. Solana and SVMExtraArgsV1)
    *
-   * @param extraArgs - BOC-encoded extra args as hex string or bytes
+   * @param extraArgs - Extra args as hex string or bytes (raw bit-packed or BOC-wrapped)
    * @returns Decoded EVMExtraArgsV2 (GenericExtraArgsV2) object or undefined if invalid
    */
   static decodeExtraArgs(
@@ -1113,25 +1114,16 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * {@inheritDoc Chain.generateUnsignedExecute}
    * @throws {@link CCIPExtraArgsInvalidError} if extra args are not EVMExtraArgsV2 format
    */
-  generateUnsignedExecute(
+  async generateUnsignedExecute(
     opts: Parameters<Chain['generateUnsignedExecute']>[0],
   ): Promise<UnsignedTONTx> {
-    if (
-      !(
-        'input' in opts &&
-        'message' in opts.input &&
-        'allowOutOfOrderExecution' in opts.input.message &&
-        'gasLimit' in opts.input.message
-      )
-    ) {
-      throw new CCIPExtraArgsInvalidError('TON')
-    }
-    const { offRamp, input } = opts
+    const resolved = await this.resolveExecuteOpts(opts)
+    const { offRamp, input } = resolved
 
     const unsigned = generateUnsignedExecuteReport(
       offRamp,
       input as ExecutionInput<CCIPMessage_V1_6_EVM>,
-      opts,
+      resolved,
     )
 
     return Promise.resolve({
@@ -1146,16 +1138,17 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
    * @throws {@link CCIPReceiptNotFoundError} if execution receipt not found within timeout
    */
   async execute(opts: Parameters<Chain['execute']>[0]): Promise<CCIPExecution> {
-    if (!('input' in opts && 'message' in opts.input))
-      throw new CCIPExecutionReportChainMismatchError('TON')
-    const { offRamp, wallet } = opts
-    if (!isTONWallet(wallet)) {
-      throw new CCIPWalletInvalidError(wallet)
-    }
+    const { wallet } = opts
+    if (!isTONWallet(wallet)) throw new CCIPWalletInvalidError(wallet)
     const payer = await wallet.getAddress()
 
+    const resolved = await this.resolveExecuteOpts(opts)
+    const { offRamp } = resolved
+    if (!('message' in resolved.input)) throw new CCIPExecutionReportChainMismatchError('TON')
+    const message = resolved.input.message as CCIPMessage_V1_6_EVM
+
     const { family: _, ...unsigned } = await this.generateUnsignedExecute({
-      ...opts,
+      ...resolved,
       payer,
     })
 
@@ -1166,7 +1159,6 @@ export class TONChain extends Chain<typeof ChainFamily.TON> {
       ...unsigned,
     })
 
-    const message = opts.input.message as CCIPMessage_V1_6_EVM
     for await (const exec of this.getExecutionReceipts({
       offRamp,
       messageId: message.messageId,

package/src/ton/send.ts

@@ -54,6 +54,7 @@ function encodeTokenAmounts(
  * - allowOutOfOrderExecution: 1 bit
  * @param extraArgs - Extra arguments for CCIP message
  * @returns Cell encoding the extra arguments
+ * @throws {@link CCIPExtraArgsInvalidError} if `extraArgs` contains fields other than `gasLimit` and `allowOutOfOrderExecution`
  */
 export function encodeExtraArgsCell(extraArgs: ExtraArgs): Cell {
   if (
@@ -78,6 +79,12 @@ export function encodeExtraArgsCell(extraArgs: ExtraArgs): Cell {
  * Builds the Router ccipSend message cell.
  *
  * Relies on TL-B structure (Router_CCIPSend) from chainlink-ton repo.
+ *
+ * @param destChainSelector - Destination chain selector
+ * @param message - CCIP message containing receiver, data, tokenAmounts, and extraArgs
+ * @param feeTokenAddress - Fee token jetton address, or null for native TON
+ * @param queryId - TON query ID for the message (default: 0)
+ * @returns Cell containing the encoded Router ccipSend message
  */
 export function buildCcipSendCell(
   destChainSelector: bigint,

package/src/utils.ts

@@ -476,7 +476,7 @@ export function convertKeysToCamelCase(
   mapValues?: (value: unknown, key?: string) => unknown,
   key?: string,
 ): unknown {
-  if (Array.isArray(obj) && obj.every((v) => typeof v === 'number')) {
+  if (Array.isArray(obj) && obj.length && obj.every((v) => typeof v === 'number')) {
     return mapValues ? mapValues(obj, key) : obj
   } else if (Array.isArray(obj)) {
     return obj.map((v) => convertKeysToCamelCase(v, mapValues, key))
@@ -608,7 +608,10 @@ 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?].
+ * @returns Tuple of `[normalizedType, normalizedVersion, original, suffix?]` where
+ *   `normalizedType` has kebab-to-PascalCase, `CCIP` uppercasing, and ramp casing applied
+ *   (e.g., `"ccip-offramp"` becomes `"CCIPOffRamp"`), and `normalizedVersion` has the patch
+ *   component forced to `.0` for core contracts (OnRamp, OffRamp, Router).
  * @throws {@link CCIPTypeVersionInvalidError} if string format is invalid
  */
 export function parseTypeAndVersion(
@@ -828,7 +831,11 @@ export function createRateLimitedFetch(
  *
  * @param url - URL to fetch
  * @param operation - Operation name for error context
- * @param opts - Optional timeout, abort signal, fetch function, and extra RequestInit fields
+ * @param opts - Optional configuration:
+ *   - `timeoutMs` — request timeout in milliseconds (default: 30000).
+ *   - `signal` — an external `AbortSignal` to cancel the request.
+ *   - `fetch` — custom fetch function (defaults to `globalThis.fetch`).
+ *   - `init` — additional `RequestInit` fields merged into the fetch call.
  * @returns Promise resolving to Response
  * @throws CCIPTimeoutError if request times out
  * @throws CCIPAbortError if request is aborted via signal