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

package/ai-exported/integration/features/auxiliary-services.md

@@ -0,0 +1,169 @@
+# Auxiliary services — `@sodax/dapp-kit`
+
+Smaller surfaces grouped together: partner fee claiming, recovery, backend queries (read-only data hooks), and shared utilities.
+
+Pair: [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md).
+
+## Partner
+
+Partner fee claiming and auto-swap preferences.
+
+```ts
+// @ai-snippets-skip
+useFetchAssetsBalances({ params, queryOptions });   // Partner asset balances
+useGetAutoSwapPreferences({ params, queryOptions });
+useIsTokenApproved({ params: { payload: FeeTokenApproveParams }, queryOptions });
+useApproveToken({ mutationOptions });
+useSetSwapPreference({ mutationOptions });
+useFeeClaimSwap({ mutationOptions });               // Claim partner fees via swap
+```
+
+`useFeeClaimSwap` returns `SafeUseMutationResult<IntentAutoSwapResult, Error, UseFeeClaimSwapVars>` — the success value is `IntentAutoSwapResult` (NOT `SwapResponse`). TVars are `Omit<PartnerFeeClaimSwapAction<HubChainKey, false>, 'raw'>`.
+
+## Recovery
+
+Withdraw stuck hub-wallet assets back to a spoke chain.
+
+```ts
+// @ai-snippets-skip
+useHubAssetBalances({ params, queryOptions });      // List assets stuck on hub
+useWithdrawHubAsset({ mutationOptions });
+```
+
+## Backend queries (read-only data)
+
+No wallet connection required.
+
+### Intent tracking
+
+```ts
+// @ai-snippets-skip
+useBackendIntentByTxHash({ params, queryOptions });   // Polls 1s once a txHash is supplied
+useBackendIntentByHash({ params, queryOptions });
+useBackendUserIntents({ params, queryOptions });      // Date-filtered user history; data is { items: IntentResponse[], total, offset, limit }
+```
+
+### Orderbook
+
+```ts
+// @ai-snippets-skip
+// `pagination` MUST be nested under `params` — top-level pagination is invalid.
+useBackendOrderbook({ params: { pagination: { offset, limit } }, queryOptions });   // staleTime 30s; no auto-refresh
+```
+
+### Money market data
+
+```ts
+// @ai-snippets-skip
+useBackendMoneyMarketPosition({ params, queryOptions });
+useBackendMoneyMarketAsset({ params, queryOptions });
+useBackendAllMoneyMarketAssets({ queryOptions });
+useBackendMoneyMarketAssetSuppliers({ params, queryOptions });
+useBackendMoneyMarketAssetBorrowers({ params, queryOptions });
+// Pagination required — without it the query is disabled.
+useBackendAllMoneyMarketBorrowers({ params: { pagination: { offset, limit } }, queryOptions });
+```
+
+### Swap submission
+
+```ts
+// @ai-snippets-skip
+useBackendSubmitSwapTx({ mutationOptions });           // Mutation
+useBackendSubmitSwapTxStatus({ params, queryOptions }); // Query — check submitted status
+```
+
+`useBackendSubmitSwapTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`:
+
+```ts
+// @ai-snippets-skip
+const { mutateAsync: submitSwapTx } = useBackendSubmitSwapTx();
+await submitSwapTx({ request: swapPayload, apiConfig: { baseURL: 'https://...' } });
+```
+
+## Shared utilities
+
+Cross-cutting hooks used by other features.
+
+```ts
+// @ai-snippets-skip
+useSodaxContext();                                  // Access the Sodax SDK instance
+useHubProvider();                                   // Hub chain (Sonic) provider
+useXBalances({ params, queryOptions });             // Cross-chain token balances
+useDeriveUserWalletAddress({ params, queryOptions }); // Hub wallet address (CREATE3)
+useGetUserHubWalletAddress({ params, queryOptions }); // Hub wallet via wallet router
+useEstimateGas({ mutationOptions });                // Gas estimation for raw tx
+useStellarTrustlineCheck({ params, queryOptions });
+useRequestTrustline({ mutationOptions });
+```
+
+### `useXBalances` shape
+
+```ts
+// @ai-snippets-skip
+type UseXBalancesParams = ReadHookParams<Record<string, bigint>, {
+  xService: IXServiceBase | undefined;       // From @sodax/wallet-sdk-react's useXService
+  xChainId: SpokeChainKey | undefined;
+  xTokens: readonly XToken[];                // Tokens to fetch balances for
+  address: string | undefined;
+}>;
+```
+
+Note: the **request-side** field is `xChainId` (kept for the cross-chain abstraction it overlays). This is distinct from the v2-renamed token-side `chainKey` — don't conflate them.
+
+Consumer must supply `xService` from `@sodax/wallet-sdk-react`:
+
+```tsx
+// @ai-snippets-skip
+import { useXService, getXChainType } from '@sodax/wallet-sdk-react';
+const xService = useXService({ xChainType: getXChainType(xChainId) });
+const { data: balances } = useXBalances({ params: { xService, xChainId, xTokens, address } });
+```
+
+### Stellar trustlines
+
+Stellar accounts that have never held an asset have no trustline — receiving will fail. Pre-flight with `useStellarTrustlineCheck`; fix with `useRequestTrustline`:
+
+```ts
+// @ai-snippets-skip — illustrative only; real types pulled into agents below.
+// useStellarTrustlineCheck takes { token, amount, chainId, walletProvider } under params.
+// `chainId` here is a `SpokeChainKey` (typed loosely so consumers can pass any chain key —
+// the hook returns `true` for non-Stellar chains, making it safe to gate on conditionally).
+const { data: hasTrustline } = useStellarTrustlineCheck({
+  params: { token, amount, chainId: ChainKeys.STELLAR_MAINNET, walletProvider },
+});
+
+// useRequestTrustline is NOT a canonical mutation hook — it takes a single positional
+// `token` arg and returns { requestTrustline, isLoading, isRequested, error, data }.
+// The `requestTrustline` callback signature is:
+//   ({ token, amount, srcChainKey, walletProvider }) => Promise<string>
+// NOTE: fields are `token` / `amount` / `srcChainKey` / `walletProvider` — NOT
+// `account` / `asset`. Pass a StellarChainKey for srcChainKey.
+const { requestTrustline, isLoading } = useRequestTrustline(token);
+if (hasTrustline === false) {
+  await requestTrustline({ token, amount, srcChainKey: ChainKeys.STELLAR_MAINNET, walletProvider });
+}
+```
+
+## Default polling intervals
+
+| Hook | Polling | Notes |
+|---|---|---|
+| `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
+| `useBackendSubmitSwapTxStatus` | varies | poll stops on `executed` / `failed` |
+| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
+| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
+| `useQuote` (swap) | 3s | refetchInterval |
+| `useStatus` (swap) | 3s | refetchInterval |
+| `useSwapAllowance` (swap) | 2s | refetchInterval |
+| `useMMAllowance` (mm) | 5s | refetchInterval; `enabled: false` for borrow/withdraw actions |
+| Reserves data (mm) | 5s | `useReservesData` / `useReservesHumanized` / user position hooks |
+| Most others | None | |
+
+All overridable via `queryOptions.refetchInterval`.
+
+## Cross-references
+
+- [`../recipes/backend-queries.md`](../recipes/backend-queries.md) — worked examples for intent tracking, orderbook, MM data.
+- [`../recipes/wallet-connectivity.md`](../recipes/wallet-connectivity.md) — `useXBalances` worked example.
+- [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md) — v1 → v2 porting.
+- [`../../../../sdk/ai-exported/integration/features/auxiliary-services.md`](../../../../sdk/ai-exported/integration/features/auxiliary-services.md) — underlying SDK auxiliary surfaces (partner, recovery, backendApi).

package/ai-exported/integration/features/bitcoin.md

@@ -0,0 +1,87 @@
+# Bitcoin (Radfi) — `@sodax/dapp-kit`
+
+Bitcoin trading via the Radfi protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
+
+Pair: [`../../migration/features/bitcoin.md`](../../migration/features/bitcoin.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// Session lifecycle
+useRadfiAuth({ mutationOptions });               // Authenticate via BIP322 signing
+useRadfiSession(walletProvider);                 // Manage full lifecycle (login, refresh, auto-refresh)
+useTradingWallet(walletAddress);                 // Synchronous: read persisted session
+
+// Balances
+useBitcoinBalance({ params: { address, rpcUrl? }, queryOptions });             // Personal wallet (default mempool.space)
+useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Radfi API
+
+// Operations
+useFundTradingWallet({ mutationOptions });
+useRadfiWithdraw({ mutationOptions });
+useExpiredUtxos({ params: { walletProvider, tradingAddress }, queryOptions }); // Polls 60s
+useRenewUtxos({ mutationOptions });
+```
+
+## Session flow
+
+Radfi requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
+
+```ts
+// @ai-snippets-skip
+const { walletAddress, isAuthed, tradingAddress, login, isLoginPending } = useRadfiSession(walletProvider);
+```
+
+Lifecycle behavior:
+- On mount: refreshes token to validate existing session
+- Every 5 min: auto-refreshes access token
+- If refresh fails: clears session, sets `isAuthed = false`
+- Session persisted in localStorage (keyed by wallet address)
+
+## Mutation TVars
+
+```ts
+// @ai-snippets-skip
+// useFundTradingWallet
+type FundTradingWalletVars = { amount: bigint; walletProvider: IBitcoinWalletProvider };
+
+// useRadfiWithdraw
+type RadfiWithdrawVars = {
+  amount: string;
+  tokenId: string;       // e.g. '0:0'
+  withdrawTo: string;    // user's personal BTC address
+  walletProvider: IBitcoinWalletProvider;
+};
+
+// useRenewUtxos
+type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvider };
+```
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+| `useRadfiAuth` | `SafeUseMutationResult<RadfiAuthResult, Error, UseRadfiAuthVars>` where `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields, NOT `RadfiSession` — the hook persists `publicKey` to localStorage internally but doesn't return it) |
+| `useFundTradingWallet` | `SafeUseMutationResult<TxId, Error, ...>` |
+| `useRadfiWithdraw` | `SafeUseMutationResult<{ txId, fee }, Error, ...>` |
+| `useRenewUtxos` | `SafeUseMutationResult<TxId, Error, ...>` |
+| `useRadfiSession` | `{ walletAddress, isAuthed, tradingAddress, login, isLoginPending }` (utility, not Query/Mutation) |
+| `useTradingWallet` | `{ tradingAddress: string \| undefined }` (synchronous from localStorage) |
+| `useBitcoinBalance` | `UseQueryResult<bigint, Error>` (BTC balance in sats; default Esplora is mempool.space, override via `rpcUrl`) |
+| `useTradingWalletBalance` | `UseQueryResult<RadfiWalletBalance, Error>` where `RadfiWalletBalance = { btcSatoshi: bigint; pendingSatoshi: bigint; externalPendingSatoshi: bigint; totalUtxos: number }` |
+| `useExpiredUtxos` | `UseQueryResult<RadfiUtxo[], Error>` where `RadfiUtxo = { _id, txid, vout, txidVout, satoshi, amount, address, isSpent, status, source, runes? }` |
+
+## Gotchas
+
+1. **Authentication required before any trading operation.** `useRadfiSession` manages this automatically — gate buttons on `isAuthed`.
+2. **Trading wallet is created during first authentication** — not a separate step.
+3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Radfi session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
+4. **PSBT signing flow for withdrawals.** Radfi server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
+5. **Session tokens are for API rate-limiting, not asset access.** Stored in localStorage keyed by wallet address. Compromise of localStorage data doesn't affect funds.
+6. **`useExpiredUtxos` polls every 60s** — set `queryOptions.refetchInterval: false` to disable while UI is hidden.
+
+## Cross-references
+
+- [`../recipes/bitcoin.md`](../recipes/bitcoin.md) — full worked examples (session, fund, withdraw, UTXO management).
+- [`../../migration/features/bitcoin.md`](../../migration/features/bitcoin.md) — v1 → v2 porting (mostly hook signature shape changes; flow stays the same).

package/ai-exported/integration/features/bridge.md

@@ -0,0 +1,91 @@
+# Bridge — `@sodax/dapp-kit`
+
+Cross-chain token transfers via the hub-and-spoke vault architecture.
+
+Pair: [`../../migration/features/bridge.md`](../../migration/features/bridge.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// Mutation
+useBridge({ mutationOptions });
+useBridgeApprove({ mutationOptions });
+
+// Queries
+// useBridgeAllowance nests payload + walletProvider under params (NOT at top level)
+useBridgeAllowance({ params: { payload: CreateBridgeIntentParams<K>, walletProvider }, queryOptions });
+useGetBridgeableAmount({ params: { from: XToken, to: XToken }, queryOptions });
+useGetBridgeableTokens({ params: { from: SpokeChainKey, to: SpokeChainKey, token: string }, queryOptions });
+```
+
+## Mutation params
+
+```ts
+// @ai-snippets-skip
+type CreateBridgeIntentParams<K extends SpokeChainKey = SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: string;
+  srcToken: string;
+  amount: bigint;
+  dstChainKey: SpokeChainKey;
+  dstToken: string;
+  recipient: string;   // non-encoded recipient address on the destination chain
+};
+
+const { mutateAsyncSafe: bridge } = useBridge();
+const result = await bridge({ params, walletProvider });
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair
+```
+
+## Query params
+
+```ts
+// @ai-snippets-skip
+// useBridgeAllowance — payload + walletProvider nested under params
+type UseBridgeAllowanceParams<K extends SpokeChainKey> = ReadHookParams<
+  boolean,
+  {
+    payload: CreateBridgeIntentParams<K> | undefined;
+    walletProvider: GetWalletProviderType<K> | undefined;
+  }
+>;
+
+// useGetBridgeableAmount — flat: pair of XToken objects
+type UseGetBridgeableAmountParams = ReadHookParams<BridgeLimit, {
+  from: XToken | undefined;
+  to: XToken | undefined;
+}>;
+// BridgeLimit = { amount: bigint; decimals: number; type: 'DEPOSIT_LIMIT' | 'WITHDRAWAL_LIMIT' }
+
+// useGetBridgeableTokens — flat: (from, to, token)
+type UseGetBridgeableTokensParams = ReadHookParams<XToken[], {
+  from: SpokeChainKey | undefined;
+  to: SpokeChainKey | undefined;
+  token: string | undefined;
+}>;
+```
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+| `useBridge` | `SafeUseMutationResult<TxHashPair, Error, ...>` (`{ srcChainTxHash, dstChainTxHash }`) |
+| `useBridgeApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, UseBridgeApproveVars<K>>` — chain-keyed receipt union (EVM/Stellar/Sui differ) |
+| `useBridgeAllowance` | `UseQueryResult<boolean, Error>` — already unwrapped; on SDK `!ok` the queryFn returns `false` (does NOT throw), so `isError` stays clean |
+| `useGetBridgeableAmount` | `UseQueryResult<BridgeLimit, Error>` (richer than v1's bare `bigint`) |
+| `useGetBridgeableTokens` | `UseQueryResult<XToken[], Error>` |
+
+## Gotchas
+
+1. **`useGetBridgeableAmount` takes XToken objects, not addresses + chain ids.** Each `XToken` carries its own `chainKey`. v1 took 4 separate args; v2 takes 2 objects.
+2. **`useGetBridgeableAmount` value is `BridgeLimit`, not a bare bigint.** Access `result.value.amount` and `result.value.decimals` for the limit + scale.
+3. **Tokens are bridgeable iff they share the same vault on the hub.** Use `useGetBridgeableTokens` to enumerate compatible destinations for a given source — passing an incompatible pair to `bridge()` rejects with `VALIDATION_FAILED`.
+4. **`bridge()` returns `TxHashPair`, not a tuple.** Destructure as `{ srcChainTxHash, dstChainTxHash }` — never `[a, b]`.
+
+## Cross-references
+
+- [`../recipes/bridge.md`](../recipes/bridge.md) — full worked example.
+- [`../../migration/features/bridge.md`](../../migration/features/bridge.md) — v1 → v2 porting.
+- [`../../../../sdk/ai-exported/integration/features/bridge.md`](../../../../sdk/ai-exported/integration/features/bridge.md) — underlying SDK bridge surface.

package/ai-exported/integration/features/dex.md

@@ -0,0 +1,152 @@
+# DEX — `@sodax/dapp-kit`
+
+Concentrated-liquidity DEX (similar to Uniswap V3). Two-step flow: deposit assets to mint pool tokens, then supply liquidity to a position.
+
+Pair: [`../../migration/features/dex.md`](../../migration/features/dex.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// Asset deposit / withdraw (spoke ↔ hub pool tokens)
+useDexDeposit({ mutationOptions });
+useDexWithdraw({ mutationOptions });
+useDexAllowance({ params: { payload: CreateAssetDepositParams<K> }, queryOptions });
+useDexApprove({ mutationOptions });
+usePoolBalances({ params, queryOptions });
+
+// Liquidity (pool tokens ↔ position)
+useSupplyLiquidity({ mutationOptions });           // Mint new or increase existing
+useDecreaseLiquidity({ mutationOptions });
+useClaimRewards({ mutationOptions });
+
+// Reads
+usePools({ queryOptions });
+usePoolData({ params, queryOptions });
+usePositionInfo({ params, queryOptions });
+useLiquidityAmounts({ params, queryOptions });
+
+// Param builders (compute derived params client-side) — these take a FLAT props object,
+// NOT a `{ params }` wrapper. They return memoized derived params that the consumer adds
+// `srcChainKey` + `srcAddress` to at the mutation call site.
+useCreateDepositParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
+useCreateWithdrawParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
+useCreateSupplyLiquidityParams({ poolData, poolKey, minPrice, maxPrice, liquidityToken0Amount, liquidityToken1Amount, slippageTolerance, positionId?, isValidPosition? });
+useCreateDecreaseLiquidityParams({ /* see source for fields */ });
+```
+
+## SDK param types (passed via `mutate({ params, walletProvider })`)
+
+Each dex mutation hook's TVars is `{ params: <SDKParamsType>, walletProvider, timeout? }`. The SDK param types below are what goes INSIDE `params` — they are not the TVars themselves.
+
+```ts
+// @ai-snippets-skip
+// Deposit / withdraw — spoke chain assets → hub pool tokens (or vice versa)
+type CreateAssetDepositParams<K> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  asset: string;       // spoke-chain asset address
+  amount: bigint;
+  poolToken: string;   // hub-side pool token (vault) address
+  dst?: { chainKey: SpokeChainKey; address: string };
+};
+
+// Supply liquidity — `useSupplyLiquidity` fans out internally to mint-new vs
+// increase-existing based on params.tokenId + params.isValidPosition.
+// The TVars `params` field is `UseCreateSupplyLiquidityParamsResult & { srcChainKey, srcAddress }`
+// (the memoized output of `useCreateSupplyLiquidityParams` + the chain/address pair).
+// Underlying SDK type ClSupplyParams<K> (for mint-new) has NO tokenId field:
+type ClSupplyParams<K> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  poolKey: PoolKey;
+  tickLower: bigint;
+  tickUpper: bigint;
+  liquidity: bigint;
+  amount0Max: bigint;
+  amount1Max: bigint;
+  sqrtPriceX96: bigint;
+};
+// And ClIncreaseLiquidityParams<K> = ClSupplyParams<K> & { tokenId: bigint }
+// for the increase-existing branch.
+
+// Decrease liquidity
+type ClDecreaseLiquidityParams<K> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  poolKey: PoolKey;
+  tokenId: bigint;
+  liquidity: bigint;
+  amount0Min: bigint;
+  amount1Min: bigint;
+};
+
+// Claim rewards
+type ClClaimRewardsParams<K> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  poolKey: PoolKey;
+  tokenId: bigint;
+  tickLower: bigint;
+  tickUpper: bigint;
+};
+```
+
+## Param builders
+
+The `useCreate*Params` hooks compute the right derived params client-side (e.g. ERC-4626 share conversions for deposit, current tick range for liquidity). Spread the result into the mutation:
+
+```ts
+// @ai-snippets-skip — illustrative; `useCreateSupplyLiquidityParams` takes a FLAT props
+// object (not `{ params }`-wrapped). The consumer adds `srcChainKey` + `srcAddress` at
+// the mutation call site.
+const supplyResult = useCreateSupplyLiquidityParams({
+  poolData,
+  poolKey,
+  minPrice,
+  maxPrice,
+  liquidityToken0Amount,
+  liquidityToken1Amount,
+  slippageTolerance,
+  positionId,         // optional, for increase-existing
+  isValidPosition,    // optional, gates the increase-existing branch
+});
+
+const { mutateAsync: supply } = useSupplyLiquidity();
+if (supplyResult && walletProvider) {
+  await supply({
+    params: { ...supplyResult, srcChainKey, srcAddress },
+    walletProvider,
+  });
+}
+```
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+| `useDexDeposit` / `useDexWithdraw` | `SafeUseMutationResult<TxHashPair, Error, UseDex(Deposit\|Withdraw)Vars<K>>` (TVars = `{ params, walletProvider, ...optional }`) |
+| `useDexApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, UseDexApproveVars<K>>` — chain-keyed receipt union |
+| `useSupplyLiquidity` (mint or increase) | `SafeUseMutationResult<TxHashPair, Error, UseSupplyLiquidityVars<K>>` — single shape for both branches; fan-out happens inside the hook |
+| `useDecreaseLiquidity` / `useClaimRewards` | `SafeUseMutationResult<TxHashPair, Error, ...>` |
+| `useDexAllowance` | `UseQueryResult<boolean, Error>` (already unwrapped; throws on SDK `!ok`) |
+| `usePools` | `UseQueryResult<PoolKey[], Error>` — `staleTime: Infinity` (no auto-refresh; pools are static config) |
+| `usePoolData` | `UseQueryResult<PoolData, Error>` |
+| `usePositionInfo` | `UseQueryResult<{ positionInfo: ClPositionInfo, isValid: boolean }, Error>` — `tokenId` param is `string \| null` (NOT bigint) |
+| `usePoolBalances` | `UseQueryResult<{ token0Balance: bigint; token1Balance: bigint }, Error>` |
+| `useLiquidityAmounts` | Direct synchronous calculation (memoized via `useMemo`) — not a React Query hook |
+
+## Gotchas
+
+1. **Two-step flow: deposit, then supply.** First `useDexDeposit` brings the spoke asset to the hub as pool-token shares (ERC-4626). Then `useSupplyLiquidity` uses those shares to mint or grow a position. UI flows usually combine them.
+2. **`useSupplyLiquidity` handles both mint-new and increase-existing.** If `params.tokenId` is provided AND that position is valid for the pool, it increases. Otherwise it mints a new position. Use `useCreateSupplyLiquidityParams` to handle the routing.
+3. **Ticks are logarithmic.** `tickLower` / `tickUpper` are not prices — they're indices. Convert with viem's `Q96` math or the SDK's helpers.
+4. **`usePools` never auto-refreshes.** Pools are static config — fetch once. Override `queryOptions.refetchInterval` only if you really know your config changed.
+5. **`useDexAllowance` doesn't take `walletProvider`.** Read-only — derives the user from `srcAddress` in `params`.
+6. **`useClaimRewards` operates per-position.** If you need to claim across multiple positions, call it once per `tokenId`. The hook invalidates the corresponding `usePositionInfo` after success.
+
+## Cross-references
+
+- [`../recipes/dex.md`](../recipes/dex.md) — full worked examples.
+- [`../../migration/features/dex.md`](../../migration/features/dex.md) — v1 → v2 porting.
+- [`../../../../sdk/ai-exported/integration/features/dex.md`](../../../../sdk/ai-exported/integration/features/dex.md) — underlying SDK DEX surface.

package/ai-exported/integration/features/migration.md

@@ -0,0 +1,118 @@
+# Migration — `@sodax/dapp-kit`
+
+Token migration: ICX/wICX → SODA, BALN → SODA, legacy bnUSD ↔ new bnUSD. Six per-action hooks plus shared allowance/approve.
+
+Pair: [`../../migration/features/migration.md`](../../migration/features/migration.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip — hook-surface listing; `<inner>` is a type placeholder, not real code
+// Mutations (one per action)
+useMigrateIcxToSoda({ mutationOptions });
+useRevertMigrateSodaToIcx({ mutationOptions });
+useMigratebnUSD({ mutationOptions });               // Bidirectional (auto-detects direction)
+useMigrateBaln({ mutationOptions });
+
+// Allowance + approve (action-discriminated)
+useMigrationApprove({ mutationOptions });
+// useMigrationAllowance — params nest `{ params: <inner-migration-params>, action }` under the outer `params`
+useMigrationAllowance({ params: { params: <inner>, action: 'migrate' | 'revert' }, queryOptions });
+```
+
+## Mutation params
+
+```ts
+// @ai-snippets-skip
+// useMigrateIcxToSoda — wICX (ICON) → SODA (Sonic)
+type IcxMigrateParams = {
+  srcChainKey: IconChainKey;   // typeof ChainKeys.ICON_MAINNET
+  srcAddress: IconAddress;     // `hx${string}` | `cx${string}`
+  address: IcxTokenType;       // narrow union: wICX address OR native-ICX address
+  amount: bigint;
+  dstAddress: Address;         // `0x${string}` — Sonic recipient
+};
+
+// useRevertMigrateSodaToIcx — SODA (Sonic) → wICX (ICON)
+type IcxCreateRevertMigrationParams = {
+  srcChainKey: SonicChainKey;  // typeof ChainKeys.SONIC_MAINNET
+  srcAddress: Address;         // `0x${string}` — Sonic
+  amount: bigint;
+  dstAddress: IconEoaAddress;  // `hx${string}` — ICON recipient
+};
+
+// useMigratebnUSD — bidirectional, swap srcbnUSD/dstbnUSD + chains for the other direction
+type UnifiedBnUSDMigrateParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: string;          // SDK keeps this loose (cross-chain)
+  srcbnUSD: string;            // legacy or new bnUSD
+  dstChainKey: SpokeChainKey;
+  dstbnUSD: string;            // the other one
+  amount: bigint;
+  dstAddress: string;
+};
+
+// useMigrateBaln — BALN (ICON) → SODA with optional lock
+type BalnMigrateParams = {
+  srcChainKey: IconChainKey;
+  srcAddress: IconAddress;
+  amount: bigint;
+  lockupPeriod: LockupPeriod;  // enum (values in SECONDS), see below
+  dstAddress: Address;
+  stake: boolean;              // REQUIRED — auto-stake migrated SODA into xSODA vault
+};
+
+// `LockupPeriod` is an enum with 5 members (values are in seconds, NOT months):
+//   NO_LOCKUP            = 0                       (0.5x reward multiplier)
+//   SIX_MONTHS           = 6  * 30 * 24 * 60 * 60  (0.75x)
+//   TWELVE_MONTHS        = 12 * 30 * 24 * 60 * 60  (1.0x)
+//   EIGHTEEN_MONTHS      = 18 * 30 * 24 * 60 * 60  (1.25x)
+//   TWENTY_FOUR_MONTHS   = 24 * 30 * 24 * 60 * 60  (1.5x)
+
+// All wrapped as TVars: { params: <ParamsType>, walletProvider }
+```
+
+## Allowance / approve
+
+The migration approve/allowance hooks are **action-discriminated** — same hook handles all migrations, with `action` disambiguating which token is being approved:
+
+```ts
+// @ai-snippets-skip
+const { data: isApproved } = useMigrationAllowance({
+  params: { params: bnUSDParams, action: 'migrate' },   // 'migrate' | 'revert'
+});
+const { mutateAsync: approve } = useMigrationApprove();
+await approve({ params: bnUSDParams, walletProvider, action: 'migrate' });
+```
+
+## Migration paths summary
+
+| Migration | Approval needed? | Hook |
+|---|---|---|
+| ICX/wICX (ICON) → SODA | No (ICON has no ERC-20 allowance) | `useMigrateIcxToSoda` |
+| SODA → wICX (revert) | Yes | `useRevertMigrateSodaToIcx` + `useMigrationApprove({ action: 'revert' })` |
+| Legacy bnUSD ↔ new bnUSD (EVM) | Yes | `useMigratebnUSD` + `useMigrationApprove({ action: 'migrate' })` |
+| Legacy bnUSD (Stellar/Sui) ↔ new bnUSD | Maybe (depends on chain) | Same as above |
+| BALN (ICON) → SODA | No | `useMigrateBaln` |
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+| `useMigrateIcxToSoda` / `useRevertMigrateSodaToIcx` / `useMigratebnUSD` / `useMigrateBaln` | `SafeUseMutationResult<TxHashPair, Error, ...>` |
+| `useMigrationApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, ...>` — chain-keyed receipt union (EVM/Stellar differ) |
+| `useMigrationAllowance` | `UseQueryResult<boolean, Error>` (already unwrapped) |
+
+## Gotchas
+
+1. **`useMigratebnUSD` is bidirectional.** v2 detects direction from `(srcbnUSD, dstbnUSD)` token addresses. To go the other direction, swap the params; no separate hook.
+2. **BALN `lockupPeriod` is the `LockupPeriod` enum, NOT a literal number union.** Use `LockupPeriod.NO_LOCKUP`, `LockupPeriod.SIX_MONTHS`, `LockupPeriod.TWELVE_MONTHS`, `LockupPeriod.EIGHTEEN_MONTHS`, or `LockupPeriod.TWENTY_FOUR_MONTHS`. Enum values are in **seconds** (e.g. `TWELVE_MONTHS = 12 * 30 * 24 * 60 * 60`), not months. Reward multiplier ranges 0.5x (no lockup) → 1.5x (24 months). Also note: `BalnMigrateParams` requires `stake: boolean` — set `true` to auto-stake migrated SODA into the xSODA vault.
+3. **ICON-side migrations don't need approval.** ICON has no ERC-20 allowance mechanism.
+4. **`useRevertMigrateSodaToIcx` requires SODA approval on Sonic.** Use `useMigrationAllowance` + `useMigrationApprove` with `action: 'revert'`.
+5. **`useMigratebnUSD` errors include `direction: 'forward' | 'reverse'` on context.** When surfacing errors, distinguish forward vs reverse for clearer messaging.
+
+## Cross-references
+
+- [`../recipes/migration.md`](../recipes/migration.md) — full worked examples.
+- [`../../migration/features/migration.md`](../../migration/features/migration.md) — v1 → v2 porting (the v1 dapp-kit had a single `useMigrate(spokeProvider)`-style hook; v2 split into 6).
+- [`../../../../sdk/ai-exported/integration/features/icx-bnusd-baln.md`](../../../../sdk/ai-exported/integration/features/icx-bnusd-baln.md) — underlying SDK migration surface.