@sodax/dapp-kit 0.0.1-rc.9 → 1.0.0-beta

package/src/hooks/shared/useRequestTrustline.ts

@@ -0,0 +1,103 @@
+import { type SpokeProvider, StellarSpokeProvider, StellarSpokeService, type TxReturnType } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useCallback, useState } from 'react';
+
+/**
+ * React hook to request a Stellar trustline for a given token and amount.
+ *
+ * This hook provides a callback function 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 {Object} An object containing:
+ *   - `requestTrustline`: Function to trigger the trustline request.
+ *   - `isLoading`: Whether the request is in progress.
+ *   - `isRequested`: Whether a trustline has been successfully requested.
+ *   - `error`: Any error encountered during the request.
+ *   - `data`: The transaction result if successful.
+ *
+ * @example
+ * ```tsx
+ * import { useRequestTrustline } from '@sodax/dapp-kit';
+ *
+ * const { requestTrustline, isLoading, isRequested, error, data } = useRequestTrustline('USDC-G...TOKEN');
+ *
+ * // To request a trustline:
+ * await 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 (isRequested) return <span>Trustline requested! Tx: {data?.txHash}</span>;
+ * ```
+ */
+
+export function useRequestTrustline<T extends SpokeProvider = SpokeProvider>(
+  token: string | undefined,
+): {
+  requestTrustline: (params: {
+    token: string;
+    amount: bigint;
+    spokeProvider: T;
+  }) => Promise<TxReturnType<StellarSpokeProvider, false>>;
+  isLoading: boolean;
+  isRequested: boolean;
+  error: Error | null;
+  data: TxReturnType<StellarSpokeProvider, false> | null;
+} {
+  const queryClient = useQueryClient();
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [isRequested, setIsRequested] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [data, setData] = useState<TxReturnType<StellarSpokeProvider, false> | null>(null);
+
+  const requestTrustline = useCallback(
+    async ({
+      token,
+      amount,
+      spokeProvider,
+    }: {
+      token: string;
+      amount: bigint;
+      spokeProvider: T;
+    }): Promise<TxReturnType<StellarSpokeProvider, false>> => {
+      if (!spokeProvider || !token || !amount || !(spokeProvider instanceof StellarSpokeProvider)) {
+        const error = new Error('Spoke provider, token or amount not found');
+        setError(error);
+        throw error;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const result = await StellarSpokeService.requestTrustline(token, amount, spokeProvider);
+        setData(result);
+        setIsRequested(true);
+        queryClient.invalidateQueries({ queryKey: ['stellar-trustline-check', token] });
+        return result;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Unknown error occurred');
+        setError(error);
+        throw error;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [queryClient],
+  );
+
+  return {
+    requestTrustline,
+    isLoading,
+    isRequested,
+    error,
+    data,
+  };
+}

package/src/hooks/shared/useStellarTrustlineCheck.ts

@@ -0,0 +1,71 @@
+import { STELLAR_MAINNET_CHAIN_ID, StellarSpokeProvider, StellarSpokeService } from '@sodax/sdk';
+import type { SpokeChainId, SpokeProvider } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * React hook to check if a Stellar account has a sufficient trustline for a given token and amount.
+ *
+ * This hook queries the Stellar network (via the provided SpokeProvider) to determine
+ * whether the account has established a trustline for the specified token and if the trustline
+ * is sufficient for the intended amount. It is useful for gating UI actions that require
+ * a trustline to be present and funded.
+ *
+ * @template T - The type of SpokeProvider, defaults to SpokeProvider.
+ * @param {string | undefined} token - The Stellar asset code or token address to check the trustline for.
+ * @param {bigint | undefined} amount - The minimum amount required for the trustline.
+ * @param {T | undefined} spokeProvider - The provider instance for interacting with the Stellar network.
+ * @param {SpokeChainId | undefined} chainId - The chain ID to determine if the check should be performed (only on Stellar mainnet).
+ * @returns {UseQueryResult<boolean, Error>} A React Query result object containing:
+ *   - `data`: `true` if the trustline exists and is sufficient, `false` otherwise.
+ *   - `error`: Any error encountered during the check.
+ *   - `isLoading`: Whether the query is in progress.
+ *   - Other React Query state.
+ *
+ * @example
+ * ```tsx
+ * import { useStellarTrustlineCheck } from '@sodax/dapp-kit';
+ *
+ * const { data: hasTrustline, isLoading, error } = useStellarTrustlineCheck(
+ *   'USDC-G...TOKEN',
+ *   10000000n,
+ *   stellarProvider,
+ *   'stellar'
+ * );
+ *
+ * if (isLoading) return <span>Checking trustline...</span>;
+ * if (error) return <span>Error: {error.message}</span>;
+ * if (!hasTrustline) return <span>Trustline not established or insufficient.</span>;
+ * return <span>Trustline is sufficient!</span>;
+ * ```
+ */
+
+export function useStellarTrustlineCheck<T extends SpokeProvider = SpokeProvider>(
+  token: string | undefined,
+  amount: bigint | undefined,
+  spokeProvider: T | undefined,
+  chainId: SpokeChainId | undefined,
+): UseQueryResult<boolean, Error> {
+  return useQuery({
+    queryKey: ['stellar-trustline-check', token],
+    queryFn: async () => {
+      if (chainId !== STELLAR_MAINNET_CHAIN_ID) {
+        return true;
+      }
+      if (!spokeProvider || !token || !amount || !(spokeProvider instanceof StellarSpokeProvider)) {
+        console.error(
+          'Spoke provider, token or amount not found. Details: spokeProvider:',
+          spokeProvider,
+          'token:',
+          token,
+          'amount:',
+          amount,
+        );
+        return false;
+      }
+      const response = await StellarSpokeService.hasSufficientTrustline(token, amount, spokeProvider);
+
+      return response;
+    },
+    enabled: !!spokeProvider && !!token && !!amount,
+  });
+}

package/src/hooks/staking/index.ts

@@ -0,0 +1,19 @@
+// packages/dapp-kit/src/hooks/staking/index.ts
+export { useStake } from './useStake';
+export { useStakeApprove } from './useStakeApprove';
+export { useStakeAllowance } from './useStakeAllowance';
+export { useUnstake } from './useUnstake';
+export { useClaim } from './useClaim';
+export { useCancelUnstake } from './useCancelUnstake';
+export { useStakingInfo } from './useStakingInfo';
+export { useUnstakingInfoWithPenalty } from './useUnstakingInfoWithPenalty';
+export { useStakingConfig } from './useStakingConfig';
+export { useStakeRatio } from './useStakeRatio';
+export { useInstantUnstakeRatio } from './useInstantUnstakeRatio';
+export { useConvertedAssets } from './useConvertedAssets';
+export { useInstantUnstake } from './useInstantUnstake';
+export { useUnstakeAllowance } from './useUnstakeAllowance';
+export { useUnstakeApprove } from './useUnstakeApprove';
+export { useUnstakingInfo } from './useUnstakingInfo';
+export { useInstantUnstakeApprove } from './useInstantUnstakeApprove';
+export { useInstantUnstakeAllowance } from './useInstantUnstakeAllowance';

package/src/hooks/staking/useCancelUnstake.ts

@@ -0,0 +1,52 @@
+// packages/dapp-kit/src/hooks/staking/useCancelUnstake.ts
+import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext';
+import type { CancelUnstakeParams, SpokeProvider, SpokeTxHash, HubTxHash } from '@sodax/sdk';
+
+/**
+ * Hook for executing cancel unstake transactions to cancel pending unstake requests.
+ * Uses React Query's useMutation for better state management and caching.
+ *
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider to use for the cancel unstake
+ * @returns {UseMutationResult<[SpokeTxHash, HubTxHash], Error, Omit<CancelUnstakeParams, 'action'>>} Mutation result object containing mutation function and state
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsync: cancelUnstake, isPending } = useCancelUnstake(spokeProvider);
+ *
+ * const handleCancelUnstake = async () => {
+ *   const result = await cancelUnstake({
+ *     requestId: 1n
+ *   });
+ *
+ *   console.log('Cancel unstake successful:', result);
+ * };
+ * ```
+ */
+export function useCancelUnstake(
+  spokeProvider: SpokeProvider | undefined,
+): UseMutationResult<[SpokeTxHash, HubTxHash], Error, Omit<CancelUnstakeParams, 'action'>> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (params: Omit<CancelUnstakeParams, 'action'>) => {
+      if (!spokeProvider) {
+        throw new Error('Spoke provider not available');
+      }
+
+      const result = await sodax.staking.cancelUnstake({ ...params, action: 'cancelUnstake' }, spokeProvider);
+      if (!result.ok) {
+        throw new Error(`Cancel unstake failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+    onSuccess: () => {
+      // Invalidate relevant queries to refresh data
+      queryClient.invalidateQueries({ queryKey: ['stakingInfo'] });
+      queryClient.invalidateQueries({ queryKey: ['unstakingInfo'] });
+      queryClient.invalidateQueries({ queryKey: ['unstakingInfoWithPenalty'] });
+    },
+  });
+}

package/src/hooks/staking/useClaim.ts

@@ -0,0 +1,46 @@
+// packages/dapp-kit/src/hooks/staking/useClaim.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import type { ClaimParams, SpokeTxHash, HubTxHash, SpokeProvider } from '@sodax/sdk';
+import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+
+/**
+ * Hook for executing claim transactions to claim unstaked SODA tokens after the unstaking period.
+ * Uses React Query's useMutation for better state management and caching.
+ *
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider to use for the claim
+ * @returns {UseMutationResult<[SpokeTxHash, HubTxHash], Error, Omit<ClaimParams, 'action'>>} Mutation result object containing mutation function and state
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsync: claim, isPending } = useClaim(spokeProvider);
+ *
+ * const handleClaim = async () => {
+ *   const result = await claim({
+ *     requestId: 1n
+ *   });
+ *
+ *   console.log('Claim successful:', result);
+ * };
+ * ```
+ */
+export function useClaim(
+  spokeProvider: SpokeProvider | undefined,
+): UseMutationResult<[SpokeTxHash, HubTxHash], Error, Omit<ClaimParams, 'action'>> {
+  const { sodax } = useSodaxContext();
+
+  return useMutation<[SpokeTxHash, HubTxHash], Error, Omit<ClaimParams, 'action'>>({
+    mutationFn: async (params: Omit<ClaimParams, 'action'>) => {
+      if (!spokeProvider) {
+        throw new Error('Spoke provider not found');
+      }
+
+      const result = await sodax.staking.claim({ ...params, action: 'claim' }, spokeProvider);
+
+      if (!result.ok) {
+        throw new Error(`Claim failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+  });
+}

package/src/hooks/staking/useConvertedAssets.ts

@@ -0,0 +1,47 @@
+// packages/dapp-kit/src/hooks/staking/useConvertedAssets.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * Hook for fetching converted assets amount for xSODA shares.
+ * Uses React Query for efficient caching and state management.
+ *
+ * @param {bigint | undefined} amount - The amount of xSODA shares to convert
+ * @param {number} refetchInterval - The interval in milliseconds to refetch data (default: 10000)
+ * @returns {UseQueryResult<bigint, Error>} Query result object containing converted assets amount and state
+ *
+ * @example
+ * ```typescript
+ * const { data: convertedAssets, isLoading, error } = useConvertedAssets(1000000000000000000n); // 1 xSODA
+ *
+ * if (isLoading) return <div>Loading converted assets...</div>;
+ * if (convertedAssets) {
+ *   console.log('Converted assets:', convertedAssets);
+ * }
+ * ```
+ */
+export function useConvertedAssets(amount: bigint | undefined, refetchInterval = 10000): UseQueryResult<bigint, Error> {
+  const { sodax } = useSodaxContext();
+
+  console.log('useConvertedAssets hook called with:', { amount: amount?.toString(), sodax: !!sodax });
+
+  return useQuery({
+    queryKey: ['soda', 'convertedAssets', amount?.toString()],
+    queryFn: async () => {
+      console.log('useConvertedAssets queryFn called with amount:', amount?.toString());
+      if (!amount || amount <= 0n) {
+        throw new Error('Amount must be greater than 0');
+      }
+
+      const result = await sodax.staking.getConvertedAssets(amount);
+
+      if (!result.ok) {
+        throw new Error(`Failed to fetch converted assets: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+    enabled: !!amount && amount > 0n && !!sodax?.staking,
+    refetchInterval,
+  });
+}

package/src/hooks/staking/useInstantUnstake.ts

@@ -0,0 +1,50 @@
+// packages/dapp-kit/src/hooks/staking/useInstantUnstake.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+import type { SpokeProvider, InstantUnstakeParams } from '@sodax/sdk';
+
+/**
+ * Hook for executing instant unstake operations.
+ * Uses React Query for efficient state management and error handling.
+ *
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider for the transaction
+ * @returns {UseMutationResult<[string, string], Error, Omit<InstantUnstakeParams, 'action'>>} Mutation result object containing instant unstake state and methods
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsync: instantUnstake, isPending } = useInstantUnstake(spokeProvider);
+ *
+ * const handleInstantUnstake = async () => {
+ *   const result = await instantUnstake({
+ *     amount: 1000000000000000000n,
+ *     minAmount: 950000000000000000n,
+ *     account: '0x...'
+ *   });
+ *   console.log('Instant unstake successful:', result);
+ * };
+ * ```
+ */
+export function useInstantUnstake(
+  spokeProvider: SpokeProvider | undefined,
+): UseMutationResult<[string, string], Error, Omit<InstantUnstakeParams, 'action'>> {
+  const { sodax } = useSodaxContext();
+
+  return useMutation({
+    mutationFn: async (params: Omit<InstantUnstakeParams, 'action'>) => {
+      if (!spokeProvider) {
+        throw new Error('spokeProvider is not found');
+      }
+
+      const result = await sodax.staking.instantUnstake({ ...params, action: 'instantUnstake' }, spokeProvider);
+
+      if (!result.ok) {
+        throw new Error(`Instant unstake failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+    onError: error => {
+      console.error('Instant unstake error:', error);
+    },
+  });
+}

package/src/hooks/staking/useInstantUnstakeAllowance.ts

@@ -0,0 +1,59 @@
+// packages/dapp-kit/src/hooks/staking/useStakeAllowance.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import type { SpokeProvider, InstantUnstakeParams } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * Hook for checking xSODA token allowance for instant unstaking operations.
+ * Uses React Query for efficient caching and state management.
+ *
+ * @param {Omit<InstantUnstakeParams, 'action'> | undefined} params - The instant unstaking parameters. If undefined, the query will be disabled.
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider to use for the allowance check
+ * @returns {UseQueryResult<boolean, Error>} Query result object containing allowance data and state
+ *
+ * @example
+ * ```typescript
+ * const { data: hasAllowed, isLoading } = useInstantUnstakeAllowance(
+ *   {
+ *     amount: 1000000000000000000n, // 1 xSODA
+ *     minAmount: 950000000000000000n, // 0.95 SODA
+ *     account: '0x...'
+ *   },
+ *   spokeProvider
+ * );
+ *
+ * if (isLoading) return <div>Checking allowance...</div>;
+ * if (hasAllowed) {
+ *   console.log('Sufficient allowance for instant unstaking');
+ * }
+ * ```
+ */
+export function useInstantUnstakeAllowance(
+  params: Omit<InstantUnstakeParams, 'action'> | undefined,
+  spokeProvider: SpokeProvider | undefined,
+): UseQueryResult<boolean, Error> {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['soda', 'instantUnstakeAllowance', params, spokeProvider?.chainConfig.chain.id],
+    queryFn: async () => {
+      if (!params || !spokeProvider) {
+        return false;
+      }
+
+      const result = await sodax.staking.isAllowanceValid({
+        params: { ...params, action: 'instantUnstake' },
+        spokeProvider,
+      });
+
+      if (!result.ok) {
+        console.error(`Unstake allowance check failed: ${result.error.code}, error: ${result.error.error}`);
+        throw new Error(`Unstake allowance check failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+    enabled: !!params && !!spokeProvider,
+    refetchInterval: 5000, // Refetch every 5 seconds
+  });
+}

package/src/hooks/staking/useInstantUnstakeApprove.ts

@@ -0,0 +1,52 @@
+// packages/dapp-kit/src/hooks/staking/useStakeApprove.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import type { InstantUnstakeParams, TxReturnType, SpokeProvider } from '@sodax/sdk';
+import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+
+/**
+ * Hook for approving xSODA token spending for instant unstaking operations.
+ * Uses React Query's useMutation for better state management and caching.
+ *
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider to use for the approval
+ * @returns {UseMutationResult<TxReturnType<SpokeProvider, false>, Error, Omit<InstantUnstakeParams, 'action'>>} Mutation result object containing mutation function and state
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsync: approve, isPending } = useInstantUnstakeApprove(spokeProvider);
+ *
+ * const handleApprove = async () => {
+ *   const result = await approve({
+ *     amount: 1000000000000000000n, // 1 xSODA
+ *     minAmount: 950000000000000000n, // 0.95 SODA
+ *     account: '0x...'
+ *   });
+ *
+ *   console.log('Approval successful:', result);
+ * };
+ * ```
+ */
+export function useInstantUnstakeApprove(
+  spokeProvider: SpokeProvider | undefined,
+): UseMutationResult<TxReturnType<SpokeProvider, false>, Error, Omit<InstantUnstakeParams, 'action'>> {
+  const { sodax } = useSodaxContext();
+
+  return useMutation<TxReturnType<SpokeProvider, false>, Error, Omit<InstantUnstakeParams, 'action'>>({
+    mutationFn: async (params: Omit<InstantUnstakeParams, 'action'>) => {
+      console.log('useInstantUnstakeApprove called with params:', params);
+      if (!spokeProvider) {
+        throw new Error('Spoke provider not found');
+      }
+
+      const result = await sodax.staking.approve({
+        params: { ...params, action: 'instantUnstake' },
+        spokeProvider,
+      });
+
+      if (!result.ok) {
+        throw new Error(`Instant unstake approval failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+  });
+}

package/src/hooks/staking/useInstantUnstakeRatio.ts

@@ -0,0 +1,54 @@
+// packages/dapp-kit/src/hooks/staking/useInstantUnstakeRatio.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * Hook for fetching instant unstake ratio estimates.
+ * Uses React Query for efficient caching and state management.
+ *
+ * @param {bigint | undefined} amount - The amount of xSoda to estimate instant unstake for
+ * @param {number} refetchInterval - The interval in milliseconds to refetch data (default: 10000)
+ * @returns {UseQueryResult<bigint, Error>} Query result object containing instant unstake ratio and state
+ *
+ * @example
+ * ```typescript
+ * const { data: instantUnstakeRatio, isLoading, error } = useInstantUnstakeRatio(1000000000000000000n); // 1 xSoda
+ *
+ * if (isLoading) return <div>Loading instant unstake ratio...</div>;
+ * if (instantUnstakeRatio) {
+ *   console.log('Instant unstake ratio:', instantUnstakeRatio);
+ * }
+ * ```
+ */
+export function useInstantUnstakeRatio(
+  amount: bigint | undefined,
+  refetchInterval = 10000,
+): UseQueryResult<bigint, Error> {
+  const { sodax } = useSodaxContext();
+
+  console.log('useInstantUnstakeRatio hook called with:', { amount: amount?.toString(), sodax: !!sodax });
+
+  return useQuery({
+    queryKey: ['soda', 'instantUnstakeRatio', amount?.toString()],
+    queryFn: async () => {
+      console.log('useInstantUnstakeRatio queryFn called with amount:', amount?.toString());
+      if (!amount || amount <= 0n) {
+        throw new Error('Amount must be greater than 0');
+      }
+
+      if (!sodax?.staking) {
+        throw new Error('Staking service not available');
+      }
+
+      const result = await sodax.staking.getInstantUnstakeRatio(amount);
+
+      if (!result.ok) {
+        throw new Error(`Failed to fetch instant unstake ratio: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+    enabled: !!amount && amount > 0n && !!sodax?.staking,
+    refetchInterval,
+  });
+}

package/src/hooks/staking/useStake.ts

@@ -0,0 +1,47 @@
+// packages/dapp-kit/src/hooks/staking/useStake.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import type { StakeParams, SpokeTxHash, HubTxHash, SpokeProvider } from '@sodax/sdk';
+import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+
+/**
+ * Hook for executing stake transactions to stake SODA tokens and receive xSODA shares.
+ * Uses React Query's useMutation for better state management and caching.
+ *
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider to use for the stake
+ * @returns {UseMutationResult<[SpokeTxHash, HubTxHash], Error, StakeParams>} Mutation result object containing mutation function and state
+ *
+ * @example
+ * ```typescript
+ * const { mutateAsync: stake, isPending } = useStake(spokeProvider);
+ *
+ * const handleStake = async () => {
+ *   const result = await stake({
+ *     amount: 1000000000000000000n, // 1 SODA
+ *     account: '0x...'
+ *   });
+ *
+ *   console.log('Stake successful:', result);
+ * };
+ * ```
+ */
+export function useStake(
+  spokeProvider: SpokeProvider | undefined,
+): UseMutationResult<[SpokeTxHash, HubTxHash], Error, StakeParams> {
+  const { sodax } = useSodaxContext();
+
+  return useMutation<[SpokeTxHash, HubTxHash], Error, StakeParams>({
+    mutationFn: async (params: StakeParams) => {
+      if (!spokeProvider) {
+        throw new Error('Spoke provider not found');
+      }
+
+      const result = await sodax.staking.stake(params, spokeProvider);
+
+      if (!result.ok) {
+        throw new Error(`Stake failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+  });
+}

package/src/hooks/staking/useStakeAllowance.ts

@@ -0,0 +1,57 @@
+// packages/dapp-kit/src/hooks/staking/useStakeAllowance.ts
+import { useSodaxContext } from '../shared/useSodaxContext';
+import type { StakeParams, SpokeProvider } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+
+/**
+ * Hook for checking SODA token allowance for staking operations.
+ * Uses React Query for efficient caching and state management.
+ *
+ * @param {Omit<StakeParams, 'action'> | undefined} params - The staking parameters. If undefined, the query will be disabled.
+ * @param {SpokeProvider | undefined} spokeProvider - The spoke provider to use for the allowance check
+ * @returns {UseQueryResult<boolean, Error>} Query result object containing allowance data and state
+ *
+ * @example
+ * ```typescript
+ * const { data: hasAllowed, isLoading } = useStakeAllowance(
+ *   {
+ *     amount: 1000000000000000000n, // 1 SODA
+ *     account: '0x...'
+ *   },
+ *   spokeProvider
+ * );
+ *
+ * if (isLoading) return <div>Checking allowance...</div>;
+ * if (hasAllowed) {
+ *   console.log('Sufficient allowance for staking');
+ * }
+ * ```
+ */
+export function useStakeAllowance(
+  params: Omit<StakeParams, 'action'> | undefined,
+  spokeProvider: SpokeProvider | undefined,
+): UseQueryResult<boolean, Error> {
+  const { sodax } = useSodaxContext();
+
+  return useQuery({
+    queryKey: ['soda', 'stakeAllowance', params, spokeProvider?.chainConfig.chain.id],
+    queryFn: async () => {
+      if (!params || !spokeProvider) {
+        return false;
+      }
+
+      const result = await sodax.staking.isAllowanceValid({
+        params: { ...params, action: 'stake' },
+        spokeProvider,
+      });
+
+      if (!result.ok) {
+        throw new Error(`Allowance check failed: ${result.error.code}`);
+      }
+
+      return result.value;
+    },
+    enabled: !!params && !!spokeProvider,
+    refetchInterval: 5000, // Refetch every 5 seconds
+  });
+}