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

package/src/hooks/backend/useBackendSubmitSwapTxStatus.ts

@@ -1,79 +1,59 @@
-import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
-import type { SubmitSwapTxStatusResponse } from '@sodax/types';
-import type { RequestOverrideConfig } from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { RequestOverrideConfig, SubmitSwapTxStatusResponse } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from './unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
 
-export type UseBackendSubmitSwapTxStatusParams = {
-  params: {
+export type UseBackendSubmitSwapTxStatusParams = ReadHookParams<
+  SubmitSwapTxStatusResponse | undefined,
+  {
     txHash: string | undefined;
-    srcChainId?: string;
-  };
-  apiConfig?: RequestOverrideConfig;
-  queryOptions?: UseQueryOptions<SubmitSwapTxStatusResponse | undefined, Error>;
-};
+    srcChainKey?: string;
+    apiConfig?: RequestOverrideConfig;
+  }
+>;
 
 /**
  * React hook for polling the processing status of a submitted swap transaction.
  *
- * @param {UseBackendSubmitSwapTxStatusParams | undefined} params - Parameters for the query:
- *   - `params.txHash`: The transaction hash of the submitted swap; query is disabled if undefined or empty.
- *   - `params.srcChainId`: Optional source chain ID to narrow the status lookup.
- *   - `queryOptions`: Optional React Query options to override default behavior (e.g., refetchInterval, retry).
- *
- * @returns {UseQueryResult<SubmitSwapTxStatusResponse | undefined, Error>} React Query result object:
- *   - `data`: The status response or undefined if unavailable.
- *   - `isLoading`: Loading state.
- *   - `error`: Error instance if the query failed.
- *   - `refetch`: Function to re-trigger the query.
- *
  * @example
- * const { data: status, isLoading, error } = useBackendSubmitSwapTxStatus({
- *   params: { txHash: '0x123...', srcChainId: '1' },
+ * const { data: status } = useBackendSubmitSwapTxStatus({
+ *   params: { txHash: '0x123...', srcChainKey: 'sonic' },
  * });
  *
- * if (status?.data.status === 'executed') {
- *   console.log('Swap completed!', status.data.result);
- * }
- *
  * @remarks
- * - Query is disabled if `params` is undefined or `txHash` is undefined/empty.
- * - Default refetch interval is 1 second for real-time status polling.
- * - Uses React Query for state management, caching, and retries.
+ * - Default refetch interval is 1 second; stops on 'executed' or 'failed' status.
  */
