@sodax/wallet-sdk-react 1.5.7-beta → 2.0.0-rc.2

package/ai-exported/migration/README.md

@@ -0,0 +1,49 @@
+# Migration: v1 → v2 (Human-readable overview)
+
+This folder documents how to migrate an app from v1 to v2 of `@sodax/wallet-sdk-react`. The package name did not change — the breaking changes are in the API surface (provider config, hook signatures, store name, chain class imports). It is the **human-facing** entry point for migration. If you are a coding agent, read [`ai-rules.md`](./ai-rules.md) first.
+
+---
+
+## What changed at a high level
+
+v2 is a near-rewrite of v1 with a focus on three goals:
+
+1. **Configurable chain opt-in** — v1 always mounted every chain adapter. v2 lets you opt in per chain by including only the slots you need on `SodaxWalletConfig`.
+2. **Single source of truth for chain config** — v1 spread chain config across `rpcConfig`, `options`, and `initialState`. v2 collapses these into one `config` object on `SodaxWalletProvider`.
+3. **Store-first hooks** — v2 hooks all read from a central Zustand store; no chain-specific React context coupling. This makes hooks composable and testable in isolation.
+
+The persisted localStorage key (`xwagmi-store`) is **unchanged** — existing user connections survive the migration boundary.
+
+> Full prose on motivations and behavior changes lives in [`breaking-changes.md`](./breaking-changes.md).
+
+---
+
+## Read order
+
+If you are migrating by hand, read in this order:
+
+1. [`breaking-changes.md`](./breaking-changes.md) — every breaking change with the WHY behind it.
+2. [`reference/imports.md`](./reference/imports.md) — package and path renames (mechanical).
+3. [`reference/config.md`](./reference/config.md) — `SodaxWalletProvider` config shape (this is the biggest single change).
+4. [`reference/hooks.md`](./reference/hooks.md) — hook signature and rename map.
+5. [`reference/components.md`](./reference/components.md) — component / provider renames.
+6. [`recipes/`](./recipes/) — paired before/after for common patterns (connect button, multi-chain modal, SSR, WalletConnect).
+7. [`checklist.md`](./checklist.md) — final verification pass; tick each item before declaring done.
+
+If you are letting a coding agent drive the migration, point it at [`ai-rules.md`](./ai-rules.md) — that file gives the agent its workflow, stop conditions, and verification protocol.
+
+---
+
+## What is NOT covered here
+
+- **Other SODAX packages** (`@sodax/sdk`, `@sodax/dapp-kit`). They have their own migration docs in their respective `ai-exported/` folders.
+- **Behavioral migration of business logic** that isn't tied to wallet hooks — out of scope.
+- **App framework upgrades** (Next.js, Vite versions) — out of scope.
+
+---
+
+## Getting help
+
+If you hit a v1 pattern not covered in `reference/` or `recipes/`, please [open an issue](https://github.com/icon-project/sodax-sdks/issues) with the v1 code snippet — we'll add it to the docs.
+
+For internal SODAX maintainers: see `../CLAUDE.md` for architecture context.

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

@@ -0,0 +1,144 @@
+# AI Rules — v1 → v2 Migration
+
+You are migrating a user's app from v1 to v2 of `@sodax/wallet-sdk-react`. The package name did not change — detect v1 by import surface (`useXWagmiStore`, positional hook args, `rpcConfig`/`options`/`initialState` props on `SodaxWalletProvider`, concrete chain class imports from the barrel). Follow this protocol exactly.
+
+---
+
+## Workflow (do these in order)
+
+### 1. Survey
+
+Before changing anything, survey the user's project:
+
+```bash
+# v1 store usage
+grep -rn "useXWagmiStore" <user-src>
+
+# v1 provider props (rpcConfig / options / initialState)
+grep -rn "SodaxWalletProvider" <user-src> -A 5 | grep -E "rpcConfig|initialState|options="
+
+# v1 positional hook args (e.g. useXAccount('EVM'))
+grep -rnE "useXAccount\(['\"]" <user-src>
+grep -rnE "useXConnectors\(['\"]" <user-src>
+grep -rnE "useXConnection\(['\"]" <user-src>
+grep -rnE "useXService\(['\"]" <user-src>
+grep -rnE "useWalletProvider\(['\"]" <user-src>
+
+# v1 concrete chain class imports from the barrel
+grep -rnE "from '@sodax/wallet-sdk-react'" <user-src> | grep -E "XService|XConnector"
+```
+
+Build a list of every file that uses a v1 pattern. Show this list to the user before proceeding.
+
+### 2. Bump the package version
+
+Update `@sodax/wallet-sdk-react` to the latest v2 release in the user's `package.json`. Run install. **Do not edit any source files yet** — keep TypeScript broken so you can use compiler errors as a worklist.
+
+### 3. Migrate the provider first
+
+Always migrate `SodaxWalletProvider` (or v1's `XWagmiProviders`) before touching consumer files. The config shape is the biggest change — see [`reference/config.md`](./reference/config.md) and [`recipes/`](./recipes/) for the new pattern. Without a working provider, hooks will fail at runtime even if types pass.
+
+### 4. Run typecheck, use errors as worklist
+
+```bash
+pnpm checkTs
+```
+
+For each error mentioning `@sodax/wallet-sdk-react` or a v1 hook name:
+
+1. Look up the symbol in [`reference/imports.md`](./reference/imports.md), [`reference/hooks.md`](./reference/hooks.md), [`reference/config.md`](./reference/config.md), or [`reference/components.md`](./reference/components.md).
+2. If found, apply the mechanical replacement.
+3. If not found, **stop and ask the user**. Do not invent a migration.
+
+### 5. Apply recipes for non-mechanical changes
+
+Some patterns require structural rewrites, not just symbol swaps. Use the matching recipe file:
+
+- Connect button → [`recipes/connect-button.md`](./recipes/connect-button.md)
+- Multi-chain modal → [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md)
+- Next.js SSR setup → [`recipes/ssr-setup.md`](./recipes/ssr-setup.md)
+- WalletConnect → [`recipes/walletconnect-migration.md`](./recipes/walletconnect-migration.md)
+
+### 6. Verify with the checklist
+
+Loop through every item in [`checklist.md`](./checklist.md). Each item is machine-checkable (most are `grep` commands). Do not skip items. Report results back to the user.
+
+---
+
+## DO
+
+- **DO** read `migration/breaking-changes.md` once at the start to understand the WHY behind changes. This helps you handle ambiguous user code.
+- **DO** preserve user comments, formatting, and unrelated code. Only touch what the migration requires.
+- **DO** update one file at a time, then re-run `pnpm checkTs` to confirm progress.
+- **DO** prefer the official `recipes/` over inventing your own structural rewrite.
+- **DO** treat `reference/*.md` as the only source of truth for symbol mappings. If a mapping is missing, it's a docs gap — flag it.
+- **DO** explicitly check whether the user's project is Next.js (App Router or Pages) before touching providers — SSR config differs.
+
+---
+
+## DO NOT
+
+- **DO NOT** delete v1 imports until the corresponding v2 imports are added and the file typechecks.
+- **DO NOT** rename user files, even if v1 file names look outdated. Keep file paths stable so the user's git history stays clean.
+- **DO NOT** modify tests until source migration is complete — wait for green typecheck first, then update tests as a separate pass.
+- **DO NOT** "improve" surrounding code (refactor, restyle, add error handling, change variable names). Only apply migration changes.
+- **DO NOT** assume v1 prop shapes from memory — always verify against [`reference/config.md`](./reference/config.md). v1 had several optional fields whose defaults differ from v2.
+- **DO NOT** silently drop user features. If v1 used `XWagmiProviders` with `initialState` and v2 has no equivalent, **stop and ask** how to preserve that state initialization.
+- **DO NOT** change the persisted localStorage key (`xwagmi-store`). User connections will be lost across the migration boundary if you do.
+
+---
+
+## Stop conditions (defer to user)
+
+Stop and ask the user before continuing if you encounter any of the following. These cannot be migrated mechanically:
+
+| Signal | Why stop |
+|---|---|
+| Custom `XConnector` subclass in user code | v1 and v2 have different abstract method signatures. User must port manually. |
+| Custom `XService` subclass in user code | Same as above. |
+| User reads from `useXWagmiStore` with a selector touching `setXConnection`, `unsetXConnection`, or any v2-internal field (`enabledChains`, `walletProviders`, `chainActions`, …) | These are not part of the v2 public API. Agent must replace direct store reads with public hooks (`useXServices`, `useXConnections`, etc. — see [`reference/imports.md`](./reference/imports.md) § "Store hook removed"). For mutations the user must adopt `useXConnect` / `useXDisconnect` — confirm before substituting. |
+| User passes `rpcConfig`, `options`, or `initialState` to the v1 provider | These are removed in v2. Migration target is the new `config` object. Verify what behavior the user wants preserved. |
+| Test files that mock `XService` or `XConnector` | Mock surface differs. Tests must be updated by hand with the user's intent in mind. |
+| `apps/wallet-modal-example` is referenced | This is internal SODAX scaffolding, not for end users. |
+| User explicitly says "don't change behavior X" | Some v2 changes are intentional behavior shifts (e.g. EVM = single connection across all networks). Confirm before forcing v1 behavior back. |
+
+When stopping, **quote the file/line** of the offending code and present the user with concrete options.
+
+---
+
+## Verification protocol (after every change)
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Verify no v1 patterns remain
+grep -rn "useXWagmiStore\|useXWalletStore" <user-src>         # expect empty (v2 barrel doesn't export the store hook under either name — all call sites must use public hooks)
+grep -rnE "SodaxWalletProvider[^>]*\b(rpcConfig|initialState|options)\s*=" <user-src>  # expect empty
+grep -rnE "useXAccount\(['\"]" <user-src>                     # expect empty
+grep -rnE "useXConnectors\(['\"]" <user-src>                  # expect empty
+grep -rnE "useXConnection\(['\"]" <user-src>                  # expect empty
+
+# 3. Verify v2 provider is mounted with config prop
+grep -rnE "SodaxWalletProvider[^>]*\bconfig\s*=" <user-src>   # expect at least one match in app entry
+
+# 4. Verify QueryClientProvider wraps SodaxWalletProvider (v2 no longer mounts QueryClient internally)
+# (manual — open the provider file, confirm <QueryClientProvider> wraps <SodaxWalletProvider>)
+```
+
+If all four pass and the [`checklist.md`](./checklist.md) is complete, the migration is done.
+
+---
+
+## Done criteria
+
+The migration is complete when:
+
+- [ ] `pnpm checkTs` exits clean.
+- [ ] No `useXWagmiStore` or `useXWalletStore` imports remain (v2 does not export the store hook — every call site must use public hooks like `useXServices` / `useXConnections`).
+- [ ] No positional hook args remain (`useXAccount('EVM')` etc).
+- [ ] `SodaxWalletProvider` is mounted with a v2-shaped `config` prop, wrapped by `QueryClientProvider`.
+- [ ] All items in [`checklist.md`](./checklist.md) are checked.
+- [ ] The user has confirmed the connect/disconnect flow works in their dev environment.
+
+Do not declare the migration done before all six are true.

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

@@ -0,0 +1,305 @@
+# Breaking Changes: v1 → v2
+
+This is the **single source of truth** for behavior and API changes between v1 and v2 of `@sodax/wallet-sdk-react`. The reference files (`imports.md`, `hooks.md`, `config.md`, `components.md`) are **lookup tables** derived from the changes here — they do not duplicate the prose.
+
+## Table of contents
+
+1. [`SodaxWalletProvider` props (largest change)](#1-sodaxwalletprovider-props-largest-change)
+2. [`QueryClientProvider` is no longer mounted internally](#2-queryclientprovider-is-no-longer-mounted-internally)
+3. [Hooks now take an options object, not positional args](#3-hooks-now-take-an-options-object-not-positional-args)
+4. [Store hook removed from the public API](#4-store-hook-removed-from-the-public-api)
+5. [Concrete chain classes moved behind sub-path imports](#5-concrete-chain-classes-moved-behind-sub-path-imports)
+6. [Chain-type opt-in (mounting behavior)](#6-chain-type-opt-in-mounting-behavior)
+7. [EVM = single connection across every configured EVM network](#7-evm--single-connection-across-every-configured-evm-network)
+8. [New: WalletConnect support for EVM](#8-new-walletconnect-support-for-evm)
+9. [New: headless wallet modal primitives](#9-new-headless-wallet-modal-primitives)
+10. [Removed: `useXBalances`](#10-removed-usexbalances)
+11. [`useEvmSwitchChain` reshaped](#11-useevmswitchchain-reshaped)
+12. [`SodaxWalletProvider` freezes config on first render](#12-sodaxwalletprovider-freezes-config-on-first-render)
+
+What did NOT change → [bottom of file](#what-did-not-change).
+
+---
+
+## 1. `SodaxWalletProvider` props (largest change)
+
+### What changed
+
+v1 spread chain configuration across **three separate props**: `rpcConfig` (per-chain RPC URLs), `options` (per-adapter options like `wagmi.ssr`, `solana.autoConnect`, `sui.autoConnect`), and `initialState` (wagmi state for SSR hydration).
+
+v2 collapses all three into a **single `config` prop** of type `SodaxWalletConfig`. The new shape uses **chain-type slots** (`EVM`, `SOLANA`, `SUI`, `BITCOIN`, `STELLAR`, `ICON`, `INJECTIVE`, `NEAR`, `STACKS`) at the top level. Each slot is `ChainTypeConfig<T>` — adapter options merged with `{ chains?, connectors? }` where `chains` is keyed by `ChainKey` and holds per-chain `{ rpcUrl?, defaults? }`.
+
+### Why
+
+- **Configurable chain opt-in.** v1 always mounted every chain adapter regardless of need. v2 mounts only the slots you include — omit a slot to skip it entirely. Pass `{}` to mount with SDK defaults.
+- **Single source of truth.** v1 spread chain knowledge across three independent props that had to stay in sync; the new `config` shape derives `enabledChains`, `chains`, and per-chain defaults from one tree.
+- **Per-chain `defaults`.** v2 lets each chain entry hold call-level defaults (e.g. EVM `waitForTransactionReceipt.confirmations`) that flow to the bridged `IXxxWalletProvider`.
+
+### How to migrate
+
+See [`reference/config.md`](./reference/config.md) for the mechanical mapping. See [`recipes/`](./recipes/) for paired before/after code in common patterns.
+
+---
+
+## 2. `QueryClientProvider` is no longer mounted internally
+
+### What changed
+
+v1 created its own `QueryClient` inside `SodaxWalletProvider` and wrapped children with `<QueryClientProvider>` automatically. v2 expects the consumer to provide one, externally.
+
+### Why
+
+- **One QueryClient per app, not per package.** v1's behavior caused subtle bugs when an app already had its own `QueryClient` for app-level queries — there were two clients, two caches, and React Query devtools showed only one.
+- **Predictable provider order.** Consumers can now mount `QueryClientProvider` at the position that fits their app — between auth providers and `SodaxWalletProvider`, around route boundaries, etc.
+
+### How to migrate
+
+Wrap `<SodaxWalletProvider>` with `<QueryClientProvider>` at the call site:
+
+```tsx
+// v2 ✅
+<QueryClientProvider client={queryClient}>
+  <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+</QueryClientProvider>
+```
+
+Add `@tanstack/react-query` as a direct dependency if not already present:
+
+```bash
+pnpm add @tanstack/react-query
+```
+
+---
+
+## 3. Hooks now take an options object, not positional args
+
+### What changed
+
+Every public hook that took a `xChainType` or `chainIdentifier` positional argument now takes an options object with named fields. The same applies to the **callback returned by `useXDisconnect`** — `await disconnect('EVM')` is now `await disconnect({ xChainType: 'EVM' })`.
+
+### Why
+
+- **Forward compatibility.** Adding new fields (e.g. `xChainId` alongside `xChainType`) without breaking call sites.
+- **Disambiguation.** v1 `useXAccount(chainIdentifier)` accepted both `ChainType` (`'EVM'`) and `ChainId` (`'0x1.eth'`) and detected at runtime. v2 splits them — `xChainType: ChainType` vs `xChainId: SpokeChainKey` — and the type system enforces "exactly one".
+
+### How to migrate
+
+See [`reference/hooks.md`](./reference/hooks.md) for the per-hook signature map. The `useXDisconnect` returned-callback case typically surfaces as `TS2345: Argument of type 'string' is not assignable to parameter of type 'UseXDisconnectArgs'`.
+
+---
+
+## 4. Store hook removed from the public API
+
+### What changed
+
+v1 exported the Zustand store hook as `useXWagmiStore` from the package barrel. v2 **does not export the store hook at all** — direct store access is no longer part of the public API. The localStorage **persistence key is unchanged** (`xwagmi-store`) so existing user connections survive the upgrade.
+
+### Why
+
+- **Public surface should be the hook layer.** Reading store state directly couples consumers to internal field shapes that change between minor versions. v2 provides one public hook per consumer concern (`useXService`, `useXConnection`, `useXConnectors`, …) so internal store renames don't break consumers.
+- **localStorage compatibility.** Renaming the persistence key would log every user out on upgrade. The internal store rename (which v2 also did) keeps the localStorage key intact.
+
+### How to migrate
+
+For each `useXWagmiStore(state => state.X)` selector, replace with the equivalent public hook. There is no `useXWalletStore` import to rename to. See [`reference/imports.md`](./reference/imports.md) § "Store hook removed" for the field-to-hook map.
+
+---
+
+## 5. Concrete chain classes moved behind sub-path imports
+
+### What changed
+
+v1 re-exported every concrete `XService` and `XConnector` class from the package barrel:
+
+```diff
+- // v1 — barrel exports concrete classes
+- import { EvmXService, XverseXConnector, IconHanaXConnector } from '@sodax/wallet-sdk-react';
+```
+
+v2's barrel exports only **types, hooks, abstractions, and `SodaxWalletProvider`**. Concrete chain classes live behind sub-paths:
+
+```ts
+// v2 — concrete classes via sub-path
+import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+```
+
+### Why
+
+- **API surface hygiene.** Consumers who only use hooks shouldn't pull concrete chain classes into their bundle just because they were re-exported. v2's barrel is shaped around the consumer-facing API; advanced use (e.g. `instanceof`) opts in via deep imports.
+- **Adding chains is non-breaking.** v1 required updating `index.ts` whenever a new chain landed. v2 auto-discovers per-chain entries via tsup glob — adding a chain doesn't touch the barrel.
+
+### How to migrate
+
+See [`reference/imports.md`](./reference/imports.md) for the sub-path map per chain.
+
+---
+
+## 6. Chain-type opt-in (mounting behavior)
+
+### What changed
+
+v1 mounted **every** chain adapter (wagmi, `@solana/wallet-adapter`, `@mysten/dapp-kit`) and registered services for every chain regardless of whether the consumer used them.
+
+v2 mounts only the slots present in `walletConfig`. An app that only needs EVM + Sui passes `{ EVM: {...}, SUI: {...} }` and ships **none** of the Solana / Bitcoin / NEAR adapter code in the React tree.
+
+### Why
+
+- **Bundle size.** v1 forced every consumer to ship every adapter. v2 lets you opt in.
+- **Provider context isolation.** Apps that don't need Solana don't get the `WalletProvider` from `@solana/wallet-adapter` in their context — fewer renders, fewer dev-tool nodes.
+
+### How to migrate
+
+Add only the chain-type slots your app actually uses to `walletConfig`. See [`reference/config.md`](./reference/config.md). New behavior: `useXConnectors({ xChainType: 'X' })` returns `[]` for chains not in `enabledChains` and logs a one-time warning.
+
+---
+
+## 7. EVM = single connection across every configured EVM network
+
+### What changed
+
+v1 had one connector per chain in some flows (legacy from earlier wagmi versions). v2 treats EVM as **one logical connection** that spans every configured EVM chain — there is no per-network connect/disconnect, and `useChainGroups` collapses EVM into a single row.
+
+### Why
+
+- **Match wagmi's actual semantics.** wagmi has always modeled EVM connection as one connector per session that hops between configured chains via `wagmi.switchChain`. v1's per-chain UI was a workaround.
+- **Multi-chain dApps.** Users connect once and operate across every EVM network the app supports — no re-authorization on each chain switch.
+
+### How to migrate
+
+Audit any UI that exposed per-EVM-chain connect/disconnect. Replace with a single "EVM" entry. Use `useEvmSwitchChain` for switching. See [`recipes/connect-button.md`](./recipes/connect-button.md) and [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md).
+
+---
+
+## 8. New: WalletConnect support for EVM
+
+### What changed
+
+v2 adds `EVM.walletConnect.projectId` to `walletConfig` to enable the WalletConnect connector. v1 did not support WalletConnect — only EIP-6963 injected wallets.
+
+### Why
+
+- **Enterprise custody.** Partners using Fireblocks / Ledger Live / mobile-only wallets cannot install browser extensions. WalletConnect is the only viable protocol.
+- **Backwards compatible default.** Omitting `walletConnect` from the config preserves v1 behavior (EIP-6963 only).
+
+### How to migrate
+
+Not breaking — additive. See [`recipes/walletconnect-migration.md`](./recipes/walletconnect-migration.md) for opt-in.
+
+---
+
+## 9. New: headless wallet modal primitives
+
+### What changed
+
+v2 ships `useWalletModal`, `useChainGroups`, `useConnectedChains`, `useBatchConnect`, `useBatchDisconnect`, `useIsWalletInstalled`, `useConnectionFlow`. None of these existed in v1.
+
+### Why
+
+- **Bring-your-own UI.** v1 left the modal UX to the consumer. v2 ships state-machine primitives — render-agnostic — so apps can build modal UX without rebuilding the chain registry / connector dispatch logic from scratch.
+
+### How to migrate
+
+Not breaking — additive. See [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md) for the modern pattern.
+
+---
+
+## 10. Removed: `useXBalances`
+
+### What changed
+
+v1 exported `useXBalances({ xChainId, xTokens, address })` from `@sodax/wallet-sdk-react`. v2 removes it. A hook with the same name lives in `@sodax/dapp-kit`, but the **signature has changed**:
+
+```diff
+- // v1 ❌ — from wallet-sdk-react
+- import { useXBalances } from '@sodax/wallet-sdk-react';
+- const { data } = useXBalances({ xChainId, xTokens, address });
++ // v2 ✅ — from dapp-kit, params are now wrapped
++ import { useXBalances } from '@sodax/dapp-kit';
++ import { useXService } from '@sodax/wallet-sdk-react';
++ const xService = useXService({ xChainType: 'EVM' });
++ const { data } = useXBalances({ params: { xService, xChainId, xTokens, address } });
+```
+
+### Why
+
+- **Wrong package.** Token-balance queries are a dApp-feature concern, not a wallet-sdk concern. The hook required token metadata, RPC routing, and refetch policies — none of which belong in a wallet SDK.
+- **`xService` is now an explicit input.** v2 surfaces the chain service to the call site so query keys are stable across config changes and the hook is testable in isolation.
+
+### How to migrate
+
+1. `pnpm add @sodax/dapp-kit` if not already installed.
+2. Switch the import path: `'@sodax/wallet-sdk-react'` → `'@sodax/dapp-kit'`.
+3. Wrap the existing arg as `{ params: { xService, xChainId, xTokens, address } }` and pass `xService` from `useXService({ xChainType })`.
+
+If you cannot add dapp-kit, port the call to direct `viem` / `@solana/web3.js` reads with your own `useQuery`.
+
+---
+
+## 11. `useEvmSwitchChain` reshaped
+
+### What changed
+
+v1 forwarded wagmi's `switchChain` mutation directly:
+
+```ts
+// v1 ❌
+const { switchChain } = useEvmSwitchChain();
+await switchChain({ chainId: 1 });
+```
+
+v2 takes a target `xChainId` and exposes wrong-network state:
+
+```ts
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
+  xChainId: ChainKeys.ETHEREUM_MAINNET,
+});
+```
+
+### Why
+
+- **Single source of truth for "expected chain".** UI code repeatedly recomputed `connectedChainId !== expectedChainId`. The hook owns that comparison once.
+- **Injective + MetaMask.** v2 transparently handles the Injective-via-MetaMask case (auto-switches to Ethereum mainnet). v1 callers had to bolt this on.
+- **Safe when EVM is disabled.** If the consumer's `walletConfig` omits the `EVM` slot, v2 returns no-op values instead of throwing.
+
+### How to migrate
+
+Replace the destructured `switchChain` with `handleSwitchChain` and feed the target chain via `xChainId`. Render the network-mismatch CTA from `isWrongChain`. See [`reference/hooks.md`](./reference/hooks.md) for examples.
+
+---
+
+## 12. `SodaxWalletProvider` freezes config on first render
+
+### What changed
+
+v1 re-derived chain config on every render whose `rpcConfig` / `options` reference changed. v2 **captures `config` once on mount** and ignores subsequent prop changes. To swap config at runtime, remount with a new `key`.
+
+### Why
+
+- **Stable wagmi config object.** wagmi's `WagmiProvider` is sensitive to config-object identity changes — re-creating the config triggers re-connection and breaks in-flight transactions.
+- **Predictable identity.** Apps should compose chain config once at startup, not derive it dynamically. Hot config swaps were rare in v1 but caused hard-to-debug reconnect storms.
+
+### How to migrate
+
+If you previously updated `rpcConfig` reactively, route the change through a remount:
+
+```tsx
+<SodaxWalletProvider key={configVersion} config={walletConfig}>
+  {children}
+</SodaxWalletProvider>
+```
+
+Bumping `configVersion` (e.g. when the user picks a new RPC endpoint) forces a clean re-init of all chain services.
+
+---
+
+## What did NOT change
+
+- Chain support: still 9 chain types (EVM, BITCOIN, INJECTIVE, STELLAR, SUI, SOLANA, ICON, NEAR, STACKS).
+- Persisted localStorage key: still `xwagmi-store`.
+- Devtools store name: still `xwagmi-store`.
+- Peer dependencies: `react >= 19`, `@tanstack/react-query 5.x`.
+- `XService` / `XConnector` abstract base contract (still has `connect()` / `disconnect()` / `getXConnectors()`).
+- Public `XAccount`, `XConnection`, `WalletId` types in `@sodax/types`.

package/ai-exported/migration/checklist.md

@@ -0,0 +1,159 @@
+# Migration Checklist (Machine-Checkable)
+
+Run these checks after every code change and at the end of the migration. Each item has a concrete `grep` / typecheck command. Loop through until all are checked.
+
+---
+
+## Provider migration
+
+- [ ] `SodaxWalletProvider` is mounted exactly once in app source.
+  ```bash
+  grep -rn "SodaxWalletProvider" <user-src> --include="*.tsx" --include="*.ts" | grep -v "import" | wc -l
+  # expect 1 (the JSX usage)
+  ```
+
+- [ ] `SodaxWalletProvider` uses the v2 `config` prop (no `rpcConfig` / `options` / `initialState`).
+  ```bash
+  grep -rnE "SodaxWalletProvider[^/>]*\b(rpcConfig|initialState|options)\s*=" <user-src>
+  # expect empty
+  ```
+
+- [ ] `QueryClientProvider` wraps `SodaxWalletProvider`.
+  ```bash
+  # Manual — open the provider file and confirm:
+  # <QueryClientProvider client={queryClient}>
+  #   <SodaxWalletProvider config={walletConfig}>
+  ```
+
+- [ ] If app is Next.js, `EVM.ssr: true` is set in `walletConfig`.
+  ```bash
+  grep -rnE "EVM:\s*\{[^}]*\bssr:\s*true" <user-src>
+  # expect at least one match if Next.js
+  ```
+
+---
+
+## Store migration
+
+- [ ] No `useXWagmiStore` imports remain (the v2 barrel removed the store hook entirely — every call site must be replaced with a public hook).
+  ```bash
+  grep -rn "useXWagmiStore" <user-src>
+  # expect empty
+  ```
+
+- [ ] No `useXWalletStore` imports were introduced (v2 does not export the store hook under either name).
+  ```bash
+  grep -rn "useXWalletStore" <user-src>
+  # expect empty
+  ```
+
+- [ ] Every former store read uses a public hook (`useXService` / `useXServices` / `useXConnection` / `useXConnections` / `useEnabledChains` / `useWalletProvider`). See [`reference/imports.md`](./reference/imports.md) § "Store hook removed" for the field-to-hook map.
+
+---
+
+## Hook signature migration
+
+- [ ] No positional hook calls remain.
+  ```bash
+  # All of these must be empty:
+  grep -rnE "useXAccount\(['\"]" <user-src>
+  grep -rnE "useXConnectors\(['\"]" <user-src>
+  grep -rnE "useXConnection\(['\"]" <user-src>
+  grep -rnE "useXService\(['\"]" <user-src>
+  grep -rnE "useWalletProvider\(['\"]" <user-src>
+  ```
+
+- [ ] All call sites pass `{ xChainType }` or `{ xChainId }`, never both.
+  ```bash
+  grep -rnE "useXAccount\(\{[^}]*xChainType[^}]*xChainId" <user-src>
+  grep -rnE "useXAccount\(\{[^}]*xChainId[^}]*xChainType" <user-src>
+  # expect empty
+  ```
+
+- [ ] No `useXDisconnect` callback called with positional ChainType (v2 takes `{ xChainType }` object).
+  ```bash
+  # The hook itself is identical in v1/v2; the BREAKING change is on the returned callback.
+  # Look for callbacks invoked with a bare string instead of an options object.
+  grep -rnE "disconnect\((['\"](EVM|SOLANA|SUI|BITCOIN|STELLAR|ICON|INJECTIVE|NEAR|STACKS)['\"])\)" <user-src>
+  # expect empty — replace with `disconnect({ xChainType: 'EVM' })`
+  ```
+
+- [ ] No `useEvmSwitchChain` destructuring of `switchChain` (v2 returns `{ isWrongChain, handleSwitchChain }`).
+  ```bash
+  grep -rnE "useEvmSwitchChain\(\)" <user-src>
+  # expect empty — v2 requires `{ xChainId }`
+  grep -rnE "const \{[^}]*\bswitchChain\b[^}]*\} = useEvmSwitchChain" <user-src>
+  # expect empty — switchChain is no longer destructurable from this hook
+  ```
+
+---
+
+## Sub-path imports
+
+- [ ] No concrete chain classes are imported from the package barrel.
+  ```bash
+  grep -rnE "from '@sodax/wallet-sdk-react'" <user-src> | grep -E "EvmXService|SolanaXService|SuiXService|BitcoinXService|StellarXService|InjectiveXService|IconXService|NearXService|StacksXService|EvmXConnector|SolanaXConnector|SuiXConnector|UnisatXConnector|XverseXConnector|OKXXConnector|StellarWalletsKitXConnector|InjectiveXConnector|IconHanaXConnector|NearXConnector|StacksXConnector"
+  # expect empty (or only `import type` lines, which are still allowed for some types)
+  ```
+
+- [ ] Concrete classes use sub-path imports (`@sodax/wallet-sdk-react/xchains/<chain>`).
+  ```bash
+  grep -rnE "from '@sodax/wallet-sdk-react/xchains/" <user-src>
+  # if user code needs concrete classes, expect matches here
+  ```
+
+---
+
+## Removed APIs
+
+- [ ] No `useXBalances` calls remain that import from `@sodax/wallet-sdk-react` (moved to `@sodax/dapp-kit` with a new signature).
+  ```bash
+  grep -rn "from '@sodax/wallet-sdk-react'" <user-src> | grep useXBalances
+  # expect empty — v2 imports from '@sodax/dapp-kit', wraps args as `{ params: { xService, xChainId, xTokens, address } }`
+  ```
+
+- [ ] No `useEthereumChainId` imports remain (internal in v2).
+  ```bash
+  grep -rn "useEthereumChainId" <user-src>
+  # expect empty — replace with wagmi's `useAccount().chainId` or `useEvmSwitchChain({ xChainId })`
+  ```
+
+---
+
+## Behavior verification
+
+- [ ] `pnpm checkTs` exits clean (in the user's app root).
+  ```bash
+  pnpm checkTs
+  # expect exit code 0
+  ```
+
+- [ ] Connect/disconnect flow works in dev environment (manual).
+  ```
+  # Manual:
+  # 1. pnpm dev
+  # 2. Click connect on each enabled chain
+  # 3. Confirm address renders, localStorage has `xwagmi-store` key with the new connection
+  # 4. Reload — confirm connection survives
+  # 5. Click disconnect — confirm `xwagmi-store` clears that chain
+  ```
+
+- [ ] EVM treated as single connection (manual; only if app had per-EVM-chain UI in v1).
+  ```
+  # Manual:
+  # 1. Connect to EVM with any wallet
+  # 2. Confirm useChainGroups returns one EVM row, not per-network rows
+  # 3. Confirm useEvmSwitchChain switches the active network without re-connecting
+  ```
+
+---
+
+## Done criteria
+
+The migration is complete when:
+
+- [ ] All sections above are checked.
+- [ ] User has confirmed the app's connect / disconnect / sign flows work end-to-end.
+- [ ] Tests are updated (if any test mocks `XService` / `useXWagmiStore`) — flagged in stop conditions; defer to user.
+
+If any item fails or is ambiguous, **stop and ask the user**. Do not declare complete until every box is ticked.