docs

Author: mgrabina

src/components/transactions/Swap/README.md

@@ -0,0 +1,89 @@
+## Swap module
+
+![Swap module architecture](./docs/swap-modal-architecture.png)
+
+### Goals
+- **Consistent UI/UX** across all swap-related modals
+- **Shared logic, no duplication** via a common base content and shared helpers
+- **Multi‑provider** architecture (CoW Protocol, ParaSwap; easy to extend)
+- **Composable and customizable** components
+
+### High‑level flow
+1. A top‑level modal (`modals/*Modal.tsx`) renders a corresponding content component in `modals/request/*ModalContent.tsx`.
+2. Each `*ModalContent` composes `BaseSwapModalContent`, which wires data, inputs, warnings, details, and actions.
+3. Provider selection is automatic via `helpers/shared/provider.helpers.ts` (`getSwitchProvider`).
+4. Quotes are fetched with `hooks/useSwapQuote` and refreshed periodically; flash‑loan and health‑factor logic is handled by `hooks/useFlowSelector`.
+5. The UI is composed from shared inputs, pre/post warnings, per‑flow details, and provider‑specific actions.
+
+### Directory overview
+- `modals/`
+  - Entry points displayed to users: `SwapModal.tsx`, `CollateralSwapModal.tsx`, `DebtSwapModal.tsx`, etc.
+  - `modals/request/` contains `*ModalContent.tsx` for each flow and a `BaseSwapModalContent` used by all.
+  - `modals/result/` shows success/receipt views.
+
+- `inputs/`
+  - `SwapInputs.tsx` orchestrates order inputs; `MarketOrderInputs.tsx` and `LimitOrderInputs.tsx` are the two modes.
+  - `inputs/shared/` and `inputs/primitives/` host reusable input UI.
+
+- `warnings/`
+  - Pre‑ and post‑input warnings: `SwapPreInputWarnings.tsx`, `SwapPostInputWarnings.tsx`.
+  - Flow‑ and rule‑specific implementations live under `warnings/preInputs/` and `warnings/postInputs/`.
+
+- `details/`
+  - Transaction overview blocks: `SwapDetails.tsx`, plus flow variants like `CollateralSwapDetails.tsx`, `DebtSwapDetails.tsx`, `RepayWithCollateralDetails.tsx`, `WithdrawAndSwapDetails.tsx`.
+  - Provider‑specific cost breakdowns, e.g. `CowCostsDetails.tsx`.
+
+- `actions/`
+  - The submit/CTA area and transaction execution.
+  - Flow containers: `SwapActions`, `CollateralSwapActions`, `DebtSwapActions`, `RepayWithCollateralActions`, `WithdrawAndSwapActions`.
+  - Provider adapters implement the same surface per flow, e.g. `SwapActionsViaCoW.tsx`, `SwapActionsViaParaswap.tsx`, and their flow equivalents under each subfolder.
+  - `approval/useSwapTokenApproval.ts` handles allowance flows when needed.
+
+- `hooks/`
+  - `useSwapQuote` retrieves and normalizes quotes (CoW/ParaSwap) and writes into `SwapState`.
+  - `useFlowSelector` computes health‑factor effects and decides when to use flash‑loans.
+  - Other utilities: `useSwapOrderAmounts`, `useSwapGasEstimation`, `useSlippageSelector`, `useMaxNativeAmount`, `useProtocolReserves`, `useUserContext`.
+
+- `helpers/`
+  - `shared/` contains provider‑agnostic logic (provider selection, formatting, misc) and `gasEstimation.helpers.ts`.
+  - `cow/` and `paraswap/` contain provider integrations (rates, order helpers, misc).
+
+- `errors/`
+  - UI components and mapping/helpers for error presentation; organized by provider and shared concerns.
+
+- `constants/`
+  - Provider and feature flags: `cow.constants.ts`, `paraswap.constants.ts`, `limitOrders.constants.ts`, `shared.constants.ts`.
+
+- `types/`
+  - Shared domain types: params, state, tokens, quotes, and re‑exports.
+
+- `shared/`
+  - Small UI pieces reused across modals (e.g., `OrderTypeSelector`, `SwapModalTitle`).
+
+- `analytics/`
+  - Analytics constants and hooks to track swap interactions.
+
+- `backup/`
+  - Legacy/previous implementation kept for reference during the migration to the new modular structure.
+
+### Extending to a new provider
+1. Add provider constants in `constants/` and integration helpers under `helpers/<provider>/`.
+2. Plug the provider into `helpers/shared/provider.helpers.ts` so it can be selected.
+3. Implement `*ActionsVia<Provider>.tsx` for each supported flow under `actions/`.
+4. Optionally add provider‑specific details/warnings and wire them in the `*Details.tsx`/warnings where appropriate.
+
+### Data model
+- `types/state.types.ts` defines the authoritative `SwapState` used across the module.
+- `types/params.types.ts` carries immutable parameters from the modal entry.
+- Quotes unify to a `quote.types.ts` shape so the UI remains provider‑agnostic.
+
+### Notes
+- `useSwapQuote` refreshes quotes every 30s by default, paused during action execution.
+- Some flows invert the quote route (e.g., `DebtSwap`, `RepayWithCollateral`); this is encapsulated in `useSwapQuote` and consumers stay agnostic.
+
+### Core types (documented)
+- State: see `types/state.types.ts` (`SwapState`, `TokensSwapState`, `ProtocolSwapState`).
+- Params: see `types/params.types.ts` (`SwapParams`).
+- Tokens and quotes: see `types/tokens.types.ts`, `types/quote.types.ts`, and shared enums in `types/shared.types.ts`.
+
+

