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

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

@@ -0,0 +1,88 @@
+# 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

@@ -0,0 +1,123 @@
+# 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`
+   - `recipient` → `dstAddress`
+   - **NEW required**: `srcAddress`
+2. **`useBridge` return is `TxHashPair`, not a tuple.** v1 may have returned `[spokeTxHash, hubTxHash]`; v2 returns `{ srcChainTxHash, dstChainTxHash }`. Don't destructure as array.
+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;
+-     const result = await bridge.mutateAsync({
+-       params: {
+-         srcChainId: BASE_MAINNET_CHAIN_ID,
+-         srcAsset: '0x...',
+-         amount: 1_000_000n,
+-         dstChainId: POLYGON_MAINNET_CHAIN_ID,
+-         dstAsset: '0x...',
+-         recipient: '0x...',
+-       },
+-     });
+-     if (result.ok) {
+-       const [spokeTxHash, hubTxHash] = result.value;
+-       /* ... */
+-     }
++     const result = await bridge({
++       params: {
++         srcChainKey: ChainKeys.BASE_MAINNET,
++         srcAddress,                                  // NEW: required
++         srcAsset: '0x...',
++         amount: 1_000_000n,
++         dstChainKey: ChainKeys.POLYGON_MAINNET,
++         dstAsset: '0x...',
++         dstAddress: '0x...',                         // RENAMED from `recipient`
++       },
++       walletProvider,
++     });
++     if (!result.ok) return;
++     const { srcChainTxHash, dstChainTxHash } = result.value;   // OBJECT, not tuple
+    };
+  }
+```
+
+### `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

@@ -0,0 +1,101 @@
+# 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

@@ -0,0 +1,120 @@
+# 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.

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

