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

package/ai-exported/integration/examples/04-walletconnect-setup.tsx

@@ -0,0 +1,89 @@
+/**
+ * WalletConnect setup — adds the WalletConnect connector to the EVM modal.
+ * For dApps that target users on mobile-only or enterprise custody wallets
+ * (Ledger Live, Safe, Fireblocks, ...) which cannot install browser extensions.
+ *
+ * Get a projectId at https://cloud.walletconnect.com
+ *
+ * To narrow the WalletConnect modal to ONE specific wallet (e.g. an enterprise
+ * custody integration), see the commented `qrModalOptions` block below — fill
+ * in the target wallet id from https://walletconnect.com/explorer.
+ */
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import {
+  SodaxWalletProvider,
+  type SodaxWalletConfig,
+  useWalletModal,
+  useXConnectors,
+  useXAccount,
+  useXDisconnect,
+} from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+const queryClient = new QueryClient();
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+      [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
+    },
+    walletConnect: {
+      projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID ?? '',
+      // Optional — restrict the WalletConnect QR modal to a specific wallet:
+      //
+      // qrModalOptions: {
+      //   explorerRecommendedWalletIds: ['<target-wallet-id-from-walletconnect-explorer>'],
+      //   explorerExcludedWalletIds: 'ALL', // hide everything except recommended
+      // },
+    },
+  },
+};
+
+export function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>
+        <ConnectWithWalletConnect />
+      </SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+
+function ConnectWithWalletConnect() {
+  const modal = useWalletModal();
+  const connectors = useXConnectors({ xChainType: 'EVM' });
+  const account = useXAccount({ xChainType: 'EVM' });
+  const disconnect = useXDisconnect();
+
+  const wcConnector = connectors.find((c) => c.id === 'walletConnect');
+
+  // Hide the modal while wagmi/WalletConnect's QR modal owns the screen
+  if (modal.state.kind === 'connecting' && modal.state.connector.id === 'walletConnect') {
+    return null;
+  }
+
+  if (account.address) {
+    return (
+      <div>
+        <code>{account.address}</code>
+        <button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
+          Disconnect
+        </button>
+      </div>
+    );
+  }
+
+  if (!wcConnector) {
+    return <p>WalletConnect not configured — set NEXT_PUBLIC_WC_PROJECT_ID</p>;
+  }
+
+  return (
+    <button type="button" onClick={() => modal.selectWallet(wcConnector)}>
+      Connect via WalletConnect
+    </button>
+  );
+}

package/ai-exported/integration/examples/README.md

@@ -0,0 +1,29 @@
+# Examples
+
+Copy-paste-runnable code examples. Each file is complete — drop it into a fresh React 19 project with `@sodax/wallet-sdk-react` + `@tanstack/react-query` installed and it works.
+
+For narrative + step-by-step explanation, see [`../recipes/`](../recipes/). Examples here are pure code with minimal comments.
+
+| File | Use case | Lines |
+|---|---|---|
+| [`01-minimal-evm.tsx`](./01-minimal-evm.tsx) | Smallest working setup — provider + 1 connect button | ~50 |
+| [`02-multi-chain-modal.tsx`](./02-multi-chain-modal.tsx) | Headless wallet modal with chain → connector → connecting flow | ~120 |
+| [`03-nextjs-app-router.tsx`](./03-nextjs-app-router.tsx) | Next.js 15 App Router setup (SSR + `'use client'`) | ~60 |
+| [`04-walletconnect-setup.tsx`](./04-walletconnect-setup.tsx) | WalletConnect connector setup (with optional single-wallet filter) | ~50 |
+
+## Conventions
+
+- All files use TypeScript (`.tsx`).
+- All consumer components have `'use client'` (Next.js compatible).
+- `walletConfig` is defined as a **module-level constant** — never created inside a component (the provider freezes config on first render).
+- `QueryClient` is also a module-level constant — one client per app, shared across providers.
+- Examples use `<button>`, `<select>`, `<dialog>` etc. directly — bring your own UI library.
+
+## Running an example
+
+```bash
+pnpm add @sodax/wallet-sdk-react @tanstack/react-query
+# also: react@>=19, react-dom@>=19
+```
+
+Drop the file into your app, mount the provider component at the root, and use the consumer component anywhere below it.

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

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

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