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

package/skills/evm-only-walletconnect.md

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

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

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