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

package/ai-exported/migration/breaking-changes/querykey-conventions.md

@@ -1,108 +0,0 @@
-# queryKey conventions — v1 → v2
-
-This is a low-priority migration item — it only matters if your code grafts onto dapp-kit's cache invalidation (e.g. you fetch a related query and want it to be invalidated when dapp-kit's mutation fires).
-
-If your app doesn't share queryKey shapes with dapp-kit, skip this file. The shape changes are a nicety, not a blocker — your existing keys still work for your own queries.
-
-## What changed
-
-v1 was ad-hoc; v2 is canonical.
-
-| Aspect | v1 | v2 |
-|---|---|---|
-| First segment | Free-form (`'xBalances'`, `'btc-balance'`, `'api'`) | Feature directory name (`'shared'`, `'bitcoin'`, `'backend'`) |
-| Casing | Mixed (kebab-case in places) | camelCase exclusively |
-| Bigint values | Inconsistent | Always `.toString()` before going into a key |
-| Default `mutationKey` | Many hooks had none | Every hook has a default; consumer can override |
-
-## Why align?
-
-Your custom queries can be invalidated by dapp-kit's mutations if they share the prefix:
-
-```ts
-// @ai-snippets-skip — illustrative; `queryFn` is shown as `...` placeholder
-// Your custom query
-const { data: customAnalytics } = useQuery({
-  queryKey: ['shared', 'xBalances', xChainId, address, 'with-analytics'],
-  queryFn: ...,
-});
-
-// Dapp-kit's `useSwap` invalidates `['shared', 'xBalances', srcChainKey]`,
-// which is a PREFIX of your key — your query gets invalidated automatically.
-```
-
-If your key starts with something else (e.g. `['my-app', 'xBalances', ...]`), dapp-kit's invalidation won't touch it — you'd need to wire your own invalidation in `mutationOptions.onSuccess`.
-
-## Migration patterns
-
-### Sweep your custom queryKeys
-
-If your app has custom queries that overlap with dapp-kit's domains, rename them to match v2 conventions:
-
-<!-- ai-keys-allow — v1 keys shown for migration context; the `-` lines are v1 shapes, not real v2 source keys -->
-
-```diff
-  const { data } = useQuery({
--   queryKey: ['xBalances', address, ...],
-+   queryKey: ['shared', 'xBalances', xChainId, [token], address],
-    queryFn: ...,
-  });
-
-  const { data } = useQuery({
--   queryKey: ['btc-balance', address],
-+   queryKey: ['bitcoin', 'balance', address],
-    queryFn: ...,
-  });
-  <!-- ai-keys-allow -->
-
-  const { data } = useQuery({
--   queryKey: ['api', 'mm', userAddress],
-+   queryKey: ['backend', 'mm', userAddress],
-    queryFn: ...,
-  });
-```
-
-### If you previously overrode dapp-kit's queryKeys
-
-v1 query hooks accepted `queryKey` overrides. v2 hooks own their queryKeys — the option is gone.
-
-```diff
-- const { data } = useUserReservesData({
--   spokeProvider,
--   address,
--   queryKey: ['my-app-mm-positions'],   // v1
-- });
-+ // v2 — drop the queryKey override; if you needed an alias, write your own useQuery.
-+ const { data } = useUserReservesData({
-+   params: { spokeChainKey, userAddress: address },
-+ });
-```
-
-### If you had your own `mutationKey` defaults
-
-v1 mutation hooks often had no default `mutationKey` — consumers set one in `mutationOptions`. v2 hooks set a sensible default (e.g. `['swap']`, `['mm', 'supply']`) — drop redundant overrides:
-
-```diff
-  const { mutateAsync: swap } = useSwap({
-    mutationOptions: {
--     mutationKey: ['swap'],   // already the default in v2
-      retry: 5,
-    },
-  });
-```
-
-## Per-feature conventions
-
-See [`../../integration/reference/querykey-conventions.md`](../../integration/reference/querykey-conventions.md) for the full per-feature key tables. Use that as the reference when aligning your own keys.
-
-## Done criteria
-
-<!-- ai-keys-allow — the bare xBalances key below is shown as a v1-style anti-example -->
-- [ ] No custom queryKeys overlapping with dapp-kit's domains using non-canonical first segments (e.g. `['xBalances', ...]` should become `['shared', 'xBalances', ...]`).
-- [ ] No `queryKey` overrides in `useFooQuery({ ..., queryKey: [...] })` patterns (the option is gone).
-- [ ] Optional: drop redundant default-`mutationKey` overrides in `mutationOptions`.
-
-## Cross-references
-
-- [`../../integration/reference/querykey-conventions.md`](../../integration/reference/querykey-conventions.md) — full canonical conventions + per-feature key tables.
-- [`hook-signatures.md`](hook-signatures.md) — broader hook-shape changes.

