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

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

package/ai-exported/integration/recipes/sub-path-imports.md

@@ -1,95 +0,0 @@
-# Recipe: Sub-Path Imports (Advanced)
-
-When and how to use deep imports from `@sodax/wallet-sdk-react/xchains/<chain>`. Default to barrel imports — reach for sub-paths only when you need a concrete class for `instanceof` checks, custom connector lists, or chain-specific utilities not exposed through the public hooks.
-
-**Depends on:** [`setup.md`](./setup.md)
-
----
-
-## When you need it
-
-The package barrel exports hooks, types, abstractions, and `SodaxWalletProvider`. Concrete chain-specific classes (`XverseXConnector`, `EvmXService`, `IconHanaXConnector`, …) live behind sub-paths to keep the barrel small. Reach for a sub-path import in three cases:
-
-| Use case | Example |
-|---|---|
-| Runtime type check on a connector | `if (connector instanceof XverseXConnector) { … }` |
-| Override the default connector list for a chain | Pass `connectors: [new MyConnector()]` to `ChainTypeConfig` |
-| Call a chain-specific method not on `IXConnector` | `xverseConnector.setAddressPurpose('payment')` |
-
-If none of the above applies, **stick with barrel imports** — sub-paths are not part of the typical surface.
-
----
-
-## `instanceof` check (most common)
-
-Tag a connector by class to call methods specific to that wallet:
-
-```tsx
-import { useXConnectors } from '@sodax/wallet-sdk-react';
-import { XverseXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
-
-function BitcoinConnectButton() {
-  const connectors = useXConnectors({ xChainType: 'BITCOIN' });
-
-  return (
-    <>
-      {connectors.map((connector) => (
-        <button
-          type="button"
-          key={connector.id}
-          onClick={async () => {
-            // Pre-configure Xverse before connect
-            if (connector instanceof XverseXConnector) {
-              connector.setAddressPurpose('payment');
-            }
-            await connector.connect();
-          }}
-        >
-          {connector.name}
-        </button>
-      ))}
-    </>
-  );
-}
-```
-
-The barrel-typed `IXConnector` exposes only `connect()` / `disconnect()` / metadata fields. To reach `setAddressPurpose` (or any class-specific method), narrow via `instanceof` after a sub-path import.
-
----
-
-## Custom connector list
-
-Override the default connectors a chain ships with by passing `connectors` on the `ChainTypeConfig`:
-
-```tsx
-import type { SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-import { XverseXConnector, UnisatXConnector } from '@sodax/wallet-sdk-react/xchains/bitcoin';
-
-const walletConfig: SodaxWalletConfig = {
-  BITCOIN: {
-    // Only mount Xverse + Unisat — drop the OKX connector that ships by default.
-    connectors: [new XverseXConnector(), new UnisatXConnector()],
-  },
-};
-```
-
-Use sparingly — the default lists are tuned per chain. Override only when you need to remove a connector you do not support, or add a custom one you implemented yourself.
-
----
-
-## Available sub-paths
-
-For the per-chain symbol list, see [`../reference/api-surface.md`](../reference/api-surface.md) § "Sub-path exports". That table is the single source of truth — `scripts/check-ai-exported.sh` validates it stays in sync with `src/xchains/`.
-
----
-
-## Verification
-
-```bash
-# 1. Type check
-pnpm checkTs
-
-# 2. Sub-path imports must resolve to a real chain folder
-grep -rnE "from '@sodax/wallet-sdk-react/xchains/[a-z]+'" <user-src>
-# Each match's <chain> must be one of: bitcoin, evm, icon, injective, near, solana, stacks, stellar, sui
-```