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

package/ai-exported/integration/architecture.md

@@ -1,181 +0,0 @@
-# Architecture — Mental Model
-
-This file explains **why** `@sodax/wallet-sdk-react` is shaped the way it is. Read it once before applying recipes — knowing the model lets you handle ambiguous user code without inventing migrations.
-
-If you are looking for "how do I do X", go to [`recipes/`](./recipes/). This file is purely conceptual.
-
----
-
-## The shape of the package
-
-`@sodax/wallet-sdk-react` is a **uniform React layer over heterogeneous chain wallet libraries**. Each chain family ships a different React adapter (wagmi, `@solana/wallet-adapter-react`, `@mysten/dapp-kit`) or no React adapter at all (Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). The package wraps all nine families behind one set of hooks so consumer code does not branch on chain family.
-
-Two abstractions make this work:
-
-- **`XConnector`** — represents a *wallet* on a *chain family* (e.g. MetaMask on EVM, Phantom on Solana, Xverse on Bitcoin). Knows how to `connect()`, `disconnect()`, expose `id` / `name` / `icon` / `isInstalled`.
-- **`XService`** — represents a *chain family* (one per `ChainType`). Holds the list of available connectors, the current active connection, and exposes a chain-family-specific `IXxxWalletProvider` once connected.
-
-Hooks always operate on `XService` / `XConnector` — never directly on a chain library's primitives. Consumers do not import `useAccount` from wagmi; they call `useXAccount({ xChainType: 'EVM' })` and get back a uniform `XAccount` shape.
-
----
-
-## The provider mount tree
-
-`<SodaxWalletProvider config={...}>` mounts only the chain-type slots present in `config`. The internal nesting order is fixed:
-
-```
-<WalletConfigProvider value={frozenConfig}>
-  <EvmProvider config={config.EVM}>           ← only if EVM slot present (mounts wagmi.WagmiProvider)
-    <SuiProvider config={config.SUI}>          ← only if SUI slot present (mounts dapp-kit providers)
-      <SolanaProvider config={config.SOLANA}>  ← only if SOLANA slot present (mounts solana-wallet-adapter)
-        {children}
-      </SolanaProvider>
-    </SuiProvider>
-  </EvmProvider>
-</WalletConfigProvider>
-```
-
-Three things to internalize:
-
-1. **Slot opt-in is real.** Omitting `config.SOLANA` means `@solana/wallet-adapter-react` is **not** in the React tree at all — zero runtime cost, smaller bundle. `useXConnectors({ xChainType: 'SOLANA' })` returns `[]` and logs a one-time warning. Apps that only use EVM should pass only `{ EVM: {...} }`.
-2. **Provider-managed vs registered chains.** EVM/Solana/Sui have native React adapters and need a provider tree node. Bitcoin/Stellar/ICON/Injective/NEAR/Stacks register their `XService` at mount time via `useInitChainServices` — no provider node, no React context for the underlying SDK.
-3. **`QueryClientProvider` must wrap `<SodaxWalletProvider>`.** v2 does *not* mount a `QueryClient` internally (v1 did). `useXConnect`, `useXSignMessage`, batch hooks all depend on React Query — without an outer `QueryClientProvider` they throw at runtime, not at type-check.
-
----
-
-## Config is captured once
-
-`<SodaxWalletProvider config>` freezes `config` with `useRef` on first render. Subsequent renders with a new reference have **no effect**. Reasons:
-
-- **Wagmi config-object identity matters.** wagmi reconnects if the config object identity changes; reactive configs caused reconnect storms in v1.
-- **Predictable startup.** Apps should compose chain config once at module scope, not derive it dynamically from props.
-
-To swap config at runtime, remount with a new `key`:
-
-```tsx
-<SodaxWalletProvider key={configVersion} config={walletConfig}>
-  {children}
-</SodaxWalletProvider>
-```
-
-This is the only supported way to change config — there is no `setConfig` API.
-
----
-
-## State: Zustand store + adapter sync
-
-The package keeps connection state in a Zustand store keyed by `ChainType`. The store hook **is not exported** — consumers read state through public hooks (`useXAccount`, `useXService`, `useWalletProvider`, …), each of which subscribes to the relevant slice internally. The shape below is informational only:
-
-```ts
-// internal shape — do NOT import
-{
-  xServices:     Partial<Record<ChainType, IXService>>,
-  xConnections:  Partial<Record<ChainType, XConnection>>,
-  // …plus internal mutations
-}
-```
-
-Two things matter to consumers:
-
-1. **Provider-managed chains sync state from the adapter.** EVM/Solana/Sui each have a `<Hydrator>` that watches its native adapter (wagmi `useAccount`, etc.) and writes the active connection into `xConnections`. Hooks read from the Zustand store, so they see one consistent view across all chains.
-2. **Persistence: `xwagmi-store` localStorage key, kept stable from v1.** Renaming would log out every existing user. Hydration runs lazily — the first render after refresh has `xConnections = {}` even if storage has data. Hooks expose this via `useConnectedChains().status === 'ready'` — gate UI on that to avoid hydration flicker on Next.js.
-
-You should **not** read the store directly. Use the public hooks. The store hook itself is not exported from v2 — see [`reference/api-surface.md`](./reference/api-surface.md) § "Not exported".
-
----
-
-## Wallet discovery (EIP-6963 + custom)
-
-For EVM, available wallets are discovered via [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) — browser extensions broadcast their metadata and `useXConnectors({ xChainType: 'EVM' })` builds the list at runtime. No hardcoded wallet registry; new wallets installed by the user appear without an SDK update.
-
-Other chains ship a curated connector list (Bitcoin: Xverse / Unisat / OKX, Sui: dapp-kit's standard connectors, Solana: wallet-adapter's standard connectors, etc.). For each connector, `isInstalled` reflects whether the underlying extension/wallet is detected. `sortConnectors(list, { preferred })` puts installed connectors first — call it once in your render path; the result is stable per render.
-
----
-
-## Chain identifiers — `xChainType` vs `xChainId`
-
-Two parallel addressing schemes:
-
-- **`xChainType: ChainType`** — family-level (`'EVM'`, `'SOLANA'`, `'BITCOIN'`, …). 9 values total.
-- **`xChainId: SpokeChainKey`** — chain-specific key from `@sodax/types` (`ChainKeys.ETHEREUM_MAINNET`, `ChainKeys.BSC_MAINNET`, …). 20 values today.
-
-Hooks that accept both enforce **exactly one** at runtime *and* at the type level. Passing both, neither, or `undefined` for both throws.
-
-```ts
-useXAccount({ xChainType: 'EVM' });                              // ✅ family-level
-useXAccount({ xChainId: ChainKeys.BSC_MAINNET });                // ✅ key-level
-useXAccount({ xChainType: 'EVM', xChainId: ChainKeys.BSC });     // ❌ throws
-useXAccount({});                                                 // ❌ throws
-```
-
-When to pick which:
-
-- **Use `xChainType`** for family-level reads (e.g. "is the user connected to *any* EVM chain?"). One connection covers every configured EVM network.
-- **Use `xChainId`** when you need the narrowest TypeScript inference (e.g. `useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET })` returns `IEvmWalletProvider | undefined`, not the broader `IWalletProvider`).
-
-The chain-id form is required when handing off to `@sodax/sdk` — SDK calls take a chain-narrowed wallet provider.
-
----
-
-## EVM is one connection across every configured EVM network
-
-A subtle but important model choice: wagmi treats every configured EVM chain as one connector session. v2 reflects this directly — `useChainGroups()` collapses EVM into a single row, and `useXAccount({ xChainType: 'EVM' })` returns the same `address` regardless of which chain the user is currently on.
-
-Consequences:
-
-- **No per-EVM-network connect/disconnect UI.** "Connect to Ethereum" and "Connect to BSC" are the same operation.
-- **Switching networks does not re-connect.** `useEvmSwitchChain({ xChainId })` calls wagmi's `switchChain` and fires the `chainChanged` EIP-1193 event. The connector stays connected.
-- **`useEvmSwitchChain` owns the "wrong network" comparison.** Pass the *expected* `xChainId`; the hook returns `{ isWrongChain, handleSwitchChain }`. Don't recompute this in UI code.
-- **Injective + MetaMask special case.** `useEvmSwitchChain` auto-switches to Ethereum mainnet when the user connects to Injective via MetaMask (Injective has a separate native chain but uses MetaMask's EVM signing for some flows). Transparent to consumers.
-
-Other chain families do **not** have this single-connection model — Bitcoin connects to one address per connector, Solana to one wallet, etc.
-
----
-
-## Bridging to `@sodax/sdk`
-
-The `IXxxWalletProvider` interface is the contract between this package and `@sodax/sdk`. Consumers call `useWalletProvider({ xChainId })` to get a chain-narrowed provider, then pass it to SDK methods:
-
-```ts
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { useSwap } from '@sodax/dapp-kit';
-import { ChainKeys } from '@sodax/types';
-
-const evm = useWalletProvider({ xChainId: ChainKeys.ETHEREUM_MAINNET });
-// evm: IEvmWalletProvider | undefined
-
-const swap = useSwap();
-if (evm) await swap.mutateAsync({ ..., walletProvider: evm });
-```
-
-The wallet provider is `undefined` until the user is connected on that chain family. SDK calls should always guard on `!= undefined`. See [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md) for the full pattern.
-
----
-
-## What lives where (file-system tour)
-
-```
-src/
-├── SodaxWalletProvider.tsx     # Root provider — mounts slots conditionally
-├── core/                       # XService + XConnector abstract base classes
-├── context/                    # WalletConfigContext (frozen config injection)
-├── hooks/                      # All public `useXxx` hooks (read-only)
-├── actions/                    # Imperative helpers (getXService, getXChainType)
-├── utils/                      # sortConnectors, walletRpcConfig, isNativeToken
-├── types/                      # Public types — config, interfaces, chainActions
-├── providers/                  # Per-chain-type React provider implementations
-└── xchains/<chain>/            # Per-chain XService + XConnector implementations
-    │                           # Sub-path import: '@sodax/wallet-sdk-react/xchains/<chain>'
-    └── ...                     # Auto-discovered by tsup; not re-exported from barrel
-```
-
-Adding a new chain = create `src/xchains/<chain>/index.ts`. tsup picks it up automatically; the package barrel does not need editing.
-
----
-
-## Things that look weird until you know why
-
-- **`useXAccount` returns an object with `address: undefined` when disconnected**, not `undefined` itself. Avoids `account?.address` chains everywhere.
-- **`useXConnect` resolves to `undefined` for provider-managed chains** (EVM/Solana/Sui). The mutation kicks off the adapter's connect flow; the address arrives via the adapter's state, not the mutation result. Read it via `useXAccount` after the mutation lands.
-- **`useEvmSwitchChain` returns `{ isWrongChain: false, handleSwitchChain: noop }` if EVM is not in `walletConfig`.** Same shape, no-op behavior — so UI code does not need to branch on "is EVM enabled".
-- **Concrete chain classes are not on the barrel.** `XverseXConnector`, `EvmXService`, etc. live behind `@sodax/wallet-sdk-react/xchains/<chain>`. Default to barrel imports; opt into deep imports only when you need `instanceof` or to extend a class.

package/ai-exported/integration/examples/01-minimal-evm.tsx

@@ -1,75 +0,0 @@
-/**
- * Minimal EVM setup — provider + single connect button.
- * Smallest working integration of @sodax/wallet-sdk-react.
- *
- * Run: drop this file in a Vite/CRA app, render <App /> at the root.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  SodaxWalletProvider,
-  type SodaxWalletConfig,
-  useXAccount,
-  useXConnect,
-  useXConnectors,
-  useXDisconnect,
-} from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-// Module-level constants — never recreate these inside a component.
-const queryClient = new QueryClient();
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: false,
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
-    },
-  },
-};
-
-export function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>
-        <ConnectButton />
-      </SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-function ConnectButton() {
-  const connectors = useXConnectors({ xChainType: 'EVM' });
-  const { mutateAsync: connect, isPending } = useXConnect();
-  const account = useXAccount({ xChainType: 'EVM' });
-  const disconnect = useXDisconnect();
-
-  if (account.address) {
-    return (
-      <div>
-        <code>{account.address}</code>
-        <button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
-          Disconnect
-        </button>
-      </div>
-    );
-  }
-
-  return (
-    <div>
-      {connectors.map((connector) => (
-        <button
-          type="button"
-          key={connector.id}
-          onClick={() => connect(connector).catch(() => {})}
-          disabled={isPending || !connector.isInstalled}
-        >
-          {connector.name}
-          {!connector.isInstalled && ' (not installed)'}
-        </button>
-      ))}
-    </div>
-  );
-}

package/ai-exported/integration/examples/02-multi-chain-modal.tsx

@@ -1,169 +0,0 @@
-/**
- * Multi-chain headless wallet modal.
- * Renders chain picker → wallet picker → connecting → success/error using `useWalletModal`.
- *
- * UI uses native <dialog> — replace with shadcn/Radix/your dialog primitive.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  SodaxWalletProvider,
-  type SodaxWalletConfig,
-  useWalletModal,
-  useChainGroups,
-  useXConnectors,
-  sortConnectors,
-  type IXConnector,
-} from '@sodax/wallet-sdk-react';
-import type { ChainType } from '@sodax/types';
-import { ChainKeys } from '@sodax/types';
-
-const queryClient = new QueryClient();
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-    },
-  },
-  SOLANA: {
-    chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://api.mainnet-beta.solana.com' } },
-  },
-  SUI: { network: 'mainnet' },
-  BITCOIN: {},
-  ICON: {
-    chains: { [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' } },
-  },
-};
-
-export function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>
-        <WalletModalRoot />
-      </SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-function WalletModalRoot() {
-  const modal = useWalletModal({
-    onConnected: (chainType, account) => {
-      console.log('connected', chainType, account.address);
-    },
-  });
-
-  switch (modal.state.kind) {
-    case 'closed':
-      return (
-        <button type="button" onClick={modal.open}>
-          Connect Wallet
-        </button>
-      );
-
-    case 'chainSelect':
-      return <ChainPicker onPick={modal.selectChain} onClose={modal.close} />;
-
-    case 'walletSelect':
-      return (
-        <WalletPicker
-          chainType={modal.state.chainType}
-          onPick={modal.selectWallet}
-          onBack={modal.back}
-          onClose={modal.close}
-        />
-      );
-
-    case 'connecting':
-      // Hide modal while wagmi's QR modal owns the screen for WalletConnect
-      if (modal.state.connector.id === 'walletConnect') return null;
-      return (
-        <Dialog onClose={modal.close}>
-          <p>Approve in {modal.state.connector.name}…</p>
-          <button type="button" onClick={modal.back}>
-            Cancel
-          </button>
-        </Dialog>
-      );
-
-    case 'error':
-      return (
-        <Dialog onClose={modal.close}>
-          <p>Error: {modal.state.error.message}</p>
-          {!modal.state.connector.isInstalled && modal.state.connector.installUrl && (
-            <a href={modal.state.connector.installUrl} target="_blank" rel="noreferrer">
-              Install {modal.state.connector.name}
-            </a>
-          )}
-          <button type="button" onClick={modal.retry}>
-            Retry
-          </button>
-          <button type="button" onClick={modal.back}>
-            Pick another wallet
-          </button>
-        </Dialog>
-      );
-
-    case 'success':
-      // onConnected fired; close the modal
-      queueMicrotask(modal.close);
-      return null;
-
-    default:
-      return null;
-  }
-}
-
-function ChainPicker({ onPick, onClose }: { onPick: (c: ChainType) => void; onClose: () => void }) {
-  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'SUI', 'BITCOIN', 'ICON'] });
-  return (
-    <Dialog onClose={onClose}>
-      <h2>Select a chain</h2>
-      {groups.map(group => (
-        <button type="button" key={group.chainType} onClick={() => onPick(group.chainType)}>
-          <span>{group.displayName}</span>
-          {group.isConnected && ' ✓'}
-        </button>
-      ))}
-    </Dialog>
-  );
-}
-
-const PREFERRED = ['hana', 'metamask', 'phantom'] as const;
-
-function WalletPicker({
-  chainType,
-  onPick,
-  onBack,
-  onClose,
-}: {
-  chainType: ChainType;
-  onPick: (c: IXConnector) => void;
-  onBack: () => void;
-  onClose: () => void;
-}) {
-  const connectors = sortConnectors(useXConnectors({ xChainType: chainType }), { preferred: PREFERRED });
-  return (
-    <Dialog onClose={onClose}>
-      <button type="button" onClick={onBack}>
-        ← Back
-      </button>
-      <h2>Connect to {chainType}</h2>
-      {connectors.map(connector => (
-        <button type="button" key={connector.id} onClick={() => onPick(connector)} disabled={!connector.isInstalled}>
-          {connector.name}
-          {!connector.isInstalled && ' (not installed)'}
-        </button>
-      ))}
-    </Dialog>
-  );
-}
-
-function Dialog({ children, onClose }: { children: React.ReactNode; onClose: () => void }) {
-  return (
-    <dialog open onClose={onClose} style={{ padding: 16 }}>
-      {children}
-    </dialog>
-  );
-}

package/ai-exported/integration/examples/03-nextjs-app-router.tsx

@@ -1,99 +0,0 @@
-/**
- * Next.js 15 App Router setup with SSR-safe hydration.
- *
- * This file shows three separate files merged into one for reference. In your
- * project, split them into the matching paths:
- *
- *   app/
- *   ├── layout.tsx     ← server component (RootLayout below — make it the file's `export default`)
- *   ├── providers.tsx  ← client component (Providers below — needs `'use client'` at top of file)
- *   └── page.tsx       ← client component (Home below — needs `'use client'` at top of file)
- *
- * Key SSR points:
- * - `EVM.ssr: true` enables wagmi cookie-based hydration.
- * - `'use client'` on every component that calls a hook from this package.
- * - QueryClient as a module constant — one client per app, never recreated.
- * - SodaxWalletProvider config also a module constant — frozen on first render.
- *
- * NOTE: this combined file uses named exports only so it lints clean. Each of
- * `RootLayout`, `Providers`, and `Home` should be the `export default` of its
- * own file in your real project.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { SodaxWalletProvider, type SodaxWalletConfig, useConnectedChains } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-import type { ReactNode } from 'react';
-
-// ============================================================
-// app/providers.tsx — client component
-// (top of file: `'use client';`)
-// ============================================================
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: { staleTime: 60 * 1000 },
-  },
-});
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true, // ← required for Next.js — enables wagmi cookies hydration
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
-    },
-  },
-};
-
-export function Providers({ children }: { children: ReactNode }) {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-// ============================================================
-// app/layout.tsx — server component
-// (no `'use client'`; in your real file, change `export function` to `export default function`)
-// ============================================================
-
-export function RootLayout({ children }: { children: ReactNode }) {
-  return (
-    <html lang="en">
-      <body>
-        <Providers>{children}</Providers>
-      </body>
-    </html>
-  );
-}
-
-// ============================================================
-// app/page.tsx — client component (because we use a hook)
-// (top of file: `'use client';`; change `export function` to `export default function`)
-// ============================================================
-
-export function Home() {
-  // Gate UI on hydration to prevent reload flicker
-  const { chains, status } = useConnectedChains();
-
-  if (status === 'loading') {
-    return <p>Loading…</p>;
-  }
-
-  if (chains.length === 0) {
-    return <p>No wallets connected</p>;
-  }
-
-  return (
-    <ul>
-      {chains.map((c) => (
-        <li key={c.chainType}>
-          {c.chainType}: <code>{c.account.address}</code>
-        </li>
-      ))}
-    </ul>
-  );
-}

package/ai-exported/integration/examples/04-walletconnect-setup.tsx

@@ -1,89 +0,0 @@
-/**
- * WalletConnect setup — adds the WalletConnect connector to the EVM modal.
- * For dApps that target users on mobile-only or enterprise custody wallets
- * (Ledger Live, Safe, Fireblocks, ...) which cannot install browser extensions.
- *
- * Get a projectId at https://cloud.walletconnect.com
- *
- * To narrow the WalletConnect modal to ONE specific wallet (e.g. an enterprise
- * custody integration), see the commented `qrModalOptions` block below — fill
- * in the target wallet id from https://walletconnect.com/explorer.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import {
-  SodaxWalletProvider,
-  type SodaxWalletConfig,
-  useWalletModal,
-  useXConnectors,
-  useXAccount,
-  useXDisconnect,
-} from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-const queryClient = new QueryClient();
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true,
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-      [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
-    },
-    walletConnect: {
-      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID ?? '',
-      // Optional — restrict the WalletConnect QR modal to a specific wallet:
-      //
-      // qrModalOptions: {
-      //   explorerRecommendedWalletIds: ['<target-wallet-id-from-walletconnect-explorer>'],
-      //   explorerExcludedWalletIds: 'ALL', // hide everything except recommended
-      // },
-    },
-  },
-};
-
-export function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>
-        <ConnectWithWalletConnect />
-      </SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-
-function ConnectWithWalletConnect() {
-  const modal = useWalletModal();
-  const connectors = useXConnectors({ xChainType: 'EVM' });
-  const account = useXAccount({ xChainType: 'EVM' });
-  const disconnect = useXDisconnect();
-
-  const wcConnector = connectors.find((c) => c.id === 'walletConnect');
-
-  // Hide the modal while wagmi/WalletConnect's QR modal owns the screen
-  if (modal.state.kind === 'connecting' && modal.state.connector.id === 'walletConnect') {
-    return null;
-  }
-
-  if (account.address) {
-    return (
-      <div>
-        <code>{account.address}</code>
-        <button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
-          Disconnect
-        </button>
-      </div>
-    );
-  }
-
-  if (!wcConnector) {
-    return <p>WalletConnect not configured — set NEXT_PUBLIC_WC_PROJECT_ID</p>;
-  }
-
-  return (
-    <button type="button" onClick={() => modal.selectWallet(wcConnector)}>
-      Connect via WalletConnect
-    </button>
-  );
-}

package/ai-exported/integration/examples/README.md

@@ -1,29 +0,0 @@
-# Examples
-
-Copy-paste-runnable code examples. Each file is complete — drop it into a fresh React 19 project with `@sodax/wallet-sdk-react` + `@tanstack/react-query` installed and it works.
-
-For narrative + step-by-step explanation, see [`../recipes/`](../recipes/). Examples here are pure code with minimal comments.
-
-| File | Use case | Lines |
-|---|---|---|
-| [`01-minimal-evm.tsx`](./01-minimal-evm.tsx) | Smallest working setup — provider + 1 connect button | ~50 |
-| [`02-multi-chain-modal.tsx`](./02-multi-chain-modal.tsx) | Headless wallet modal with chain → connector → connecting flow | ~120 |
-| [`03-nextjs-app-router.tsx`](./03-nextjs-app-router.tsx) | Next.js 15 App Router setup (SSR + `'use client'`) | ~60 |
-| [`04-walletconnect-setup.tsx`](./04-walletconnect-setup.tsx) | WalletConnect connector setup (with optional single-wallet filter) | ~50 |
-
-## Conventions
-
-- All files use TypeScript (`.tsx`).
-- All consumer components have `'use client'` (Next.js compatible).
-- `walletConfig` is defined as a **module-level constant** — never created inside a component (the provider freezes config on first render).
-- `QueryClient` is also a module-level constant — one client per app, shared across providers.
-- Examples use `<button>`, `<select>`, `<dialog>` etc. directly — bring your own UI library.
-
-## Running an example
-
-```bash
-pnpm add @sodax/wallet-sdk-react @tanstack/react-query
-# also: react@>=19, react-dom@>=19
-```
-
-Drop the file into your app, mount the provider component at the root, and use the consumer component anywhere below it.