@chainlink/ccip-sdk 1.3.1 → 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],

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

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/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(
@@ -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