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

package/ai-exported/integration/recipes/switch-chain.md

@@ -1,141 +0,0 @@
-# Recipe: Switch EVM Chain
-
-A single wagmi connection covers **every configured EVM network** (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, etc.). The user picks a wallet once; switching the **active network** is a separate concern handled by `useEvmSwitchChain`.
-
-**Depends on:** [`setup.md`](./setup.md), [`connect-button.md`](./connect-button.md) or [`multi-chain-modal.md`](./multi-chain-modal.md)
-
----
-
-## Why this exists
-
-When you call `sodax.swaps.swap({ params: { srcChainKey: ChainKeys.BSC_MAINNET, ... }, walletProvider })`, the wallet provider must be **on BSC at signing time** — wagmi will reject the tx otherwise. But wagmi remembers the last network the user selected, so a user who connected via MetaMask on Ethereum and then opened your dApp's BSC swap form needs to switch first.
-
-`useEvmSwitchChain` reads the connected EVM wallet's current chain id, compares against the chain id implied by `srcChainKey`, and exposes:
-
-- `isWrongChain: boolean` — render a "Switch to BSC" CTA when `true`
-- `handleSwitchChain()` — triggers wagmi's `switchChain()` (or `wallet_switchEthereumChain` for Injective MetaMask)
-
-Without this hook you'd have to import wagmi directly and replicate the logic per-chain.
-
----
-
-## Hook API
-
-```typescript
-import { useEvmSwitchChain } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
-  xChainId: ChainKeys.BSC_MAINNET,
-});
-```
-
-| Field | Type | Behavior |
-|-------|------|----------|
-| `isWrongChain` | `boolean` | `true` when the wallet's active chain id doesn't match `xChainId`. Always `false` for non-EVM/Injective chain ids. |
-| `handleSwitchChain` | `() => void` | Triggers the network switch. No-op for chain ids that aren't EVM or Injective. |
-
-The hook never throws — `handleSwitchChain` returns synchronously and lets wagmi (or `wallet_switchEthereumChain`) own the user-rejection error path.
-
----
-
-## Standard EVM switch flow
-
-```tsx
-'use client';
-
-import { useEvmSwitchChain, useWalletProvider, useXAccount } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-export function BscSwapButton() {
-  const account = useXAccount({ xChainType: 'EVM' });
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-  const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
-    xChainId: ChainKeys.BSC_MAINNET,
-  });
-
-  if (!account.address || !walletProvider) {
-    return <ConnectCta />;
-  }
-
-  if (isWrongChain) {
-    return <button onClick={handleSwitchChain}>Switch to BSC</button>;
-  }
-
-  return <button onClick={() => doSwap(walletProvider)}>Swap on BSC</button>;
-}
-```
-
-`useSwitchChain` opens the wallet's network-switch popup; wagmi handles the chain-config-not-added flow (most wallets prompt to add the chain if it's missing).
-
----
-
-## Pattern: gate every cross-chain action
-
-For dApps where the source chain depends on user input (e.g. a swap form with a "from chain" picker), wire `useEvmSwitchChain` against the **selected** chain id:
-
-```tsx
-function SwapForm() {
-  const [srcChainKey, setSrcChainKey] = useState<SpokeChainKey>(ChainKeys.SONIC_MAINNET);
-  const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({ xChainId: srcChainKey });
-  const walletProvider = useWalletProvider({ xChainId: srcChainKey });
-
-  const buttonState =
-    !walletProvider ? 'connect' :
-    isWrongChain ? 'switch' :
-    'swap';
-
-  return (
-    <>
-      <ChainSelect value={srcChainKey} onChange={setSrcChainKey} />
-      {buttonState === 'connect' && <ConnectCta />}
-      {buttonState === 'switch' && <button onClick={handleSwitchChain}>Switch chain</button>}
-      {buttonState === 'swap' && <button onClick={() => doSwap(walletProvider)}>Swap</button>}
-    </>
-  );
-}
-```
-
-Re-renders on `srcChainKey` change automatically — no manual reset needed.
-
----
-
-## Injective MetaMask special case
-
-Injective offers MetaMask as a wallet option (in addition to Keplr, Leap). When MetaMask is the active Injective wallet, **the underlying Ethereum chain id must be mainnet (`1`)** — Injective uses MetaMask's `personal_sign` infrastructure which is bound to whatever EVM network the wallet is currently on.
-
-```tsx
-const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
-  xChainId: ChainKeys.INJECTIVE_MAINNET,
-});
-// isWrongChain === true if user is on Injective via MetaMask AND active EVM chain is not mainnet (1)
-// handleSwitchChain calls wallet_switchEthereumChain to chain id 0x1
-```
-
-Keplr and Leap on Injective don't have this constraint — `isWrongChain` is `false` for those wallets regardless of network state.
-
----
-
-## Safe to call when EVM is disabled
-
-`useEvmSwitchChain` checks `useEnabledChains()` and returns a no-op result `{ isWrongChain: false, handleSwitchChain: () => {} }` when the EVM slot isn't mounted in `SodaxWalletProvider` config. Calling wagmi's hooks outside a `WagmiProvider` would throw — the early-return lets components opt-in to a "switch chain" CTA without checking EVM-enabled themselves at every call site.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — connect MetaMask on Ethereum, open BSC swap form, confirm Switch button appears
-# 3. Manual — click Switch, approve in MetaMask, confirm Swap button replaces it
-# 4. Manual — switch to Polygon manually (in MetaMask), confirm Switch button reappears for BSC form
-```
-
----
-
-## Reference
-
-- [wagmi `useSwitchChain`](https://wagmi.sh/react/api/hooks/useSwitchChain) — underlying hook
-- [EIP-3326 — `wallet_switchEthereumChain`](https://eips.ethereum.org/EIPS/eip-3326) — RPC method spec

package/ai-exported/integration/recipes/walletconnect-setup.md

@@ -1,139 +0,0 @@
-# Recipe: WalletConnect Setup (EVM only)
-
-Enable WalletConnect protocol on the EVM slot for partners using enterprise custody (Fireblocks, Ledger Live, mobile-only wallets). Default EVM discovery (EIP-6963) only finds browser-extension wallets — WalletConnect lets users pair via QR / deep-link.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## When to use
-
-| Scenario | Need WalletConnect? |
-|----------|---------------------|
-| MetaMask / Hana / Rabby browser extension | ❌ — EIP-6963 covers them |
-| Enterprise custody wallets (e.g. Fireblocks, Safe) | ✅ |
-| Ledger Live | ✅ |
-| MetaMask Mobile / Trust / Rainbow (paired via QR) | ✅ |
-| Coinbase Smart Wallet | ✅ (fallback path) |
-
-If your dApp only targets desktop browser-extension wallets, omit `walletConnect` entirely.
-
----
-
-## 1. Get a WalletConnect Cloud project id
-
-Sign up at [https://cloud.walletconnect.com](https://cloud.walletconnect.com) and copy your project id. Add it to `.env`:
-
-```bash
-NEXT_PUBLIC_WC_PROJECT_ID=your-project-id
-```
-
----
-
-## 2. Add `walletConnect` to the `EVM` slot
-
-```typescript
-import { type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true,
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
-    },
-    walletConnect: {
-      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
-      // showQrModal: true is the default — wagmi/WalletConnect own the QR display
-    },
-  },
-};
-```
-
-A WalletConnect connector now surfaces alongside EIP-6963 wallets. `useXConnectors({ xChainType: 'EVM' })` returns it with `id === 'walletConnect'`. **No UI changes required** — your existing connect-button or modal already handles it.
-
----
-
-## 3. Restrict the QR modal to a specific wallet (optional)
-
-To show **only** one wallet in the WalletConnect modal (e.g. when integrating with a single enterprise custody provider), filter the WalletConnect Explorer list:
-
-```typescript
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    walletConnect: {
-      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
-      qrModalOptions: {
-        explorerRecommendedWalletIds: [
-          '<target-wallet-id>', // hex from WalletConnect Explorer
-        ],
-        explorerExcludedWalletIds: 'ALL', // hide everything except recommended
-      },
-    },
-  },
-};
-```
-
-Find wallet IDs at the [WalletConnect Explorer](https://walletconnect.com/explorer) — they're the long hex strings in the URL, not the human names. Default (no `qrModalOptions`) shows the full WalletConnect wallet list.
-
----
-
-## 4. Hide the Sodax modal during WalletConnect QR
-
-When the user picks the WalletConnect connector, wagmi opens its own QR modal — two dialogs would stack. Detect WC by connector id and render `null`:
-
-```typescript
-import { useWalletModal } from '@sodax/wallet-sdk-react';
-
-const modal = useWalletModal();
-
-if (
-  modal.state.kind === 'connecting' &&
-  modal.state.connector.id === 'walletConnect'
-) {
-  return null; // wagmi's QR modal owns the screen
-}
-```
-
-The `useWalletModal` state machine handles the `connecting → success | error` transition normally — only the rendering is conditionally blanked.
-
----
-
-## Missing `projectId` — silent skip
-
-Setting `walletConnect: {}` without a `projectId` (or with an empty string) **silently skips** the WalletConnect connector and logs a warning:
-
-```
-[wallet-sdk-react] walletConnect.projectId is required — WalletConnect connector skipped.
-```
-
-EIP-6963 wallets continue to work normally — the dApp degrades gracefully. This intentionally avoids forcing local-dev environments to plumb the env var.
-
----
-
-## EVM-only
-
-The `walletConnect` field only exists on the `EVM` slot. Solana, Bitcoin, etc. use their own native wallet adapters and don't share the WalletConnect protocol layer. Don't attempt `SOLANA: { walletConnect: ... }` — TypeScript will reject it.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Confirm walletConnect projectId is set
-grep -rn "walletConnect" <user-src> | grep -i "projectId"
-# expect at least one match
-
-# 3. Manual — open connect modal, confirm WalletConnect option appears alongside extension wallets
-```
-
----
-
-## Reference
-
-- [wagmi `WalletConnectParameters`](https://wagmi.sh/core/api/connectors/walletConnect) — full options reference
-- [WalletConnect Cloud](https://cloud.walletconnect.com) — get a `projectId`

package/ai-exported/integration/reference/api-surface.md

@@ -1,175 +0,0 @@
-# Reference: API Surface
-
-The complete public export surface of `@sodax/wallet-sdk-react` v2. This is the **single source of truth** for "what can I import". If a symbol is not listed here, it is not part of the public API.
-
-The check script `scripts/check-ai-exported.sh` validates that every symbol referenced in `ai-exported/**/*.md` appears either in this file or in `reference/connectors.md` / `reference/hooks.md`.
-
----
-
-## Barrel exports — `import { X } from '@sodax/wallet-sdk-react'`
-
-### Components
-
-| Symbol | Kind | Source |
-|---|---|---|
-| `SodaxWalletProvider` | React component | `SodaxWalletProvider.tsx` |
-| `SodaxWalletProviderProps` | type | `SodaxWalletProvider.tsx` |
-| `WalletConfigProvider` | React component (advanced — internal context) | `context/WalletConfigContext` |
-
-### Hooks
-
-See [`hooks.md`](./hooks.md) for full signatures. Names only:
-
-- `useXAccount`, `useXAccounts`
-- `useXConnect`, `useXDisconnect`
-- `useXConnection`, `useXConnections`
-- `useXConnectors`, `useXConnectorsByChain`
-- `useIsWalletInstalled`
-- `useChainGroups`, `useConnectedChains`
-- `useConnectionFlow`
-- `useBatchConnect`, `useBatchDisconnect`
-- `useWalletModal`
-- `useWalletProvider`
-- `useXService`, `useXServices`
-- `useEnabledChains`
-- `useEvmSwitchChain`
-- `useXSignMessage`
-
-### Abstract classes (advanced — extend only when implementing a new chain)
-
-| Symbol | Kind | Source |
-|---|---|---|
-| `XService` | abstract class | `core/XService` |
-| `XConnector` | abstract class | `core/XConnector` |
-
-### Imperative actions
-
-| Symbol | Kind | Source |
-|---|---|---|
-| `getXChainType` | function | `actions/getXChainType` |
-| `getXService` | function | `actions/getXService` |
-
-### Utilities
-
-| Symbol | Notes |
-|---|---|
-| `sortConnectors` | Stable-sort connectors by `preferred[]` then install state. See [`connectors.md`](./connectors.md). |
-| `getEntryDefaults`, `getRpcUrl`, `resolveEvmDefaults` | Read defaults / RPC URL out of `SodaxWalletConfig` (advanced — for custom Hydrator-like code). |
-| `isNativeToken`, `getWagmiChainId` | Small helpers — native-token check and `ChainKey` → wagmi numeric chain id. |
-
-### Public interfaces
-
-| Symbol | Kind | Source |
-|---|---|---|
-| `IXService` | interface | `types/interfaces` |
-| `IXConnector` | interface | `types/interfaces` |
-| `IWalletProvider` | re-export from `@sodax/types` | `types/index` |
-
-### Account / connection types
-
-| Symbol | Kind |
-|---|---|
-| `XAccount` | type |
-| `XConnection` | type |
-
-### Config types
-
-Top-level:
-
-| Symbol | Kind |
-|---|---|
-| `SodaxWalletConfig` | type |
-| `ChainTypeConfig<T>` | generic type |
-| `ChainEntry<K>` | generic type |
-| `ChainMeta` | type |
-| `ChainTypeOf<K>` | generic type |
-| `WalletDefaultsByKey<K>` | generic type |
-
-Per-chain aliases follow two naming patterns — one alias per chain family (9 each):
-
-- `<Chain>TypeConfig` — per-slot config (e.g. `EvmTypeConfig`, `SolanaTypeConfig`)
-- `<Chain>ChainEntry` — per-chain-key entry (e.g. `EvmChainEntry`, `BitcoinChainEntry`)
-
-Replace `<Chain>` with `Evm | Solana | Sui | Bitcoin | Stellar | Injective | Icon | Near | Stacks`. Most consumers can derive these from `ChainTypeConfig<T>` / `ChainEntry<K>` instead of importing the per-chain alias directly.
-
-Adapter-field types (only chains with React adapters):
-
-| Symbol | Kind |
-|---|---|
-| `EvmAdapterFields` | type |
-| `SolanaAdapterFields` | type |
-| `SuiAdapterFields` | type |
-
-### Hook option / result types
-
-Every hook also exports its options / result types alongside it. Naming pattern is `Use<Name>Options`, `Use<Name>Result` (or `Use<Name>Return`), and any inline value types in `PascalCase` (e.g. `ChainGroup`, `ConnectedChain`, `WalletModalState`, `ConnectionStatus`). See [`hooks.md`](./hooks.md) for the signature each pair belongs to.
-
----
-
-## Sub-path exports — `import { X } from '@sodax/wallet-sdk-react/xchains/<chain>'`
-
-Concrete chain classes live behind sub-paths. Default to barrel imports; opt into these only when you need `instanceof`, want to extend a class, or are wiring a custom connector list via `ChainTypeConfig.connectors`.
-
-### Default pattern (most chains)
-
-`/xchains/{evm, icon, injective, near, solana, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, etc. Icon also exports `IconHanaXConnector` (the connector for the Hana wallet).
-
-```ts
-import { EvmXService, EvmXConnector } from '@sodax/wallet-sdk-react/xchains/evm';
-import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
-```
-
-### Chains with extra exports
-
-| Sub-path | Beyond `XService`/`XConnector` |
-|---|---|
-| `/xchains/bitcoin` | `XverseXConnector`, `UnisatXConnector`, `OKXXConnector` (3 wallet connectors), hook `useBitcoinXConnectors`, type `BtcWalletAddressType` |
-| `/xchains/evm` | `createWagmiConfig` (function — also exported as alias `createWagmi`) |
-| `/xchains/icon` | `CHAIN_INFO` (value), `SupportedChainId` (enum) |
-| `/xchains/stacks` | `STACKS_PROVIDERS` (value), hook `useStacksXConnectors`, type `StacksProviderConfig` |
-
-### Special case
-
-| Sub-path | Notes |
-|---|---|
-| `/xchains/stellar` | **No concrete classes re-exported.** Stellar uses `@creit.tech/stellar-wallets-kit` directly via an `XConnector` registered through the chain registry — no public class to `instanceof`-check. |
-
-If unsure what a sub-path exports, check the published `dist/`:
-
-```bash
-grep -E '^export' node_modules/@sodax/wallet-sdk-react/dist/xchains/<chain>/index.d.ts
-```
-
----
-
-## Peer dependencies (consumer must install)
-
-| Package | Version |
-|---|---|
-| `react` | `>= 19` |
-| `@tanstack/react-query` | `5.x` |
-
-`@tanstack/react-query` is required at runtime — `<QueryClientProvider>` must wrap `<SodaxWalletProvider>`. v1 mounted one internally; v2 does not.
-
----
-
-## Not exported (deliberately internal)
-
-These exist in the source but are **not** part of the public API. Do not import from `@sodax/wallet-sdk-react/dist/...` to reach them.
-
-- `useEthereumChainId` — read EVM chain id via wagmi's `useAccount().chainId` instead.
-- `useInitChainServices` — used by `<SodaxWalletProvider>` only.
-- `useXWalletStore` — Zustand store hook. Public hooks are the supported surface; if you need store access, file an issue describing the use case.
-
----
-
-## What the v2 barrel does NOT re-export (vs v1)
-
-For migration context only — these were on v1's barrel:
-
-- All concrete `XService` / `XConnector` classes (now sub-path imports)
-- `useXBalances` (moved to `@sodax/dapp-kit` with a new signature — see `migration/breaking-changes.md` § 10)
-- `XWagmiProviders` (renamed to `SodaxWalletProvider`)
-- `useXWagmiStore` (the store hook — v2 doesn't export the store hook under any name; use public hooks like `useXServices` / `useXConnections` instead)
-
-See [`../../migration/reference/imports.md`](../../migration/reference/imports.md) for the full v1→v2 import map.

package/ai-exported/integration/reference/chain-support.md

@@ -1,78 +0,0 @@
-# Reference: Chain Support
-
-Chains supported by `@sodax/wallet-sdk-react` v2 — their `ChainType` family and per-slot config shape. Use this when picking which slots to include in `walletConfig`.
-
----
-
-## Chain families (`ChainType`)
-
-9 chain families. Each is a top-level slot on `SodaxWalletConfig`:
-
-| ChainType | Networks (examples) | React adapter mounted |
-|---|---|---|
-| `EVM` | Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia | wagmi |
-| `SOLANA` | Solana mainnet | `@solana/wallet-adapter-react` |
-| `SUI` | Sui mainnet/testnet | `@mysten/dapp-kit` |
-| `BITCOIN` | Bitcoin mainnet | (none — direct extension probes) |
-| `STELLAR` | Stellar mainnet | (none) |
-| `ICON` | ICON mainnet | (none) |
-| `INJECTIVE` | Injective mainnet | (none) |
-| `NEAR` | NEAR mainnet | (none) |
-| `STACKS` | Stacks mainnet | (none) |
-
-EVM is the only family with multiple networks under one connection — wagmi maintains a single connection that spans every configured EVM network. See [`../architecture.md`](../architecture.md) § "EVM is one connection".
-
----
-
-## Per-slot config shape
-
-| Slot | Config fields | Notes |
-|---|---|---|
-| `EVM` | `ssr?, walletConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
-| `SOLANA` | `autoConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
-| `SUI` | `network?, connectors?, chains?` | `network: 'mainnet' \| 'testnet'` |
-| `BITCOIN` | extends `BitcoinRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
-| `STELLAR` | extends `StellarRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
-| `INJECTIVE` | extends `InjectiveRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
-| `ICON` | `connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
-| `NEAR` | `connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
-| `STACKS` | preset name (string) **or** `StacksNetworkLike & { defaults?, connectors? }` | `'mainnet'` / `'testnet'` preset accepted |
-
-The single source of truth for the per-chain shape is `ChainMeta` in `src/types/config.ts` — `SodaxWalletConfig`, `ChainEntry<K>`, `WalletDefaultsByKey<K>` derive from it.
-
----
-
-## ChainKey constants
-
-`ChainKey` is the chain-id enum exported from `@sodax/types`. Use it in `walletConfig.<SLOT>.chains[<ChainKey>]` and in hooks that take `xChainId`.
-
-```ts
-import { ChainKeys } from '@sodax/types';
-
-ChainKeys.SONIC_MAINNET;       // EVM
-ChainKeys.ETHEREUM_MAINNET;    // EVM
-ChainKeys.SOLANA_MAINNET;      // SOLANA
-ChainKeys.BITCOIN_MAINNET;     // BITCOIN
-// …etc
-```
-
-Naming pattern: `<NETWORK>_MAINNET`. EVM has 12 entries (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia); the other 8 families each have one. Inspect `@sodax/types` for the authoritative list.
-
----
-
-## Slot opt-in behavior
-
-- **Omit a slot** to skip mounting that adapter entirely. The chain won't appear in `useXConnectors`, `useChainGroups`, or `useEnabledChains`.
-- **Pass `{}`** to mount with SDK defaults. Useful for chains where you don't need to override RPC or connectors.
-- **Provide a partial config** (`{ chains: {...} }`) to override only what you need; everything else uses defaults.
-
-```ts
-const walletConfig: SodaxWalletConfig = {
-  EVM: { ssr: true, chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: '...' } } }, // explicit
-  BITCOIN: {},                                                                    // defaults
-  SOLANA: { autoConnect: false, chains: { [ChainKeys.SOLANA_MAINNET]: {} } },     // partial
-  // STELLAR not included → not mounted
-};
-```
-
-For per-hook fallback behavior when a slot is omitted, see [`hooks.md`](./hooks.md) § "Behavior when the chain slot is not in walletConfig".

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.