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

package/ai-exported/integration/recipes/sub-path-imports.md

@@ -1,95 +0,0 @@
-# Recipe: Sub-Path Imports (Advanced)
-
-When and how to use deep imports from `@sodax/wallet-sdk-react/xchains/<chain>`. Default to barrel imports — reach for sub-paths only when you need a concrete class for `instanceof` checks, custom connector lists, or chain-specific utilities not exposed through the public hooks.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## When you need it
-
-The package barrel exports hooks, types, abstractions, and `SodaxWalletProvider`. Concrete chain-specific classes (`XverseXConnector`, `EvmXService`, `IconHanaXConnector`, …) live behind sub-paths to keep the barrel small. Reach for a sub-path import in three cases:
-
-| Use case | Example |
-|---|---|
-| Runtime type check on a connector | `if (connector instanceof XverseXConnector) { … }` |
-| Override the default connector list for a chain | Pass `connectors: [new MyConnector()]` to `ChainTypeConfig` |
-| Call a chain-specific method not on `IXConnector` | `xverseConnector.setAddressPurpose('payment')` |
-
-If none of the above applies, **stick with barrel imports** — sub-paths are not part of the typical surface.
-
----
-
-## `instanceof` check (most common)
-
-Tag a connector by class to call methods specific to that wallet:
-
-```tsx
-import { useXConnectors } from '@sodax/wallet-sdk-react';
-import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
-
-function BitcoinConnectButton() {
-  const connectors = useXConnectors({ xChainType: 'BITCOIN' });
-
-  return (
-    <>
-      {connectors.map((connector) => (
-        <button
-          type="button"
-          key={connector.id}
-          onClick={async () => {
-            // Pre-configure Xverse before connect
-            if (connector instanceof XverseXConnector) {
-              connector.setAddressPurpose('payment');
-            }
-            await connector.connect();
-          }}
-        >
-          {connector.name}
-        </button>
-      ))}
-    </>
-  );
-}
-```
-
-The barrel-typed `IXConnector` exposes only `connect()` / `disconnect()` / metadata fields. To reach `setAddressPurpose` (or any class-specific method), narrow via `instanceof` after a sub-path import.
-
----
-
-## Custom connector list
-
-Override the default connectors a chain ships with by passing `connectors` on the `ChainTypeConfig`:
-
-```tsx
-import type { SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-import { XverseXConnector, UnisatXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
-
-const walletConfig: SodaxWalletConfig = {
-  BITCOIN: {
-    // Only mount Xverse + Unisat — drop the OKX connector that ships by default.
-    connectors: [new XverseXConnector(), new UnisatXConnector()],
-  },
-};
-```
-
-Use sparingly — the default lists are tuned per chain. Override only when you need to remove a connector you do not support, or add a custom one you implemented yourself.
-
----
-
-## Available sub-paths
-
-For the per-chain symbol list, see [`../reference/api-surface.md`](../reference/api-surface.md) § "Sub-path exports". That table is the single source of truth — `scripts/check-ai-exported.sh` validates it stays in sync with `src/xchains/`.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Sub-path imports must resolve to a real chain folder
-grep -rnE "from '@sodax/wallet-sdk-react/xchains/[a-z]+'" <user-src>
-# Each match's <chain> must be one of: bitcoin, evm, icon, injective, near, solana, stacks, stellar, sui
-```

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/{bitcoin, evm, icon, injective, near, solana, stacks, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, `BitcoinXService`/`BitcoinXConnector`, `StacksXService`/`StacksXConnector`, 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".