@sodax/dapp-kit 0.0.1-rc.3 → 0.0.1-rc.30

package/src/hooks/mm/useReservesHumanized.ts

@@ -0,0 +1,30 @@
+import type { ReservesDataHumanized } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext';
+/**
+ * Hook for fetching humanized reserves data from the Sodax money market.
+ *
+ * This hook provides access to the current state of all reserves (humanized format) in the money market protocol,
+ * including liquidity, interest rates, and other key metrics. The data is automatically
+ * fetched and cached using React Query.
+ *
+ * @example
+ * ```typescript
+ * const { data: reservesHumanized, isLoading, error } = useReservesHumanized();
+ * ```
+ *
+ * @returns A React Query result object containing:
+ *   - data: The reserves humanized data when available
+ *   - isLoading: Loading state indicator
+ *   - error: Any error that occurred during data fetching
+ */
+export function useReservesHumanized(): UseQueryResult<ReservesDataHumanized, Error> {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['reservesHumanized'],
+    queryFn: async () => {
+      return await sodax.moneyMarket.data.getReservesHumanized();
+    },
+  });
+}

package/src/hooks/mm/useReservesList.ts

@@ -0,0 +1,29 @@
+import { useQuery } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext';
+
+/**
+ * Hook for fetching list of reserves from the Sodax money market.
+ *
+ * This hook provides access to the list of addresses of all reserves in the money market protocol.
+ * The data is automatically fetched and cached using React Query.
+ *
+ * @example
+ * ```typescript
+ * const { data: reservesList, isLoading, error } = useReservesList();
+ * ```
+ *
+ * @returns A React Query result object containing:
+ *   - data: The reserves list when available
+ *   - isLoading: Loading state indicator
+ *   - error: Any error that occurred during data fetching
+ */
+export function useReservesList() {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['reservesList'],
+    queryFn: async () => {
+      return await sodax.moneyMarket.data.getReservesList();
+    },
+  });
+}

package/src/hooks/mm/useReservesUsdFormat.ts

@@ -0,0 +1,38 @@
+import type { FormatReserveUSDResponse, ReserveData } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext';
+
+/**
+ * Hook for fetching formatted summary of Sodax user portfolio (holdings, total liquidity,
+ *  collateral, borrows, liquidation threshold, health factor, available borrowing power, etc..).
+ *
+ * This hook provides access to the current state of user portfolio in the money market protocol.
+ * The data is automatically fetched and cached using React Query.
+ *
+ * @example
+ * ```typescript
+ * const { data: userFormattedSummary, isLoading, error } = useUserFormattedSummary();
+ * ```
+ *
+ * @returns A React Query result object containing:
+ *   - data: The formatted summary of Sodax user portfolio when available
+ *   - isLoading: Loading state indicator
+ *   - error: Any error that occurred during data fetching
+ */
+export function useReservesUsdFormat(): UseQueryResult<
+  (ReserveData & { priceInMarketReferenceCurrency: string } & FormatReserveUSDResponse)[],
+  Error
+> {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['reservesUsdFormat'],
+    queryFn: async () => {
+      // fetch reserves and hub wallet address
+      const reserves = await sodax.moneyMarket.data.getReservesHumanized();
+
+      // format reserves
+      return sodax.moneyMarket.data.formatReservesUSD(sodax.moneyMarket.data.buildReserveDataWithPrice(reserves));
+    },
+  });
+}

package/src/hooks/mm/useSupply.ts

@@ -1,13 +1,12 @@
-import type { SpokeChainId } from '@sodax/sdk';
+import type { SpokeProvider } from '@sodax/sdk';
 import type { XToken } from '@sodax/types';
 import { useMutation, type UseMutationResult } from '@tanstack/react-query';
 import { parseUnits } from 'viem';
