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

package/src/hooks/dex/useSupplyLiquidity.ts

@@ -1,91 +1,96 @@
-import { useMutation, useQueryClient, type UseMutationResult } from '@tanstack/react-query';
-import type { HubTxHash, SpokeTxHash, SpokeProvider } from '@sodax/sdk';
-import { useSodaxContext } from '../shared/useSodaxContext';
-import type { UseCreateSupplyLiquidityParamsResult } from './useCreateSupplyLiquidityParams';
+// packages/dapp-kit/src/hooks/dex/useSupplyLiquidity.ts
+import type {
+  ClIncreaseLiquidityParams,
+  ClSupplyParams,
+  GetWalletProviderType,
+  SpokeChainKey,
+  TxHashPair,
+} from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { UseCreateSupplyLiquidityParamsResult } from './useCreateSupplyLiquidityParams.js';
+import type { MutationHookParams } from '../shared/types.js';
+import { useSafeMutation, type SafeUseMutationResult } from '../shared/useSafeMutation.js';
+import { unwrapResult } from '../shared/unwrapResult.js';
 
-export type UseSupplyLiquidityProps = {
-  params: UseCreateSupplyLiquidityParamsResult;
-  spokeProvider: SpokeProvider;
+/**
+ * Mutation variables for {@link useSupplyLiquidity}. Generic over `K extends SpokeChainKey`
+ * (defaults to the full union). The hook fans out internally to either
+ * `clService.increaseLiquidity` (when `params.tokenId` + `params.isValidPosition` are present) or
+ * `clService.supplyLiquidity` (mint a new position).
+ */
+export type UseSupplyLiquidityVars<K extends SpokeChainKey = SpokeChainKey> = {
+  params: UseCreateSupplyLiquidityParamsResult & { srcChainKey: K; srcAddress: string };
+  walletProvider: GetWalletProviderType<K>;
+  /** Optional relay timeout in ms (default 60_000) */
+  timeout?: number;
 };
 
 /**
- * Hook for supplying liquidity to a pool.
- *
- * This hook handles both minting new positions and increasing liquidity in existing positions.
- * It applies slippage tolerance before calculating liquidity and handles the complete transaction flow.
- *
- * @param {SpokeProvider} spokeProvider - The spoke provider for the chain
- * @returns {UseMutationResult<void, Error, SupplyLiquidityParams>} Mutation result with supply function
- *
- * @example
- * ```typescript
- * const { mutateAsync: supplyLiquidity, isPending, error } = useSupplyLiquidity(spokeProvider);
+ * React hook for supplying liquidity to a concentrated-liquidity pool. If the input vars include a
+ * valid `tokenId` for an existing position, the hook calls `increaseLiquidity`; otherwise it mints
+ * a new position via `supplyLiquidity`.
  *
- * await supplyLiquidity({
- *   poolData,
- *   poolKey,
- *   minPrice: '100',
- *   maxPrice: '200',
- *   liquidityToken0Amount: '10',
- *   liquidityToken1Amount: '20',
- *   slippageTolerance: '0.5',
- * });
- * ```
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
  */
-export function useSupplyLiquidity(): UseMutationResult<[SpokeTxHash, HubTxHash], Error, UseSupplyLiquidityProps> {
+export function useSupplyLiquidity<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseSupplyLiquidityVars<K>> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseSupplyLiquidityVars<K>
+> {
   const { sodax } = useSodaxContext();
   const queryClient = useQueryClient();
 
-  return useMutation({
-    mutationFn: async ({ params, spokeProvider }: UseSupplyLiquidityProps) => {
-      // Check if we're increasing an existing position or minting a new one
-      if (params.tokenId && params.isValidPosition) {
-        // Increase liquidity in existing position
-        const increaseResult = await sodax.dex.clService.increaseLiquidity({
-          params: {
-            poolKey: params.poolKey,
-            tokenId: BigInt(params.tokenId),
-            tickLower: params.tickLower,
-            tickUpper: params.tickUpper,
-            liquidity: params.liquidity,
-            amount0Max: params.amount0Max,
-            amount1Max: params.amount1Max,
-            sqrtPriceX96: params.sqrtPriceX96,
-          },
-          spokeProvider,
-        });
+  return useSafeMutation<TxHashPair, Error, UseSupplyLiquidityVars<K>>({
+    mutationKey: ['dex', 'supplyLiquidity'],
+    ...mutationOptions,
+    mutationFn: async ({ params, walletProvider, timeout }) => {
+      const sharedParams = {
+        srcChainKey: params.srcChainKey,
+        srcAddress: params.srcAddress as ClSupplyParams<K>['srcAddress'],
+        poolKey: params.poolKey,
+        tickLower: params.tickLower,
+        tickUpper: params.tickUpper,
+        liquidity: params.liquidity,
+        amount0Max: params.amount0Max,
+        amount1Max: params.amount1Max,
+        sqrtPriceX96: params.sqrtPriceX96,
+      } satisfies ClSupplyParams<K>;
 
-        if (!increaseResult.ok) {
-          throw new Error(`Increase liquidity failed: ${increaseResult.error?.code || 'Unknown error'}`);
-        }
-
-        return increaseResult.value;
+      if (params.tokenId !== undefined && params.isValidPosition) {
+        const increaseParams: ClIncreaseLiquidityParams<K> = {
+          ...sharedParams,
+          tokenId: typeof params.tokenId === 'bigint' ? params.tokenId : BigInt(params.tokenId),
+        };
+        return unwrapResult(
+          await sodax.dex.clService.increaseLiquidity({ params: increaseParams, raw: false, walletProvider, timeout }),
+        );
       }
 
-      // Mint new position
-      const supplyResult = await sodax.dex.clService.supplyLiquidity({
-        params: {
-          poolKey: params.poolKey,
-          tickLower: params.tickLower,
-          tickUpper: params.tickUpper,
-          liquidity: params.liquidity,
-          amount0Max: params.amount0Max,
-          amount1Max: params.amount1Max,
-          sqrtPriceX96: params.sqrtPriceX96,
-        },
-        spokeProvider,
-      });
-
-      if (!supplyResult.ok) {
-        throw new Error(`Supply liquidity failed: ${supplyResult.error?.code || 'Unknown error'}`);
-      }
-
-      return supplyResult.value;
+      return unwrapResult(
+        await sodax.dex.clService.supplyLiquidity({ params: sharedParams, raw: false, walletProvider, timeout }),
+      );
     },
-    onSuccess: () => {
-      // Invalidate relevant queries
-      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances'] });
-      queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo'] });
+    onSuccess: async (data, vars, ctx) => {
+      const { params } = vars;
+      // Increase-liquidity branch knows the affected position — scope to it. Mint-new-position
+      // branch creates a fresh tokenId that's only known after the tx, so a bare invalidation is
+      // the right fallback (refetches all positions, including the new one once it lands).
+      if (params.tokenId !== undefined && params.isValidPosition) {
+        // `usePositionInfo` keys by string tokenId — coerce here to match its shape regardless of
+        // whether the caller passed bigint or string.
+        const tokenIdStr = String(params.tokenId);
+        queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo', tokenIdStr, params.poolKey] });
+      } else {
+        queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo'] });
+      }
+      queryClient.invalidateQueries({ queryKey: ['dex', 'poolData', params.poolKey] });
+      queryClient.invalidateQueries({ queryKey: ['dex', 'poolBalances', params.srcChainKey, params.srcAddress] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', params.srcChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
     },
   });
 }

package/src/hooks/index.ts

@@ -1,10 +1,12 @@
-export * from './shared';
-export * from './provider';
-export * from './bitcoin';
-export * from './mm';
-export * from './swap';
-export * from './backend';
-export * from './bridge';
-export * from './staking';
-export * from './migrate';
-export * from './dex';
+export * from './shared/index.js';
+export * from './provider/index.js';
+export * from './bitcoin/index.js';
+export * from './mm/index.js';
+export * from './swap/index.js';
+export * from './backend/index.js';
+export * from './bridge/index.js';
+export * from './staking/index.js';
+export * from './partner/index.js';
+export * from './recovery/index.js';
+export * from './migrate/index.js';
+export * from './dex/index.js';

package/src/hooks/migrate/index.ts

@@ -1,4 +1,13 @@
-export { useMigrate } from './useMigrate';
-export { useMigrationAllowance } from './useMigrationAllowance';
-export { useMigrationApprove } from './useMigrationApprove';
-export * from './types';
+export { useMigrateIcxToSoda, type UseMigrateIcxToSodaVars } from './useMigrateIcxToSoda.js';
+export {
+  useRevertMigrateSodaToIcx,
+  type UseRevertMigrateSodaToIcxVars,
+} from './useRevertMigrateSodaToIcx.js';
+export { useMigratebnUSD, type UseMigratebnUSDVars } from './useMigratebnUSD.js';
+export { useMigrateBaln, type UseMigrateBalnVars } from './useMigrateBaln.js';
+export { useMigrationApprove, type UseMigrationApproveVars } from './useMigrationApprove.js';
+export {
+  useMigrationAllowance,
+  type UseMigrationAllowanceInputs,
+  type UseMigrationAllowanceParams,
+} from './useMigrationAllowance.js';

package/src/hooks/migrate/useMigrateBaln.ts

@@ -0,0 +1,42 @@
+// packages/dapp-kit/src/hooks/migrate/useMigrateBaln.ts
+import type { BalnMigrateAction, TxHashPair } from '@sodax/sdk';
+import { ChainKeys } 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 UseMigrateBalnVars = Omit<BalnMigrateAction<false>, 'raw'>;
+
+/**
+ * React hook for migrating BALN → SODA on the Sonic hub. Source chain is always Icon. Supports
+ * lockup periods (0–24 months) which multiply the SODA reward (0.5x–1.5x).
+ *
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
+ */
+export function useMigrateBaln({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseMigrateBalnVars> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseMigrateBalnVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxHashPair, Error, UseMigrateBalnVars>({
+    mutationKey: ['migrate', 'baln'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.migration.migrateBaln({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['migrate', 'allowance'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', ChainKeys.ICON_MAINNET] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', ChainKeys.SONIC_MAINNET] });
+      // BALN with stake=true affects staking info too; cheap broad invalidation.
+      queryClient.invalidateQueries({ queryKey: ['staking', 'info'] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/migrate/useMigrateIcxToSoda.ts

@@ -0,0 +1,44 @@
+// packages/dapp-kit/src/hooks/migrate/useMigrateIcxToSoda.ts
+import type { IcxMigrateAction, TxHashPair } from '@sodax/sdk';
+import { ChainKeys } 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 useMigrateIcxToSoda}. Wraps `IcxMigrateAction<false>` with `raw`
+ * stripped — the hook always submits non-raw and unwraps the SDK Result.
+ */
+export type UseMigrateIcxToSodaVars = Omit<IcxMigrateAction<false>, 'raw'>;
+
+/**
+ * React hook for migrating ICX/wICX → SODA on the Sonic hub. Forward-only direction; for the
+ * reverse (SODA → ICX) use {@link useRevertMigrateSodaToIcx}.
+ *
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
+ */
+export function useMigrateIcxToSoda({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseMigrateIcxToSodaVars> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseMigrateIcxToSodaVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxHashPair, Error, UseMigrateIcxToSodaVars>({
+    mutationKey: ['migrate', 'icxToSoda'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.migration.migrateIcxToSoda({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['migrate', 'allowance'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.srcChainKey] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', ChainKeys.SONIC_MAINNET] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/migrate/useMigratebnUSD.ts

@@ -0,0 +1,47 @@
+// packages/dapp-kit/src/hooks/migrate/useMigratebnUSD.ts
+import type { SpokeChainKey, TxHashPair, UnifiedBnUSDMigrateAction } 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 useMigratebnUSD}. Generic over `K extends SpokeChainKey` (defaults
+ * to the full union). Bidirectional — handles both legacy → new and new → legacy bnUSD migration
+ * via the same SDK call; the SDK detects direction from the token addresses.
+ */
+export type UseMigratebnUSDVars<K extends SpokeChainKey = SpokeChainKey> = Omit<
+  UnifiedBnUSDMigrateAction<K, false>,
+  'raw'
+>;
+
+/**
+ * React hook for migrating bnUSD between legacy and new formats across spoke chains via Sonic.
+ *
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
+ */
+export function useMigratebnUSD<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseMigratebnUSDVars<K>> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseMigratebnUSDVars<K>
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxHashPair, Error, UseMigratebnUSDVars<K>>({
+    mutationKey: ['migrate', 'bnUSD'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.migration.migratebnUSD({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      const { params } = vars;
+      queryClient.invalidateQueries({ queryKey: ['migrate', 'allowance'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', params.srcChainKey] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', params.dstChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/migrate/useMigrationAllowance.ts

@@ -0,0 +1,76 @@
+// packages/dapp-kit/src/hooks/migrate/useMigrationAllowance.ts
+import type {
+  BalnMigrateParams,
+  IcxCreateRevertMigrationParams,
+  IcxMigrateParams,
+  MigrationAction,
+  SpokeChainKey,
+  UnifiedBnUSDMigrateParams,
+} from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
+
+/**
+ * Domain inputs for {@link useMigrationAllowance}. `params` is the underlying migration params
+ * (NOT the action wrapper — no `walletProvider`/`raw`); `action` is the `'migrate' | 'revert'`
+ * discriminator the SDK uses to pick the right allowance check path.
+ *
+ * For ICX forward migration (`migrate`, params={IcxMigrateParams}) and BALN migration the SDK
+ * always returns `true` (Icon has no ERC-20-style allowance) — but the hook still works there
+ * for code-uniformity at the call site.
+ */
+export type UseMigrationAllowanceInputs<K extends SpokeChainKey = SpokeChainKey> = {
+  params:
+    | IcxMigrateParams
+    | IcxCreateRevertMigrationParams
+    | UnifiedBnUSDMigrateParams<K>
+    | BalnMigrateParams
+    | undefined;
+  action: MigrationAction | undefined;
+};
+
+export type UseMigrationAllowanceParams<K extends SpokeChainKey = SpokeChainKey> = ReadHookParams<
+  boolean,
+  UseMigrationAllowanceInputs<K>
+>;
+
+const REFETCH_INTERVAL_MS = 2_000;
+
+/**
+ * React hook to check if migration spending is approved.
+ *
+ * Returns `false` when params are missing (so the call site can disable the action button).
+ * Hook lifecycle (`enabled`, `queryKey`, `queryFn`) is owned internally; consumers can override
+ * other React Query knobs via `queryOptions`.
+ */
+export function useMigrationAllowance<K extends SpokeChainKey = SpokeChainKey>({
+  params,
+  queryOptions,
+}: UseMigrationAllowanceParams<K> = {}): UseQueryResult<boolean, Error> {
+  const { sodax } = useSodaxContext();
+  const migrationParams = params?.params;
+  const action = params?.action;
+
+  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: [
+      'migrate',
+      'allowance',
+      action,
+      migrationParams?.srcChainKey,
+      migrationParams?.srcAddress,
+      migrationParams && 'srcbnUSD' in migrationParams ? migrationParams.srcbnUSD : undefined,
+      migrationParams?.amount?.toString(),
+    ],
+    queryFn: async () => {
+      if (!migrationParams || !action) return false;
+      const result = await sodax.migration.isAllowanceValid<K>(migrationParams, action);
+      return result.ok ? result.value : false;
+    },
+    enabled: !!migrationParams && !!action,
+    refetchInterval: REFETCH_INTERVAL_MS,
+    ...queryOptions,
+  });
+}

package/src/hooks/migrate/useMigrationApprove.ts

@@ -0,0 +1,66 @@
+// packages/dapp-kit/src/hooks/migrate/useMigrationApprove.ts
+import type {
+  IcxRevertMigrationAction,
+  MigrationAction,
+  SpokeChainKey,
+  TxReturnType,
+  UnifiedBnUSDMigrateAction,
+} 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 useMigrationApprove}. The SDK's `approve` accepts a union of
+ * action wrappers (Icx-revert OR bnUSD bidirectional) plus a separate `'migrate' | 'revert'`
+ * discriminator. Both ride along in `TVars` here so the hook stays a pure pass-through.
+ */
+export type UseMigrationApproveVars<K extends SpokeChainKey = SpokeChainKey> = (
+  | Omit<IcxRevertMigrationAction<false>, 'raw'>
+  | Omit<UnifiedBnUSDMigrateAction<K, false>, 'raw'>
+) & { action: MigrationAction };
+
+/**
+ * React hook for approving token spending on a migration intent. Required before:
+ * - SODA → ICX revert (consumes SODA on Sonic via the user's hub router)
+ * - bnUSD migrations on EVM/Stellar source chains (consumes the source bnUSD via asset manager)
+ *
+ * NOT required for ICX → SODA forward migrations or BALN migrations (both originate on Icon
+ * which doesn't use ERC-20 allowances).
+ *
+ * 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 useMigrationApprove<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<TxReturnType<K, false>, UseMigrationApproveVars<K>> = {}): SafeUseMutationResult<
+  TxReturnType<K, false>,
+  Error,
+  UseMigrationApproveVars<K>
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxReturnType<K, false>, Error, UseMigrationApproveVars<K>>({
+    mutationKey: ['migrate', 'approve'],
+    ...mutationOptions,
+    mutationFn: async ({ action, ...actionParams }) =>
+      unwrapResult(
+        await sodax.migration.approve(
+          { ...actionParams, raw: false } as
+            | IcxRevertMigrationAction<false>
+            | UnifiedBnUSDMigrateAction<K, false>,
+          action,
+        ),
+      ),
+    onSuccess: async (data, vars, ctx) => {
+      // Broad — wipes all migrate allowance variants. The mutation can't know exactly which
+      // (action, params) tuple the consumer was reading, so refetch all and let the active
+      // queries reconcile.
+      queryClient.invalidateQueries({ queryKey: ['migrate', 'allowance'] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/migrate/useRevertMigrateSodaToIcx.ts

@@ -0,0 +1,39 @@
+// packages/dapp-kit/src/hooks/migrate/useRevertMigrateSodaToIcx.ts
+import type { IcxRevertMigrationAction, TxHashPair } from '@sodax/sdk';
+import { ChainKeys } 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 UseRevertMigrateSodaToIcxVars = Omit<IcxRevertMigrationAction<false>, 'raw'>;
+
+/**
+ * React hook for reverting SODA → ICX (the inverse of {@link useMigrateIcxToSoda}).
+ *
+ * Throws on SDK failure so React Query's native error model engages (`isError`, `error`,
+ * `onError`, `retry`). Returns the unwrapped `TxHashPair` on success.
+ */
+export function useRevertMigrateSodaToIcx({
+  mutationOptions,
+}: MutationHookParams<TxHashPair, UseRevertMigrateSodaToIcxVars> = {}): SafeUseMutationResult<
+  TxHashPair,
+  Error,
+  UseRevertMigrateSodaToIcxVars
+> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<TxHashPair, Error, UseRevertMigrateSodaToIcxVars>({
+    mutationKey: ['migrate', 'revertSodaToIcx'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.migration.revertMigrateSodaToIcx({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['migrate', 'allowance'] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.srcChainKey] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', ChainKeys.ICON_MAINNET] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}

package/src/hooks/mm/index.ts

@@ -1,12 +1,14 @@
-export * from './useBorrow';
-export * from './useRepay';
-export * from './useSupply';
-export * from './useWithdraw';
-export * from './useUserReservesData';
-export * from './useReservesData';
-export * from './useMMAllowance';
-export * from './useMMApprove';
-export * from './useAToken';
-export * from './useATokensBalances';
-export * from './useReservesUsdFormat';
-export * from './useUserFormattedSummary';
+export * from './useBorrow.js';
+export * from './useRepay.js';
+export * from './useSupply.js';
+export * from './useWithdraw.js';
+export * from './useUserReservesData.js';
+export * from './useReservesData.js';
+export * from './useReservesHumanized.js';
+export * from './useReservesList.js';
+export * from './useMMAllowance.js';
+export * from './useMMApprove.js';
+export * from './useAToken.js';
+export * from './useATokensBalances.js';
+export * from './useReservesUsdFormat.js';
+export * from './useUserFormattedSummary.js';

package/src/hooks/mm/useAToken.ts

@@ -1,53 +1,35 @@
-import { isAddress } from 'viem';
-import type { XToken } from '@sodax/sdk';
-import { useQuery, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
-import { useSodaxContext } from '../shared/useSodaxContext';
+import type { Erc20Token } from '@sodax/sdk';
+import type { ChainKey } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import { type Address, isAddress } from 'viem';
+import { useSodaxContext } from '../shared/useSodaxContext.js';
+import type { ReadHookParams } from '../shared/types.js';
 
-export type UseATokenParams = {
-  aToken: string;
-  queryOptions?: UseQueryOptions<XToken, Error>;
-};
+export type ATokenData = Erc20Token & { chainKey: ChainKey };
+
+export type UseATokenParams = ReadHookParams<
+  ATokenData,
+  {
+    aToken: Address | string | undefined;
+  }
+>;
 
 /**
- * React hook to fetch and cache metadata for a given aToken address.
- *
- * Accepts an aToken address and React Query options to control query behavior.
- * Returns the aToken's ERC20-style metadata from the Sodax money market, with querying/caching
- * powered by React Query.
- *
- * @param {UseATokenParams} params - Required params object:
- *   @property {Address} aToken - The aToken contract address to query.
- *   @property {UseQueryOptions<XToken, Error>} queryOptions - React Query options to control query (e.g., staleTime, refetch, etc.).
- *
- * @returns {UseQueryResult<XToken, Error>} React Query result object:
- *   - data: XToken metadata, if available
- *   - isLoading: Boolean loading state
- *   - error: Error, if API call fails
- *
- * @example
- * const { data: xToken, isLoading, error } = useAToken({ aToken: aTokenAddress, queryOptions: {} });
- * if (xToken) {
- *   console.log(xToken.symbol);
- * }
+ * React hook to fetch ERC-20 metadata for a given aToken address on the hub chain.
+ * Returns `Erc20Token` (`name`, `symbol`, `decimals`, `address`) augmented with the hub
+ * `chainKey`. Note: the returned shape is a subset of `XToken` — `hubAsset` and `vault` fields
+ * must be resolved separately if needed.
  */
-export function useAToken({ aToken, queryOptions }: UseATokenParams): UseQueryResult<XToken, Error> {
+export function useAToken({ params, queryOptions }: UseATokenParams = {}): UseQueryResult<ATokenData, Error> {
   const { sodax } = useSodaxContext();
-  const defaultQueryOptions = {
-    queryKey: ['mm', 'aToken', aToken],
-    enabled: !!aToken,
-  };
-  queryOptions = {
-    ...defaultQueryOptions,
-    ...queryOptions, // override default query options if provided
-  };
+  const aToken = params?.aToken;
 
   return useQuery({
-    ...queryOptions,
+    queryKey: ['mm', 'aToken', aToken],
     queryFn: async () => {
       if (!aToken) {
-        throw new Error('aToken address or hub provider is not defined');
+        throw new Error('aToken address is required');
       }
-
       if (!isAddress(aToken)) {
         throw new Error('aToken address is not a valid address');
       }
@@ -55,8 +37,10 @@ export function useAToken({ aToken, queryOptions }: UseATokenParams): UseQueryRe
       const aTokenData = await sodax.moneyMarket.data.getATokenData(aToken);
       return {
         ...aTokenData,
-        xChainId: sodax.hubProvider.chainConfig.chain.id,
+        chainKey: sodax.hubProvider.chainConfig.chain.key,
       };
     },
+    enabled: !!aToken && isAddress(aToken ?? ''),
+    ...queryOptions,
   });
 }