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

package/ai-exported/integration/reference/querykey-conventions.md

@@ -1,179 +0,0 @@
-# queryKey / mutationKey conventions — `@sodax/dapp-kit`
-
-Mandatory shape rules for every `queryKey` and `mutationKey`. Mechanically enforced on mutation keys by [`packages/dapp-kit/src/hooks/_mutationContract.test.ts`](../../../src/hooks/_mutationContract.test.ts); reviewer-enforced on query keys.
-
-## The five rules
-
-### Rule 1 — first segment is the feature directory name
-
-| Hook directory | First segment |
-|---|---|
-| `backend/` | `'backend'` |
-| `bitcoin/` | `'bitcoin'` |
-| `bridge/` | `'bridge'` |
-| `dex/` | `'dex'` |
-| `mm/` | `'mm'` |
-| `partner/` | `'partner'` |
-| `recovery/` | `'recovery'` |
-| `shared/` | `'shared'` |
-| `staking/` | `'staking'` |
-| `swap/` | `'swap'` |
-| `migrate/` | `'migrate'` |
-
-No exceptions. A hook in `swap/` whose key starts with `'intent'` is wrong.
-
-### Rule 2 — camelCase for all segments
-
-No kebab-case (`'btc-balance'`), no ad-hoc casing, no `snake_case`. Identifiers are camelCase string literals (`'tradingWalletBalance'`, `'submitSwapTx'`).
-
-### Rule 3 — shape is `[feature, action, ...identifiers]`
-
-Stable order: chain → token/asset → user → amount.
-
-```ts
-// @ai-snippets-skip
-queryKey: ['mm', 'allowance', srcChainKey, token, action]
-// not ['mm', 'allowance', token, srcChainKey, action]
-```
-
-### Rule 4 — bigints stringify
-
-React Query's hash uses `JSON.stringify` which throws on raw bigints. Always coerce:
-
-```ts
-queryKey: ['staking', 'stakeRatio', amount.toString()]   // ✓
-queryKey: ['staking', 'stakeRatio', amount]              // ✗ — runtime crash
-```
-
-Exception: query keys that pass bigint via the read hook's typed params and the corresponding invalidations use the same raw value — match the read hook's shape exactly. New code should always stringify.
-
-### Rule 5 — invalidate the narrowest key that could change
-
-If the mutation knows the affected `tokenId` / user / chain, scope the invalidation to it. Bare keys (no segments past the action) are reserved for "we don't know which variant changed" cases and should be commented.
-
-```ts
-// Good — narrow scope
-queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo', tokenId, poolKey] });
-
-// Acceptable — when the mutation can't scope further
-queryClient.invalidateQueries({ queryKey: ['swap', 'allowance'] }); // wipe all allowance variants on approve
-```
-
-## Worked examples
-
-```ts
-// @ai-snippets-skip
-// Cross-feature pattern: allowance reads. Shapes vary per feature (each carries
-// the inputs that actually scope the allowance). Match the read hook's shape exactly
-// from invalidations.
-queryKey: ['mm', 'allowance', srcChainKey, token, action]
-queryKey: ['swap', 'allowance', srcChainKey, srcAddress, inputToken, inputAmount.toString()]
-queryKey: ['bridge', 'allowance', srcChainKey, srcAddress, srcToken, amount.toString()]
-queryKey: ['dex', 'allowance', srcChainKey, asset, amount.toString()]
-queryKey: ['staking', 'allowance', srcChainKey, action, srcAddress, amount.toString()]
-//   ^^ action is a fixed literal per hook: 'stake' / 'unstake' / 'instantUnstake'
-
-// User position reads
-queryKey: ['mm', 'userReservesData', spokeChainKey, userAddress]
-queryKey: ['staking', 'info', srcChainKey, srcAddress]              // useStakingInfo — second segment is 'info', not 'stakingInfo'
-queryKey: ['shared', 'xBalances', xChainId, tokens, address]
-
-// Mutation default keys
-mutationKey: ['swap']                                                // useSwap
-mutationKey: ['swap', 'approve']                                     // useSwapApprove
-mutationKey: ['swap', 'cancel']                                      // useCancelSwap
-mutationKey: ['swap', 'limitOrder', 'create']                        // useCreateLimitOrder
-mutationKey: ['swap', 'limitOrder', 'cancel']                        // useCancelLimitOrder
-mutationKey: ['mm', 'supply']
-mutationKey: ['staking', 'stake']
-mutationKey: ['staking', 'approve', 'stake']                         // useStakeApprove (action discriminator inside the key)
-mutationKey: ['bridge']                                              // useBridge — single segment (no 'execute' suffix)
-mutationKey: ['migrate', 'icxToSoda']
-mutationKey: ['dex', 'supplyLiquidity']
-```
-
-## Per-feature key tables
-
-Skip if you're writing a feature hook for the first time and want to align with existing conventions.
-
-### Swap
-
-| Key | Hook |
-|---|---|
-| `['swap', 'quote', { ...payload, amount: payload.amount.toString() }]` | `useQuote` (object segment with bigint stringified) |
-| `['swap', 'allowance', srcChainKey, srcAddress, inputToken, inputAmount.toString()]` | `useSwapAllowance` |
-| `['swap', 'status', intentTxHash]` | `useStatus` |
-| `['swap']` | `useSwap` mutation key |
-| `['swap', 'approve']` | `useSwapApprove` |
-| `['swap', 'cancel']` | `useCancelSwap` |
-| `['swap', 'limitOrder', 'create']` | `useCreateLimitOrder` |
-| `['swap', 'limitOrder', 'cancel']` | `useCancelLimitOrder` |
-
-### Money market
-
-| Key | Hook |
-|---|---|
-| `['mm', 'reservesData']` | `useReservesData` |
-| `['mm', 'reservesHumanized']` | `useReservesHumanized` |
-| `['mm', 'reservesList']` | `useReservesList` |
-| `['mm', 'reservesUsdFormat']` | `useReservesUsdFormat` |
-| `['mm', 'userReservesData', spokeChainKey, userAddress]` | `useUserReservesData` |
-| `['mm', 'userFormattedSummary', spokeChainKey, userAddress]` | `useUserFormattedSummary` |
-| `['mm', 'allowance', srcChainKey, token, action]` | `useMMAllowance` |
-| `['mm', 'aToken', aToken]` | `useAToken` |
-| `['mm', 'aTokensBalances', aTokens, spokeChainKey, userAddress]` | `useATokensBalances` |
-| `['mm', 'supply']` | `useSupply` mutation |
-| `['mm', 'borrow']` | `useBorrow` |
-| `['mm', 'withdraw']` | `useWithdraw` |
-| `['mm', 'repay']` | `useRepay` |
-| `['mm', 'approve']` | `useMMApprove` |
-
-### Staking
-
-| Key | Hook |
-|---|---|
-| `['staking', 'info', srcChainKey, srcAddress]` | `useStakingInfo` (second segment is `'info'`, NOT `'stakingInfo'`) |
-| `['staking', 'unstakingInfo', srcChainKey, srcAddress]` | `useUnstakingInfo` |
-| `['staking', 'unstakingInfoWithPenalty', srcChainKey, srcAddress]` | `useUnstakingInfoWithPenalty` |
-| `['staking', 'config']` | `useStakingConfig` |
-| `['staking', 'stakeRatio', amount.toString()]` | `useStakeRatio` |
-| `['staking', 'instantUnstakeRatio', amount.toString()]` | `useInstantUnstakeRatio` |
-| `['staking', 'convertedAssets', amount.toString()]` | `useConvertedAssets` |
-| `['staking', 'allowance', srcChainKey, action, srcAddress, amount.toString()]` | `useStakeAllowance` / `useUnstakeAllowance` / `useInstantUnstakeAllowance` — `action` is a fixed literal per hook |
-| `['staking', 'stake']` | `useStake` mutation |
-| `['staking', 'unstake']` | `useUnstake` |
-| `['staking', 'instantUnstake']` | `useInstantUnstake` |
-| `['staking', 'claim']` | `useClaim` |
-| `['staking', 'cancelUnstake']` | `useCancelUnstake` |
-| `['staking', 'approve', 'stake' \| 'unstake' \| 'instantUnstake']` | `useStakeApprove` / `useUnstakeApprove` / `useInstantUnstakeApprove` |
-
-### Bridge / DEX / Migration / Bitcoin / etc.
-
-Follow the same shape. See the source hook files (`packages/dapp-kit/src/hooks/<feature>/`) for current keys.
-
-## v1 → v2
-
-In v1 dapp-kit, queryKey conventions were ad-hoc:
-
-```ts
-// @ai-snippets-skip — queryKey-shape examples; `...` is a placeholder, not real code
-// ai-keys-allow — v1 keys shown for migration context; not real v2 source keys
-// v1 examples
-queryKey: ['xBalances', ...]                  // missing feature prefix
-queryKey: ['btc-balance', ...]                // kebab-case
-queryKey: ['api', 'mm', ...]                  // wrong feature prefix
-mutationKey: undefined                         // many hooks had no default
-
-// v2
-queryKey: ['shared', 'xBalances', ...]        // feature-prefixed
-queryKey: ['bitcoin', 'balance', ...]         // camelCase
-queryKey: ['backend', 'mm', ...]              // correctly nested under 'backend'
-mutationKey: ['mm', 'supply']                 // every hook has a default; consumer can override via mutationOptions.mutationKey
-```
-
-For migration code grafting onto dapp-kit's cache invalidation, see [`../../migration/breaking-changes/querykey-conventions.md`](../../migration/breaking-changes/querykey-conventions.md).
-
-## Cross-references
-
-- [`../architecture.md`](../architecture.md) § "queryKey / mutationKey conventions" — full design rationale.
-- [`hooks-index.md`](hooks-index.md) — full hook table.

