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

package/ai-exported/AGENTS.md

@@ -4,7 +4,7 @@
 
 ## Project
 
-`@sodax/dapp-kit` is a React hooks library that wraps `@sodax/sdk` with React Query. It provides ~95 hooks across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Radfi, backend queries, shared) for consumer dApps. It is **React-only** — Node.js scripts and backend services use `@sodax/sdk` directly.
+`@sodax/dapp-kit` is a React hooks library that wraps `@sodax/sdk` with React Query. It provides hooks across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Radfi, backend queries, shared) for consumer dApps. It is **React-only** — Node.js scripts and backend services use `@sodax/sdk` directly.
 
 This package is **v2**. v2 was a deep canonicalization pass over v1's hook shapes — single-object params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the entire SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). Code written against v1 dapp-kit will not compile against v2.
 

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

@@ -39,6 +39,7 @@ DO / DO NOT / workflow / stop conditions for AI agents writing v2 dapp-kit code.
 - **DO NOT** recreate the v1 `invalidateMmQueries(...)` utility or anything similar. Each mutation hook invalidates the relevant keys in its own `onSuccess`. Add cross-feature invalidations via consumer `onSuccess`.
 - **DO NOT** destructure cross-chain mutation results as arrays — `[a, b] = result.value` is wrong. The shape is `TxHashPair = { srcChainTxHash, dstChainTxHash }` (object). This applies to `useBridge`, `useStake`/`useUnstake`/etc., `useDexDeposit`/`useDexWithdraw`, all four MM mutations, and all four migration mutations.
 - **DO NOT** use legacy chain-id constants (`BSC_MAINNET_CHAIN_ID`, etc.). They're gone in v2 — use `ChainKeys.X_MAINNET`.
+- **DO NOT** reach for `as any` / `as IEvmWalletProvider` casts when wiring `useWalletProvider({ xChainId })` into mutation `mutate(vars)`. v2 supports the broad-union case structurally; the cast is not needed. See `recipes/wallet-connectivity.md` § "No type cast is needed".
 
 ## Stop conditions (defer to user)
 

package/ai-exported/integration/architecture.md

@@ -33,6 +33,8 @@ Every v2 design concept the hooks rest on, in one TOC-navigable file. Read it on
 
 `SodaxProvider` does **not** depend on `@sodax/wallet-sdk-react` — wallet state is wired side-by-side. Backend / non-React consumers (Node scripts, bots) bypass dapp-kit entirely and use `@sodax/sdk` directly with their own wallet implementation.
 