-export const useBackendSubmitSwapTxStatus = (
-  params: UseBackendSubmitSwapTxStatusParams | undefined,
-): UseQueryResult<SubmitSwapTxStatusResponse | undefined, Error> => {
+export const useBackendSubmitSwapTxStatus = ({
+  params,
+  queryOptions,
+}: UseBackendSubmitSwapTxStatusParams = {}): UseQueryResult<SubmitSwapTxStatusResponse | undefined, Error> => {
   const { sodax } = useSodaxContext();
+  const txHash = params?.txHash;
+  const srcChainKey = params?.srcChainKey;
+  const apiConfig = params?.apiConfig;
 
-  const defaultQueryOptions = {
-    queryKey: ['api', 'swaps', 'submit-tx', 'status', params?.params?.txHash, params?.params?.srcChainId],
-    enabled: !!params?.params?.txHash && params.params.txHash.length > 0,
+  return useQuery({
+    queryKey: ['backend', 'submitSwapTx', 'status', txHash, srcChainKey],
+    queryFn: async (): Promise<SubmitSwapTxStatusResponse | undefined> => {
+      if (!txHash) return undefined;
+      return unwrapResult(
+        await sodax.backendApi.getSubmitSwapTxStatus(
+          {
+            txHash,
+            srcChainKey,
+          },
+          apiConfig,
+        ),
+      );
+    },
+    enabled: !!txHash && txHash.length > 0,
     retry: 3,
-    refetchInterval: (query: { state: { data: SubmitSwapTxStatusResponse | undefined } }) => {
+    refetchInterval: query => {
       const status = query.state.data?.data?.status;
       if (status === 'executed' || status === 'failed') return false;
       return 1000;
     },
-  };
-
-  const queryOptions = {
-    ...defaultQueryOptions,
-    ...params?.queryOptions,
-  };
-
-  return useQuery({
     ...queryOptions,
-    queryFn: async (): Promise<SubmitSwapTxStatusResponse | undefined> => {
-      if (!params?.params?.txHash) {
-        return undefined;
-      }
-      return sodax.backendApi.getSubmitSwapTxStatus(
-        {
-          txHash: params.params.txHash,
-          srcChainId: params.params.srcChainId,
-        },
-        params.apiConfig,
-      );
-    },
   });
 };

package/src/hooks/backend/useBackendUserIntents.ts

@@ -1,81 +1,43 @@
 import type { UserIntentsResponse, Address } from '@sodax/sdk';
-// packages/dapp-kit/src/hooks/backend/useBackendUserIntents.ts
-import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { BackendPaginationParams } from './types';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import { unwrapResult } from './unwrapResult.js';
+import type { ReadHookParams } from '../shared/types.js';
 
-export type GetUserIntentsParams = {
-  userAddress: Address;
-  startDate?: number;
-  endDate?: number;
-};
-
-export type UseBackendUserIntentsParams = {
-  params?: GetUserIntentsParams;
-  queryOptions?: UseQueryOptions<UserIntentsResponse | undefined, Error>;
-  pagination?: BackendPaginationParams;
-};
+export type UseBackendUserIntentsParams = ReadHookParams<
+  UserIntentsResponse | undefined,
+  {
+    userAddress: Address | undefined;
+    startDate?: number;
+    endDate?: number;
+  }
+>;
 
 /**
- * React hook for fetching user-created intents from the backend API for a given user address,
- * with optional support for a date filtering range.
- *
- * @param {UseBackendUserIntentsParams} args - Query configuration.
- *   @param {GetUserIntentsParams | undefined} args.params - User intent filter parameters.
- *     @param {Address} args.params.userAddress - The wallet address of the user (required).
- *     @param {number} [args.params.startDate] - Include intents created after this timestamp (ms).
- *     @param {number} [args.params.endDate] - Include intents created before this timestamp (ms).
- *   @param {UseQueryOptions<UserIntentsResponse | undefined, Error>} [args.queryOptions] - Optional React Query options.
- *   @param {BackendPaginationParams} [args.pagination] - (currently ignored) Pagination options.
- *
- * @returns {UseQueryResult<UserIntentsResponse | undefined, Error>} React Query result:
- *   - `data`: The user intent response, or undefined if unavailable.
- *   - `isLoading`: `true` if loading.
- *   - `error`: An Error instance if any occurred.
- *   - `refetch`: Function to refetch data.
- *
- * @example
- * const { data: userIntents, isLoading, error } = useBackendUserIntents({
- *   params: { userAddress: "0x123..." }
- * });
+ * React hook for fetching user-created intents from the backend API for a given user address.
  *
  * @example
- * const { data } = useBackendUserIntents({
- *   params: {
- *     userAddress: "0xabc...",
- *     startDate: Date.now() - 1_000_000,
- *     endDate: Date.now(),
- *   },
+ * const { data: userIntents } = useBackendUserIntents({
+ *   params: { userAddress: '0x123...' },
  * });
- *
- * @remarks
- * The query is disabled if `params` or `params.userAddress` is missing or empty. Uses React Query for
- * cache/state management and auto-retries failed requests three times by default.
  */
 export const useBackendUserIntents = ({
   params,
   queryOptions,
-}: UseBackendUserIntentsParams): UseQueryResult<UserIntentsResponse | undefined, Error> => {
+}: UseBackendUserIntentsParams = {}): UseQueryResult<UserIntentsResponse | undefined, Error> => {
   const { sodax } = useSodaxContext();
-  const defaultQueryOptions = {
-    queryKey: ['api', 'intent', 'user', params],
-    enabled: !!params && !!params.userAddress && params.userAddress.length > 0,
-    retry: 3,
-  };
-
-  queryOptions = {
-    ...defaultQueryOptions,
-    ...queryOptions, // override default query options if provided
-  };
+  const userAddress = params?.userAddress;
+  const startDate = params?.startDate;
+  const endDate = params?.endDate;
 
   return useQuery({
-    ...queryOptions,
+    queryKey: ['backend', 'intent', 'user', userAddress, startDate, endDate],
     queryFn: async (): Promise<UserIntentsResponse | undefined> => {
-      if (!params?.userAddress) {
-        return undefined;
-      }
-
-      return sodax.backendApi.getUserIntents(params);
+      if (!userAddress) return undefined;
+      return unwrapResult(await sodax.backendApi.getUserIntents({ userAddress, startDate, endDate }));
     },
+    enabled: !!userAddress && userAddress.length > 0,
+    retry: 3,
+    ...queryOptions,
   });
 };

package/src/hooks/bitcoin/index.ts

@@ -1,8 +1,9 @@
-export * from './useRadfiAuth';
-export * from './useRadfiSession';
-export * from './useFundTradingWallet';
-export * from './useBitcoinBalance';
-export * from './useTradingWalletBalance';
-export * from './useExpiredUtxos';
-export * from './useRenewUtxos';
-export * from './useRadfiWithdraw';
+export * from './useRadfiAuth.js';
+export * from './useRadfiSession.js';
+export * from './useFundTradingWallet.js';
+export * from './useBitcoinBalance.js';
+export * from './useTradingWallet.js';
+export * from './useTradingWalletBalance.js';
+export * from './useExpiredUtxos.js';
+export * from './useRenewUtxos.js';
+export * from './useRadfiWithdraw.js';

package/src/hooks/bitcoin/useBitcoinBalance.ts

@@ -1,4 +1,15 @@
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseBitcoinBalanceParams = ReadHookParams<
+  bigint,
+  {
+    address: string | undefined;
+    rpcUrl?: string;
+  }
+>;
+
+const DEFAULT_RPC_URL = 'https://mempool.space/api';
 
 /**
  * Hook to fetch BTC balance for any Bitcoin address.
@@ -7,12 +18,15 @@ import { useQuery, type UseQueryResult } from '@tanstack/react-query';
  * The UTXO set already excludes spent outputs (even from unconfirmed txs),
  * so the total is always the correct spendable balance.
  */
-export function useBitcoinBalance(
-  address: string | undefined,
-  rpcUrl = 'https://mempool.space/api',
-): UseQueryResult<bigint, Error> {
+export function useBitcoinBalance({
+  params,
+  queryOptions,
+}: UseBitcoinBalanceParams = {}): UseQueryResult<bigint, Error> {
+  const address = params?.address;
+  const rpcUrl = params?.rpcUrl ?? DEFAULT_RPC_URL;
+
   return useQuery<bigint, Error>({
-    queryKey: ['btc-balance', address],
+    queryKey: ['bitcoin', 'balance', address],
     queryFn: async () => {
       if (!address) return 0n;
 
@@ -23,5 +37,6 @@ export function useBitcoinBalance(
       return BigInt(utxos.reduce((sum, utxo) => sum + utxo.value, 0));
     },
     enabled: !!address,
+    ...queryOptions,
   });
 }

package/src/hooks/bitcoin/useExpiredUtxos.ts

@@ -1,25 +1,35 @@
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
-import type { BitcoinSpokeProvider, RadfiUtxo } from '@sodax/sdk';
+import type { RadfiUtxo, IBitcoinWalletProvider } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseExpiredUtxosParams = ReadHookParams<
+  RadfiUtxo[],
+  {
+    walletProvider: IBitcoinWalletProvider | undefined;
+    tradingAddress: string | undefined;
+  }
+>;
+
+export function useExpiredUtxos({
+  params,
+  queryOptions,
+}: UseExpiredUtxosParams = {}): UseQueryResult<RadfiUtxo[], Error> {
+  const { sodax } = useSodaxContext();
+  const walletProvider = params?.walletProvider;
+  const tradingAddress = params?.tradingAddress;
 
-/**
- * Hook to fetch expired UTXOs for a trading wallet address.
- * UTXOs that are expired or within 2 weeks of expiry are considered invalid for trading
- * and need to be renewed via the Radfi renew-utxo flow.
- */
-export function useExpiredUtxos(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-  tradingAddress: string | undefined,
-): UseQueryResult<RadfiUtxo[], Error> {
   return useQuery<RadfiUtxo[], Error>({
-    queryKey: ['expired-utxos', tradingAddress],
+    queryKey: ['bitcoin', 'expiredUtxos', tradingAddress],
     queryFn: async () => {
-      if (!spokeProvider || !tradingAddress) {
-        throw new Error('spokeProvider and tradingAddress are required');
+      if (!walletProvider || !tradingAddress) {
+        throw new Error('walletProvider and tradingAddress are required');
       }
-      const result = await spokeProvider.radfi.getExpiredUtxos(tradingAddress);
+      const result = await sodax.spoke.bitcoin.radfi.getExpiredUtxos(tradingAddress);
       return result.data;
     },
-    enabled: !!spokeProvider && !!tradingAddress,
-    refetchInterval: 60_000, // refetch every minute
+    enabled: !!walletProvider && !!tradingAddress,
+    refetchInterval: 60_000,
+    ...queryOptions,
   });
 }

package/src/hooks/bitcoin/useFundTradingWallet.ts

@@ -1,39 +1,42 @@
-import { BitcoinSpokeService, type BitcoinSpokeProvider } from '@sodax/sdk';
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
+// packages/dapp-kit/src/hooks/bitcoin/useFundTradingWallet.ts
+import { useQueryClient } from '@tanstack/react-query';
+import { ChainKeys, type IBitcoinWalletProvider } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+export type UseFundTradingWalletVars = {
+  amount: bigint;
+  walletProvider: IBitcoinWalletProvider;
+};
 
 /**
- * Hook to fund the Radfi trading wallet by sending BTC from the user's personal wallet.
- *
- * @param {BitcoinSpokeProvider | undefined} spokeProvider - The Bitcoin spoke provider with signing capability
- * @returns {UseMutationResult} Mutation result — input is amount in satoshis, output is transaction ID
- *
- * @example
- * ```tsx
- * const { mutateAsync: fundWallet, isPending } = useFundTradingWallet(spokeProvider);
- *
- * const handleFund = async () => {
- *   const txId = await fundWallet(100_000n); // fund 100,000 satoshis
- *   console.log('Funded:', txId);
- * };
- * ```
+ * React hook for funding the user's Radfi trading wallet from their personal Bitcoin wallet.
+ * Pure mutation: pass `{ amount, walletProvider }` to `mutate({...})`. Returns the broadcast tx
+ * id on success.
  */
-export function useFundTradingWallet(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-): UseMutationResult<string, Error, bigint> {
+export function useFundTradingWallet({
+  mutationOptions,
+}: MutationHookParams<string, UseFundTradingWalletVars> = {}): SafeUseMutationResult<
+  string,
+  Error,
+  UseFundTradingWalletVars
+> {
+  const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation<string, Error, bigint>({
-    mutationFn: async (amount: bigint) => {
-      if (!spokeProvider) {
-        throw new Error('Bitcoin spoke provider not found');
-      }
-
-      return BitcoinSpokeService.fundTradingWallet(amount, spokeProvider);
+  return useSafeMutation<string, Error, UseFundTradingWalletVars>({
+    mutationKey: ['bitcoin', 'fundTradingWallet'],
+    ...mutationOptions,
+    mutationFn: async ({ amount, walletProvider }) => {
+      const walletAddress = await walletProvider.getWalletAddress();
+      return sodax.spoke.bitcoin.fundTradingWallet(amount, walletAddress, walletProvider);
     },
-    onSuccess: () => {
-      // Invalidate balance queries to reflect the fund transfer
-      queryClient.invalidateQueries({ queryKey: ['btc-balance'] });
-      queryClient.invalidateQueries({ queryKey: ['xBalances'] });
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['bitcoin', 'balance'] });
+      queryClient.invalidateQueries({ queryKey: ['bitcoin', 'tradingWalletBalance'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', ChainKeys.BITCOIN_MAINNET] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/bitcoin/useRadfiAuth.ts

@@ -1,5 +1,8 @@
-import type { BitcoinSpokeProvider } from '@sodax/sdk';
-import { useMutation, type UseMutationResult } from '@tanstack/react-query';
+// packages/dapp-kit/src/hooks/bitcoin/useRadfiAuth.ts
+import { RadfiApiError, type IBitcoinWalletProvider } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
 
 export type RadfiSession = {
   accessToken: string;
@@ -8,17 +11,20 @@ export type RadfiSession = {
   publicKey: string;
 };
 
+export type UseRadfiAuthVars = {
+  walletProvider: IBitcoinWalletProvider;
+};
+
 type RadfiAuthResult = {
   accessToken: string;
   refreshToken: string;
   tradingAddress: string;
 };
 
-const SESSION_KEY = (address: string) => `radfi_session_${address}`;
+const SESSION_KEY = (address: string): string => `radfi_session_${address}`;
 
 export function saveRadfiSession(address: string, session: RadfiSession): void {
   try {
-    // Radfi tokens are only used for API rate-limiting / anti-spam, not for accessing user assets.
     localStorage.setItem(SESSION_KEY(address), JSON.stringify(session));
   } catch {}
 }
@@ -39,62 +45,59 @@ export function clearRadfiSession(address: string): void {
 }
 
 /**
- * Hook to authenticate with Radfi using BIP322 message signing.
- * Saves session (accessToken, refreshToken, tradingAddress, publicKey) to localStorage.
+ * React hook for authenticating with Radfi via BIP322-signed message. Pure mutation: pass
+ * `{ walletProvider }` to `mutate({...})`. The hook itself takes no arguments other than the
+ * structural `mutationOptions` slot.
  */
-export function useRadfiAuth(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-): UseMutationResult<RadfiAuthResult, Error, void> {
-  return useMutation<RadfiAuthResult, Error, void>({
-    mutationFn: async () => {
-      if (!spokeProvider) {
-        throw new Error('Bitcoin spoke provider not found');
-      }
-
-      const walletAddress = await spokeProvider.walletProvider.getWalletAddress();
+export function useRadfiAuth({
+  mutationOptions,
+}: MutationHookParams<RadfiAuthResult, UseRadfiAuthVars> = {}): SafeUseMutationResult<
+  RadfiAuthResult,
+  Error,
+  UseRadfiAuthVars
+> {
+  const { sodax } = useSodaxContext();
+  return useSafeMutation<RadfiAuthResult, Error, UseRadfiAuthVars>({
+    mutationKey: ['bitcoin', 'radfiAuth'],
+    ...mutationOptions,
+    mutationFn: async ({ walletProvider }) => {
+      const radfi = sodax.spoke.bitcoin.radfi;
+      const walletAddress = await walletProvider.getWalletAddress();
       const existingSession = loadRadfiSession(walletAddress);
       const cachedPublicKey = existingSession?.publicKey;
 
       try {
-        const { accessToken, refreshToken, tradingAddress, publicKey } = await spokeProvider.authenticateWithWallet(cachedPublicKey);
-
-        const session: RadfiSession = {
-          accessToken,
-          refreshToken,
-          tradingAddress,
-          publicKey,
-        };
-
-        saveRadfiSession(walletAddress, session);
-
+        const { accessToken, refreshToken, tradingAddress, publicKey } = await radfi.authenticateWithWallet(
+          walletProvider,
+          cachedPublicKey,
+        );
+        saveRadfiSession(walletAddress, { accessToken, refreshToken, tradingAddress, publicKey });
         return { accessToken, refreshToken, tradingAddress };
       } catch (err: unknown) {
-        // Error 4008: wallet already registered — authenticate is register+login combined.
-        // Try to refresh with existing session if available.
-        const isAlreadyRegistered =
-          err instanceof Error &&
-          (err.message.includes('duplicatedPubKey') || err.message.includes('4008'));
+        const isAlreadyRegistered = err instanceof RadfiApiError && err.code === '4008';
 
         if (isAlreadyRegistered && existingSession?.refreshToken) {
           try {
-            const refreshed = await spokeProvider.radfi.refreshAccessToken(existingSession.refreshToken);
-            const session: RadfiSession = {
+            const refreshed = await radfi.refreshAccessToken(existingSession.refreshToken);
+            radfi.setRadfiAccessToken(refreshed.accessToken, refreshed.refreshToken);
+            saveRadfiSession(walletAddress, {
               ...existingSession,
               accessToken: refreshed.accessToken,
               refreshToken: refreshed.refreshToken,
+            });
+            return {
+              accessToken: refreshed.accessToken,
+              refreshToken: refreshed.refreshToken,
+              tradingAddress: existingSession.tradingAddress,
             };
-            spokeProvider.setRadfiAccessToken(refreshed.accessToken, refreshed.refreshToken);
-            saveRadfiSession(walletAddress, session);
-            return { accessToken: refreshed.accessToken, refreshToken: refreshed.refreshToken, tradingAddress: existingSession.tradingAddress };
           } catch {
-            // Refresh also failed — clear stale session and guide user
             clearRadfiSession(walletAddress);
           }
 
           throw new Error(
             'This wallet is already registered with Radfi from another session. ' +
-            'Please clear your browser storage for this site and try again, ' +
-            'or wait for the previous session to expire.',
+              'Please clear your browser storage for this site and try again, ' +
+              'or wait for the previous session to expire.',
           );
         }