@sodax/dapp-kit 2.0.0-rc.3 → 2.0.0-rc.4

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

@@ -1,114 +0,0 @@
-# Auxiliary services migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
-
-Smaller surfaces grouped together: partner, recovery, backend queries, shared utilities. Most changes are mechanical — single-object params, mutateAsyncSafe — same as the other features.
-
-## Partner
-
-```diff
-- const claim = useFeeClaimSwap(spokeProvider);
-- await claim.mutateAsync(params);
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.SONIC_MAINNET });
-+ const { mutateAsyncSafe: claim } = useFeeClaimSwap();
-+ const result = await claim({ params, walletProvider });
-```
-
-`useApproveToken`, `useSetSwapPreference` — same pattern.
-
-`useFetchAssetsBalances`, `useGetAutoSwapPreferences`, `useIsTokenApproved` — convert to single-object query shape.
-
-## Recovery
-
-```diff
-- const withdraw = useWithdrawHubAsset(spokeProvider);
-+ const { mutateAsyncSafe: withdraw } = useWithdrawHubAsset();
-+ await withdraw({ params, walletProvider });
-```
-
-## Backend queries
-
-Read-only. No `walletProvider` involved. Convert to single-object query shape.
-
-```diff
-- const { data: intent } = useBackendIntentByTxHash(txHash);
-+ const { data: intent } = useBackendIntentByTxHash({ params: { txHash } });
-
-- const { data: orderbook } = useBackendOrderbook({ offset: '0', limit: '20' });
-+ const { data: orderbook } = useBackendOrderbook({ pagination: { offset: '0', limit: '20' } });
-
-- const { data: position } = useBackendMoneyMarketPosition(userAddress);
-+ const { data: position } = useBackendMoneyMarketPosition({ params: { userAddress } });
-
-- const { data: assets } = useBackendAllMoneyMarketAssets();
-+ const { data: assets } = useBackendAllMoneyMarketAssets({});
-```
-
-`useBackendSubmitSwapTx` is a mutation — per-call config flows through `mutate(vars)`:
-
-```diff
-- const submit = useBackendSubmitSwapTx({ baseURL: 'https://...' });   // v1: per-instance config
-- await submit.mutateAsync(swapPayload);
-+ const { mutateAsync: submit } = useBackendSubmitSwapTx();
-+ await submit({ request: swapPayload, apiConfig: { baseURL: 'https://...' } });   // v2: per-call config
-```
-
-## Shared utilities
-
-### `useXBalances`
-
-v2 requires four fields under `params`: `xService` (from `@sodax/wallet-sdk-react`), `xChainId`, `xTokens`, and `address`. The token list is no longer optional.
-
-```diff
-- const { data: balances } = useXBalances(BSC_MAINNET_CHAIN_ID, address, tokens);
-+ import { useXService, getXChainType } from '@sodax/wallet-sdk-react';
-+ const xChainId = ChainKeys.BSC_MAINNET;
-+ const xService = useXService({ xChainType: getXChainType(xChainId) });
-+ const { data: balances } = useXBalances({
-+   params: { xService, xChainId, xTokens, address },
-+ });
-```
-
-Note: the request param is still `xChainId` (not renamed to `chainKey`). This is intentional — `xChainId` overlays the cross-chain abstraction; the rename only happened for token-side fields. Don't conflate.
-
-### `useEstimateGas`
-
-```diff
-- const estimate = useEstimateGas(walletProvider);
-- await estimate.mutateAsync({ rawTx });
-+ const { mutateAsyncSafe: estimateGas } = useEstimateGas();
-+ const result = await estimateGas({ rawTx, walletProvider });
-```
-
-### `useStellarTrustlineCheck` / `useRequestTrustline`
-
-```diff
-- const { data: hasTrustline } = useStellarTrustlineCheck(account, asset);
-+ const { data: hasTrustline } = useStellarTrustlineCheck({ params: { account, asset } });
-
-- const request = useRequestTrustline(walletProvider);
-- await request.mutateAsync({ account, asset });
-+ const { mutateAsync: request } = useRequestTrustline();
-+ await request({ account, asset, walletProvider });
-```
-
-### `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`
-
-```diff
-- const { data: hubAddress } = useDeriveUserWalletAddress(spokeChainKey, srcAddress);
-+ const { data: hubAddress } = useDeriveUserWalletAddress({ params: { spokeChainKey, srcAddress } });
-```
-
-## Pitfalls
-
-1. **`useBackendIntentByTxHash` polls every 1s while pending** — same as v1, but make sure your `queryOptions.refetchInterval` overrides if needed.
-2. **`useBackendOrderbook` does NOT auto-refetch** — it has `staleTime: 30s` only, so data stays fresh for 30s after a fetch but won't refresh on its own. Trigger a refetch manually or pass `refetchInterval` via `queryOptions` if you need polling.
-3. **`useXBalances` uses `xChainId` (not `chainKey`)** — request-side field name retained on this hook.
-4. **`useBackendSubmitSwapTx` config moved to per-call.** v1 may have had `baseURL` at hook init; v2 puts it in `mutate(vars).apiConfig`. Lets you have a single hook serve multiple backends if needed.
-
-## Cross-references
-
-- [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md) — v2 reference.
-- [`../../integration/recipes/backend-queries.md`](../../integration/recipes/backend-queries.md) — backend hooks worked examples.
-- [`../../integration/recipes/wallet-connectivity.md`](../../integration/recipes/wallet-connectivity.md) — `useXBalances` worked example.
-- [`../../../../sdk/ai-exported/migration/features/auxiliary-services.md`](../../../../sdk/ai-exported/migration/features/auxiliary-services.md) — underlying SDK auxiliary migrations.

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