src/components/transactions/Swap/actions/CollateralSwap/CollateralSwapActionsViaCoWAdapters.tsx

@@ -20,7 +20,6 @@ import { ExpiryToSecondsMap, SwapParams, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
 export const CollateralSwapActionsViaCowAdapters = ({
-  params,
   state,
   setState,
   trackingHandlers,
@@ -190,7 +189,6 @@ export const CollateralSwapActionsViaCowAdapters = ({
       const result = await tradingSdk.postLimitOrder(limitOrder, orderPostParams.swapSettings);
 
       trackingHandlers.trackSwap();
-      params.invalidateAppState(); // todo remove, running when finished
       setMainTxState({
         loading: false,
         success: true,

src/components/transactions/Swap/actions/CollateralSwap/CollateralSwapActionsViaParaswapAdapters.tsx

@@ -191,8 +191,8 @@ export const CollateralSwapActionsViaParaswapAdapters = ({
           chainId: state.chainId,
         }
       );
-      trackingHandlers.trackSwap(); // TODO: check this happening in all actions
-      params.invalidateAppState(); // TODO: check this happening in all actions
+      trackingHandlers.trackSwap();
+      params.invalidateAppState();
       setMainTxState({
         txHash: response.hash,
         loading: false,

src/components/transactions/Swap/actions/DebtSwap/DebtSwapActionsViaCoW.tsx

@@ -20,8 +20,16 @@ import { useSwapGasEstimation } from '../../hooks/useSwapGasEstimation';
 import { ExpiryToSecondsMap, isProtocolSwapState, SwapParams, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
+/**
+ * Debt swap via CoW Protocol Flashloan Adapters.
+ *
+ * Flow summary:
+ * 1) Approve delegation on the destination variable debt token (permit supported)
+ * 2) Compute flashloan fee and sell amount; we temporarily borrow to close existing debt
+ * 3) Create a LIMIT order INVERTED relative to the UI: new debt asset -> old debt asset
+ * 4) Post order with adapter swap settings; adapter executes the repay + reborrow atomically
+ */
 export const DebtSwapActionsViaCoW = ({
-  params,
   state,
   setState,
   trackingHandlers,
@@ -198,7 +206,6 @@ export const DebtSwapActionsViaCoW = ({
       const result = await tradingSdk.postLimitOrder(limitOrder, orderPostParams.swapSettings);
 
       trackingHandlers.trackSwap();
-      params.invalidateAppState(); // move to sucess state
       setMainTxState({
         loading: false,
         success: true,

src/components/transactions/Swap/actions/DebtSwap/DebtSwapActionsViaParaswap.tsx

@@ -1,6 +1,5 @@
 import { valueToBigNumber } from '@aave/math-utils';
 import { Trans } from '@lingui/macro';
-import { useQueryClient } from '@tanstack/react-query';
 import { parseUnits } from 'ethers/lib/utils';
 import { Dispatch } from 'react';
 import { TxActionsWrapper } from 'src/components/transactions/TxActionsWrapper';
@@ -9,7 +8,6 @@ import { useModalContext } from 'src/hooks/useModal';
 import { useWeb3Context } from 'src/libs/hooks/useWeb3Context';
 import { useRootStore } from 'src/store/root';
 import { getErrorTextFromError, TxAction } from 'src/ui-config/errorMapping';
-import { queryKeysFactory } from 'src/ui-config/queries';
 import { useShallow } from 'zustand/shallow';
 
 import { TrackAnalyticsHandlers } from '../../analytics/useTrackAnalytics';
@@ -18,9 +16,20 @@ import { useSwapGasEstimation } from '../../hooks/useSwapGasEstimation';
 import { isParaswapRates, ProtocolSwapParams, ProtocolSwapState, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
+/**
+ * Debt swap via ParaSwap Adapter.
+ *
+ * Flow summary:
+ * 1) Approve delegation on the destination variable debt token to the adapter
+ * 2) Build a ParaSwap route INVERTED relative to the UI: new debt asset -> old debt asset
+ *    - Inversion is required because we're acquiring new debt to repay old debt
+ * 3) Call the Debt Switch adapter with swap calldata and permit/delegation signature
+ */
 export const DebtSwapActionsViaParaswap = ({
   state,
+  params,
   setState,
+  trackingHandlers,
 }: {
   params: ProtocolSwapParams;
   state: ProtocolSwapState;
@@ -38,7 +47,6 @@ export const DebtSwapActionsViaParaswap = ({
   const { approvalTxState, mainTxState, loadingTxns, setMainTxState, setTxError } =
     useModalContext();
   const { sendTx } = useWeb3Context();
-  const queryClient = useQueryClient();
 
   // TODO: CHECK LIMIT ORDERS BUY ORDERS
 
@@ -157,8 +165,8 @@ export const DebtSwapActionsViaParaswap = ({
           .toString(),
       });
 
-      queryClient.invalidateQueries({ queryKey: queryKeysFactory.pool });
-      queryClient.invalidateQueries({ queryKey: queryKeysFactory.gho });
+      params.invalidateAppState();
+      trackingHandlers.trackSwap();
     } catch (error) {
       console.error('error', error);
       const parsedError = getErrorTextFromError(error, TxAction.GAS_ESTIMATION, false);

src/components/transactions/Swap/actions/RepayWithCollateral/RepayWithCollateralActionsViaCoW.tsx

@@ -19,8 +19,18 @@ import { useSwapGasEstimation } from '../../hooks/useSwapGasEstimation';
 import { ExpiryToSecondsMap, SwapParams, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
+/**
+ * Repay-with-collateral via CoW Protocol Flashloan Adapters.
+ *
+ * Flow summary:
+ * 1) Approve collateral aToken (permit supported) to the CoW flashloan adapter
+ * 2) Compute flashloan fee and sell amount to sign
+ * 3) Create a LIMIT order INVERTED relative to the UI: collateral -> debt asset
+ *    - The order kind depends on processed side; inversion is required because
+ *      we swap the available collateral to acquire the debt asset to repay
+ * 4) Post order with adapter-provided swap settings; adapter orchestrates repay
+ */
 export const RepayWithCollateralActionsViaCoW = ({
-  params,
   state,
   setState,
   trackingHandlers,
@@ -191,7 +201,6 @@ export const RepayWithCollateralActionsViaCoW = ({
       const result = await tradingSdk.postLimitOrder(limitOrder, orderPostParams.swapSettings);
 
       trackingHandlers.trackSwap();
-      params.invalidateAppState();
       setMainTxState({
         loading: false,
         success: true,

src/components/transactions/Swap/actions/RepayWithCollateral/RepayWithCollateralActionsViaParaswap.tsx

@@ -16,6 +16,16 @@ import { useSwapGasEstimation } from '../../hooks/useSwapGasEstimation';
 import { isParaswapRates, ProtocolSwapParams, ProtocolSwapState, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
+/**
+ * Repay-with-collateral via ParaSwap Adapter.
+ *
+ * Flow summary:
+ * 1) Approve aToken (or use permit) to the RepayWithCollateral adapter
+ * 2) Build a ParaSwap route INVERTED relative to the UI: collateral aToken -> debt token
+ *    - We invert because the protocol action consumes collateral to acquire the debt asset
+ * 3) Compute repay amounts with slippage; detect `repayAllDebt` when balance covers max with margin
+ * 4) Call adapter with swap calldata + optional permit to execute repay and residual handling
+ */
 export const RepayWithCollateralActionsViaParaswap = ({
   params,
   state,
@@ -46,6 +56,7 @@ export const RepayWithCollateralActionsViaParaswap = ({
         -state.destinationToken.decimals
       ).toString(),
       0
+      // Adds margin to account future incremental so better ux
     ),
     state.destinationToken.decimals
   );
@@ -57,8 +68,7 @@ export const RepayWithCollateralActionsViaParaswap = ({
       token: state.destinationToken.addressToSwap, // aToken
       symbol: state.destinationToken.symbol,
       decimals: state.destinationToken.decimals,
-      // amount: normalizeBN(state.outputAmount, -state.destinationToken.decimals).toString(), // TODO: need to add a margin to account time for better ux?
-      amount: collateralToRepayAmountToApprove.toString(), // TODO: need to add a margin to account time for better ux?
+      amount: collateralToRepayAmountToApprove.toString(),
       spender: currentMarketData.addresses.REPAY_WITH_COLLATERAL_ADAPTER,
       setState,
     });

src/components/transactions/Swap/actions/SwapActions/SwapActionsViaCoW.tsx

@@ -33,6 +33,20 @@ import { useSwapGasEstimation } from '../../hooks/useSwapGasEstimation';
 import { isCowProtocolRates, OrderType, SwapParams, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
+/**
+ * Asset swap via CoW Protocol (Limit/Market orders).
+ *
+ * Process:
+ * 1) Ensure token approval (with permit when possible) for the CoW Relayer. Handles smart contract wallets and native token flows.
+ * 2) For tokens requiring approval, attempts onchain approval and reacts to possible failures or pending states.
+ * 3) For ERC-20s supporting permit, attempts signature path unless already approved.
+ * 4) Handles both normal EOA users and smart contract wallets (e.g. Gnosis Safe) with pre-sign or off-chain signatures as needed.
+ * 5) Posts order to the CoW API (off-chain) or submits on-chain pre-sign transaction, depending on user/wallet.
+ * 6) Tracks tx/analytics and updates transaction state accurately for UI.
+ *
+ * Automatically accounts for amount normalization, possible token decimal mismatches,
+ * error states in approvals or post order flow, and UI feedback for each path.
+ */
 export const SwapActionsViaCoW = ({
   params,
   state,
@@ -78,9 +92,6 @@ export const SwapActionsViaCoW = ({
 
   const slippageInPercent = state.slippage;
 
-  // TODO: decide amount to use
-  // const sellAmountAccountingCosts = sellAmountWithCostsIncluded(state);
-  // const buyAmountAccountingCosts = buyAmountWithCostsIncluded(state);
   const sellAmountAccountingCosts = state.sellAmountBigInt;
   const buyAmountAccountingCosts = state.buyAmountBigInt;
 
@@ -329,7 +340,6 @@ export const SwapActionsViaCoW = ({
     }
 
     trackingHandlers.trackSwap();
-    params.invalidateAppState();
   };
 
   return (

src/components/transactions/Swap/actions/SwapActions/SwapActionsViaParaswap.tsx

@@ -1,20 +1,22 @@
 import { Trans } from '@lingui/macro';
-import { useQueryClient } from '@tanstack/react-query';
 import { Dispatch, useEffect } from 'react';
 import { TxActionsWrapper } from 'src/components/transactions/TxActionsWrapper';
 import { useParaswapSellTxParams } from 'src/hooks/paraswap/useParaswapRates';
 import { useModalContext } from 'src/hooks/useModal';
 import { useWeb3Context } from 'src/libs/hooks/useWeb3Context';
 import { useRootStore } from 'src/store/root';
 import { getErrorTextFromError, TxAction } from 'src/ui-config/errorMapping';
-import { queryKeysFactory } from 'src/ui-config/queries';
 import { useShallow } from 'zustand/shallow';
 
 import { TrackAnalyticsHandlers } from '../../analytics/useTrackAnalytics';
 import { useSwapGasEstimation } from '../../hooks/useSwapGasEstimation';
 import { isParaswapRates, SwapParams, SwapState } from '../../types';
 import { useSwapTokenApproval } from '../approval/useSwapTokenApproval';
 
+/**
+ * Simple asset swap via ParaSwap Adapter (non-position flow).
+ * Prepares approval if needed and executes the route returned by useSwapQuote.
+ */
 export const SwapActionsViaParaswap = ({
   params,
   state,
@@ -26,20 +28,14 @@ export const SwapActionsViaParaswap = ({
   setState: Dispatch<Partial<SwapState>>;
   trackingHandlers: TrackAnalyticsHandlers;
 }) => {
-  const [user, estimateGasLimit, addTransaction, currentMarketData] = useRootStore(
-    useShallow((state) => [
-      state.account,
-      state.estimateGasLimit,
-      state.addTransaction,
-      state.currentMarketData,
-    ])
+  const [user, estimateGasLimit, addTransaction] = useRootStore(
+    useShallow((state) => [state.account, state.estimateGasLimit, state.addTransaction])
   );
 
   const { mainTxState, loadingTxns, setMainTxState, setTxError, approvalTxState } =
     useModalContext();
 
   const { sendTx } = useWeb3Context();
-  const queryClient = useQueryClient();
   const { mutateAsync: fetchParaswapTxParams } = useParaswapSellTxParams(state.chainId);
 
   const slippageInPercent = (Number(state.slippage) * 100).toString();
@@ -102,9 +98,9 @@ export const SwapActionsViaParaswap = ({
             loading: false,
             success: true,
           });
-          queryClient.invalidateQueries({
-            queryKey: queryKeysFactory.poolTokens(user, currentMarketData),
-          });
+
+          params.invalidateAppState();
+          trackingHandlers.trackSwap();
         } catch (error) {
           const parsedError = getErrorTextFromError(error, TxAction.MAIN_ACTION, false);
           setTxError(parsedError);
@@ -144,9 +140,6 @@ export const SwapActionsViaParaswap = ({
         actionsLoading: false,
       });
     }
-
-    params.invalidateAppState();
-    trackingHandlers.trackSwap();
   };
 
   // Track execution state to pause rate updates during actions