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

package/docs/EVM_SWITCH_CHAIN.md

@@ -0,0 +1,161 @@
+# EVM Switch Chain
+
+A single wagmi connection covers **every configured EVM network** (Sonic, Ethereum, Arbitrum, Base, BSC, Optimism, Polygon, Avalanche, HyperEVM, Lightlink, Redbelly, Kaia). The user picks a wallet once; switching the **active network** within that wallet is a separate concern handled by `useEvmSwitchChain`.
+
+The hook also covers Injective's MetaMask wallet path — when the user connected Injective via MetaMask, the underlying ethereum chain id must be Ethereum mainnet (chain id `1`). `useEvmSwitchChain` detects the mismatch and exposes a switch action.
+
+Source: [`useEvmSwitchChain.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/hooks/useEvmSwitchChain.ts), [`useEthereumChainId.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/hooks/useEthereumChainId.ts).
+
+## Table of contents
+
+1. [Why this exists](#why-this-exists)
+2. [`useEvmSwitchChain` API](#useevmswitchchain-api)
+3. [Standard EVM switch flow](#standard-evm-switch-flow)
+4. [Injective MetaMask special case](#injective-metamask-special-case)
+5. [`useEthereumChainId` — read the wagmi/MetaMask chain id](#useethereumchainid--read-the-wagmimetamask-chain-id)
+6. [Safe to call when EVM is disabled](#safe-to-call-when-evm-is-disabled)
+
+---
+
+## 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.
+
+---
+
+## `useEvmSwitchChain` 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
+import { useEvmSwitchChain, useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+function BscSwapButton() {
+  const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
+    xChainId: ChainKeys.BSC_MAINNET,
+  });
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+
+  if (!walletProvider) {
+    return <ConnectCta />;
+  }
+
+  if (isWrongChain) {
+    return <button onClick={handleSwitchChain}>Switch to BSC</button>;
+  }
+
+  return <button onClick={() => doSwap(walletProvider)}>Swap</button>;
+}
+```
+
+Internally:
+- Reads `chainId` from wagmi's `useAccount()`.
+- Compares against `baseChainInfo[xChainId].chainId` (numeric EVM chain id resolved from the `SpokeChainKey`).
+- `handleSwitchChain` calls wagmi's `useSwitchChain().switchChain({ chainId })`.
+
+`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).
+
+---
+
+## 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.
+
+`useEvmSwitchChain({ xChainId: ChainKeys.INJECTIVE_MAINNET })` detects the mismatch:
+
+```typescript
+isWrongChain =
+  xChainType === 'INJECTIVE' &&
+  injectiveXService?.walletStrategy.getWallet() === Wallet.Metamask &&
+  ethereumChainId !== 1; // mainnet.id from viem/chains
+```
+
+`handleSwitchChain` for Injective calls `wallet_switchEthereumChain` directly on `window.ethereum` (not wagmi's `switchChain`, which only knows EVM chains registered in the wagmi config). It uses an EIP-1193-compliant promise + event listener pair:
+
+```typescript
+await Promise.race([
+  metamask.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: '0x1' }] }),
+  new Promise(resolve => {
+    const handler = (chainId: string) => {
+      if (chainId === '0x1') {
+        metamask.removeListener('chainChanged', handler);
+        resolve();
+      }
+    };
+    metamask.on('chainChanged', handler);
+  }),
+]);
+```
+
+The promise/event race covers both wallet behaviors — some wallets resolve `wallet_switchEthereumChain` only after the user confirms; others resolve immediately and emit `chainChanged` afterwards.
+
+Keplr and Leap on Injective don't have this constraint — `isWrongChain` is `false` for those wallets regardless of network state.
+
+---
+
+## `useEthereumChainId` — read the wagmi/MetaMask chain id
+
+A read-only helper that returns the **active Ethereum chain id** when MetaMask is the Injective wallet, otherwise `null`. Used internally by `useEvmSwitchChain`; expose-able for custom UIs that need to display the network state independently.
+
+```typescript
+import useEthereumChainId from '@sodax/wallet-sdk-react/hooks/useEthereumChainId';
+
+const ethereumChainId = useEthereumChainId();
+// number (e.g. 1 for mainnet) or null
+```
+
+It subscribes to MetaMask's `onChainIdChanged` event so the value stays fresh when the user switches networks outside the dApp. For non-MetaMask Injective wallets (Keplr, Leap) and non-Injective use cases, it returns `null`.
+
+This hook is rarely needed in app code — `useEvmSwitchChain` already consumes it internally.
+
+---
+
+## Safe to call when EVM is disabled
+
+`useEvmSwitchChain` checks `useIsChainEnabled('EVM')` and returns a no-op result `{ isWrongChain: false, handleSwitchChain: () => {} }` when the EVM slot isn't mounted in `SodaxWalletProvider` config:
+
+```typescript
+const evmEnabled = useIsChainEnabled('EVM');
+if (!evmEnabled) return EVM_DISABLED_RESULT;
+```
+
+This is **important** — calling wagmi's `useAccount` / `useSwitchChain` 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.
+
+The conditional hook call (early-return before `useEvmSwitchChainInner` runs) is technically a Rules-of-Hooks violation but **safe**: `evmEnabled` is derived from config, which is immutable after `SodaxWalletProvider` mounts (the config is captured once via `useRef`). The branch never changes during the component's lifetime.
+
+---
+
+## Related docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — opt in / out of EVM
+- [Wallet Provider Bridge](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_PROVIDER_BRIDGE.md) — `useWalletProvider` returns the same provider for all EVM chain ids
+- [Chain Detection](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md) — EVM collapses to one row in `useChainGroups` / `useConnectedChains` for the same reason
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — connect once; chain switching is a separate UX
+- [wagmi `useSwitchChain` docs](https://wagmi.sh/react/api/hooks/useSwitchChain)
+- [EIP-3326 — `wallet_switchEthereumChain`](https://eips.ethereum.org/EIPS/eip-3326)

package/docs/SIGN_MESSAGE.md

@@ -0,0 +1,213 @@
+# Sign Message
+
+`useXSignMessage` is a single React Query mutation that delegates message signing to the connected wallet's `ChainActions.signMessage` implementation. The signature shape and encoding rules differ per chain — Bitcoin in particular auto-selects between BIP-322 and ECDSA based on the connected address type.
+
+The hook source is [`useXSignMessage.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/hooks/useXSignMessage.ts); the per-chain wiring lives in [`chainRegistry.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/chainRegistry.ts) and the provider-managed `<Chain>Actions.tsx` files.
+
+## Table of contents
+
+1. [Hook API](#hook-api)
+2. [Per-chain support matrix](#per-chain-support-matrix)
+3. [Bitcoin — BIP-322 vs ECDSA auto-detect](#bitcoin--bip-322-vs-ecdsa-auto-detect)
+4. [ICON not supported](#icon-not-supported)
+5. [Provider-managed chains (EVM / Solana / Sui)](#provider-managed-chains-evm--solana--sui)
+6. [Stellar / Injective / NEAR / Stacks](#stellar--injective--near--stacks)
+7. [Error handling](#error-handling)
+
+---
+
+## Hook API
+
+```typescript
+import { useXSignMessage } from '@sodax/wallet-sdk-react';
+
+const sign = useXSignMessage();
+
+const signature = await sign.mutateAsync({
+  xChainType: 'EVM',
+  message: 'Sign in to MyDApp\nNonce: abc123',
+});
+// signature: `0x${string}` | Uint8Array | string | undefined
+```
+
+Variables:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `xChainType` | `ChainType` | Which chain to sign with (`'EVM'`, `'BITCOIN'`, …) |
+| `message` | `string` | Plain UTF-8; per-chain wrappers handle encoding |
+
+Return type is the discriminated union `\`0x${string}\` | Uint8Array | string | undefined` because each chain returns its native signature shape (hex for EVM, base64 for Stellar, base58 for Solana, etc.). Cast or branch on `xChainType` when consuming.
+
+`undefined` is returned (not thrown) when the chain doesn't implement `signMessage` — currently only ICON. A one-time `console.warn` accompanies the `undefined`.
+
+---
+
+## Per-chain support matrix
+
+| Chain | Implementation | Signature shape |
+|-------|----------------|-----------------|
+| EVM | `signMessageAsync` from wagmi → personal_sign | `\`0x${string}\`` |
+| Solana | `signMessage` from `@solana/wallet-adapter` | `Uint8Array` |
+| Sui | `signPersonalMessage` from `@mysten/dapp-kit` | `string` (base64 signature + bytes) |
+| Bitcoin | Auto-detect: BIP-322 (P2WPKH/P2TR) or ECDSA (P2SH/P2PKH) | `string` |
+| Stellar | `walletsKit.signMessage` from `@creit.tech/stellar-wallets-kit` | `string` (base64) |
+| Injective | `walletStrategy.signArbitrary` from `@injectivelabs/wallet-base` | `string` |
+| NEAR | NEAR connector's `signMessage` | `string` |
+| Stacks | `signMessage` from `@stacks/connect` | `string` |
+| **ICON** | **Not supported** — Hana wallet does not expose a signing API | `undefined` |
+
+---
+
+## Bitcoin — BIP-322 vs ECDSA auto-detect
+
+Bitcoin's signing flow inspects the connected address and picks the right method automatically:
+
+| Address type | Signing method | Connectors that support it |
+|--------------|----------------|----------------------------|
+| P2WPKH (native segwit, `bc1q…`) | BIP-322 | Unisat, Xverse, OKX |
+| P2TR (taproot, `bc1p…`) | BIP-322 | Unisat, Xverse, OKX |
+| P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX |
+| P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX |
+
+The dispatch happens inside [`chainRegistry.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/chainRegistry.ts) using `detectBitcoinAddressType(address)` + the `hasSignBip322` / `hasSignEcdsa` type guards from [`bitcoinSignGuards.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/xchains/bitcoin/bitcoinSignGuards.ts):
+
+```typescript
+switch (addressType) {
+  case 'P2WPKH':
+  case 'P2TR':
+    if (!hasSignBip322(connector)) {
+      throw new Error(`${connector.id} does not support BIP-322 signing`);
+    }
+    return connector.signBip322Message(message);
+
+  case 'P2SH':
+  case 'P2PKH':
+    if (!hasSignEcdsa(connector)) {
+      throw new Error(`${connector.id} does not support ECDSA signing`);
+    }
+    return connector.signEcdsaMessage(message);
+}
+```
+
+The same logic mirrors the SDK's `BitcoinSpokeProvider.authenticateWithWallet` — the React layer doesn't reinvent the dispatch. If a custom connector implements only one of the two methods, calling `signMessage` from a wrongly-typed address surfaces the error inline.
+
+**Why BIP-322 for segwit/taproot?** Legacy ECDSA message signing (`signEcdsaMessage`) doesn't have a standard for non-P2PKH addresses. BIP-322 added a generic verification framework that works across address types — most modern Bitcoin wallets implement it for segwit/taproot specifically.
+
+---
+
+## ICON not supported
+
+Hana wallet on ICON exposes account / transaction APIs but no general-purpose `signMessage` endpoint. `useXSignMessage({ xChainType: 'ICON' })` returns `undefined` and logs:
+
+```
+[useXSignMessage] signMessage not supported for chain "ICON"
+```
+
+If you need a signature on ICON for SIWE-style auth, fall back to a transaction-based proof or skip ICON in your auth flow. The chainRegistry comment explicitly documents this: `// ICON: signMessage not implemented — Hana wallet does not expose a signing API.`
+
+---
+
+## Provider-managed chains (EVM / Solana / Sui)
+
+For EVM, Solana, and Sui, `signMessage` is registered by the chain's `<Chain>Actions.tsx` component using a **ref to the native SDK hook**. The ref is updated on each render so the registered closure always calls the latest function:
+
+```typescript
+// EvmActions.tsx — pattern shared with SolanaActions, SuiActions
+const { signMessageAsync } = useSignMessage(); // wagmi
+const signMessageRef = useRef(signMessageAsync);
+useEffect(() => { signMessageRef.current = signMessageAsync; }, [signMessageAsync]);
+
+useEffect(() => {
+  registerActions({
+    signMessage: async (message) => signMessageRef.current({ message }),
+  });
+}, []);
+```
+
+This pattern keeps the registered action stable (registered once on mount) while still calling the current native SDK function — important because re-registering on every render would trigger downstream re-subscribes.
+
+Consumer perspective is the same — call `useXSignMessage` and let the layer handle the routing.
+
+---
+
+## Stellar / Injective / NEAR / Stacks
+
+Non-provider chains register `signMessage` directly in `chainRegistry`:
+
+```typescript
+// Stellar
+signMessage: async (message: string) => {
+  const res = await service.walletsKit.signMessage(message);
+  return res.signedMessage;
+}
+
+// Injective — auto-converts injective1… address to 0x… for MetaMask wallet
+signMessage: async (message: string) => {
+  const ethereumAddress = getEthereumAddress(address);
+  return await service.walletStrategy.signArbitrary(
+    service.walletStrategy.getWallet() === Wallet.Metamask ? ethereumAddress : address,
+    message,
+  );
+}
+```
+
+Each delegates to the chain's native signing API. Errors propagate as-is — you'll see `Wallet.signMessage rejected by user`, `Address mismatch`, etc., depending on the chain's SDK.
+
+---
+
+## Error handling
+
+```tsx
+import { useXSignMessage } from '@sodax/wallet-sdk-react';
+
+function SignButton() {
+  const sign = useXSignMessage();
+
+  const handleSign = async () => {
+    try {
+      const signature = await sign.mutateAsync({
+        xChainType: 'EVM',
+        message: 'Sign in',
+      });
+      if (!signature) {
+        // ICON or other unsupported chain
+        return;
+      }
+      submitSignature(signature);
+    } catch (error) {
+      // User rejection, wallet disconnect mid-sign, address mismatch, etc.
+      console.error('sign failed:', error);
+    }
+  };
+
+  return (
+    <button onClick={handleSign} disabled={sign.isPending}>
+      {sign.isPending ? 'Waiting for wallet…' : 'Sign'}
+    </button>
+  );
+}
+```
+
+Common error messages by chain:
+
+| Chain | Typical error |
+|-------|---------------|
+| EVM | `User rejected the request` (MetaMask), `User denied message signature` (Rabby) |
+| Solana | `WalletSignMessageError: User rejected the request` |
+| Sui | `User rejected the signature request` |
+| Bitcoin | `<connector.id> does not support BIP-322 signing` (mismatch with address type), `User canceled the request` |
+| Stellar | `Stellar signature not found` |
+| Injective | `Injective signature not found`, `Injective address not found` |
+
+`mutation.error` reflects the latest failure; `mutation.isError` / `mutation.isPending` follow standard React Query semantics.
+
+---
+
+## Related docs
+
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — must connect a wallet before signing
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — chain must be enabled in config to dispatch
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — Bitcoin connector classes for `instanceof` checks
+- [SDK Wallet Providers Reference](https://github.com/icon-project/sodax-sdks/blob/main/packages/sdk/docs/WALLET_PROVIDERS.md) — Bitcoin's lower-level `signTransaction` / `signEcdsaMessage` / `signBip322Message` interface
+- [BIP-322 specification](https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki) — generic signed-message format for all Bitcoin address types

package/docs/SUB_PATH_EXPORTS.md

@@ -0,0 +1,246 @@
+# Sub-path Exports
+
+`@sodax/wallet-sdk-react` ships a **two-tier export surface**:
+
+- **Barrel** — `import { useXConnect, type IXConnector } from '@sodax/wallet-sdk-react'` exposes hooks, types, the abstract `XConnector` base, and `<SodaxWalletProvider>`.
+- **Sub-path** — `import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin'` exposes concrete connector / service classes for advanced use (`instanceof` checks, calling chain-specific methods).
+
+The split is deliberate: keeping concrete classes off the barrel prevents accidental coupling to internal implementations and lets the SDK refactor chain code without breaking consumers.
+
+This document covers the build-time plumbing that makes sub-paths work.
+
+## Table of contents
+
+1. [Why two tiers](#why-two-tiers)
+2. [What's exported where](#whats-exported-where)
+3. [`tsup` multi-entry build](#tsup-multi-entry-build)
+4. [`package.json` `exports` + `typesVersions`](#packagejson-exports--typesversions)
+5. [`instanceof` semantics across entry points](#instanceof-semantics-across-entry-points)
+6. [Common errors and fixes](#common-errors-and-fixes)
+
+---
+
+## Why two tiers
+
+Three reasons:
+
+**1. Coupling control.** A consumer that imports `EvmXConnector` from the barrel implicitly depends on a concrete class. Six months later when the SDK refactors how EVM connectors are constructed (e.g. moves from one connector class per wagmi connector to a polymorphic dispatcher), every consumer that did the deep dependency breaks. Forcing `instanceof` users to deep-import makes the dependency explicit and visible to the SDK author at refactor time.
+
+**2. Tree-shaking efficiency.** The barrel re-exports hooks and types only — small surface area, small bundle. Consumers who never touch `XverseXConnector` don't pay its cost. Sub-path imports pull only the chain they reference.
+
+**3. AI agent / IDE intent signal.** Code reviewers and autocomplete see at a glance whether a file is using "everyday hooks" (barrel) or "chain-specific advanced features" (deep import). The latter typically warrants a closer look.
+
+---
+
+## What's exported where
+
+### Barrel (`@sodax/wallet-sdk-react`)
+
+Everything in `src/index.ts` — hooks, utils, types, interfaces, the `<SodaxWalletProvider>` component, and the abstract `XConnector` / `XService` base classes:
+
+```typescript
+// ✅ Barrel imports
+import {
+  SodaxWalletProvider,
+  useXConnect,
+  useXAccount,
+  useWalletProvider,
+  useWalletModal,
+  useBatchConnect,
+  XConnector,                       // abstract base — for custom connectors
+  type IXConnector,                 // interface
+  type IXService,                   // interface
+  type SodaxWalletConfig,
+  type XAccount,
+  type XConnection,
+  sortConnectors,
+} from '@sodax/wallet-sdk-react';
+```
+
+### Sub-paths (`@sodax/wallet-sdk-react/xchains/<chain>`)
+
+Concrete classes — one barrel per chain folder:
+
+```typescript
+// ✅ Sub-path imports
+import { EvmXConnector, EvmXService, createWagmiConfig } from '@sodax/wallet-sdk-react/xchains/evm';
+import { SolanaXConnector, SolanaXService } from '@sodax/wallet-sdk-react/xchains/solana';
+import { SuiXConnector, SuiXService } from '@sodax/wallet-sdk-react/xchains/sui';
+import {
+  BitcoinXService,
+  BitcoinXConnector,    // abstract
+  UnisatXConnector,     // concrete
+  XverseXConnector,     // concrete
+  OKXXConnector,        // concrete
+  useBitcoinXConnectors,
+  type BtcWalletAddressType,
+} from '@sodax/wallet-sdk-react/xchains/bitcoin';
+import { StellarXService, StellarWalletsKitXConnector } from '@sodax/wallet-sdk-react/xchains/stellar';
+import { InjectiveXConnector, InjectiveXService } from '@sodax/wallet-sdk-react/xchains/injective';
+import { IconXService, IconHanaXConnector, CHAIN_INFO, SupportedChainId } from '@sodax/wallet-sdk-react/xchains/icon';
+import { NearXConnector, NearXService } from '@sodax/wallet-sdk-react/xchains/near';
+import {
+  StacksXService,
+  StacksXConnector,
+  STACKS_PROVIDERS,
+  useStacksXConnectors,
+  type StacksProviderConfig,
+} from '@sodax/wallet-sdk-react/xchains/stacks';
+```
+
+For the full list, see [`CONNECTORS.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md#sub-path-imports--concrete-classes).
+
+### Concrete chain symbols live only in sub-paths
+
+Concrete connector / service classes — and their named types — are not re-exported from the barrel. Even a `type`-only reference must come from the sub-path; `import type { XverseXConnector } from '@sodax/wallet-sdk-react'` fails with TS2305 / TS2724.
+
+```typescript
+// ✅ Sub-path — works for both `type` and runtime use
+import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+import type { BtcWalletAddressType } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+```
+
+If a cross-cutting type genuinely needs to be available from the barrel (typing a function param, narrowing a return type), add it as `export type { ... }` in `src/index.ts` — but the default is sub-path-only.
+
+---
+
+## `tsup` multi-entry build
+
+[`tsup.config.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/tsup.config.ts) declares one entry per public boundary:
+
+```typescript
+const sharedConfig = {
+  entry: [
+    'src/index.ts',
+    'src/xchains/*/index.ts',     // glob — picks up new chain folders automatically
+    'src/xchains/*/index.tsx',
+  ],
+  outDir: 'dist',
+  external: ['react', 'react-dom', '@tanstack/react-query'],
+  // ...
+};
+
+export default defineConfig([
+  { ...sharedConfig, format: ['esm'], splitting: true,  outExtension: () => ({ js: '.mjs' }) },
+  { ...sharedConfig, format: ['cjs'], splitting: false, outExtension: () => ({ js: '.cjs' }) },
+]);
+```
+
+Two production builds:
+
+| Build | `splitting` | Output |
+|-------|-------------|--------|
+| ESM | `true` | `.mjs` files share class instances across entry points |
+| CJS | `false` | One `.cjs` per entry, no chunk-sharing |
+
+**Why ESM splitting matters** — without it, the same class would be defined twice (once in `dist/index.mjs`, once in `dist/xchains/bitcoin/index.mjs`), and `instanceof XverseXConnector` would return `false` if the connector was constructed in one entry and tested in another. With splitting on, both entries import the class from a shared chunk, preserving identity.
+
+### Adding a new chain
+
+The glob `src/xchains/*/index.ts` is **auto-discovering** — creating `src/xchains/aptos/index.ts` automatically produces `dist/xchains/aptos/index.{mjs,cjs,d.ts}` on next build. No `tsup.config.ts` edit required. See [`ADDING_A_NEW_CHAIN.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md#step-4--xchainschainindexts-barrel-for-sub-path-export).
+
+---
+
+## `package.json` `exports` + `typesVersions`
+
+Two fields work together to support modern bundlers and legacy `moduleResolution: "node"`:
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./xchains/*": {
+      "types": "./dist/xchains/*/index.d.ts",
+      "import": "./dist/xchains/*/index.mjs",
+      "require": "./dist/xchains/*/index.cjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "xchains/*": ["./dist/xchains/*/index.d.ts"]
+    }
+  }
+}
+```
+
+| Field | Read by | Purpose |
+|-------|---------|---------|
+| `exports['.']` | All bundlers (Vite, Webpack, esbuild, Next.js), modern Node | Resolves `@sodax/wallet-sdk-react` to the right artifact per condition (ESM/CJS/types) |
+| `exports['./xchains/*']` | Same | Wildcard maps `@sodax/wallet-sdk-react/xchains/<chain>` to the matching `dist/xchains/<chain>/index.<ext>` |
+| `typesVersions['xchains/*']` | TypeScript with `moduleResolution: "node"` (legacy) | Fallback for TS configs that don't honor the `exports` field's `types` condition |
+
+Modern projects with `"moduleResolution": "bundler"` or `"node16"` only need `exports`. `typesVersions` ensures sub-path types resolve for older configs that still see `@sodax/wallet-sdk-react/xchains/bitcoin` as a path traversal.
+
+If a consumer reports "Cannot find module" for sub-paths in TypeScript, check their `tsconfig.json` `moduleResolution` setting first.
+
+---
+
+## `instanceof` semantics across entry points
+
+Class identity is preserved across barrel and sub-path entries **only in ESM**:
+
+```typescript
+// ESM — works
+import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+const connectors = useXConnectors({ xChainType: 'BITCOIN' });
+const xverse = connectors.find(c => c instanceof XverseXConnector); // ✅ may be true
+
+// CJS — broken (in theory)
+// require('@sodax/wallet-sdk-react') and require('@sodax/wallet-sdk-react/xchains/bitcoin')
+// load XverseXConnector from separate compiled files; instanceof returns false.
+```
+
+In practice this **doesn't break browser consumers** — Vite, Next.js, esbuild, Webpack all resolve ESM by default. CJS-only Node.js scripts that mix barrel and sub-path imports would hit the issue, but those scripts typically don't need `instanceof XverseXConnector` (they wouldn't run in a browser-extension context).
+
+If you're a Node.js consumer running CJS and need cross-entry `instanceof`, either:
+- Switch your project to ESM (`"type": "module"` in your `package.json`), or
+- Stick to **one** entry point — only the sub-path or only the barrel, never both for the same class.
+
+The `tsup.config.ts` comment documents this trade-off:
+
+```typescript
+// CJS does not support code splitting — instanceof across barrel and sub-path
+// entries will fail. In practice this is not an issue because browser apps (Vite,
+// Next.js) resolve ESM, and Node.js scripts don't use sub-path instanceof checks.
+```
+
+---
+
+## Common errors and fixes
+
+### `Cannot find module '@sodax/wallet-sdk-react/xchains/bitcoin'`
+
+- **TypeScript**: check `moduleResolution` is `"bundler"`, `"node16"`, or `"nodenext"`. Older `"node"` setting needs `typesVersions` (already provided in this package).
+- **Bundler**: check `package.json` is being read — some monorepos with custom resolvers ignore `exports`. Verify by adding a console.log of `require.resolve('@sodax/wallet-sdk-react/xchains/bitcoin')`.
+
+### `XverseXConnector is not exported from '@sodax/wallet-sdk-react'`
+
+Expected — concrete connector classes are NOT re-exported from the barrel. Switch to:
+
+```typescript
+import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
+```
+
+The error message can also appear if you tried `import type { XverseXConnector } from '@sodax/wallet-sdk-react'` and then used it as a runtime value — `export type` only covers type position.
+
+### `instanceof XverseXConnector` returns `false` for a connector that should match
+
+Likely a CJS / dual-import issue. Verify that the connector instance came from the same entry point you're testing against. Switching to ESM resolution fixes this for all bundlers.
+
+### `Module not found: '@sodax/wallet-sdk-react/xchains/aptos'` after adding a new chain
+
+Run `pnpm build:packages` — `dist/xchains/aptos/` only exists after a build. The `exports` wildcard resolves at runtime, so consumer apps need the freshly-built artifact.
+
+---
+
+## Related docs
+
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — full sub-path map per chain
+- [Adding a New Chain](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ADDING_A_NEW_CHAIN.md) — Step 4 covers the barrel that powers a new sub-path
+- [Architecture](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/ARCHITECTURE.md) — store-first hooks consume only barrel exports
+- [tsup splitting docs](https://tsup.egoist.dev/#code-splitting) — official docs on the ESM splitting behavior
+- [Node.js subpath exports](https://nodejs.org/api/packages.html#subpath-exports) — the spec behind `package.json` `exports`