@@ -1,88 +0,0 @@
-# Bitcoin (Radfi) migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/bitcoin.md`](../../integration/features/bitcoin.md).
-
-Bitcoin / Radfi hook surface was new in v1 with limited adoption; v2 standardizes its shapes against the canonical hook conventions. Treat the v2 forms below as the canonical reference — if your v1 code used a different shape, swap to v2's directly.
-
-## TL;DR
-
-> Cross-cutting conventions (drop `spokeProvider`, single-object hook init, `mutate(vars)` for domain inputs, `mutateAsyncSafe` ergonomics) — see [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) and [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md). Bitcoin-specific deltas:
-
-1. **`useRadfiSession` API unchanged** — still takes a `walletProvider` directly (not via `mutate(vars)`); it manages session lifecycle.
-2. **`useTradingWallet(walletAddress)` is synchronous** — no Query/Mutation; reads localStorage. Unchanged.
-3. **`useBitcoinBalance` / `useTradingWalletBalance`** use single-object query shape `{ params, queryOptions }`.
-4. **Withdrawal/funding mutations** follow the canonical mutation hook shape — only `{ mutationOptions }` at hook init; `walletProvider` and per-call config flow through `mutate(vars)`.
-
-## v2 canonical shapes
-
-### `useFundTradingWallet`
-
-```ts
-// @ai-snippets-skip
-const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
-const { mutateAsyncSafe: fund } = useFundTradingWallet();
-const result = await fund({ amount: 100_000n, walletProvider });
-if (!result.ok) return;
-const txId = result.value;
-```
-
-### `useRadfiWithdraw`
-
-```ts
-// @ai-snippets-skip
-const { mutateAsyncSafe: withdraw } = useRadfiWithdraw();
-const result = await withdraw({
-  amount: '10000',
-  tokenId: '0:0',
-  withdrawTo,
-  walletProvider,
-});
-```
-
-### `useRenewUtxos`
-
-```ts
-// @ai-snippets-skip
-await renewUtxos({ txIdVouts, walletProvider });
-```
-
-### `useRadfiSession`
-
-```ts
-// @ai-snippets-skip
-// Unchanged — still takes walletProvider directly (not via mutate vars).
-const { isAuthed, tradingAddress, login, isLoginPending } = useRadfiSession(walletProvider);
-```
-
-The session-management lifecycle hook needs constant access to the wallet provider for token refresh — it doesn't fit the `mutate(vars)` pattern.
-
-### `useBitcoinBalance` / `useTradingWalletBalance`
-
-Single-object query shape:
-
-```diff
-- const { data } = useBitcoinBalance(address);
-+ const { data } = useBitcoinBalance({ params: { address } });
-
-- const { data } = useTradingWalletBalance(walletProvider, tradingAddress);
-+ const { data } = useTradingWalletBalance({ params: { walletProvider, tradingAddress } });
-```
-
-### `useExpiredUtxos`
-
-```diff
-- const { data: expiredUtxos } = useExpiredUtxos(walletProvider, tradingAddress);
-+ const { data: expiredUtxos } = useExpiredUtxos({ params: { walletProvider, tradingAddress } });
-```
-
-## Pitfalls
-
-1. **`useRadfiSession` is the lifecycle owner.** Don't create your own `useRadfiAuth` ad-hoc handlers if you're using `useRadfiSession` — it manages auth + refresh + persistence.
-2. **Session tokens in localStorage are NOT for asset access.** They're API rate-limit tokens. Compromise of localStorage data doesn't let an attacker move funds.
-3. **Trading wallet is auto-created** during first authentication — don't add a separate "create wallet" step in your UI.
-4. **PSBT signing flow is internal.** v1 may have surfaced the unsigned PSBT for explicit consumer signing; v2 hooks orchestrate the full flow (build → sign → co-sign → broadcast) inside `mutationFn`.
-
-## Cross-references
-
-- [`../../integration/features/bitcoin.md`](../../integration/features/bitcoin.md) — v2 reference.
-- [`../../integration/recipes/bitcoin.md`](../../integration/recipes/bitcoin.md) — full v2 worked examples.

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

