@sodax/dapp-kit 1.5.7-beta → 2.0.0-rc.1

package/src/hooks/staking/useUnstakeAllowance.ts

@@ -1,58 +1,51 @@
-// packages/dapp-kit/src/hooks/staking/useStakeAllowance.ts
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { UnstakeParams, SpokeProvider } from '@sodax/sdk';
+import type { UnstakeParams } from '@sodax/sdk';
+import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseUnstakeAllowanceParams<K extends SpokeChainKey = SpokeChainKey> = ReadHookParams<
+  boolean,
+  {
+    payload: Omit<UnstakeParams<K>, 'action'> | undefined;
+  }
+>;
 
 /**
- * Hook for checking xSODA token allowance for unstaking operations.
- * Uses React Query for efficient caching and state management.
- *
- * @param {Omit<UnstakeParams, 'action'> | undefined} params - The 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 } = useUnstakeAllowance(
- *   {
- *     amount: 1000000000000000000n, // 1 xSODA
- *     account: '0x...'
- *   },
- *   spokeProvider
- * );
- *
- * if (isLoading) return <div>Checking allowance...</div>;
- * if (hasAllowed) {
- *   console.log('Sufficient allowance for unstaking');
- * }
- * ```
+ * React hook to check whether the user has approved sufficient xSODA spending for the unstake
+ * action. Read-only — calls `staking.isAllowanceValid` with `raw: true` so no `walletProvider`
+ * is required.
  */
