@chainlink/ccip-sdk 0.95.0 → 0.96.0

package/src/requests.ts

@@ -126,9 +126,12 @@ function decodeJsonMessage(data: Record<string, unknown> | undefined) {
 }
 
 /**
- * Decodes hex strings, bytearrays, JSON strings and raw objects as CCIPMessages
- * Does minimal validation, but converts objects in the format expected by ccip-tools-ts
- **/
+ * Decodes hex strings, bytearrays, JSON strings and raw objects as CCIPMessages.
+ * Does minimal validation, but converts objects in the format expected by ccip-tools-ts.
+ * @param data - Data to decode (hex string, Uint8Array, JSON string, or object)
+ * @returns Decoded CCIPMessage
+ * @throws {@link CCIPMessageDecodeError} if data cannot be decoded as a valid message
+ */
 export function decodeMessage(data: string | Uint8Array | Record<string, unknown>): CCIPMessage {
   if (
     (typeof data === 'string' && data.startsWith('{')) ||
@@ -151,10 +154,11 @@ export function decodeMessage(data: string | Uint8Array | Record<string, unknown
 }
 
 /**
- * Populates missing required fields (e.g. `extraArgs`) from AnyMessage
- * @param message - partial AnyMessage
- * @returns original message or shallow copy with defaults for required fields
- **/
+ * Populates missing required fields (e.g. `extraArgs`) from AnyMessage.
+ * @param message - Partial AnyMessage with at least receiver
+ * @param dest - Destination chain family to build message for
+ * @returns Original message or shallow copy with defaults for required fields
+ */
 export function buildMessageForDest(message: MessageInput, dest: ChainFamily): AnyMessage {
   const chain = supportedChains[dest] ?? Chain
   return chain.buildMessageForDest(message)
@@ -162,10 +166,12 @@ export function buildMessageForDest(message: MessageInput, dest: ChainFamily): A
 
 /**
  * Fetch all CCIP messages in a transaction.
- * @param source - Chain
+ * @param source - Source chain instance
  * @param tx - ChainTransaction to search in
  * @returns CCIP requests (messages) in the transaction (at least one)
- **/
+ * @throws {@link CCIPChainFamilyUnsupportedError} if chain family not supported for legacy messages
+ * @throws {@link CCIPMessageNotFoundInTxError} if no CCIP messages found in transaction
+ */
 export async function getMessagesInTx(source: Chain, tx: ChainTransaction): Promise<CCIPRequest[]> {
   // RPC fallback
   const requests: CCIPRequest[] = []
@@ -332,6 +338,7 @@ export async function getMessagesInBatch<
  * @param sender - Sender address.
  * @param filter - Log filter options.
  * @returns Async generator of CCIP requests.
+ * @throws {@link CCIPChainFamilyUnsupportedError} if chain family not supported for legacy messages
  */
 export async function* getMessagesForSender(
   source: Chain,
@@ -375,6 +382,7 @@ export async function* getMessagesForSender(
  * @param onRamp - Contract address.
  * @param sourceTokenAmount - tokenAmount object, usually containing `token` and `amount` properties.
  * @returns tokenAmount object with `sourcePoolAddress`, `sourceTokenAddress`, `destTokenAddress`, and remaining properties.
+ * @throws {@link CCIPTokenNotInRegistryError} if token not found in registry
  */
 export async function sourceToDestTokenAddresses<S extends { token: string }>(
   source: Chain,

package/src/selectors.ts

@@ -721,6 +721,12 @@ const selectors: Selectors = {
     network_type: 'TESTNET',
     family: 'EVM',
   },
+  '3343': {
+    selector: 6325494908023253251n,
+    name: 'edge-mainnet',
+    network_type: 'MAINNET',
+    family: 'EVM',
+  },
   '3636': {
     selector: 1467223411771711614n,
     name: 'bitcoin-testnet-botanix',
@@ -1003,6 +1009,12 @@ const selectors: Selectors = {
     network_type: 'MAINNET',
     family: 'EVM',
   },
+  '33431': {
+    selector: 13222148116102326311n,
+    name: 'edge-testnet',
+    network_type: 'TESTNET',
+    family: 'EVM',
+  },
   '34443': {
     selector: 7264351850409363825n,
     name: 'ethereum-mainnet-mode-1',

package/src/solana/index.ts

@@ -252,6 +252,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * @param url - RPC endpoint URL (https://, http://, wss://, or ws://).
    * @param ctx - context containing logger.
    * @returns Solana Connection instance.
+   * @throws {@link CCIPDataFormatUnsupportedError} if URL format is invalid
    */
   static _getConnection(url: string, ctx?: WithLogger): Connection {
     const { logger = console } = ctx ?? {}
@@ -293,7 +294,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
   }
 
   // cached
-  /** {@inheritDoc Chain.getBlockTimestamp} */
+  /**
+   * {@inheritDoc Chain.getBlockTimestamp}
+   * @throws {@link CCIPBlockTimeNotFoundError} if block time cannot be retrieved
+   */
   async getBlockTimestamp(block: number | 'latest' | 'finalized'): Promise<number> {
     if (typeof block !== 'number') {
       const slot = await this.connection.getSlot(block === 'latest' ? 'confirmed' : block)
@@ -313,7 +317,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return blockTime
   }
 
-  /** {@inheritDoc Chain.getTransaction} */
+  /**
+   * {@inheritDoc Chain.getTransaction}
+   * @throws {@link CCIPTransactionNotFoundError} if transaction not found
+   */
   async getTransaction(hash: string): Promise<SolanaTransaction> {
     const tx = await this.connection.getTransaction(hash, {
       commitment: 'confirmed',
@@ -389,6 +396,8 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    *   - `programs`: Special option to allow querying by address of interest, but yielding matching
    *     logs from specific (string address) program or any (true)
    * @returns AsyncIterableIterator of parsed Log_ objects.
+   * @throws {@link CCIPLogsAddressRequiredError} if address is not provided
+   * @throws {@link CCIPTopicsInvalidError} if topics contain invalid values
    */
   async *getLogs(
     opts: LogFilter & { programs?: string[] | true },
@@ -480,7 +489,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return Promise.resolve(onRamp) // Solana's router is also the onRamp
   }
 
-  /** {@inheritDoc Chain.getRouterForOffRamp} */
+  /**
+   * {@inheritDoc Chain.getRouterForOffRamp}
+   * @throws {@link CCIPSolanaRefAddressesNotFoundError} if reference addresses PDA not found
+   */
   async getRouterForOffRamp(offRamp: string, _sourceChainSelector: bigint): Promise<string> {
     const offRamp_ = new PublicKey(offRamp)
     const program = new Program(CCIP_OFFRAMP_IDL as Idl, offRamp_, {
@@ -507,7 +519,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return Promise.resolve(NATIVE_MINT.toBase58())
   }
 
-  /** {@inheritDoc Chain.getOffRampsForRouter} */
+  /**
+   * {@inheritDoc Chain.getOffRampsForRouter}
+   * @throws {@link CCIPSolanaOffRampEventsNotFoundError} if no OffRamp events found
+   */
   async getOffRampsForRouter(router: string, sourceChainSelector: bigint): Promise<string[]> {
     // feeQuoter is present in router's config, and has a DestChainState account which is updated by
     // the offramps, so we can use it to narrow the search for the offramp
@@ -559,7 +574,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return Promise.resolve(offRamp) // Solana supports only CCIP>=1.6, for which OffRamp and CommitStore are the same
   }
 
-  /** {@inheritDoc Chain.getTokenForTokenPool} */
+  /**
+   * {@inheritDoc Chain.getTokenForTokenPool}
+   * @throws {@link CCIPTokenPoolInfoNotFoundError} if token pool info not found
+   */
   async getTokenForTokenPool(tokenPool: string): Promise<string> {
     const tokenPoolInfo = await this.connection.getAccountInfo(new PublicKey(tokenPool))
     if (!tokenPoolInfo) throw new CCIPTokenPoolInfoNotFoundError(tokenPool)
@@ -570,7 +588,11 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return config.mint.toString()
   }
 
-  /** {@inheritDoc Chain.getTokenInfo} */
+  /**
+   * {@inheritDoc Chain.getTokenInfo}
+   * @throws {@link CCIPSplTokenInvalidError} if token is not a valid SPL token
+   * @throws {@link CCIPTokenDataParseError} if token data cannot be parsed
+   */
   async getTokenInfo(token: string): Promise<TokenInfo> {
     const mint = new PublicKey(token)
     const mintInfo = await this.connection.getParsedAccountInfo(mint)
@@ -619,7 +641,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
   }
 
-  /** {@inheritDoc Chain.getBalance} */
+  /**
+   * {@inheritDoc Chain.getBalance}
+   * @throws {@link CCIPTokenAccountNotFoundError} if token account not found
+   */
   async getBalance(opts: GetBalanceOpts): Promise<bigint> {
     const { holder, token } = opts
     const holderPubkey = new PublicKey(holder)
@@ -712,6 +737,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * Decodes a CCIP message from a Solana log event.
    * @param log - Log with data field.
    * @returns Decoded CCIPMessage or undefined if not valid.
+   * @throws {@link CCIPExtraArgsInvalidError} if extra args cannot be decoded
    */
   static decodeMessage({ data }: { data: unknown }): CCIPMessage | undefined {
     if (!data || typeof data !== 'string') return undefined
@@ -789,6 +815,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * Decodes extra arguments from Solana CCIP messages.
    * @param extraArgs - Encoded extra arguments bytes.
    * @returns Decoded EVMExtraArgsV2 or undefined if unknown format.
+   * @throws {@link CCIPExtraArgsLengthInvalidError} if extra args length is invalid
    */
   static decodeExtraArgs(
     extraArgs: BytesLike,
@@ -816,6 +843,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * Encodes extra arguments for Solana CCIP messages.
    * @param args - Extra arguments to encode.
    * @returns Encoded extra arguments as hex string.
+   * @throws {@link CCIPSolanaExtraArgsEncodingError} if SVMExtraArgsV1 encoding is attempted
    */
   static encodeExtraArgs(args: ExtraArgs): string {
     if ('computeUnits' in args) throw new CCIPSolanaExtraArgsEncodingError()
@@ -832,6 +860,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * @param log - Log with data field.
    * @param lane - Lane info for filtering.
    * @returns Array of CommitReport or undefined if not valid.
+   * @throws {@link CCIPLogDataMissingError} if log data is missing
    */
   static decodeCommits(
     log: Pick<Log_, 'data'>,
@@ -886,6 +915,8 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    * Decodes an execution receipt from a Solana log event.
    * @param log - Log with data, tx, and index fields.
    * @returns ExecutionReceipt or undefined if not valid.
+   * @throws {@link CCIPLogDataMissingError} if log data is missing
+   * @throws {@link CCIPExecutionStateInvalidError} if execution state is invalid
    */
   static decodeReceipt(log: Pick<Log_, 'data' | 'tx' | 'index'>): ExecutionReceipt | undefined {
     // Check if this is a ExecutionStateChanged event by looking at the discriminant
@@ -984,7 +1015,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return getV16SolanaLeafHasher(lane, ctx)
   }
 
-  /** {@inheritDoc Chain.getTokenAdminRegistryFor} */
+  /**
+   * {@inheritDoc Chain.getTokenAdminRegistryFor}
+   * @throws {@link CCIPContractNotRouterError} if address is not a Router
+   */
   async getTokenAdminRegistryFor(address: string): Promise<string> {
     const [type] = await this.typeAndVersion(address)
     if (!type.includes('Router')) throw new CCIPContractNotRouterError(address, type)
@@ -1026,7 +1060,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     )
   }
 
-  /** {@inheritDoc Chain.sendMessage} */
+  /**
+   * {@inheritDoc Chain.sendMessage}
+   * @throws {@link CCIPWalletInvalidError} if wallet is not a valid Solana wallet
+   */
   async sendMessage(opts: Parameters<Chain['sendMessage']>[0]): Promise<CCIPRequest> {
     if (!isWallet(opts.wallet)) throw new CCIPWalletInvalidError(util.inspect(opts.wallet))
     const unsigned = await this.generateUnsignedSendMessage({
@@ -1050,6 +1087,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    *   mainIndex - index of the `manuallyExecute` instruction in the array; last unless
    *   forceLookupTable is set, in which case last is ALT deactivation tx, and manuallyExecute is
    *   second to last
+   * @throws {@link CCIPExecutionReportChainMismatchError} if message is not a Solana message
    */
   async generateUnsignedExecuteReport({
     payer,
@@ -1069,7 +1107,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     )
   }
 
-  /** {@inheritDoc Chain.executeReport} */
+  /**
+   * {@inheritDoc Chain.executeReport}
+   * @throws {@link CCIPWalletInvalidError} if wallet is not a valid Solana wallet
+   */
   async executeReport(
     opts: Parameters<Chain['executeReport']>[0] & {
       // when cleaning leftover LookUp Tables, wait deactivation grace period (~513 slots) then close ALT
@@ -1118,6 +1159,7 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
    *   - waitDeactivation - Whether to wait for lookup table deactivation cool down period
    *       (513 slots) to pass before closing; by default, we deactivate (if needed) and move on, to
    *       close other ready ALTs
+   * @throws {@link CCIPWalletInvalidError} if wallet is not a valid Solana wallet
    */
   async cleanUpBuffers(opts: { wallet: unknown; waitDeactivation?: boolean }): Promise<void> {
     const wallet = opts.wallet
@@ -1241,7 +1283,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     yield* super.getExecutionReceipts(opts_)
   }
 
-  /** {@inheritDoc Chain.getRegistryTokenConfig} */
+  /**
+   * {@inheritDoc Chain.getRegistryTokenConfig}
+   * @throws {@link CCIPTokenNotConfiguredError} if token is not configured in registry
+   */
   async getRegistryTokenConfig(
     registry: string,
     token: string,
@@ -1295,8 +1340,11 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return config
   }
 
-  /** {@inheritDoc Chain.getTokenPoolConfigs} */
-  async getTokenPoolConfigs(tokenPool: string): Promise<{
+  /**
+   * {@inheritDoc Chain.getTokenPoolConfig}
+   * @throws {@link CCIPTokenPoolStateNotFoundError} if token pool state not found
+   */
+  async getTokenPoolConfig(tokenPool: string): Promise<{
     token: string
     router: string
     tokenPoolProgram: string
@@ -1328,7 +1376,11 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     }
   }
 
-  /** {@inheritDoc Chain.getTokenPoolRemotes} */
+  /**
+   * {@inheritDoc Chain.getTokenPoolRemotes}
+   * @throws {@link CCIPTokenPoolStateNotFoundError} if token pool state not found
+   * @throws {@link CCIPTokenPoolChainConfigNotFoundError} if chain config not found for specified selector
+   */
   async getTokenPoolRemotes(
     tokenPool: string,
     remoteChainSelector?: bigint,
@@ -1506,7 +1558,10 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     return program.account.config.fetch(configPda)
   }
 
-  /** {@inheritDoc ChainStatic.buildMessageForDest} */
+  /**
+   * {@inheritDoc ChainStatic.buildMessageForDest}
+   * @throws {@link CCIPArgumentInvalidError} if tokenReceiver missing when sending tokens with data
+   */
   static override buildMessageForDest(
     message: Parameters<ChainStatic['buildMessageForDest']>[0],
   ): AnyMessage & { extraArgs: SVMExtraArgsV1 } {
@@ -1544,7 +1599,8 @@ export class SolanaChain extends Chain<typeof ChainFamily.Solana> {
     const tokenReceiver =
       message.extraArgs &&
       'tokenReceiver' in message.extraArgs &&
-      message.extraArgs.tokenReceiver != null
+      message.extraArgs.tokenReceiver != null &&
+      typeof message.extraArgs.tokenReceiver === 'string'
         ? message.extraArgs.tokenReceiver
         : message.tokenAmounts?.length
           ? this.getAddress(message.receiver)

package/src/sui/index.ts

@@ -125,6 +125,8 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
    * Creates a SuiChain instance from an RPC URL.
    * @param url - HTTP or WebSocket endpoint URL for the Sui network.
    * @returns A new SuiChain instance.
+   * @throws {@link CCIPDataFormatUnsupportedError} if unable to fetch chain identifier
+   * @throws {@link CCIPError} if chain identifier is not supported
    */
   static async fromUrl(url: string, ctx?: ChainContext): Promise<SuiChain> {
     const client = new SuiClient({ url })
@@ -208,7 +210,11 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     }
   }
 
-  /** {@inheritDoc Chain.getLogs} */
+  /**
+   * {@inheritDoc Chain.getLogs}
+   * @throws {@link CCIPLogsAddressRequiredError} if address is not provided
+   * @throws {@link CCIPTopicsInvalidError} if topics format is invalid
+   */
   async *getLogs(opts: LogFilter & { versionAsHash?: boolean }) {
     if (!opts.address) throw new CCIPLogsAddressRequiredError()
 
@@ -246,7 +252,10 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return getMessagesInBatch(this, request, commit, opts)
   }
 
-  /** {@inheritDoc Chain.typeAndVersion} */
+  /**
+   * {@inheritDoc Chain.typeAndVersion}
+   * @throws {@link CCIPDataFormatUnsupportedError} if view call fails
+   */
   async typeAndVersion(address: string) {
     // requires address to have `::<module>` suffix
     address = await getLatestPackageId(address, this.client)
@@ -280,7 +289,10 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return Promise.resolve(onRamp)
   }
 
-  /** {@inheritDoc Chain.getRouterForOffRamp} */
+  /**
+   * {@inheritDoc Chain.getRouterForOffRamp}
+   * @throws {@link CCIPContractNotRouterError} always (Sui architecture doesn't have separate router)
+   */
   getRouterForOffRamp(offRamp: string, _sourceChainSelector: bigint): Promise<string> {
     throw new CCIPContractNotRouterError(offRamp, 'unknown')
   }
@@ -305,7 +317,10 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return Promise.resolve(router)
   }
 
-  /** {@inheritDoc Chain.getOnRampForOffRamp} */
+  /**
+   * {@inheritDoc Chain.getOnRampForOffRamp}
+   * @throws {@link CCIPDataFormatUnsupportedError} if view call fails
+   */
   async getOnRampForOffRamp(offRamp: string, sourceChainSelector: bigint): Promise<string> {
     offRamp = await getLatestPackageId(offRamp, this.client)
     const functionName = 'get_source_chain_config'
@@ -383,7 +398,11 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return Promise.resolve(offRamp)
   }
 
-  /** {@inheritDoc Chain.getTokenForTokenPool} */
+  /**
+   * {@inheritDoc Chain.getTokenForTokenPool}
+   * @throws {@link CCIPError} if token pool type is invalid or state not found
+   * @throws {@link CCIPDataFormatUnsupportedError} if view call fails
+   */
   async getTokenForTokenPool(tokenPool: string): Promise<string> {
     const normalizedTokenPool = normalizeSuiAddress(tokenPool)
 
@@ -481,7 +500,10 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return coinMetadataAddress
   }
 
-  /** {@inheritDoc Chain.getTokenInfo} */
+  /**
+   * {@inheritDoc Chain.getTokenInfo}
+   * @throws {@link CCIPError} if token address is invalid or metadata cannot be loaded
+   */
   async getTokenInfo(token: string): Promise<{ symbol: string; decimals: number }> {
     const normalizedTokenAddress = normalizeSuiAddress(token)
     if (!isValidSuiAddress(normalizedTokenAddress)) {
@@ -558,6 +580,7 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
    * Decodes a CCIP message from a Sui log event.
    * @param log - Log event data.
    * @returns Decoded CCIPMessage or undefined if not valid.
+   * @throws {@link CCIPSuiLogInvalidError} if log data format is invalid
    */
   static decodeMessage(log: Log_): CCIPMessage | undefined {
     const { data } = log
@@ -592,6 +615,7 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
    * Encodes extra arguments for CCIP messages.
    * @param _extraArgs - Extra arguments to encode.
    * @returns Encoded extra arguments as a hex string.
+   * @throws {@link CCIPNotImplementedError} always (not yet implemented)
    */
   static encodeExtraArgs(_extraArgs: ExtraArgs): string {
     throw new CCIPNotImplementedError()
@@ -723,7 +747,11 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return Promise.reject(new CCIPNotImplementedError('SuiChain.generateUnsignedExecuteReport'))
   }
 
-  /** {@inheritDoc Chain.executeReport} */
+  /**
+   * {@inheritDoc Chain.executeReport}
+   * @throws {@link CCIPError} if transaction submission fails
+   * @throws {@link CCIPExecTxRevertedError} if transaction reverts
+   */
   async executeReport(
     opts: Parameters<Chain['executeReport']>[0] & {
       receiverObjectIds?: string[]
@@ -838,9 +866,9 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     return Promise.reject(new CCIPNotImplementedError('SuiChain.getRegistryTokenConfig'))
   }
 
-  /** {@inheritDoc Chain.getTokenPoolConfigs} */
-  async getTokenPoolConfigs(_tokenPool: string): Promise<never> {
-    return Promise.reject(new CCIPNotImplementedError('SuiChain.getTokenPoolConfigs'))
+  /** {@inheritDoc Chain.getTokenPoolConfig} */
+  async getTokenPoolConfig(_tokenPool: string): Promise<never> {
+    return Promise.reject(new CCIPNotImplementedError('SuiChain.getTokenPoolConfig'))
   }
 
   /** {@inheritDoc Chain.getTokenPoolRemotes} */
@@ -872,7 +900,8 @@ export class SuiChain extends Chain<typeof ChainFamily.Sui> {
     const tokenReceiver =
       message.extraArgs &&
       'tokenReceiver' in message.extraArgs &&
-      message.extraArgs.tokenReceiver != null
+      message.extraArgs.tokenReceiver != null &&
+      typeof message.extraArgs.tokenReceiver === 'string'
         ? message.extraArgs.tokenReceiver
         : message.tokenAmounts?.length
           ? this.getAddress(message.receiver)