+**Config reactivity.** `config` is tracked by reference - see [`recipes/setup.md § Config reactivity`](recipes/setup.md#config-reactivity) for the module-const vs `useMemo` patterns.
+
 ### `createSodaxQueryClient`
 
 Returns a `QueryClient` pre-wired with a `MutationCache.onError` hook for global mutation observability. Default behavior: logs every mutation failure to console as `[sodax] Mutation error: <error>`.
@@ -237,7 +239,7 @@ queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo', tokenId, poolK
 
 ## Hook organization
 
-~95 hooks (41 mutations + ~50 queries + utilities) organized by feature domain in `src/hooks/`:
+Hooks organized by feature domain in `src/hooks/`:
 
 ```
 hooks/
@@ -248,13 +250,13 @@ hooks/
 ├── swap/       # useQuote, useSwap, useStatus, useSwapAllowance, useSwapApprove,
 │               # useCancelSwap, useCreateLimitOrder, useCancelLimitOrder
 ├── mm/         # useSupply, useWithdraw, useBorrow, useRepay, useMMAllowance, useMMApprove,
-│               # reserves data hooks (13 hooks total)
+│               # reserves data hooks
 ├── bridge/     # useBridge, useBridgeAllowance, useBridgeApprove, bridgeable amounts/tokens
-├── staking/    # useStake, useUnstake, useInstantUnstake, useClaim, staking info hooks (~18)
-├── dex/        # usePools, useDexDeposit, useDexWithdraw, liquidity hooks (~13)
-├── bitcoin/    # useRadfiSession, fund/withdraw, UTXO management (~8)
-├── backend/    # Intent tracking, swap submission, orderbook, money market position queries (~13)
-├── partner/    # Partner fee claim, auto-swap preferences, token approval (6)
+├── staking/    # useStake, useUnstake, useInstantUnstake, useClaim, staking info hooks
+├── dex/        # usePools, useDexDeposit, useDexWithdraw, liquidity hooks
+├── bitcoin/    # useRadfiSession, fund/withdraw, UTXO management
+├── backend/    # Intent tracking, swap submission, orderbook, money market position queries
+├── partner/    # Partner fee claim, auto-swap preferences, token approval
 ├── recovery/   # useHubAssetBalances, useWithdrawHubAsset
 └── migrate/    # useMigrateIcxToSoda, useRevertMigrateSodaToIcx, useMigratebnUSD,
                 # useMigrateBaln, useMigrationApprove, useMigrationAllowance

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

@@ -2,16 +2,16 @@
 
 Per-feature reference docs. Each file documents the hooks, params types, return types, and feature-specific gotchas — but doesn't include extended worked examples (those live in [`../recipes/`](../recipes/)).
 
-| File | Hook count | What's covered |
-|---|---|---|
-| [`swap.md`](swap.md) | 8 | Cross-chain swaps via the intent solver: `useQuote`, `useSwap`, allowance/approve, status polling, limit orders. |
-| [`money-market.md`](money-market.md) | 13 | Lending/borrowing on the cross-chain MM: `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, allowance/approve, reserves data hooks. |
-| [`staking.md`](staking.md) | ~18 | SODA → xSODA staking: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, allowance/approve, info/ratio reads. |
-| [`bridge.md`](bridge.md) | 5 | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
-| [`dex.md`](dex.md) | ~13 | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
-| [`migration.md`](migration.md) | 6 | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
-| [`bitcoin.md`](bitcoin.md) | ~8 | Radfi (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
-| [`auxiliary-services.md`](auxiliary-services.md) | ~30 | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
+| File | What's covered |
+|---|---|
+| [`swap.md`](swap.md) | Cross-chain swaps via the intent solver: `useQuote`, `useSwap`, allowance/approve, status polling, limit orders. |
+| [`money-market.md`](money-market.md) | Lending/borrowing on the cross-chain MM: `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, allowance/approve, reserves data hooks. |
+| [`staking.md`](staking.md) | SODA → xSODA staking: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, allowance/approve, info/ratio reads. |
+| [`bridge.md`](bridge.md) | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
+| [`dex.md`](dex.md) | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
+| [`migration.md`](migration.md) | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
+| [`bitcoin.md`](bitcoin.md) | Radfi (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`auxiliary-services.md`](auxiliary-services.md) | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
 
 ## Reference vs recipes
 

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

@@ -6,7 +6,7 @@ Pair: [`../../migration/features/auxiliary-services.md`](../../migration/feature
 
 ## Partner
 
-Partner fee claiming and auto-swap preferences. 6 hooks.
+Partner fee claiming and auto-swap preferences.
 
 ```ts
 // @ai-snippets-skip
@@ -22,7 +22,7 @@ useFeeClaimSwap({ mutationOptions });               // Claim partner fees via sw
 
 ## Recovery
 
-Withdraw stuck hub-wallet assets back to a spoke chain. 2 hooks.
+Withdraw stuck hub-wallet assets back to a spoke chain.
 
 ```ts
 // @ai-snippets-skip
@@ -32,7 +32,7 @@ useWithdrawHubAsset({ mutationOptions });
 
 ## Backend queries (read-only data)
 
-12 hooks. No wallet connection required.
+No wallet connection required.
 
 ### Intent tracking
 

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

@@ -29,10 +29,38 @@ useUserFormattedSummary({ params, queryOptions });     // Health factor, collate
 useUserReservesData({ params, queryOptions });         // Per-reserve user position
 
 // aTokens
-useAToken({ params, queryOptions });                   // aToken metadata
-useATokensBalances({ params, queryOptions });          // aToken balances
+useAToken({ params: { aToken }, queryOptions });                                  // aToken metadata (single)
+useATokensBalances({ params: { aTokens, spokeChainKey, userAddress }, queryOptions }); // aToken balances (batched multicall)
 ```
 
+### Read-hook param shapes
+
+```ts
+// @ai-snippets-skip
+// useUserFormattedSummary / useUserReservesData — user-position queries
+type UseUserFormattedSummaryParams = ReadHookParams<FormatUserSummaryResponse, {
+  spokeChainKey: SpokeChainKey | undefined;
+  userAddress: string | undefined;
+}>;
+// Same shape on useUserReservesData. The hook derives the hub wallet from (spokeChainKey, userAddress) internally.
+
+// useAToken — single aToken metadata; FLAT (no chain/user fields)
+type UseATokenParams = ReadHookParams<ATokenData, {
+  aToken: Address | string | undefined;
+}>;
+// ATokenData = Erc20Token & { chainKey: ChainKey }
+
+// useATokensBalances — batched aToken balances
+type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
+  aTokens: readonly Address[];
+  spokeChainKey: SpokeChainKey | undefined;
+  userAddress: string | undefined;
+}>;
+// Returns a Map keyed by aToken address. The hook resolves the hub wallet from (spokeChainKey, userAddress).
+```
+
+> **Read-side chain key is `spokeChainKey`, not `srcChainKey`.** Mutation hooks (`useSupply`/`useBorrow`/etc.) use `srcChainKey` because the request crosses chains and needs a source. Read hooks describe a user's position on a single spoke chain — the field is `spokeChainKey`. Applies to `useATokensBalances`, `useUserFormattedSummary`, and `useUserReservesData` (`useAToken` is metadata-only and takes neither). Don't grep-replace one for the other.
+
 ## Mutation params
 
 All four user mutations share the same TVars shape (only the `action` literal differs):

package/ai-exported/integration/recipes/money-market.md

@@ -191,16 +191,17 @@ type MoneyMarketSupplyParams<K extends SpokeChainKey = SpokeChainKey> = {
   token: string;
   amount: bigint;
   action: 'supply';
-  toChainId?: SpokeChainKey;
-  toAddress?: string;
+  dstChainKey?: SpokeChainKey;
+  dstAddress?: string;
 };
 
-// Borrow / Withdraw / Repay follow the same shape with their respective `action` literal.
+// Borrow / Withdraw / Repay follow the same shape with their respective `action` literal
+// (`'borrow'` / `'withdraw'` / `'repay'`) and the same `src*` / `dst*` field names.
 ```
 
 ## Notes
 
 - **Borrow/withdraw skip approval** — `useMMAllowance` returns `true` automatically for these actions.
 - **Health factor < 1.0** means liquidation risk.
-- All operations support optional `toChainId` / `toAddress` (and `fromChainId` / `fromAddress` on borrow) for cross-chain delivery.
+- All four operations (supply / borrow / withdraw / repay) accept optional `dstChainKey` / `dstAddress` for cross-chain delivery — omit both for same-chain. There are no `from*` / `to*` field variants on any action.
 - Mutations throw on SDK failure — use `mutateAsyncSafe` for `Result<T>` ergonomics without `try/catch`.

package/ai-exported/integration/recipes/setup.md

@@ -47,6 +47,30 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
+### Config reactivity
+
+`SodaxProvider`'s `config` prop is tracked by **reference**, not by value. The SDK is re-instantiated whenever the prop identity changes - resetting wagmi connection state, in-flight RPC, and any persisted state inside `useSodaxContext` consumers. Choose the pattern that matches your config source:
+
+```tsx
+// @ai-snippets-skip — illustrative; uses placeholder values + JSX without surrounding imports
+// ✅ Static config — module constant (preferred when nothing depends on runtime state).
+const sodaxConfig: DeepPartial<SodaxConfig> = {
+  chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: '...' } },
+};
+
+// ✅ Runtime-switchable config — useMemo with explicit deps.
+//    Re-runs only when listed deps change, so the SDK survives unrelated re-renders.
+const sodaxConfig = useMemo(
+  () => ({ solver: solverConfigMap[solverEnv], chains: { ... } }),
+  [solverEnv], // SDK re-inits when solverEnv switches.
+);
+
+// ❌ Inline — new identity every parent render, SDK churns on every render.
+<SodaxProvider config={{ chains: { ... } }}>
+```
+
+Drive runtime config switches (solver env, feature flags, etc.) through `useMemo` deps - never remount `SodaxProvider` for them.
+
 ### Optional: Add Wallet Provider
 
 If you want to use `@sodax/wallet-sdk-react` for wallet connectivity, wrap `SodaxWalletProvider` inside `QueryClientProvider`:

package/ai-exported/integration/recipes/wallet-connectivity.md

@@ -99,3 +99,30 @@ function SwapButton() {
 ```
 
 This pattern is consistent across all features: `useSwap`, `useBridge`, `useSupply`, `useStake`, `useDexDeposit`, etc.
