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

package/docs/CONNECTORS.md

@@ -0,0 +1,247 @@
+# 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. The base abstract class `XConnector` provides default `isInstalled` / `installUrl` semantics that subclasses override per wallet.
+
+Concrete connector and service classes are **not** exported from the package barrel — they live behind sub-path imports under `@sodax/wallet-sdk-react/xchains/<chain>` to prevent accidental coupling.
+
+## Table of contents
+
+1. [`IXConnector` interface](#ixconnector-interface)
+2. [`XConnector` abstract base](#xconnector-abstract-base)
+3. [Sub-path imports — concrete classes](#sub-path-imports--concrete-classes)
+4. [Per-chain connector reference](#per-chain-connector-reference)
+5. [Discovery — EIP-6963 vs adapter vs window probe](#discovery--eip-6963-vs-adapter-vs-window-probe)
+6. [`sortConnectors` — display ordering](#sortconnectors--display-ordering)
+7. [Custom connectors](#custom-connectors)
+
+---
+
+## `IXConnector` interface
+
+Defined in [`src/types/interfaces.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/types/interfaces.ts):
+
+```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;          // raw icon URL (or undefined)
+
+  readonly id: string;              // public getter — same as _id
+  readonly icon: string | undefined; // public getter
+
+  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 — this 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 (store updates, parent re-renders).
+
+---
+
+## `XConnector` abstract base
+
+The default class subclasses extend ([`src/core/XConnector.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/core/XConnector.ts)):
+
+```typescript
+export abstract class XConnector implements IXConnector {
+  public readonly xChainType: ChainType;
+  public readonly name: string;
+  public readonly _id: string;
+  public readonly _icon?: string;
+
+  constructor(xChainType: ChainType, name: string, id: string) { ... }
+
+  abstract connect(): Promise<XAccount | undefined>;
+  abstract disconnect(): Promise<void>;
+
+  get id(): string { return this._id; }
+  get icon(): string | undefined { return this._icon; }
+
+  /** Default: true. Override in subclasses backed by extension injection. */
+  get isInstalled(): boolean { return true; }
+  get installUrl(): string | undefined { return undefined; }
+}
+```
+
+The `isInstalled = true` default is correct for **provider-managed chains** (EVM via EIP-6963, Solana via wallet-adapter discovery, Sui via dapp-kit) — if the connector exists in the store, the underlying extension was found by the native SDK.
+
+Browser-extension chains (Bitcoin, ICON, Stacks) override `isInstalled` with a `window.unisat` / `window.hanaWallet` / `window.LeatherProvider` probe, plus an `installUrl` to point users to the Chrome Web Store entry.
+
+---
+
+## Sub-path imports — concrete classes
+
+The package barrel `@sodax/wallet-sdk-react` deliberately omits concrete classes — only types/interfaces and hooks are exported. To get a concrete class for `instanceof` checks or chain-specific methods, deep-import:
+
+```typescript
+// ✅ Normal usage — barrel
+import { useXConnect, useXAccount, type IXConnector } from '@sodax/wallet-sdk-react';
+
+// ✅ Advanced — concrete class
+import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+
+if (connector instanceof XverseXConnector) {
+  connector.setAddressPurpose('payment');
+}
+```
+
+The `package.json` `exports` field maps `./xchains/*` to `dist/xchains/*/index.{mjs,cjs}` and `typesVersions` adds the `node` resolution fallback.
+
+### Sub-path map
+
+| Sub-path | Exports |
+|----------|---------|
+| `@sodax/wallet-sdk-react/xchains/evm` | `EvmXService`, `EvmXConnector`, `createWagmiConfig` (alias `createWagmi`) |
+| `@sodax/wallet-sdk-react/xchains/solana` | `SolanaXService`, `SolanaXConnector` |
+| `@sodax/wallet-sdk-react/xchains/sui` | `SuiXService`, `SuiXConnector` |
+| `@sodax/wallet-sdk-react/xchains/bitcoin` | `BitcoinXService`, `BitcoinXConnector`, `UnisatXConnector`, `XverseXConnector`, `OKXXConnector`, `useBitcoinXConnectors`, type `BtcWalletAddressType` |
+| `@sodax/wallet-sdk-react/xchains/stellar` | `StellarXService`, `StellarWalletsKitXConnector` |
+| `@sodax/wallet-sdk-react/xchains/injective` | `InjectiveXService`, `InjectiveXConnector` |
+| `@sodax/wallet-sdk-react/xchains/icon` | `IconXService`, `IconHanaXConnector`, `CHAIN_INFO`, `SupportedChainId` |
+| `@sodax/wallet-sdk-react/xchains/near` | `NearXService`, `NearXConnector` |
+| `@sodax/wallet-sdk-react/xchains/stacks` | `StacksXService`, `StacksXConnector`, `STACKS_PROVIDERS`, `useStacksXConnectors`, type `StacksProviderConfig` |
+
+`StellarXService`, `XverseXConnector`, `BtcWalletAddressType` are **also** re-exported from the barrel as `export type` (no runtime class) — those imports work either way.
+
+---
+
+## Per-chain connector reference
+
+| Chain | Connector class(es) | Discovery | Native SDK |
+|-------|---------------------|-----------|------------|
+| EVM | `EvmXConnector` | EIP-6963 + wagmi connectors | `wagmi` + `viem` |
+| Solana | `SolanaXConnector` | `@solana/wallet-adapter-react` | `@solana/web3.js` |
+| Sui | `SuiXConnector` | `@mysten/dapp-kit` | `@mysten/sui` |
+| Stellar | `StellarWalletsKitXConnector` | async — `walletsKit.getSupportedWallets()` | `@creit.tech/stellar-wallets-kit` |
+| Injective | `InjectiveXConnector` × 3 (MetaMask, Keplr, Leap) | wallet-base wallet types | `@injectivelabs/sdk-ts` |
+| ICON | `IconHanaXConnector` | `window.hanaWallet` probe | `icon-sdk-js` |
+| Bitcoin | `UnisatXConnector`, `XverseXConnector`, `OKXXConnector` | `window.unisat`, `window.XverseProviders`, `window.okxwallet.bitcoin` | `sats-connect` (Xverse), connector-specific (Unisat, OKX) |
+| NEAR | `NearXConnector` | `@hot-labs/near-connect` | `near-api-js` |
+| Stacks | `StacksXConnector` × N (one per registered provider) | provider list + `window.LeatherProvider` probe | `@stacks/connect` |
+
+The `BitcoinXConnector` is an abstract base — concrete subclasses (Unisat, Xverse, OKX) implement `signEcdsaMessage` / `signBip322Message` per wallet's API. See [`SIGN_MESSAGE.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/SIGN_MESSAGE.md) for the dispatch logic.
+
+---
+
+## Discovery — EIP-6963 vs adapter vs window probe
+
+Connectors land in the store via three discovery patterns:
+
+**Synchronous default list** (most chains) — `chainRegistry.<CHAIN>.defaultConnectors()` returns a static array at `initChainServices()` time. Bitcoin always registers Unisat + Xverse + OKX; Injective registers MetaMask + Keplr + Leap.
+
+**Async discovery** — Stellar's connectors come from `walletsKit.getSupportedWallets()` which probes for installed Stellar wallets at runtime. Implemented via `chainRegistry.STELLAR.discoverConnectors`, called as a side-effect during init.
+
+**Native SDK adapter** — EVM, Solana, Sui delegate to wagmi / wallet-adapter / dapp-kit. The adapter discovers wallets via EIP-6963 announcements (EVM) or vendor-specific extension protocols, and the chain's Hydrator reads the discovered list and writes it to the store.
+
+Once in the store, all three patterns surface uniformly through `useXConnectors({ xChainType })` — consumers can't tell them apart.
+
+---
+
+## `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 (matches the batch-operation API), use [`useIsWalletInstalled`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md#useiswalletinstalled--install-detection) instead.
+
+---
+
+## Custom connectors
+
+Two ways to plug in a wallet the SDK doesn't ship:
+
+### Option 1 — extend `XConnector`
+
+```typescript
+import { XConnector } from '@sodax/wallet-sdk-react'; // base class is exported from barrel
+import type { XAccount } from '@sodax/wallet-sdk-react';
+
+class MyEvmConnector extends XConnector {
+  constructor() {
+    super('EVM', 'My Wallet', 'com.mycompany.wallet');
+  }
+
+  override get isInstalled(): boolean {
+    return typeof window !== 'undefined' && 'mywallet' in window;
+  }
+
+  override get installUrl(): string {
+    return 'https://chrome.google.com/webstore/detail/...';
+  }
+
+  async connect(): Promise<XAccount | undefined> {
+    const accounts = await window.mywallet.request({ method: 'eth_requestAccounts' });
+    return accounts[0]
+      ? { address: accounts[0], xChainType: 'EVM' }
+      : undefined;
+  }
+
+  async disconnect(): Promise<void> {
+    await window.mywallet.request({ method: 'wallet_revokePermissions' });
+  }
+}
+```
+
+Pass it via `SodaxWalletConfig.<CHAIN>.connectors`:
+
+```typescript
+const config: SodaxWalletConfig = {
+  EVM: {
+    connectors: [new MyEvmConnector(), /* …or omit and the registry's defaults run instead */],
+  },
+};
+```
+
+The `connectors` field on a chain-type slot **replaces** the registry defaults for that chain. Include the SDK's defaults in the array if you want them alongside your custom one.
+
+### Option 2 — implement `IXConnector` directly
+
+Skip `XConnector` if you already have a class hierarchy and don't want the abstract base. Just implement every property/method on `IXConnector`. The SDK never does an `instanceof XConnector` check on user-supplied connectors — it only relies on the interface.
+
+```typescript
+class MyConnector implements IXConnector {
+  readonly xChainType = 'EVM';
+  readonly name = 'My Wallet';
+  readonly _id = 'com.mycompany.wallet';
+  readonly id = this._id;
+  readonly icon = undefined;
+  get isInstalled() { /* … */ }
+  get installUrl() { /* … */ }
+  async connect() { /* … */ }
+  async disconnect() { /* … */ }
+}
+```
+
+For chains with custom `signMessage` requirements (Bitcoin, Injective), implement the chain-specific extra methods (`signBip322Message` / `signEcdsaMessage` for Bitcoin) — `chainRegistry` checks for them via type guards at dispatch time.
+
+---
+
+## Related docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — `connectors` slot field for overriding defaults
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — how `useXConnectors` returns these connectors
+- [Sign Message](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/SIGN_MESSAGE.md) — Bitcoin connector subclass dispatch (BIP-322 vs ECDSA)
+- [Batch Operations](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/BATCH_OPERATIONS.md) — identifier-based connector matching
+- [Wallet Modal](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md) — `selectWallet(connector)` consumes `IXConnector`
+- [SDK Wallet Providers Reference](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md) — the `IXxxWalletProvider` interfaces these connectors back into

package/docs/CONNECT_FLOW.md

@@ -0,0 +1,276 @@
+# Connect Flow
+
+The connect flow covers the full wallet lifecycle in `@sodax/wallet-sdk-react`: discover available connectors → connect to a wallet → read connected account state → disconnect. Every hook reads from the central Zustand store — no direct chain-SDK hook usage in user code.
+
+The canonical hook surface is exported from [`src/hooks/index.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/hooks/index.ts).
+
+## Table of contents
+
+1. [Lifecycle overview](#lifecycle-overview)
+2. [Discover connectors](#discover-connectors)
+3. [Connect a wallet](#connect-a-wallet)
+4. [Read connected account state](#read-connected-account-state)
+5. [Disconnect](#disconnect)
+6. [Provider-managed chains caveat](#provider-managed-chains-caveat)
+7. [Persisted connections](#persisted-connections)
+8. [Error handling](#error-handling)
+
+---
+
+## Lifecycle overview
+
+```
+useXConnectors  →  user picks a connector  →  useXConnect.mutateAsync(connector)
+       │                                              │
+       │                                              ↓
+       │                              ChainActions.connect(connectorId)
+       │                                              │
+       │                                              ↓
+       │                              setXConnection(xChainType, { xAccount, xConnectorId })
+       │                                              │
+       ↓                                              ↓
+useXAccount(xChainType) ←─────────────  Zustand store  ─────────────→  useXConnection(xChainType)
+                                                      │
+                                                      ↓
+                                            useXDisconnect({ xChainType })
+                                                      │
+                                                      ↓
+                                              ChainActions.disconnect()
+                                                      │
+                                                      ↓
+                                              clearXConnection(xChainType)
+```
+
+**Single store, single source of truth** — every hook subscribes to the same Zustand slice. Connect mutations write through `setXConnection`; reads (`useXAccount`, `useXConnection`) reflect that immediately. Provider-managed chains (EVM/Solana/Sui) write via their Hydrator components instead of inside the mutation — see [Provider-managed chains caveat](#provider-managed-chains-caveat).
+
+---
+
+## Discover connectors
+
+### `useXConnectors({ xChainType })` — connectors for one chain type
+
+Returns the list of available connectors for a single chain family. Pass `xChainType` (`'EVM' | 'SOLANA' | 'BITCOIN' | …`).
+
+```typescript
+import { useXConnectors } from '@sodax/wallet-sdk-react';
+
+function EvmWalletList() {
+  const connectors = useXConnectors({ xChainType: 'EVM' });
+  // connectors: IXConnector[] with { id, name, icon, isInstalled, installUrl, xChainType }
+}
+```
+
+If the chain isn't enabled in `SodaxWalletProvider` config, `useXConnectors` returns `[]` and logs a one-time warning per chain.
+
+`connector.isInstalled` reads `window.*` at render time (no extra subscription) — values stay fresh through normal React render triggers (store updates, parent re-renders).
+
+### `useXConnectorsByChain()` — all chains at once
+
+Returns connectors grouped by chain type. Useful for multi-chain wallet pickers.
+
+```typescript
+import { useXConnectorsByChain } from '@sodax/wallet-sdk-react';
+
+function MultiChainPicker() {
+  const byChain = useXConnectorsByChain();
+  // byChain: Partial<Record<ChainType, IXConnector[]>>
+  // e.g. { EVM: [...], SOLANA: [...], BITCOIN: [...] }
+}
+```
+
+### `sortConnectors(connectors, { preferred })` — display ordering
+
+Pure utility that sorts a connector list **stably** by:
+1. Position in `preferred[]` (earlier wins)
+2. `isInstalled === true`
+3. Original order
+
+```typescript
+import { useXConnectors, sortConnectors } from '@sodax/wallet-sdk-react';
+
+const PREFERRED = ['hana', 'metamask'] as const;
+
+function ConnectorList() {
+  const raw = useXConnectors({ xChainType: 'EVM' });
+  const connectors = sortConnectors(raw, { preferred: PREFERRED });
+  // Hana first if installed, then MetaMask, then any other installed wallets, then uninstalled.
+}
+```
+
+---
+
+## Connect a wallet
+
+`useXConnect()` returns a React Query mutation. Pass an `IXConnector` to `mutate` / `mutateAsync` — the hook delegates to the chain's `ChainActions.connect()` and writes the connection state into the store on success.
+
+```tsx
+import { useXConnect, useXConnectors, useXAccount } from '@sodax/wallet-sdk-react';
+
+function ConnectButton() {
+  const connectors = useXConnectors({ xChainType: 'EVM' });
+  const { mutateAsync: connect, isPending, error } = useXConnect();
+  const account = useXAccount({ xChainType: 'EVM' });
+
+  if (account.address) {
+    return <span>Connected: {account.address}</span>;
+  }
+
+  return (
+    <div>
+      {connectors.map(connector => (
+        <button
+          key={connector.id}
+          onClick={() => connect(connector)}
+          disabled={isPending}
+        >
+          {connector.icon && <img src={connector.icon} alt="" width={20} height={20} />}
+          {connector.name}
+        </button>
+      ))}
+      {error && <p style={{ color: 'red' }}>{error.message}</p>}
+    </div>
+  );
+}
+```
+
+The mutation throws `Error('Chain "<X>" is not enabled or ChainActions not registered')` if the connector's chain type isn't mounted in `SodaxWalletProvider` config.
+
+---
+
+## Read connected account state
+
+Four read hooks expose the same store data at different granularities:
+
+| Hook | Returns | Use case |
+|------|---------|----------|
+| `useXAccount({ xChainId })` | `XAccount` for the chain's family (resolves chain id → chain type) | Signing/reading at chain-id level (e.g. `useXAccount({ xChainId: ChainKeys.BSC_MAINNET })`) |
+| `useXAccount({ xChainType })` | `XAccount` for that family | Family-level UI (e.g. EVM badge — one wagmi connection covers all 12 EVM chains) |
+| `useXAccounts()` | `Partial<Record<ChainType, XAccount>>` for every enabled chain | Account list / multi-chain dashboard |
+| `useXConnection({ xChainType })` | `XConnection \| undefined` | When you also need `xConnectorId` (e.g. to drive disconnect UX) |
+| `useXConnections()` | `Partial<Record<ChainType, XConnection>>` | Aggregate UIs that care about connector identity per chain |
+
+```typescript
+import { useXAccount, useXAccounts, useXConnection } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+// By chain id — narrows to EVM family
+const evmAccount = useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
+// evmAccount: { address: '0x...' | undefined, xChainType: 'EVM', publicKey?: string }
+
+// By chain type — same data, family-level UI
+const solanaAccount = useXAccount({ xChainType: 'SOLANA' });
+
+// All connected accounts at once
+const accounts = useXAccounts();
+// accounts.EVM, accounts.SOLANA, accounts.BITCOIN, ...
+
+// With connector identity (for disconnect button labels, etc.)
+const evmConnection = useXConnection({ xChainType: 'EVM' });
+// evmConnection: { xAccount: XAccount, xConnectorId: string } | undefined
+```
+
+**`xChainId` vs `xChainType`** — `useXAccount` and `useWalletProvider` accept either, never both. `xChainId` (a `SpokeChainKey` like `ChainKeys.BSC_MAINNET`) is resolved to its family via `getXChainType()` internally. For EVM, the family-level view is correct because wagmi maintains a single connection across all configured EVM networks (see [`EVM_SWITCH_CHAIN.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/EVM_SWITCH_CHAIN.md)).
+
+When no wallet is connected, `useXAccount` returns `{ address: undefined, xChainType }` (not `undefined`) so consumers don't need to null-check before reading `xChainType`.
+
+---
+
+## Disconnect
+
+`useXDisconnect()` returns a callback. Invoke with the chain type to disconnect:
+
+```tsx
+import { useXDisconnect } from '@sodax/wallet-sdk-react';
+
+function DisconnectButton() {
+  const disconnect = useXDisconnect();
+  return <button onClick={() => disconnect({ xChainType: 'EVM' })}>Disconnect EVM</button>;
+}
+```
+
+The callback delegates to `ChainActions.disconnect()`. If no actions are registered (chain not enabled in config), it logs a warning and resolves silently — no throw. Connection state is cleared by the chain's action implementation (provider-managed) or by the store side-effect (non-provider).
+
+---
+
+## Provider-managed chains caveat
+
+EVM, Solana, and Sui mount their native React adapters (wagmi, `@solana/wallet-adapter`, `@mysten/dapp-kit`) and use a **Provider/Hydrator/Actions trio**:
+
+- `<ChainProvider>` — wraps native adapter context.
+- `<ChainHydrator>` — sole writer of connection state into the store, watching native adapter hooks.
+- `<ChainActions>` — registers `ChainActions.connect/disconnect` that trigger native SDK operations only.
+
+Because of this split, **`useXConnect.mutateAsync(connector)` resolves with `undefined`** for EVM/Solana/Sui — connection state lands asynchronously when the Hydrator observes the wallet adapter's status flip from `disconnected` → `connected`. Read the connected account via `useXAccount` / `useXConnection` instead:
+
+```typescript
+const { mutateAsync: connect } = useXConnect();
+const account = useXAccount({ xChainType: 'EVM' });
+
+await connect(connector); // may resolve before account.address is populated
+// Don't read connect's return value — read account.address from the next render.
+```
+
+Non-provider chains (Bitcoin, ICON, Injective, Stellar, NEAR, Stacks) write the connection state inside the mutation, so the resolved `XAccount` is reliable for those chains. Code defensively if you support both.
+
+---
+
+## Persisted connections
+
+Connection state is persisted to `localStorage` (key: `xwagmi-store`) by Zustand's `persist` middleware. On page reload:
+
+- **Provider-managed chains** — wagmi/wallet-adapter/dapp-kit auto-reconnect from their own persistence layer; the Hydrator observes and re-writes the store.
+- **Non-provider chains** — `useInitChainServices` calls `reconnectIcon()` / `reconnectInjective()` / `reconnectStellar()` after hydration. ICON, Injective, and Stellar attempt to reconnect to the previously-connected wallet automatically.
+- **Bitcoin** — `BitcoinXConnector.recreateWalletProvider` rebuilds the provider from `window.*` + the persisted `XAccount` (no popup), so signing works after reload without a reconnect call.
+- **NEAR / Stacks** — no auto-reconnect. The user must re-connect manually after a reload.
+- **Cleanup** — connections for chains no longer in `SodaxWalletProvider` config are removed via `cleanupDisabledConnections()` after persist hydration completes.
+
+To detect when persisted state is ready (avoid disconnect flash on first paint), use [`useConnectedChains`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md) and gate UI on `status === 'ready'`.
+
+---
+
+## Error handling
+
+`useXConnect` errors fall into two categories:
+
+**Configuration errors** — chain type isn't enabled. Message: `Chain "<X>" is not enabled or ChainActions not registered`. Fix by adding the slot to `SodaxWalletProvider` config.
+
+**Wallet/runtime errors** — propagated from the underlying wallet SDK. Examples:
+
+| Source | Message style |
+|--------|---------------|
+| User rejects in wallet popup | Wallet-specific (`"User rejected the request"`, `"User denied account authorization"`, etc.) |
+| Wallet not installed | `"Wallet extension not detected"` (varies by chain) |
+| Network mismatch | `"Chain not configured"` (wagmi) |
+
+Read `mutation.error.message` and surface to UI; for install CTA, fall back to `connector.installUrl`:
+
+```tsx
+const { mutateAsync: connect, error } = useXConnect();
+
+return (
+  <>
+    <button onClick={() => connect(connector).catch(() => {})}>Connect</button>
+    {error && (
+      <div>
+        {error.message}
+        {!connector.isInstalled && connector.installUrl && (
+          <a href={connector.installUrl}>Install {connector.name}</a>
+        )}
+      </div>
+    )}
+  </>
+);
+```
+
+For multi-chain modal flows that wrap connect with status + retry semantics, see [`WALLET_MODAL.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md).
+
+---
+
+## Related docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — chain-type slots, opt-in mounting
+- [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
+- [Wallet Modal](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md) — headless state machine (chainSelect → walletSelect → connecting → success | error)
+- [Chain Detection](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md) — aggregate connected-chain views + hydration status
+- [EVM Switch Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/EVM_SWITCH_CHAIN.md) — single wagmi connection across EVM networks
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — `IXConnector` contract, deep imports for concrete classes