@@ -0,0 +1,97 @@
+# Money Market migration — v1 → v2 (dapp-kit)
+
+Pair: [`../../integration/features/money-market.md`](../../integration/features/money-market.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. **`useSupply` / `useBorrow` / `useWithdraw` / `useRepay`** all switch to single-object `{ mutationOptions }` hook init + `mutate({ params, walletProvider })`.
+2. **`MoneyMarketSupplyParams<K>` (and the four similar action-param types) gained required `srcChainKey` + `srcAddress`** — SDK-leakage.
+3. **`useMMAllowance` auto-skips on-chain checks for borrow/withdraw** — v1 may have had this too, but v2 returns `true` synchronously for those actions instead of issuing a no-op RPC.
+4. **`useMMApprove` returns standard `SafeUseMutationResult`** — `isLoading` → `isPending`.
+5. **Reserve data hooks renamed `address` → `userAddress`** in some queries (`useUserFormattedSummary`, `useUserReservesData`).
+
+## Per-method delta
+
+### `useSupply` (and `useBorrow` / `useWithdraw` / `useRepay`)
+
+```diff
+  function SupplyButton({ token, amount, srcAddress }) {
+-   const supply = useSupply(spokeProvider);
++   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
++   const { mutateAsyncSafe: supply, isPending } = useSupply();
+
+    const handleSupply = async () => {
++     if (!walletProvider) return;
+-     const result = await supply.mutateAsync({ params: { token, amount, action: 'supply' } });
+-     if (result.ok) {
+-       const txHashPair = result.value;
+-       /* ... */
+-     }
++     const result = await supply({
++       params: {
++         srcChainKey: ChainKeys.BASE_MAINNET,                  // NEW: required
++         srcAddress,                                           // NEW: required
++         token,
++         amount,
++         action: 'supply',
++       },
++       walletProvider,
++     });
++     if (!result.ok) return;
++     const { srcChainTxHash, dstChainTxHash } = result.value;  // TxHashPair
+    };
+  }
+```
+
+`useBorrow`, `useWithdraw`, `useRepay` follow the same pattern with their respective `action` literals (`'borrow'` / `'withdraw'` / `'repay'`). Borrow + repay can specify optional `dstChainKey` / `dstAddress` for cross-chain delivery.
+
+### `useMMAllowance` — auto-skip
+
+```diff
+- const { data: isApproved } = useMMAllowance({ params, spokeProvider });
++ const { data: isApproved } = useMMAllowance({ params: { payload: params } });
++ // No walletProvider — read-only (SDK call uses `raw: true` internally).
++ // For borrow/withdraw actions, returns `true` synchronously (no RPC call).
++ // For supply/repay, reads on-chain allowance.
+```
+
+### `useMMApprove`
+
+```diff
+- const { approve, isLoading } = useMMApprove(spokeProvider);
+- await approve(params);
++ const { mutateAsync: approve, isPending } = useMMApprove();
++ await approve({ params, walletProvider });
+```
+
+### Reserve data hooks
+
+Most got the single-object shape:
+
+```diff
+- const { data } = useReservesData({ ...refetchOptions });
++ const { data } = useReservesData({ queryOptions: { ...refetchOptions } });
+```
+
+User-position hooks renamed param fields:
+
+```diff
+- const { data } = useUserFormattedSummary({ spokeChainKey, address: userAddress });
++ const { data } = useUserFormattedSummary({ params: { spokeChainKey, userAddress } });
+```
+
+## Pitfalls
+
+1. **`srcAddress` is the user's spoke-side address**, not the hub address. Hub wallet is derived internally.
+2. **`useMMAllowance` returns `true` instantly for borrow/withdraw** — don't wait on the query state. Branch on `isApproved` directly.
+3. **Cross-chain borrow/repay**: omit `dstChainKey` / `dstAddress` for same-chain. Don't pass `dstChainKey === srcChainKey` (let the default kick in).
+4. **`MoneyMarketSupplyParams<K>` is now generic.** Use `as const` on `srcChainKey` for narrowing: `srcChainKey: ChainKeys.BASE_MAINNET as const`.
+
+## Cross-references
+
+- [`../../integration/features/money-market.md`](../../integration/features/money-market.md) — v2 reference.
+- [`../../integration/recipes/money-market.md`](../../integration/recipes/money-market.md) — full v2 worked example.
+- [`../breaking-changes/sdk-leakage.md`](../breaking-changes/sdk-leakage.md) — `srcChainKey`/`srcAddress` required.
+- [`../../../../sdk/ai-exported/migration/features/money-market.md`](../../../../sdk/ai-exported/migration/features/money-market.md) — underlying SDK MM migration.

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

@@ -0,0 +1,109 @@
+# Staking migration — v1 → v2 (dapp-kit)
+
+Pair: [`../../integration/features/staking.md`](../../integration/features/staking.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 five mutations** (`useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`) drop `spokeProvider` from hook init; `walletProvider` flows through `mutate(vars)`.
+2. **Three approve hooks** (`useStakeApprove`, `useUnstakeApprove`, `useInstantUnstakeApprove`) — same shape change. Each approves a different token (SODA for stake; xSODA for unstake/instant).
+3. **`useStakeRatio` return changed.** v2: `Result<[xSodaAmount, previewDepositAmount]>` — a 2-tuple. v1 returned a single bigint.
+4. **`useUnstakingInfo` return shape changed.** v2: `Result<UnstakingInfo>` where `UnstakingInfo = { userUnstakeSodaRequests: UserUnstakeInfo[], totalUnstaking: bigint }`. v1 may have returned just the array — v2 wraps it in an object.
+5. **Action params gained `srcChainKey` + `srcAddress`.** Same SDK-leakage as MM.
+
+## Per-method delta
+
+### `useStake` (template for all five)
+
+```diff
+  function StakeButton({ amount, srcAddress }) {
+-   const stake = useStake(spokeProvider);
++   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
++   const { mutateAsyncSafe: stake } = useStake();
+
+    const handleStake = async () => {
++     if (!walletProvider) return;
+-     await stake.mutateAsync({ params: { amount, minReceive, action: 'stake' } });
++     const result = await stake({
++       params: {
++         srcChainKey: ChainKeys.BASE_MAINNET,
++         srcAddress,
++         amount,
++         minReceive,
++         action: 'stake',
++       },
++       walletProvider,
++     });
++     if (!result.ok) return;
++     const { srcChainTxHash, dstChainTxHash } = result.value;
+    };
+  }
+```
+
+`useUnstake` / `useInstantUnstake` / `useClaim` / `useCancelUnstake` follow the same pattern with their respective params types.
+
+### Approve hooks
+
+Each of stake / unstake / instantUnstake has its OWN approve hook (different tokens):
+
+```diff
+- const { approve, isLoading } = useStakeApprove(spokeProvider);
+- await approve({ amount, action: 'stake' });
++ const { mutateAsync: approve, isPending } = useStakeApprove();
++ await approve({ params: { srcChainKey, srcAddress, amount, action: 'stake' }, walletProvider });
+```
+
+`useUnstakeApprove`, `useInstantUnstakeApprove` — same pattern.
+
+### `useStakeRatio` — return type change
+
+```diff
+- const { data: ratio } = useStakeRatio(amount);
+- if (ratio) {
+-   const xSodaAmount = ratio;   // v1 returned single bigint
+-   /* ... */
+- }
++ const { data: ratio } = useStakeRatio({ params: { amount } });
++ if (ratio?.ok) {
++   const [xSodaAmount, previewDepositAmount] = ratio.value;   // v2 returns tuple
++ }
+```
+
+### `useUnstakingInfo` — return shape change
+
+```diff
+- const { data: requests } = useUnstakingInfo(spokeProvider);
+- requests?.map((r) => /* ... */);   // v1 was an array
++ const { data: result } = useUnstakingInfo({ params: { srcAddress, srcChainKey } });
++ if (result?.ok) {
++   const { userUnstakeSodaRequests, totalUnstaking } = result.value;   // v2 is object
++   userUnstakeSodaRequests.map((r) => /* ... */);
++ }
+```
+
+### `useUnstakingInfoWithPenalty`
+
+New in v2 — wraps `useUnstakingInfo`'s base shape with a per-request penalty annotation. Skip this section if your v1 codebase didn't compute penalty client-side.
+
+```ts
+// @ai-snippets-skip
+const { data: result } = useUnstakingInfoWithPenalty({ params: { srcAddress, srcChainKey } });
+if (result?.ok) {
+  const { requestsWithPenalty } = result.value;   // each adds penalty, penaltyPercentage, claimableAmount
+}
+```
+
+## Pitfalls
+
+1. **`useStakeRatio` returns a tuple, not a single bigint.** v1 was simpler; v2 returns `[xSodaAmount, previewDepositAmount]`. Adjust render code.
+2. **`useStakingInfo` is unwrapped (not Result), but `useUnstakingInfo` IS Result-wrapped.** Asymmetric — check the integration docs per hook.
+3. **`useUnstakingInfoWithPenalty` returns an object with `requestsWithPenalty` array embedded** — don't `.value.map(...)`, use `.value.requestsWithPenalty.map(...)`.
+4. **Unstake has a waiting period.** Display via `useStakingConfig().unstakingPeriod`. Shows up in v1 too, but the read shape may have changed.
+5. **Instant unstake bypasses the waiting period but pays slippage.** Use `useInstantUnstakeRatio` to preview; set `minAmount` in params for slippage protection.
+
+## Cross-references
+
+- [`../../integration/features/staking.md`](../../integration/features/staking.md) — v2 reference.
+- [`../../integration/recipes/staking.md`](../../integration/recipes/staking.md) — full v2 worked example.
+- [`../../../../sdk/ai-exported/migration/features/staking.md`](../../../../sdk/ai-exported/migration/features/staking.md) — underlying SDK staking migration.