@chainlink/ccip-sdk 1.3.0 → 1.4.0

package/src/solana/index.ts

@@ -35,6 +35,7 @@ import {
   type LogFilter,
   type TokenInfo,
   type TokenPoolRemote,
+  type TokenPrice,
   type TokenTransferFeeOpts,
   Chain,
 } from '../chain.ts'
@@ -112,6 +113,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'
@@ -1567,6 +1569,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 +1627,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],
@@ -1645,15 +1694,12 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
       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
+        ? [message.extraArgs.tokenReceiver, message.receiver] // explicit tokenReceiver, keep both
         : message.tokenAmounts?.length
-          ? this.getAddress(message.receiver)
-          : PublicKey.default.toBase58()
+          ? [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
     const accounts =
       message.extraArgs && 'accounts' in message.extraArgs && message.extraArgs.accounts != null
         ? message.extraArgs.accounts
@@ -1675,9 +1721,8 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
 
     return {
       ...message,
+      receiver,
       extraArgs,
-      // if tokenReceiver, then message.receiver can (must?) be default
-      ...(!!message.tokenAmounts?.length && { receiver: PublicKey.default.toBase58() }),
     }
   }
 }

package/src/solana/utils.ts

@@ -27,7 +27,7 @@ import {
   CCIPTransactionNotFinalizedError,
 } from '../errors/index.ts'
 import type { ChainLog, WithLogger } from '../types.ts'
-import { bigIntReplacer, getDataBytes, sleep } from '../utils.ts'
+import { bigIntReplacer, getDataBytes, isBase64, sleep } from '../utils.ts'
 import type { IDL as BASE_TOKEN_POOL_IDL } from './idl/1.6.0/BASE_TOKEN_POOL.ts'
 import type { UnsignedSolanaTx, Wallet } from './types.ts'
 import type { RateLimiterState } from '../chain.ts'
@@ -211,13 +211,13 @@ 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(
   logs_:
     | readonly string[]
-    | readonly Pick<ChainLog, 'address' | 'index' | 'data' | 'topics'>[]
+    | readonly Pick<ChainLog, 'address' | 'index' | 'data' | 'topics' | 'tx'>[]
     | null,
 ): { program: string; [k: string]: string } | undefined {
   if (!logs_?.length) return
@@ -234,12 +234,13 @@ export function getErrorFromLogs(
         !acc.length || (l.address === acc[0]!.address && !l.topics.length) ? [l, ...acc] : acc,
       [] as Pick<ChainLog, 'address' | 'index' | 'data'>[],
     )
+    .filter(({ data }) => !isBase64(data))
     .map(({ data }) => data as string)
     .reduceRight(
       (acc, l) =>
         l.endsWith(':') && acc.length
           ? [`${l} ${acc[0]}`, ...acc.slice(1)]
-          : l.split(': ').length > 1 && l.split('. ').length > 1
+          : l.indexOf(': ') >= 0 && l.indexOf('. ') >= 0
             ? [...l.replace(/\.$/, '').split('. '), ...acc]
             : [l, ...acc],
       [] as string[],
@@ -261,22 +262,28 @@ export function getErrorFromLogs(
         return l
       }
     })
-  if (lastProgramLogs.every((l) => l.indexOf(': ') >= 0)) {
-    return {
-      program: lastLog.address,
-      ...Object.fromEntries(
-        lastProgramLogs.map((l) => [
-          l.substring(0, l.indexOf(': ')),
-          l.substring(l.indexOf(': ') + 2),
-        ]),
-      ),
-    }
+
+  const res: { program: string; [k: string]: string } = {
+    program: lastLog.address,
+  }
+  if (lastProgramLogs.every((l) => l.indexOf(': ') >= 0 || l.indexOf(' in ') >= 0)) {
+    Object.assign(
+      res,
+      Object.fromEntries(lastProgramLogs.map((l) => l.split(/: | in /, 2) as [string, string])),
+    )
   } else {
-    return {
-      program: lastLog.address,
-      error: lastProgramLogs.join('\n'),
-    }
+    res['error'] = lastProgramLogs.join('\n')
   }
+  if (!!logs[0] && 'tx' in logs[0] && !!logs[0].tx?.error)
+    Object.assign(
+      res,
+      Object.fromEntries(
+        Object.entries(logs[0].tx.error as Record<string, [number, string]>).map(
+          ([k, [i, e]]) => [`${k}[${i}]`, e] as const,
+        ),
+      ),
+    )
+  return res
 }
 
 /**
@@ -390,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,
@@ -458,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],

package/src/ton/index.ts

@@ -184,6 +184,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 +563,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 +606,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 +711,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 +719,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(

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/types.ts

@@ -470,7 +470,7 @@ export type AnyMessage = {
  * }
  * ```
  */
-export type MessageInput = Partial<AnyMessage> & {
+export type MessageInput = Partial<Omit<AnyMessage, 'extraArgs'>> & {
   receiver: AnyMessage['receiver']
   extraArgs?: Partial<ExtraArgs>
   fee?: bigint

package/src/utils.ts

@@ -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(
@@ -616,9 +619,8 @@ export function parseTypeAndVersion(
 ): Awaited<ReturnType<Chain['typeAndVersion']>> {
   const match = typeAndVersion.match(/^(\w.+\S)\s+v?(\d+\.\d+(?:\.\d+)?)([^\d.].*)?$/)
   if (!match) throw new CCIPTypeVersionInvalidError(typeAndVersion)
-  const [, typeRaw, version] = match
   // some string normalization
-  const type = typeRaw!
+  const type = match[1]!
     .replaceAll(/-(\w)/g, (_, w: string) => w.toUpperCase()) // kebabToPascal
     .replace(/ccip/gi, 'CCIP')
     .replace(
@@ -626,8 +628,15 @@ export function parseTypeAndVersion(
       (_, o: string, n: string, ramp: string) =>
         `${o.toUpperCase()}${n.toLowerCase()}${ramp.charAt(0).toUpperCase()}${ramp.slice(1).toLowerCase()}`,
     ) // ccipOfframp -> CCIPOffRamp
-  if (!match[3]) return [type, version!, typeAndVersion]
-  else return [type, version!, typeAndVersion, match[3]]
+    .replace('router', 'Router') // ccip-router -> CCIPRouter
+
+  let version = match[2]!
+  // for core contracts, always use patch `.0`, to match CCIPVersion
+  if (type.match(/((o(n|ff)ramp)|router)\b/gi))
+    version = version.replace(/^(\d+\.\d+)(?:\.\d+)?$/, '$1.0')
+
+  if (!match[3]) return [type, version, typeAndVersion]
+  else return [type, version, typeAndVersion, match[3]]
 }
 
 /* eslint-disable jsdoc/require-jsdoc */
@@ -822,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