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

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

@@ -1,139 +0,0 @@
-# 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. **Position / aToken-balance hooks renamed `address` → `userAddress`.** Applies to `useUserFormattedSummary`, `useUserReservesData`, **and `useATokensBalances`** (which also drops `spokeProvider` and adds a required `spokeChainKey` alongside `aTokens` + `userAddress`). `useAToken` is unaffected — it takes only `{ aToken }`.
-
-## 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'`). **All four MM action params share an identical field shape** — only the `action` literal differs:
-
-```ts
-// @ai-snippets-skip
-// MoneyMarketSupplyParams<K> | MoneyMarketBorrowParams<K> | MoneyMarketWithdrawParams<K> | MoneyMarketRepayParams<K>
-{
-  srcChainKey: K;                  // required — where the user signs / funds come from
-  srcAddress: string;              // required — user's spoke-side address on srcChainKey
-  token: string;                   // token on srcChainKey (supply/repay) or on dstChainKey (borrow/withdraw)
-  amount: bigint;
-  action: 'supply' | 'borrow' | 'withdraw' | 'repay';
-  dstChainKey?: SpokeChainKey;     // optional — defaults to srcChainKey (same-chain)
-  dstAddress?: string;             // optional — defaults to srcAddress (same-chain)
-}
-```
-
-Cross-chain delivery via `dstChainKey` / `dstAddress` is supported on **all four** actions, not just borrow/repay. Omit both for same-chain operations.
-
-> **Porting note** — v2 does NOT use `fromChainKey` / `fromAddress` / `toChainKey` / `toAddress` (or `fromChainId` / `toChainId`) on any MM action. Borrow and repay use the **same** `src*` / `dst*` field names as supply and withdraw — the v2 type system unified the cross-chain shape across all four actions. If your v1 call sites or app types carry `from*` / `to*` naming for the spend-chain vs. debt-chain, rename to `src*` / `dst*` (e.g. `fromChainKey → srcChainKey`, `toChainKey → dstChainKey`). See the SDK migration doc cross-link below for explicit borrow/repay diff examples.
-
-### `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 } });
-```
-
-Same shape on `useUserReservesData`.
-
-### `useATokensBalances`
-
-```diff
-- const { data: balances } = useATokensBalances({ aTokens, spokeProvider, userAddress });
-+ const { data: balances } = useATokensBalances({
-+   params: {
-+     aTokens,                                  // readonly Address[]
-+     spokeChainKey,                            // SpokeChainKey — NOT `srcChainKey`
-+     userAddress,                              // string — spoke-side user address (renamed from `address` if you're porting from any earlier shape)
-+   },
-+ });
-+ // data: Map<Address, bigint> | undefined (already unwrapped — hook throws on SDK !ok)
-```
-
-Three things to verify when porting:
-
-- `spokeProvider` is gone — the hook derives the hub wallet internally from `(spokeChainKey, userAddress)` via `EvmHubProvider.getUserHubWalletAddress`.
-- The chain-key field is **`spokeChainKey`**, not `srcChainKey`. `src*` names belong to mutation params (`useSupply`/`useBorrow`/etc.) — read hooks for a single-chain position use `spokeChainKey`.
-- The user-address field is **`userAddress`**, not `address` — same rename as `useUserFormattedSummary` and `useUserReservesData`.
-
-`useAToken` (metadata-only) is unaffected by the user/chain renames — it takes only `{ aToken }`.
-
-## 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 delivery (all four actions)**: omit `dstChainKey` / `dstAddress` for same-chain. Don't pass `dstChainKey === srcChainKey` (let the default kick in). The field names are `src*` / `dst*` on **every** MM action — there is no `from*` / `to*` variant.
-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

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

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

@@ -1,133 +0,0 @@
-# Swap migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/swap.md`](../../integration/features/swap.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. **Drop `spokeProvider` from `useSwap` and `useSwapApprove` hook init.** Pass `walletProvider` (from `useWalletProvider({ xChainId: chainKey })`) into `mutate(vars)`.
-2. **`useSwapAllowance({ params: { payload, srcChainKey, walletProvider } })`** — query inputs all nest under `params` (no top-level `spokeProvider` or `walletProvider`); the SDK request goes under `params.payload`.
-3. **Approve hook return shape changed.** `{ approve, isLoading } = useSwapApprove(...)` → `{ mutateAsync: approve, isPending } = useSwapApprove()`.
-4. **`mutationFn` throws on SDK `!ok`.** Either wrap `mutateAsync` in `try/catch` or use `mutateAsyncSafe` for `Result<T>` branching.
-5. **Field on `Intent` read shape kept its name.** `Intent.srcChain` / `Intent.dstChain` are still `IntentRelayChainId` (bigint) — distinct from request-side `srcChainKey` / `dstChainKey` on action params.
-6. **`useStatus({ params: { intentTxHash } })` — single-object query shape.** v1's positional version is gone. Key was renamed `intentHash → intentTxHash`. Return is `Result<SolverIntentStatusResponse, SolverErrorResponse> | undefined` — branch on `data?.ok` before reading status fields.
-
-## Per-method delta
-
-### `useSwap` — execute swap
-
-```diff
-  function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
--   const swap = useSwap(spokeProvider);
-+   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-+   const { mutateAsyncSafe: swap, isPending } = useSwap();
-
-    const handleSwap = async () => {
-+     if (!walletProvider) return;
--     const result = await swap.mutateAsync({ params: intentParams });
--     if (result.ok) {
--       // v1: result.value was a TUPLE — destructure positionally
--       const [executionResponse] = result.value;
--       const txHash = executionResponse.intent_hash;
--       /* ... */
--     } else {
--       toast.error(result.error.message);
--     }
-+     const result = await swap({ params: intentParams, walletProvider });
-+     if (!result.ok) {
-+       toast.error(result.error instanceof Error ? result.error.message : 'Swap failed');
-+       return;
-+     }
-+     // v2: result.value is a NAMED OBJECT (SwapResponse) — destructure by name
-+     const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
-+     const intentHash = solverExecutionResponse.intent_hash;       // protocol-level intent id (v1 ≈ executionResponse.intent_hash)
-+     const spokeTxHash = intentDeliveryInfo.srcTxHash;             // on-chain tx hash on srcChainKey — use for tx-history display
-+     /* ... */
-    };
-  }
-```
-
-#### `SwapResponse` field map (`result.value`)
-
-| Field | Type | Use it for |
-|---|---|---|
-| `solverExecutionResponse` | `{ answer: 'OK'; intent_hash: Hex }` | Protocol-level intent identifier. **`solverExecutionResponse.intent_hash` is the v2 equivalent of v1's `executionResponse.intent_hash`.** Pass it to `useStatus({ params: { intentTxHash } })` to poll execution status. |
-| `intent` | `Intent` | Intent metadata (`intentId: bigint`, `creator`, tokens, amounts, `srcChain`/`dstChain` as `IntentRelayChainId` bigints). **No transaction hashes on this object** — don't read `intent.intent_hash` (does not exist) or `intent.tx_hash`. |
-| `intentDeliveryInfo` | `{ srcChainKey, srcTxHash, srcAddress, dstChainKey, dstTxHash, dstAddress }` | **On-chain transaction hashes.** `srcTxHash` is the spoke-chain tx on `srcChainKey` (the one that typically feeds a user-facing transaction history); `dstTxHash` is the delivery tx on `dstChainKey`. |
-
-**Porting `[executionResponse] = result.value` (v1 tuple) → v2:** rename to `{ solverExecutionResponse } = result.value`. Any `executionResponse.intent_hash` read becomes `solverExecutionResponse.intent_hash`. If the value was being used as the **transaction hash** in a transaction-history row (not as the intent identifier), switch to `intentDeliveryInfo.srcTxHash` instead — `intent_hash` and `srcTxHash` are not interchangeable.
-
-### `useSwapApprove` — return shape
-
-```diff
-- const { approve, isLoading, error } = useSwapApprove(spokeProvider);
-- await approve(intentParams);
-+ const { mutateAsync: approve, isPending, error } = useSwapApprove();
-+ await approve({ params: intentParams, walletProvider });
-```
-
-`isLoading` → `isPending` (React Query 5 convention).
-
-### `useSwapAllowance` — payload + srcChainKey + walletProvider all under `params`
-
-```diff
-- const { data: allowanceResult } = useSwapAllowance({ params: intentParams, spokeProvider });
-+ const { data: isApproved } = useSwapAllowance({
-+   params: { payload: intentParams, srcChainKey: ChainKeys.BSC_MAINNET, walletProvider },
-+ });
-+ // `data` is `boolean | undefined` (already unwrapped); no `.ok` branch needed.
-```
-
-### `useStatus` — single-object shape + param renamed `intentHash → intentTxHash`
-
-```diff
-- const { data: status } = useStatus(intentHash);
-+ const { data: status } = useStatus({ params: { intentTxHash } });
-+ // `data` is `Result<SolverIntentStatusResponse, SolverErrorResponse> | undefined` —
-+ // branch on `data?.ok` before reading `data.value.<fields>`.
-```
-
-### `useQuote` — single-object shape + SDK request nested under `params.payload`
-
-```diff
-- const { data: quote } = useQuote({
--   token_src: SRC_TOKEN,
--   token_dst: DST_TOKEN,
--   token_src_blockchain_id: BSC_MAINNET_CHAIN_ID,
--   token_dst_blockchain_id: ARBITRUM_MAINNET_CHAIN_ID,
--   amount,
--   quote_type: 'exact_input',
-- });
-+ const { data: quote } = useQuote({
-+   params: {
-+     payload: {
-+       token_src: SRC_TOKEN,
-+       token_dst: DST_TOKEN,
-+       token_src_blockchain_id: ChainKeys.BSC_MAINNET,
-+       token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
-+       amount,
-+       quote_type: 'exact_input',
-+     },
-+   },
-+ });
-```
-
-`SolverIntentQuoteRequest` shape unchanged. Two v2 changes: SDK request is nested under `params.payload` (not directly under `params`); constants renamed (`*_MAINNET_CHAIN_ID` → `ChainKeys.X_MAINNET`).
-
-### `useCreateLimitOrder` / `useCancelLimitOrder` / `useCancelSwap`
-
-Same shape changes as `useSwap` — drop `spokeProvider`, move domain inputs to `mutate(vars)`.
-
-## Pitfalls
-
-1. **`Intent.srcChain` / `Intent.dstChain` look like they should rename.** They didn't. Those are read-shape `IntentRelayChainId` (bigint), distinct from request-side `srcChainKey` / `dstChainKey`. Don't grep-replace.
-2. **`useStatus` polling default.** v2 polls every 3 s unconditionally once `intentTxHash` is supplied (it does not auto-stop on terminal states — your UI should disable rendering when no longer needed, or override `queryOptions.refetchInterval: false`). Port any v1 custom polling to `queryOptions.refetchInterval`.
-3. **`useQuote` data is `Result<T>`** — branch on `data?.ok` before reading `data.value.quoted_amount`.
-
-## Cross-references
-
-- [`../../integration/features/swap.md`](../../integration/features/swap.md) — v2 reference.
-- [`../../integration/recipes/swap.md`](../../integration/recipes/swap.md) — full v2 worked example.
-- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md), [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) — cross-cutting deltas.
-- [`../../../../sdk/ai-exported/migration/features/swap.md`](../../../../sdk/ai-exported/migration/features/swap.md) — underlying SDK swap migration.

