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

package/ai-exported/migration/recipes/walletconnect-migration.md

@@ -0,0 +1,168 @@
+# Recipe: Adopt WalletConnect (v2 only)
+
+WalletConnect support is **new in v2** — there is no v1 equivalent to migrate from. This recipe is here for users who tried to bolt WalletConnect onto v1 by hand-rolling a wagmi config and now want to use the v2 first-class option.
+
+If you didn't have WalletConnect in v1, **this recipe is opt-in, not required**. Skip if not relevant.
+
+---
+
+## When to use this recipe
+
+Apply when the user's v1 code:
+
+- Built a custom wagmi config that injected `walletConnect()` connector
+- Mounted a separate `WagmiProvider` outside `SodaxWalletProvider`
+- Patched the v1 internal `createWagmiConfig` helper to include WalletConnect
+
+Or when the user simply wants to **add WalletConnect for the first time** while migrating to v2.
+
+---
+
+## Why apps add WalletConnect
+
+EIP-6963 (the default v2 EVM discovery mechanism) only finds **browser-extension wallets**. Partners using enterprise custody — Fireblocks, Ledger Live, mobile-only wallets — cannot install browser extensions. WalletConnect is the protocol that lets these wallets connect via QR / deep link.
+
+---
+
+## Before (v1, hand-rolled — typical workaround)
+
+```tsx
+// v1 ❌ — bypassed the package's wagmi config
+import { createConfig, WagmiProvider } from 'wagmi';
+import { walletConnect } from 'wagmi/connectors';
+import { mainnet, sonic } from 'wagmi/chains';
+
+const wagmiConfig = createConfig({
+  chains: [mainnet, sonic],
+  connectors: [
+    walletConnect({ projectId: 'wc-cloud-project-id' }),
+    // ...
+  ],
+  // ...
+});
+
+export function Providers({ children }) {
+  return (
+    <WagmiProvider config={wagmiConfig}>
+      {/* SodaxWalletProvider mounted alongside, with conflicting wagmi state */}
+      <SodaxWalletProvider rpcConfig={...} options={...}>
+        {children}
+      </SodaxWalletProvider>
+    </WagmiProvider>
+  );
+}
+```
+
+(This pattern caused two parallel wagmi states and was never officially supported.)
+
+---
+
+## After (v2 — first-class)
+
+```tsx
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    ssr: true,
+    walletConnect: {
+      projectId: 'wc-cloud-project-id', // from cloud.walletconnect.com
+    },
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+    },
+  },
+};
+
+const queryClient = new QueryClient();
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+The WalletConnect connector is added to wagmi automatically. `useXConnectors({ xChainType: 'EVM' })` will surface it alongside any EIP-6963 wallets.
+
+---
+
+## What changed
+
+| Concern | v1 (hand-rolled) | v2 (first-class) |
+|---|---|---|
+| WagmiProvider mount | manual, outside SodaxWalletProvider | internal to SodaxWalletProvider |
+| wagmi config | hand-built via `createConfig` | derived from `walletConfig` |
+| WalletConnect projectId | passed to `walletConnect()` connector | passed to `EVM.walletConnect.projectId` |
+| Two parallel wagmi states | yes — common bug | no — single source of truth |
+| Connector list in modal | mixed (some via custom connectors, some via SodaxWalletProvider) | unified via `useXConnectors({ xChainType: 'EVM' })` |
+
+---
+
+## Restricting the modal to specific wallets
+
+`EVM.walletConnect` extends wagmi's `WalletConnectParameters` — full options available. To show only one specific wallet (e.g. when integrating with a single enterprise custody provider) and hide the rest:
+
+```tsx
+EVM: {
+  walletConnect: {
+    projectId: 'wc-cloud-project-id',
+    qrModalOptions: {
+      explorerRecommendedWalletIds: ['<target-wallet-id>'],
+      explorerExcludedWalletIds: 'ALL',
+    },
+  },
+},
+```
+
+Wallet IDs come from the [WalletConnect Explorer](https://cloud.walletconnect.com/sign-in). Filter options:
+
+| Option | Effect |
+|---|---|
+| `explorerRecommendedWalletIds` | Prioritized at the top of the QR modal. |
+| `explorerExcludedWalletIds: 'ALL'` | Hides every wallet not in `explorerRecommendedWalletIds`. |
+| `explorerExcludedWalletIds: ['id1', 'id2']` | Hides specific wallets only. |
+
+---
+
+## Migration steps
+
+1. **Remove the hand-rolled `WagmiProvider` and `createConfig`.** v2 builds wagmi config internally.
+2. **Move `projectId`** into `walletConfig.EVM.walletConnect.projectId`.
+3. **Move any `qrModalOptions`** (e.g. wallet filters) into `walletConfig.EVM.walletConnect.qrModalOptions`.
+4. **Verify** that `useXConnectors({ xChainType: 'EVM' })` returns both EIP-6963 connectors and the WalletConnect entry.
+5. **Drop** any custom hooks / state that bridged between the two wagmi configs in v1.
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Confirm no manual WagmiProvider remains
+grep -rn "WagmiProvider" <user-src>
+# expect empty (or only inside the wallet-sdk-react package itself if the user has a deep import — flag and remove)
+
+# 3. Confirm walletConnect config is in walletConfig
+grep -rn "walletConnect" <user-src> | grep -i "projectId"
+# expect at least one match in the provider file
+
+# 4. Manual — load app, open connect modal, confirm WalletConnect option appears
+```
+
+---
+
+## Common pitfalls
+
+- **Missing projectId.** Without `projectId`, the WalletConnect connector won't initialize. Get one free at [cloud.walletconnect.com](https://cloud.walletconnect.com).
+- **Bundling EIP-6963 + WalletConnect.** The two are additive — `useXConnectors` returns both. UI should let users pick.
+- **`qrModalOptions.explorerExcludedWalletIds` typo.** It's `'ALL'` (string), not `true` or `'all'`.
+- **Multiple SodaxWalletProvider mounts.** Don't mount one with WalletConnect and another without — define `walletConfig` once at the app root.