@@ -1,160 +0,0 @@
-# Bridge migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge.md).
-
-## TL;DR
-
-> Cross-cutting conventions (drop `spokeProvider`, single-object hook init, `mutate(vars)` for domain inputs, `mutateAsyncSafe` ergonomics) — see [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) and [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md). Feature-specific deltas below:
-
-1. **`CreateBridgeIntentParams` field renames** (SDK-leakage):
-   - `srcChainId` → `srcChainKey`
-   - `dstChainId` → `dstChainKey`
-   - `srcAsset` → `srcToken`
-   - `dstAsset` → `dstToken`
-   - `recipient` is **unchanged** (stays `recipient` in v2 — it is NOT renamed to `dstAddress`; the only `dstAddress`-shaped field in v2 lives on money-market params, not bridge)
-   - **NEW required**: `srcAddress` (the user's spoke-side sender address, distinct from `recipient` which is the destination)
-2. **`bridge()` return shape changed.** v1 was `Promise<string>` (a single tx hash that threw on error). v2 returns `Promise<Result<TxHashPair, BridgeOrchestrationError>>` where `TxHashPair = { srcChainTxHash: string; dstChainTxHash: string }`. **This is the shape at the direct-SDK boundary** (`sodax.bridge.bridge(...)`); the `useBridge` hook does not adapt the inner object, it only unwraps the `Result` wrapper (so the hook surfaces `TxHashPair` directly via `data` / `mutateAsync` / `mutateAsyncSafe`'s `value`). Don't destructure as a tuple — there was no `[spokeTxHash, hubTxHash]` form in either v1 or v2.
-3. **`useGetBridgeableAmount` reshape.** v1 took `(srcChainId, srcAsset, dstChainId, dstAsset)`. v2 takes `{ from: XToken, to: XToken }` — each `XToken` carries its own `chainKey`.
-4. **`useGetBridgeableAmount` return value is `BridgeLimit`, not bare `bigint`.** Access `.value.amount` and `.value.decimals`.
-5. **`useGetBridgeableTokens` is sync now** in the SDK. The hook still returns `UseQueryResult` but the underlying SDK call doesn't fire RPC — it's config-derived.
-6. **Allowance/approve** — same shape changes as every other feature.
-
-## Per-method delta
-
-### `useBridge` — params + return
-
-```diff
-  function BridgeButton({ srcAddress }) {
--   const bridge = useBridge(spokeProvider);
-+   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-+   const { mutateAsyncSafe: bridge } = useBridge();
-
-    const handleBridge = async () => {
-+     if (!walletProvider) return;
--     // v1: single tx hash, throws on failure
--     const txHash: string = await bridge.mutateAsync({
--       params: {
--         srcChainId: BASE_MAINNET_CHAIN_ID,
--         srcAsset: '0x...',
--         amount: 1_000_000n,
--         dstChainId: POLYGON_MAINNET_CHAIN_ID,
--         dstAsset: '0x...',
--         recipient: '0x...',
--       },
--     });
-+     const result = await bridge({
-+       params: {
-+         srcChainKey: ChainKeys.BASE_MAINNET,
-+         srcAddress,                                  // NEW: required (your spoke-side sender)
-+         srcToken: '0x...',                           // RENAMED from `srcAsset`
-+         amount: 1_000_000n,
-+         dstChainKey: ChainKeys.POLYGON_MAINNET,
-+         dstToken: '0x...',                           // RENAMED from `dstAsset`
-+         recipient: '0x...',                          // UNCHANGED — destination receiver
-+       },
-+       walletProvider,
-+     });
-+     if (!result.ok) return;
-+     const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair object, not [a, b]
-    };
-  }
-```
-
-### Calling `sodax.bridge.bridge()` directly (no hook)
-
-If you call the SDK directly inside a custom `useMutation` (instead of `useBridge`), the return shape is **exactly the same** — the dapp-kit hook only unwraps the `Result` wrapper, it does not reshape `TxHashPair`:
-
-```diff
-- // v1 direct-SDK call:
-- const txHash: string = await sodax.bridge.bridge({ params: { /* v1 shape */ }, spokeProvider });
-+ // v2 direct-SDK call:
-+ const result = await sodax.bridge.bridge({
-+   params: {
-+     srcChainKey: ChainKeys.BASE_MAINNET,
-+     srcAddress,
-+     srcToken: '0x...',
-+     amount: 1_000_000n,
-+     dstChainKey: ChainKeys.POLYGON_MAINNET,
-+     dstToken: '0x...',
-+     recipient: '0x...',
-+   },
-+   raw: false,
-+   walletProvider,
-+ });
-+ // Type: Result<TxHashPair, BridgeOrchestrationError>
-+ if (!result.ok) {
-+   // result.error is a SodaxError<C> with feature: 'bridge'
-+   return;
-+ }
-+ const { srcChainTxHash, dstChainTxHash } = result.value;   // same shape as the hook
-```
-
-The hook equivalence in code:
-
-```ts
-// @ai-snippets-skip
-// What `useBridge` does internally (sketch):
-// mutationFn: async vars => unwrapResult(await sodax.bridge.bridge({ ...vars, raw: false }))
-// `unwrapResult` throws on `!ok` and returns `value` on `ok` — that's the only adapter.
-```
-
-### `useGetBridgeableAmount` — params + return reshape
-
-```diff
-- const { data: amount } = useGetBridgeableAmount({
--   params: {
--     srcChainId: BASE_MAINNET_CHAIN_ID,
--     srcAsset: '0x...',
--     dstChainId: POLYGON_MAINNET_CHAIN_ID,
--     dstAsset: '0x...',
--   },
-- });
-- if (amount) {
--   <p>Max: {formatUnits(amount, 6)}</p>;   // v1 was bare bigint
-- }
-+ const { data: result } = useGetBridgeableAmount({
-+   params: { from: srcXToken, to: dstXToken },   // each XToken carries chainKey
-+ });
-+ if (result?.ok) {
-+   <p>Max: {formatUnits(result.value.amount, result.value.decimals)}</p>;
-+ }
-```
-
-### `useGetBridgeableTokens`
-
-```diff
-- const { data: tokens } = useGetBridgeableTokens(BASE_MAINNET_CHAIN_ID, POLYGON_MAINNET_CHAIN_ID, srcAsset);
-+ const { data: result } = useGetBridgeableTokens({
-+   params: { from: ChainKeys.BASE_MAINNET, to: ChainKeys.POLYGON_MAINNET, token: srcAsset },
-+ });
-+ if (result?.ok) {
-+   const tokens: XToken[] = result.value;
-+ }
-```
-
-### `useBridgeAllowance` / `useBridgeApprove`
-
-`useBridgeAllowance` query inputs (payload + walletProvider) all nest under `params` in v2:
-
-```diff
-- const { data: allowanceResult } = useBridgeAllowance({ params, spokeProvider });
-+ const { data: isApproved } = useBridgeAllowance({
-+   params: { payload: bridgeParams, walletProvider },
-+ });
-+ // `data` is `boolean | undefined` (already unwrapped).
-```
-
-`useBridgeApprove` mutation drops `spokeProvider` from hook init; `mutate(vars)` takes `{ params, walletProvider }`.
-
-## Pitfalls
-
-1. **`useGetBridgeableAmount` data shape changed.** v1 returned bare `bigint`; v2 returns `Result<BridgeLimit>` where `BridgeLimit = { amount, decimals, type }`. UI code that displayed the bigint directly needs `.value.amount`.
-2. **Tokens must share the same vault** to be bridgeable. Use `useGetBridgeableTokens` to enumerate compatible destinations — passing an incompatible pair to `bridge()` rejects with `VALIDATION_FAILED`.
-3. **`useBridge` return is `TxHashPair`** — destructure as `{ srcChainTxHash, dstChainTxHash }`, not `[a, b]`.
-4. **`recipient` field renamed to `dstAddress`** for consistency with the rest of the SDK.
-
-## Cross-references
-
-- [`../../integration/features/bridge.md`](../../integration/features/bridge.md) — v2 reference.
-- [`../../integration/recipes/bridge.md`](../../integration/recipes/bridge.md) — full v2 worked example.
-- [`../../../../sdk/ai-exported/migration/features/bridge.md`](../../../../sdk/ai-exported/migration/features/bridge.md) — underlying SDK bridge migration.

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

@@ -1,101 +0,0 @@
-# DEX migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/dex.md`](../../integration/features/dex.md).
-
-## TL;DR
-
-> Cross-cutting conventions (drop `spokeProvider`, single-object hook init, `mutate(vars)` for domain inputs, `mutateAsyncSafe` ergonomics) — see [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) and [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md). Feature-specific deltas below:
-
-1. **All mutations** (`useDexDeposit`, `useDexWithdraw`, `useSupplyLiquidity`, `useDecreaseLiquidity`, `useClaimRewards`, `useDexApprove`) — single-object hook init + `mutate({ params, walletProvider })`. SDK-leakage adds required `srcChainKey` + `srcAddress` to all action params.
-2. **`useSupplyLiquidity` handles both mint-new and increase-existing** — pass `tokenId` in params for increase, omit for mint. Use `useCreateSupplyLiquidityParams` to handle the routing.
-3. **`usePools` returns synchronously** in the SDK. The hook still returns `UseQueryResult` but the underlying call is config-derived (no RPC) — `staleTime: Infinity`, no auto-refresh.
-4. **Param builders take a FLAT props object** — `useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams` — NOT `{ params: { ... } }`-wrapped. Their inputs use `srcChainKey` (not `srcChainId`); the result is spread into the mutation's `params` field at the call site.
-
-## Per-method delta
-
-### `useDexDeposit` / `useDexWithdraw`
-
-```diff
-- const deposit = useDexDeposit(spokeProvider);
-- await deposit.mutateAsync({ params: { asset, amount, poolToken } });
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-+ const { mutateAsyncSafe: deposit } = useDexDeposit();
-+ const result = await deposit({
-+   params: {
-+     srcChainKey: ChainKeys.BASE_MAINNET,
-+     srcAddress,                          // NEW
-+     asset,
-+     amount,
-+     poolToken,
-+   },
-+   walletProvider,
-+ });
-+ if (!result.ok) return;
-+ const { srcChainTxHash, dstChainTxHash } = result.value;
-```
-
-### `useSupplyLiquidity` — mint vs increase routing
-
-```diff
-- // v1: separate hooks for mint and increase
-- const mint = useMintLiquidity(spokeProvider);
-- const increase = useIncreaseLiquidity(spokeProvider);
-- if (existingTokenId) {
--   await increase.mutateAsync({ params: { tokenId, poolKey, ... } });
-- } else {
--   await mint.mutateAsync({ params: { poolKey, ... } });
-- }
-
-+ // v2: single hook handles both via tokenId presence
-+ const { mutateAsyncSafe: supply } = useSupplyLiquidity();
-+ const supplyParams = useCreateSupplyLiquidityParams({
-+   params: { poolKey, tickLower, tickUpper, amount0, amount1, tokenId: existingTokenId },
-+ });
-+ if (supplyParams && walletProvider) {
-+   const result = await supply({ params: supplyParams, walletProvider });
-+ }
-```
-
-### `useDecreaseLiquidity` / `useClaimRewards`
-
-Standard pattern — drop `spokeProvider` from hook init, add `srcChainKey` / `srcAddress` to params, pass `walletProvider` via `mutate(vars)`.
-
-### `useDexAllowance` / `useDexApprove`
-
-`useDexAllowance` wraps the deposit params under `params.payload`. Read-only — no `walletProvider`:
-
-```diff
-- const { data: allowance } = useDexAllowance({ params: depositParams, walletProvider });
-+ const { data: isApproved } = useDexAllowance({ params: { payload: depositParams } });
-+ // `data` is `boolean | undefined`; the hook calls `isAllowanceValid` with `raw: true`.
-```
-
-`useDexApprove` mutation drops `spokeProvider` from hook init; `mutate(vars)` takes `{ params, walletProvider }`.
-
-### `usePoolData` / `usePositionInfo` / `usePools`
-
-Convert to single-object query shape:
-
-```diff
-- const { data } = usePoolData(poolKey);
-+ const { data } = usePoolData({ params: { poolKey } });
-
-- const { data } = usePositionInfo(tokenId, poolKey);
-+ const { data } = usePositionInfo({ params: { tokenId, poolKey } });
-
-- const { data: pools } = usePools();
-+ const { data: pools } = usePools({});   // single-object shape, even with no params
-```
-
-## Pitfalls
-
-1. **`useSupplyLiquidity` is now ONE hook for both mint and increase.** v1 may have had two separate hooks. Use `tokenId` presence in `params` to drive the routing — `useCreateSupplyLiquidityParams` handles this for you.
-2. **Two-step flow stays the same.** First `useDexDeposit` brings the spoke asset to the hub as pool-token shares. Then `useSupplyLiquidity` uses those shares to mint/grow a position. UI sequencing unchanged.
-3. **Ticks are logarithmic.** Calculation libraries unchanged; just be aware that `tickLower` / `tickUpper` are tick indices, not prices.
-4. **`usePools` never auto-refreshes** — pools are static config. Override `queryOptions.refetchInterval` only if you really know your config changed.
-
-## Cross-references
-
-- [`../../integration/features/dex.md`](../../integration/features/dex.md) — v2 reference.
-- [`../../integration/recipes/dex.md`](../../integration/recipes/dex.md) — full v2 worked example.
-- [`../../../../sdk/ai-exported/migration/features/dex.md`](../../../../sdk/ai-exported/migration/features/dex.md) — underlying SDK DEX migration.

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

@@ -1,120 +0,0 @@
-# Migration migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/migration.md`](../../integration/features/migration.md).
-
-The biggest single API change in dapp-kit v2: v1 had a single `useMigrate(spokeProvider)`-style hook (often commented out by the time consumers needed it); v2 split it into 6 dedicated hooks.
-
-## TL;DR
-
-> Cross-cutting conventions (drop `spokeProvider`, single-object hook init, `mutate(vars)` for domain inputs, `mutateAsyncSafe` ergonomics) — see [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) and [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md). Feature-specific deltas below:
-
-1. **`useMigrate(spokeProvider)` is gone.** Replaced by **six per-action hooks**:
-   - `useMigrateIcxToSoda` — wICX (ICON) → SODA (Sonic)
-   - `useRevertMigrateSodaToIcx` — SODA → wICX (revert)
-   - `useMigratebnUSD` — legacy bnUSD ↔ new bnUSD (bidirectional)
-   - `useMigrateBaln` — BALN (ICON) → SODA with optional lock period
-   - `useMigrationApprove` — approve before migration (action-discriminated)
-   - `useMigrationAllowance` — check approval (action-discriminated)
-2. **`useMigratebnUSD` is bidirectional.** v2 detects direction from `(srcbnUSD, dstbnUSD)` token addresses — no separate forward/reverse hook.
-3. **All mutations** drop `spokeProvider`; `walletProvider` flows through `mutate(vars)`. SDK-leakage adds `srcChainKey` / `srcAddress` to all action params.
-4. **`useMigrationApprove` / `useMigrationAllowance` are action-discriminated.** Same hook handles all migration approvals; pass `action: 'migrate' | 'revert'` to disambiguate.
-5. **BALN `lockupPeriod` is a literal union, not arbitrary number.** `0 | 1 | 2 | 3 | 6 | 12 | 18 | 24` (months).
-
-## Per-method delta
-
-### v1 single hook → v2 six hooks
-
-```diff
-- // v1 — single hook
-- const migrate = useMigrate(spokeProvider);
-- await migrate.mutateAsync({ params: { type: 'icxToSoda', amount, /* ... */ } });
-
-+ // v2 — pick the right hook
-+ const { mutateAsyncSafe: migrate } = useMigrateIcxToSoda();
-+ const result = await migrate({
-+   params: {
-+     srcChainKey: ChainKeys.ICON_MAINNET,
-+     srcAddress: 'hx...',
-+     address: 'cx88fd...',                        // wICX token address
-+     amount,
-+     dstAddress: '0x...',                         // Sonic recipient
-+   },
-+   walletProvider,
-+ });
-+ if (!result.ok) return;
-+ const { srcChainTxHash, dstChainTxHash } = result.value;
-```
-
-### `useMigratebnUSD` — bidirectional via token addresses
-
-```diff
-- // v1 might have had separate forward/reverse hooks (or all-in-one)
-+ // v2: one hook; direction detected from (srcbnUSD, dstbnUSD)
-+ const { mutateAsyncSafe: migratebnUSD } = useMigratebnUSD();
-+ const result = await migratebnUSD({
-+   params: {
-+     srcChainKey: ChainKeys.BASE_MAINNET,
-+     srcAddress: '0x...',
-+     srcbnUSD: '0x... (legacy or new)',
-+     dstChainKey: ChainKeys.ARBITRUM_MAINNET,
-+     dstbnUSD: '0x... (the other one)',
-+     amount,
-+     dstAddress: '0x...',
-+   },
-+   walletProvider,
-+ });
-+ if (!result.ok) {
-+   const direction = result.error.context?.direction;   // 'forward' | 'reverse'
-+   /* ... */
-+ }
-```
-
-### `useMigrateBaln` — lock period
-
-```diff
-+ const { mutateAsyncSafe: migrateBaln } = useMigrateBaln();
-+ await migrateBaln({
-+   params: {
-+     srcChainKey: ChainKeys.ICON_MAINNET,
-+     srcAddress: 'hx...',
-+     amount,
-+     lockupPeriod: 12,                            // 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24
-+     dstAddress: '0x...',
-+   },
-+   walletProvider,
-+ });
-```
-
-### `useMigrationApprove` / `useMigrationAllowance` — action-discriminated
-
-```diff
-- const { approve } = useMigrationApprove(spokeProvider);
-- await approve(params);
-+ const { data: isApproved } = useMigrationAllowance({
-+   params: { params: revertParams, action: 'revert' },
-+ });
-+ const { mutateAsync: approve } = useMigrationApprove();
-+ await approve({ params: revertParams, walletProvider, action: 'revert' });
-```
-
-## Approval requirements
-
-| Migration | Approval needed? |
-|---|---|
-| ICX/wICX (ICON) → SODA | No (ICON has no ERC-20 allowance) |
-| SODA → wICX (revert) | Yes |
-| Legacy bnUSD ↔ new bnUSD (EVM/Stellar source) | Yes |
-| BALN (ICON) → SODA | No |
-
-## Pitfalls
-
-1. **The single `useMigrate` is gone.** Pick the per-action hook that matches your migration. The v1 one-size-fits-all approach doesn't have a v2 shim.
-2. **`useMigratebnUSD` direction detection.** v2 detects from token addresses. If both `srcbnUSD` and `dstbnUSD` are on the same side (both legacy or both new), the SDK rejects with `VALIDATION_FAILED`. Use `error.context?.direction` to disambiguate in error messaging.
-3. **`lockupPeriod` is a literal union.** TypeScript rejects `lockupPeriod: 7`. Allowed: `0 | 1 | 2 | 3 | 6 | 12 | 18 | 24`. Reward multiplier ranges 0.5x (0 months) → 1.5x (24 months).
-4. **ICON-side migrations don't need approval** — ICON has no ERC-20 allowance mechanism. Don't render an approve step for `useMigrateIcxToSoda` or `useMigrateBaln`.
-
-## Cross-references
-
-- [`../../integration/features/migration.md`](../../integration/features/migration.md) — v2 reference.
-- [`../../integration/recipes/migration.md`](../../integration/recipes/migration.md) — full v2 worked examples (ICX, BALN, bnUSD, revert).
-- [`../../../../sdk/ai-exported/migration/features/icx-bnusd-baln.md`](../../../../sdk/ai-exported/migration/features/icx-bnusd-baln.md) — underlying SDK migration migration.