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

package/docs/CHAIN_DETECTION.md

@@ -0,0 +1,216 @@
+# Chain Detection
+
+Aggregate views over the wallet store — what's enabled, what's connected, what's installed. Use these hooks to render chain pickers, "manage connections" panels, and install CTAs without manually walking `xConnections` / `xConnectorsByChain`.
+
+EVM **collapses to a single group / single row** in these views — wagmi maintains one connection across every configured EVM network, so reporting per-network rows would misrepresent the actual connection topology.
+
+## Table of contents
+
+1. [`useEnabledChains` — what's mounted](#useenabledchains--whats-mounted)
+2. [`useChainGroups` — picker model](#usechaingroups--picker-model)
+3. [`useConnectedChains` — connected list with hydration gate](#useconnectedchains--connected-list-with-hydration-gate)
+4. [`useIsWalletInstalled` — install detection](#useiswalletinstalled--install-detection)
+5. [Hydration status — gating reload flicker](#hydration-status--gating-reload-flicker)
+6. [Display ordering](#display-ordering)
+
+---
+
+## `useEnabledChains` — what's mounted
+
+Returns the list of chain types currently enabled in `SodaxWalletProvider` config:
+
+```typescript
+import { useEnabledChains } from '@sodax/wallet-sdk-react';
+
+const enabled = useEnabledChains();
+// e.g. ['EVM', 'SOLANA', 'BITCOIN']
+```
+
+Source: the `enabledChains` slice of the Zustand store, populated by `initChainServices` from your `SodaxWalletConfig`. Reflects the **slot keys** in config (`config.EVM`, `config.SOLANA`, …), not which chains have a wallet connected.
+
+Use cases:
+- Render only chain rows the dApp opted into.
+- Cross-reference with `useXConnections()` to compute "of N enabled chains, M are connected".
+- Drive `<Tabs>` / `<Select>` UIs without hard-coding a list.
+
+`useChainGroups` and `useConnectedChains` both already filter by `useEnabledChains` internally — reach for `useEnabledChains` directly only when you need the raw list.
+
+---
+
+## `useChainGroups` — picker model
+
+Returns one `ChainGroup` per enabled chain type, with display metadata + connection status. Designed for chain-picker UIs (the "select a chain" step in [`useWalletModal`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md)).
+
+```tsx
+import { useChainGroups } from '@sodax/wallet-sdk-react';
+
+function ChainPicker({ onPick }: { onPick: (chainType: ChainType) => void }) {
+  const groups = useChainGroups();
+
+  return groups.map(group => (
+    <button key={group.chainType} onClick={() => onPick(group.chainType)}>
+      {group.iconUrl && <img src={group.iconUrl} alt="" width={24} height={24} />}
+      <span>{group.displayName}</span>
+      {group.isConnected && <Badge>Connected</Badge>}
+    </button>
+  ));
+}
+```
+
+### `ChainGroup` shape
+
+| Field | Type | Source |
+|-------|------|--------|
+| `chainType` | `ChainType` | The slot key (`'EVM'`, `'SOLANA'`, …) |
+| `chainIds` | `readonly SpokeChainKey[]` | All chain keys sharing this `chainType` (e.g. all 12 EVM `ChainKeys.*` for `'EVM'`) |
+| `displayName` | `string` | From `chainRegistry[chainType].displayName`, fallback to `chainType` |
+| `iconUrl` | `string \| undefined` | From `chainRegistry`. `undefined` = SDK doesn't ship one — provide your own |
+| `isConnected` | `boolean` | `true` when `xConnections[chainType].xAccount.address` is set |
+| `account` | `XAccount \| undefined` | Connected account (or `undefined`) |
+| `connectorId` | `string \| undefined` | Active connector id when connected |
+
+### EVM collapses
+
+EVM's `chainIds` lists every configured EVM `ChainKey`, but the group itself is **one row**. wagmi maintains a single connection across all those networks — there's no "per-network connection state" to render. If a user needs to switch the active EVM network, that's [`useEvmSwitchChain`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/EVM_SWITCH_CHAIN.md), not a separate group.
+
+### Custom display order
+
+```typescript
+import { useChainGroups } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+const ORDER: readonly ChainType[] = ['EVM', 'ICON', 'SOLANA', 'SUI'];
+const groups = useChainGroups({ order: ORDER });
+// EVM first, then ICON, then SOLANA, then SUI; chains not in ORDER fall to the bottom alphabetically.
+```
+
+Without `order`, groups follow `enabledChains` insertion order (driven by `SodaxWalletProvider` config object key order — not stable across reloads in some bundlers). Pass `order` for deterministic UIs.
+
+---
+
+## `useConnectedChains` — connected list with hydration gate
+
+Returns one entry per **currently-connected** chain (skipping the rest), with enriched connector metadata (name + icon) for "manage connections" UIs and status badges.
+
+```tsx
+import { useConnectedChains } from '@sodax/wallet-sdk-react';
+
+function ConnectionList() {
+  const { chains, total, status } = useConnectedChains();
+
+  if (status === 'loading') return <Skeleton />;
+  if (total === 0) return <ConnectCta />;
+
+  return (
+    <ul>
+      {chains.map(chain => (
+        <li key={chain.chainType}>
+          {chain.connectorIcon && <img src={chain.connectorIcon} alt="" />}
+          <span>{chain.connectorName ?? chain.connectorId}</span>
+          <code>{chain.account.address}</code>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### `ConnectedChain` shape
+
+| Field | Type | Source |
+|-------|------|--------|
+| `chainType` | `ChainType` | |
+| `account` | `XAccount` | Always populated (only included when address is non-empty) |
+| `connectorId` | `string` | The persisted active connector |
+| `connectorName` | `string \| undefined` | Looked up in `xConnectorsByChain` — `undefined` if connector list hasn't been registered yet |
+| `connectorIcon` | `string \| undefined` | |
+
+### Result shape
+
+```typescript
+type UseConnectedChainsResult = {
+  chains: ConnectedChain[];
+  total: number;
+  status: 'loading' | 'ready';
+};
+```
+
+`total` is `chains.length` — there for ergonomics in conditional rendering.
+
+---
+
+## `useIsWalletInstalled` — install detection
+
+Read hook that pairs with the [batch operation](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/BATCH_OPERATIONS.md) hooks. Use it to gate "Connect" buttons on actual installation:
+
+```typescript
+import { useIsWalletInstalled } from '@sodax/wallet-sdk-react';
+
+// True if any Hana variant is installed (matches across all enabled chains)
+const hasHana = useIsWalletInstalled({ connectors: ['hana'] });
+
+// True if any wallet is installed for Bitcoin specifically
+const hasBitcoinWallet = useIsWalletInstalled({ chainType: 'BITCOIN' });
+
+// AND — Hana specifically on EVM
+const hanaOnEvm = useIsWalletInstalled({ connectors: ['hana'], chainType: 'EVM' });
+```
+
+Filters AND together. The type union enforces at compile time that **at least one of `connectors` / `chainType`** is present — `useIsWalletInstalled({})` is a type error. At runtime, bypassing the type union returns `false` plus a one-time warning (better than a render-tree crash).
+
+`connectors: []` is explicit "match nothing" — returns `false`.
+
+See [Identifier matching](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/BATCH_OPERATIONS.md#identifier-matching) for the substring-match rules.
+
+---
+
+## Hydration status — gating reload flicker
+
+`useConnectedChains` exposes `status: 'loading' | 'ready'`. Use it to avoid the "Connect wallet" → "Connected" flash on page reload while Zustand rehydrates from `localStorage`:
+
+```tsx
+const { chains, status } = useConnectedChains();
+
+// ❌ Flicker — `chains` is empty for one render before hydration completes
+return chains.length >= 1 ? <Connected /> : <ConnectCta />;
+
+// ✅ No flicker — wait for hydration before deciding
+return status === 'loading'
+  ? <Skeleton />
+  : chains.length >= 1 ? <Connected /> : <ConnectCta />;
+```
+
+The flag tracks `useXWalletStore.persist.hasHydrated()` via `useSyncExternalStore`. `useChainGroups` does not expose this flag — its outputs are stable across hydration because the connection-status fields (`isConnected`, `account`) start as `false` / `undefined` and gain values atomically when the persist middleware finishes.
+
+For first-paint correctness in SSR (Next.js), prefer `useConnectedChains.status` over an ad-hoc `useEffect(() => setMounted(true), [])` pattern — it's the official hydration signal.
+
+---
+
+## Display ordering
+
+Both `useChainGroups` and `useConnectedChains` accept an `order?: readonly ChainType[]` option. Behavior:
+
+1. Chains in the array render in array order.
+2. Chains **not** in the array fall to the bottom, **sorted alphabetically among themselves**.
+3. Without `order`:
+   - `useChainGroups` follows `enabledChains` insertion order (driven by config key order).
+   - `useConnectedChains` follows the canonical `ChainTypeArr` order from `@sodax/types` — stable across reloads.
+
+The compare function lives in [`utils/chainOrder.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/utils/chainOrder.ts).
+
+```typescript
+const groups = useChainGroups({ order: ['EVM', 'ICON'] });
+// EVM → ICON → (alphabetical: BITCOIN, INJECTIVE, NEAR, SOLANA, STACKS, STELLAR, SUI)
+```
+
+For custom-stable UIs (e.g. a header chain list that must not reflow on reload), always pass `order`.
+
+---
+
+## Related docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — which slots show up in `useEnabledChains`
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — populates `xConnections` consumed here
+- [Wallet Modal](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md) — drives chain picker from `useChainGroups`
+- [Batch Operations](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/BATCH_OPERATIONS.md) — `useIsWalletInstalled` shares the same identifier matcher
+- [EVM Switch Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/EVM_SWITCH_CHAIN.md) — the per-network EVM control absent from `useChainGroups`

package/docs/CONFIGURE_PROVIDER.md

@@ -0,0 +1,360 @@
+# Configure SodaxWalletProvider
+
+Learn how to configure `<SodaxWalletProvider>` for your dApp. The provider is the root component for wallet connectivity — it mounts only the chain-type adapters you opt into, holds per-chain RPC + wallet defaults, and bridges to `@sodax/wallet-sdk-core` so SDK calls receive a typed wallet provider.
+
+The canonical TypeScript shape is [`SodaxWalletConfig`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/types/config.ts) in `@sodax/wallet-sdk-react`.
+
+## Table of contents
+
+1. [Quick start — minimal config](#quick-start--minimal-config)
+2. [`SodaxWalletConfig` overview](#sodaxwalletconfig-overview)
+3. [Chain-type slots — opt in by presence](#chain-type-slots--opt-in-by-presence)
+4. [Per-chain entries (`chains[ChainKey]`)](#per-chain-entries-chainschainkey)
+5. [Per-chain wallet defaults](#per-chain-wallet-defaults)
+6. [WalletConnect (EVM only)](#walletconnect-evm-only)
+7. [Config is captured once on mount](#config-is-captured-once-on-mount)
+8. [Single source of truth — `ChainMeta`](#single-source-of-truth--chainmeta)
+9. [Breaking changes from v1](#breaking-changes-from-v1)
+
+---
+
+## Quick start — minimal config
+
+Mount `<SodaxWalletProvider>` inside `<QueryClientProvider>` with the chain-type slots your dApp needs. Omit any slot you don't need — its native adapter (wagmi, `@solana/wallet-adapter`, `@mysten/dapp-kit`) won't be mounted.
+
+```tsx
+import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { ChainKeys } from '@sodax/types';
+
+const queryClient = new QueryClient();
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+    },
+  },
+  SOLANA: {
+    chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://solana-mainnet.g.alchemy.com/v2/<KEY>' } },
+  },
+  BITCOIN: {}, // mount with SDK defaults
+};
+
+export function App({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+`SodaxWalletProvider` mounts the EVM (wagmi), Solana (`@solana/wallet-adapter-react`), and Sui (`@mysten/dapp-kit`) React providers conditionally based on which slots are present, then registers chain services for non-provider chains (Bitcoin, ICON, Injective, Stellar, NEAR, Stacks).
+
+---
+
+## `SodaxWalletConfig` overview
+
+Top-level keys are `ChainType` strings — one slot per chain family. **Every slot is optional**. Omitting a slot skips mounting that adapter; passing `{}` mounts it with SDK defaults.
+
+| Key | Mounts | Adapter fields | Per-chain entries |
+|-----|--------|----------------|-------------------|
+| `EVM` | wagmi (12 EVM chains) | `ssr`, `reconnectOnMount`, `initialState`, `walletConnect` | `{ rpcUrl?, defaults? }` per `EvmChainKey` |
+| `SOLANA` | `@solana/wallet-adapter-react` | `autoConnect` | `{ rpcUrl?, defaults? }` per `SolanaChainKey` |
+| `SUI` | `@mysten/dapp-kit` | `autoConnect`, `network` | `{ rpcUrl?, defaults? }` per `SuiChainKey` |
+| `ICON` | (no React adapter) | — | `{ rpcUrl?, defaults? }` per `IconChainKey` |
+| `NEAR` | (no React adapter) | — | `{ rpcUrl?, defaults? }` per `NearChainKey` |
+| `STELLAR` | (no React adapter) | — | `StellarRpcConfig & { defaults? }` per `StellarChainKey` |
+| `BITCOIN` | (no React adapter) | — | `BitcoinRpcConfig & { defaults? }` per `BitcoinChainKey` |
+| `INJECTIVE` | (no React adapter) | — | `InjectiveRpcConfig & { defaults? }` per `InjectiveChainKey` |
+| `STACKS` | (no React adapter) | — | `StacksNetworkName \| (StacksNetworkLike & { defaults? })` |
+
+**Provider-managed vs non-provider** — EVM, Solana, and Sui need React context providers from their native SDKs (Hydrator components sync state into the Zustand store). The remaining six chains use direct browser-extension APIs and skip the React adapter layer; their actions are registered during `initChainServices()` after the provider mounts.
+
+Each slot also accepts an optional `connectors?: IXConnector[]` array to override the default connectors registered by `chainRegistry`.
+
+---
+
+## Chain-type slots — opt in by presence
+
+The slot's mere presence enables the chain type. Adapter fields and per-chain entries are independent of each other — set whichever you need.
+
+```typescript
+const walletConfig: SodaxWalletConfig = {
+  // Adapter fields only — wagmi mounts with the bundled chain set, no custom RPCs
+  EVM: { ssr: true },
+
+  // Per-chain entries only — wagmi adapter uses defaults
+  SOLANA: { chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://...' } } },
+
+  // Both
+  SUI: {
+    network: 'mainnet',
+    autoConnect: true,
+    chains: { [ChainKeys.SUI_MAINNET]: { rpcUrl: 'https://fullnode.mainnet.sui.io' } },
+  },
+
+  // Empty object — opt in with SDK defaults
+  BITCOIN: {},
+};
+```
+
+To **disable** a chain type, omit the slot entirely. `useEnabledChains()` reads back the slots that were set, and hooks like `useWalletProvider({ xChainType: 'EVM' })` return `undefined` for disabled chains (with a one-time console warning).
+
+---
+
+## Per-chain entries (`chains[ChainKey]`)
+
+Each slot's `chains` field is keyed by `ChainKey` constants. The entry shape varies by chain family:
+
+### Simple chains — `{ rpcUrl?, defaults? }`
+
+EVM, Solana, Sui, ICON, and NEAR share the simple shape — single RPC URL plus optional wallet provider defaults.
+
+```typescript
+import { ChainKeys } from '@sodax/types';
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    chains: {
+      [ChainKeys.ARBITRUM_MAINNET]: {
+        rpcUrl: 'https://arb1.arbitrum.io/rpc',
+        defaults: { waitForTransactionReceipt: { confirmations: 1 } },
+      },
+      [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://base.drpc.org' },
+    },
+  },
+  ICON: {
+    chains: { [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' } },
+  },
+};
+```
+
+### Multi-field RPC — Stellar, Bitcoin, Injective
+
+Stellar (Horizon + Soroban), Bitcoin (RPC + Radfi indexer), and Injective (gRPC + indexer) extend their existing `*RpcConfig` types from `@sodax/types`. Mirror the full shape:
+
+```typescript
+import { ChainKeys } from '@sodax/types';
+
+const walletConfig: SodaxWalletConfig = {
+  STELLAR: {
+    chains: {
+      [ChainKeys.STELLAR_MAINNET]: {
+        horizonRpcUrl: 'https://horizon.stellar.org',
+        sorobanRpcUrl: 'https://rpc.ankr.com/stellar_soroban',
+        defaults: { pollInterval: 1_000 },
+      },
+    },
+  },
+  BITCOIN: {
+    chains: {
+      [ChainKeys.BITCOIN_MAINNET]: {
+        // BitcoinRpcConfig fields + defaults
+        defaults: { defaultFinalize: true },
+      },
+    },
+  },
+};
+```
+
+### Stacks — preset name OR network object
+
+Stacks accepts either a preset name string (`'mainnet' | 'testnet'`) or a full `StacksNetworkLike` object:
+
+```typescript
+const walletConfig: SodaxWalletConfig = {
+  STACKS: {
+    chains: {
+      [ChainKeys.STACKS_MAINNET]: 'mainnet', // preset
+    },
+  },
+};
+
+// Or with full network object:
+const advanced: SodaxWalletConfig = {
+  STACKS: {
+    chains: {
+      [ChainKeys.STACKS_MAINNET]: {
+        // StacksNetworkLike fields...
+        defaults: { network: 'mainnet', postConditionMode: 'deny' },
+      },
+    },
+  },
+};
+```
+
+---
+
+## Per-chain wallet defaults
+
+The `defaults` field on each chain entry forwards directly to `wallet-sdk-core`'s provider classes — these are the per-method defaults applied when the SDK calls `walletProvider.sendTransaction(...)` etc.
+
+| Slot | `defaults` shape |
+|------|------------------|
+| `EVM` | `EvmWalletDefaults` — `sendTransaction`, `waitForTransactionReceipt`, `publicClient`, `walletClient`, `transport` |
+| `SOLANA` | `SolanaWalletDefaults` — `connectionCommitment`, `connectionConfig`, `sendOptions`, `confirmCommitment` |
+| `SUI` | `SuiWalletDefaults` — `signAndExecuteTxn`, `getCoins` |
+| `ICON` | `IconWalletDefaults` — `stepLimit`, `version`, `timestampProvider`, `jsonRpcId` |
+| `INJECTIVE` | `InjectiveWalletDefaults` — `defaultFunds`, `defaultMemo`, `sequence`, `accountNumber` |
+| `STELLAR` | `StellarWalletDefaults` — `pollInterval`, `pollTimeout`, `networkPassphrase` |
+| `STACKS` | `StacksWalletDefaults` — `network`, `postConditionMode` |
+| `BITCOIN` | `BitcoinWalletDefaults` — `defaultFinalize` |
+| `NEAR` | `NearWalletDefaults` — `throwOnFailure`, `waitUntil`, `gasDefault`, `depositDefault` |
+
+Defaults merge **shallowly** — top-level keys only. Nested objects (e.g. `sendTransaction: { gas, maxFeePerGas }`) are replaced wholesale, not deep-merged. See [`packages/sdk/docs/WALLET_PROVIDERS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md) for full per-chain config reference.
+
+---
+
+## WalletConnect (EVM only)
+
+Default EVM discovery uses [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) — only browser-extension wallets. Partners using enterprise custody (Fireblocks, Ledger, etc.) cannot install browser extensions and need WalletConnect protocol.
+
+The `walletConnect` field on the `EVM` slot extends wagmi's `WalletConnectParameters` directly — every wagmi option is available:
+
+```typescript
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' } },
+    walletConnect: {
+      projectId: '<your-walletconnect-cloud-project-id>',
+      // showQrModal, isNewChainsStale, qrModalOptions, etc.
+    },
+  },
+};
+```
+
+When `walletConnect` is provided, a WalletConnect connector is added to the wagmi config and `EvmHydrator` discovers it automatically — no UI changes needed.
+
+**Restrict modal to specific wallets** — pass `qrModalOptions` to filter the WalletConnect Explorer list:
+
+```typescript
+walletConnect: {
+  projectId: '...',
+  qrModalOptions: {
+    explorerRecommendedWalletIds: ['<fireblocks-wallet-id>'],
+    explorerExcludedWalletIds: 'ALL', // hides everything except recommended
+  },
+}
+```
+
+If `projectId` is missing, the WalletConnect connector is silently skipped and a warning is logged. See [`WALLETCONNECT.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLETCONNECT.md) for the partner integration guide.
+
+---
+
+## Config is captured once on mount
+
+`SodaxWalletProvider` freezes the `config` prop on the **first render** via `useRef`. Subsequent re-renders with a new reference have **no effect** on the underlying providers, store, or wagmi config:
+
+```tsx
+// ❌ Dynamic config — RPC change is ignored after first render
+const walletConfig: SodaxWalletConfig = useMemo(() => ({
+  EVM: { chains: { [ChainKeys.BSC_MAINNET]: { rpcUrl: dynamicRpc } } },
+}), [dynamicRpc]);
+
+return <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>;
+```
+
+To swap config at runtime, **remount** the provider with a new `key`:
+
+```tsx
+return (
+  <SodaxWalletProvider key={configVersion} config={walletConfig}>
+    {children}
+  </SodaxWalletProvider>
+);
+```
+
+This avoids subtle bugs where Zustand persistence, wagmi reconnect, and Hydrator state-syncing diverge from a mid-flight config change.
+
+---
+
+## Single source of truth — `ChainMeta`
+
+When adding a new chain type to the package, the only file you edit is [`ChainMeta`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/types/config.ts):
+
+```typescript
+export type ChainMeta = {
+  EVM: { keys: EvmChainKey; entry: EvmChainEntry; defaults: EvmWalletDefaults; adapter: EvmAdapterFields };
+  // ... one entry per ChainType
+};
+```
+
+`SodaxWalletConfig`, `ChainTypeConfig<T>`, `ChainEntry<K>`, `WalletDefaultsByKey<K>` all derive automatically from `ChainMeta`. See [`ADDING_A_NEW_CHAIN.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md) for the full chain-onboarding workflow.
+
+---
+
+## Breaking changes from v1
+
+The v2 config is **not backward-compatible** with v1's flat shape. If you're upgrading:
+
+### `rpcConfig` removed
+
+```tsx
+// ❌ v1 — flat per-chain RPC map
+<SodaxWalletProvider rpcConfig={{
+  sonic: 'https://rpc.soniclabs.com',
+  '0x38.bsc': 'https://bsc-dataseed1.binance.org',
+  solana: 'https://...',
+}}>
+
+// ✅ v2 — chain-type slots with nested per-chain entries
+<SodaxWalletProvider config={{
+  EVM: {
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed1.binance.org' },
+    },
+  },
+  SOLANA: { chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://...' } } },
+}}>
+```
+
+### `options` removed — fields moved to slot adapter fields
+
+| v1 prop | v2 location |
+|---------|-------------|
+| `options.ssr` | `config.EVM.ssr` |
+| `options.reconnectOnMount` | `config.EVM.reconnectOnMount` |
+| `options.solanaAutoConnect` | `config.SOLANA.autoConnect` |
+| `options.suiAutoConnect` | `config.SUI.autoConnect` |
+| `options.suiNetwork` | `config.SUI.network` |
+| `options.walletConnect` | `config.EVM.walletConnect` |
+
+### `initialState` removed — moved to slot
+
+```tsx
+// ❌ v1
+<SodaxWalletProvider rpcConfig={...} initialState={wagmiInitialState}>
+
+// ✅ v2
+<SodaxWalletProvider config={{ EVM: { initialState: wagmiInitialState, ... } }}>
+```
+
+### `chains: { EVM, SOLANA, ... }` wrapper removed
+
+```tsx
+// ❌ v1
+<SodaxWalletProvider config={{ chains: { EVM: { ... }, SOLANA: { ... } } }}>
+
+// ✅ v2 — chain-type slots are top-level
+<SodaxWalletProvider config={{ EVM: { ... }, SOLANA: { ... } }}>
+```
+
+### Persisted `xConnections` for now-disabled chains are cleaned up
+
+If a previous session connected a chain that is no longer in `config`, the persisted connection in `localStorage` (key: `xwagmi-store`) is removed automatically by `cleanupDisabledConnections()` after persist hydration. No consumer action required.
+
+---
+
+## Related docs
+
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — discover connectors, connect, read account, disconnect
+- [Wallet Provider Bridge](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_PROVIDER_BRIDGE.md) — `useWalletProvider` → typed `IXxxWalletProvider` for SDK calls
+- [WalletConnect](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLETCONNECT.md) — enterprise/custody wallet setup (Fireblocks, etc.)
+- [Adding a New Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md) — `ChainMeta` extension and chain registry
+- [SDK Wallet Providers Reference](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md) — per-chain `defaults` shape reference