package/ai-exported/migration/reference/components.md

@@ -0,0 +1,73 @@
+# Reference: Component / Provider Map
+
+Components and exported providers between v1 and v2. See [`../breaking-changes.md`](../breaking-changes.md) for the WHY.
+
+---
+
+## `SodaxWalletProvider`
+
+Same name in v1 and v2. **Props changed** — see [`config.md`](./config.md) for the full shape map.
+
+```tsx
+// v1 ❌
+<SodaxWalletProvider
+  rpcConfig={rpcConfig}
+  options={{ wagmi, solana, sui }}
+  initialState={wagmiState}
+>
+  {children}
+</SodaxWalletProvider>
+
+// v2 ✅
+<SodaxWalletProvider config={walletConfig}>
+  {children}
+</SodaxWalletProvider>
+```
+
+### Provider-stack order
+
+| Position | v1 | v2 |
+|---|---|---|
+| Outermost (app entry) | `SodaxWalletProvider` (creates internal QueryClient) | `QueryClientProvider` (caller-provided QueryClient) |
+| Middle | (none) | `SodaxWalletProvider` |
+| Children | app | app |
+
+```tsx
+// v1 ❌ — SodaxWalletProvider internal QueryClient
+<SodaxWalletProvider rpcConfig={...} options={...}>
+  {children}
+</SodaxWalletProvider>
+
+// v2 ✅ — caller wraps with QueryClientProvider
+<QueryClientProvider client={queryClient}>
+  <SodaxWalletProvider config={walletConfig}>
+    {children}
+  </SodaxWalletProvider>
+</QueryClientProvider>
+```
+
+---
+
+## Internal-only components (do not import directly)
+
+These are mounted **inside** `SodaxWalletProvider` and are not part of the public API in either v1 or v2. Listed for awareness — if you imported them in v1 you should not have, and v2 may not expose them.
+
+| Component | v1 | v2 | Note |
+|---|---|---|---|
+| `Hydrate` | exported (file `Hydrate.ts`) | replaced by per-chain `EvmHydrator`, `SolanaHydrator`, `SuiHydrator` (internal) | If you imported `Hydrate` from v1, **remove the import** — v2 does not export an equivalent. State hydration is automatic. |
+| `WagmiProvider`, `SuiClientProvider`, `SolanaWalletProvider` (re-exports) | not re-exported | not re-exported | Use the original packages (`wagmi`, `@mysten/dapp-kit`, `@solana/wallet-adapter-react`) only if you need direct access — most apps should not. |
+
+---
+
+## `XService` and `XConnector` abstract classes
+
+| | v1 | v2 |
+|---|---|---|
+| Import path | `@sodax/wallet-sdk-react` (barrel) | `@sodax/wallet-sdk-react` (barrel — types only) |
+| Runtime class export | yes | yes |
+| Abstract method signature | `abstract connect(): Promise<XAccount \| undefined>` | unchanged |
+| Properties | `id`, `name`, `icon`, `xChainType` | unchanged |
+
+The abstract contract is **stable across v1 → v2**. If you have a custom subclass, it should compile against v2 with no changes — but verify, and check `getBalance` / `getBalances` defaults if you override them.
+
+> **Stop condition:** if the user has a custom `XConnector` or `XService` subclass, the migration agent must stop and ask. The abstract surface is stable but downstream usage (e.g. how the subclass is instantiated, registered) has changed.

