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

package/ai-exported/integration/recipes/batch-operations.md

@@ -1,223 +0,0 @@
-# Recipe: Batch Connect / Disconnect
-
-`useBatchConnect` and `useBatchDisconnect` orchestrate multi-chain wallet operations sequentially using **wallet brand identifiers** (e.g. `'hana'`, `'phantom'`) instead of individual connectors. Pass an identifier and the hooks discover every chain that wallet supports across the registry, then connect/disconnect them in order.
-
-Sequential by design — many extensions share popup singletons, so parallel attempts would race a single popup. Errors are collected, not thrown — `run()` always resolves.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## Identifier matching
-
-Both batch hooks (and `useIsWalletInstalled`) take a `connectors: readonly string[]` field. Each entry is a **wallet brand identifier** matched **case-insensitive substring** against `connector.id` and `connector.name`:
-
-| Identifier | Matches connectors |
-|------------|--------------------|
-| `'hana'` | Hana on EVM (`io.havah.hana`), Hana on ICON (`hana`), Hana on Sui, Hana on Stellar… |
-| `'phantom'` | Phantom on Solana (`phantom`), Phantom on EVM (`app.phantom`) |
-| `'metamask'` | MetaMask on EVM (`io.metamask`), Injective MetaMask connector |
-| `'xverse'` | Xverse on Bitcoin (`xverse`), Xverse on Stacks (`XverseProviders.BitcoinProvider`) |
-
-For the full list of known wallet brands and a runtime-discovery snippet (paste-in component that lists every connector available in your app), see [`../reference/wallet-brands.md`](../reference/wallet-brands.md).
-
-Earlier identifiers in the array are **higher-priority per chain**. The runner uses **fallback-on-failure**:
-
-- If a chain matches `'hana'` but the Hana popup is denied / errors out, the runner tries the next identifier's connector on that same chain (e.g. Phantom).
-- If a chain succeeds on the first identifier, later identifiers for that chain are **silently skipped** — only one popup per chain on the happy path.
-- A chain ends up in `result.failed` only when **every** matched identifier's connector has failed.
-
-```typescript
-// Prefer Hana on every chain it covers; fall back to Phantom either
-// because Hana isn't available (e.g. Solana) OR because its popup failed.
-const { run } = useBatchConnect({ connectors: ['hana', 'phantom'] });
-```
-
-`onProgress` fires per attempt — a chain can emit a `failure` event followed by a `success` event when fallback kicks in. The final outcome lives in `result`.
-
-To target a specific connector (not a brand), bypass this API and use `useXConnectors({ xChainType }).find(c => c.id === '...')` + `useXConnect` directly.
-
----
-
-## `useBatchConnect`
-
-Connect every chain where one of the supplied identifiers matches an installed connector. Sequential, never throws, dedupes concurrent runs.
-
-```tsx
-'use client';
-
-import { useBatchConnect } from '@sodax/wallet-sdk-react';
-
-export function ConnectAllHana() {
-  const { run, status, result, reset } = useBatchConnect({
-    connectors: ['hana'],
-    skipConnected: true, // skip chains already connected at run() time
-    onProgress: event => {
-      console.log(`[batch] ${event.chainType}: ${event.outcome}`);
-    },
-  });
-
-  return (
-    <div>
-      <button onClick={run} disabled={status === 'running'}>
-        {status === 'running' ? 'Connecting all Hana chains…' : 'Connect with Hana'}
-      </button>
-      {status === 'done' && result && (
-        <div>
-          <p>{result.successful.length} connected</p>
-          <p>{result.failed.length} failed</p>
-          <p>{result.skipped.length} skipped</p>
-          <button onClick={reset}>Reset</button>
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-### Options
-
-| Field | Type | Effect |
-|-------|------|--------|
-| `connectors` | `readonly string[]` | Identifiers (required, non-empty) |
-| `skipConnected` | `boolean` | Skip chains already holding an account at `run()` time. Default `false` |
-| `onProgress` | `(event) => void` | Per-target progress event |
-
-### Result shape
-
-```typescript
-type BatchConnectResult = {
-  successful: ChainType[];
-  failed: Array<{ chainType: ChainType; error: Error }>;
-  skipped: ChainType[];
-};
-```
-
-`run()` returns `Promise<BatchConnectResult>` — never rejects.
-
----
-
-## `useBatchDisconnect`
-
-Mirror of `useBatchConnect` for disconnect:
-
-```tsx
-import { useBatchDisconnect } from '@sodax/wallet-sdk-react';
-
-function DisconnectAll() {
-  const { run, status } = useBatchDisconnect();
-  // No `connectors` → disconnect every currently-connected chain regardless of wallet
-
-  return (
-    <button onClick={run} disabled={status === 'running'}>
-      {status === 'running' ? 'Disconnecting…' : 'Disconnect all chains'}
-    </button>
-  );
-}
-
-function DisconnectHanaOnly() {
-  const { run } = useBatchDisconnect({ connectors: ['hana'] });
-  // Only disconnect chains whose CURRENTLY ACTIVE connector matches 'hana'
-  return <button onClick={run}>Disconnect Hana</button>;
-}
-```
-
-### Scope difference vs `useBatchConnect`
-
-`useBatchConnect.connectors` is **mandatory** — it picks **which connector** to use on each chain.
-
-`useBatchDisconnect.connectors` is **optional** — it filters **which chains** to disconnect by checking the **currently active** connector against the identifiers. Chains where the active connector doesn't match are left untouched.
-
-```typescript
-useBatchDisconnect();                                // Disconnect every chain
-useBatchDisconnect({ connectors: ['hana'] });        // Disconnect chains where Hana is active
-useBatchDisconnect({ connectors: ['hana', 'xverse'] }); // Hana OR Xverse
-```
-
----
-
-## Wallet install detection — `useIsWalletInstalled`
-
-Companion read hook that uses the same identifier matching to detect whether a wallet brand is installed for any (or specific) chain.
-
-```typescript
-import { useIsWalletInstalled } from '@sodax/wallet-sdk-react';
-
-// True if any Hana variant is installed across any enabled chain
-const isHanaInstalled = useIsWalletInstalled({ connectors: ['hana'] });
-
-// True if any wallet is installed for the given chain
-const hasBitcoinWallet = useIsWalletInstalled({ chainType: 'BITCOIN' });
-
-// AND filter — Hana specifically on EVM
-const hanaOnEvm = useIsWalletInstalled({ connectors: ['hana'], chainType: 'EVM' });
-```
-
-The options union enforces at the type level that **at least one** of `connectors` / `chainType` is present. Use this hook to gate an `useBatchConnect` button:
-
-```tsx
-const isInstalled = useIsWalletInstalled({ connectors: ['hana'] });
-const { run } = useBatchConnect({ connectors: ['hana'] });
-
-return isInstalled ? (
-  <button onClick={run}>Connect Hana</button>
-) : (
-  <a href="https://hana-wallet.com">Install Hana</a>
-);
-```
-
----
-
-## Status lifecycle and concurrency
-
-| `status` | Meaning |
-|----------|---------|
-| `'idle'` | Initial / after `reset()` |
-| `'running'` | A `run()` is in flight |
-| `'done'` | The last `run()` settled — `result` is populated |
-
-**Concurrent `run()` calls are deduped** — the second call returns the existing in-flight promise.
-
-**`reset()` does NOT abort an in-flight batch** — there is no cancellation signal. It only clears the observable `status` / `result`. Typical usage: call `reset()` only after `status === 'done'`.
-
----
-
-## Progress events
-
-```typescript
-const { run } = useBatchConnect({
-  connectors: ['hana'],
-  onProgress: event => {
-    switch (event.outcome) {
-      case 'success': toast(`✓ Connected ${event.chainType}`); break;
-      case 'failure': toast.error(`✗ ${event.chainType}: ${event.error.message}`); break;
-      case 'skipped': toast(`⏭ ${event.chainType} already connected`); break;
-    }
-  },
-});
-```
-
-`onProgress` is read from a ref each time, so passing an inline arrow function is safe.
-
----
-
-## When to use the lower-level hooks instead
-
-Reach for `useXConnect` / `useXDisconnect` directly when:
-
-- **You need a specific connector**, not a brand.
-- **Order is user-driven**, not registry-driven.
-- **You need cancellation** — batch hooks have no cancel signal.
-- **You only have one chain to operate on**.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — install Hana, click batch connect button, confirm sequential popups across chains
-# 3. Manual — confirm result.failed contains chains where Hana isn't available
-```