package/ai-exported/migration/breaking-changes/result-handling.md

@@ -1,211 +0,0 @@
-# Result<T> handling — v1 → v2
-
-The most subtle breakage: `Result<T>` semantics inside dapp-kit's mutation pipeline inverted in v2.
-
-## The semantic shift
-
-| | v1 | v2 |
-|---|---|---|
-| `mutationFn` return | `Result<T>` | unwrapped `T`; throws on `!ok` |
-| `mutation.data` shape | `Result<T>` (`{ ok, value }` or `{ ok, error }`) | unwrapped `T` (e.g. `SwapResponse`, `TxHashPair`) |
-| Where to branch | Inside `onSuccess`: `if (data.ok) ...` | Branch on `mutation.error` / `mutation.isError`, OR use `mutateAsyncSafe` |
-| `onSuccess` fires on SDK `!ok`? | **Yes** (success path) — required `data.ok` check inside | **No** — only on actual success |
-| `onError` fires on SDK `!ok`? | No | **Yes** — engages React Query's native error model |
-| `retry` config | Ignored on SDK `!ok` | Engages on SDK `!ok` |
-| Devtools error display | Empty | Shows the SDK error |
-
-The shift makes React Query's native error model engage for SDK failures, instead of treating every SDK call as "successful but maybe with an error inside."
-
-## Why the change
-
-In v1:
-- Consumers had to remember to branch on `data.ok` inside every `onSuccess`. Forgetting was easy and silent (success logic ran on a failed swap).
-- Hook-owned invalidations fired on SDK failure too, burning RPC traffic on every failed click.
-- Devtools showed every mutation as "success" even when the SDK returned `{ ok: false }`.
-- `retry` config didn't engage (the request didn't "fail" from React Query's perspective).
-
-v2's `mutationFn` calls `unwrapResult(await sodax.<feature>.<method>(vars))`:
-- `Result<T>` `{ ok: true; value }` → returns `value` (the unwrapped success type).
-- `Result<T>` `{ ok: false; error }` → throws `error`.
-
-This makes `isError`, `error`, `onError`, `retry`, devtools all work correctly out of the box.
-
-## Migration patterns
-
-### Pattern 1: success-path branching → drop the check
-
-```diff
-  const { mutateAsync: swap } = useSwap({
-    mutationOptions: {
--     onSuccess: (data, vars) => {
--       if (data.ok) {
--         showSuccess(data.value.intent);
--       } else {
--         showError(data.error);
--       }
--     },
-+     onSuccess: (data, vars) => {
-+       // data is now SwapResponse — already-unwrapped success value.
-+       showSuccess(data.intent);
-+     },
-+     onError: (error) => {
-+       showError(error);
-+     },
-    },
-  });
-```
-
-`onSuccess` only fires on actual success now; `onError` fires on SDK failure. Move the failure logic to `onError`.
-
-### Pattern 2: imperative `mutateAsync` → wrap in try/catch
-
-```diff
-  const { mutateAsync: swap } = useSwap();
-- const result = await swap({ params, spokeProvider });
-- if (result.ok) {
--   navigate('/done');
-- } else {
--   toast.error(result.error.message);
-- }
-+ try {
-+   const result = await swap({ params, walletProvider });
-+   navigate('/done');
-+ } catch (e) {
-+   toast.error(e instanceof Error ? e.message : 'Swap failed');
-+ }
-```
-
-v2's `mutateAsync` rejects on SDK `!ok` — `try/catch` is mandatory. If you forget `try/catch`, an unhandled rejection lands in the global handler.
-
-### Pattern 3: imperative `mutateAsync` → use `mutateAsyncSafe` (recommended)
-
-If you prefer the v1 `Result<T>` ergonomics without exception flow, use `mutateAsyncSafe` — it never rejects:
-
-```diff
-- const { mutateAsync: swap } = useSwap();
-- const result = await swap({ params, spokeProvider });
-- if (result.ok) {
--   navigate('/done');
-- } else {
--   toast.error(result.error.message);
-- }
-+ const { mutateAsyncSafe: swap } = useSwap();
-+ const result = await swap({ params, walletProvider });
-+ if (!result.ok) {
-+   toast.error(result.error instanceof Error ? result.error.message : 'Swap failed');
-+   return;
-+ }
-+ navigate('/done');
-```
-
-`mutateAsyncSafe` re-packs the throw inside `mutationFn` back into `Result<TData>`. Same React Query state under the hood (`isError`, `error`, devtools all work). Recommended for sequenced flows.
-
-### Pattern 4: sequenced flow (approve + execute)
-
-```diff
-- // v1: branch on every step
-- const result1 = await approve({ params, spokeProvider });
-- if (!result1.ok) { toast(result1.error); return; }
-- const result2 = await action({ params, spokeProvider });
-- if (!result2.ok) { toast(result2.error); return; }
-- navigate('/done');
-
-+ // v2: same shape, but Result is from mutateAsyncSafe; walletProvider in mutate(vars)
-+ const result1 = await approve({ params, walletProvider });
-+ if (!result1.ok) { toast(result1.error.message); return; }
-+ const result2 = await action({ params, walletProvider });
-+ if (!result2.ok) { toast(result2.error.message); return; }
-+ navigate('/done');
-```
-
-Just swap `mutateAsync` → `mutateAsyncSafe` and `spokeProvider` → `walletProvider`. The branching pattern stays nearly identical — same `result.ok` check.
-
-## Edge case: `data` consumed in render
-
-```diff
-  function SwapResult() {
-    const { data, isError } = useSwap();
--   if (data?.ok) return <p>Success: {data.value.intent.intentHash}</p>;
--   if (data && !data.ok) return <p>Error: {data.error.message}</p>;
-+   const { data, error, isError } = useSwap();
-+   if (data) return <p>Success: {data.intent.intentHash}</p>;
-+   if (isError && error) return <p>Error: {error.message}</p>;
-    return null;
-  }
-```
-
-`data` is the unwrapped success value or `undefined`. `error` is the SDK error (or `null`). `isError` is the React Query flag.
-
-## Edge case: `mutation.error` consumers
-
-In v1, `mutation.error` only fired for actual exceptions (e.g. missing `walletProvider`, invalid input). In v2, it ALSO fires for SDK `!ok`. Audit all places that read `mutation.error` to ensure the new firings are appropriate.
-
-```ts
-// @ai-snippets-skip
-// v1: error was rare (only thrown exceptions)
-{mutation.error && <p>Unexpected error: {mutation.error.message}</p>}
-
-// v2: error includes SDK !ok
-// You may want to distinguish, e.g. check isSodaxError(error)
-{mutation.error && (
-  isSodaxError(mutation.error)
-    ? <p>SDK error ({mutation.error.code}): {mutation.error.message}</p>
-    : <p>Unexpected error: {mutation.error.message}</p>
-)}
-```
-
-`isSodaxError` is exported from `@sodax/dapp-kit` (re-exported from `@sodax/sdk`).
-
-## Edge case: query hooks returning `Result<T>` as data
-
-A small set of query hooks for SDK methods that can fail in expected ways (e.g. quote unavailable, status not yet known) surface the `Result<T>` directly to the consumer as `data` rather than unwrapping. This is intentional — read failures are part of the data flow, not exception flow.
-
-**Result-wrapped query hooks** (data is `Result<T> | undefined` — branch on `data?.ok`):
-
-```tsx
-// @ai-snippets-skip
-// useQuote — SDK request goes under params.payload
-const { data: quoteResult } = useQuote({ params: { payload: quotePayload } });
-if (quoteResult?.ok) {
-  const quote = quoteResult.value;
-}
-
-// useStatus — key is `intentTxHash`, NOT `intentHash`
-const { data: statusResult } = useStatus({ params: { intentTxHash } });
-if (statusResult?.ok) {
-  const status = statusResult.value;
-}
-```
-
-**Most other query hooks unwrap** the SDK Result inside the hook (`if (!result.ok) throw result.error`), so `data` is the success value directly and React Query's native error model (`isError`/`error`/`onError`/`retry`) engages on SDK failure. Examples:
-
-```tsx
-// @ai-snippets-skip
-// useStakingInfo, useUnstakingInfo, useUnstakingInfoWithPenalty,
-// useStakingConfig, useStakeRatio, useInstantUnstakeRatio, useConvertedAssets,
-// all three staking allowance hooks (useStakeAllowance/useUnstakeAllowance/useInstantUnstakeAllowance),
-// useMMAllowance, useSwapAllowance, useDexAllowance,
-// all MM reserves + position hooks, all DEX read hooks except where noted —
-// data is the unwrapped value. NO `.ok` / `.value` branching.
-const { data: info, isError, error } = useStakingInfo({ params: { srcAddress, srcChainKey } });
-// info is StakingInfo | undefined — read fields directly: info?.totalStaked
-```
-
-**`useBridgeAllowance` is special** — it returns `false` on SDK `!ok` (does NOT throw). The data is still `boolean | undefined`, just biased toward "not approved" on lookup error.
-
-For per-hook truth, check the per-feature reference (`integration/features/<x>.md`).
-
-## Done criteria for this category
-
-- [ ] No `data.ok` checks inside mutation `onSuccess` callbacks.
-- [ ] No `result.ok` branching after `mutateAsync(...)` (it now throws — either `try/catch` or use `mutateAsyncSafe`).
-- [ ] All `mutateAsync` calls are wrapped in `try/catch` OR replaced with `mutateAsyncSafe`.
-- [ ] `onError` callbacks audit — they now fire for SDK `!ok` (which they didn't before).
-- [ ] Mutation `mutation.error` reads — same audit.
-
-## Cross-references
-
-- [`hook-signatures.md`](hook-signatures.md) — the structural changes (provider stack, hook shapes, approve returns).
-- [`../../integration/recipes/mutation-error-handling.md`](../../integration/recipes/mutation-error-handling.md) — full v2 patterns for picking call shapes.
-- [`../../integration/architecture.md`](../../integration/architecture.md) § "SDK Result handling" — full design rationale.
-- [`../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md`](../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md) — SDK-side `Result<T>` migration (the underlying contract that dapp-kit translates).

package/ai-exported/migration/breaking-changes/sdk-leakage.md

@@ -1,165 +0,0 @@
-# SDK leakage — v1 → v2
-
-Some v1 dapp-kit migration items are really *SDK* migrations that surface through dapp-kit's hook signatures. Each is documented in detail in the SDK's migration tree — this file summarizes what you'll see at the dapp-kit layer and links out for the full picture.
-
-## chain-key terminology
-
-The SDK renamed `xChainId` / `srcChainId` / `dstChainId` to `chainKey` / `srcChainKey` / `dstChainKey` on token shapes and request params. In dapp-kit, this surfaces in:
-
-```diff
-- // useGetBridgeableTokens — v1 took chain ids
-- useGetBridgeableTokens(BASE_MAINNET_CHAIN_ID, POLYGON_MAINNET_CHAIN_ID, '0x...');
-+ // v2 takes chain keys via the canonical query shape
-+ useGetBridgeableTokens({ params: { from: ChainKeys.BASE_MAINNET, to: ChainKeys.POLYGON_MAINNET, token: '0x...' } });
-```
-
-```diff
-- // bridge params — v1
-- await bridge({ params: { srcChainId: BASE_MAINNET_CHAIN_ID, dstChainId: POLYGON_MAINNET_CHAIN_ID, /* ... */ } });
-+ // v2
-+ await bridge({ params: { srcChainKey: ChainKeys.BASE_MAINNET, dstChainKey: ChainKeys.POLYGON_MAINNET, /* ... */ }, walletProvider });
-```
-
-```diff
-- // XToken read shape — v1
-- const chainId = token.xChainId;
-+ // v2
-+ const chainKey = token.chainKey;
-```
-
-**Note:** `useXBalances` request params still take `xChainId` (the field name stayed for the cross-chain abstraction it overlays). This is distinct from the renamed token-side `chainKey`. Don't conflate them.
-
-**Note:** `Intent.srcChain` / `Intent.dstChain` (read shape) kept their names. They're `IntentRelayChainId` (bigints), distinct from request-side `srcChainKey` / `dstChainKey`. Don't blanket grep-replace.
-
-Full SDK-level detail: [`../../../../sdk/ai-exported/migration/breaking-changes/type-system.md`](../../../../sdk/ai-exported/migration/breaking-changes/type-system.md).
-
-## Required `srcChainKey` + `srcAddress` on action params
-
-v1 mutation params were minimal (`{ token, amount, action }`). v2 added required `srcChainKey` + `srcAddress` to every feature's action params. The chain key drives spoke routing internally; the address is the user's spoke-side address.
-
-```diff
-- // v1
-- await supply({ params: { token, amount, action: 'supply' } });
-+ // v2
-+ await supply({
-+   params: {
-+     srcChainKey: ChainKeys.BASE_MAINNET,
-+     srcAddress: '0x...',                  // NEW: required
-+     token,
-+     amount,
-+     action: 'supply',
-+   },
-+   walletProvider,
-+ });
-```
-
-Same applies to `useBorrow`, `useWithdraw`, `useRepay`, `useStake`, `useUnstake`, `useBridge`, `useDexDeposit`, `useDexWithdraw`, etc. — anywhere the SDK now requires it.
-
-Full SDK-level detail: [`../../../../sdk/ai-exported/migration/features/`](../../../../sdk/ai-exported/migration/features/) — each feature's migration file lists the required new fields.
-
-## `*_MAINNET_CHAIN_ID` constants gone
-
-v1 exported individual constants (`BSC_MAINNET_CHAIN_ID`, `BASE_MAINNET_CHAIN_ID`, etc.). v2 replaces them with the `ChainKeys.*` namespace.
-
-```diff
-- import { BSC_MAINNET_CHAIN_ID, BASE_MAINNET_CHAIN_ID } from '@sodax/sdk';
-+ import { ChainKeys } from '@sodax/sdk';
-
-- const chainKey = BSC_MAINNET_CHAIN_ID;
-+ const chainKey = ChainKeys.BSC_MAINNET;
-```
-
-Codemod with sed:
-
-```bash
-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`) where needed.
-
-Full SDK-level detail: [`../../../../sdk/ai-exported/migration/breaking-changes/type-system.md`](../../../../sdk/ai-exported/migration/breaking-changes/type-system.md).
-
-## `SodaxConfig` reshape — `rpcConfig` → `chains`
-
-`SodaxProvider`'s config prop is `DeepPartial<SodaxConfig>`. The SDK renamed/restructured the config:
-
-```diff
-- <SodaxProvider rpcConfig={{
--   sonic: 'https://sonic-rpc.publicnode.com',
--   '0xa86a.avax': 'https://...',
-- }}>
-+ <SodaxProvider config={{
-+   chains: {
-+     [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
-+     [ChainKeys.AVALANCHE_MAINNET]: { rpcUrl: 'https://...' },
-+   },
-+ }}>
-```
-
-Other v1 fields renamed or restructured:
-
-| v1 | v2 |
-|---|---|
-| `rpcConfig` | `chains[ChainKeys.X]: { rpcUrl }` |
-| `backendApi: { url }` | `api: { baseURL }` |
-| `swaps: { intentsContract, ... }` | Split: `solver: { intentsContract, ... }` for endpoints; `swaps: SwapsConfig` for supported tokens |
-| `hubProviderConfig` | `hub: HubConfig` |
-
-Full SDK-level detail: [`../../../../sdk/ai-exported/migration/breaking-changes/architecture.md`](../../../../sdk/ai-exported/migration/breaking-changes/architecture.md) (Appendix B).
-
-## Error class
-
-The SDK consolidated 7+ per-feature error classes (`MoneyMarketError<Code>`, `IntentError<Code>`, `StakingError<Code>`, `BridgeError<Code>`, `MigrationError<Code>`, etc.) into a single canonical `SodaxError<C>`.
-
-If your dapp-kit consumer code catches errors from mutations and uses `instanceof XxxError`, those checks are now broken:
-
-```diff
-- // v1
-- catch (e) {
--   if (e instanceof MoneyMarketError) {
--     console.error('MM-specific:', e.code);
--   }
-- }
-
-+ // v2
-+ catch (e) {
-+   if (isSodaxError(e) && e.feature === 'moneyMarket') {
-+     console.error('MM-specific:', e.code);
-+   }
-+ }
-```
-
-`isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to 13 reason-only codes.
-
-Full SDK-level detail: [`../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md`](../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md).
-
-## `Result<T>` type and propagation
-
-The SDK's `Result<T>` type is the same in v1 and v2. What changed is **where it's returned vs unwrapped**:
-
-| | v1 | v2 |
-|---|---|---|
-| SDK service method return | `Result<T>` | `Result<T>` (unchanged) |
-| dapp-kit `mutationFn` return | `Result<T>` | unwrapped `T` (throws on `!ok`) |
-| Consumer's `mutation.data` | `Result<T>` | unwrapped `T` |
-
-So at the SDK level, `Result<T>` semantics didn't change. But at the dapp-kit level, the unwrap point moved into the hook. See [`result-handling.md`](result-handling.md) for the full picture.
-
-## Other SDK-level migrations
-
-These are unlikely to leak through hook signatures unless your app reaches into the SDK directly via `useSodaxContext()`:
-
-- **`*SpokeProvider` classes deleted** — the chain key drives spoke routing; no provider classes to construct. dapp-kit consumers never see these (you'd already be using `useSpokeProvider` which is gone).
-- **`ConfigService` replaces static lookup tables** — `hubAssets`, `moneyMarketSupportedTokens`, `SodaTokens` globals are gone. Use `sodax.config.*` (which dapp-kit's hooks already do internally).
-- **`WalletProviderSlot<K, Raw>` discriminated union** — a TypeScript-level construct; `walletProvider` is the typical consumer-facing shape.
-
-For the full SDK migration playbook, start at [`../../../../sdk/ai-exported/migration/README.md`](../../../../sdk/ai-exported/migration/README.md).
-
-## Cross-references
-
-- [`../../../../sdk/ai-exported/migration/README.md`](../../../../sdk/ai-exported/migration/README.md) — full SDK migration overview.
-- [`../../../../sdk/ai-exported/migration/breaking-changes/type-system.md`](../../../../sdk/ai-exported/migration/breaking-changes/type-system.md) — type renames + ChainKeys.
-- [`../../../../sdk/ai-exported/migration/breaking-changes/architecture.md`](../../../../sdk/ai-exported/migration/breaking-changes/architecture.md) — `*SpokeProvider`, ConfigService, SodaxConfig reshape.
-- [`../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md`](../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md) — `Result<T>` + error class consolidation.
-- [`hook-signatures.md`](hook-signatures.md) — dapp-kit-only hook-shape changes.
-- [`result-handling.md`](result-handling.md) — dapp-kit-only `Result<T>` unwrap-point shift.

package/ai-exported/migration/checklist.md

@@ -1,89 +0,0 @@
-# Migration checklist — `@sodax/dapp-kit` v1 → v2
-
-Top-down cross-cutting checklist. Walk it in order — each step makes later ones tractable.
-
-## Phase 1 — provider stack and imports
-
-- [ ] **Update `SodaxProvider` config shape.** `rpcConfig: { sonic: '...', ... }` → `chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: '...' } }`. See [`breaking-changes/hook-signatures.md`](breaking-changes/hook-signatures.md) § Provider stack.
-- [ ] **Replace `new QueryClient()` with `createSodaxQueryClient()`** (optional but recommended — gives you global mutation observability).
-- [ ] **Drop any `@sodax/types` dependency** from `package.json`. Re-exported via `@sodax/sdk` (which dapp-kit re-exports). Run `pnpm install` after.
-- [ ] **Import statement codemod.**
-  - `useSpokeProvider` import → delete the import line.
-  - `BSC_MAINNET_CHAIN_ID` (and the 14 other `*_MAINNET_CHAIN_ID` constants) → `ChainKeys.X_MAINNET`.
-  - Any deep-import from `@sodax/dapp-kit/dist/...` → import from `@sodax/dapp-kit` root.
-
-## Phase 2 — mechanical sweeps
-
-- [ ] **Delete every `useSpokeProvider(...)` call.** The `walletProvider` from `useWalletProvider({ xChainId: chainKey })` flows directly into `mutate(vars)`. See [`reference/deleted-hooks.md`](reference/deleted-hooks.md).
-- [ ] **`*_MAINNET_CHAIN_ID` → `ChainKeys.X_MAINNET`.** Codemod with sed:
-
-   ```bash
-   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'
-   ```
-
-- [ ] **`xChainId` → `chainKey` on `XToken`.** Be careful — only on the read shape. The `useXBalances` hook still takes `xChainId` as a request param (intentional naming for the cross-chain abstraction). See [`breaking-changes/sdk-leakage.md`](breaking-changes/sdk-leakage.md).
-
-## Phase 3 — hook-call-site rewrites (per feature)
-
-For each feature your app uses, walk the matching `migration/features/<feature>.md`:
-
-- [ ] [`features/swap.md`](features/swap.md) — swap call sites.
-- [ ] [`features/money-market.md`](features/money-market.md) — supply / borrow / withdraw / repay.
-- [ ] [`features/staking.md`](features/staking.md) — stake / unstake / claim.
-- [ ] [`features/bridge.md`](features/bridge.md) — bridge.
-- [ ] [`features/dex.md`](features/dex.md) — deposit / supply liquidity / etc.
-- [ ] [`features/migration.md`](features/migration.md) — ICX / bnUSD / BALN. **Note:** v1's `useMigrate(spokeProvider)` is gone; v2 has 6 per-action hooks.
-- [ ] [`features/bitcoin.md`](features/bitcoin.md) — Radfi.
-- [ ] [`features/auxiliary-services.md`](features/auxiliary-services.md) — partner, recovery, backend queries, shared utilities.
-
-The cross-cutting pattern at every call site:
-
-1. **Hook init**: `useFoo(spokeProvider, params)` → `useFoo()` or `useFoo({ mutationOptions })`. No domain inputs at hook init.
-2. **Mutation invocation**: `mutate(spokeProvider)` or `mutate()` → `mutate({ params, walletProvider })`. ALL domain inputs flow through here.
-3. **Approve hooks**: `const { approve, isLoading } = useFooApprove(spokeProvider)` → `const { mutateAsync: approve, isPending } = useFooApprove()`.
-4. **Query hooks**: `useFoo(arg1, arg2)` → `useFoo({ params: { ... }, queryOptions: { ... } })`.
-
-## Phase 4 — Result<T> handling
-
-- [ ] **Mutation success-path branching.** v1: `onSuccess: (data) => { if (data.ok) ... }`. v2: drop the `.ok` check; `data` is unwrapped success (e.g. `SwapResponse`, `TxHashPair`).
-- [ ] **Convert imperative `mutateAsync` calls.** Wrap in `try/catch` (v2 throws on `!ok`) OR switch to `mutateAsyncSafe` and branch on `result.ok`. See [`breaking-changes/result-handling.md`](breaking-changes/result-handling.md).
-- [ ] **Audit `onError` callbacks.** They now fire for SDK `!ok` (didn't in v1). Check that any error-toast logic is appropriate.
-
-## Phase 5 — invalidations
-
-- [ ] **Delete `invalidate*Queries` utility files.** Hook-owned in v2; no consumer-side invalidation needed.
-- [ ] **Drop manual `queryClient.invalidateQueries(...)` calls** that mirror what dapp-kit hooks already do (e.g. `xBalances` after a swap).
-- [ ] **Keep ONLY the cross-feature invalidations** that dapp-kit hooks don't know about (e.g. your custom analytics view query).
-- [ ] **If you have consumer wrappers around dapp-kit mutations**, ensure they don't double-invalidate. Move custom invalidations to the wrapper's `mutationOptions.onSuccess`.
-
-## Phase 6 — queryKey alignment (optional but recommended)
-
-If your code grafts onto dapp-kit's cache invalidation (e.g. you fetch a related query and want it to be invalidated by dapp-kit's mutation), align your queryKeys with dapp-kit conventions:
-
-- [ ] **First segment = feature directory name.** `'swap'`, `'mm'`, `'bridge'`, etc. See [`../integration/reference/querykey-conventions.md`](../integration/reference/querykey-conventions.md).
-- [ ] **camelCase segments.** No kebab-case.
-- [ ] **Bigints stringified** in keys.
-
-## Phase 7 — SDK-level migrations leaking through
-
-These are SDK-level changes that surface in dapp-kit hook signatures or types. Refer to the SDK migration tree for full detail:
-
-- [ ] **Chain-key terminology** — `xChainId` / `srcChainId` / `dstChainId` on action params → `chainKey` / `srcChainKey` / `dstChainKey`. See [`../../../sdk/ai-exported/migration/breaking-changes/type-system.md`](../../../sdk/ai-exported/migration/breaking-changes/type-system.md).
-- [ ] **SodaxConfig reshape** — flat `rpcConfig` → nested `chains[ChainKeys.X]: { rpcUrl }`. See [`../../../sdk/ai-exported/migration/breaking-changes/architecture.md`](../../../sdk/ai-exported/migration/breaking-changes/architecture.md).
-- [ ] **Error class** — `MoneyMarketError<Code>` etc. → single `SodaxError<C>`. See [`../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md`](../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md). dapp-kit consumers see this only if they directly reference SDK error classes.
-
-## Phase 8 — verification
-
-- [ ] `pnpm tsc --noEmit` is clean.
-- [ ] Smoke-test each feature your app uses: connect wallet, run one mutation, observe success + state updates.
-- [ ] Search for v1 leftovers: `grep -rE '\buseSpokeProvider\b|\binvalidateMmQueries\b|_MAINNET_CHAIN_ID\b'` returns zero hits.
-- [ ] Confirm `mutateAsync` calls are wrapped in `try/catch` OR replaced with `mutateAsyncSafe`.
-- [ ] Confirm provider stack uses `chains: ...` not `rpcConfig: ...`.
-
-## Cross-references
-
-- [`README.md`](README.md) — overview and v1↔v2 glossary.
-- [`ai-rules.md`](ai-rules.md) — DO / DO NOT for the agent doing the migration.
-- [`breaking-changes/`](breaking-changes/) — cross-cutting v1→v2 deltas (hook signatures, result handling, queryKey, SDK leakage).
-- [`recipes.md`](recipes.md) — codemods and adapters.
-- [`features/`](features/) — per-feature porting playbooks.

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

@@ -1,34 +0,0 @@
-# Migration features — `@sodax/dapp-kit` v1 → v2
-
-Per-feature porting playbooks. Each file shows the v1 → v2 delta for one feature's hook surface, with concrete code diffs.
-
-| File | What's covered |
-|---|---|
-| [`swap.md`](swap.md) | v1 `useSwap(spokeProvider)`-style call sites → v2 `mutate({ params, walletProvider })`. Approve return shape change. Result handling. |
-| [`money-market.md`](money-market.md) | v1 supply/borrow/withdraw/repay → v2 same with `srcChainKey`/`srcAddress` required. Allowance auto-skip for borrow/withdraw. |
-| [`staking.md`](staking.md) | All five mutations + their dedicated approve hooks. `useStakeRatio` returns a tuple in v2. |
-| [`bridge.md`](bridge.md) | Field renames in `useBridge` params (`srcChainId` → `srcChainKey`, `recipient` → `dstAddress`). `useGetBridgeableAmount` shape change. |
-| [`dex.md`](dex.md) | Two-step flow stayed the same; field renames + `srcChainKey` requirement. `useSupplyLiquidity` mint/increase routing. |
-| [`migration.md`](migration.md) | **Biggest change**: v1's `useMigrate(spokeProvider)` → 6 per-action hooks. |
-| [`bitcoin.md`](bitcoin.md) | Radfi flow shapes are mostly unchanged; provider/session lifecycle hooks tightened. |
-| [`auxiliary-services.md`](auxiliary-services.md) | Partner / recovery / backend queries / shared utilities — small per-hook changes. |
-
-## Pair-completeness
-
-Every file in this directory has a sibling in [`../../integration/features/`](../../integration/features/) with the same filename — the v2 design context for that feature. When you're stuck in one, the other is one path-swap away.
-
-## Cross-cutting prerequisites
-
-Before reading a feature playbook, make sure you've already read the cross-cutting deltas:
-
-- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) — provider stack, hook init shapes, approve return.
-- [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) — `Result<T>` semantic shift.
-- [`../breaking-changes/sdk-leakage.md`](../breaking-changes/sdk-leakage.md) — `srcChainKey`/`srcAddress` required, chain-key terminology, etc.
-
-The per-feature files below are about the *feature-specific* delta on top of those cross-cutting changes.
-
-## Cross-references
-
-- [`../README.md`](../README.md) — migration overview + glossary.
-- [`../checklist.md`](../checklist.md) — top-down checklist.
-- [`../ai-rules.md`](../ai-rules.md) — DO / DO NOT for the porting agent.