@sodax/skills 2.0.0-rc.10

package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/hooks.md

@@ -0,0 +1,336 @@
+# Reference: Hook Signature Map
+
+Per-hook signature changes for v1 → v2. See [`../breaking-changes.md`](../breaking-changes.md) §3 for the WHY.
+
+---
+
+## Quick rule
+
+| Pattern | v1 (positional) | v2 (options object) |
+|---|---|---|
+| Pass chain family | `useX('EVM')` | `useX({ xChainType: 'EVM' })` |
+| Pass chain id | `useX('0x1.eth')` | `useX({ xChainId: ChainKeys.ETHEREUM_MAINNET })` |
+| Cannot pass both | (runtime detected) | TypeScript-enforced (`xChainType: never` on the chain-id branch and vice versa) |
+
+`xChainId` in v2 is typed as `SpokeChainKey` (the enum from `@sodax/types`), not the raw string id. The narrower type lets v2 hooks return chain-typed providers (e.g. `IEvmWalletProvider | undefined`) instead of the v1 union.
+
+---
+
+## Canonical rule — `xChainId` is non-nullable
+
+Hooks that take `xChainId` declare it via overloads as required `SpokeChainKey`. Passing a nullable value (e.g. `token?.chainKey`) does not compile.
+
+The exported `UseWalletProviderOptions` (and similar) is the *implementation* type and looks permissive — but calls resolve against the overloads, which are stricter. Casting around the error is unsafe: it either fails to bypass the overload at all, or silently strips the nullable from the type while the runtime value stays `undefined` (some hooks tolerate that and return `undefined`; `useXAccount` throws).
+
+Handle the nullable **before** the hook call:
+
+```ts
+// @ai-snippets-skip
+// Narrow, default-fallback, or split into a child component — pick the one that fits.
+if (!chainKey) return null;
+const wp = useWalletProvider({ xChainId: chainKey });
+```
+
+---
+
+## `useXAccount`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌
+const { address } = useXAccount('EVM');
+const { address } = useXAccount('0x1.eth');
+
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+
+const { address } = useXAccount({ xChainType: 'EVM' });
+const { address } = useXAccount({ xChainId: ChainKeys.ETHEREUM_MAINNET });
+```
+
+**Decision rule (positional value → field name):** v1 accepted both `ChainType` and `ChainId` and detected at runtime. In v2 you must choose the right field:
+
+- v1 value is a family literal (`'EVM'`, `'SOLANA'`, …) → v2 `xChainType`.
+- v1 value is a chain-key string (`'0x1.eth'`, `XToken.xChainId`, …) → v2 `xChainId` typed as `SpokeChainKey`.
+- v1 value comes from `getXChainType(...)` (returns `ChainType | undefined`) → v2 `xChainType`, but **guard against `undefined`** — see below.
+
+**v2 asserts at runtime that exactly one of `xChainId` / `xChainType` is present.** Both undefined throws `'[useXAccount] pass xChainId or xChainType'`; both present throws `'[useXAccount] pass either xChainId or xChainType, not both'`. v1 was permissive (called with `undefined`, it returned an empty account). v2 is strict.
+
+**Common nullable patterns and their fixes:**
+
+```ts
+// @ai-snippets-skip
+// ❌ v1 idiom — returns empty account when nothing selected, runs every render
+const { address } = useXAccount(selectedChainId ?? undefined);
+
+// ✅ v2 fix 1 — index a snapshot from useXAccounts (no per-key hook call)
+const xAccounts = useXAccounts();
+const chainType = selectedChainId ? getXChainType(selectedChainId) : undefined;
+const address = chainType ? xAccounts[chainType]?.address : undefined;
+
+// ✅ v2 fix 2 — supply a sensible default chain key so the hook always has input
+const { address } = useXAccount({
+  xChainId: selectedChainId ?? ChainKeys.SONIC_MAINNET,
+});
+
+// ✅ v2 fix 3 — split into a child component that only mounts when input is known
+{selectedChainId ? <Account xChainId={selectedChainId} /> : null}
+function Account({ xChainId }: { xChainId: SpokeChainKey }) {
+  const { address } = useXAccount({ xChainId });
+  // ...
+}
+```
+
+The other "options-object" hooks (`useXConnection`, `useXConnectors`, `useXService`, `useWalletProvider`) are **lenient** — passing no field returns the empty/undefined value silently. `useXAccount` is the only one that asserts.
+
+**Other notes:**
+- Return shape unchanged: `XAccount = { address, xChainType, publicKey? }`.
+- When a valid chain is supplied but no wallet is connected, `address` is `undefined` while `xChainType` is filled — same as v1's connected-empty state.
+
+---
+
+## `useXConnectors`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌
+const connectors = useXConnectors('EVM');
+
+// v2 ✅
+const connectors = useXConnectors({ xChainType: 'EVM' });
+```
+
+**Other notes:**
+- Return type changed from `XConnector[]` to `IXConnector[]` (interface). For most consumers this is invisible — both expose `id`, `name`, `icon`, `xChainType`, `connect()`, `disconnect()`.
+- v2 enriches each connector with `isInstalled`, `installUrl`, `icon` (read at access time from `window.*`).
+- v2 returns `[]` and logs a one-time warning if the chain isn't in `enabledChains`. v1 returned `[]` silently.
+
+---
+
+## `useXConnection`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌
+const connection = useXConnection('EVM');
+
+// v2 ✅
+const connection = useXConnection({ xChainType: 'EVM' });
+```
+
+Return shape unchanged: `XConnection | undefined = { xAccount, xConnectorId } | undefined`.
+
+---
+
+## `useXService`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌
+const service = useXService('EVM');
+
+// v2 ✅
+const service = useXService({ xChainType: 'EVM' });
+```
+
+Return type unchanged.
+
+> **Need the typed concrete class** (e.g. `EvmXService.publicClient`, `StellarXService.server`, `BitcoinXService` for `instanceof` checks)? The concrete classes (`EvmXService`, `SolanaXService`, `StellarXService`, etc.) are **still exported in v2**, but moved from the package barrel to per-chain sub-paths: `@sodax/wallet-sdk-react/xchains/<chain>`. See [`imports.md` § Concrete chain classes](./imports.md#concrete-chain-classes--moved-behind-sub-path-imports) for the full per-chain table. The TS error `TS2724: '"@sodax/wallet-sdk-react"' has no exported member named 'StellarXService'. Did you mean 'useXService'?` is misleading when you actually need the class — the class is at the sub-path, not the hook.
+
+---
+
+## `useWalletProvider`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌ — positional spokeChainId, returns wide union
+const wp = useWalletProvider('sui');
+
+// v2 ✅ — options object, narrowest type when xChainId is passed
+import { ChainKeys } from '@sodax/types';
+
+const wp = useWalletProvider({ xChainId: ChainKeys.SUI_MAINNET });
+//    ^ inferred as ISuiWalletProvider | undefined
+
+const wp2 = useWalletProvider({ xChainType: 'EVM' });
+//    ^ inferred as IEvmWalletProvider | undefined
+
+const wp3 = useWalletProvider();
+//    ^ inferred as IWalletProvider | undefined (any)
+```
+
+**Other notes:**
+- Pass either `xChainId` (`SpokeChainKey`) or `xChainType` (`ChainType`), never both. Chain key gives narrower TypeScript inference.
+- Returns `undefined` when the chain isn't enabled in `walletConfig` (logs a one-time warning) or when no wallet is connected.
+
+---
+
+## `useXConnect`
+
+```ts
+// @ai-snippets-skip
+// v1 ✅ AND v2 ✅ — same signature
+const { mutateAsync: connect } = useXConnect();
+await connect(connector);
+```
+
+No change in shape. The `connector` argument type is `IXConnector` in v2 (was `XConnector` abstract class in v1) — runtime behavior identical for any connector returned by `useXConnectors`.
+
+---
+
+## `useXDisconnect`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌ — returned function takes positional ChainType
+const disconnect = useXDisconnect();
+await disconnect('EVM');
+
+// v2 ✅ — returned function takes options object
+const disconnect = useXDisconnect();
+await disconnect({ xChainType: 'EVM' });
+```
+
+The hook itself takes no args in both versions. The **returned function** changed: v1 was positional `(xChainType: ChainType) => Promise<void>`; v2 is `(args: UseXDisconnectArgs) => Promise<void>` where `UseXDisconnectArgs = { xChainType: ChainType }`. Same forward-compat reason as the other hooks — see [`../breaking-changes.md`](../breaking-changes.md) §3.
+
+**Common breakage:** `await disconnect(xChainType)` raises `TS2345: Argument of type 'string' is not assignable to parameter of type 'UseXDisconnectArgs'`. Wrap in an object.
+
+---
+
+## `useXSignMessage`
+
+```ts
+// @ai-snippets-skip
+// v1 ✅ AND v2 ✅ — same signature
+const { mutateAsync: signMessage } = useXSignMessage();
+const sig = await signMessage({ xChainType: 'EVM', message: 'hello' });
+```
+
+No change.
+
+---
+
+## `useXAccounts`
+
+```ts
+// @ai-snippets-skip
+// v1
+const accounts = useXAccounts();
+
+// v2 — return type is now strictly typed
+const accounts = useXAccounts();
+// → Partial<Record<ChainType, XAccount>>
+```
+
+Call signature unchanged. **Indexing tightened**: `accounts[chainType]` returns `XAccount | undefined`. The index variable must be typed as `ChainType` (not `string` or `any`) — otherwise you'll see `TS7053: Element implicitly has an 'any' type`.
+
+```ts
+// @ai-snippets-skip
+// ❌ FAILS — chainType is `string`, can't index Partial<Record<ChainType, ...>>
+const chainType = someStringFromConfig;
+const account = accounts[chainType];
+
+// ✅ FIX 1 — narrow with getXChainType (returns ChainType | undefined)
+import { getXChainType } from '@sodax/wallet-sdk-react';
+const chainType = getXChainType(chainId);
+const account = chainType ? accounts[chainType] : undefined;
+
+// ✅ FIX 2 — call useXAccount per-chain instead of indexing
+const account = useXAccount({ xChainType: 'EVM' });
+```
+
+---
+
+## `useEvmSwitchChain`
+
+```ts
+// @ai-snippets-skip
+// v1 ❌ — positional `expectedXChainId: ChainId`
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain(chainId);
+
+// v2 ✅ — options object; `xChainId: SpokeChainKey`
+import { ChainKeys } from '@sodax/types';
+
+const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
+  xChainId: ChainKeys.ETHEREUM_MAINNET,
+});
+
+if (isWrongChain) handleSwitchChain();
+```
+
+**Breaking changes:**
+
+- **Call shape**: positional → options object. Same forward-compat reason as the other hooks.
+- **Parameter type**: `ChainId` → `SpokeChainKey` (rename in `@sodax/types`). If the chain key value comes from `XToken.chainKey` (v2) or any `ChainKeys.*` constant, no value change is needed — the rename is type-only.
+
+**Return shape is unchanged** — both v1 and v2 return `{ isWrongChain: boolean, handleSwitchChain: () => void }`. The hook compares the connected EVM chain to the chain expected by `xChainId` and exposes `isWrongChain` so UI can render a "switch network" CTA without recomputing.
+
+**Behavior added in v2:**
+
+- **Injective + MetaMask auto-switch.** When the user connects to Injective via MetaMask, v2 automatically targets Ethereum mainnet underneath. v1 had no Injective awareness.
+- **Safe when EVM is disabled.** v2 returns no-op values (`isWrongChain: false`, `handleSwitchChain: () => {}`) if `walletConfig.EVM` is absent, so UI doesn't need to branch.
+
+---
+
+## `useEthereumChainId`
+
+**Removed from the public barrel in v2.** Despite the generic-sounding name, the v1 hook was **Injective + MetaMask specific** — it read the underlying Ethereum chain ID exposed by Injective's wallet strategy and was almost always used to drive the "switch back to Ethereum mainnet" UX. v2 makes the hook internal because `useEvmSwitchChain` now handles that Injective auto-switch case directly.
+
+Migration:
+
+```diff
+- // v1 ❌ — manual chain-ID comparison for Injective + MetaMask UX
+- import { useEthereumChainId } from '@sodax/wallet-sdk-react';
+- const chainId = useEthereumChainId();
+- if (chainId !== 1) /* prompt user to switch to Ethereum mainnet */;
++ // v2 ✅ — useEvmSwitchChain auto-handles Injective + MetaMask underneath
++ import { useEvmSwitchChain } from '@sodax/wallet-sdk-react';
++ import { ChainKeys } from '@sodax/types';
++ const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
++   xChainId: ChainKeys.INJECTIVE_MAINNET,
++ });
++ if (isWrongChain) handleSwitchChain();
+```
+
+If you genuinely need the raw EVM chain ID (rare — almost no usage outside the Injective case), wagmi's `useAccount().chainId` is the underlying source. Prefer staying inside `@sodax/wallet-sdk-react` hooks where possible.
+
+---
+
+## Removed in v2
+
+| Hook / symbol | Replacement |
+|---|---|
+| `useXBalances` | Moved to `@sodax/dapp-kit` **AND signature changed**. See note below. |
+| `useXWagmiStore` | Removed entirely — direct store reads are not part of the v2 API. Use public hooks (`useXServices`, `useXConnections`, `useXService({ xChainType })`, `useXConnection({ xChainType })`, etc.). See note below. |
+| Concrete X-service / X-connector classes (`EvmXService`, `SolanaXService`, `StellarXService`, `BitcoinXService`, `IconXService`, `InjectiveXService`, `SuiXService`, `NearXService`, `StacksXService`, `XverseXConnector`, `UnisatXConnector`, `OKXXConnector`, `IconHanaXConnector`, …) | **Not removed — moved to per-chain sub-paths.** TS error `TS2724: '"@sodax/wallet-sdk-react"' has no exported member named 'StellarXService'. Did you mean 'useXService'?` is misleading — the hint points at `useXService` (which returns the abstract `XService \| undefined`), but the typed class itself lives at `@sodax/wallet-sdk-react/xchains/<chain>`. See [`imports.md` § "Concrete chain classes — moved behind sub-path imports"](./imports.md#concrete-chain-classes--moved-behind-sub-path-imports) for the per-chain table. |
+
+### `useXBalances` — moved + reshaped
+
+Not a simple package-rename. The v2 hook also wraps params and adds a required `xService` field:
+
+```diff
+- // v1 — flat args from @sodax/wallet-sdk-react
+- import { useXBalances } from '@sodax/wallet-sdk-react';
+- const { data } = useXBalances({ xChainId, xTokens, address });
+
++ // v2 — from @sodax/dapp-kit; params wrapped; xService required
++ import { useXBalances } from '@sodax/dapp-kit';
++ import { useXService, getXChainType } from '@sodax/wallet-sdk-react';
++
++ const xService = useXService({ xChainType: getXChainType(xChainId) });
++ const { data } = useXBalances({
++   params: { xService, xChainId, xTokens, address },
++ });
+```
+
+The `xService` injection is part of dapp-kit's "no implicit wallet-sdk dependency" design — dapp-kit doesn't import from `wallet-sdk-react`, so the consumer wires the service across at the call site. See `sodax-dapp-kit`: `integration/knowledge/architecture.md` § "Decoupling from wallet-sdk-react".
+
+### `useXWagmiStore` — removed (store reads moved to public hooks)
+
+The v1 Zustand store hook is gone from the v2 barrel. Direct store access is no longer supported. Every `useXWagmiStore(state => state.X)` selector maps to a public hook — see [`imports.md` § "Store hook removed from the public API"](./imports.md#store-hook-removed-from-the-public-api) for the full field-to-hook map and decision tree (`state.xServices` → `useXServices()`, `state.xConnections[chainType]` → `useXConnection({ xChainType })`, etc.). The localStorage key (`xwagmi-store`) is unchanged, so user connections survive the upgrade.
+
+---
+
+## Added in v2 (no v1 equivalent)
+
+See [`imports.md`](./imports.md) § "Added in v2" for the full list (`useWalletModal`, `useChainGroups`, `useBatchConnect`, etc.). These are not migration items — they are new capabilities you may opt into.

package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/imports.md

@@ -0,0 +1,158 @@
+# Reference: Import Path Map
+
+Mechanical import-path replacements for v1 → v2. The package name (`@sodax/wallet-sdk-react`) is unchanged. See [`../breaking-changes.md`](../breaking-changes.md) §5 for the WHY behind concrete-class sub-path imports.
+
+---
+
+## Store hook removed from the public API
+
+v1 exported the Zustand store hook (`useXWagmiStore`) from the package barrel. **v2 does not export the store hook at all** — direct store access is no longer supported. The localStorage key (`xwagmi-store`) is unchanged, so user connections survive the upgrade.
+
+For each `useXWagmiStore(state => state.X)` selector, replace with the equivalent public hook below. **Do not rename to `useXWalletStore`** — the v2 barrel does not export it.
+
+### Field-to-hook map
+
+| v1 selector | v2 replacement |
+|---|---|
+| `state.xServices` (whole map) | `useXServices()` |
+| `state.xServices[chainType]` (per chain) | `useXService({ xChainType })` |
+| `state.xConnections` (whole map) | `useXConnections()` |
+| `state.xConnections[chainType]` (per chain) | `useXConnection({ xChainType })` |
+| `state.setXConnection` | not a public mutation — use `useXConnect()` (mutation hook) |
+| `state.unsetXConnection` | not a public mutation — use `useXDisconnect()` |
+
+```diff
+- // v1 ❌
+- import { useXWagmiStore } from '@sodax/wallet-sdk-react';
+- const xServices = useXWagmiStore(state => state.xServices);
++ // v2 ✅ — public hook, no store access
++ import { useXServices } from '@sodax/wallet-sdk-react';
++ const xServices = useXServices();
+```
+
+### Decision tree — `useXWagmiStore` selector handling
+
+For each occurrence of `useXWagmiStore(state => state.X)`:
+
+1. **Is `X` a public-hook-equivalent read** (`xServices`, `xConnections`, or per-chain access of either)?
+   → Replace with the public hook from the table. Drop the `useXWagmiStore` import.
+2. **Is `X` a mutation** (`setXConnection`, `unsetXConnection`) **or a v2-internal field** (`enabledChains`, `chainActions`, `walletProviders`, `xConnectorsByChain`)?
+   → STOP. The user's code is poking at internal API or was hand-edited mid-migration. Ask the user before changing.
+3. **Anything else** (typo, removed v1 field)?
+   → STOP. Ask user.
+
+### Worked example
+
+```ts
+// @ai-snippets-skip
+// v1 ❌ — direct store read
+const xServices = useXWagmiStore(state => state.xServices);
+
+// v2 ✅ — public hook (no store access)
+const xServices = useXServices();
+
+// 🛑 STOP — mutation through store; v2 does not expose this on a hook
+const setConn = useXWagmiStore(state => state.setXConnection);
+// → Ask user. Likely they want useXConnect()'s mutation instead.
+```
+
+Always prefer public hooks (`useXService`, `useXServices`, `useXConnection`, `useXConnections`, `useEnabledChains`, `useWalletProvider`) over store reads — see [`reference/hooks.md`](../../../integration/knowledge/reference/hooks.md).
+
+---
+
+## Concrete chain classes — moved behind sub-path imports
+
+v1 re-exported every concrete `XService` / `XConnector` subclass from the package barrel. v2's barrel exports only types, hooks, abstractions, and `SodaxWalletProvider`.
+
+| Concrete class | v1 import path | v2 import path |
+|---|---|---|
+| `EvmXService`, `EvmXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/evm` |
+| `SolanaXService`, `SolanaXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/solana` |
+| `SuiXService`, `SuiXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/sui` |
+| `BitcoinXService`, `UnisatXConnector`, `XverseXConnector`, `OKXXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/bitcoin` |
+| `StellarXService`, `StellarWalletsKitXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/stellar` |
+| `InjectiveXService`, `InjectiveXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/injective` |
+| `IconXService`, `IconHanaXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/icon` |
+| `NearXService`, `NearXConnector` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/near` |
+| `StacksXService`, `StacksXConnector`, `STACKS_PROVIDERS` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react/xchains/stacks` |
+
+### Examples
+
+```diff
+- // v1 ❌ — all concrete classes from barrel
+- import {
+-   EvmXService,
+-   XverseXConnector,
+-   IconHanaXConnector,
+- } from '@sodax/wallet-sdk-react';
++ // v2 ✅ — sub-path per chain
++ import { EvmXService } from '@sodax/wallet-sdk-react/xchains/evm';
++ import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
++ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
+```
+
+### Type imports also use sub-path
+
+Even when you only need a **type** (not the runtime class), the v2 barrel does not re-export concrete chain types. Use the sub-path import with `import type`:
+
+```diff
+- // v1 ❌
+- import { type StellarXService, useXService } from '@sodax/wallet-sdk-react';
++ // v2 ✅ — sub-path import for both type and runtime
++ import type { StellarXService } from '@sodax/wallet-sdk-react/xchains/stellar';
++ import type { XverseXConnector, BtcWalletAddressType } from '@sodax/wallet-sdk-react/xchains/bitcoin';
++ import { useXService } from '@sodax/wallet-sdk-react';
+```
+
+`import type` from sub-paths is **erased at build time** — no runtime cost. Use it freely for type annotations, `as`, generics, etc.
+
+---
+
+## Hooks — same package, same names (signatures changed)
+
+| Hook | v1 path | v2 path | Signature changed? |
+|---|---|---|---|
+| `useXAccount` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes — see [`hooks.md`](./hooks.md) |
+| `useXAccounts` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | no |
+| `useXConnect` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | no |
+| `useXConnection` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useXConnectors` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useXDisconnect` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes — returned function now takes `{ xChainType }` object (was positional) |
+| `useXService` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useWalletProvider` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes |
+| `useXSignMessage` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | no |
+| `useEvmSwitchChain` | `@sodax/wallet-sdk-react` | `@sodax/wallet-sdk-react` | yes — now takes `{ xChainId }`, returns `{ isWrongChain, handleSwitchChain }` |
+
+For signature changes see [`hooks.md`](./hooks.md).
+
+---
+
+## Removed in v2
+
+| Symbol | v1 path | Replacement |
+|---|---|---|
+| `useXBalances` | `@sodax/wallet-sdk-react` | Moved to `@sodax/dapp-kit` with a new signature (`{ params: { xService, xChainId, xTokens, address } }`). See [`../breaking-changes.md`](../breaking-changes.md) §10. |
+| `useEthereumChainId` | `@sodax/wallet-sdk-react` | Internal in v2. Use `useAccount().chainId` from `wagmi` for the raw EVM chain ID, or `useEvmSwitchChain({ xChainId })` if you only needed it for "wrong network" UX. See [`hooks.md`](./hooks.md) § `useEthereumChainId`. |
+
+---
+
+## Added in v2 (informational — no v1 to migrate from)
+
+These are new exports — no v1 import to replace, but knowing they exist may let you simplify hand-rolled v1 code during migration:
+
+| New hook / utility | Path | Purpose |
+|---|---|---|
+| `useWalletModal` | `@sodax/wallet-sdk-react` | Headless modal state machine |
+| `useConnectionFlow` | `@sodax/wallet-sdk-react` | `connect + status + retry` without modal |
+| `useBatchConnect` | `@sodax/wallet-sdk-react` | Sequential connect across multiple connectors |
+| `useBatchDisconnect` | `@sodax/wallet-sdk-react` | Mirror of `useBatchConnect` |
+| `useChainGroups` | `@sodax/wallet-sdk-react` | One row per enabled chain (EVM collapses) |
+| `useConnectedChains` | `@sodax/wallet-sdk-react` | Aggregate connected view + hydration `status` |
+| `useEnabledChains` | `@sodax/wallet-sdk-react` | List of chain types enabled in config |
+| `useIsWalletInstalled` | `@sodax/wallet-sdk-react` | Cross-chain install check |
+| `useXConnections` | `@sodax/wallet-sdk-react` | All connections (plural) |
+| `useXConnectorsByChain` | `@sodax/wallet-sdk-react` | Multi-chain connector list (no per-chain warnings) |
+| `useXServices` | `@sodax/wallet-sdk-react` | All services (plural) |
+| `sortConnectors` | `@sodax/wallet-sdk-react` | Helper: preferred → installed → original |
+| `getXChainType` | `@sodax/wallet-sdk-react` | Imperative: map a `SpokeChainKey` to its `ChainType` family. Common pattern: `useXService({ xChainType: getXChainType(srcChainKey) })` when you only have a chain key on hand. |
+| `getXService` | `@sodax/wallet-sdk-react` | Imperative variant of `useXService` for non-React call sites (e.g. inside event handlers that don't re-render). Prefer `useXService` in component bodies. |