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

package/ai-exported/migration/recipes/multi-chain-modal.md

@@ -1,244 +0,0 @@
-# Recipe: Migrate a Multi-Chain Wallet Modal
-
-Replaces a hand-rolled v1 modal (chain picker → connector picker → connect) with v2's headless `useWalletModal` state machine. Self-contained — apply this recipe without reading other files.
-
----
-
-## When to use this recipe
-
-Apply when the user's v1 code:
-
-- Maintains its own state for "which chain is the user picking"
-- Calls `useXConnectors(<chain>)` per chain in a loop
-- Calls `useXConnect` directly from a click handler
-- Tracks a `connecting` / `success` / `error` state by hand
-
-v2 ships these primitives so the consumer focuses only on UI rendering.
-
----
-
-## Before (v1, simplified)
-
-```diff
-- 'use client';
--
-- import { useState } from 'react';
-- import {
--   useXConnectors,
--   useXConnect,
--   useXDisconnect,
--   type ChainType,
-- } from '@sodax/wallet-sdk-react';
--
-- const SUPPORTED_CHAINS: ChainType[] = ['EVM', 'SUI', 'SOLANA', 'ICON'];
--
-- export function WalletModal({ open, onClose }: { open: boolean; onClose: () => void }) {
--   const [pickedChain, setPickedChain] = useState<ChainType | null>(null);
--   const [connectingId, setConnectingId] = useState<string | null>(null);
--   const [error, setError] = useState<Error | null>(null);
--
--   const evmConnectors = useXConnectors('EVM');
--   const suiConnectors = useXConnectors('SUI');
--   const solanaConnectors = useXConnectors('SOLANA');
--   const iconConnectors = useXConnectors('ICON');
--
--   const { mutateAsync: connect } = useXConnect();
--   const disconnect = useXDisconnect();
--
--   const connectorsByChain: Record<ChainType, ReturnType<typeof useXConnectors>> = {
--     EVM: evmConnectors,
--     SUI: suiConnectors,
--     SOLANA: solanaConnectors,
--     ICON: iconConnectors,
--   };
--
--   if (!open) return null;
--
--   if (!pickedChain) {
--     return (
--       <Dialog onClose={onClose}>
--         <h2>Select a chain</h2>
--         {SUPPORTED_CHAINS.map((chain) => (
--           <button key={chain} onClick={() => setPickedChain(chain)}>
--             {chain}
--           </button>
--         ))}
--       </Dialog>
--     );
--   }
--
--   const connectors = connectorsByChain[pickedChain] ?? [];
--
--   return (
--     <Dialog onClose={onClose}>
--       <button onClick={() => setPickedChain(null)}>← back</button>
--       <h2>Connect to {pickedChain}</h2>
--       {error && <div>Error: {error.message}</div>}
--       {connectors.map((connector) => (
--         <button
--           key={connector.id}
--           disabled={connectingId !== null}
--           onClick={async () => {
--             setConnectingId(connector.id);
--             setError(null);
--             try {
--               await connect(connector);
--               onClose();
--             } catch (err) {
--               setError(err as Error);
--             } finally {
--               setConnectingId(null);
--             }
--           }}
--         >
--           {connector.name}
--           {connectingId === connector.id && ' (connecting...)'}
--         </button>
--       ))}
--     </Dialog>
--   );
-- }
-```
-
-(Most v1 modals look like this — manual chain list, manual loop over connectors, manual try/catch for state.)
-
----
-
-## After (v2)
-
-```tsx
-'use client';
-
-import {
-  useWalletModal,
-  useChainGroups,
-  sortConnectors,
-} from '@sodax/wallet-sdk-react';
-
-export function WalletModal({ open, onClose }: { open: boolean; onClose: () => void }) {
-  const modal = useWalletModal({
-    onConnected: () => onClose(),
-  });
-  const chainGroups = useChainGroups();
-
-  if (!open) return null;
-
-  switch (modal.state.kind) {
-    case 'closed':
-    case 'chainSelect':
-      return (
-        <Dialog onClose={onClose}>
-          <h2>Select a chain</h2>
-          {chainGroups.map((group) => (
-            <button
-              key={group.id}
-              onClick={() => modal.openChain(group.xChainType)}
-            >
-              {group.label}
-            </button>
-          ))}
-        </Dialog>
-      );
-
-    case 'walletSelect': {
-      const sorted = sortConnectors(modal.state.connectors, {
-        preferred: ['MetaMask', 'Phantom'],
-      });
-      return (
-        <Dialog onClose={onClose}>
-          <button onClick={() => modal.back()}>← back</button>
-          <h2>Connect to {modal.state.xChainType}</h2>
-          {sorted.map((connector) => (
-            <button
-              key={connector.id}
-              disabled={!connector.isInstalled}
-              onClick={() => modal.connect(connector)}
-            >
-              {connector.name}
-              {!connector.isInstalled && (
-                <a href={connector.installUrl} target="_blank" rel="noreferrer">
-                  Install
-                </a>
-              )}
-            </button>
-          ))}
-        </Dialog>
-      );
-    }
-
-    case 'connecting':
-      return (
-        <Dialog onClose={onClose}>
-          <p>Connecting to {modal.state.connector.name}…</p>
-        </Dialog>
-      );
-
-    case 'error':
-      return (
-        <Dialog onClose={onClose}>
-          <p>Error: {modal.state.error.message}</p>
-          <button onClick={() => modal.retry()}>Retry</button>
-        </Dialog>
-      );
-
-    case 'success':
-      return null; // onConnected handler closes
-
-    default:
-      return null;
-  }
-}
-```
-
----
-
-## What changed
-
-| Concern | v1 (manual) | v2 (primitive) |
-|---|---|---|
-| Track which chain is picked | `useState<ChainType \| null>` | `useWalletModal().state.kind === 'walletSelect'` |
-| List enabled chains | hardcoded `SUPPORTED_CHAINS` | `useChainGroups()` (driven by `walletConfig`) |
-| List connectors per chain | one `useXConnectors` per chain | `modal.state.connectors` when `kind === 'walletSelect'` |
-| Connecting / error state | `useState` for `connectingId`, `error` | `modal.state.kind` with discriminated union |
-| Retry on error | re-trigger click manually | `modal.retry()` |
-| Filter to installed wallets | n/a | `connector.isInstalled` + `connector.installUrl` |
-| Sort connectors | manual `array.sort` | `sortConnectors(xs, { preferred })` |
-| Close on success | manual `onClose()` after `connect` | `useWalletModal({ onConnected })` callback |
-| EVM treated as one | per-network confusion | `useChainGroups` collapses EVM into one row |
-
----
-
-## Migration steps
-
-1. **Find the v1 modal file.** Search for `useState<ChainType` or multiple `useXConnectors` calls in the same component.
-2. **Replace state-tracking with `useWalletModal`.** Remove `useState` for picked chain, connectingId, error.
-3. **Replace hardcoded chain list with `useChainGroups`.** Use the `xChainType` field on each group entry.
-4. **Switch on `modal.state.kind`.** Render branches: `'closed'` / `'chainSelect'` / `'walletSelect'` / `'connecting'` / `'error'` / `'success'`.
-5. **Use connector metadata.** `connector.isInstalled` / `connector.installUrl` for install CTA. `sortConnectors` to rank installed wallets first.
-6. **Keep your existing `<Dialog>` primitive.** v2 is **headless** — bring your own UI components.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Confirm no manual state is tracking modal flow
-grep -nE "useState<ChainType" <user-modal-file>
-grep -nE "useState.*connectingId|useState.*pickedChain" <user-modal-file>
-# expect empty
-
-# 3. Manual — open modal, walk through chain → wallet → connecting → success
-```
-
----
-
-## Edge cases
-
-- **Modal opens on a specific chain (skip chain select).** Call `modal.openChain('EVM')` directly in your trigger button instead of going through chain select. The state machine starts at `'walletSelect'` for that chain.
-- **App needs to know which chain the user picked even before connecting.** Read `modal.state.xChainType` inside the `'walletSelect'` / `'connecting'` branches.
-- **Multiple modal trigger buttons (e.g. chain-specific CTAs).** Reuse one `useWalletModal` instance — do not create one per button.
-
-For a full integration walkthrough (without v1 baggage), see [`../../integration/recipes/multi-chain-modal.md`](../../integration/recipes/multi-chain-modal.md).

package/ai-exported/migration/recipes/ssr-setup.md

@@ -1,164 +0,0 @@
-# Recipe: Migrate Next.js SSR Setup
-
-Migrates the SSR-specific provider setup. Both `initialState` and `reconnectOnMount` move **into the `EVM` slot** of the new `config` prop — they are not removed in v2. Self-contained — apply this recipe without reading other files.
-
----
-
-## When to use this recipe
-
-Apply when the user's v1 code:
-
-- Passes `initialState={...}` to `SodaxWalletProvider`
-- Has a server component or page that calls `cookieToInitialState` (wagmi)
-- Sets `options.wagmi.ssr: true` and/or `options.wagmi.reconnectOnMount`
-
-If the project is **not** Next.js (Vite, CRA), only the prop-shape rewrite applies; `initialState` plumbing is not needed.
-
----
-
-## Before (v1)
-
-```diff
-- // app/layout.tsx — v1 ❌
-- import { headers } from 'next/headers';
-- import { cookieToInitialState } from 'wagmi';
-- import { SodaxWalletProvider } from '@sodax/wallet-sdk-react';
-- import { createWagmiConfig } from '@sodax/wallet-sdk-react'; // hypothetical helper consumers used
--
-- const rpcConfig = {
--   'sonic': 'https://rpc.soniclabs.com',
--   '0x1.eth': 'https://ethereum-rpc.publicnode.com',
-- };
--
-- export default async function RootLayout({ children }: { children: React.ReactNode }) {
--   const headersList = await headers();
--   const cookie = headersList.get('cookie');
--
--   // Build wagmi config the same way the package built it internally to derive initialState
--   const wagmiConfig = createWagmiConfig(rpcConfig, { ssr: true });
--   const initialState = cookieToInitialState(wagmiConfig, cookie);
--
--   return (
--     <html>
--       <body>
--         <SodaxWalletProvider
--           rpcConfig={rpcConfig}
--           options={{ wagmi: { ssr: true, reconnectOnMount: true } }}
--           initialState={initialState}
--         >
--           {children}
--         </SodaxWalletProvider>
--       </body>
--     </html>
--   );
-- }
-```
-
----
-
-## After (v2)
-
-```tsx
-// app/layout.tsx — v2 ✅
-import { headers } from 'next/headers';
-import { cookieToInitialState } from 'wagmi';
-import { ChainKeys } from '@sodax/types';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-import { createWagmiConfig } from '@sodax/wallet-sdk-react/xchains/evm';
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true,
-    reconnectOnMount: true,
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-    },
-  },
-  // Add other chain slots as needed
-};
-
-const queryClient = new QueryClient();
-
-export default async function RootLayout({ children }: { children: React.ReactNode }) {
-  const cookie = (await headers()).get('cookie');
-  // Re-derive initialState from cookies to avoid disconnect-flash on first render.
-  const wagmiConfig = createWagmiConfig(walletConfig.EVM!);
-  const initialState = cookieToInitialState(wagmiConfig, cookie);
-
-  const evmConfig = { ...walletConfig.EVM!, initialState };
-  const config: SodaxWalletConfig = { ...walletConfig, EVM: evmConfig };
-
-  return (
-    <html>
-      <body>
-        <QueryClientProvider client={queryClient}>
-          <SodaxWalletProvider config={config}>{children}</SodaxWalletProvider>
-        </QueryClientProvider>
-      </body>
-    </html>
-  );
-}
-```
-
-If you don't need to avoid the first-render disconnect flash, drop the cookie / `initialState` plumbing entirely — `EVM.ssr: true` alone is enough for the typical SSR app.
-
----
-
-## What changed
-
-| Concern | v1 | v2 |
-|---|---|---|
-| `rpcConfig` flat dict | top-level prop | nested under `EVM.chains[<ChainKey>].rpcUrl` |
-| `options.wagmi.ssr` | nested under `options.wagmi` | `EVM.ssr: true` |
-| `options.wagmi.reconnectOnMount` | nested under `options.wagmi` | `EVM.reconnectOnMount` (still supported, default `false`) |
-| `initialState` | top-level prop | `EVM.initialState` (still supported — pass `cookieToInitialState(...)` for Next.js cookie hydration) |
-| `QueryClient` | created internally by `SodaxWalletProvider` | created by caller, wrapped with `QueryClientProvider` |
-
----
-
-## Migration steps
-
-1. **Move per-chain RPC URLs.** Move `rpcConfig['sonic']` etc. into `EVM.chains[ChainKeys.SONIC_MAINNET].rpcUrl`. Use `ChainKeys` constants from `@sodax/types`.
-2. **Collapse `options.wagmi.*` into `EVM.*`.** `options.wagmi.ssr` → `EVM.ssr`, `options.wagmi.reconnectOnMount` → `EVM.reconnectOnMount`.
-3. **Move `initialState` into `EVM.initialState`.** v2 still accepts wagmi cookie state; the prop name and location changed, not the feature.
-4. **Add `QueryClientProvider`.** Create a `QueryClient` (top-level module constant — singleton across renders) and wrap `SodaxWalletProvider` with `<QueryClientProvider>`.
-5. **Make sure `@tanstack/react-query` is a direct dep.** Add it if missing:
-   ```bash
-   pnpm add @tanstack/react-query
-   ```
-6. **Confirm consumer components are `'use client'`.** Hooks (`useXAccount`, `useXConnect`, etc.) only run on the client — any component that calls them needs the directive.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. No top-level v1 props remain on SodaxWalletProvider
-grep -rnE "SodaxWalletProvider[^>]*\b(rpcConfig|options|initialState)\s*=" <user-src>
-# expect empty
-
-# 3. EVM.ssr: true is set
-grep -rnE "EVM:\s*\{[^}]*\bssr:\s*true" <user-src>
-# expect at least one match
-
-# 4. QueryClientProvider wraps SodaxWalletProvider
-# (manual — open layout.tsx, confirm nesting)
-
-# 5. Manual — pnpm build && pnpm start, load page, confirm no hydration mismatch warnings in console
-```
-
----
-
-## Common pitfalls
-
-- **Forgetting `'use client'` on consumer components.** If you call `useXAccount` / `useXConnect` in a Server Component, you'll get "useEffect cannot be called from a server component". Wrap the consumer in a client component.
-- **Creating `QueryClient` inside the layout component.** Each render creates a new client and React Query loses its cache. Define `queryClient` as a **module-level constant**, or use `useState(() => new QueryClient())` inside a client component.
-- **Pages Router project.** This recipe assumes App Router. For Pages Router, mount the providers in `_app.tsx` instead — the API is the same.
-- **Dynamic RPC URLs from env vars.** If `rpcUrl` comes from `process.env.NEXT_PUBLIC_*`, ensure the env var is available at module init time (it is, by Next.js convention). Don't compute the config inside a hook — `SodaxWalletProvider` freezes config on first render, so config must be stable.
-
-