package/ai-exported/migration/README.md

@@ -1,60 +0,0 @@
-# Migration — `@sodax/dapp-kit` v1 → v2
-
-This tree is the v1 → v2 migration playbook for **existing consumers** using v1 dapp-kit. If you're starting fresh on v2 with no v1 code to port, skip to [`../integration/README.md`](../integration/README.md).
-
-## What v2 changes (the 30-second version)
-
-v2 was a deep canonicalization of dapp-kit's hook shapes plus an architectural reshape underneath in `@sodax/sdk`. Five orthogonal changes account for ~95% of the breakage your typecheck will surface:
-
-1. **Single-object hook params.** Every hook accepts a single optional object. Mutation hooks take only `{ mutationOptions }` at hook-init; ALL domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)`. Query hooks take `{ params, queryOptions }`. v1's positional args and hook-level `spokeProvider` / `params` are gone.
-2. **`Result<T>` semantics inverted.** v1: `mutationFn` returned `Result<T>` as success; consumer branched on `data.ok` inside `onSuccess`. v2: `mutationFn` calls `unwrapResult` and **throws** on `!ok` — React Query's native `isError` / `error` / `onError` / `retry` engage. New `mutateAsyncSafe(vars): Promise<Result<TData>>` re-packs the throw for `Result<T>`-style branching when you want it.
-3. **`useSpokeProvider` deleted.** Pass `walletProvider` (from `useWalletProvider({ xChainId: chainKey })`) directly into `mutate(vars)`. There is no provider class to derive.
-4. **Approve-hook return shape standardized.** v1's `useFooApprove(spokeProvider)` returned a custom `{ approve, isLoading, error }` object. v2 returns the standard `SafeUseMutationResult` with `mutateAsync` / `mutateAsyncSafe` / `isPending`.
-5. **Hook-owned invalidations.** Each mutation hook invalidates the relevant query keys in its own `onSuccess`. v1 utilities like `invalidateMmQueries` are deleted; consumer-provided `onSuccess` runs after the hook's invalidations.
-
-The remainder is per-feature shape diffs (return types, params field renames, new required params) and SDK-leakage (`xChainId` → `chainKey`, `*_MAINNET_CHAIN_ID` → `ChainKeys.*`, `Result<T>` propagation through hook signatures).
-
-## Reading order
-
-Read in this order. Each step builds on the last.
-
-1. **[`ai-rules.md`](ai-rules.md)** — DO / DO NOT / workflow / stop-conditions. Read first, then dive in.
-2. **This file.** Cross-cutting glossary below + reference list of breaking-changes / features / checklist.
-3. **[`checklist.md`](checklist.md)** — top-down cross-cutting migration checklist. Walk it, mark items off as you go.
-4. **[`breaking-changes/hook-signatures.md`](breaking-changes/hook-signatures.md)** — fix every hook call site shape first (single-object params, `mutate(vars)`, approve return).
-5. **[`breaking-changes/result-handling.md`](breaking-changes/result-handling.md)** — convert SDK-level error handling: success-path branching → `mutateAsyncSafe` (or `try/catch` on `mutateAsync`).
-6. **[`breaking-changes/querykey-conventions.md`](breaking-changes/querykey-conventions.md)** — rename consumer query keys to match v2 conventions (where consumer code grafts onto dapp-kit cache invalidation).
-7. **[`breaking-changes/sdk-leakage.md`](breaking-changes/sdk-leakage.md)** — SDK-level changes leaking through dapp-kit hook signatures. Cross-links to the SDK's migration tree.
-8. **[`features/<x>.md`](features/)** — port the call sites for each feature you use. Pair with [`../integration/features/<x>.md`](../integration/features/) (same filename) when you need v2 design context.
-9. **[`recipes.md`](recipes.md)** — codemods and adapters for incremental migration.
-
-## v1 ↔ v2 glossary (terms that changed meaning)
-
-Same word, different concept across versions. Skim before reading the breaking-changes files — this dictionary prevents the most common porting confusions.
-
-| Term | v1 meaning | v2 meaning |
-|---|---|---|
-| **mutation hook arg** | Positional or first-arg `spokeProvider`; mutation called with minimal vars. | Optional `{ mutationOptions }` only. ALL domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)`. |
-| **query hook arg** | Positional args (e.g. `useGetBridgeableTokens(srcChainId, dstChainId, addr)`). | Single object `{ params, queryOptions }`. |
-| **mutation `data`** | `Result<T>` — `{ ok: true; value: T } \| { ok: false; error }`. Branch on `data.ok` in `onSuccess`. | The unwrapped success type `T`. SDK failures throw inside `mutationFn` so React Query's `isError` / `error` engage. |
-| **approve hook return** | Custom object: `{ approve, isLoading, error }`. | Standard `SafeUseMutationResult`: `mutateAsync` / `mutateAsyncSafe`, `isPending`, `isError`, `error`. |
-| **`useSpokeProvider`** | Hook that derived a `SpokeProvider` from connected wallet state. | Deleted. Pass `walletProvider` (from `useWalletProvider`) directly into `mutate(vars)`. |
-| **invalidations** | Consumer-managed via `invalidateMmQueries(queryClient, ...)` utilities. | Hook-owned in composed `onSuccess`. Consumer `onSuccess` runs after the hook's. |
-| **`xChainId` / `srcChainId` / `dstChainId`** | Field names on tokens, intents, bridge params. (SDK-leakage.) | Renamed: `XToken.chainKey`, request-side `srcChainKey` / `dstChainKey`. **`Intent.srcChain` / `Intent.dstChain` (read shape) kept** — distinct from request-side. |
-| **`*_MAINNET_CHAIN_ID` constants** | Individual exports (`BSC_MAINNET_CHAIN_ID`, etc.). | Gone. Use `ChainKeys.X_MAINNET` namespace access. |
-| **`SodaxProvider`'s config** | Flat `rpcConfig: { sonic: '...', ... }`. | Nested under `chains`: `config.chains[ChainKeys.X]: { rpcUrl: '...' }`. |
-| **`useMigrate(spokeProvider)`** | Single hook (commented out in v1). | Six per-action hooks: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, `useMigrationApprove`, `useMigrationAllowance`. |
-| **error class** | Per-feature classes (`MoneyMarketError<Code>`, `IntentError<Code>`, etc.). (SDK-leakage.) | One canonical `SodaxError<C>` with `feature` + closed 13-code reason vocabulary. |
-
-## Cross-references to integration
-
-Every breaking-change file in this tree has a v2-design counterpart in `../integration/`. Follow the link when "what does v2 expect instead?" comes up:
-
-- [`breaking-changes/hook-signatures.md`](breaking-changes/hook-signatures.md) ↔ [`../integration/architecture.md`](../integration/architecture.md) (§ Read hook shape, Mutation hook shape).
-- [`breaking-changes/result-handling.md`](breaking-changes/result-handling.md) ↔ [`../integration/recipes/mutation-error-handling.md`](../integration/recipes/mutation-error-handling.md).
-- [`breaking-changes/querykey-conventions.md`](breaking-changes/querykey-conventions.md) ↔ [`../integration/reference/querykey-conventions.md`](../integration/reference/querykey-conventions.md).
-- [`breaking-changes/sdk-leakage.md`](breaking-changes/sdk-leakage.md) ↔ [`../../../sdk/ai-exported/migration/`](../../../sdk/ai-exported/migration/) (the underlying SDK's migration tree).
-- [`features/<x>.md`](features/) ↔ [`../integration/features/<x>.md`](../integration/features/) (same filename).
-- [`recipes.md`](recipes.md) ↔ no integration counterpart (migration-only patterns).
-
-The pair-completeness rule: every file in `migration/features/` has a sibling in `integration/features/` with the same filename. Use this when you're stuck in one and want the other view.

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

@@ -1,81 +0,0 @@
-# AI rules — `@sodax/dapp-kit` migration v1 → v2
-
-DO / DO NOT / workflow / stop conditions for AI agents porting v1 dapp-kit code to v2. Read this **before** the per-feature migration playbooks.
-
-## Workflow (do these in order)
-
-1. **Survey the v1 surface area first.**
-
-   ```bash
-   pnpm tsc --noEmit                                                          # baseline (will produce hundreds of errors)
-   grep -rE '\buseSpokeProvider\b|\binvalidateMmQueries\b' --include='*.tsx' --include='*.ts' src/   # hottest v1 patterns
-   grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b' --include='*.tsx' --include='*.ts' src/               # SDK leakage
-   ```
-
-2. **Read [`checklist.md`](checklist.md)** — top-down cross-cutting checklist. Walk it before touching code.
-3. **Fix imports + provider-stack first** ([`breaking-changes/hook-signatures.md`](breaking-changes/hook-signatures.md) § Provider stack). The rest of the codebase won't typecheck without these.
-4. **Mechanical sweeps next** — easier wins:
-   - `*_MAINNET_CHAIN_ID` → `ChainKeys.X_MAINNET` (one codemod)
-   - `useSpokeProvider` deletions
-   - `xChainId` → `chainKey` on `XToken` (with care — read shape kept the field)
-5. **Per-call-site rewrites:** mutation hook calls (move `params` + `walletProvider` from hook init to `mutate(vars)`), approve-hook returns (`{ approve, isLoading }` → `mutateAsync` + `isPending`), result handling (`data.ok` branching → `mutateAsyncSafe` or `try/catch`).
-6. **Delete v1-managed invalidations** (`invalidateMmQueries`-style utilities). Hook-owned now.
-7. **Verify with `pnpm tsc --noEmit`** until clean. Then run app smoke tests.
-
-## DO
-
-- **DO** mechanical sweeps before per-call-site rewrites. Type renames and constant renames are codemod-friendly; result handling needs case-by-case attention.
-- **DO** prefer `mutateAsyncSafe` for sequenced flows. The user-reject case is modal, not exceptional.
-- **DO** `try/catch` `mutateAsync` calls if you keep that call shape. v2's `mutateAsync` rejects on SDK `!ok`.
-- **DO** delete consumer-side `invalidate*Queries` utility files. Hook-owned invalidations make them obsolete.
-- **DO** swap `BSC_MAINNET_CHAIN_ID` (and the other 14 v1 constants) for `ChainKeys.BSC_MAINNET` (or whichever chain). Codemod-friendly.
-- **DO** consult [`../integration/architecture.md`](../integration/architecture.md) when "what does v2 expect instead?" comes up.
-- **DO** consult [`../../../sdk/ai-exported/migration/`](../../../sdk/ai-exported/migration/) for any SDK-leakage migrations (chain-key terminology, `Result<T>` propagation, ConfigService).
-
-## DO NOT
-
-- **DO NOT** convert `data.ok` branching mechanically. v1's `data` was `Result<T>`; v2's `data` is the unwrapped success value. The branching has to move from `onSuccess` to either `mutateAsyncSafe` (preferred) or `try/catch` on `mutateAsync`.
-- **DO NOT** keep the legacy `useFooApprove(spokeProvider)` call shape. v2's approve hooks return `SafeUseMutationResult` — call as `useFooApprove()` (no args), then `mutateAsync({ params, walletProvider })`.
-- **DO NOT** preserve `useSpokeProvider` "for compat." It's deleted; there's no shim. Pass `walletProvider` from `useWalletProvider({ xChainId: chainKey })` directly into `mutate(vars)`.
-- **DO NOT** blanket-replace `srcChain` → `srcChainKey`. The `Intent` *read shape* keeps `srcChain` / `dstChain` (those are `IntentRelayChainId`s). Only the *request-side* params (e.g. `MoneyMarketSupplyParams`) renamed to `srcChainKey` / `dstChainKey`.
-- **DO NOT** treat the v1 `useMigrate(spokeProvider)` API as still working. v2 split it into 6 per-action hooks (`useMigrateIcxToSoda`, etc.).
-- **DO NOT** add `@sodax/types` as an explicit dep during migration. It's transitively re-exported.
-
-## Stop conditions (defer to user)
-
-| Signal | Why stop |
-|---|---|
-| User wants to keep v1 dapp-kit | Tell them the shapes are not compatible. They either upgrade or stay on v1. |
-| User wants to use React Server Components (RSC) | dapp-kit code goes in client components. Server Components can't run hooks. |
-| Codebase has consumer wrappers around dapp-kit hooks that look like dapp-kit's own internals | Examine each — they may be reasonable but check that they preserve `mutateAsyncSafe`. v1 wrappers often replaced React Query's `useMutation` directly. |
-| User expects approve hooks to look like before | Show them the new return shape. v2 standardized approve to `SafeUseMutationResult`; `{ approve, isLoading }` is gone. |
-| You hit an SDK-level migration item | Defer to [`../../../sdk/ai-exported/migration/`](../../../sdk/ai-exported/migration/). Don't try to re-explain SDK changes inside dapp-kit migration files — link them out. |
-
-## Verification protocol
-
-```bash
-# 1. Type-check the consumer (canonical pass).
-pnpm tsc --noEmit   # zero errors expected
-
-# 2. Confirm no leftover v1 patterns.
-grep -rE '\buseSpokeProvider\b' src/                  # zero hits
-grep -rE 'invalidateMmQueries\b' src/                 # zero hits
-grep -rE '_MAINNET_CHAIN_ID\b' src/                   # zero hits
-grep -rE 'data\?\.ok\b.*onSuccess' src/               # zero hits — v1 success-path branching is gone
-
-# 3. Confirm mutateAsync calls are properly wrapped.
-grep -rE 'mutateAsync\(' src/ | grep -v 'try\|catch\|mutateAsyncSafe'  # zero hits or audit each
-
-# 4. Confirm dapp-kit imports come only from the package root.
-grep -rE "@sodax/dapp-kit/[a-z]" src/                 # zero hits (no deep imports)
-```
-
-## Done criteria
-
-- [ ] Provider stack updated: `<SodaxProvider config={...}>` + `<QueryClientProvider>` (preferably `createSodaxQueryClient()`).
-- [ ] Every v1 hook call site rewritten to single-object params + `mutate(vars)` flow for domain inputs.
-- [ ] Every approve hook usage rewritten to `mutateAsync` / `mutateAsyncSafe` + `isPending`.
-- [ ] Every mutation result handler converted from `data.ok` branching to `mutateAsyncSafe`'s `result.ok` branching, or to `try/catch` on `mutateAsync`.
-- [ ] No `useSpokeProvider`, no `invalidateMmQueries`, no `*_MAINNET_CHAIN_ID` constants.
-- [ ] `pnpm tsc --noEmit` clean.
-- [ ] App smoke-tested: connect wallet, run one mutation per feature you use.

package/ai-exported/migration/breaking-changes/hook-signatures.md

@@ -1,233 +0,0 @@
-# Hook signatures — v1 → v2
-
-The structural shape of every dapp-kit hook changed in v2. Five categories of breakage:
-
-1. Provider stack config
-2. Mutation hook signature (`{ mutationOptions }` only)
-3. Query hook signature (`{ params, queryOptions }`)
-4. Approve hook return shape
-5. `useSpokeProvider` deletion + invalidation logic move
-
-## 1. Provider stack
-
-`SodaxProvider`'s prop shape changed.
-
-```diff
-- <SodaxProvider rpcConfig={{
--   sonic: 'https://sonic-rpc.publicnode.com',
--   '0xa86a.avax': 'https://...',
--   '0xa4b1.arbitrum': 'https://arb1.arbitrum.io/rpc',
-- }}>
-+ <SodaxProvider config={{
-+   chains: {
-+     [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
-+     [ChainKeys.AVALANCHE_MAINNET]: { rpcUrl: 'https://...' },
-+     [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
-+   },
-+ }}>
-```
-
-The `config` prop is `DeepPartial<SodaxConfig>` from `@sodax/sdk`. Other fields available: `api`, `solver`, `swaps`, `bridge`, `dex`, `moneyMarket`, `hub`, `relay`, `fee`. See [`../../../../sdk/ai-exported/migration/breaking-changes/architecture.md`](../../../../sdk/ai-exported/migration/breaking-changes/architecture.md) for the SDK-side reshape.
-
-**Recommended pairing**: replace `new QueryClient()` with `createSodaxQueryClient()` for global mutation observability.
-
-```diff
-- import { QueryClient } from '@tanstack/react-query';
-- const queryClient = new QueryClient();
-+ import { createSodaxQueryClient } from '@sodax/dapp-kit';
-+ const queryClient = createSodaxQueryClient();
-```
-
-## 2. Mutation hook signature
-
-v1: hook took `spokeProvider` (or other domain inputs) at hook-init.
-v2: hook takes only `{ mutationOptions }`. ALL domain inputs flow through `mutate(vars)`.
-
-```diff
-- // v1
-- function SwapButton({ intentParams, spokeProvider }) {
--   const swap = useSwap(spokeProvider);
--   await swap.mutateAsync({ params: intentParams });
-- }
-
-+ // v2
-+ function SwapButton({ intentParams }) {
-+   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });   // separate now
-+   const { mutateAsync: swap } = useSwap();
-+   if (!walletProvider) return;
-+   await swap({ params: intentParams, walletProvider });
-+ }
-```
-
-This affects every mutation hook — `useSupply`, `useBorrow`, `useStake`, `useBridge`, etc. The mechanical recipe per call site:
-
-1. Drop `spokeProvider` from the hook init.
-2. Add `useWalletProvider({ xChainId: chainKey })` separately.
-3. Move `params` and `walletProvider` from hook init to `mutate(vars)`.
-4. Update the destructure: `const { mutateAsync: foo } = useFoo();` (or `mutateAsyncSafe`).
-
-### Approve hooks (the most disruptive of the bunch)
-
-v1's approve hooks returned a custom object. v2 returns the standard `SafeUseMutationResult`.
-
-```diff
-- // v1
-- const { approve, isLoading, error } = useSwapApprove(spokeProvider);
-- await approve(intentParams);
-
-+ // v2
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-+ const { mutateAsync: approve, mutateAsyncSafe, isPending, error } = useSwapApprove();
-+ if (!walletProvider) return;
-+ await approve({ params: intentParams, walletProvider });
-```
-
-Field rename: `isLoading` → `isPending` (React Query 5 convention; v2 dapp-kit follows it).
-
-## 3. Query hook signature
-
-v1: positional args (`useFoo(arg1, arg2)`).
-v2: single object (`useFoo({ params, queryOptions })`).
-
-```diff
-- // v1
-- const { data: tokens } = useGetBridgeableTokens(srcChainId, dstChainId, tokenAddress);
-
-+ // v2
-+ const { data: tokens } = useGetBridgeableTokens({
-+   params: { from: ChainKeys.BASE_MAINNET, to: ChainKeys.POLYGON_MAINNET, token: tokenAddress },
-+ });
-```
-
-Hook owns `queryKey`, `queryFn`, `enabled`. The `queryOptions` slot is `Omit<UseQueryOptions, 'queryKey' | 'queryFn' | 'enabled'>`. Don't try to override those three fields — TypeScript rejects.
-
-## 4. Wallet plumbing — `useSpokeProvider` deletion
-
-v1 had `useSpokeProvider(chainId, walletProvider)` to derive a `SpokeProvider` instance. v2 deleted this hook entirely.
-
-```diff
-- // v1
-- import { useSpokeProvider } from '@sodax/dapp-kit';
--
-- const spokeProvider = useSpokeProvider({ chainId: BSC_MAINNET_CHAIN_ID });
-- // ... pass spokeProvider into hooks
-
-+ // v2
-+ import { useWalletProvider } from '@sodax/wallet-sdk-react';
-+ import { ChainKeys } from '@sodax/sdk';
-+
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-+ // ... pass walletProvider into mutate(vars)
-```
-
-`SpokeProvider` was a v1 abstraction that v2 makes implicit (the chain key on action params drives spoke routing internally). There's no shim — drop the concept.
-
-## 5. Invalidation logic
-
-v1 expected consumers to manage cache invalidation manually:
-
-```ts
-// @ai-snippets-skip
-// v1 — consumer-managed
-import { useQueryClient } from '@tanstack/react-query';
-const queryClient = useQueryClient();
-await supply({ params, spokeProvider });
-invalidateMmQueries(queryClient, srcChainKey, userAddress, token);
-```
-
-v2: each mutation hook invalidates its relevant keys in its own `onSuccess`. Delete consumer-side `invalidate*Queries` utilities.
-
-```diff
-- // v1
-- await supply({ params, spokeProvider });
-- invalidateMmQueries(queryClient, srcChainKey, userAddress, token);
-
-+ // v2
-+ await supply({ params, walletProvider });   // hook invalidates xBalances + userReservesData automatically
-```
-
-To run additional cross-feature invalidations (your own analytics view, etc.), pass `mutationOptions.onSuccess`:
-
-```ts
-// @ai-snippets-skip
-const { mutateAsync: supply } = useSupply({
-  mutationOptions: {
-    onSuccess: async (data, vars) => {
-      // Runs AFTER dapp-kit's invalidations.
-      await queryClient.invalidateQueries({ queryKey: ['my-app', 'analytics'] });
-    },
-  },
-});
-```
-
-See [`../../integration/recipes/invalidations.md`](../../integration/recipes/invalidations.md) for the full pattern.
-
-## 6. Variable-shape changes inside `mutate(vars)`
-
-v1's mutation vars were scattered (some at hook init, some in `mutate`). v2 consolidates everything into `TVars`.
-
-```diff
-- // v1
-- const supply = useSupply(spokeProvider);
-- await supply.mutateAsync({ params: { token, amount, action: 'supply' } });
-
-+ // v2 — params now requires srcChainKey + srcAddress (SDK leakage)
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-+ const { mutateAsync: supply } = useSupply();
-+ await supply({
-+   params: {
-+     srcChainKey: ChainKeys.BASE_MAINNET,
-+     srcAddress: '0x...',                  // NEW: required in v2
-+     token,
-+     amount,
-+     action: 'supply',
-+   },
-+   walletProvider,                          // NEW: at mutate(vars), not hook init
-+ });
-```
-
-The added `srcChainKey` + `srcAddress` is SDK-leakage — see [`sdk-leakage.md`](sdk-leakage.md) for the full picture.
-
-## 7. Query options shape
-
-v1 query hooks accepted ad-hoc option overrides (sometimes including `queryKey`). v2 typed the slot strictly:
-
-```diff
-- // v1
-- const { data } = useUserReservesData({
--   spokeProvider,
--   address,
--   queryKey: ['my-custom-key'],   // ⚠️ v2 forbids overriding queryKey
-- });
-
-+ // v2
-+ const { data } = useUserReservesData({
-+   params: { spokeChainKey, userAddress: address },
-+   queryOptions: { staleTime: 5000, refetchInterval: 10000 },
-+ });
-```
-
-If you were overriding `queryKey` in v1 to graft your own invalidations, that's not the v2 way. Either:
-- Use the hook's default queryKey + invalidate via your own `mutationOptions.onSuccess` after relevant mutations.
-- If you need a totally different query shape, write your own `useQuery` directly (don't shoehorn dapp-kit's hook).
-
-## TypeScript fingerprints
-
-These error patterns indicate this category of breakage:
-
-| Error | What it means |
-|---|---|
-| `Module '"@sodax/dapp-kit"' has no exported member 'useSpokeProvider'` | Hook deleted; drop import. |
-| `Property 'approve' does not exist on type 'SafeUseMutationResult'` | v1 approve return shape; use `mutateAsync` / `mutateAsyncSafe`. |
-| `Property 'isLoading' does not exist on type 'SafeUseMutationResult'` | Renamed to `isPending`. |
-| `Object literal may only specify known properties, and 'spokeProvider' does not exist in type 'UseFooVars'` | Hook init or mutate vars still has v1 `spokeProvider`. Drop it. |
-| `Object literal may only specify known properties, and 'queryKey' does not exist in type 'ReadQueryOptions'` | v1 ad-hoc queryOptions; queryKey is hook-owned now. |
-| `Type '...' is missing the following properties from type 'MoneyMarketSupplyParams': srcChainKey, srcAddress` | SDK leakage — params shape gained required fields. |
-| `Expected 0-1 arguments, but got 3` (on a query hook) | v1 positional args; switch to `{ params, queryOptions }`. |
-
-## Cross-references
-
-- [`result-handling.md`](result-handling.md) — `Result<T>` semantic shift (success-path → throws inside mutationFn).
-- [`querykey-conventions.md`](querykey-conventions.md) — queryKey/mutationKey rename rules.
-- [`sdk-leakage.md`](sdk-leakage.md) — SDK-side changes that surface here (chain-key terminology, etc.).
-- [`../../integration/architecture.md`](../../integration/architecture.md) — the canonical v2 hook shapes.