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

package/docs/WALLETCONNECT.md

@@ -0,0 +1,154 @@
+# WalletConnect
+
+Default EVM wallet discovery uses [EIP-6963](https://eips.ethereum.org/EIPS/eip-6963) — only browser-extension wallets surface. Partners using enterprise custody solutions (Fireblocks, Ledger Live, etc.) cannot install browser extensions; they need WalletConnect protocol to connect.
+
+`@sodax/wallet-sdk-react` enables WalletConnect via the `walletConnect` field on the `EVM` chain-type slot. The field extends wagmi's [`WalletConnectParameters`](https://wagmi.sh/core/api/connectors/walletConnect) directly — every wagmi option is available.
+
+The integration point is [`EvmProvider.tsx`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/providers/evm/EvmProvider.tsx).
+
+## Table of contents
+
+1. [When you need WalletConnect](#when-you-need-walletconnect)
+2. [Minimal setup](#minimal-setup)
+3. [Restrict the modal — Fireblocks-only example](#restrict-the-modal--fireblocks-only-example)
+4. [QR-modal stacking with `useWalletModal`](#qr-modal-stacking-with-usewalletmodal)
+5. [Missing `projectId` — silent skip](#missing-projectid--silent-skip)
+6. [WalletConnect is EVM-only](#walletconnect-is-evm-only)
+
+---
+
+## When you need WalletConnect
+
+Add WalletConnect when the partner's user can't install a browser extension:
+
+| Custody / wallet | Why WalletConnect |
+|---|---|
+| Fireblocks | No browser extension — workspace approval flows over WalletConnect |
+| Ledger Live | Hardware-wallet wrapper, no EIP-6963 injection |
+| Mobile-only wallets (Trust, Rainbow, MetaMask Mobile) | Browser session pairs with phone via QR |
+| Coinbase Smart Wallet | Pop-up + WC fallback |
+
+If your dApp only targets desktop browser wallets (MetaMask extension, Hana, Phantom EVM, etc.), you can omit `walletConnect` entirely — EIP-6963 covers them.
+
+---
+
+## Minimal setup
+
+1. Get a WalletConnect Cloud project id at [https://cloud.walletconnect.com](https://cloud.walletconnect.com).
+2. Pass it to `config.EVM.walletConnect.projectId`.
+
+```typescript
+import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
+    },
+    walletConnect: {
+      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
+      // showQrModal, isNewChainsStale, qrModalOptions, etc.
+    },
+  },
+};
+```
+
+A `walletConnect` connector is added to the wagmi config alongside any EIP-6963 wallets. `EvmHydrator` discovers it automatically — `useXConnectors({ xChainType: 'EVM' })` returns it in the same list as MetaMask, Hana, etc. **No UI changes required**.
+
+The default behavior (`showQrModal: true`) lets wagmi/WalletConnect own the QR display. Pass `showQrModal: false` only if you render a custom QR modal.
+
+---
+
+## Restrict the modal — Fireblocks-only example
+
+Some partners want **only** their custody wallet visible in the QR modal — no Trust / Rainbow / MetaMask Mobile noise. Use `qrModalOptions` to filter the WalletConnect Explorer list:
+
+```typescript
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    chains: { [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' } },
+    walletConnect: {
+      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
+      qrModalOptions: {
+        explorerRecommendedWalletIds: ['225affb176778569276e484e1b92637ad061b01e13a048b35a9d280c3b58970f'], // Fireblocks
+        explorerExcludedWalletIds: 'ALL', // hide everything except recommended
+      },
+    },
+  },
+};
+```
+
+Key `qrModalOptions` fields (extends `QrModalOptions` from `@walletconnect/ethereum-provider`):
+
+| Field | Effect |
+|-------|--------|
+| `explorerRecommendedWalletIds` | Wallet IDs to surface at the top of the list |
+| `explorerExcludedWalletIds` | Wallet IDs to hide. `'ALL'` hides everything except recommended |
+| `themeMode` | `'light' \| 'dark'` |
+| `themeVariables` | CSS custom-property overrides |
+
+Find wallet IDs in the [WalletConnect Explorer](https://walletconnect.com/explorer) — they're the long hex strings, not the human names.
+
+---
+
+## QR-modal stacking with `useWalletModal`
+
+When the user picks the WalletConnect connector inside `useWalletModal`'s `walletSelect` state, wagmi opens its own QR modal. While that modal is up, `useWalletModal` stays in `connecting` — two dialogs would stack.
+
+The SDK doesn't enforce a hide policy; partners decide. The recommended pattern is to render `null` while wagmi's modal is visible:
+
+```typescript
+import { useWalletModal } from '@sodax/wallet-sdk-react';
+
+function WalletModalRoot() {
+  const modal = useWalletModal();
+
+  if (
+    modal.state.kind === 'connecting' &&
+    modal.state.connector.id === 'walletConnect'
+  ) {
+    return null; // let wagmi's QR modal own the screen
+  }
+
+  // ... render the rest of the state machine
+}
+```
+
+The wagmi connector id is the literal string `'walletConnect'`. Resume rendering when the state transitions to `success` / `error`. See [`WALLET_MODAL.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md#walletconnect-qr-modal-caveat) for the full discussion.
+
+---
+
+## Missing `projectId` — silent skip
+
+If `walletConnect` is present but `projectId` is missing or empty, the WalletConnect connector is **silently skipped** at wagmi config time and a one-time warning is logged:
+
+```
+[wallet-sdk-react] walletConnect.projectId is required — WalletConnect connector skipped.
+```
+
+EIP-6963 wallets continue to work normally — the dApp degrades gracefully to extension-only mode. There is no runtime crash.
+
+This behavior intentionally avoids forcing every developer to plumb `projectId` through environment variables in dev — they can leave `walletConnect: { /* no projectId */ }` commented or empty during local work and re-enable for production.
+
+---
+
+## WalletConnect is EVM-only
+
+The `walletConnect` field exists only on the `EVM` slot. Other chain families (`SOLANA`, `BITCOIN`, etc.) use their own native wallet adapters and don't share the WalletConnect protocol layer.
+
+To support Solana via WalletConnect-equivalent protocols (Solana Wallet Standard, Mobile Wallet Adapter), use the appropriate connectors registered in the `SOLANA` chain registry — those don't go through this `walletConnect` field.
+
+---
+
+## Related docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md#walletconnect-evm-only) — full chain-type slot reference
+- [Wallet Modal](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md) — `useWalletModal` state machine + QR-stacking pattern
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — discover/connect/disconnect lifecycle
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — `IXConnector` contract; the WC connector surfaces with `id === 'walletConnect'`
+- [wagmi WalletConnect docs](https://wagmi.sh/core/api/connectors/walletConnect) — full `WalletConnectParameters` reference
+- [WalletConnect Cloud](https://cloud.walletconnect.com) — get a `projectId`

package/docs/WALLET_MODAL.md

@@ -0,0 +1,331 @@
+# Wallet Modal
+
+`useWalletModal` is a headless multi-chain wallet-connect lifecycle exposed as a discriminated state machine. It owns transitions between `closed → chainSelect → walletSelect → connecting → success | error`, dedupes concurrent connect attempts, and waits for provider-managed chains' Hydrators to land an account before signaling success. The hook is render-agnostic — pair it with any dialog, drawer, or inline UI.
+
+For non-modal flows (single button with status + retry), use [`useConnectionFlow`](#useconnectionflow--non-modal-alternative) instead.
+
+The canonical state union is [`WalletModalState`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/useWalletModalStore.ts).
+
+## Table of contents
+
+1. [State machine](#state-machine)
+2. [Hook API](#hook-api)
+3. [Rendering — switch on `state.kind`](#rendering--switch-on-statekind)
+4. [`selectWallet` lifecycle](#selectwallet-lifecycle)
+5. [Smart `back()` navigation](#smart-back-navigation)
+6. [`onConnected` side-effect callback](#onconnected-side-effect-callback)
+7. [Hydration timeout](#hydration-timeout)
+8. [WalletConnect QR modal caveat](#walletconnect-qr-modal-caveat)
+9. [Cancellation semantics](#cancellation-semantics)
+10. [`useConnectionFlow` — non-modal alternative](#useconnectionflow--non-modal-alternative)
+
+---
+
+## State machine
+
+```
+                       open()
+        ┌──────────────────────────────────────┐
+        │                                      ▼
+   ┌─────────┐                          ┌──────────────┐
+   │ closed  │ ◀─── close() ─────────── │ chainSelect  │
+   └─────────┘                          └──────────────┘
+        ▲                                      │
+        │                                      │ selectChain(chainType)
+        │ close() / back() ◀── success ◀───────┤
+        │                                      ▼
+        │                              ┌──────────────┐
+        │                              │ walletSelect │ ◀─── back() ─────┐
+        │                              └──────────────┘                  │
+        │                                      │                          │
+        │                          selectWallet(connector)                │
+        │                                      │                          │
+        │                                      ▼                          │
+        │                              ┌──────────────┐                   │
+        │                              │  connecting  │ ─── back() ───────┤
+        │                              └──────────────┘                   │
+        │                                  │       │                       │
+        │                              ok  │       │  err                  │
+        │                                  ▼       ▼                       │
+        │                            ┌─────────┐  ┌────────┐               │
+        └────── back() ◀──────────── │ success │  │ error  │ ──── back() ──┘
+                                     └─────────┘  └────────┘
+                                          │            │
+                                     onConnected     retry()
+                                          │
+                                       (consumer
+                                        calls
+                                        close())
+```
+
+Six discriminated states:
+
+| `state.kind` | Extra fields | Meaning |
+|---|---|---|
+| `'closed'` | — | Modal is dismissed |
+| `'chainSelect'` | — | User picks a chain family (EVM / SOLANA / …) |
+| `'walletSelect'` | `chainType` | User picks a wallet within the chosen family |
+| `'connecting'` | `chainType`, `connector` | `selectWallet` in flight, waiting for wallet popup |
+| `'success'` | `chainType`, `connector`, `account` | Connect resolved with a usable `XAccount` |
+| `'error'` | `chainType`, `connector`, `error` | Connect failed; consumer can call `retry()` |
+
+The state lives in `useWalletModalStore` — a Zustand slice **separate** from `useXWalletStore`. Modal lifecycle is ephemeral UI state with no persistence concerns; connection state is persisted independently. Direct store access is intentionally not part of the public surface — go through `useWalletModal()`.
+
+---
+
+## Hook API
+
+```typescript
+import { useWalletModal } from '@sodax/wallet-sdk-react';
+
+const modal = useWalletModal({
+  onConnected: async (chainType, account) => {
+    // app side-effects after a successful connect
+  },
+  hydrationTimeoutMs: 5_000, // optional, default 5000ms
+});
+
+// modal.state           — current WalletModalState (discriminated by `kind`)
+// modal.open()          — closed → chainSelect
+// modal.close()         — any → closed
+// modal.back()          — smart back (see below)
+// modal.selectChain(chainType)
+// modal.selectWallet(connector)  → Promise<XAccount | undefined>
+// modal.retry()         → Promise<XAccount | undefined>  — re-runs from `error` state
+```
+
+The `selectWallet` and `retry` promises **never reject**. Failures populate `state.kind === 'error'` instead — render the error branch and offer a retry button.
+
+---
+
+## Rendering — switch on `state.kind`
+
+```tsx
+import { useEffect } from 'react';
+import { useWalletModal } from '@sodax/wallet-sdk-react';
+
+// Side effects (closing the modal, navigation, etc.) must run from useEffect, not directly
+// during render — Strict Mode double-invokes renders in dev and would fire the effect twice.
+function AutoClose({ onMount }: { onMount: () => void }) {
+  useEffect(() => {
+    onMount();
+  }, [onMount]);
+  return null;
+}
+
+function WalletModalRoot() {
+  const modal = useWalletModal();
+
+  switch (modal.state.kind) {
+    case 'closed':
+      return <button onClick={modal.open}>Connect Wallet</button>;
+
+    case 'chainSelect':
+      return (
+        <Dialog onClose={modal.close}>
+          <ChainList onPick={modal.selectChain} />
+        </Dialog>
+      );
+
+    case 'walletSelect':
+      return (
+        <Dialog onClose={modal.close} onBack={modal.back}>
+          <WalletList chainType={modal.state.chainType} onPick={modal.selectWallet} />
+        </Dialog>
+      );
+
+    case 'connecting':
+      return (
+        <Dialog onClose={modal.close} onBack={modal.back}>
+          <Spinner connector={modal.state.connector} />
+          <p>Approve in {modal.state.connector.name}…</p>
+        </Dialog>
+      );
+
+    case 'success':
+      // Auto-close after onConnected fires.
+      return <AutoClose onMount={modal.close} />;
+
+    case 'error':
+      return (
+        <Dialog onClose={modal.close} onBack={modal.back}>
+          <p>{modal.state.error.message}</p>
+          {!modal.state.connector.isInstalled && modal.state.connector.installUrl && (
+            <a href={modal.state.connector.installUrl}>Install {modal.state.connector.name}</a>
+          )}
+          <button onClick={modal.retry}>Retry</button>
+        </Dialog>
+      );
+  }
+}
+```
+
+Render the modal in **one place** at the app root — the state lives in a Zustand slice, so any header CTA or inline button can dispatch `modal.open()` without prop drilling.
+
+---
+
+## `selectWallet` lifecycle
+
+`selectWallet(connector)` runs:
+
+1. **Pre-check `connector.isInstalled`** — if false, transition straight to `error` with an install hint. Avoids legacy connectors imperatively opening install pages from inside `connect()` and leaving the state stuck in `connecting`.
+2. **Transition to `connecting`** — sets `state = { kind: 'connecting', chainType, connector }`.
+3. **Call `useXConnect.mutateAsync(connector)`** — opens the wallet popup. Non-provider chains return the `XAccount` directly; provider-managed chains (EVM/Solana/Sui) return `undefined`.
+4. **For provider-managed chains, wait for the Hydrator** — subscribe to `useXWalletStore` and resolve when an `xConnections[chainType]` entry appears whose **`xConnectorId` matches the picked connector's id** (not just any address — see [`Cancellation semantics`](#cancellation-semantics)).
+5. **Transition to `success`** with the resolved account, then fire `onConnected`.
+6. **On error or timeout**, transition to `error`.
+
+The promise returned by `selectWallet` resolves with the `XAccount` on success or `undefined` on error/cancellation — never rejects.
+
+---
+
+## Smart `back()` navigation
+
+| From | `back()` goes to |
+|------|------------------|
+| `'walletSelect'` | `'chainSelect'` |
+| `'connecting'` | `'walletSelect'` (preserves `chainType`) |
+| `'error'` | `'walletSelect'` (preserves `chainType`) |
+| `'success'` | `'closed'` |
+| `'closed'` / `'chainSelect'` | no-op |
+
+`connecting` → back preserves the chain so the user can pick a different wallet without reselecting the chain. The in-flight connect attempt is **dropped** when `back()` fires (see [`Cancellation semantics`](#cancellation-semantics)).
+
+---
+
+## `onConnected` side-effect callback
+
+Fires once after a successful connect initiated through the modal. Use for app-specific side effects that don't belong in the SDK:
+
+```typescript
+const modal = useWalletModal({
+  onConnected: async (chainType, account) => {
+    await registerIfNew(chainType, account.address);
+    if (await needsTosAcceptance(account.address)) {
+      router.push('/terms');
+    }
+  },
+});
+```
+
+Throwing inside `onConnected` is **non-fatal** — it's logged and the modal stays in `success`. The connection is already persisted in the store; downgrading to `error` would mislead the UI into showing a retry button for a connect that actually succeeded.
+
+---
+
+## Hydration timeout
+
+For provider-managed chains (EVM/Solana/Sui), the connection becomes visible only when the Hydrator observes the native SDK's status flip. `hydrationTimeoutMs` caps how long `selectWallet` waits before transitioning to `error` with `Connection did not complete. Did you close the wallet popup?`.
+
+```typescript
+const modal = useWalletModal({
+  hydrationTimeoutMs: 15_000, // raise for slow networks / wallets
+});
+```
+
+Default: `5_000` ms. Ignored for non-provider chains (Bitcoin, ICON, Stellar, NEAR, Stacks, Injective) — those return the account directly from `connect()`.
+
+---
+
+## WalletConnect QR modal caveat
+
+When the user picks an EVM WalletConnect connector, wagmi opens **its own** QR modal as a third-party UI. While that QR modal is visible, `useWalletModal` stays in `connecting` — two dialogs would stack visually.
+
+The SDK doesn't bake in a hide policy because partners want different UX. Detect WC and conditionally render `null`:
+
+```typescript
+if (
+  modal.state.kind === 'connecting' &&
+  modal.state.connector.id === 'walletConnect'
+) {
+  return null; // let wagmi's QR modal own the screen
+}
+```
+
+The wagmi connector id is `'walletConnect'`. Resume rendering when the state transitions to `success` / `error`.
+
+---
+
+## Cancellation semantics
+
+The state machine handles three concurrency cases that would otherwise corrupt the UI:
+
+**Same connector double-clicked** — `selectWallet(connector)` returns the **same in-flight promise**, so two popups don't open and two state writes don't race.
+
+**Different connector picked mid-attempt** — starts a new attempt; the previous attempt's late resolution is dropped. The previous connect's wallet popup may still be open, but the modal won't transition to `success`/`error` for it.
+
+**`back()` / `close()` mid-attempt** — the in-flight attempt is cancelled at the modal layer. The wallet may already have approved by the time the user cancels — in that case `xConnections[chainType]` is populated by `useXConnect` / the Hydrator independently, but the modal stays in the user's chosen state (`walletSelect` or `closed`). **The account stays connected.** If full rollback is required, call `useXDisconnect({ xChainType })` from the same handler:
+
+```tsx
+const disconnect = useXDisconnect();
+
+<button
+  onClick={async () => {
+    modal.close();
+    if (modal.state.kind === 'connecting') {
+      await disconnect({ xChainType: modal.state.chainType });
+    }
+  }}
+>
+  Cancel
+</button>
+```
+
+The cancellation guard is implemented by reading the store directly (not the React snapshot) so user-driven transitions are observable inside the in-flight callback. See [`useWalletModal.ts`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/src/hooks/useWalletModal.ts) for the exact `isStillCurrent` check.
+
+---
+
+## `useConnectionFlow` — non-modal alternative
+
+When you don't need a multi-step modal — just `connect → status → retry` for a single button — use `useConnectionFlow`. It wraps `useXConnect` + `useXDisconnect` and surfaces the error on state instead of throwing.
+
+```tsx
+import { useConnectionFlow } from '@sodax/wallet-sdk-react';
+
+function ConnectButton({ connector }: { connector: IXConnector }) {
+  const { status, error, activeConnector, connect, retry, reset } = useConnectionFlow();
+
+  if (status === 'error' && error) {
+    if (activeConnector && !activeConnector.isInstalled) {
+      return <a href={activeConnector.installUrl ?? '#'}>Install {activeConnector.name}</a>;
+    }
+    return (
+      <div>
+        <p>{error.message}</p>
+        <button onClick={retry}>Retry</button>
+        <button onClick={reset}>Dismiss</button>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={() => connect(connector)} disabled={status === 'connecting'}>
+      {status === 'connecting' ? 'Waiting for wallet…' : `Connect ${connector.name}`}
+    </button>
+  );
+}
+```
+
+`useConnectionFlow` returns:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `status` | `'idle' \| 'connecting' \| 'success' \| 'error'` | Current attempt state |
+| `error` | `Error \| null` | Last failure |
+| `activeConnector` | `XConnector \| null` | Connector of the last attempt |
+| `activeChainType` | `ChainType \| null` | Convenience accessor |
+| `connect(connector)` | `Promise<XAccount \| undefined>` | Connect; never throws |
+| `disconnect({ xChainType })` | `Promise<void>` | Same as `useXDisconnect` |
+| `retry()` | `Promise<XAccount \| undefined>` | Re-runs the last `connect` |
+| `reset()` | `void` | Clears `status` / `error` / `activeConnector` |
+
+`connect()` and `retry()` never reject — errors flow into `error` so render code stays linear without `try/catch`.
+
+---
+
+## Related docs
+
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — the underlying `useXConnect` lifecycle
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — opt in chain-type slots before users can pick them
+- [Chain Detection](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md) — `useChainGroups` for the chain picker, `useIsWalletInstalled` for filtering
+- [WalletConnect](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLETCONNECT.md) — `walletConnect` slot config + Fireblocks/custody filters
+- [Connectors](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECTORS.md) — `IXConnector` contract for `selectWallet` argument