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

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>`.

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/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/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/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

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

@@ -27,7 +27,9 @@ Pair: [`../../integration/features/swap.md`](../../integration/features/swap.md)
 +     if (!walletProvider) return;
 -     const result = await swap.mutateAsync({ params: intentParams });
 -     if (result.ok) {
--       const { intent, intentDeliveryInfo } = result.value;
+-       // v1: result.value was a TUPLE — destructure positionally
+-       const [executionResponse] = result.value;
+-       const txHash = executionResponse.intent_hash;
 -       /* ... */
 -     } else {
 -       toast.error(result.error.message);
@@ -37,12 +39,25 @@ Pair: [`../../integration/features/swap.md`](../../integration/features/swap.md)
 +       toast.error(result.error instanceof Error ? result.error.message : 'Swap failed');
 +       return;
 +     }
-+     const { intent, intentDeliveryInfo } = result.value;
++     // v2: result.value is a NAMED OBJECT (SwapResponse) — destructure by name
++     const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
++     const intentHash = solverExecutionResponse.intent_hash;       // protocol-level intent id (v1 ≈ executionResponse.intent_hash)
++     const spokeTxHash = intentDeliveryInfo.srcTxHash;             // on-chain tx hash on srcChainKey — use for tx-history display
 +     /* ... */
     };
   }
 ```
 
+#### `SwapResponse` field map (`result.value`)
+
+| Field | Type | Use it for |
+|---|---|---|
+| `solverExecutionResponse` | `{ answer: 'OK'; intent_hash: Hex }` | Protocol-level intent identifier. **`solverExecutionResponse.intent_hash` is the v2 equivalent of v1's `executionResponse.intent_hash`.** Pass it to `useStatus({ params: { intentTxHash } })` to poll execution status. |
+| `intent` | `Intent` | Intent metadata (`intentId: bigint`, `creator`, tokens, amounts, `srcChain`/`dstChain` as `IntentRelayChainId` bigints). **No transaction hashes on this object** — don't read `intent.intent_hash` (does not exist) or `intent.tx_hash`. |
+| `intentDeliveryInfo` | `{ srcChainKey, srcTxHash, srcAddress, dstChainKey, dstTxHash, dstAddress }` | **On-chain transaction hashes.** `srcTxHash` is the spoke-chain tx on `srcChainKey` (the one that typically feeds a user-facing transaction history); `dstTxHash` is the delivery tx on `dstChainKey`. |
+
+**Porting `[executionResponse] = result.value` (v1 tuple) → v2:** rename to `{ solverExecutionResponse } = result.value`. Any `executionResponse.intent_hash` read becomes `solverExecutionResponse.intent_hash`. If the value was being used as the **transaction hash** in a transaction-history row (not as the intent identifier), switch to `intentDeliveryInfo.srcTxHash` instead — `intent_hash` and `srcTxHash` are not interchangeable.
+
 ### `useSwapApprove` — return shape
 
 ```diff

package/ai-exported/migration/recipes.md

@@ -42,28 +42,25 @@ for (const file of project.getSourceFiles('src/**/*.{ts,tsx}')) {
 await project.save();
 ```
 
-## Codemod 2: useSpokeProvider deletion
+## Codemod 2: useSpokeProvider deletion (2-arg → 1-arg)
 
-`useSpokeProvider` is gone in v2. Delete the import + usage; replace with `useWalletProvider` from `@sodax/wallet-sdk-react`.
+`useSpokeProvider` is gone in v2. Replace with `useWalletProvider` from `@sodax/wallet-sdk-react`.
 
-```bash
-# 1. Find all usages first.
-grep -rE '\buseSpokeProvider\b' src/
-
-# 2. Manual delete + rewrite each (no safe sed for this — context varies).
-```
-
-Per call site, the rewrite:
+v1 had **two positional args**: `useSpokeProvider(spokeChainId, walletProvider)`. v2 collapses to a single options object: `useWalletProvider({ xChainId })`. The second v1 argument is **dropped entirely** — v2 resolves the wallet provider from the wallet-sdk-react store internally based on `xChainId`. If your v1 code constructed a wallet provider separately to pass in, delete that construction code too.
 
 ```diff
+- // v1 — 2 positional args (chainKey + walletProvider)
 - import { useSpokeProvider } from '@sodax/dapp-kit';
-- const spokeProvider = useSpokeProvider({ chainId: BSC_MAINNET_CHAIN_ID });
+- const spokeProvider = useSpokeProvider(srcChainId, walletProvider);
+
++ // v2 — 1 options arg, no external walletProvider
 + import { useWalletProvider } from '@sodax/wallet-sdk-react';
-+ import { ChainKeys } from '@sodax/sdk';
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
++ const walletProvider = useWalletProvider({ xChainId: srcChainId });
 ```
 