+
+## No type cast is needed — broad-union wiring just works
+
+A common anti-pattern is reaching for `as any` / `as IEvmWalletProvider` when the runtime-typed `walletProvider` from `useWalletProvider({ xChainId })` is passed into a mutation hook. **That cast is not needed.** v2 accepts the broad-union wallet-provider type as long as the chain key on the payload and the wallet provider both come from the same runtime `xChainId` value.
+
+```tsx
+// @ai-snippets-skip — illustrative anti-pattern vs correct
+// ❌ ANTI-PATTERN — unnecessary cast
+const walletProvider = useWalletProvider({ xChainId });
+await swap({ params, walletProvider: walletProvider as any });           // don't
+await swap({ params, walletProvider: walletProvider as IEvmWalletProvider }); // don't
+
+// ✅ CORRECT — pass directly, TypeScript infers the relationship
+const walletProvider = useWalletProvider({ xChainId });
+if (!walletProvider) return;        // narrow undefined first
+await swap({ params, walletProvider });
+```
+
+### Why this works
+
+- `useWalletProvider({ xChainId })` returns `GetWalletProviderType<typeof xChainId> | undefined`. When `xChainId` is a runtime value (e.g. from props/state typed `SpokeChainKey`), the return type is the **broad union** `IWalletProvider | undefined`, not `any`.
+- Mutation hooks like `useSwap<K>()` default `K` to the broad `SpokeChainKey` union. Their `mutate` vars are typed `{ params: SwapParams<SpokeChainKey>, walletProvider: GetWalletProviderType<SpokeChainKey> }` — i.e. `walletProvider` is the same broad union.
+- The two unions are structurally assignable. No cast required.
+
+### When the cast is actually needed
+
+If you've narrowed `xChainId` to a literal (e.g. via `chainKey === ChainKeys.BSC_MAINNET` checks in a branch) and the mutation hook is also generic-narrowed, you'll get narrower types on both sides. Even there, the cast is usually unnecessary — TypeScript propagates the narrowed `K` through the hook's generic. Reach for a cast only when you can produce a real TS error message proving it's needed.

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