-export function useUnstakeAllowance(
-  params: Omit<UnstakeParams, 'action'> | undefined,
-  spokeProvider: SpokeProvider | undefined,
-): UseQueryResult<boolean, Error> {
+export function useUnstakeAllowance<K extends SpokeChainKey = SpokeChainKey>({
+  params,
+  queryOptions,
+}: UseUnstakeAllowanceParams<K> = {}): UseQueryResult<boolean, Error> {
   const { sodax } = useSodaxContext();
+  const payload = params?.payload;
 
-  return useQuery({
-    queryKey: ['soda', 'unstakeAllowance', params, spokeProvider?.chainConfig.chain.id],
+  return useQuery<boolean, Error>({
+    queryKey: [
+      'staking',
+      'allowance',
+      payload?.srcChainKey,
+      'unstake',
+      payload?.srcAddress,
+      payload?.amount?.toString(),
+    ],
     queryFn: async () => {
-      if (!params || !spokeProvider) {
-        return false;
+      if (!payload) {
+        throw new Error('Params are required');
       }
-
       const result = await sodax.staking.isAllowanceValid({
-        params: { ...params, action: 'unstake' },
-        spokeProvider,
+        params: { ...payload, action: 'unstake' },
+        raw: true,
       });
-
-      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}`);
-      }
-
+      if (!result.ok) throw result.error;
       return result.value;
     },
-    enabled: !!params && !!spokeProvider,
-    refetchInterval: 5000, // Refetch every 5 seconds
+    enabled: !!payload,
+    refetchInterval: 5_000,
+    gcTime: 0,
+    ...queryOptions,
   });
 }

package/src/hooks/staking/useUnstakeApprove.ts

@@ -1,52 +1,49 @@
-// packages/dapp-kit/src/hooks/staking/useStakeApprove.ts
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { TxReturnType, UnstakeParams } from '@sodax/sdk';
-import { useMutation, type UseMutationResult } from '@tanstack/react-query';
-import type { SpokeProvider } from '@sodax/sdk';
+// packages/dapp-kit/src/hooks/staking/useUnstakeApprove.ts
+import type { GetWalletProviderType, SpokeChainKey, TxReturnType, UnstakeParams } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 
 /**
- * Hook for approving xSODA token spending for 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<UnstakeParams, 'action'>>} Mutation result object containing mutation function and state
- *
- * @example
- * ```typescript
- * const { mutateAsync: approve, isPending } = useUnstakeApprove(spokeProvider);
- *
- * const handleApprove = async () => {
- *   const result = await approve({
- *     amount: 1000000000000000000n, // 1 xSODA
- *     account: '0x...'
- *   });
+ * Mutation variables for {@link useUnstakeApprove}. The `action` literal is injected by the hook.
+ */
+export type UseUnstakeApproveVars<K extends SpokeChainKey = SpokeChainKey> = {
+  params: Omit<UnstakeParams<K>, 'action'>;
+  walletProvider: GetWalletProviderType<K>;
+};
+
+/**
+ * React hook for approving xSODA spending on the unstake action.
  *
- *   console.log('Approval successful:', result);
- * };
- * ```
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped tx return value on success.
  */
-export function useUnstakeApprove(
-  spokeProvider: SpokeProvider | undefined,
-): UseMutationResult<TxReturnType<SpokeProvider, false>, Error, Omit<UnstakeParams, 'action'>> {
+export function useUnstakeApprove<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxReturnType<K, false>, UseUnstakeApproveVars<K>> = {}): SafeUseMutationResult<
+  TxReturnType<K, false>,
+  Error,
+  UseUnstakeApproveVars<K>
+> {
   const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
 
-  return useMutation<TxReturnType<SpokeProvider, false>, Error, Omit<UnstakeParams, 'action'>>({
-    mutationFn: async (params: Omit<UnstakeParams, 'action'>) => {
-      console.log('useUnstakeApprove called with params:', params);
-      if (!spokeProvider) {
-        throw new Error('Spoke provider not found');
-      }
-
-      const result = await sodax.staking.approve({
-        params: { ...params, action: 'unstake' },
-        spokeProvider,
-      });
-
-      if (!result.ok) {
-        throw new Error(`Unstake approval failed: ${result.error.code}`);
-      }
-
-      return result.value;
+  return useSafeMutation<TxReturnType<K, false>, Error, UseUnstakeApproveVars<K>>({
+    mutationKey: ['staking', 'approve', 'unstake'],
+    ...mutationOptions,
+    mutationFn: async ({ params, walletProvider }) =>
+      unwrapResult(
+        await sodax.staking.approve({
+          params: { ...params, action: 'unstake' },
+          raw: false,
+          walletProvider,
+        }),
+      ),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['staking', 'allowance', vars.params.srcChainKey, 'unstake'] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/staking/useUnstakingInfo.ts

@@ -1,53 +1,41 @@
-// packages/dapp-kit/src/hooks/staking/useUnstakingInfoWithPenalty.ts
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { UnstakingInfo, SpokeProvider } from '@sodax/sdk';
+import type { UnstakingInfo } from '@sodax/sdk';
+import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseUnstakingInfoParams = ReadHookParams<
+  UnstakingInfo,
+  {
+    srcAddress: `0x${string}` | undefined;
+    srcChainKey: SpokeChainKey | undefined;
+  }
+>;
 
 /**
- * Hook for fetching unstaking information from the stakedSoda contract.
- * Uses React Query for efficient caching and state management.
- *
- * @param {string | undefined} userAddress - The user address to fetch unstaking info for
- * @param {SpokeProvider | undefined} spokeProvider - The spoke provider instance
- * @param {number} refetchInterval - The interval in milliseconds to refetch data (default: 5000)
- * @returns {UseQueryResult<UnstakingInfo, Error>} Query result object containing unstaking info and state
- *
- * @example
- * ```typescript
- * const { data: unstakingInfo, isLoading, error } = useUnstakingInfo(userAddress, spokeProvider);
- *
- * if (isLoading) return <div>Loading unstaking info...</div>;
- * if (unstakingInfo) {
- *   console.log('Total unstaking:', unstakingInfo.totalUnstaking);
- *   unstakingInfo.userUnstakeSodaRequests.forEach(request => {
- *     console.log('Request amount:', request.request.amount);
- *   });
- * }
- * ```
+ * React hook to fetch the user's pending unstake requests by deriving the hub wallet from the
+ * spoke `srcAddress` + `srcChainKey`. Throws on `!ok`.
  */
-export function useUnstakingInfo(
-  userAddress: string | undefined,
-  spokeProvider: SpokeProvider | undefined,
-  refetchInterval = 5000,
-): UseQueryResult<UnstakingInfo, Error> {
+export function useUnstakingInfo({
+  params,
+  queryOptions,
+}: UseUnstakingInfoParams = {}): UseQueryResult<UnstakingInfo, Error> {
   const { sodax } = useSodaxContext();
+  const srcAddress = params?.srcAddress;
+  const srcChainKey = params?.srcChainKey;
 
-  return useQuery({
-    queryKey: ['soda', 'unstakingInfoWithPenalty', spokeProvider?.chainConfig.chain.id, userAddress],
+  return useQuery<UnstakingInfo, Error>({
+    queryKey: ['staking', 'unstakingInfo', srcChainKey, srcAddress],
     queryFn: async () => {
-      if (!spokeProvider || !userAddress) {
-        throw new Error('Spoke provider or user address not found');
+      if (!srcAddress || !srcChainKey) {
+        throw new Error('srcAddress and srcChainKey are required');
       }
-
-      const result = await sodax.staking.getUnstakingInfo(spokeProvider);
-
-      if (!result.ok) {
-        throw new Error(`Failed to fetch unstaking info: ${result.error.code}`);
-      }
-
+      const result = await sodax.staking.getUnstakingInfo(srcAddress, srcChainKey);
+      if (!result.ok) throw result.error;
       return result.value;
     },
-    enabled: !!spokeProvider && !!userAddress,
-    refetchInterval,
+    enabled: !!srcAddress && !!srcChainKey,
+    refetchInterval: 5_000,
+    ...queryOptions,
   });
 }

package/src/hooks/staking/useUnstakingInfoWithPenalty.ts

@@ -1,59 +1,43 @@
-// packages/dapp-kit/src/hooks/staking/useUnstakingInfoWithPenalty.ts
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { UnstakingInfo, UnstakeRequestWithPenalty, SpokeProvider } from '@sodax/sdk';
+import type { UnstakeRequestWithPenalty, UnstakingInfo } from '@sodax/sdk';
+import type { SpokeChainKey } from '@sodax/sdk';
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
 
-export type UnstakingInfoWithPenalty = UnstakingInfo & {
-  requestsWithPenalty: UnstakeRequestWithPenalty[];
-};
+export type UnstakingInfoWithPenalty = UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] };
+
+export type UseUnstakingInfoWithPenaltyParams = ReadHookParams<
+  UnstakingInfoWithPenalty,
+  {
+    srcAddress: `0x${string}` | undefined;
+    srcChainKey: SpokeChainKey | undefined;
+  }
+>;
 
 /**
- * Hook for fetching unstaking information with penalty calculations from the stakedSoda contract.
- * Uses React Query for efficient caching and state management.
- *
- * @param {string | undefined} userAddress - The user address to fetch unstaking info for
- * @param {SpokeProvider | undefined} spokeProvider - The spoke provider instance
- * @param {number} refetchInterval - The interval in milliseconds to refetch data (default: 5000)
- * @returns {UseQueryResult<UnstakingInfoWithPenalty, Error>} Query result object containing unstaking info with penalties and state
- *
- * @example
- * ```typescript
- * const { data: unstakingInfo, isLoading, error } = useUnstakingInfoWithPenalty(userAddress, spokeProvider);
- *
- * if (isLoading) return <div>Loading unstaking info...</div>;
- * if (unstakingInfo) {
- *   console.log('Total unstaking:', unstakingInfo.totalUnstaking);
- *   unstakingInfo.requestsWithPenalty.forEach(request => {
- *     console.log('Penalty:', request.penaltyPercentage + '%');
- *     console.log('Claimable amount:', request.claimableAmount);
- *   });
- * }
- * ```
+ * React hook to fetch the user's pending unstake requests **with computed early-exit penalties**
+ * by deriving the hub wallet from the spoke `srcAddress` + `srcChainKey`. Throws on `!ok`.
  */
-export function useUnstakingInfoWithPenalty(
-  userAddress: string | undefined,
-  spokeProvider: SpokeProvider | undefined,
-  refetchInterval = 5000,
-): UseQueryResult<UnstakingInfoWithPenalty, Error> {
+export function useUnstakingInfoWithPenalty({
+  params,
+  queryOptions,
+}: UseUnstakingInfoWithPenaltyParams = {}): UseQueryResult<UnstakingInfoWithPenalty, Error> {
   const { sodax } = useSodaxContext();
+  const srcAddress = params?.srcAddress;
+  const srcChainKey = params?.srcChainKey;
 
-  return useQuery({
-    queryKey: ['soda', 'unstakingInfoWithPenalty', spokeProvider?.chainConfig.chain.id, userAddress],
+  return useQuery<UnstakingInfoWithPenalty, Error>({
+    queryKey: ['staking', 'unstakingInfoWithPenalty', srcChainKey, srcAddress],
     queryFn: async () => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider not found');
+      if (!srcAddress || !srcChainKey) {
+        throw new Error('srcAddress and srcChainKey are required');
       }
-
-      // Get unstaking info with penalty calculations
-      const penaltyResult = await sodax.staking.getUnstakingInfoWithPenalty(spokeProvider);
-
-      if (!penaltyResult.ok) {
-        throw new Error(`Failed to fetch unstaking info with penalty: ${penaltyResult.error.code}`);
-      }
-
-      return penaltyResult.value;
+      const result = await sodax.staking.getUnstakingInfoWithPenalty(srcAddress, srcChainKey);
+      if (!result.ok) throw result.error;
+      return result.value;
     },
-    enabled: !!spokeProvider && !!userAddress,
-    refetchInterval,
+    enabled: !!srcAddress && !!srcChainKey,
+    refetchInterval: 5_000,
+    ...queryOptions,
   });
 }

package/src/hooks/swap/index.ts

@@ -1,8 +1,8 @@
-export * from './useQuote';
-export * from './useSwap';
-export * from './useStatus';
-export * from './useSwapAllowance';
-export * from './useSwapApprove';
-export * from './useCancelSwap';
-export * from './useCreateLimitOrder';
-export * from './useCancelLimitOrder';
+export * from './useQuote.js';
+export * from './useSwap.js';
+export * from './useStatus.js';
+export * from './useSwapAllowance.js';
+export * from './useSwapApprove.js';
+export * from './useCancelSwap.js';
+export * from './useCreateLimitOrder.js';
+export * from './useCancelLimitOrder.js';

package/src/hooks/swap/useCancelLimitOrder.ts

@@ -1,53 +1,36 @@
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { Intent, IntentError, IntentErrorCode, Result, SpokeProvider } from '@sodax/sdk';
-import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+// packages/dapp-kit/src/hooks/swap/useCancelLimitOrder.ts
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { GetWalletProviderType, Intent, SpokeChainKey, TxHashPair } from '@sodax/sdk';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 
-type CancelLimitOrderParams = {
+type CancelLimitOrderParams<K extends SpokeChainKey = SpokeChainKey> = {
+  srcChainKey: K;
+  walletProvider: GetWalletProviderType<K>;
   intent: Intent;
-  spokeProvider: SpokeProvider;
   timeout?: number;
 };
 
-type CancelLimitOrderResult = Result<[string, string], IntentError<IntentErrorCode>>;
-
 /**
- * Hook for canceling a limit order intent and submitting it to the Relayer API.
- * Uses React Query's useMutation for better state management and caching.
- *
- * This hook wraps cancelLimitOrder which cancels the intent on the spoke chain,
- * submits it to the relayer API, and waits for execution on the destination/hub chain.
- *
- * @returns {UseMutationResult} Mutation result object containing mutation function and state
- *
- * @example
- * ```typescript
- * const { mutateAsync: cancelLimitOrder, isPending } = useCancelLimitOrder();
- *
- * const handleCancelLimitOrder = async () => {
- *   const result = await cancelLimitOrder({
- *     intent: intentObject,
- *     spokeProvider,
- *     timeout: 60000 // optional, defaults to 60 seconds
- *   });
+ * React hook for cancelling a limit-order intent.
  *
- *   if (result.ok) {
- *     const [cancelTxHash, dstTxHash] = result.value;
- *     console.log('Cancel transaction hash:', cancelTxHash);
- *     console.log('Destination transaction hash:', dstTxHash);
- *   }
- * };
- * ```
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  */
-export function useCancelLimitOrder(): UseMutationResult<CancelLimitOrderResult, Error, CancelLimitOrderParams> {
+export function useCancelLimitOrder({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, CancelLimitOrderParams> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  CancelLimitOrderParams
+> {
   const { sodax } = useSodaxContext();
 
-  return useMutation<CancelLimitOrderResult, Error, CancelLimitOrderParams>({
-    mutationFn: async ({ intent, spokeProvider, timeout }: CancelLimitOrderParams): Promise<CancelLimitOrderResult> => {
-      return sodax.swaps.cancelLimitOrder({
-        intent,
-        spokeProvider,
-        timeout,
-      });
-    },
+  return useSafeMutation<TxHashPair, Error, CancelLimitOrderParams>({
+    mutationKey: ['swap', 'limitOrder', 'cancel'],
+    ...mutationOptions,
+    mutationFn: async ({ srcChainKey, walletProvider, intent, timeout }) =>
+      unwrapResult(await sodax.swaps.cancelLimitOrder({ params: { srcChainKey, intent }, walletProvider, timeout })),
   });
 }

package/src/hooks/swap/useCancelSwap.ts

@@ -1,44 +1,35 @@
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { Intent, Result, SpokeProvider, TxReturnType } from '@sodax/sdk';
-import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+// packages/dapp-kit/src/hooks/swap/useCancelSwap.ts
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { GetWalletProviderType, Intent, SpokeChainKey, TxHashPair } from '@sodax/sdk';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 
-type CancelIntentParams = {
+type CancelIntentParams<K extends SpokeChainKey = SpokeChainKey> = {
+  srcChainKey: K;
+  walletProvider: GetWalletProviderType<K>;
   intent: Intent;
-  raw?: boolean;
 };
 
-type CancelIntentResult = Result<TxReturnType<SpokeProvider, boolean>>;
-
 /**
- * Hook for canceling a swap intent order.
- * Uses React Query's useMutation for better state management and caching.
- *
- * @param {SpokeProvider} spokeProvider - The spoke provider to use for canceling the intent
- * @returns {UseMutationResult} Mutation result object containing mutation function and state
- *
- * @example
- * ```typescript
- * const { mutateAsync: cancelSwap, isPending } = useCancelSwap(spokeProvider);
+ * React hook for cancelling an in-flight swap intent.
  *
- * const handleCancelSwap = async () => {
- *   const result = await cancelSwap({
- *     intent: intentObject,
- *     raw: false // optional, defaults to false
- *   });
- * };
- * ```
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  */
-export function useCancelSwap(
-  spokeProvider: SpokeProvider | undefined,
-): UseMutationResult<CancelIntentResult, Error, CancelIntentParams> {
+export function useCancelSwap({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, CancelIntentParams> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  CancelIntentParams
+> {
   const { sodax } = useSodaxContext();
 
-  return useMutation<CancelIntentResult, Error, CancelIntentParams>({
-    mutationFn: async ({ intent, raw = false }: CancelIntentParams) => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider not found');
-      }
-      return sodax.swaps.cancelIntent(intent, spokeProvider, raw);
-    },
+  return useSafeMutation<TxHashPair, Error, CancelIntentParams>({
+    mutationKey: ['swap', 'cancel'],
+    ...mutationOptions,
+    mutationFn: async ({ srcChainKey, walletProvider, intent }) =>
+      unwrapResult(await sodax.swaps.cancelIntent({ params: { srcChainKey, intent }, walletProvider })),
   });
 }

package/src/hooks/swap/useCreateLimitOrder.ts

@@ -1,72 +1,39 @@
-import { useSodaxContext } from '../shared/useSodaxContext';
-import { useMutation, type UseMutationResult } from '@tanstack/react-query';
-import type {
-  CreateLimitOrderParams,
-  SolverExecutionResponse,
-  Intent,
-  IntentError,
-  IntentErrorCode,
-  IntentDeliveryInfo,
-  Result,
-  SpokeProvider,
-} from '@sodax/sdk';
+// packages/dapp-kit/src/hooks/swap/useCreateLimitOrder.ts
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { LimitOrderActionParams, SpokeChainKey, SwapResponse } from '@sodax/sdk';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 
-type CreateLimitOrderResult = Result<
-  [SolverExecutionResponse, Intent, IntentDeliveryInfo],
-  IntentError<IntentErrorCode>
+/**
+ * Mutation variables for {@link useCreateLimitOrder}. Generic over `K extends SpokeChainKey`
+ * (defaults to the full union). Sophisticated callers can lock K at the call site to narrow the
+ * `walletProvider` and `params.srcChainKey` types.
+ */
+export type UseCreateLimitOrderVars<K extends SpokeChainKey = SpokeChainKey> = Omit<
+  LimitOrderActionParams<K, false>,
+  'raw'
 >;
 
 /**
- * Hook for creating a limit order intent (no deadline, must be cancelled manually by user).
- * Uses React Query's useMutation for better state management and caching.
- *
- * Limit orders remain active until manually cancelled by the user. Unlike swaps, limit orders
- * do not have a deadline (deadline is automatically set to 0n).
- *
- * @param {SpokeProvider} spokeProvider - The spoke provider to use for creating the limit order
- * @returns {UseMutationResult} Mutation result object containing mutation function and state
- *
- * @example
- * ```typescript
- * const { mutateAsync: createLimitOrder, isPending } = useCreateLimitOrder(spokeProvider);
- *
- * const handleCreateLimitOrder = async () => {
- *   const result = await createLimitOrder({
- *     inputToken: '0x...',
- *     outputToken: '0x...',
- *     inputAmount: 1000000000000000000n,
- *     minOutputAmount: 900000000000000000n,
- *     allowPartialFill: false,
- *     srcChain: '0xa4b1.arbitrum',
- *     dstChain: '0x89.polygon',
- *     srcAddress: '0x...',
- *     dstAddress: '0x...',
- *     solver: '0x0000000000000000000000000000000000000000',
- *     data: '0x'
- *   });
+ * React hook for creating a limit-order intent (no deadline).
  *
- *   if (result.ok) {
- *     const [solverExecutionResponse, intent, intentDeliveryInfo] = result.value;
- *     console.log('Limit order created:', intent);
- *     console.log('Intent hash:', solverExecutionResponse.intent_hash);
- *   }
- * };
- * ```
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `SwapResponse` on success.
  */
-export function useCreateLimitOrder(
-  spokeProvider: SpokeProvider | undefined,
-): UseMutationResult<CreateLimitOrderResult, Error, CreateLimitOrderParams> {
+export function useCreateLimitOrder<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<SwapResponse, UseCreateLimitOrderVars<K>> = {}): SafeUseMutationResult<
+  SwapResponse,
+  Error,
+  UseCreateLimitOrderVars<K>
+> {
   const { sodax } = useSodaxContext();
 
-  return useMutation<CreateLimitOrderResult, Error, CreateLimitOrderParams>({
-    mutationFn: async (params: CreateLimitOrderParams) => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider not found');
-      }
-      return sodax.swaps.createLimitOrder({
-        intentParams: params,
-        spokeProvider,
-      });
-    },
+  return useSafeMutation<SwapResponse, Error, UseCreateLimitOrderVars<K>>({
+    mutationKey: ['swap', 'limitOrder', 'create'],
+    ...mutationOptions,
+    mutationFn: async vars =>
+      unwrapResult(await sodax.swaps.createLimitOrder({ ...vars, raw: false })),
   });
 }