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

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

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

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

@@ -1,325 +0,0 @@
-# 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.
-
----
-
-## ⚠️ First, fix the provider stack (silent runtime crash otherwise)
-
-**v1 created `QueryClient` internally; v2 expects the consumer to provide one.** If you only swap the prop shape without adding `QueryClientProvider`, the app crashes at runtime — React Query hooks throw "No QueryClient set". This is **not** a typecheck error; it surfaces only when a wallet hook mounts.
-
-```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.
-
-When dapp-kit is also in use, the full provider stack is:
-
-```tsx
-<SodaxProvider config={sodaxConfig}>
-  <QueryClientProvider client={queryClient}>           {/* required wrapper */}
-    <SodaxWalletProvider config={walletConfig}>
-      <YourApp />
-    </SodaxWalletProvider>
-  </QueryClientProvider>
-</SodaxProvider>
-```
-
----
-
-## 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
-
-Moved to the top of this file — see the ⚠️ block at the start. The summary: wrap `SodaxWalletProvider` in `QueryClientProvider`, otherwise React Query throws "No QueryClient set" at runtime.
-
----
-
-## 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.