@@ -4,7 +4,7 @@ Lookup tables. Read while writing code; not a tutorial.
 
 | File | What's in it |
 |---|---|
-| [`hooks-index.md`](hooks-index.md) | Comprehensive hook table (95 hooks, organized by feature, with hook type and purpose). |
+| [`hooks-index.md`](hooks-index.md) | Comprehensive hook table (organized by feature, with hook type and purpose). |
 | [`querykey-conventions.md`](querykey-conventions.md) | Mandatory queryKey/mutationKey shape rules + per-feature key tables. |
 | [`public-api.md`](public-api.md) | What `@sodax/dapp-kit` exports + import rules. |
 | [`glossary.md`](glossary.md) | Type aliases (`ReadHookParams`, `MutationHookParams`, `SafeUseMutationResult`, `MutationHookOptions`, etc.). |

package/ai-exported/integration/reference/glossary.md

@@ -132,6 +132,8 @@ App-level React component. Provides:
 
 Optional config: `<SodaxProvider config={DeepPartial<SodaxConfig>}>`. Without config, SDK uses packaged defaults.
 
+Config is tracked by **reference** - see [`recipes/setup.md § Config reactivity`](../recipes/setup.md#config-reactivity) for module-const vs `useMemo` patterns.
+
 ### `createSodaxQueryClient`
 
 Factory for a `QueryClient` with `MutationCache.onError` pre-wired for global mutation observability. Optional — if you construct your own `QueryClient`, dapp-kit hooks still work; you just don't get the global observability seam.

package/ai-exported/integration/reference/hooks-index.md

@@ -1,6 +1,6 @@
 # Hooks index — `@sodax/dapp-kit` v2
 
-Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you know the feature you're building but don't remember the exact hook name.
+Comprehensive hook table across 11 feature domains. Use this when you know the feature you're building but don't remember the exact hook name.
 
 ## Provider + context
 
@@ -11,7 +11,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useSodaxContext` | Utility | Access the `Sodax` SDK instance |
 | `useHubProvider` | Utility | Hub chain (Sonic) provider |
 
-## Swap (8)
+## Swap
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -24,7 +24,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useCreateLimitOrder` | Mutation | Create a limit order (no deadline) |
 | `useCancelLimitOrder` | Mutation | Cancel a limit order |
 
-## Money market (13)
+## Money market
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -43,7 +43,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useAToken` | Query | aToken metadata |
 | `useATokensBalances` | Query | aToken balances |
 
-## Bridge (5)
+## Bridge
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -53,7 +53,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useGetBridgeableAmount` | Query | Max bridgeable amount between two `XToken`s |
 | `useGetBridgeableTokens` | Query | Tokens bridgeable to a destination chain |
 
-## Staking (~18)
+## Staking
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -76,7 +76,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useInstantUnstakeRatio` | Query | Instant unstake rate |
 | `useConvertedAssets` | Query | xSODA → SODA conversion |
 
-## DEX (~13)
+## DEX
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -97,7 +97,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useCreateSupplyLiquidityParams` | Param builder | Build tick-range + liquidity params |
 | `useCreateDecreaseLiquidityParams` | Param builder | Build decrease params from position state |
 
-## Migration (6)
+## Migration
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -108,7 +108,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useMigrationApprove` | Mutation | Approve before migration (action-discriminated) |
 | `useMigrationAllowance` | Query | Approval check (action-discriminated) |
 
-## Bitcoin / Radfi (~8)
+## Bitcoin / Radfi
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -122,7 +122,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useExpiredUtxos` | Query | Expired UTXOs (polls 60s) |
 | `useRenewUtxos` | Mutation | Renew expired UTXOs |
 
-## Backend queries (~13)
+## Backend queries
 
 ### Intents
 
@@ -151,7 +151,7 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
 | `useBackendAllMoneyMarketBorrowers` | All borrowers |
 
-## Partner (6)
+## Partner
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -162,14 +162,14 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `useSetSwapPreference` | Mutation | Set swap preference |
 | `useFeeClaimSwap` | Mutation | Claim partner fees via swap |
 
-## Recovery (2)
+## Recovery
 
 | Hook | Type | Purpose |
 |---|---|---|
 | `useHubAssetBalances` | Query | Hub asset balances |
 | `useWithdrawHubAsset` | Mutation | Withdraw hub asset |
 
-## Shared (~9)
+## Shared
 
 | Hook | Type | Purpose |
 |---|---|---|
@@ -183,10 +183,6 @@ Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you
 | `unwrapResult` | Internal | `Result<T>` → throw / return |
 | `toResult` | Internal | `Promise<T>` → `Result<T>` |
 
-## Total
-
-41 mutations + ~50 queries + utilities + provider = **~95 hooks**.
-
 ## Cross-references
 
 - [`../features/`](../features/) — per-feature reference docs (params types, return shapes, gotchas).

package/ai-exported/integration/reference/public-api.md

@@ -8,14 +8,14 @@ The package's `src/index.ts` re-exports four buckets:
 
 ```ts
 // @ai-snippets-skip
-export * from './hooks/index.js';      // ~95 hooks across 11 feature dirs
+export * from './hooks/index.js';      // hooks across 11 feature dirs
 export * from './providers/index.js';  // SodaxProvider, createSodaxQueryClient
 export * from './utils/index.js';      // dex-utils param builders
 export * from '@sodax/sdk';            // FULL @sodax/sdk re-export
 ```
 
 Practical implications:
-- All ~95 hooks are importable from the root: `import { useSwap, useSupply, ... } from '@sodax/dapp-kit'`.
+- All hooks are importable from the root: `import { useSwap, useSupply, ... } from '@sodax/dapp-kit'`.
 - All `@sodax/sdk` types are importable from `@sodax/dapp-kit` directly: `import { ChainKeys, type SodaxConfig, type CreateIntentParams } from '@sodax/dapp-kit'`.
 - You may also import directly from `@sodax/sdk` — both work, both are stable.
 

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

@@ -96,6 +96,8 @@ Full SDK-level detail: [`../../../../sdk/ai-exported/migration/breaking-changes/
 + }}>
 ```
 
+**Config is tracked by reference in v2.** See [`../../integration/recipes/setup.md § Config reactivity`](../../integration/recipes/setup.md#config-reactivity) for the module-const vs `useMemo` patterns. Drive runtime config switches (e.g. solver env) through `useMemo` deps, not by remounting the provider.
+
 Other v1 fields renamed or restructured:
 
 | v1 | v2 |

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

@@ -4,7 +4,7 @@ Pair: [`../../integration/features/auxiliary-services.md`](../../integration/fea
 
 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)
+## Partner
 
 ```diff
 - const claim = useFeeClaimSwap(spokeProvider);
@@ -18,7 +18,7 @@ Smaller surfaces grouped together: partner, recovery, backend queries, shared ut
 
 `useFetchAssetsBalances`, `useGetAutoSwapPreferences`, `useIsTokenApproved` — convert to single-object query shape.
 
-## Recovery (2 hooks)
+## Recovery
 
 ```diff
 - const withdraw = useWithdrawHubAsset(spokeProvider);
@@ -26,7 +26,7 @@ Smaller surfaces grouped together: partner, recovery, backend queries, shared ut
 + await withdraw({ params, walletProvider });
 ```
 
-## Backend queries (~13 hooks)
+## Backend queries
 
 Read-only. No `walletProvider` involved. Convert to single-object query shape.
 

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

@@ -9,9 +9,11 @@ Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge
 1. **`CreateBridgeIntentParams` field renames** (SDK-leakage):
    - `srcChainId` → `srcChainKey`
    - `dstChainId` → `dstChainKey`
-   - `recipient` → `dstAddress`
-   - **NEW required**: `srcAddress`
-2. **`useBridge` return is `TxHashPair`, not a tuple.** v1 may have returned `[spokeTxHash, hubTxHash]`; v2 returns `{ srcChainTxHash, dstChainTxHash }`. Don't destructure as array.
+   - `srcAsset` → `srcToken`
+   - `dstAsset` → `dstToken`
+   - `recipient` is **unchanged** (stays `recipient` in v2 — it is NOT renamed to `dstAddress`; the only `dstAddress`-shaped field in v2 lives on money-market params, not bridge)
+   - **NEW required**: `srcAddress` (the user's spoke-side sender address, distinct from `recipient` which is the destination)
+2. **`bridge()` return shape changed.** v1 was `Promise<string>` (a single tx hash that threw on error). v2 returns `Promise<Result<TxHashPair, BridgeOrchestrationError>>` where `TxHashPair = { srcChainTxHash: string; dstChainTxHash: string }`. **This is the shape at the direct-SDK boundary** (`sodax.bridge.bridge(...)`); the `useBridge` hook does not adapt the inner object, it only unwraps the `Result` wrapper (so the hook surfaces `TxHashPair` directly via `data` / `mutateAsync` / `mutateAsyncSafe`'s `value`). Don't destructure as a tuple — there was no `[spokeTxHash, hubTxHash]` form in either v1 or v2.
 3. **`useGetBridgeableAmount` reshape.** v1 took `(srcChainId, srcAsset, dstChainId, dstAsset)`. v2 takes `{ from: XToken, to: XToken }` — each `XToken` carries its own `chainKey`.
 4. **`useGetBridgeableAmount` return value is `BridgeLimit`, not bare `bigint`.** Access `.value.amount` and `.value.decimals`.
 5. **`useGetBridgeableTokens` is sync now** in the SDK. The hook still returns `UseQueryResult` but the underlying SDK call doesn't fire RPC — it's config-derived.
@@ -29,7 +31,8 @@ Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge
 
     const handleBridge = async () => {
 +     if (!walletProvider) return;
--     const result = await bridge.mutateAsync({
+-     // v1: single tx hash, throws on failure
+-     const txHash: string = await bridge.mutateAsync({
 -       params: {
 -         srcChainId: BASE_MAINNET_CHAIN_ID,
 -         srcAsset: '0x...',
@@ -39,28 +42,62 @@ Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge
 -         recipient: '0x...',
 -       },
 -     });
--     if (result.ok) {
--       const [spokeTxHash, hubTxHash] = result.value;
--       /* ... */
--     }
 +     const result = await bridge({
 +       params: {
 +         srcChainKey: ChainKeys.BASE_MAINNET,
-+         srcAddress,                                  // NEW: required
-+         srcAsset: '0x...',
++         srcAddress,                                  // NEW: required (your spoke-side sender)
++         srcToken: '0x...',                           // RENAMED from `srcAsset`
 +         amount: 1_000_000n,
 +         dstChainKey: ChainKeys.POLYGON_MAINNET,
-+         dstAsset: '0x...',
-+         dstAddress: '0x...',                         // RENAMED from `recipient`
++         dstToken: '0x...',                           // RENAMED from `dstAsset`
++         recipient: '0x...',                          // UNCHANGED — destination receiver
 +       },
 +       walletProvider,
 +     });
 +     if (!result.ok) return;
-+     const { srcChainTxHash, dstChainTxHash } = result.value;   // OBJECT, not tuple
++     const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair object, not [a, b]
     };
   }
 ```
 
+### Calling `sodax.bridge.bridge()` directly (no hook)
+
+If you call the SDK directly inside a custom `useMutation` (instead of `useBridge`), the return shape is **exactly the same** — the dapp-kit hook only unwraps the `Result` wrapper, it does not reshape `TxHashPair`:
+
+```diff
+- // v1 direct-SDK call:
+- const txHash: string = await sodax.bridge.bridge({ params: { /* v1 shape */ }, spokeProvider });
++ // v2 direct-SDK call:
++ const result = await sodax.bridge.bridge({
++   params: {
++     srcChainKey: ChainKeys.BASE_MAINNET,
++     srcAddress,
++     srcToken: '0x...',
++     amount: 1_000_000n,
++     dstChainKey: ChainKeys.POLYGON_MAINNET,
++     dstToken: '0x...',
++     recipient: '0x...',
++   },
++   raw: false,
++   walletProvider,
++ });
++ // Type: Result<TxHashPair, BridgeOrchestrationError>
++ if (!result.ok) {
++   // result.error is a SodaxError<C> with feature: 'bridge'
++   return;
++ }
++ const { srcChainTxHash, dstChainTxHash } = result.value;   // same shape as the hook
+```
+
+The hook equivalence in code:
+
+```ts
+// @ai-snippets-skip
+// What `useBridge` does internally (sketch):
+// mutationFn: async vars => unwrapResult(await sodax.bridge.bridge({ ...vars, raw: false }))
+// `unwrapResult` throws on `!ok` and returns `value` on `ok` — that's the only adapter.
+```
+
 ### `useGetBridgeableAmount` — params + return reshape
 
 ```diff

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

@@ -10,7 +10,7 @@ Pair: [`../../integration/features/money-market.md`](../../integration/features/
 2. **`MoneyMarketSupplyParams<K>` (and the four similar action-param types) gained required `srcChainKey` + `srcAddress`** — SDK-leakage.
 3. **`useMMAllowance` auto-skips on-chain checks for borrow/withdraw** — v1 may have had this too, but v2 returns `true` synchronously for those actions instead of issuing a no-op RPC.
 4. **`useMMApprove` returns standard `SafeUseMutationResult`** — `isLoading` → `isPending`.
-5. **Reserve data hooks renamed `address` → `userAddress`** in some queries (`useUserFormattedSummary`, `useUserReservesData`).
+5. **Position / aToken-balance hooks renamed `address` → `userAddress`.** Applies to `useUserFormattedSummary`, `useUserReservesData`, **and `useATokensBalances`** (which also drops `spokeProvider` and adds a required `spokeChainKey` alongside `aTokens` + `userAddress`). `useAToken` is unaffected — it takes only `{ aToken }`.
 
 ## Per-method delta
 
@@ -45,7 +45,25 @@ Pair: [`../../integration/features/money-market.md`](../../integration/features/
   }
 ```
 
-`useBorrow`, `useWithdraw`, `useRepay` follow the same pattern with their respective `action` literals (`'borrow'` / `'withdraw'` / `'repay'`). Borrow + repay can specify optional `dstChainKey` / `dstAddress` for cross-chain delivery.
+`useBorrow`, `useWithdraw`, `useRepay` follow the same pattern with their respective `action` literals (`'borrow'` / `'withdraw'` / `'repay'`). **All four MM action params share an identical field shape** — only the `action` literal differs:
+
+```ts
+// @ai-snippets-skip
+// MoneyMarketSupplyParams<K> | MoneyMarketBorrowParams<K> | MoneyMarketWithdrawParams<K> | MoneyMarketRepayParams<K>
+{
+  srcChainKey: K;                  // required — where the user signs / funds come from
+  srcAddress: string;              // required — user's spoke-side address on srcChainKey
+  token: string;                   // token on srcChainKey (supply/repay) or on dstChainKey (borrow/withdraw)
+  amount: bigint;
+  action: 'supply' | 'borrow' | 'withdraw' | 'repay';
+  dstChainKey?: SpokeChainKey;     // optional — defaults to srcChainKey (same-chain)
+  dstAddress?: string;             // optional — defaults to srcAddress (same-chain)
+}
+```
+
+Cross-chain delivery via `dstChainKey` / `dstAddress` is supported on **all four** actions, not just borrow/repay. Omit both for same-chain operations.
+
+> **Porting note** — v2 does NOT use `fromChainKey` / `fromAddress` / `toChainKey` / `toAddress` (or `fromChainId` / `toChainId`) on any MM action. Borrow and repay use the **same** `src*` / `dst*` field names as supply and withdraw — the v2 type system unified the cross-chain shape across all four actions. If your v1 call sites or app types carry `from*` / `to*` naming for the spend-chain vs. debt-chain, rename to `src*` / `dst*` (e.g. `fromChainKey → srcChainKey`, `toChainKey → dstChainKey`). See the SDK migration doc cross-link below for explicit borrow/repay diff examples.
 
 ### `useMMAllowance` — auto-skip
 
@@ -82,11 +100,35 @@ User-position hooks renamed param fields:
 + const { data } = useUserFormattedSummary({ params: { spokeChainKey, userAddress } });
 ```
 
+Same shape on `useUserReservesData`.
+
+### `useATokensBalances`
+
+```diff
+- const { data: balances } = useATokensBalances({ aTokens, spokeProvider, userAddress });
++ const { data: balances } = useATokensBalances({
++   params: {
++     aTokens,                                  // readonly Address[]
++     spokeChainKey,                            // SpokeChainKey — NOT `srcChainKey`
++     userAddress,                              // string — spoke-side user address (renamed from `address` if you're porting from any earlier shape)
++   },
++ });
++ // data: Map<Address, bigint> | undefined (already unwrapped — hook throws on SDK !ok)
+```
+
+Three things to verify when porting:
+
+- `spokeProvider` is gone — the hook derives the hub wallet internally from `(spokeChainKey, userAddress)` via `EvmHubProvider.getUserHubWalletAddress`.
+- The chain-key field is **`spokeChainKey`**, not `srcChainKey`. `src*` names belong to mutation params (`useSupply`/`useBorrow`/etc.) — read hooks for a single-chain position use `spokeChainKey`.
+- The user-address field is **`userAddress`**, not `address` — same rename as `useUserFormattedSummary` and `useUserReservesData`.
+
+`useAToken` (metadata-only) is unaffected by the user/chain renames — it takes only `{ aToken }`.
+
 ## Pitfalls
 
 1. **`srcAddress` is the user's spoke-side address**, not the hub address. Hub wallet is derived internally.
 2. **`useMMAllowance` returns `true` instantly for borrow/withdraw** — don't wait on the query state. Branch on `isApproved` directly.
-3. **Cross-chain borrow/repay**: omit `dstChainKey` / `dstAddress` for same-chain. Don't pass `dstChainKey === srcChainKey` (let the default kick in).
+3. **Cross-chain delivery (all four actions)**: omit `dstChainKey` / `dstAddress` for same-chain. Don't pass `dstChainKey === srcChainKey` (let the default kick in). The field names are `src*` / `dst*` on **every** MM action — there is no `from*` / `to*` variant.
 4. **`MoneyMarketSupplyParams<K>` is now generic.** Use `as const` on `srcChainKey` for narrowing: `srcChainKey: ChainKeys.BASE_MAINNET as const`.
 
 ## Cross-references