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

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

@@ -1,156 +0,0 @@
-# Recipe: Connect Button
-
-Single-chain connect/disconnect button — pick a connector, connect, read the account, disconnect. Self-contained.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## Hooks used
-
-| Hook | Purpose |
-|------|---------|
-| `useXConnectors({ xChainType })` | List available connectors for the chain family |
-| `useXConnect()` | React Query mutation — `mutate(connector)` |
-| `useXAccount({ xChainType })` | Read connected account (always returns object — `address` is `undefined` when disconnected) |
-| `useXDisconnect()` | Returns `(xChainType) => Promise<void>` |
-| `sortConnectors(list, { preferred })` | Optional — rank installed/preferred wallets first |
-
----
-
-## Connect button
-
-```tsx
-'use client';
-
-import {
-  useXConnectors,
-  useXConnect,
-  useXAccount,
-  useXDisconnect,
-  sortConnectors,
-  type IXConnector,
-} from '@sodax/wallet-sdk-react';
-
-const PREFERRED = ['hana', 'metamask'] as const;
-
-export function EvmConnectButton() {
-  const raw = useXConnectors({ xChainType: 'EVM' });
-  const connectors = sortConnectors(raw, { preferred: PREFERRED });
-  const { mutateAsync: connect, isPending, error } = useXConnect();
-  const account = useXAccount({ xChainType: 'EVM' });
-  const disconnect = useXDisconnect();
-
-  if (account.address) {
-    return (
-      <div>
-        <code>{account.address}</code>
-        <button onClick={() => disconnect({ xChainType: 'EVM' })}>Disconnect</button>
-      </div>
-    );
-  }
-
-  return (
-    <div>
-      {connectors.map((connector) => (
-        <button
-          key={connector.id}
-          onClick={() => connect(connector).catch(() => {})}
-          disabled={isPending}
-        >
-          {connector.icon && <img src={connector.icon} alt="" width={20} height={20} />}
-          {connector.name}
-          {!connector.isInstalled && ' (not installed)'}
-        </button>
-      ))}
-      {error && <p style={{ color: 'red' }}>{error.message}</p>}
-    </div>
-  );
-}
-```
-
----
-
-## Install CTA for missing wallets
-
-```tsx
-{connectors.map((connector) =>
-  connector.isInstalled ? (
-    <button key={connector.id} onClick={() => connect(connector)}>
-      {connector.name}
-    </button>
-  ) : (
-    <a key={connector.id} href={connector.installUrl} target="_blank" rel="noreferrer">
-      Install {connector.name}
-    </a>
-  ),
-)}
-```
-
-`isInstalled` reads `window.*` at render time (no extra subscription). For batch install detection across wallet brands, use `useIsWalletInstalled` — see [`batch-operations.md`](./batch-operations.md).
-
----
-
-## Caveat — provider-managed chains resolve with `undefined`
-
-For EVM, Solana, and Sui, `connect(connector)` resolves with `undefined` because connection state is set asynchronously after the native SDK adapter reports `connected`. Always read the account via `useXAccount`, not the mutation's return value:
-
-```typescript
-const { mutateAsync: connect } = useXConnect();
-const account = useXAccount({ xChainType: 'EVM' });
-
-await connect(connector); // resolves with undefined for EVM
-// account.address is populated on the next render
-```
-
-Non-provider chains (Bitcoin, ICON, Injective, Stellar, NEAR, Stacks) return the resolved `XAccount` from `connect()` — but reading via `useXAccount` works for both, so default to it.
-
----
-
-## Multiple chains, one button
-
-For a "connect EVM + Solana + Bitcoin in one click" pattern, use [`batch-operations.md`](./batch-operations.md):
-
-```tsx
-import { useBatchConnect } from '@sodax/wallet-sdk-react';
-
-const { run, status } = useBatchConnect({ connectors: ['hana'] });
-// Connects every chain Hana supports — sequential, errors collected.
-<button onClick={run} disabled={status === 'running'}>
-  Connect Hana on all chains
-</button>;
-```
-
----
-
-## Variations
-
-### Per-chain-id button (e.g. one button per EVM network)
-
-⚠️ Not recommended for EVM — wagmi treats EVM as a **single connection across every configured network**. A per-Ethereum button rarely matches user expectations. If you really need per-chain-id resolution:
-
-```tsx
-import { ChainKeys } from '@sodax/types';
-
-const account = useXAccount({ xChainId: ChainKeys.ETHEREUM_MAINNET });
-```
-
-### Sui / Solana / etc.
-
-Replace `'EVM'` with the chain type the button targets:
-
-```tsx
-const connectors = useXConnectors({ xChainType: 'SUI' });
-const { address } = useXAccount({ xChainType: 'SUI' });
-```
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — load page, click connect, confirm address renders, reload page, confirm connection survives
-```

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

@@ -1,199 +0,0 @@
-# Recipe: Multi-Chain Wallet 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`](./setup.md)
-
----
-
-## Hooks used
-
-| 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
-'use client';
-
-import {
-  useWalletModal,
-  useChainGroups,
-  useXConnectors,
-  type IXConnector,
-} from '@sodax/wallet-sdk-react';
-
-export function WalletModalRoot() {
-  const modal = useWalletModal({
-    onConnected: async (chainType, account) => {
-      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
-
-```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
-
-```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.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — open modal, walk through chain → wallet → connecting → success → close
-# 3. Manual — pick non-installed wallet, confirm install link appears in error state
-```

package/ai-exported/integration/recipes/setup.md

@@ -1,158 +0,0 @@
-# Recipe: Setup
-
-Install and wire `@sodax/wallet-sdk-react` into a React project. **Always do this first** — every other recipe assumes `SodaxWalletProvider` is mounted.
-
-**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. Drop for Vite/CRA.
-    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>
-  );
-}
-```
-
----
-
-## Mount point per framework
-
-| Framework | Where to mount `<Providers>` | `EVM.ssr` |
-|---|---|---|
-| Next.js (App Router) | `app/layout.tsx`, inside `<body>`. Mark the providers file `'use client'`. Pair with [`recipes/ssr-setup.md`](../../migration/recipes/ssr-setup.md) if you need wagmi cookie hydration. | `true` |
-| Vite + React | `main.tsx`, wrap `<App />` directly. | omit (defaults `false`) |
-| Create React App | `index.tsx`, wrap `<App />` directly. | omit |
-| Remix / Tanstack Start | Root route component, marked client-only. Same as Next.js. | `true` |
-
----
-
-## Chain-type slots
-
-| Slot | React adapter mounted? | Notes |
-|---|---|---|
-| `EVM` | ✅ wagmi | One connection across every configured EVM chain. WalletConnect opt-in via `EVM.walletConnect.projectId`. |
-| `SOLANA` | ✅ `@solana/wallet-adapter-react` | `autoConnect` defaults to `true`. |
-| `SUI` | ✅ `@mysten/dapp-kit` | `network` defaults to `'mainnet'`. |
-| `BITCOIN` / `STELLAR` / `ICON` / `INJECTIVE` / `NEAR` / `STACKS` | ❌ no React adapter | Service auto-registered at mount. Connector list shipped per chain. |
-
-For chain key constants and per-chain entry shapes, see [`../reference/chain-support.md`](../reference/chain-support.md).
-
----
-
-## Enable WalletConnect (optional)
-
-Add WalletConnect support for Fireblocks / Ledger Live / mobile-only EVM wallets by setting `EVM.walletConnect.projectId`:
-
-```tsx
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    ssr: true,
-    walletConnect: {
-      projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!,
-      // Optional: showQrModal, metadata, qrModalOptions — see WalletConnectParameters
-    },
-    chains: { /* ... */ },
-  },
-};
-```
-
-Get a project ID from [cloud.walletconnect.com](https://cloud.walletconnect.com). Omit `walletConnect` entirely to disable — v2 falls back to EIP-6963 injected wallets only. Full pattern in [`walletconnect-setup.md`](./walletconnect-setup.md).
-
----
-
-## 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>
-```
-
-`SodaxProvider` (from dapp-kit) wraps the lot. `QueryClientProvider` must wrap `SodaxWalletProvider` because hooks inside use React Query.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Provider mounted exactly once
-grep -rn "SodaxWalletProvider" <user-src> --include="*.tsx" | grep -v "import" | wc -l
-# expect 1
-
-# 3. QueryClientProvider wraps SodaxWalletProvider
-# (manual — confirm nesting in providers.tsx)
-```
-
----
-
-## Next steps
-
-- [`connect-button.md`](./connect-button.md) — single-chain connect/disconnect button
-- [`multi-chain-modal.md`](./multi-chain-modal.md) — multi-chain headless wallet modal
-- [`bridge-to-sdk.md`](./bridge-to-sdk.md) — pass `walletProvider` to `@sodax/sdk` calls

package/ai-exported/integration/recipes/sign-message.md

@@ -1,137 +0,0 @@
-# Recipe: Sign Message
-
-`useXSignMessage` is a single React Query mutation that delegates message signing to the connected wallet's per-chain `signMessage` implementation. The signature shape and encoding rules differ per chain — Bitcoin in particular auto-selects between BIP-322 and ECDSA based on the connected address type.
-
-**Depends on:** [`setup.md`](./setup.md), one of [`connect-button.md`](./connect-button.md) / [`multi-chain-modal.md`](./multi-chain-modal.md)
-
----
-
-## Hook API
-
-```typescript
-import { useXSignMessage } from '@sodax/wallet-sdk-react';
-
-const sign = useXSignMessage();
-
-const signature = await sign.mutateAsync({
-  xChainType: 'EVM',
-  message: 'Sign in to MyDApp\nNonce: abc123',
-});
-// signature: `0x${string}` | Uint8Array | string | undefined
-```
-
-| Field | Type | Notes |
-|-------|------|-------|
-| `xChainType` | `ChainType` | Which chain to sign with (`'EVM'`, `'BITCOIN'`, …) |
-| `message` | `string` | Plain UTF-8; per-chain wrappers handle encoding |
-
-Return type is the discriminated union `` `0x${string}` | Uint8Array | string | undefined `` because each chain returns its native signature shape (hex for EVM, base64 for Stellar, base58 for Solana, etc.). Cast or branch on `xChainType` when consuming.
-
-`undefined` is returned (not thrown) when the chain doesn't implement `signMessage` — currently only ICON. A one-time `console.warn` accompanies the `undefined`.
-
----
-
-## Per-chain support matrix
-
-| Chain | Implementation | Signature shape |
-|-------|----------------|-----------------|
-| EVM | `signMessageAsync` from wagmi → personal_sign | `` `0x${string}` `` |
-| Solana | `signMessage` from `@solana/wallet-adapter` | `Uint8Array` |
-| Sui | `signPersonalMessage` from `@mysten/dapp-kit` | `string` (base64 signature + bytes) |
-| Bitcoin | Auto-detect: BIP-322 (P2WPKH/P2TR) or ECDSA (P2SH/P2PKH) | `string` |
-| Stellar | `walletsKit.signMessage` from `@creit.tech/stellar-wallets-kit` | `string` (base64) |
-| Injective | `walletStrategy.signArbitrary` from `@injectivelabs/wallet-base` | `string` |
-| NEAR | NEAR connector's `signMessage` | `string` |
-| Stacks | `signMessage` from `@stacks/connect` | `string` |
-| **ICON** | **Not supported** — Hana wallet does not expose a signing API | `undefined` |
-
----
-
-## Bitcoin — BIP-322 vs ECDSA auto-detect
-
-Bitcoin's signing flow inspects the connected address and picks the right method automatically:
-
-| Address type | Signing method | Connectors that support it |
-|--------------|----------------|----------------------------|
-| P2WPKH (native segwit, `bc1q…`) | BIP-322 | Unisat, Xverse, OKX |
-| P2TR (taproot, `bc1p…`) | BIP-322 | Unisat, Xverse, OKX |
-| P2SH (legacy multi-sig, `3…`) | ECDSA | Unisat, Xverse, OKX |
-| P2PKH (legacy, `1…`) | ECDSA | Unisat, Xverse, OKX |
-
-If a custom connector implements only one of the two methods, calling `signMessage` from a wrongly-typed address surfaces the error inline.
-
-The same logic mirrors the SDK's `BitcoinSpokeProvider.authenticateWithWallet` — the React layer doesn't reinvent the dispatch.
-
----
-
-## ICON not supported
-
-Hana wallet on ICON exposes account / transaction APIs but no general-purpose `signMessage` endpoint. `sign.mutateAsync({ xChainType: 'ICON' })` returns `undefined` and logs:
-
-```
-[useXSignMessage] signMessage not supported for chain "ICON"
-```
-
-If you need a signature on ICON for SIWE-style auth, fall back to a transaction-based proof or skip ICON in your auth flow.
-
----
-
-## Error handling
-
-```tsx
-'use client';
-
-import { useXSignMessage } from '@sodax/wallet-sdk-react';
-
-export function SignButton() {
-  const sign = useXSignMessage();
-
-  const handleSign = async () => {
-    try {
-      const signature = await sign.mutateAsync({
-        xChainType: 'EVM',
-        message: 'Sign in',
-      });
-      if (!signature) {
-        // ICON or other unsupported chain
-        return;
-      }
-      submitSignature(signature);
-    } catch (error) {
-      // User rejection, wallet disconnect mid-sign, address mismatch, etc.
-      console.error('sign failed:', error);
-    }
-  };
-
-  return (
-    <button onClick={handleSign} disabled={sign.isPending}>
-      {sign.isPending ? 'Waiting for wallet…' : 'Sign'}
-    </button>
-  );
-}
-```
-
-Common error messages by chain:
-
-| Chain | Typical error |
-|-------|---------------|
-| EVM | `User rejected the request` (MetaMask), `User denied message signature` (Rabby) |
-| Solana | `WalletSignMessageError: User rejected the request` |
-| Sui | `User rejected the signature request` |
-| Bitcoin | `<connector.id> does not support BIP-322 signing` (mismatch with address type), `User canceled the request` |
-| Stellar | `Stellar signature not found` |
-| Injective | `Injective signature not found`, `Injective address not found` |
-
-`mutation.error` reflects the latest failure; `mutation.isError` / `mutation.isPending` follow standard React Query semantics.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — connect wallet, click sign button, approve in wallet, confirm signature in handler
-# 3. Manual — reject the signature, confirm error renders
-```