package/ai-exported/integration/recipes/bridge-to-sdk.md

@@ -1,164 +0,0 @@
-# Recipe: Bridge to `@sodax/sdk`
-
-Pass the user's connected wallet to `@sodax/sdk` calls — `useWalletProvider` returns a typed `IXxxWalletProvider` ready to plug into any SDK method.
-
-**Depends on:** [`setup.md`](./setup.md), one of [`connect-button.md`](./connect-button.md) / [`multi-chain-modal.md`](./multi-chain-modal.md)
-
-**Requires also:** `pnpm add @sodax/sdk` — this package does not depend on `@sodax/sdk`. Install it separately in the consumer app.
-
----
-
-## Hooks used
-
-| Hook | Purpose |
-|------|---------|
-| `useWalletProvider({ xChainId })` | Typed `IXxxWalletProvider` (chain-narrowed by chain id) |
-| `useWalletProvider({ xChainType })` | Family-level provider (same shape for every chain id in family) |
-| `useXAccount({ xChainId })` | Read connected address |
-| `useXService({ xChainType })` | Lower-level — chain `XService` instance for advanced reads |
-
-Pass either `xChainId` (a `SpokeChainKey`) or `xChainType` (a `ChainType`), never both.
-
----
-
-## Pattern — drive an SDK swap from a connected wallet
-
-```tsx
-import { useWalletProvider, useXAccount } from '@sodax/wallet-sdk-react';
-import { Sodax, ChainKeys } from '@sodax/sdk';
-import type { CreateIntentParams } from '@sodax/sdk';
-
-const sodax = new Sodax(); // or hold one in context / pass via @sodax/dapp-kit
-
-export function SwapButton({ params }: { params: CreateIntentParams<typeof ChainKeys.BSC_MAINNET> }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-  const account = useXAccount({ xChainId: ChainKeys.BSC_MAINNET });
-
-  const handleSwap = async () => {
-    if (!walletProvider) return;
-    const result = await sodax.swaps.swap({
-      params,
-      walletProvider, // typed as IEvmWalletProvider — must match BSC src chain
-    });
-    if (!result.ok) {
-      console.error('swap failed:', result.error);
-      return;
-    }
-    console.log('swap submitted:', result.value);
-  };
-
-  return (
-    <button onClick={handleSwap} disabled={!walletProvider || !account.address}>
-      Swap
-    </button>
-  );
-}
-```
-
-The pattern works for every SDK feature service:
-
-```typescript
-sodax.swaps.swap({ params, walletProvider });
-sodax.bridge.bridge({ params, walletProvider });
-sodax.moneyMarket.supply({ params, walletProvider });
-sodax.staking.stake({ params, walletProvider });
-sodax.dex.deposit({ params, walletProvider });
-```
-
----
-
-## TypeScript narrowing
-
-```typescript
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-// By chain id — narrowest typing
-const evm = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-// evm: IEvmWalletProvider | undefined
-
-const sol = useWalletProvider({ xChainId: ChainKeys.SOLANA_MAINNET });
-// sol: ISolanaWalletProvider | undefined
-
-// By chain type — family-level (one wagmi connection covers all EVM chains)
-const evmFamily = useWalletProvider({ xChainType: 'EVM' });
-// evmFamily: IEvmWalletProvider | undefined
-```
-
-Passing the wrong wallet provider type to an SDK call (e.g. `ISolanaWalletProvider` to a `srcChainKey: BSC_MAINNET` swap) is a **compile error**.
-
----
-
-## EVM — single connection across all networks
-
-`useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET })` and `useWalletProvider({ xChainId: ChainKeys.ARBITRUM_MAINNET })` return the **same** `EvmWalletProvider` instance — wagmi maintains one connection across all configured EVM networks. To switch the **active** EVM network:
-
-```tsx
-import { useEvmSwitchChain } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/types';
-
-const { isWrongChain, handleSwitchChain } = useEvmSwitchChain({
-  xChainId: ChainKeys.BSC_MAINNET,
-});
-
-if (isWrongChain) {
-  return <button onClick={handleSwitchChain}>Switch to BSC</button>;
-}
-```
-
----
-
-## Disabled chains return `undefined`
-
-If `xChainType` resolves to a chain not enabled in `SodaxWalletProvider` config, `useWalletProvider` returns `undefined` and logs a one-time warning:
-
-```
-[useWalletProvider] chain "BITCOIN" is not enabled in SodaxWalletProvider config.chains — returning undefined
-```
-
-Always null-check before passing to an SDK call.
-
----
-
-## Raw transactions — skip the bridge
-
-If you only need unsigned transaction data (manual relay, gas estimation, external signing), pass `raw: true` to the SDK and skip `walletProvider`:
-
-```typescript
-const result = await sodax.swaps.createIntent({
-  params,
-  raw: true, // walletProvider must be absent — compile error if passed
-});
-// result.value.tx is an EvmRawTransaction
-```
-
----
-
-## Server / scripts — use `@sodax/wallet-sdk-core` directly
-
-For Node.js scripts / bots, skip wallet-sdk-react entirely:
-
-```typescript
-import { Sodax } from '@sodax/sdk';
-import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
-import { ChainKeys } from '@sodax/types';
-
-const sodax = new Sodax();
-const walletProvider = new EvmWalletProvider({
-  privateKey: process.env.PRIVATE_KEY!,
-  chainId: ChainKeys.BSC_MAINNET,
-  rpcUrl: 'https://bsc-dataseed.binance.org',
-});
-const result = await sodax.swaps.swap({ params, walletProvider });
-```
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — connect wallet, click SDK action button, confirm transaction prompts in wallet
-```

package/ai-exported/integration/recipes/chain-detection.md

@@ -1,254 +0,0 @@
-# Recipe: Chain & Wallet Detection
-
-Aggregate views over the wallet store — what's enabled, what's connected, what's installed. Use these hooks to render chain pickers, "manage connections" panels, install CTAs, and hydration-safe UIs.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## Hooks at a glance
-
-| Hook | Purpose |
-|------|---------|
-| `useEnabledChains()` | List chain types mounted in `SodaxWalletProvider` config |
-| `useChainGroups({ order? })` | One row per enabled chain (with display + connection metadata) — for chain pickers |
-| `useConnectedChains({ order? })` | List of currently-connected chains + hydration `status` — for "manage connections" |
-| `useIsWalletInstalled({ connectors?, chainType? })` | Cross-chain install check — for gating "Install X" CTA |
-
-EVM **collapses to a single row** — wagmi maintains one connection across every configured EVM network.
-
----
-
-## `useEnabledChains` — what's mounted
-
-```tsx
-import { useEnabledChains } from '@sodax/wallet-sdk-react';
-
-const enabled = useEnabledChains();
-// e.g. ['EVM', 'SOLANA', 'BITCOIN']
-```
-
-Returns the slot keys in `SodaxWalletConfig` (`config.EVM`, `config.SOLANA`, …), not which chains have a wallet connected. Use cases:
-
-- Render only chain rows the dApp opted into.
-- Cross-reference with `useXConnections()` to compute "of N enabled chains, M are connected".
-- Drive `<Tabs>` / `<Select>` UIs without hard-coding a list.
-
-`useChainGroups` and `useConnectedChains` already filter by `useEnabledChains` internally — reach for it directly only when you need the raw list.
-
----
-
-## `useChainGroups` — chain picker model
-
-One `ChainGroup` per enabled chain type, with display metadata + connection status. Designed for the "select a chain" step in modals.
-
-```tsx
-'use client';
-
-import { useChainGroups } from '@sodax/wallet-sdk-react';
-import type { ChainType } from '@sodax/types';
-
-export function ChainPicker({ onPick }: { onPick: (c: ChainType) => void }) {
-  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'BITCOIN', 'ICON'] });
-
-  return (
-    <ul>
-      {groups.map((group) => (
-        <li key={group.chainType}>
-          <button onClick={() => onPick(group.chainType)}>
-            {group.iconUrl && <img src={group.iconUrl} alt="" width={24} height={24} />}
-            <span>{group.displayName}</span>
-            {group.isConnected && <span className="badge">Connected</span>}
-          </button>
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-### `ChainGroup` shape
-
-| Field | Type | Source |
-|-------|------|--------|
-| `chainType` | `ChainType` | The slot key (`'EVM'`, `'SOLANA'`, …) |
-| `chainIds` | `readonly SpokeChainKey[]` | All chain keys sharing this `chainType` (e.g. all 12 EVM `ChainKeys.*` for `'EVM'`) |
-| `displayName` | `string` | Default per-chain display name |
-| `iconUrl` | `string \| undefined` | `undefined` = SDK doesn't ship one — provide your own |
-| `isConnected` | `boolean` | `true` when an account is connected for this chain |
-| `account` | `XAccount \| undefined` | Connected account |
-| `connectorId` | `string \| undefined` | Active connector id when connected |
-
-EVM's `chainIds` lists every configured EVM `ChainKey`, but the group itself is **one row**. Per-network switching belongs to [`switch-chain.md`](./switch-chain.md), not a separate group.
-
----
-
-## `useConnectedChains` — connected list with hydration gate
-
-Returns one entry per **currently-connected** chain (skipping the rest), with enriched connector metadata for "manage connections" UIs and status badges.
-
-```tsx
-'use client';
-
-import { useConnectedChains } from '@sodax/wallet-sdk-react';
-
-export function ConnectionList() {
-  const { chains, total, status } = useConnectedChains();
-
-  if (status === 'loading') return <Skeleton />;
-  if (total === 0) return <ConnectCta />;
-
-  return (
-    <ul>
-      {chains.map((chain) => (
-        <li key={chain.chainType}>
-          {chain.connectorIcon && <img src={chain.connectorIcon} alt="" />}
-          <span>{chain.connectorName ?? chain.connectorId}</span>
-          <code>{chain.account.address}</code>
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-### `ConnectedChain` shape
-
-| Field | Type | Notes |
-|-------|------|-------|
-| `chainType` | `ChainType` | |
-| `account` | `XAccount` | Always populated (only included when address is non-empty) |
-| `connectorId` | `string` | The persisted active connector |
-| `connectorName` | `string \| undefined` | Looked up in `xConnectorsByChain` |
-| `connectorIcon` | `string \| undefined` | |
-
-### Result shape
-
-```typescript
-type UseConnectedChainsResult = {
-  chains: ConnectedChain[];
-  total: number;
-  status: 'loading' | 'ready';
-};
-```
-
----
-
-## `useIsWalletInstalled` — install detection
-
-Read hook for gating "Connect" buttons on actual installation. Same identifier matching as `useBatchConnect` — see [`batch-operations.md`](./batch-operations.md).
-
-```typescript
-import { useIsWalletInstalled } from '@sodax/wallet-sdk-react';
-
-// True if any Hana variant is installed across all enabled chains
-const hasHana = useIsWalletInstalled({ connectors: ['hana'] });
-
-// True if any wallet is installed for Bitcoin specifically
-const hasBitcoinWallet = useIsWalletInstalled({ chainType: 'BITCOIN' });
-
-// AND filter — Hana specifically on EVM
-const hanaOnEvm = useIsWalletInstalled({ connectors: ['hana'], chainType: 'EVM' });
-```
-
-The type union enforces at compile time that **at least one of `connectors` / `chainType`** is present — `useIsWalletInstalled({})` is a type error. `connectors: []` is explicit "match nothing" — returns `false`.
-
----
-
-## Hydration status — gate reload flicker
-
-`useConnectedChains` exposes `status: 'loading' | 'ready'`. Use it to avoid the "Connect wallet" → "Connected" flash on page reload while Zustand rehydrates from `localStorage`:
-
-```tsx
-const { chains, status } = useConnectedChains();
-
-// ❌ Flicker — `chains` is empty for one render before hydration completes
-return chains.length >= 1 ? <Connected /> : <ConnectCta />;
-
-// ✅ No flicker — wait for hydration before deciding
-return status === 'loading'
-  ? <Skeleton />
-  : chains.length >= 1 ? <Connected /> : <ConnectCta />;
-```
-
-For first-paint correctness in SSR (Next.js), prefer `useConnectedChains.status` over an ad-hoc `useEffect(() => setMounted(true), [])` pattern — it's the official hydration signal.
-
-`useChainGroups` does **not** expose this flag — its outputs are stable across hydration because connection-status fields (`isConnected`, `account`) start as `false` / `undefined` and gain values atomically when the persist middleware finishes.
-
----
-
-## Display ordering
-
-Both `useChainGroups` and `useConnectedChains` accept an `order?: readonly ChainType[]`:
-
-1. Chains in the array render in array order.
-2. Chains **not** in the array fall to the bottom, sorted alphabetically.
-3. Without `order`:
-   - `useChainGroups` follows the order of slots in `walletConfig` (config object key order).
-   - `useConnectedChains` follows `ChainTypeArr` from `@sodax/types` — stable across reloads.
-
-```typescript
-const groups = useChainGroups({ order: ['EVM', 'ICON'] });
-// EVM → ICON → (alphabetical: BITCOIN, INJECTIVE, NEAR, SOLANA, STACKS, STELLAR, SUI)
-```
-
-For UIs that must not reflow on reload (header chain list, navigation), always pass `order`.
-
----
-
-## Common patterns
-
-### Pattern 1 — header connected-account chip
-
-```tsx
-function HeaderAccountChip() {
-  const { chains, status } = useConnectedChains();
-
-  if (status === 'loading') return null;
-  if (chains.length === 0) return <ConnectButton />;
-
-  return <span>{chains.length} chain{chains.length !== 1 ? 's' : ''} connected</span>;
-}
-```
-
-### Pattern 2 — "install Hana" CTA when not installed
-
-```tsx
-function HanaCta() {
-  const installed = useIsWalletInstalled({ connectors: ['hana'] });
-  return installed ? null : (
-    <a href="https://hana-wallet.com" target="_blank" rel="noreferrer">
-      Install Hana Wallet
-    </a>
-  );
-}
-```
-
-### Pattern 3 — chain selector in swap form
-
-```tsx
-function ChainSelector({ value, onChange }: { value: ChainType; onChange: (c: ChainType) => void }) {
-  const groups = useChainGroups({ order: ['EVM', 'SOLANA', 'SUI'] });
-  return (
-    <select value={value} onChange={(e) => onChange(e.target.value as ChainType)}>
-      {groups.map((g) => (
-        <option key={g.chainType} value={g.chainType}>
-          {g.displayName} {g.isConnected ? '✓' : ''}
-        </option>
-      ))}
-    </select>
-  );
-}
-```
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Manual — load page on slow 3G, confirm no Connect→Connected flash on reload
-# 3. Manual — uninstall Hana, confirm CTA appears; reinstall, confirm CTA disappears
-```