package/ai-exported/migration/recipes.md

@@ -1,185 +0,0 @@
-# Migration recipes — `@sodax/dapp-kit` v1 → v2
-
-Codemods, adapters, and incremental migration patterns. Use these when full conversion in one pass isn't realistic or when you want to mechanize the boring parts.
-
-## Codemod 1: chain-id constants → ChainKeys
-
-```bash
-# From your consumer's repo root:
-find src -type f \( -name '*.ts' -o -name '*.tsx' \) | xargs sed -i '' -E 's/\b([A-Z_]+)_MAINNET_CHAIN_ID\b/ChainKeys.\1_MAINNET/g'
-```
-
-Then add `import { ChainKeys } from '@sodax/sdk'` (or `'@sodax/dapp-kit'` — both work) where needed. tsc will flag missing imports.
-
-For more sophisticated automation across many files, use ts-morph:
-
-```ts
-// @ai-snippets-skip
-// codemod-chain-ids.ts — run with `tsx codemod-chain-ids.ts`
-import { Project, SyntaxKind } from 'ts-morph';
-
-const project = new Project({ tsConfigFilePath: './tsconfig.json' });
-
-for (const file of project.getSourceFiles('src/**/*.{ts,tsx}')) {
-  let needsImport = false;
-
-  file.forEachDescendant((node) => {
-    if (node.getKind() === SyntaxKind.Identifier) {
-      const text = node.getText();
-      const m = text.match(/^([A-Z_]+)_MAINNET_CHAIN_ID$/);
-      if (m) {
-        node.replaceWithText(`ChainKeys.${m[1]}_MAINNET`);
-        needsImport = true;
-      }
-    }
-  });
-
-  if (needsImport && !file.getImportDeclaration('@sodax/sdk')?.getNamedImports().some(n => n.getName() === 'ChainKeys')) {
-    file.addImportDeclaration({ moduleSpecifier: '@sodax/sdk', namedImports: ['ChainKeys'] });
-  }
-}
-
-await project.save();
-```
-
-## Codemod 2: useSpokeProvider deletion (2-arg → 1-arg)
-
-`useSpokeProvider` is gone in v2. Replace with `useWalletProvider` from `@sodax/wallet-sdk-react`.
-
-v1 had **two positional args**: `useSpokeProvider(spokeChainId, walletProvider)`. v2 collapses to a single options object: `useWalletProvider({ xChainId })`. The second v1 argument is **dropped entirely** — v2 resolves the wallet provider from the wallet-sdk-react store internally based on `xChainId`. If your v1 code constructed a wallet provider separately to pass in, delete that construction code too.
-
-```diff
-- // v1 — 2 positional args (chainKey + walletProvider)
-- import { useSpokeProvider } from '@sodax/dapp-kit';
-- const spokeProvider = useSpokeProvider(srcChainId, walletProvider);
-
-+ // v2 — 1 options arg, no external walletProvider
-+ import { useWalletProvider } from '@sodax/wallet-sdk-react';
-+ const walletProvider = useWalletProvider({ xChainId: srcChainId });
-```
-
-A naive single-pass regex over `useSpokeProvider\(([^)]+)\)` eats both args and produces invalid `useWalletProvider({ xChainId: chainKey, walletProvider })`. Do the rewrite in two passes: first the call shape (drop the second positional arg), then the import (from `@sodax/dapp-kit` → `@sodax/wallet-sdk-react`). A small number of v1 callers used the single-arg form `useSpokeProvider(chainId)` — handle those separately since they don't have a second arg to drop.
-
-Update downstream consumers of `spokeProvider` to use `walletProvider` instead — usually inside `mutate(vars)` payloads or query hook params. The field name on payloads also renamed `spokeProvider:` → `walletProvider:` (see `@sodax/sdk/ai-exported/migration/checklist.md` step 7b).
-
-## Codemod 3: invalidate*Queries utilities deletion
-
-Most v1 consumers had `lib/invalidate*Queries.ts` files. Hook-owned invalidations make these obsolete:
-
-```bash
-# Find them.
-grep -rE '(invalidateMmQueries|invalidateSwapQueries|invalidateBridgeQueries|invalidate\w+Queries)' src/
-
-# For each call site, delete the call. The mutation hook handles invalidation.
-```
-
-If you have a custom invalidation that dapp-kit's hooks don't know about (e.g. your own analytics view), move it into `mutationOptions.onSuccess`:
-
-```diff
-  const { mutateAsync: supply } = useSupply({
-+   mutationOptions: {
-+     onSuccess: async (data, vars) => {
-+       await queryClient.invalidateQueries({ queryKey: ['my-app', 'analytics'] });
-+     },
-+   },
-  });
-- await supply({ params, spokeProvider });
-- invalidateMmQueries(queryClient, ...);   // delete
-- await queryClient.invalidateQueries({ queryKey: ['my-app', 'analytics'] });   // delete
-+ await supply({ params, walletProvider });
-```
-
-## Adapter: Result<T>-shape adapter for legacy error consumers
-
-If your consumer code has a helper that branches on a v1 error shape (e.g. `error.code` from old per-feature classes), the minimal change is to map v2 onto v1 at the boundary:
-
-```ts
-// adapters/v1ErrorShape.ts
-import { isSodaxError } from '@sodax/dapp-kit';
-
-// V1 shape: { code, message, data?: { error } }
-export function adaptToV1ErrorShape(error: unknown): { code?: string; message?: string; data?: { error?: unknown } } | null {
-  if (!error) return null;
-  if (isSodaxError(error)) {
-    return {
-      code: error.code,
-      message: error.message,
-      data: { error: error.cause },
-    };
-  }
-  if (error instanceof Error) return { code: 'UNKNOWN', message: error.message };
-  if (typeof error === 'object') return error as { code?: string; message?: string };
-  return null;
-}
-```
-
-Then your existing v1-shape error handlers keep working:
-
-```ts
-// @ai-snippets-skip
-const { mutateAsync: swap } = useSwap();
-try {
-  await swap({ params, walletProvider });
-} catch (e) {
-  const adapted = adaptToV1ErrorShape(e);
-  if (adapted?.code === 'INTENT_CREATION_FAILED' /* etc. */) { /* ... */ }
-}
-```
-
-Plan to delete the adapter once you've converted error-handling code site-by-site.
-
-## Incremental migration: feature-by-feature
-
-If the codebase is too large for a single-pass migration, you can convert one feature at a time. The pattern:
-
-1. **Pick a low-traffic feature first** (e.g. recovery, partner). It limits blast radius if something breaks.
-2. **Convert that feature's call sites and approve hooks**.
-3. **Run the app, smoke-test the feature**.
-4. **Move on to the next feature**.
-
-The catch: SDK-level changes are global (e.g. chain-key terminology). You can't do `xChainId` on `XToken` for swap and `chainKey` for staking — both run on the same SDK. Plan to do all SDK-level migrations in one pass first (Phase 1 + 2 of [`checklist.md`](checklist.md)), then per-feature hook-call-site work in any order (Phase 3+).
-
-## Incremental migration: keeping v1 wrappers temporarily
-
-If you have many call sites that share a custom wrapper hook (e.g. one your codebase named `useLegacySwap` calling v1 dapp-kit underneath), you can rewrite the wrapper's body to call v2 internally while keeping the wrapper's name and surface intact. Call sites stay unchanged.
-
-```tsx
-// Custom wrapper that your codebase already has (with a project-specific name).
-// Rewrite its body to call v2 dapp-kit internally; preserve the surface so
-// existing call sites don't change yet.
-
-import { useSwap } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import type { CreateIntentParams } from '@sodax/sdk';
-
-// Function name starts with `use` because it calls React hooks (`useWalletProvider`,
-// `useSwap`). Inside a component, call it like any other hook.
-export function useLegacySwapAdapter(spokeProvider: unknown, params: CreateIntentParams) {
-  const walletProvider = useWalletProvider(/* derive chainKey from spokeProvider */);
-  const m = useSwap();
-  return {
-    swap: async () => {
-      if (!walletProvider) throw new Error('wallet not connected');
-      // Adapt v2 throw-on-fail back to v1 success-with-Result shape:
-      try {
-        const value = await m.mutateAsync({ params, walletProvider });
-        return { ok: true, value };
-      } catch (e) {
-        return { ok: false, error: e };
-      }
-    },
-    isLoading: m.isPending,
-    error: m.error,
-  };
-}
-```
-
-Then convert call sites at your own pace. Delete the wrapper once you're done.
-
-## Cross-references
-
-- [`README.md`](README.md) — overview + glossary.
-- [`checklist.md`](checklist.md) — top-down migration checklist.
-- [`ai-rules.md`](ai-rules.md) — DO / DO NOT for the agent doing the migration.
-- [`breaking-changes/`](breaking-changes/) — cross-cutting deltas in detail.
-- [`features/`](features/) — per-feature porting playbooks.

package/ai-exported/migration/reference/README.md

@@ -1,15 +0,0 @@
-# Migration reference — `@sodax/dapp-kit` v1 → v2
-
-Lookup tables for the v1 → v2 delta. Skim during migration to confirm specific renames or removals.
-
-| File | What's in it |
-|---|---|
-| [`deleted-hooks.md`](deleted-hooks.md) | v1 hooks that no longer exist in v2 (`useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`-style API). |
-| [`renamed-hooks.md`](renamed-hooks.md) | Hooks whose name or signature changed (rare — most renames are field-level). |
-| [`error-shape-crosswalk.md`](error-shape-crosswalk.md) | v1 error class names → v2 `SodaxError<C>` mapping; how thrown errors look at the consumer level. |
-
-For SDK-level reference (deleted exports, renames, error code crosswalk), see [`../../../../sdk/ai-exported/migration/reference/`](../../../../sdk/ai-exported/migration/reference/) — the underlying SDK has its own reference tree.
-
-## Pair
-
-This `migration/reference/` tree mirrors [`../../integration/reference/`](../../integration/reference/) (which documents v2 directly). When you need both "what does v2 do" and "what changed from v1" — open both.