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

package/skills/evm-only-walletconnect.md

@@ -0,0 +1,111 @@
+# Skill: EVM-only WalletConnect
+
+Enable WalletConnect protocol on the EVM slot for partners using enterprise custody (Fireblocks, Ledger Live, mobile-only wallets). Default EVM discovery (EIP-6963) only finds browser-extension wallets — WalletConnect lets users pair via QR/deep-link.
+
+**Depends on:** [setup.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/setup.md)
+
+## When to use
+
+| Scenario | Need WalletConnect? |
+|----------|---------------------|
+| MetaMask / Hana / Rabby browser extension | ❌ — EIP-6963 covers them |
+| Fireblocks workspace | ✅ |
+| Ledger Live | ✅ |
+| MetaMask Mobile / Trust / Rainbow (paired via QR) | ✅ |
+| Coinbase Smart Wallet | ✅ (fallback path) |
+
+If your dApp only targets desktop browser-extension wallets, omit `walletConnect` entirely.
+
+## 1. Get a WalletConnect Cloud project id
+
+Sign up at [https://cloud.walletconnect.com](https://cloud.walletconnect.com) and copy your project id. Add it to `.env`:
+
+```bash
+NEXT_PUBLIC_WC_PROJECT_ID=your-project-id
+```
+
+## 2. Add `walletConnect` to the `EVM` slot
+
+```typescript
+import { 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: true is the default — wagmi/WalletConnect own the QR display
+    },
+  },
+};
+```
+
+A WalletConnect connector now surfaces alongside EIP-6963 wallets. `useXConnectors({ xChainType: 'EVM' })` returns it with `id === 'walletConnect'`. **No UI changes required** — the existing connect-button or modal already handles it.
+
+## 3. Restrict the QR modal — Fireblocks-only
+
+To show **only** Fireblocks (no Trust / Rainbow / etc. clutter), filter the WalletConnect Explorer list:
+
+```typescript
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    walletConnect: {
+      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID!,
+      qrModalOptions: {
+        explorerRecommendedWalletIds: [
+          '225affb176778569276e484e1b92637ad061b01e13a048b35a9d280c3b58970f', // Fireblocks
+        ],
+        explorerExcludedWalletIds: 'ALL', // hide everything except recommended
+      },
+    },
+  },
+};
+```
+
+Find wallet IDs at the [WalletConnect Explorer](https://walletconnect.com/explorer) — they're the long hex strings in URLs, not the human names.
+
+## 4. Hide the Sodax modal during WalletConnect QR
+
+When the user picks the WalletConnect connector, wagmi opens its own QR modal — two dialogs would stack. Detect WC by connector id and render `null`:
+
+```typescript
+import { useWalletModal } from '@sodax/wallet-sdk-react';
+
+const modal = useWalletModal();
+
+if (
+  modal.state.kind === 'connecting' &&
+  modal.state.connector.id === 'walletConnect'
+) {
+  return null; // wagmi's QR modal owns the screen
+}
+```
+
+The `useWalletModal` state machine handles the `connecting → success | error` transition normally — only the rendering is conditionally blanked.
+
+## Missing `projectId` — silent skip
+
+Setting `walletConnect: {}` without a `projectId` (or with an empty string) **silently skips** the WalletConnect connector and logs a warning:
+
+```
+[wallet-sdk-react] walletConnect.projectId is required — WalletConnect connector skipped.
+```
+
+EIP-6963 wallets continue to work normally — the dApp degrades gracefully. This intentionally avoids forcing local-dev environments to plumb the env var.
+
+## EVM-only
+
+The `walletConnect` field only exists on the `EVM` slot. Solana, Bitcoin, etc. use their own native wallet adapters and don't share the WalletConnect protocol layer. Don't attempt `SOLANA: { walletConnect: ... }` — TypeScript will reject it.
+
+## Reference docs
+
+- [WalletConnect](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLETCONNECT.md) — full integration reference
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md#walletconnect-evm-only) — per-chain config
+- [Wallet Modal QR caveat](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md#walletconnect-qr-modal-caveat) — modal stacking handling
+- [wagmi `WalletConnectParameters`](https://wagmi.sh/core/api/connectors/walletConnect) — full options reference
+- [WalletConnect Cloud](https://cloud.walletconnect.com) — get a `projectId`

package/skills/multi-chain-modal.md

@@ -0,0 +1,178 @@
+# Skill: Multi-chain Modal
+
+Headless wallet-connect modal that walks the user through `chainSelect → walletSelect → connecting → success | error`. Pair with `useChainGroups` for the chain picker and `useXConnectors` for the wallet picker. Render-agnostic — works with any dialog/drawer/inline UI.
+
+**Depends on:** [setup.md](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/setup.md)
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useWalletModal({ onConnected? })` | State machine + actions (`open`, `close`, `back`, `selectChain`, `selectWallet`, `retry`) |
+| `useChainGroups({ order? })` | One row per enabled chain family (EVM collapses to one row) |
+| `useXConnectors({ xChainType })` | Wallet list for the chosen chain family |
+| `useXAccount({ xChainType })` | Read the connected account when needed |
+
+## Render switch
+
+```tsx
+import {
+  useWalletModal,
+  useChainGroups,
+  useXConnectors,
+  type IXConnector,
+} from '@sodax/wallet-sdk-react';
+
+export function WalletModalRoot() {
+  const modal = useWalletModal({
+    onConnected: async (chainType, account) => {
+      // app side-effects (e.g. registration, ToS check)
+      console.log('connected', chainType, account.address);
+    },
+  });
+
+  switch (modal.state.kind) {
+    case 'closed':
+      return <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 is up for WalletConnect
+      if (modal.state.connector.id === 'walletConnect') return null;
+      return (
+        <Dialog onClose={modal.close}>
+          <p>Approve in {modal.state.connector.name}…</p>
+          <button onClick={modal.back}>Cancel</button>
+        </Dialog>
+      );
+
+    case 'success':
+      // onConnected fired; close after a beat
+      setTimeout(modal.close, 0);
+      return null;
+
+    case 'error':
+      return (
+        <Dialog onClose={modal.close}>
+          <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>
+          <button onClick={modal.back}>Pick another wallet</button>
+        </Dialog>
+      );
+  }
+}
+```
+
+Render `<WalletModalRoot />` once at the app root — any other component can dispatch `useWalletModal().open()` to show it.
+
+## Chain picker (driven by `useChainGroups`)
+
+```tsx
+import { useChainGroups } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+function ChainPicker({ onPick, onClose }: { onPick: (c: ChainType) => void; onClose: () => void }) {
+  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'BITCOIN', 'ICON'] });
+
+  return (
+    <Dialog onClose={onClose}>
+      <h2>Select a chain</h2>
+      {groups.map((group) => (
+        <button key={group.chainType} onClick={() => onPick(group.chainType)}>
+          {group.iconUrl && <img src={group.iconUrl} alt="" width={24} height={24} />}
+          <span>{group.displayName}</span>
+          {group.isConnected && <span>Connected</span>}
+        </button>
+      ))}
+    </Dialog>
+  );
+}
+```
+
+EVM collapses to a single group covering every configured EVM network — this matches reality (wagmi maintains one connection across all EVM chains).
+
+## Wallet picker (driven by `useXConnectors`)
+
+```tsx
+import { useXConnectors, sortConnectors, type IXConnector } from '@sodax/wallet-sdk-react';
+import type { ChainType } from '@sodax/types';
+
+function WalletPicker({
+  chainType,
+  onPick,
+  onBack,
+  onClose,
+}: {
+  chainType: ChainType;
+  onPick: (c: IXConnector) => void;
+  onBack: () => void;
+  onClose: () => void;
+}) {
+  const connectors = sortConnectors(useXConnectors({ xChainType: chainType }), {
+    preferred: ['hana', 'metamask', 'phantom'],
+  });
+
+  return (
+    <Dialog onClose={onClose}>
+      <button onClick={onBack}>← Back</button>
+      <h2>Select a wallet</h2>
+      {connectors.map((connector) => (
+        <button key={connector.id} onClick={() => onPick(connector)}>
+          {connector.icon && <img src={connector.icon} alt="" />}
+          {connector.name}
+          {!connector.isInstalled && ' (not installed)'}
+        </button>
+      ))}
+    </Dialog>
+  );
+}
+```
+
+## Concurrency rules
+
+- **Same connector double-click** → returns the same in-flight promise (no double popup).
+- **Different connector mid-attempt** → starts a new attempt; previous one's late resolution is dropped.
+- **`back()` / `close()` mid-attempt** → cancellation guard inside the modal layer; the wallet may still approve in the background but `success`/`error` won't fire. To roll back, call `useXDisconnect({ xChainType })` from the same handler.
+
+## `onConnected` is non-fatal
+
+Throwing inside `onConnected` is logged but **does not** downgrade `success` → `error`. The connection is already persisted; the user is genuinely connected.
+
+## Non-modal alternative — `useConnectionFlow`
+
+For a single-button flow without the multi-step modal:
+
+```tsx
+import { useConnectionFlow } from '@sodax/wallet-sdk-react';
+
+const { status, error, connect, retry, activeConnector } = useConnectionFlow();
+
+return (
+  <button onClick={() => connect(connector)} disabled={status === 'connecting'}>
+    {status === 'connecting' ? 'Waiting…' : 'Connect'}
+  </button>
+);
+```
+
+`connect()` and `retry()` never throw — errors flow into `error` state.
+
+## Reference docs
+
+- [Wallet Modal](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_MODAL.md) — full state machine + cancellation semantics
+- [Chain Detection](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CHAIN_DETECTION.md) — `useChainGroups` + ordering
+- [Connect Flow](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONNECT_FLOW.md) — underlying `useXConnect` lifecycle

package/skills/setup.md

@@ -0,0 +1,107 @@
+# Skill: Setup
+
+Install and wire `@sodax/wallet-sdk-react` into a React project.
+
+**Depends on:** None
+
+## Install
+
+```bash
+pnpm add @sodax/wallet-sdk-react @tanstack/react-query
+```
+
+Peer dependencies:
+
+```json
+{
+  "react": ">=19",
+  "@tanstack/react-query": "5.x"
+}
+```
+
+## Wire `SodaxWalletProvider`
+
+Top-level keys on `SodaxWalletConfig` are chain-type slots — **omit a slot to skip mounting that adapter**, pass `{}` to mount with SDK defaults. `<QueryClientProvider>` must wrap `<SodaxWalletProvider>`.
+
+```tsx
+// providers.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+const queryClient = new QueryClient();
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true, // Next.js — keep true for SSR-safe 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' },
+    },
+  },
+  ICON: {
+    chains: { [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' } },
+  },
+  // BITCOIN: {},  // mount with SDK defaults
+  // SOLANA: { chains: { [ChainKeys.SOLANA_MAINNET]: { rpcUrl: '...' } } },
+};
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+Use `Providers` at the app root (e.g. `app/layout.tsx` for Next.js, `main.tsx` for Vite).
+
+## Chain-type slots
+
+| Slot | Mounts | When to include |
+|------|--------|-----------------|
+| `EVM` | wagmi (12 EVM chains) | Sonic, Ethereum, Arbitrum, Base, BSC, etc. |
+| `SOLANA` | `@solana/wallet-adapter-react` | Solana support |
+| `SUI` | `@mysten/dapp-kit` | Sui support |
+| `BITCOIN` | (no React adapter) | Bitcoin support |
+| `STELLAR` | (no React adapter) | Stellar support |
+| `ICON` | (no React adapter) | ICON support |
+| `INJECTIVE` | (no React adapter) | Injective support |
+| `NEAR` | (no React adapter) | NEAR support |
+| `STACKS` | (no React adapter) | Stacks support |
+
+## Config is captured once on mount
+
+`SodaxWalletProvider` freezes the `config` prop on first render. Subsequent re-renders with a new reference have **no effect**. To swap config at runtime, remount with a new `key`:
+
+```tsx
+<SodaxWalletProvider key={configVersion} config={walletConfig}>
+  {children}
+</SodaxWalletProvider>
+```
+
+## Pair with `@sodax/dapp-kit` (optional)
+
+If you also use `@sodax/dapp-kit` for SDK feature hooks, mount `SodaxProvider` outermost:
+
+```tsx
+<SodaxProvider config={sodaxConfig}>
+  <QueryClientProvider client={queryClient}>
+    <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+  </QueryClientProvider>
+</SodaxProvider>
+```
+
+See [`packages/dapp-kit/skills/setup.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/dapp-kit/skills/setup.md) for the dapp-kit side.
+
+## Next steps
+
+- [`connect-button.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/connect-button.md) — single-chain connect/disconnect button
+- [`multi-chain-modal.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/multi-chain-modal.md) — multi-chain headless wallet modal
+- [`bridge-to-sdk.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/skills/bridge-to-sdk.md) — pass `walletProvider` to `@sodax/sdk` calls
+
+## Reference docs
+
+- [Configure SodaxWalletProvider](https://github.com/icon-project/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/CONFIGURE_PROVIDER.md) — full config reference, breaking changes from v1, per-chain `defaults`