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

package/src/hooks/dex/useDecreaseLiquidity.ts

@@ -1,78 +1,52 @@
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import type {
-  ConcentratedLiquidityDecreaseLiquidityParams,
-  HubTxHash,
-  SpokeProvider,
-  SpokeTxHash,
-} from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
+// packages/dapp-kit/src/hooks/dex/useDecreaseLiquidity.ts
+import type { ClLiquidityDecreaseLiquidityAction, SpokeChainKey, TxHashPair } 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';
 
-export type UseDecreaseLiquidityParams = {
-  params: ConcentratedLiquidityDecreaseLiquidityParams;
-  spokeProvider: SpokeProvider;
-};
+/**
+ * Mutation variables for {@link useDecreaseLiquidity}. Generic over `K extends SpokeChainKey`
+ * (defaults to the full union). Sophisticated callers can lock K at the hook call site to narrow
+ * the `walletProvider` and `params.srcChainKey` types.
+ */
+export type UseDecreaseLiquidityVars<K extends SpokeChainKey = SpokeChainKey> = Omit<
+  ClLiquidityDecreaseLiquidityAction<K, false>,
+  'raw'
+>;
 
 /**
- * React hook that provides a mutation for decreasing liquidity in a concentrated liquidity position.
- *
- * This hook returns a mutation for removing liquidity from a position using the provided
- * `ConcentratedLiquidityDecreaseLiquidityParams` and `SpokeProvider`. The mutation returns a tuple of
- * the spoke transaction hash and the hub transaction hash upon success.
- *
- * @returns {UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseDecreaseLiquidityParams>}
- *   React Query mutation result:
- *   - `mutateAsync({ params, spokeProvider })`: Triggers the decrease liquidity mutation.
- *   - On success, returns `[spokeTxHash, hubTxHash]`.
- *   - On failure, throws an error.
- *
- * @example
- * ```typescript
- * const { mutateAsync: decreaseLiquidity, isPending, error } = useDecreaseLiquidity();
- *
- * await decreaseLiquidity({
- *   params: {
- *     poolKey,
- *     tokenId: 123n,
- *     liquidity: 100000n,
- *     amount0Min: 0n,
- *     amount1Min: 0n,
- *   },
- *   spokeProvider,
- * });
- * ```
+ * React hook for decreasing liquidity in an existing concentrated-liquidity position.
  *
- * @param {UseDecreaseLiquidityParams} variables
- *   - `params`: Parameters for the decrease liquidity operation, matching `ConcentratedLiquidityDecreaseLiquidityParams`.
- *   - `spokeProvider`: The provider instance for the target spoke chain.
- *
- * @remarks
- * - After a successful liquidity decrease, the hook will invalidate DEX pool balances and position info queries.
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  */
-export function useDecreaseLiquidity(): UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseDecreaseLiquidityParams> {
+export function useDecreaseLiquidity<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseDecreaseLiquidityVars<K>> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseDecreaseLiquidityVars<K>
+> {
   const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation({
-    mutationFn: async ({ params, spokeProvider }: UseDecreaseLiquidityParams) => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider is required');
-      }
-
-      const decreaseResult = await sodax.dex.clService.decreaseLiquidity({
-        params,
-        spokeProvider,
+  return useSafeMutation<TxHashPair, Error, UseDecreaseLiquidityVars<K>>({
+    mutationKey: ['dex', 'decreaseLiquidity'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.dex.clService.decreaseLiquidity({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      const { params } = vars;
+      // Decrease always targets a known position — scope invalidation to (tokenId, poolKey) instead
+      // of wiping all positions. `usePositionInfo` keys by string tokenId, so stringify the bigint
+      // here to keep the structural match.
+      queryClient.invalidateQueries({
+        queryKey: ['dex', 'positionInfo', params.tokenId.toString(), params.poolKey],
       });
-
-      if (!decreaseResult.ok) {
-        throw new Error(`Decrease liquidity failed: ${decreaseResult.error?.code || 'Unknown error'}`);
-      }
-
-      return decreaseResult.value;
-    },
-    onSuccess: () => {
-      // Invalidate relevant queries after successful liquidity decrease
-      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances'] });
-      queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo'] });
+      queryClient.invalidateQueries({ queryKey: ['dex', 'poolData', params.poolKey] });
+      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances', params.srcChainKey, params.srcAddress] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/dex/useDexAllowance.ts

@@ -1,87 +1,41 @@
-import { type QueryObserverOptions, useQuery, type UseQueryResult } from '@tanstack/react-query';
-import type { SpokeProvider, CreateAssetDepositParams } from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
+import type { CreateAssetDepositParams } 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 UseDexAllowanceProps = {
-  params: CreateAssetDepositParams | undefined;
-  spokeProvider: SpokeProvider | null;
-  enabled?: boolean;
-  queryOptions?: QueryObserverOptions<boolean, Error>;
-};
+export type UseDexAllowanceParams<K extends SpokeChainKey = SpokeChainKey> = ReadHookParams<
+  boolean,
+  {
+    payload: CreateAssetDepositParams<K> | undefined;
+  }
+>;
 
 /**
- * Hook to check if the user has approved sufficient token allowance for DEX deposits.
- *
- * This hook automatically queries and tracks the allowance status, indicating whether
- * the user has granted enough allowance to allow a specific deposit to the DEX. It leverages
- * React Query for status, caching, and background refetching.
- *
- * @param {CreateAssetDepositParams | undefined} params
- *   The deposit parameters: asset address, poolToken, and raw amount (BigInt), or undefined to disable.
- * @param {SpokeProvider | undefined} spokeProvider
- *   The provider interface for the selected chain. When undefined, the query is disabled.
- * @param {boolean} [enabled]
- *   Whether the allowance status check is enabled. Defaults to true if both params and spokeProvider are truthy.
- * @param {QueryObserverOptions<boolean, Error>} [queryOptions]
- *   Optional react-query options. Any override here (e.g. staleTime, refetchInterval) will merge with defaults.
- *
- * @returns {UseQueryResult<boolean, Error>}
- *   React Query result object: `data` is boolean (true if allowance is sufficient), plus `isLoading`, `error`, etc.
- *
- * @example
- * ```typescript
- * const { data: isAllowed, isLoading, error } = useDexAllowance({
- *   params: { asset, amount: parseUnits('100', 18), poolToken },
- *   spokeProvider,
- * });
- * if (isLoading) return <Spinner />;
- * if (error) return <div>Error: {error.message}</div>;
- * if (isAllowed) { ... }
- * ```
- *
- * @remarks
- * - The allowance is checked every 5 seconds as long as enabled, params, and spokeProvider are all defined.
- * - Returns `false` if allowance cannot be determined or any error occurs in isAllowanceValid.
- * - Suitable for gating UI actions that require token approval before depositing in the DEX.
+ * React hook to check whether the user has approved sufficient token allowance (or established a
+ * trustline, on Stellar) for a DEX deposit. Read-only — calls `assetService.isAllowanceValid`
+ * with `raw: true` so no `walletProvider` is required.
  */
-export function useDexAllowance({
+export function useDexAllowance<K extends SpokeChainKey = SpokeChainKey>({
   params,
-  spokeProvider,
-  queryOptions = {
-    queryKey: [
-      'dex',
-      'allowance',
-      params?.asset,
-      params?.poolToken,
-      params?.amount.toString(),
-      spokeProvider?.chainConfig.chain.id,
-    ],
-    enabled: !!params && !!spokeProvider,
-  },
-}: UseDexAllowanceProps): UseQueryResult<boolean, Error> {
+  queryOptions,
+}: UseDexAllowanceParams<K> = {}): UseQueryResult<boolean, Error> {
   const { sodax } = useSodaxContext();
+  const payload = params?.payload;
 
-  return useQuery({
-    ...queryOptions,
+  return useQuery<boolean, Error>({
+    queryKey: ['dex', 'allowance', payload?.srcChainKey, payload?.asset, payload?.amount?.toString()],
     queryFn: async () => {
-      if (!params || !spokeProvider) {
-        throw new Error('Params and spoke provider are required');
-      }
-
-      const allowanceResult = await sodax.dex.assetService.isAllowanceValid({
-        params: {
-          asset: params.asset,
-          amount: params.amount,
-          poolToken: params.poolToken,
-        },
-        spokeProvider,
-      });
-
-      if (!allowanceResult.ok) {
-        return false;
+      if (!payload) {
+        throw new Error('Params are required');
       }
-
-      return allowanceResult.value;
+      const result = await sodax.dex.assetService.isAllowanceValid({ params: payload, raw: true });
+      if (!result.ok) throw result.error;
+      return result.value;
     },
+    enabled: !!payload,
+    refetchInterval: 5_000,
+    gcTime: 0,
+    ...queryOptions,
   });
 }

package/src/hooks/dex/useDexApprove.ts

@@ -1,55 +1,44 @@
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import type { SpokeProvider, CreateAssetDepositParams, SpokeTxHash } from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
+// packages/dapp-kit/src/hooks/dex/useDexApprove.ts
+import type { AssetDepositAction, SpokeChainKey, TxReturnType } 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';
 
-export type UseDexApproveParams = {
-  params: CreateAssetDepositParams;
-  spokeProvider: SpokeProvider;
-};
+/**
+ * Mutation variables for {@link useDexApprove}. Generic over `K extends SpokeChainKey` (defaults
+ * to the full union). Sophisticated callers can lock K at the hook call site to narrow the
+ * `walletProvider` and `params.srcChainKey` types.
+ */
+export type UseDexApproveVars<K extends SpokeChainKey = SpokeChainKey> = Omit<AssetDepositAction<K, false>, 'raw'>;
 
 /**
- * React hook for performing a DEX token allowance approval transaction.
- *
- * Returns a mutation object that allows explicitly triggering a token approval
- * for a DEX deposit, using the specified approval parameters and spoke provider.
- * On successful approval, the related allowance query is invalidated and refetched
- * for consistent UI state.
- *
- * @returns {UseMutationResult<SpokeTxHash, Error, UseDexApproveParams>}
- *   React Query mutation result for the approval operation. Use `mutateAsync` with
- *   an object of shape `{ params, spokeProvider }` to initiate approval.
+ * React hook for approving ERC-20 token spending (or trustline establishment) for a DEX deposit.
  *
- * @example
- * ```typescript
- * const { mutateAsync: approve, isPending, error } = useDexApprove();
- * await approve({ params: { asset, amount, poolToken }, spokeProvider });
- * ```
- *
- * @remarks
- * - Throws if called without both a valid `params` and `spokeProvider`.
- * - On approval success, the query for ['dex', 'allowance'] is invalidated/refetched.
+ * 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 useDexApprove(): UseMutationResult<SpokeTxHash, Error, UseDexApproveParams> {
+export function useDexApprove<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxReturnType<K, false>, UseDexApproveVars<K>> = {}): SafeUseMutationResult<
+  TxReturnType<K, false>,
+  Error,
+  UseDexApproveVars<K>
+> {
   const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation({
-    mutationFn: async ({ params, spokeProvider }: UseDexApproveParams) => {
-      const approveResult = await sodax.dex.assetService.approve({
-        params,
-        spokeProvider,
-        raw: false,
+  return useSafeMutation<TxReturnType<K, false>, Error, UseDexApproveVars<K>>({
+    mutationKey: ['dex', 'approve'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.dex.assetService.approve({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      const { params } = vars;
+      queryClient.invalidateQueries({
+        queryKey: ['dex', 'allowance', params.srcChainKey, params.asset, params.amount.toString()],
       });
-
-      if (!approveResult.ok) {
-        throw new Error('Approval failed');
-      }
-
-      return approveResult.value;
-    },
-    onSuccess: () => {
-      // Invalidate allowance query to refetch the new allowance
-      queryClient.invalidateQueries({ queryKey: ['dex', 'allowance'] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/dex/useDexDeposit.ts

@@ -1,64 +1,57 @@
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import type { SpokeProvider, CreateAssetDepositParams, SpokeTxHash, HubTxHash } from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
-
-export type UseDexDepositParams = {
-  params: CreateAssetDepositParams;
-  spokeProvider: SpokeProvider;
-};
+// packages/dapp-kit/src/hooks/dex/useDexDeposit.ts
+import type { AssetDepositAction, SpokeChainKey, TxHashPair } 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';
 
 /**
+ * Mutation variables for {@link useDexDeposit}. Generic over `K extends SpokeChainKey` (defaults
+ * to the full union). Sophisticated callers can lock K at the hook call site to narrow the
+ * `walletProvider` and `params.srcChainKey` types.
+ */
+export type UseDexDepositVars<K extends SpokeChainKey = SpokeChainKey> = Omit<AssetDepositAction<K, false>, 'raw'>;
+
 /**
- * React hook that provides a mutation to perform a deposit into a DEX pool using the provided parameters and SpokeProvider.
+ * React hook for depositing an asset into a DEX pool.
  *
- * The hook returns a mutation object for executing the deposit (`mutateAsync`), tracking its state (`isPending`), and any resulting error (`error`).
- * On successful deposit, all queries matching ['dex', 'poolBalances'] are invalidated and refetched.
- *
- * @returns {UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseDexDepositParams>}
- *   React Query mutation result:
- *   - `mutateAsync({ params, spokeProvider })`: Triggers the deposit with {@link CreateDepositParams} and the target SpokeProvider.
- *   - `isPending`: True while the deposit transaction is pending.
- *   - `error`: Error if the mutation fails.
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  *
  * @example
- * ```typescript
- * const { mutateAsync: deposit, isPending, error } = useDexDeposit();
- * await deposit({ params: { asset, amount, poolToken }, spokeProvider });
+ * ```tsx
+ * const walletProvider = useWalletProvider({ xChainId: chainKey });
+ * const { mutateAsync: deposit } = useDexDeposit();
+ * try {
+ *   const { spokeTxHash, hubTxHash } = await deposit({ params, walletProvider });
+ * } catch (e) {
+ *   // surfaced via mutation.error / onError
+ * }
  * ```
- *
- * @remarks
- * - Throws if called with missing `spokeProvider` or `params`.
- * - Upon success, automatically refetches up-to-date pool balances.
  */
-export function useDexDeposit(): UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseDexDepositParams> {
+export function useDexDeposit<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseDexDepositVars<K>> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseDexDepositVars<K>
+> {
   const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation({
-    mutationFn: async ({ params, spokeProvider }: UseDexDepositParams) => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider is required');
-      }
-
-      if (!params) {
-        throw new Error('Deposit params are required');
-      }
-
-      // Perform the deposit operation
-      const depositResult = await sodax.dex.assetService.deposit({
-        params,
-        spokeProvider,
+  return useSafeMutation<TxHashPair, Error, UseDexDepositVars<K>>({
+    mutationKey: ['dex', 'deposit'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.dex.assetService.deposit({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      const { params } = vars;
+      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances', params.srcChainKey, params.srcAddress] });
+      queryClient.invalidateQueries({
+        queryKey: ['dex', 'allowance', params.srcChainKey, params.asset, params.amount.toString()],
       });
-
-      if (!depositResult.ok) {
-        throw new Error(`Deposit failed: ${depositResult.error?.code || 'Unknown error'}`);
-      }
-
-      return depositResult.value;
-    },
-    onSuccess: () => {
-      // Refetch pool balances after a successful deposit
-      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', params.srcChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/dex/useDexWithdraw.ts

@@ -1,54 +1,43 @@
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import type { SpokeProvider, SpokeTxHash, HubTxHash, CreateAssetWithdrawParams } from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
+// packages/dapp-kit/src/hooks/dex/useDexWithdraw.ts
+import type { AssetWithdrawAction, SpokeChainKey, TxHashPair } 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';
 
-export type UseDexWithdrawParams = {
-  params: CreateAssetWithdrawParams;
-  spokeProvider: SpokeProvider;
-};
+/**
+ * Mutation variables for {@link useDexWithdraw}. Generic over `K extends SpokeChainKey` (defaults
+ * to the full union). Sophisticated callers can lock K at the hook call site to narrow the
+ * `walletProvider` and `params.srcChainKey` types.
+ */
+export type UseDexWithdrawVars<K extends SpokeChainKey = SpokeChainKey> = Omit<AssetWithdrawAction<K, false>, 'raw'>;
 
 /**
- * React hook to provide a mutation for withdrawing assets from a DEX pool.
- *
- * This hook returns a mutation result object valid for use with React Query.
- * The mutation function expects an object with the withdrawal parameters and a SpokeProvider,
- * and triggers the withdrawal operation on the DEX. On success, it invalidates the relevant
- * ['dex', 'poolBalances'] query to fetch the updated balances.
- *
- * @returns {UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseDexWithdrawParams>}
- *   Mutation result object. Use its properties to:
- *   - Call `mutateAsync({ params, spokeProvider })` to perform the withdrawal.
- *   - Track progress with `isPending`.
- *   - Access any `error` encountered during the mutation.
+ * React hook for withdrawing an asset from a DEX pool.
  *
- * @example
- * const { mutateAsync: withdraw, isPending, error } = useDexWithdraw();
- * await withdraw({ params, spokeProvider });
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  */
-export function useDexWithdraw(): UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseDexWithdrawParams> {
+export function useDexWithdraw<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseDexWithdrawVars<K>> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseDexWithdrawVars<K>
+> {
   const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation({
-    mutationFn: async ({ params, spokeProvider }: UseDexWithdrawParams) => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider is required');
-      }
-      // Execute withdraw
-      const withdrawResult = await sodax.dex.assetService.withdraw({
-        params,
-        spokeProvider,
-      });
-
-      if (!withdrawResult.ok) {
-        throw new Error(`Withdraw failed: ${withdrawResult.error.code}`);
-      }
-
-      return withdrawResult.value;
-    },
-    onSuccess: () => {
-      // Invalidate balances query to refetch after withdraw
-      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances'] });
+  return useSafeMutation<TxHashPair, Error, UseDexWithdrawVars<K>>({
+    mutationKey: ['dex', 'withdraw'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.dex.assetService.withdraw({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      const { params } = vars;
+      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances', params.srcChainKey, params.srcAddress] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', params.srcChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }