@sodax/wallet-sdk-react 1.5.6-beta → 2.0.0-rc.1

package/ai-exported/migration/recipes/connect-button.md

@@ -0,0 +1,166 @@
+# Recipe: Migrate a Single-Chain Connect Button
+
+Migrates the most common pattern: one button per chain that lists connectors, lets the user pick one, and shows the connected address. Self-contained — apply this recipe without reading other files.
+
+---
+
+## When to use this recipe
+
+Apply when the user's v1 code uses any of:
+
+- `useXConnectors('<chain>')` (positional)
+- `useXAccount('<chain>')` (positional)
+- `useXConnect()` + `useXDisconnect()` for a per-chain button
+
+If the user has a multi-chain modal (chain picker → connector picker), use [`multi-chain-modal.md`](./multi-chain-modal.md) instead.
+
+---
+
+## Before (v1)
+
+```tsx
+'use client';
+
+import {
+  useXConnectors,
+  useXConnect,
+  useXAccount,
+  useXDisconnect,
+} from '@sodax/wallet-sdk-react';
+
+export function EvmConnectButton() {
+  const connectors = useXConnectors('EVM');
+  const { mutateAsync: connect, isPending } = useXConnect();
+  const { address } = useXAccount('EVM');
+  const disconnect = useXDisconnect();
+
+  if (address) {
+    return (
+      <div>
+        Connected: {address}
+        <button onClick={() => disconnect('EVM')}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {connectors.map((connector) => (
+        <button
+          key={connector.id}
+          disabled={isPending}
+          onClick={() => connect(connector)}
+        >
+          Connect with {connector.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## After (v2)
+
+```tsx
+'use client';
+
+import {
+  useXConnectors,
+  useXConnect,
+  useXAccount,
+  useXDisconnect,
+} from '@sodax/wallet-sdk-react';
+
+export function EvmConnectButton() {
+  const connectors = useXConnectors({ xChainType: 'EVM' });
+  const { mutateAsync: connect, isPending } = useXConnect();
+  const { address } = useXAccount({ xChainType: 'EVM' });
+  const disconnect = useXDisconnect();
+
+  if (address) {
+    return (
+      <div>
+        Connected: {address}
+        <button onClick={() => disconnect({ xChainType: 'EVM' })}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {connectors.map((connector) => (
+        <button
+          key={connector.id}
+          disabled={isPending}
+          onClick={() => connect(connector)}
+        >
+          Connect with {connector.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## What changed
+
+| Line | v1 | v2 |
+|---|---|---|
+| `useXConnectors` | `useXConnectors('EVM')` | `useXConnectors({ xChainType: 'EVM' })` |
+| `useXAccount` | `useXAccount('EVM')` | `useXAccount({ xChainType: 'EVM' })` |
+| `useXConnect` mutation arg | pass `connector` to `mutateAsync` | unchanged |
+| `useXDisconnect` returned callback | `disconnect('EVM')` | `disconnect({ xChainType: 'EVM' })` |
+
+The mechanical changes are the **three hook usages** above. The `useXDisconnect` callback shape changed in v2 — see [`../reference/hooks.md`](../reference/hooks.md) § `useXDisconnect`.
+
+---
+
+## Variations
+
+### Per-chain-id (e.g. one connect button per EVM network)
+
+If v1 used `useXAccount('0x1.eth')`:
+
+```tsx
+// v1 ❌
+const { address } = useXAccount('0x1.eth');
+```
+
+Use the typed chain key in v2:
+
+```tsx
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+const { address } = useXAccount({ xChainId: ChainKeys.ETHEREUM_MAINNET });
+```
+
+> ⚠️ If the v1 button is "connect to Ethereum", remember v2 treats EVM as a **single connection across every configured EVM network**. A per-Ethereum button is rarely what users want — consider replacing with a single "EVM" button + `useEvmSwitchChain` for network switching. See [`../breaking-changes.md`](../breaking-changes.md) §7.
+
+### Sui / Solana / etc.
+
+Replace `'EVM'` with the chain type the button targets — the migration is mechanical:
+
+```tsx
+const connectors = useXConnectors({ xChainType: 'SUI' });
+const { address } = useXAccount({ xChainType: 'SUI' });
+```
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Confirm no positional hook args remain in this file
+grep -nE "useXAccount\(['\"]" <file>
+grep -nE "useXConnectors\(['\"]" <file>
+# expect empty
+
+# 3. Manual — load page, click connect, confirm address renders
+```

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

@@ -0,0 +1,244 @@
+# 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

@@ -0,0 +1,162 @@
+# 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.