package/ai-exported/migration/recipes/walletconnect-migration.md

@@ -1,168 +0,0 @@
-# Recipe: Adopt WalletConnect (v2 only)
-
-WalletConnect support is **new in v2** — there is no v1 equivalent to migrate from. This recipe is here for users who tried to bolt WalletConnect onto v1 by hand-rolling a wagmi config and now want to use the v2 first-class option.
-
-If you didn't have WalletConnect in v1, **this recipe is opt-in, not required**. Skip if not relevant.
-
----
-
-## When to use this recipe
-
-Apply when the user's v1 code:
-
-- Built a custom wagmi config that injected `walletConnect()` connector
-- Mounted a separate `WagmiProvider` outside `SodaxWalletProvider`
-- Patched the v1 internal `createWagmiConfig` helper to include WalletConnect
-
-Or when the user simply wants to **add WalletConnect for the first time** while migrating to v2.
-
----
-
-## Why apps add WalletConnect
-
-EIP-6963 (the default v2 EVM discovery mechanism) only finds **browser-extension wallets**. Partners using enterprise custody — Fireblocks, Ledger Live, mobile-only wallets — cannot install browser extensions. WalletConnect is the protocol that lets these wallets connect via QR / deep link.
-
----
-
-## Before (v1, hand-rolled — typical workaround)
-
-```tsx
-// v1 ❌ — bypassed the package's wagmi config
-import { createConfig, WagmiProvider } from 'wagmi';
-import { walletConnect } from 'wagmi/connectors';
-import { mainnet, sonic } from 'wagmi/chains';
-
-const wagmiConfig = createConfig({
-  chains: [mainnet, sonic],
-  connectors: [
-    walletConnect({ projectId: 'wc-cloud-project-id' }),
-    // ...
-  ],
-  // ...
-});
-
-export function Providers({ children }) {
-  return (
-    <WagmiProvider config={wagmiConfig}>
-      {/* SodaxWalletProvider mounted alongside, with conflicting wagmi state */}
-      <SodaxWalletProvider rpcConfig={...} options={...}>
-        {children}
-      </SodaxWalletProvider>
-    </WagmiProvider>
-  );
-}
-```
-
-(This pattern caused two parallel wagmi states and was never officially supported.)
-
----
-
-## After (v2 — first-class)
-
-```tsx
-// v2 ✅
-import { ChainKeys } from '@sodax/types';
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true,
-    walletConnect: {
-      projectId: 'wc-cloud-project-id', // from cloud.walletconnect.com
-    },
-    chains: {
-      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
-      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
-    },
-  },
-};
-
-const queryClient = new QueryClient();
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
-    </QueryClientProvider>
-  );
-}
-```
-
-The WalletConnect connector is added to wagmi automatically. `useXConnectors({ xChainType: 'EVM' })` will surface it alongside any EIP-6963 wallets.
-
----
-
-## What changed
-
-| Concern | v1 (hand-rolled) | v2 (first-class) |
-|---|---|---|
-| WagmiProvider mount | manual, outside SodaxWalletProvider | internal to SodaxWalletProvider |
-| wagmi config | hand-built via `createConfig` | derived from `walletConfig` |
-| WalletConnect projectId | passed to `walletConnect()` connector | passed to `EVM.walletConnect.projectId` |
-| Two parallel wagmi states | yes — common bug | no — single source of truth |
-| Connector list in modal | mixed (some via custom connectors, some via SodaxWalletProvider) | unified via `useXConnectors({ xChainType: 'EVM' })` |
-
----
-
-## Restricting the modal to specific wallets
-
-`EVM.walletConnect` extends wagmi's `WalletConnectParameters` — full options available. To show only one specific wallet (e.g. when integrating with a single enterprise custody provider) and hide the rest:
-
-```tsx
-EVM: {
-  walletConnect: {
-    projectId: 'wc-cloud-project-id',
-    qrModalOptions: {
-      explorerRecommendedWalletIds: ['<target-wallet-id>'],
-      explorerExcludedWalletIds: 'ALL',
-    },
-  },
-},
-```
-
-Wallet IDs come from the [WalletConnect Explorer](https://cloud.walletconnect.com/sign-in). Filter options:
-
-| Option | Effect |
-|---|---|
-| `explorerRecommendedWalletIds` | Prioritized at the top of the QR modal. |
-| `explorerExcludedWalletIds: 'ALL'` | Hides every wallet not in `explorerRecommendedWalletIds`. |
-| `explorerExcludedWalletIds: ['id1', 'id2']` | Hides specific wallets only. |
-
----
-
-## Migration steps
-
-1. **Remove the hand-rolled `WagmiProvider` and `createConfig`.** v2 builds wagmi config internally.
-2. **Move `projectId`** into `walletConfig.EVM.walletConnect.projectId`.
-3. **Move any `qrModalOptions`** (e.g. wallet filters) into `walletConfig.EVM.walletConnect.qrModalOptions`.
-4. **Verify** that `useXConnectors({ xChainType: 'EVM' })` returns both EIP-6963 connectors and the WalletConnect entry.
-5. **Drop** any custom hooks / state that bridged between the two wagmi configs in v1.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Confirm no manual WagmiProvider remains
-grep -rn "WagmiProvider" <user-src>
-# expect empty (or only inside the wallet-sdk-react package itself if the user has a deep import — flag and remove)
-
-# 3. Confirm walletConnect config is in walletConfig
-grep -rn "walletConnect" <user-src> | grep -i "projectId"
-# expect at least one match in the provider file
-
-# 4. Manual — load app, open connect modal, confirm WalletConnect option appears
-```
-
----
-
-## Common pitfalls
-
-- **Missing projectId.** Without `projectId`, the WalletConnect connector won't initialize. Get one free at [cloud.walletconnect.com](https://cloud.walletconnect.com).
-- **Bundling EIP-6963 + WalletConnect.** The two are additive — `useXConnectors` returns both. UI should let users pick.
-- **`qrModalOptions.explorerExcludedWalletIds` typo.** It's `'ALL'` (string), not `true` or `'all'`.
-- **Multiple SodaxWalletProvider mounts.** Don't mount one with WalletConnect and another without — define `walletConfig` once at the app root.

package/ai-exported/migration/reference/components.md

@@ -1,73 +0,0 @@
-# Reference: Component / Provider Map
-
-Components and exported providers between v1 and v2. See [`../breaking-changes.md`](../breaking-changes.md) for the WHY.
-
----
-
-## `SodaxWalletProvider`
-
-Same name in v1 and v2. **Props changed** — see [`config.md`](./config.md) for the full shape map.
-
-```tsx
-// v1 ❌
-<SodaxWalletProvider
-  rpcConfig={rpcConfig}
-  options={{ wagmi, solana, sui }}
-  initialState={wagmiState}
->
-  {children}
-</SodaxWalletProvider>
-
-// v2 ✅
-<SodaxWalletProvider config={walletConfig}>
-  {children}
-</SodaxWalletProvider>
-```
-
-### Provider-stack order
-
-| Position | v1 | v2 |
-|---|---|---|
-| Outermost (app entry) | `SodaxWalletProvider` (creates internal QueryClient) | `QueryClientProvider` (caller-provided QueryClient) |
-| Middle | (none) | `SodaxWalletProvider` |
-| Children | app | app |
-
-```tsx
-// v1 ❌ — SodaxWalletProvider internal QueryClient
-<SodaxWalletProvider rpcConfig={...} options={...}>
-  {children}
-</SodaxWalletProvider>
-
-// v2 ✅ — caller wraps with QueryClientProvider
-<QueryClientProvider client={queryClient}>
-  <SodaxWalletProvider config={walletConfig}>
-    {children}
-  </SodaxWalletProvider>
-</QueryClientProvider>
-```
-
----
-
-## Internal-only components (do not import directly)
-
-These are mounted **inside** `SodaxWalletProvider` and are not part of the public API in either v1 or v2. Listed for awareness — if you imported them in v1 you should not have, and v2 may not expose them.
-
-| Component | v1 | v2 | Note |
-|---|---|---|---|
-| `Hydrate` | exported (file `Hydrate.ts`) | replaced by per-chain `EvmHydrator`, `SolanaHydrator`, `SuiHydrator` (internal) | If you imported `Hydrate` from v1, **remove the import** — v2 does not export an equivalent. State hydration is automatic. |
-| `WagmiProvider`, `SuiClientProvider`, `SolanaWalletProvider` (re-exports) | not re-exported | not re-exported | Use the original packages (`wagmi`, `@mysten/dapp-kit`, `@solana/wallet-adapter-react`) only if you need direct access — most apps should not. |
-
----
-
-## `XService` and `XConnector` abstract classes
-
-| | v1 | v2 |
-|---|---|---|
-| Import path | `@sodax/wallet-sdk-react` (barrel) | `@sodax/wallet-sdk-react` (barrel — types only) |
-| Runtime class export | yes | yes |
-| Abstract method signature | `abstract connect(): Promise<XAccount \| undefined>` | unchanged |
-| Properties | `id`, `name`, `icon`, `xChainType` | unchanged |
-
-The abstract contract is **stable across v1 → v2**. If you have a custom subclass, it should compile against v2 with no changes — but verify, and check `getBalance` / `getBalances` defaults if you override them.
-
-> **Stop condition:** if the user has a custom `XConnector` or `XService` subclass, the migration agent must stop and ask. The abstract surface is stable but downstream usage (e.g. how the subclass is instantiated, registered) has changed.