package/ai-exported/migration/reference/config.md

@@ -0,0 +1,307 @@
+# Reference: `SodaxWalletProvider` Config Map
+
+The biggest single change in v2. v1 spread chain configuration across three props (`rpcConfig`, `options`, `initialState`); v2 collapses them into one `config` prop. See [`../breaking-changes.md`](../breaking-changes.md) §1 for the WHY.
+
+---
+
+## Top-level shape
+
+```tsx
+// v1 ❌
+<SodaxWalletProvider
+  rpcConfig={rpcConfig}
+  options={{ wagmi, solana, sui }}
+  initialState={wagmiState}
+>
+  {children}
+</SodaxWalletProvider>
+
+// v2 ✅
+<SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+```
+
+The v2 `config` is `SodaxWalletConfig`. Top-level keys are **chain-type slots** (`EVM`, `SOLANA`, `SUI`, `BITCOIN`, `STELLAR`, `ICON`, `INJECTIVE`, `NEAR`, `STACKS`). **Omit a slot to skip mounting that adapter**; pass `{}` to mount with SDK defaults.
+
+---
+
+## v1 `rpcConfig` → v2 per-chain `rpcUrl`
+
+v1 took a flat dictionary keyed by some chain string:
+
+```ts
+// v1 ❌
+const rpcConfig: RpcConfig = {
+  'sonic': 'https://rpc.soniclabs.com',
+  '0x1.eth': 'https://ethereum-rpc.publicnode.com',
+  'solana': 'https://api.mainnet-beta.solana.com',
+  // ...
+};
+```
+
+v2 nests RPC URLs under `<ChainTypeSlot>.chains[ChainKey].rpcUrl`:
+
+```ts
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+import type { SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+      [ChainKeys.ETHEREUM_MAINNET]: { rpcUrl: 'https://ethereum-rpc.publicnode.com' },
+    },
+  },
+  SOLANA: {
+    chains: {
+      [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://api.mainnet-beta.solana.com' },
+    },
+  },
+};
+```
+
+**Per-chain entry shape varies** by chain type:
+
+| Slot | Per-chain entry |
+|---|---|
+| `EVM`, `SOLANA`, `SUI`, `ICON`, `NEAR` | `{ rpcUrl?, defaults? }` |
+| `BITCOIN`, `STELLAR`, `INJECTIVE` | extends their `*RpcConfig` type with `{ defaults? }` |
+| `STACKS` | preset name (string) **or** `StacksNetworkLike & { defaults? }` |
+
+The single source of truth for the per-chain shape is `ChainMeta` in `src/types/config.ts` — `SodaxWalletConfig`, `ChainEntry<K>`, `WalletDefaultsByKey<K>` derive from it.
+
+---
+
+## v1 `options.wagmi` → v2 `EVM.*`
+
+```ts
+// v1 ❌
+options: {
+  wagmi: {
+    reconnectOnMount: false,
+    ssr: true,
+  },
+}
+```
+
+```ts
+// v2 ✅
+EVM: {
+  ssr: true,
+  reconnectOnMount: true,
+  chains: { ... },
+}
+```
+
+| v1 | v2 | Notes |
+|---|---|---|
+| `options.wagmi.ssr` | `EVM.ssr` | Defaults: v1 `true`, v2 not set (caller decides). For Next.js, set `true`. |
+| `options.wagmi.reconnectOnMount` | `EVM.reconnectOnMount` | Still supported, default `false`. Moved into the `EVM` slot. See [`migration/recipes/ssr-setup.md`](../recipes/ssr-setup.md) for the SSR-aware flow. |
+
+---
+
+## v1 `options.solana` → v2 `SOLANA.*`
+
+```ts
+// v1 ❌
+options: {
+  solana: { autoConnect: true },
+}
+```
+
+```ts
+// v2 ✅
+SOLANA: {
+  autoConnect: true,
+  chains: {
+    [ChainKeys.SOLANA_MAINNET]: { rpcUrl: '...' },
+  },
+}
+```
+
+| v1 | v2 |
+|---|---|
+| `options.solana.autoConnect` | `SOLANA.autoConnect` |
+
+---
+
+## v1 `options.sui` → v2 `SUI.*`
+
+```ts
+// v1 ❌
+options: {
+  sui: { autoConnect: true },
+}
+```
+
+```ts
+// v2 ✅
+SUI: {
+  autoConnect: true,
+  network: 'mainnet',
+}
+```
+
+`SUI` slot fields (per `SuiAdapterFields` in `src/types/config.ts`):
+
+| Field | Type | Default |
+|---|---|---|
+| `autoConnect` | `boolean?` | `true` |
+| `network` | `'mainnet' \| 'testnet' \| 'devnet'?` | `'mainnet'` |
+
+| v1 | v2 |
+|---|---|
+| `options.sui.autoConnect` | `SUI.autoConnect` |
+
+---
+
+## v1 `initialState` → v2 `EVM.initialState`
+
+v1 accepted a top-level `initialState` prop (`WagmiState`) for SSR hydration. v2 still accepts the same value — it just lives **inside the `EVM` slot** of the `config` prop.
+
+```ts
+// v1 ❌
+<SodaxWalletProvider rpcConfig={...} options={...} initialState={wagmiState}>
+
+// v2 ✅
+<SodaxWalletProvider config={{
+  EVM: {
+    ssr: true,
+    initialState: wagmiState,
+    chains: {...},
+  },
+  /* ... */
+}}>
+```
+
+If you previously derived `initialState` via `cookieToInitialState(...)` in a server component, keep that logic — just pass the result into `EVM.initialState` instead of the top-level prop. See [`../recipes/ssr-setup.md`](../recipes/ssr-setup.md) for a full Next.js example.
+
+---
+
+## New in v2: per-chain `defaults`
+
+Each chain entry can hold call-level defaults that flow to the bridged `IXxxWalletProvider`:
+
+```ts
+// v2 ✅
+EVM: {
+  chains: {
+    [ChainKeys.ARBITRUM_MAINNET]: {
+      rpcUrl: 'https://arb1.arbitrum.io/rpc',
+      defaults: {
+        waitForTransactionReceipt: { confirmations: 1 },
+      },
+    },
+  },
+}
+```
+
+The `defaults` shape is per-chain — the type system narrows what's valid per chain key. Inspect `WalletDefaultsByKey<K>` in `src/types/config.ts`.
+
+---
+
+## New in v2: `EVM.walletConnect`
+
+WalletConnect support for EVM — extends wagmi's `WalletConnectParameters`:
+
+```ts
+// v2 ✅
+EVM: {
+  walletConnect: {
+    projectId: 'wc-cloud-project-id', // required from cloud.walletconnect.com
+    // qrModalOptions, isNewChainsStale, etc. — full WalletConnectParameters
+  },
+}
+```
+
+When `walletConnect` is present, a WalletConnect connector is added to the wagmi config; `useXConnectors({ xChainType: 'EVM' })` will surface it. Omitting the field preserves v1 behavior (EIP-6963 only).
+
+See [`../recipes/walletconnect-migration.md`](../recipes/walletconnect-migration.md).
+
+---
+
+## New in v2: `<chainSlot>.connectors?` override
+
+Each chain slot accepts an optional `connectors` field to override the default connector list. Most consumers don't need this — defaults work for all common wallet vendors.
+
+---
+
+## Frozen on first render
+
+`SodaxWalletProvider` captures `config` once on mount and ignores prop-reference changes. To swap config at runtime, remount with a new `key`:
+
+```tsx
+// v2 ✅
+<SodaxWalletProvider key={configVersion} config={walletConfig}>
+  {children}
+</SodaxWalletProvider>
+```
+
+Bumping `configVersion` (e.g. when the user picks a new RPC endpoint) forces a clean re-init. See [`../breaking-changes.md`](../breaking-changes.md) §12.
+
+---
+
+## Provider-stack order changed
+
+v1 created `QueryClient` internally; v2 expects the consumer to provide one:
+
+```tsx
+// v1 ❌ — QueryClientProvider was internal
+<SodaxWalletProvider rpcConfig={...} options={...}>{children}</SodaxWalletProvider>
+
+// v2 ✅ — caller wraps with QueryClientProvider
+<QueryClientProvider client={queryClient}>
+  <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+</QueryClientProvider>
+```
+
+Add `@tanstack/react-query 5.x` as a direct dependency if your app didn't already have it. See [`../breaking-changes.md`](../breaking-changes.md) §2.
+
+---
+
+## Minimal valid v2 config — every shape, side by side
+
+```ts
+// v2 ✅
+import { ChainKeys } from '@sodax/types';
+import type { SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+
+const walletConfig: SodaxWalletConfig = {
+  // EVM — needs chains
+  EVM: {
+    ssr: true,
+    chains: {
+      [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
+    },
+    // optional:
+    // walletConnect: { projectId: '...' },
+  },
+
+  // SOLANA — chain entry + autoConnect
+  SOLANA: {
+    autoConnect: false,
+    chains: {
+      [ChainKeys.SOLANA_MAINNET]: { rpcUrl: 'https://api.mainnet-beta.solana.com' },
+    },
+  },
+
+  // SUI — network preset
+  SUI: { network: 'mainnet' },
+
+  // ICON — chain entry
+  ICON: {
+    chains: {
+      [ChainKeys.ICON_MAINNET]: { rpcUrl: 'https://ctz.solidwallet.io/api/v3' },
+    },
+  },
+
+  // BITCOIN, STELLAR, INJECTIVE, NEAR, STACKS — pass {} to mount with SDK defaults
+  BITCOIN: {},
+  STELLAR: {},
+  INJECTIVE: {},
+  NEAR: {},
+  STACKS: {},
+};
+```
+
+Omit any slot to skip that chain entirely.