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

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

@@ -1,74 +0,0 @@
-# Reference: Connectors
-
-A connector is the adapter between a specific wallet (Hana, MetaMask, Phantom, Xverse…) and the SODAX store. Every connector implements `IXConnector`, the public contract every hook in `wallet-sdk-react` consumes.
-
-Concrete connector classes live behind sub-path imports — see [`api-surface.md`](./api-surface.md) § "Sub-path exports" for the per-chain map.
-
----
-
-## `IXConnector` interface
-
-```typescript
-export interface IXConnector {
-  readonly xChainType: ChainType;
-  readonly name: string;            // 'Hana', 'MetaMask', 'Xverse', …
-  readonly id: string;              // unique connector id (e.g. 'io.metamask')
-  readonly icon: string | undefined;
-  readonly isInstalled: boolean;    // wallet extension presence (read at getter call time)
-  readonly installUrl: string | undefined;
-  connect(): Promise<XAccount | undefined>;
-  disconnect(): Promise<void>;
-}
-```
-
-Consumer code should depend on **`IXConnector`** (the interface), not the concrete `XConnector` class — keeps your code chain-implementation-agnostic and allows custom connectors to slot in without inheriting from the abstract base.
-
-`isInstalled` reads `window.*` at getter-call time — no extra subscription is installed. Components get fresh values through normal React render triggers.
-
----
-
-## Listing connectors at runtime
-
-Don't import concrete classes to discover what's available — use the hook:
-
-```ts
-const connectors = useXConnectors({ xChainType: 'EVM' });
-// IXConnector[] — already filtered to enabled chain
-```
-
-For the per-chain class names (only needed for `instanceof` or custom-connector-list use cases), see [`api-surface.md`](./api-surface.md) § "Sub-path exports" and the worked example in [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md). Bitcoin's `BitcoinXConnector` is the only abstract base — its concrete subclasses (Unisat, Xverse, OKX) override per-wallet signing methods (see [`sign-message.md`](../recipes/sign-message.md)).
-
----
-
-## `sortConnectors` — display ordering
-
-Pure utility for ranking connectors in lists. Stable sort by:
-
-1. Position in `preferred[]` (earlier wins)
-2. `isInstalled === true`
-3. Original index
-
-```typescript
-import { useXConnectors, sortConnectors } from '@sodax/wallet-sdk-react';
-
-const PREFERRED = ['hana', 'metamask'];
-
-function ConnectorList() {
-  const raw = useXConnectors({ xChainType: 'EVM' });
-  const sorted = sortConnectors(raw, { preferred: PREFERRED });
-  // Hana first if present, then MetaMask, then any other installed wallets, then uninstalled.
-}
-```
-
-`preferred` matches by exact `connector.id`. For substring/case-insensitive matching across chains, use `useIsWalletInstalled` instead — see [`batch-operations.md`](../recipes/batch-operations.md).
-
----
-
-## Custom connectors
-
-Two ways to plug in a wallet the SDK doesn't ship:
-
-1. **Extend `XConnector`** (abstract base, exported from the barrel) — implement `connect()` / `disconnect()` / `isInstalled` / `installUrl`. Pass via `SodaxWalletConfig.<CHAIN>.connectors` to replace the registry defaults for that chain.
-2. **Implement `IXConnector` directly** — skip the abstract base. The SDK never does `instanceof XConnector` on user-supplied connectors; it only relies on the interface.
-
-For a worked example with code, see [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md) § "Custom connector list". For chains with extra signing methods (Bitcoin's `signBip322Message`, Injective specifics), implement the chain-specific extras — the SDK detects them via type guards at dispatch time.

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

@@ -1,204 +0,0 @@
-# Reference: Hooks
-
-Full hook surface of `@sodax/wallet-sdk-react` v2. All hooks accept an options object — never positional args. Pair this with [`connectors.md`](./connectors.md) for connector shape and [`chain-support.md`](./chain-support.md) for chain identifiers.
-
-> **All hooks are client-only.** They depend on `<SodaxWalletProvider>` and `<QueryClientProvider>`, which only mount on the client. Next.js App Router consumers must mark every file calling these hooks with `'use client'`. Server Components cannot read connection state directly — pass it down from a client boundary.
-
----
-
-## Behavior when the chain slot is not in `walletConfig`
-
-Hooks do **not** throw when their chain isn't enabled — each picks its own no-op fallback. UI code can call them unconditionally and branch on the return value.
-
-| Hook | Behavior when chain absent |
-|---|---|
-| `useXAccount`, `useXAccounts` | Returns shape with `address: undefined` |
-| `useXConnection`, `useXConnections` | Returns `undefined` / empty record |
-| `useXConnectors` | Returns `[]`. **One-time `console.warn`** per chain type to surface config mistakes. |
-| `useXConnectorsByChain` | Returns empty record. No warning. |
-| `useWalletProvider` | Returns `undefined` |
-| `useXService`, `useXServices` | Returns `undefined` / empty record |
-| `useEvmSwitchChain` | Returns `{ isWrongChain: false, handleSwitchChain: () => {} }` (no-op) |
-| `useEnabledChains` | Returns the list of slots actually present (does not include the disabled one) |
-| `useChainGroups`, `useConnectedChains` | Excludes the chain from output |
-| `useXConnect`, `useXDisconnect`, `useXSignMessage` | Mutation rejects when invoked with an unsupported `xChainType` |
-
-Rule of thumb: read-hooks degrade silently to "empty"; mutation-hooks reject. Both cases are safe to call unconditionally.
-
----
-
-## Connect / disconnect
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useXConnect` | `useXConnect(): UseMutationResult<XAccount \| undefined, Error, IXConnector>` | React Query mutation. **Resolves to `undefined` for provider-managed chains** (EVM/Solana/Sui) — read the connected account via `useXAccount` after the mutation lands. |
-| `useXDisconnect` | `useXDisconnect(): (args: UseXDisconnectArgs) => Promise<void>` where `UseXDisconnectArgs = { xChainType: ChainType }` | Async function — never throws |
-| `useConnectionFlow` | `useConnectionFlow(): { status, error, connect, retry, activeConnector }` | Status object |
-| `useBatchConnect` | `useBatchConnect({ connectors, skipConnected?, onProgress? })` | `{ run, status, result, reset }` |
-| `useBatchDisconnect` | `useBatchDisconnect({ connectors?, onProgress? })` | `{ run, status, result, reset }` |
-
-```ts
-const { mutateAsync: connect } = useXConnect();
-await connect(connector);
-
-const disconnect = useXDisconnect();
-await disconnect({ xChainType: 'EVM' });
-```
-
----
-
-## Read account / connection state
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useXAccount` | `useXAccount({ xChainType }) \| useXAccount({ xChainId })` | `XAccount` (always populated; `address` undefined when disconnected) |
-| `useXAccounts` | `useXAccounts()` | `Partial<Record<ChainType, XAccount>>` (only enabled chains; entries are populated, `address` undefined when disconnected) |
-| `useXConnection` | `useXConnection({ xChainType })` | `XConnection \| undefined` |
-| `useXConnections` | `useXConnections()` | `Partial<Record<ChainType, XConnection>>` |
-| `useConnectedChains` | `useConnectedChains({ order? })` | `{ status: 'loading' \| 'ready', chains: ConnectedChain[], total: number }` |
-
-```ts
-import { ChainKeys } from '@sodax/types';
-
-const { address } = useXAccount({ xChainType: 'EVM' });
-const { address } = useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
-```
-
----
-
-## Connector discovery
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useXConnectors` | `useXConnectors({ xChainType })` | `IXConnector[]` (returns `[]` and logs a one-time warning if `xChainType` isn't enabled in `walletConfig`) |
-| `useXConnectorsByChain` | `useXConnectorsByChain()` | `Partial<Record<ChainType, IXConnector[]>>` (no per-chain warnings) |
-| `useIsWalletInstalled` | `useIsWalletInstalled({ connectors?, chainType? })` | `boolean` (at least one of `connectors`/`chainType` required) |
-| `sortConnectors` | `sortConnectors(list, { preferred }): IXConnector[]` | Pure utility — installed first |
-
-```ts
-const connectors = useXConnectors({ xChainType: 'EVM' });
-const sorted = sortConnectors(connectors, { preferred: ['hana', 'metamask'] });
-
-const isInstalled = useIsWalletInstalled({ connectors: ['hana'] });
-```
-
----
-
-## Wallet provider bridge (for `@sodax/sdk` calls)
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useWalletProvider` | `useWalletProvider({ xChainId })` | Chain-narrowed `IXxxWalletProvider \| undefined` |
-| `useWalletProvider` | `useWalletProvider({ xChainType })` | Family-level `IXxxWalletProvider \| undefined` |
-| `useWalletProvider` | `useWalletProvider()` | `IWalletProvider \| undefined` |
-
-```ts
-import { ChainKeys } from '@sodax/types';
-
-const evm = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-// evm: IEvmWalletProvider | undefined
-```
-
-See [`bridge-to-sdk.md`](../recipes/bridge-to-sdk.md) for usage with SDK calls.
-
----
-
-## Modal / multi-chain UI
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useWalletModal` | `useWalletModal({ onConnected? })` | `{ state, open, close, back, selectChain, selectWallet, retry }` |
-| `useChainGroups` | `useChainGroups({ order? })` | `ChainGroup[]` (one per enabled chain family) |
-
-State machine kinds: `closed`, `chainSelect`, `walletSelect`, `connecting`, `success`, `error`.
-
-See [`multi-chain-modal.md`](../recipes/multi-chain-modal.md).
-
----
-
-## Sign message
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useXSignMessage` | `useXSignMessage()` | React Query mutation — `{ xChainType, message }` → `` `0x${string}` \| Uint8Array \| string \| undefined `` |
-
-```ts
-const sign = useXSignMessage();
-const sig = await sign.mutateAsync({ xChainType: 'EVM', message: 'hello' });
-```
-
-See [`sign-message.md`](../recipes/sign-message.md) for per-chain matrix.
-
----
-
-## EVM-specific
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useEvmSwitchChain` | `useEvmSwitchChain({ xChainId }: { xChainId: SpokeChainKey })` | `{ isWrongChain: boolean, handleSwitchChain: () => void }`. Compares the connected EVM chain to `xChainId` and exposes wrong-network state. Also handles Injective + MetaMask (auto-switches to Ethereum mainnet). Returns no-op values when `EVM` is not in `walletConfig`. |
-
-```ts
-import { ChainKeys } from '@sodax/types';
-
-const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
-  xChainId: ChainKeys.BSC_MAINNET,
-});
-
-if (isWrongChain) handleSwitchChain();
-```
-
-> **No top-level `useEthereumChainId` in v2.** The raw EVM chain ID is internal — read it via wagmi's `useAccount().chainId` instead. v2 folds the Injective+MetaMask "wrong network" UX into `useEvmSwitchChain` above.
-
----
-
-## Service-level (advanced)
-
-| Hook | Signature | Returns |
-|---|---|---|
-| `useXService` | `useXService({ xChainType })` | `IXService \| undefined` |
-| `useXServices` | `useXServices()` | `Partial<Record<ChainType, IXService>>` |
-| `useEnabledChains` | `useEnabledChains()` | `ChainType[]` |
-| `useInitChainServices` | (internal — handled by `SodaxWalletProvider`) | — |
-
----
-
-## Hook return-shape glossary
-
-```ts
-type XAccount = {
-  address: string | undefined;
-  xChainType: ChainType | undefined;
-  publicKey?: string;
-};
-
-type XConnection = {
-  xAccount: XAccount;
-  xConnectorId: string;
-};
-
-type IXConnector = {
-  readonly xChainType: ChainType;
-  readonly name: string;
-  readonly id: string;
-  readonly icon: string | undefined;
-  readonly isInstalled: boolean;
-  readonly installUrl: string | undefined;
-  connect(): Promise<XAccount | undefined>;
-  disconnect(): Promise<void>;
-};
-```
-
----
-
-## "Exactly one of" rule for chain identifiers
-
-Hooks that accept both `xChainId` and `xChainType` enforce **exactly one** — passing both, neither, or `undefined` for both throws at runtime (and is a type error):
-
-```ts
-useXAccount({ xChainType: 'EVM' });                           // ✅
-useXAccount({ xChainId: ChainKeys.BSC_MAINNET });             // ✅
-useXAccount({ xChainType: 'EVM', xChainId: ChainKeys.BSC_MAINNET }); // ❌ throws
-useXAccount({});                                              // ❌ throws
-```
-
-The chain-id form gives narrowest TypeScript inference (e.g. `xChainId: ChainKeys.BSC_MAINNET` → `IEvmWalletProvider`); the chain-type form is family-level.

package/ai-exported/integration/reference/wallet-brands.md

@@ -1,106 +0,0 @@
-# Reference: Wallet Brand Identifiers
-
-`useBatchConnect`, `useBatchDisconnect`, and `useIsWalletInstalled` accept a `connectors: readonly string[]` of **wallet brand identifiers** — short strings that match by **case-insensitive substring** against `connector.id` and `connector.name` (see [`../recipes/batch-operations.md`](../recipes/batch-operations.md)).
-
-The identifiers are **open**: any string works. The table below lists every brand the package ships connectors for so you can pick an identifier short enough to match across chain families. To target a specific connector (not a brand), bypass this API and use `useXConnectors({ xChainType }).find(c => c.id === '…')` directly — see [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md).
-
----
-
-## Known wallet brands
-
-| Identifier | Chains it matches | Underlying connector id / name |
-|---|---|---|
-| `'hana'` | EVM, ICON, Sui, Stellar | EVM via EIP-6963 RDNS (e.g. `io.havah.hana`); ICON id `hana`; Sui/Stellar — connector names containing "Hana" |
-| `'phantom'` | EVM, Solana | EVM RDNS `app.phantom`; Solana adapter name `Phantom` |
-| `'metamask'` | EVM, Injective | EVM RDNS `io.metamask`; Injective `Wallet.Metamask` strategy |
-| `'xverse'` | Bitcoin, Stacks | Bitcoin id `xverse`; Stacks id `XverseProviders.BitcoinProvider` |
-| `'unisat'` | Bitcoin | id `unisat` |
-| `'okx'` | Bitcoin | id `okx-bitcoin` |
-| `'leather'` | Stacks | id `LeatherProvider` |
-| `'asigna'` | Stacks | id `AsignaProvider` |
-| `'fordefi'` | Stacks | id `FordefiProviders.UtxoProvider` |
-| `'solflare'`, `'backpack'`, `'coinbase'`, `'trust'`, `'ledger'`, … | Solana | Adapter names from `@solana/wallet-adapter-wallets` |
-| `'freighter'`, `'albedo'`, `'lobstr'`, `'xbull'`, … | Stellar | Names from `@creit.tech/stellar-wallets-kit` |
-
-EVM (via EIP-6963), Solana, Sui, Stellar, and Injective surface connectors **dynamically** — the actual ids depend on what's installed in the user's browser. The table reflects names the upstream libraries ship by default.
-
----
-
-## Picking a short identifier
-
-Substring match is greedy. `'hana'` matches `Hana`, `io.havah.hana`, `hana-anything`. Trade-offs:
-
-- **Shorter = broader.** `'hana'` matches everywhere Hana appears across chain families. Good for batch ops targeting a brand across many chains.
-- **Longer = narrower.** `'io.metamask'` only matches the EIP-6963 RDNS — not Injective's MetaMask connector (which uses a different name string). Use when you specifically want one connector and nothing else.
-- **`< 3 chars`** triggers a dev-mode warning — substring matching on 1–2 char identifiers (e.g. `'ok'`) hits unintended connectors. The package will keep working but logs once per identifier.
-
----
-
-## Runtime discovery — list what's actually installed
-
-The table above is a guide, not authoritative. Browser extensions evolve and RDNS strings change. To inspect the real environment:
-
-```tsx
-'use client';
-
-import { useXConnectors } from '@sodax/wallet-sdk-react';
-import type { ChainType } from '@sodax/types';
-
-const CHAINS: ChainType[] = ['EVM', 'SOLANA', 'SUI', 'BITCOIN', 'STELLAR', 'ICON', 'INJECTIVE', 'NEAR', 'STACKS'];
-
-export function DevConnectorLister() {
-  return (
-    <table>
-      <thead>
-        <tr><th>Chain</th><th>id</th><th>name</th><th>installed</th></tr>
-      </thead>
-      <tbody>
-        {CHAINS.flatMap((chainType) => (
-          <ChainRow key={chainType} chainType={chainType} />
-        ))}
-      </tbody>
-    </table>
-  );
-}
-
-function ChainRow({ chainType }: { chainType: ChainType }) {
-  const connectors = useXConnectors({ xChainType: chainType });
-  return (
-    <>
-      {connectors.map((c) => (
-        <tr key={`${chainType}-${c.id}`}>
-          <td>{chainType}</td>
-          <td><code>{c.id}</code></td>
-          <td>{c.name}</td>
-          <td>{c.isInstalled ? '✓' : '—'}</td>
-        </tr>
-      ))}
-    </>
-  );
-}
-```
-
-Drop this component into your app during integration to print the live connector roster. Pick a short identifier from the `id` or `name` columns and feed it into `useBatchConnect({ connectors: [...] })`.
-
-For one-off inspection (no UI):
-
-```tsx
-useEffect(() => {
-  const all = CHAINS.flatMap((chainType) =>
-    useXConnectors({ xChainType: chainType }).map((c) => ({ chainType, id: c.id, name: c.name, isInstalled: c.isInstalled })),
-  );
-  console.table(all);
-}, []);
-```
-
----
-
-## When brand identifiers are the wrong tool
-
-Reach for `useXConnectors({ xChainType }).find(c => c.id === '…')` + `useXConnect` directly when:
-
-- **The brand list and chain list don't align.** e.g. "Connect Hana on EVM only, even though Hana also covers ICON" — the brand identifier API targets the wallet, not a chain/wallet pair.
-- **You need to disambiguate two wallets with overlapping names.** `'wallet'` would match every wallet-named connector.
-- **You're building a chain picker UI**, not a one-shot batch. Per-chain selection naturally uses `useXConnectors` per chain anyway.
-
-See [`../recipes/sub-path-imports.md`](../recipes/sub-path-imports.md) for the worked code path.

package/ai-exported/migration/README.md

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

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