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

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

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

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

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

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

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

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