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

package/src/hooks/bitcoin/useRadfiSession.ts

@@ -1,14 +1,16 @@
+// packages/dapp-kit/src/hooks/bitcoin/useRadfiSession.ts
 import { useState, useEffect, useRef, useCallback } from 'react';
-import type { BitcoinSpokeProvider } from '@sodax/sdk';
+import type { IBitcoinWalletProvider } from '@sodax/sdk';
 import {
   useRadfiAuth,
   loadRadfiSession,
   saveRadfiSession,
   clearRadfiSession,
   type RadfiSession,
-} from './useRadfiAuth';
+} from './useRadfiAuth.js';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
 
-const REFRESH_INTERVAL = 5 * 60 * 1000; // 5 min — refresh before access token expires (10 min TTL)
+const REFRESH_INTERVAL = 5 * 60 * 1000;
 
 export type UseRadfiSessionReturn = {
   walletAddress: string | undefined;
@@ -18,94 +20,86 @@ export type UseRadfiSessionReturn = {
   isLoginPending: boolean;
 };
 
-/**
- * Manages the full Radfi session lifecycle:
- * - On mount / wallet switch: refreshes token to validate session
- * - Single interval (~5 min): refreshes access token. If refresh fails → clears session, isAuthed=false
- * - ensureRadfiAccessToken (SDK layer) acts as safety net before swap/bridge
- * - Exposes login() and isAuthed for UI
- */
-export function useRadfiSession(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-): UseRadfiSessionReturn {
+export function useRadfiSession(walletProvider: IBitcoinWalletProvider | undefined): UseRadfiSessionReturn {
+  const { sodax } = useSodaxContext();
   const [walletAddress, setWalletAddress] = useState<string | undefined>();
   const [isAuthed, setIsAuthed] = useState(false);
   const [tradingAddress, setTradingAddress] = useState<string | undefined>();
   const isRefreshingRef = useRef(false);
 
-  // ── Silent refresh helper ────────────────────────────────────────────────
-  const silentRefresh = useCallback(async (address: string) => {
-    if (!spokeProvider || isRefreshingRef.current) return;
-    isRefreshingRef.current = true;
-
-    try {
-      const session = loadRadfiSession(address);
-      if (!session?.refreshToken) {
+  const silentRefresh = useCallback(
+    async (address: string) => {
+      if (!walletProvider || isRefreshingRef.current) return;
+      isRefreshingRef.current = true;
+
+      try {
+        const session = loadRadfiSession(address);
+        if (!session?.refreshToken) {
+          setIsAuthed(false);
+          return;
+        }
+
+        const radfi = sodax.spoke.bitcoin.radfi;
+        const { accessToken, refreshToken } = await radfi.refreshAccessToken(session.refreshToken);
+        const updated: RadfiSession = { ...session, accessToken, refreshToken };
+
+        saveRadfiSession(address, updated);
+        radfi.setRadfiAccessToken(accessToken, refreshToken);
+        setIsAuthed(true);
+        setTradingAddress(updated.tradingAddress || undefined);
+      } catch {
+        clearRadfiSession(address);
+        sodax.spoke.bitcoin.radfi.setRadfiAccessToken('', '');
         setIsAuthed(false);
-        return;
+        setTradingAddress(undefined);
+      } finally {
+        isRefreshingRef.current = false;
       }
+    },
+    [walletProvider, sodax],
+  );
 
-      const { accessToken, refreshToken } = await spokeProvider.radfi.refreshAccessToken(session.refreshToken);
-      const updated: RadfiSession = {
-        ...session,
-        accessToken,
-        refreshToken,
-      };
-
-      saveRadfiSession(address, updated);
-      spokeProvider.setRadfiAccessToken(accessToken, refreshToken);
-      setIsAuthed(true);
-      setTradingAddress(updated.tradingAddress || undefined);
-    } catch {
-      clearRadfiSession(address);
-      spokeProvider.setRadfiAccessToken('', '');
-      setIsAuthed(false);
-      setTradingAddress(undefined);
-    } finally {
-      isRefreshingRef.current = false;
-    }
-  }, [spokeProvider]);
-
-  // ── On mount / wallet switch: reset state + refresh to validate session ──
   useEffect(() => {
-    if (!spokeProvider) return;
+    if (!walletProvider) return;
 
-    // Reset state immediately to avoid stale data from previous wallet
     setIsAuthed(false);
     setTradingAddress(undefined);
     setWalletAddress(undefined);
 
-    spokeProvider.walletProvider.getWalletAddress()
-      .then((addr) => {
+    walletProvider
+      .getWalletAddress()
+      .then((addr: string) => {
         setWalletAddress(addr);
         const session = loadRadfiSession(addr);
         if (!session?.refreshToken) return;
-
-        // Always refresh on mount to validate the session is actually valid
         silentRefresh(addr);
       })
       .catch(() => {});
-  }, [spokeProvider, silentRefresh]);
+  }, [walletProvider, silentRefresh]);
 
-  // ── Interval: refresh token every 5 min to keep access token fresh ──────
   useEffect(() => {
-    if (!walletAddress || !spokeProvider) return;
+    if (!walletAddress || !walletProvider) return;
 
     const id = setInterval(() => {
       silentRefresh(walletAddress);
     }, REFRESH_INTERVAL);
 
     return () => clearInterval(id);
-  }, [walletAddress, spokeProvider, silentRefresh]);
+  }, [walletAddress, walletProvider, silentRefresh]);
 
-  // ── Login ────────────────────────────────────────────────────────────────
-  const { mutateAsync: loginMutate, isPending: isLoginPending } = useRadfiAuth(spokeProvider);
+  const { mutateAsyncSafe: loginMutateSafe, isPending: isLoginPending } = useRadfiAuth();
 
   const login = useCallback(async () => {
-    const result = await loginMutate();
+    if (!walletProvider) {
+      return;
+    }
+    const result = await loginMutateSafe({ walletProvider });
+    if (!result.ok) {
+      return;
+    }
     setIsAuthed(true);
-    setTradingAddress(result.tradingAddress || undefined);
-  }, [loginMutate]);
+    setTradingAddress(result.value.tradingAddress || undefined);
+  }, [loginMutateSafe, walletProvider]);
 
   return { walletAddress, isAuthed, tradingAddress, login, isLoginPending };
 }