-import { useSpokeProvider } from '../provider/useSpokeProvider';
 import { useSodaxContext } from '../shared/useSodaxContext';
 
 interface SupplyResponse {
   ok: true;
-  value: [`0x${string}`, `0x${string}`];
+  value: [string, string];
 }
 
 /**
@@ -18,6 +17,7 @@ interface SupplyResponse {
  * and cross-chain communication.
  *
  * @param {XToken} spokeToken - The token to supply on the spoke chain. Must be an XToken with valid address and chain information.
+ * @param {SpokeProvider} spokeProvider - The spoke provider to use for the supply transaction. Must be a valid SpokeProvider instance.
  *
  * @returns {UseMutationResult<SupplyResponse, Error, string>} A mutation result object with the following properties:
  *   - mutateAsync: Function to execute the supply transaction
@@ -33,9 +33,11 @@ interface SupplyResponse {
  * @throws {Error} When:
  *   - spokeProvider is not available
  */
-export function useSupply(spokeToken: XToken): UseMutationResult<SupplyResponse, Error, string> {
+export function useSupply(
+  spokeToken: XToken,
+  spokeProvider: SpokeProvider | undefined,
+): UseMutationResult<SupplyResponse, Error, string> {
   const { sodax } = useSodaxContext();
-  const spokeProvider = useSpokeProvider(spokeToken.xChainId as SpokeChainId);
 
   return useMutation<SupplyResponse, Error, string>({
     mutationFn: async (amount: string) => {
@@ -43,10 +45,11 @@ export function useSupply(spokeToken: XToken): UseMutationResult<SupplyResponse,
         throw new Error('spokeProvider is not found');
       }
 
-      const response = await sodax.moneyMarket.supplyAndSubmit(
+      const response = await sodax.moneyMarket.supply(
         {
           token: spokeToken.address,
           amount: parseUnits(amount, spokeToken.decimals),
+          action: 'supply',
         },
         spokeProvider,
       );

package/src/hooks/mm/useUserFormattedSummary.ts

@@ -0,0 +1,54 @@
+import type { FormatUserSummaryResponse, FormatReserveUSDResponse, SpokeProvider } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext';
+
+/**
+ * Hook for fetching formatted summary of Sodax user portfolio (holdings, total liquidity,
+ *  collateral, borrows, liquidation threshold, health factor, available borrowing power, etc..).
+ *
+ * This hook provides access to the current state of user portfolio in the money market protocol.
+ * The data is automatically fetched and cached using React Query.
+ *
+ * @example
+ * ```typescript
+ * const { data: userFormattedSummary, isLoading, error } = useUserFormattedSummary(spokeProvider, address);
+ * ```
+ *
+ * @returns A React Query result object containing:
+ *   - data: The formatted summary of Sodax user portfolio when available
+ *   - isLoading: Loading state indicator
+ *   - error: Any error that occurred during data fetching
+ */
+export function useUserFormattedSummary(
+  spokeProvider: SpokeProvider | undefined,
+  address: string | undefined,
+): UseQueryResult<FormatUserSummaryResponse<FormatReserveUSDResponse>, Error> {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['userFormattedSummary', spokeProvider?.chainConfig.chain.id, address],
+    queryFn: async () => {
+      if (!spokeProvider || !address) {
+        throw new Error('Spoke provider or address is not defined');
+      }
+
+      // fetch reserves and hub wallet address
+      const reserves = await sodax.moneyMarket.data.getReservesHumanized();
+
+      // format reserves
+      const formattedReserves = sodax.moneyMarket.data.formatReservesUSD(
+        sodax.moneyMarket.data.buildReserveDataWithPrice(reserves),
+      );
+
+      // fetch user reserves
+      const userReserves = await sodax.moneyMarket.data.getUserReservesHumanized(spokeProvider);
+
+      // format user summary
+      return sodax.moneyMarket.data.formatUserSummary(
+        sodax.moneyMarket.data.buildUserSummaryRequest(reserves, formattedReserves, userReserves),
+      );
+    },
+    enabled: !!spokeProvider && !!address,
+    refetchInterval: 5000,
+  });
+}

package/src/hooks/mm/useUserReservesData.ts

@@ -1,58 +1,40 @@
-import { allXTokens } from '@/core';
-import { getMoneyMarketConfig, type EvmHubProvider } from '@sodax/sdk';
-import type { HubChainId, SpokeChainId } from '@sodax/types';
-import { useXAccount, useWalletProvider } from '@sodax/wallet-sdk';
-import type { ChainId } from '@sodax/types';
-import { useQuery } from '@tanstack/react-query';
-import { useHubProvider } from '../provider/useHubProvider';
-import { useHubWalletAddress } from './useHubWalletAddress';
+import type { SpokeProvider, UserReserveData } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
 import { useSodaxContext } from '../shared/useSodaxContext';
 
-export function useUserReservesData(spokeChainId: ChainId) {
+/**
+ * Hook for fetching user reserves data from the Sodax money market.
+ *
+ * This hook provides access to the current state of user reserves in the money market protocol.
+ * The data is automatically fetched and cached using React Query.
+ *
+ * @example
+ * ```typescript
+ * const { data: userReservesData, isLoading, error } = useUserReservesData(spokeProvider, address);
+ * ```
+ *
+ * @returns A React Query result object containing:
+ *   - data: The user reserves data when available
+ *   - isLoading: Loading state indicator
+ *   - error: Any error that occurred during data fetching
+ */
+export function useUserReservesData(
+  spokeProvider: SpokeProvider | undefined,
+  address: string | undefined,
+  refetchInterval = 5000,
+): UseQueryResult<readonly [readonly UserReserveData[], number], Error> {
   const { sodax } = useSodaxContext();
-  const hubChainId = (sodax.config?.hubProviderConfig?.chainConfig.chain.id ?? 'sonic') as HubChainId;
-  const hubWalletProvider = useWalletProvider(hubChainId);
-  const hubProvider = useHubProvider();
-  const { address } = useXAccount(spokeChainId);
-  const { data: hubWalletAddress } = useHubWalletAddress(
-    spokeChainId as SpokeChainId,
-    address,
-    hubProvider as EvmHubProvider,
-  );
 
-  const { data: userReserves } = useQuery({
-    queryKey: ['userReserves', hubWalletAddress],
+  return useQuery({
+    queryKey: ['userReserves', spokeProvider?.chainConfig.chain.id, address],
     queryFn: async () => {
-      if (!hubWalletProvider) {
-        return;
+      if (!spokeProvider) {
+        throw new Error('Spoke provider or address is not defined');
       }
 
-      if (!hubWalletAddress) {
-        return;
-      }
-
-      const moneyMarketConfig = getMoneyMarketConfig(hubChainId);
-      try {
-        const [res] = await sodax.moneyMarket.getUserReservesData(
-          hubWalletAddress as `0x${string}`,
-          moneyMarketConfig.uiPoolDataProvider,
-          moneyMarketConfig.poolAddressesProvider,
-        );
-
-        return res?.map(r => {
-          return {
-            ...r,
-            token: allXTokens.find(t => t.address === r.underlyingAsset),
-          };
-        });
-      } catch (error) {
-        console.log('error', error);
-        return;
-      }
+      return await sodax.moneyMarket.data.getUserReservesData(spokeProvider);
     },
-    enabled: !!address && !!hubWalletProvider && !!hubWalletAddress,
-    refetchInterval: 5000,
+    enabled: !!spokeProvider && !!address,
+    refetchInterval,
   });
-
-  return userReserves;
 }

package/src/hooks/mm/useWithdraw.ts

@@ -1,13 +1,12 @@
-import type { SpokeChainId } from '@sodax/sdk';
-import type { ChainId, XToken } from '@sodax/types';
+import type { SpokeProvider } from '@sodax/sdk';
+import type { XToken } from '@sodax/types';
 import { useMutation, type UseMutationResult } from '@tanstack/react-query';
 import { parseUnits } from 'viem';
-import { useSpokeProvider } from '../provider/useSpokeProvider';
 import { useSodaxContext } from '../shared/useSodaxContext';
 
 interface WithdrawResponse {
   ok: true;
-  value: [`0x${string}`, `0x${string}`];
+  value: [string, string];
 }
 
 /**
@@ -17,9 +16,15 @@ interface WithdrawResponse {
  * handling the entire withdrawal process including transaction creation, submission,
  * and cross-chain communication.
  *
+ * @param {XToken} spokeToken - The token to withdraw from the spoke chain. Must be an XToken with valid address and chain information.
+ * @param {SpokeProvider} spokeProvider - The spoke provider to use for the withdraw transaction. Must be a valid SpokeProvider instance.
+ *
+ * @returns {UseMutationResult<WithdrawResponse, Error, string>} A mutation result object with the following properties:
+ *   - mutateAsync: Function to execute the withdraw transaction
+ *   - isPending: Boolean indicating if a transaction is in progress
  * @example
  * ```typescript
- * const { mutateAsync: withdraw, isPending, error } = useWithdraw(hubToken, spokeChainId);
+ * const { mutateAsync: withdraw, isPending, error } = useWithdraw(spokeToken);
  * await withdraw('100');
  * ```
  *
@@ -28,11 +33,10 @@ interface WithdrawResponse {
  *   - Transaction execution fails
  */
 export function useWithdraw(
-  hubToken: XToken,
-  spokeChainId: ChainId,
+  spokeToken: XToken,
+  spokeProvider: SpokeProvider | undefined,
 ): UseMutationResult<WithdrawResponse, Error, string> {
   const { sodax } = useSodaxContext();
-  const spokeProvider = useSpokeProvider(spokeChainId as SpokeChainId);
 
   return useMutation<WithdrawResponse, Error, string>({
     mutationFn: async (amount: string) => {
@@ -40,10 +44,12 @@ export function useWithdraw(
         throw new Error('spokeProvider is not found');
       }
 
-      const response = await sodax.moneyMarket.withdrawAndSubmit(
+      const response = await sodax.moneyMarket.withdraw(
         {
-          token: hubToken.address,
-          amount: parseUnits(amount, hubToken.decimals),
+          token: spokeToken.address,
+          // vault token on hub chain decimals is 18
+          amount: parseUnits(amount, 18),
+          action: 'withdraw',
         },
         spokeProvider,
       );

package/src/hooks/provider/useHubProvider.ts

@@ -1,26 +1,8 @@
-import { EvmHubProvider, getHubChainConfig, type HubChainId } from '@sodax/sdk';
-import { getXChainType } from '@sodax/wallet-sdk';
-import { useMemo } from 'react';
+import type { EvmHubProvider } from '@sodax/sdk';
 import { useSodaxContext } from '../shared/useSodaxContext';
 
-export function useHubProvider(): EvmHubProvider | undefined {
+export function useHubProvider(): EvmHubProvider {
   const { sodax } = useSodaxContext();
-  const hubChainId = sodax.config?.hubProviderConfig?.chainConfig.chain.id;
-  const hubRpcUrl = sodax.config?.hubProviderConfig?.hubRpcUrl;
-  const xChainType = getXChainType(hubChainId);
-  const hubProvider = useMemo(() => {
-    if (xChainType === 'EVM' && hubChainId && hubRpcUrl) {
-      const hubChainCfg = getHubChainConfig(hubChainId);
 
-      if (!hubChainCfg) return undefined;
-
-      return new EvmHubProvider({
-        hubRpcUrl: hubRpcUrl,
-        chainConfig: hubChainCfg,
-      });
-    }
-    return undefined;
-  }, [xChainType, hubChainId, hubRpcUrl]);
-
-  return hubProvider;
+  return sodax.hubProvider;
 }

package/src/hooks/provider/useSpokeProvider.ts

@@ -1,33 +1,124 @@
+import { useSodaxContext } from '@/index';
 import {
   EvmSpokeProvider,
   spokeChainConfig,
   type SuiSpokeChainConfig,
   SuiSpokeProvider,
   type EvmSpokeChainConfig,
+  IconSpokeProvider,
+  type IconSpokeChainConfig,
+  InjectiveSpokeProvider,
+  type InjectiveSpokeChainConfig,
+  StellarSpokeProvider,
+  type StellarSpokeChainConfig,
+  type SpokeProvider,
+  type IWalletProvider,
+  SolanaSpokeProvider,
+  type SolanaChainConfig,
+  SONIC_MAINNET_CHAIN_ID,
+  SonicSpokeProvider,
+  type SonicSpokeChainConfig,
 } from '@sodax/sdk';
-import type { IEvmWalletProvider, ISuiWalletProvider, SpokeChainId } from '@sodax/types';
-import { getXChainType, useWalletProvider } from '@sodax/wallet-sdk';
+import type {
+  IEvmWalletProvider,
+  IIconWalletProvider,
+  ISuiWalletProvider,
+  SpokeChainId,
+  IInjectiveWalletProvider,
+  IStellarWalletProvider,
+  ISolanaWalletProvider,
+} from '@sodax/types';
 import { useMemo } from 'react';
 
-export function useSpokeProvider(spokeChainId: SpokeChainId) {
-  const xChainType = getXChainType(spokeChainId);
-  const walletProvider = useWalletProvider(spokeChainId);
+/**
+ * Hook to get the appropriate spoke provider based on the chain type.
+ * Supports EVM, SUI, ICON and INJECTIVE chains.
+ *
+ * @param {SpokeChainId | undefined} spokeChainId - The spoke chain ID to get the provider for
+ * @param {IWalletProvider | undefined} walletProvider - The wallet provider to use
+ * @returns {SpokeProvider | undefined} The appropriate spoke provider instance for the given chain ID, or undefined if invalid/unsupported
+ *
+ * @example
+ * ```tsx
+ * // Using a specific SpokeChainId and wallet provider
+ * const spokeProvider = useSpokeProvider(spokeChainId, walletProvider);
+ * ```
+ */
+export function useSpokeProvider(
+  spokeChainId: SpokeChainId | undefined,
+  walletProvider?: IWalletProvider | undefined,
+): SpokeProvider | undefined {
+  const { rpcConfig } = useSodaxContext();
+  const xChainType = spokeChainId ? spokeChainConfig[spokeChainId]?.chain.type : undefined;
+
   const spokeProvider = useMemo(() => {
     if (!walletProvider) return undefined;
+    if (!spokeChainId) return undefined;
+    if (!xChainType) return undefined;
+    if (!rpcConfig) return undefined;
+    
     if (xChainType === 'EVM') {
+      if (spokeChainId === SONIC_MAINNET_CHAIN_ID) {
+        return new SonicSpokeProvider(
+          walletProvider as IEvmWalletProvider,
+          spokeChainConfig[spokeChainId] as SonicSpokeChainConfig,
+        );
+      }
       return new EvmSpokeProvider(
         walletProvider as IEvmWalletProvider,
         spokeChainConfig[spokeChainId] as EvmSpokeChainConfig,
       );
     }
+
     if (xChainType === 'SUI') {
       return new SuiSpokeProvider(
         spokeChainConfig[spokeChainId] as SuiSpokeChainConfig,
         walletProvider as ISuiWalletProvider,
       );
     }
+
+    if (xChainType === 'ICON') {
+      return new IconSpokeProvider(
+        walletProvider as IIconWalletProvider,
+        spokeChainConfig[spokeChainId] as IconSpokeChainConfig,
+      );
+    }
+
+    if (xChainType === 'INJECTIVE') {
+      return new InjectiveSpokeProvider(
+        spokeChainConfig[spokeChainId] as InjectiveSpokeChainConfig,
+        walletProvider as IInjectiveWalletProvider,
+      );
+    }
+
+    if (xChainType === 'STELLAR') {
+      const stellarConfig = spokeChainConfig[spokeChainId] as StellarSpokeChainConfig;
+      return new StellarSpokeProvider(
+        walletProvider as IStellarWalletProvider,
+        stellarConfig,
+        rpcConfig.stellar
+          ? rpcConfig.stellar
+          : {
+              horizonRpcUrl: stellarConfig.horizonRpcUrl,
+              sorobanRpcUrl: stellarConfig.sorobanRpcUrl,
+            },
+      );
+    }
+
+    if (xChainType === 'SOLANA') {
+      return new SolanaSpokeProvider(
+        walletProvider as ISolanaWalletProvider,
+        rpcConfig.solana
+          ? ({
+              ...spokeChainConfig[spokeChainId],
+              rpcUrl: rpcConfig.solana,
+            } as SolanaChainConfig)
+          : (spokeChainConfig[spokeChainId] as SolanaChainConfig),
+      );
+    }
+
     return undefined;
-  }, [walletProvider, xChainType, spokeChainId]);
+  }, [spokeChainId, xChainType, walletProvider, rpcConfig]);
 
   return spokeProvider;
 }

package/src/hooks/shared/index.ts

@@ -1,3 +1,5 @@
 export * from './useSodaxContext';
-export * from './useAllowance';
-export * from './useApprove';
+export * from './useEstimateGas';
+export * from './useDeriveUserWalletAddress';
+export * from './useStellarTrustlineCheck';
+export * from './useRequestTrustline';

package/src/hooks/shared/useDeriveUserWalletAddress.ts

@@ -0,0 +1,44 @@
+// packages/dapp-kit/src/hooks/shared/useDeriveUserWalletAddress.ts
+import { deriveUserWalletAddress, type SpokeProvider } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from './useSodaxContext';
+import type { Address } from 'viem';
+
+/**
+ * Hook for deriving user wallet address for hub abstraction.
+ *
+ * This hook derives the user's abstracted wallet address for the hub chain.
+ * If the spoke chain is the same as the hub chain, it returns the original wallet address.
+ * Otherwise, it returns the abstracted wallet address for cross-chain operations.
+ *
+ * @param spokeProvider - The spoke provider instance for the origin chain
+ * @param walletAddress - Optional user wallet address on spoke chain. If not provided, will fetch from spokeProvider
+ * @returns A React Query result object containing:
+ *   - data: The derived user wallet address when available
+ *   - isLoading: Loading state indicator
+ *   - error: Any error that occurred during derivation
+ *
+ * @example
+ * ```typescript
+ * const { data: derivedAddress, isLoading, error } = useDeriveUserWalletAddress(spokeProvider, userAddress);
+ * ```
+ */
+export function useDeriveUserWalletAddress(
+  spokeProvider: SpokeProvider | undefined,
+  walletAddress?: string | undefined,
+): UseQueryResult<Address, Error> {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['deriveUserWalletAddress', spokeProvider?.chainConfig.chain.id, walletAddress],
+    queryFn: async (): Promise<Address> => {
+      if (!spokeProvider) {
+        throw new Error('Spoke provider is required');
+      }
+
+      return await deriveUserWalletAddress(spokeProvider, sodax.hubProvider, walletAddress);
+    },
+    enabled: !!spokeProvider,
+    refetchInterval: false, // This is a deterministic operation, no need to refetch
+  });
+}

package/src/hooks/shared/useEstimateGas.ts

@@ -0,0 +1,18 @@
+import { type GetEstimateGasReturnType, type SpokeProvider, SpokeService, type TxReturnType } from '@sodax/sdk';
+import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+
+export function useEstimateGas<T extends SpokeProvider = SpokeProvider>(
+  spokeProvider: T | undefined,
+): UseMutationResult<GetEstimateGasReturnType<T>, Error, TxReturnType<T, true>> {
+  return useMutation<GetEstimateGasReturnType<T>, Error, TxReturnType<T, true>>({
+    mutationFn: async (rawTx: TxReturnType<T, true>) => {
+      if (!spokeProvider) {
+        throw new Error('spokeProvider is not found');
+      }
+
+      const response = await SpokeService.estimateGas(rawTx, spokeProvider);
+
+      return response;
+    },
+  });
+}

package/src/hooks/shared/useRequestTrustline.ts

@@ -0,0 +1,82 @@
+import { type SpokeProvider, StellarSpokeProvider, StellarSpokeService, type TxReturnType } from '@sodax/sdk';
+import { useMutation, type UseMutationResult, useQueryClient } from '@tanstack/react-query';
+
+/**
+ * React hook to request a Stellar trustline for a given token and amount.
+ *
+ * This hook provides a mutation for requesting a trustline on the Stellar network
+ * using the provided SpokeProvider. It is intended for use with StellarSpokeProvider
+ * and will throw if used with a non-Stellar provider. Upon success, it invalidates
+ * the trustline check query to ensure UI reflects the updated trustline state.
+ *
+ * @template T - The type of SpokeProvider, defaults to SpokeProvider.
+ * @param {string | undefined} token - The Stellar asset code or token address for which to request a trustline.
+ * @returns {UseMutationResult<TxReturnType<StellarSpokeProvider, false>, Error, { token: string; amount: bigint; spokeProvider: T }>}
+ *   A React Query mutation result object containing:
+ *   - `mutate`/`mutateAsync`: Function to trigger the trustline request.
+ *   - `data`: The transaction result if successful.
+ *   - `error`: Any error encountered during the request.
+ *   - `isLoading`: Whether the mutation is in progress.
+ *   - Other React Query mutation state.
+ *
+ * @example
+ * ```tsx
+ * import { useRequestTrustline } from '@sodax/dapp-kit';
+ *
+ * const { mutate: requestTrustline, isLoading, error, data } = useRequestTrustline('USDC-G...TOKEN');
+ *
+ * // To request a trustline:
+ * requestTrustline({
+ *   token: 'USDC-G...TOKEN',
+ *   amount: 10000000n,
+ *   spokeProvider: stellarProvider,
+ * });
+ *
+ * if (isLoading) return <span>Requesting trustline...</span>;
+ * if (error) return <span>Error: {error.message}</span>;
+ * if (data) return <span>Trustline requested! Tx: {data.txHash}</span>;
+ * ```
+ */
+
+export function useRequestTrustline<T extends SpokeProvider = SpokeProvider>(
+  token: string | undefined,
+): UseMutationResult<
+  TxReturnType<StellarSpokeProvider, false>,
+  Error,
+  {
+    token: string;
+    amount: bigint;
+    spokeProvider: T;
+  }
+> {
+  const queryClient = useQueryClient();
+
+  return useMutation<
+    TxReturnType<StellarSpokeProvider, false>,
+    Error,
+    {
+      token: string;
+      amount: bigint;
+      spokeProvider: T;
+    }
+  >({
+    mutationFn: async ({
+      token,
+      amount,
+      spokeProvider,
+    }: {
+      token: string;
+      amount: bigint;
+      spokeProvider: T;
+    }) => {
+      if (!spokeProvider || !token || !amount || !(spokeProvider instanceof StellarSpokeProvider)) {
+        throw new Error('Spoke provider, token or amount not found');
+      }
+
+      return StellarSpokeService.requestTrustline(token, amount, spokeProvider);
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['stellar-trustline-check', token] });
+    },
+  });
+}