-Then update consumers of `spokeProvider` to use `walletProvider` instead — usually inside `mutate(vars)` payloads, sometimes inside query hook params.
+A naive single-pass regex over `useSpokeProvider\(([^)]+)\)` eats both args and produces invalid `useWalletProvider({ xChainId: chainKey, walletProvider })`. Do the rewrite in two passes: first the call shape (drop the second positional arg), then the import (from `@sodax/dapp-kit` → `@sodax/wallet-sdk-react`). A small number of v1 callers used the single-arg form `useSpokeProvider(chainId)` — handle those separately since they don't have a second arg to drop.
+
+Update downstream consumers of `spokeProvider` to use `walletProvider` instead — usually inside `mutate(vars)` payloads or query hook params. The field name on payloads also renamed `spokeProvider:` → `walletProvider:` (see `@sodax/sdk/ai-exported/migration/checklist.md` step 7b).
 
 ## Codemod 3: invalidate*Queries utilities deletion
 

package/ai-exported/migration/reference/renamed-hooks.md

@@ -29,6 +29,8 @@ These keep their name but their TypeScript signature is different. Usually requi
 | `useMMAllowance` | Query params: `{ params: { payload: MoneyMarketParams<K> } }`. For `'borrow'` / `'withdraw'` actions: `enabled: false` — `data` stays `undefined`. |
 | `useUserReservesData` | Param key rename: `address → userAddress`; chain key is `spokeChainKey`. |
 | `useUserFormattedSummary` | Same. |
+| `useATokensBalances` | Params: `{ aTokens, spokeProvider, userAddress } → { params: { aTokens, spokeChainKey, userAddress } }`. `spokeProvider` dropped; chain key is **`spokeChainKey`** (NOT `srcChainKey`); user field is **`userAddress`** (NOT `address`). Data: `Map<Address, bigint> \| undefined` (already unwrapped). |
+| `useAToken` | Unaffected by the position-hook renames — takes only `{ aToken }`. Data: `Erc20Token & { chainKey }` (`hubAsset` / `vault` NOT included). |
 | All staking mutations | Same as MM. Plus dedicated approve hooks per token (`useStakeApprove` ↔ `useUnstakeApprove` ↔ `useInstantUnstakeApprove`). |
 | `useStakeRatio` | Return: `Result<bigint> → [xSodaAmount, previewDepositAmount]` (unwrapped tuple — NOT Result-wrapped in v2). |
 | `useStakingInfo` / `useUnstakingInfo` / `useUnstakingInfoWithPenalty` / `useStakingConfig` / `useInstantUnstakeRatio` / `useConvertedAssets` | All unwrapped in v2 (hooks throw on SDK `!ok`). Branch on `isError`/`error`, not `data?.ok`. |

package/dist/index.cjs

@@ -2484,10 +2484,9 @@ function useClaimRewards({
   });
 }
 var SodaxProvider = ({ children, config }) => {
-  const configRef = react.useRef(config);
-  const frozen = configRef.current;
-  const sodax = react.useMemo(() => new sdk.Sodax(frozen), [frozen]);
-  return /* @__PURE__ */ jsxRuntime.jsx(SodaxContext.Provider, { value: { sodax }, children });
+  const sodax = react.useMemo(() => new sdk.Sodax(config), [config]);
+  const contextValue = react.useMemo(() => ({ sodax }), [sodax]);
+  return /* @__PURE__ */ jsxRuntime.jsx(SodaxContext.Provider, { value: contextValue, children });
 };
 var defaultOnMutationError = (error) => {
   console.error("[sodax] Mutation error:", error);