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

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
-```

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
-```