package/src/hooks/bitcoin/useRadfiWithdraw.ts

@@ -1,11 +1,16 @@
-import { normalizePsbtToBase64, type BitcoinSpokeProvider } from '@sodax/sdk';
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import { loadRadfiSession } from './useRadfiAuth';
+// packages/dapp-kit/src/hooks/bitcoin/useRadfiWithdraw.ts
+import { normalizePsbtToBase64, ChainKeys, type IBitcoinWalletProvider } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { loadRadfiSession } from './useRadfiAuth.js';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
 
-type WithdrawToUserParams = {
+export type UseRadfiWithdrawVars = {
   amount: string;
   tokenId: string;
   withdrawTo: string;
+  walletProvider: IBitcoinWalletProvider;
 };
 
 type WithdrawResult = {
@@ -14,72 +19,49 @@ type WithdrawResult = {
 };
 
 /**
- * Hook to withdraw BTC from Radfi trading wallet to user's personal wallet.
- *
- * Flow:
- * 1. Build withdraw transaction via Radfi API (returns unsigned PSBT)
- * 2. User signs the PSBT with their wallet
- * 3. Submit signed PSBT back to Radfi for co-signing and broadcasting
- *
- * @example
- * ```tsx
- * const { mutateAsync: withdraw, isPending } = useRadfiWithdraw(spokeProvider);
- *
- * const handleWithdraw = async () => {
- *   const result = await withdraw({
- *     amount: '10000',
- *     tokenId: '0:0',
- *     withdrawTo: 'bc1q...', // user's segwit address
- *   });
- *   console.log('Withdrawn:', result.txId);
- * };
- * ```
+ * React hook for withdrawing BTC from the user's Radfi trading wallet back to their personal
+ * Bitcoin wallet. Pure mutation: pass all inputs (including the wallet provider) to
+ * `mutate({...})`.
  */
-export function useRadfiWithdraw(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-): UseMutationResult<WithdrawResult, Error, WithdrawToUserParams> {
+export function useRadfiWithdraw({
+  mutationOptions,
+}: MutationHookParams<WithdrawResult, UseRadfiWithdrawVars> = {}): SafeUseMutationResult<
+  WithdrawResult,
+  Error,
+  UseRadfiWithdrawVars
+> {
+  const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation<WithdrawResult, Error, WithdrawToUserParams>({
-    mutationFn: async ({ amount, tokenId, withdrawTo }: WithdrawToUserParams) => {
-      if (!spokeProvider) {
-        throw new Error('Bitcoin spoke provider not found');
-      }
+  return useSafeMutation<WithdrawResult, Error, UseRadfiWithdrawVars>({
+    mutationKey: ['bitcoin', 'radfiWithdraw'],
+    ...mutationOptions,
+    mutationFn: async ({ amount, tokenId, withdrawTo, walletProvider }) => {
+      const radfi = sodax.spoke.bitcoin.radfi;
 
-      const userAddress = await spokeProvider.walletProvider.getWalletAddress();
+      const userAddress = await walletProvider.getWalletAddress();
       const session = loadRadfiSession(userAddress);
-      const accessToken = session?.accessToken || spokeProvider.radfiAccessToken;
+      const accessToken = session?.accessToken || radfi.accessToken;
 
       if (!accessToken) {
         throw new Error('Radfi authentication required. Please login first.');
       }
 
-      // Step 1: Build the withdraw transaction
-      const buildResult = await spokeProvider.radfi.withdrawToUser(
-        { userAddress, amount, tokenId, withdrawTo },
-        accessToken,
-      );
+      const buildResult = await radfi.withdrawToUser({ userAddress, amount, tokenId, withdrawTo }, accessToken);
 
-      // Step 2: Sign the PSBT with user's wallet
-      const signedTx = await spokeProvider.walletProvider.signTransaction(
-        buildResult.base64Psbt,
-        false,
-      );
+      const signedTx = await walletProvider.signTransaction(buildResult.base64Psbt, false);
 
       const signedBase64Tx = normalizePsbtToBase64(signedTx);
 
-      // Step 3: Submit to Radfi for co-signing and broadcasting
-      const txId = await spokeProvider.radfi.signAndBroadcastWithdraw(
-        { userAddress, signedBase64Tx },
-        accessToken,
-      );
+      const txId = await radfi.signAndBroadcastWithdraw({ userAddress, signedBase64Tx }, accessToken);
 
       return { txId, fee: buildResult.fee.totalFee };
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['trading-wallet-balance'] });
-      queryClient.invalidateQueries({ queryKey: ['btc-balance'] });
-      queryClient.invalidateQueries({ queryKey: ['xBalances'] });
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['bitcoin', 'tradingWalletBalance'] });
+      queryClient.invalidateQueries({ queryKey: ['bitcoin', 'balance'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', ChainKeys.BITCOIN_MAINNET] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/bitcoin/useRenewUtxos.ts

@@ -1,72 +1,52 @@
-import { normalizePsbtToBase64, type BitcoinSpokeProvider } from '@sodax/sdk';
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import { loadRadfiSession } from './useRadfiAuth';
-
-type RenewUtxosParams = {
+// packages/dapp-kit/src/hooks/bitcoin/useRenewUtxos.ts
+import { normalizePsbtToBase64, type IBitcoinWalletProvider } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { loadRadfiSession } from './useRadfiAuth.js';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+
+export type UseRenewUtxosVars = {
   txIdVouts: string[];
+  walletProvider: IBitcoinWalletProvider;
 };
 
 /**
- * Hook to renew expired UTXOs in the Radfi trading wallet.
- *
- * Flow:
- * 1. Build renew-utxo transaction via Radfi API (returns unsigned PSBT)
- * 2. User signs the PSBT with their wallet
- * 3. Submit signed PSBT back to Radfi for co-signing and broadcasting
- *
- * @example
- * ```tsx
- * const { mutateAsync: renewUtxos, isPending } = useRenewUtxos(spokeProvider);
- *
- * const handleRenew = async (expiredUtxos: RadfiUtxo[]) => {
- *   const txIdVouts = expiredUtxos.map(u => u.txidVout);
- *   const txId = await renewUtxos({ txIdVouts });
- *   console.log('Renewed:', txId);
- * };
- * ```
+ * React hook for renewing expired UTXOs in the user's Radfi trading wallet. Pure mutation: pass
+ * `{ txIdVouts, walletProvider }` to `mutate({...})`.
  */
-export function useRenewUtxos(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-): UseMutationResult<string, Error, RenewUtxosParams> {
+export function useRenewUtxos({
+  mutationOptions,
+}: MutationHookParams<string, UseRenewUtxosVars> = {}): SafeUseMutationResult<string, Error, UseRenewUtxosVars> {
+  const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation<string, Error, RenewUtxosParams>({
-    mutationFn: async ({ txIdVouts }: RenewUtxosParams) => {
-      if (!spokeProvider) {
-        throw new Error('Bitcoin spoke provider not found');
-      }
+  return useSafeMutation<string, Error, UseRenewUtxosVars>({
+    mutationKey: ['bitcoin', 'renewUtxos'],
+    ...mutationOptions,
+    mutationFn: async ({ txIdVouts, walletProvider }) => {
+      const radfi = sodax.spoke.bitcoin.radfi;
 
-      const userAddress = await spokeProvider.walletProvider.getWalletAddress();
+      const userAddress = await walletProvider.getWalletAddress();
       const session = loadRadfiSession(userAddress);
-      const accessToken = session?.accessToken || spokeProvider.radfiAccessToken;
+      const accessToken = session?.accessToken || radfi.accessToken;
 
       if (!accessToken) {
         throw new Error('Radfi authentication required. Please login first.');
       }
 
-      // Step 1: Build the renew-utxo transaction
-      const buildResult = await spokeProvider.radfi.buildRenewUtxoTransaction(
-        { userAddress, txIdVouts },
-        accessToken,
-      );
+      const buildResult = await radfi.buildRenewUtxoTransaction({ userAddress, txIdVouts }, accessToken);
 
-      // Step 2: Sign the PSBT with user's wallet
-      const signedTx = await spokeProvider.walletProvider.signTransaction(
-        buildResult.base64Psbt,
-        false,
-      );
+      const signedTx = await walletProvider.signTransaction(buildResult.base64Psbt, false);
 
       const signedBase64Tx = normalizePsbtToBase64(signedTx);
 
-      // Step 3: Submit to Radfi for co-signing and broadcasting
-      return spokeProvider.radfi.signAndBroadcastRenewUtxo(
-        { userAddress, signedBase64Tx },
-        accessToken,
-      );
+      return radfi.signAndBroadcastRenewUtxo({ userAddress, signedBase64Tx }, accessToken);
     },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['expired-utxos'] });
-      queryClient.invalidateQueries({ queryKey: ['trading-wallet-balance'] });
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['bitcoin', 'expiredUtxos'] });
+      queryClient.invalidateQueries({ queryKey: ['bitcoin', 'tradingWalletBalance'] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/bitcoin/useTradingWallet.ts

@@ -1,4 +1,4 @@
-import { loadRadfiSession } from './useRadfiAuth';
+import { loadRadfiSession } from './useRadfiAuth.js';
 
 type UseTradingWalletReturn = {
   tradingAddress: string | undefined;

package/src/hooks/bitcoin/useTradingWalletBalance.ts

@@ -1,22 +1,33 @@
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
-import type { BitcoinSpokeProvider, RadfiWalletBalance } from '@sodax/sdk';
+import type { RadfiWalletBalance, IBitcoinWalletProvider } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+export type UseTradingWalletBalanceParams = ReadHookParams<
+  RadfiWalletBalance,
+  {
+    walletProvider: IBitcoinWalletProvider | undefined;
+    tradingAddress: string | undefined;
+  }
+>;
+
+export function useTradingWalletBalance({
+  params,
+  queryOptions,
+}: UseTradingWalletBalanceParams = {}): UseQueryResult<RadfiWalletBalance, Error> {
+  const { sodax } = useSodaxContext();
+  const walletProvider = params?.walletProvider;
+  const tradingAddress = params?.tradingAddress;
 
-/**
- * Hook to fetch trading wallet balance from Radfi API.
- * Returns confirmed + pending satoshi balances.
- */
-export function useTradingWalletBalance(
-  spokeProvider: BitcoinSpokeProvider | undefined,
-  tradingAddress: string | undefined,
-): UseQueryResult<RadfiWalletBalance, Error> {
   return useQuery<RadfiWalletBalance, Error>({
-    queryKey: ['trading-wallet-balance', tradingAddress],
+    queryKey: ['bitcoin', 'tradingWalletBalance', tradingAddress],
     queryFn: () => {
-      if (!spokeProvider || !tradingAddress) {
-        throw new Error('spokeProvider and tradingAddress are required');
+      if (!walletProvider || !tradingAddress) {
+        throw new Error('walletProvider and tradingAddress are required');
       }
-      return spokeProvider.radfi.getBalance(tradingAddress);
+      return sodax.spoke.bitcoin.radfi.getBalance(tradingAddress);
     },
-    enabled: !!spokeProvider && !!tradingAddress,
+    enabled: !!walletProvider && !!tradingAddress,
+    ...queryOptions,
   });
 }

package/src/hooks/bridge/index.ts

@@ -1,5 +1,5 @@
-export * from './useBridgeAllowance';
-export * from './useBridgeApprove';
-export * from './useBridge';
-export * from './useGetBridgeableAmount';
-export * from './useGetBridgeableTokens';
+export * from './useBridge.js';
+export * from './useBridgeAllowance.js';
+export * from './useBridgeApprove.js';
+export * from './useGetBridgeableAmount.js';
+export * from './useGetBridgeableTokens.js';

package/src/hooks/bridge/useBridge.ts

@@ -1,64 +1,38 @@
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type {
-  BridgeError,
-  BridgeErrorCode,
-  SpokeTxHash,
-  HubTxHash,
-  Result,
-  CreateBridgeIntentParams,
-} from '@sodax/sdk';
-import { useMutation, type UseMutationResult } from '@tanstack/react-query';
-import type { SpokeProvider } from '@sodax/sdk';
+// packages/dapp-kit/src/hooks/bridge/useBridge.ts
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { BridgeParams, SpokeChainKey, TxHashPair } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 
 /**
- * Hook for executing bridge transactions to transfer tokens between chains.
- * Uses React Query's useMutation for better state management and caching.
- *
- * @param {SpokeProvider} spokeProvider - The spoke provider to use for the bridge
- * @returns {UseMutationResult} Mutation result object containing mutation function and state
- *
- * @example
- * ```typescript
- * const { mutateAsync: bridge, isPending } = useBridge(spokeProvider);
- *
- * const handleBridge = async () => {
- *   const result = await bridge({
- *     srcChainId: '0x2105.base',
- *     srcAsset: '0x...',
- *     amount: 1000n,
- *     dstChainId: '0x89.polygon',
- *     dstAsset: '0x...',
- *     recipient: '0x...'
- *   });
+ * Mutation variables for {@link useBridge}. 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 UseBridgeVars<K extends SpokeChainKey = SpokeChainKey> = Omit<BridgeParams<K, false>, 'raw'>;
+
+/**
+ * React hook for executing a cross-chain bridge transfer.
  *
- *   console.log('Bridge transaction hashes:', {
- *     spokeTxHash: result.spokeTxHash,
- *     hubTxHash: result.hubTxHash
- *   });
- * };
- * ```
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  */
-export function useBridge(
-  spokeProvider: SpokeProvider | undefined,
-): UseMutationResult<Result<[SpokeTxHash, HubTxHash], BridgeError<BridgeErrorCode>>, Error, CreateBridgeIntentParams> {
+export function useBridge<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseBridgeVars<K>> = {}): SafeUseMutationResult<TxHashPair, Error, UseBridgeVars<K>> {
   const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
 
-  return useMutation<Result<[SpokeTxHash, HubTxHash], BridgeError<BridgeErrorCode>>, Error, CreateBridgeIntentParams>({
-    mutationFn: async (params: CreateBridgeIntentParams) => {
-      if (!spokeProvider) {
-        throw new Error('Spoke provider not found');
-      }
-
-      const result = await sodax.bridge.bridge({
-        params,
-        spokeProvider,
-      });
-
-      if (!result.ok) {
-        throw new Error(`Bridge failed: ${result.error.code}`);
-      }
-
-      return result;
+  return useSafeMutation<TxHashPair, Error, UseBridgeVars<K>>({
+    mutationKey: ['bridge'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.bridge.bridge({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.srcChainKey] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.dstChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/bridge/useBridgeAllowance.ts

@@ -1,49 +1,49 @@
 import { useQuery, type UseQueryResult } from '@tanstack/react-query';
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { SpokeProvider, CreateBridgeIntentParams } from '@sodax/sdk';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { CreateBridgeIntentParams, GetWalletProviderType, SpokeChainKey } from '@sodax/sdk';
+import type { ReadHookParams } from '../shared/types.js';
 
-/**
- * Hook for checking token allowance for bridge operations.
- *
- * This hook verifies if the user has approved enough tokens for a specific bridge action.
- * It automatically queries and tracks the allowance status.
- *
- * @param {BridgeParams} params - The parameters for the bridge to check allowance for.
- * @param {SpokeProvider} spokeProvider - The spoke provider to use for allowance checks
- *
- * @returns {UseQueryResult<boolean, Error>} A React Query result containing:
- *   - data: Boolean indicating if allowance is sufficient
- *   - isLoading: Loading state indicator
- *   - error: Any error that occurred during the check
- *
- * @example
- * ```typescript
- * const { data: hasAllowed, isLoading } = useBridgeAllowance(params, spokeProvider);
- * ```
- */
-export function useBridgeAllowance(
-  params: CreateBridgeIntentParams | undefined,
-  spokeProvider: SpokeProvider | undefined,
-): UseQueryResult<boolean, Error> {
+export type UseBridgeAllowanceParams<K extends SpokeChainKey> = ReadHookParams<
+  boolean,
+  {
+    payload: CreateBridgeIntentParams<K> | undefined;
+    walletProvider: GetWalletProviderType<K> | undefined;
+  }
+>;
+
+export function useBridgeAllowance<K extends SpokeChainKey>({
+  params,
+  queryOptions,
+}: UseBridgeAllowanceParams<K> = {}): UseQueryResult<boolean, Error> {
   const { sodax } = useSodaxContext();
+  const payload = params?.payload;
+  const walletProvider = params?.walletProvider;
 
-  return useQuery({
-    queryKey: ['bridge-allowance', params],
+  return useQuery<boolean, Error>({
+    // Extract the (chain, owner, token, amount) tuple that actually scopes the allowance —
+    // raw-object keys break per Rule 4 (bigints) and churn on every render.
+    queryKey: [
+      'bridge',
+      'allowance',
+      payload?.srcChainKey,
+      payload?.srcAddress,
+      payload?.srcToken,
+      payload?.amount?.toString(),
+    ],
     queryFn: async () => {
-      if (!spokeProvider || !params) {
+      if (!payload || !walletProvider) {
         return false;
       }
-
-      const allowance = await sodax.bridge.isAllowanceValid({
-        params,
-        spokeProvider,
+      const result = await sodax.bridge.isAllowanceValid({
+        params: payload,
+        raw: false,
+        walletProvider,
       });
-
-      if (allowance.ok) {
-        return allowance.value;
-      }
-      return false;
+      return result.ok ? result.value : false;
     },
-    enabled: !!spokeProvider && !!params,
+    enabled: !!payload && !!walletProvider,
+    refetchInterval: 2000,
+    gcTime: 0,
+    ...queryOptions,
   });
 }