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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/ai-exported/integration/recipes/setup.md +3 -1
  2. package/ai-exported/integration/reference/api-surface.md +1 -1
  3. package/ai-exported/migration/recipes/ssr-setup.md +2 -0
  4. package/ai-exported/migration/reference/config.md +31 -13
  5. package/ai-exported/migration/reference/hooks.md +47 -2
  6. package/package.json +5 -4
package/ai-exported/integration/recipes/setup.md CHANGED
@@ -66,11 +66,13 @@ export function Providers({ children }: { children: React.ReactNode }) {
66
66
 
67
67
  | Framework | Where to mount `<Providers>` | `EVM.ssr` |
68
68
  |---|---|---|
69
- | 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` |
69
+ | Next.js (App Router) | `app/layout.tsx`, inside `<body>`. Mark the providers file `'use client'`. Pair with [`../../migration/recipes/ssr-setup.md`](../../migration/recipes/ssr-setup.md) if you need wagmi cookie hydration. | `true` |
70
70
  | Vite + React | `main.tsx`, wrap `<App />` directly. | omit (defaults `false`) |
71
71
  | Create React App | `index.tsx`, wrap `<App />` directly. | omit |
72
72
  | Remix / Tanstack Start | Root route component, marked client-only. Same as Next.js. | `true` |
73
73
 
74
+ For wagmi cookie hydration in App Router, also see [`../../migration/recipes/ssr-setup.md`](../../migration/recipes/ssr-setup.md).
75
+
74
76
  ---
75
77
 
76
78
  ## Chain-type slots
package/ai-exported/integration/reference/api-surface.md CHANGED
@@ -112,7 +112,7 @@ Concrete chain classes live behind sub-paths. Default to barrel imports; opt int
112
112
 
113
113
  ### Default pattern (most chains)
114
114
 
115
- `/xchains/{evm, icon, injective, near, solana, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, etc. Icon also exports `IconHanaXConnector` (the connector for the Hana wallet).
115
+ `/xchains/{bitcoin, evm, icon, injective, near, solana, stacks, sui}` re-export the chain's `XService` + `XConnector` classes — `EvmXService`/`EvmXConnector`, `SolanaXService`/`SolanaXConnector`, `BitcoinXService`/`BitcoinXConnector`, `StacksXService`/`StacksXConnector`, etc. Icon also exports `IconHanaXConnector` (the connector for the Hana wallet).
116
116
 
117
117
  ```ts
118
118
  import { EvmXService, EvmXConnector } from '@sodax/wallet-sdk-react/xchains/evm';
package/ai-exported/migration/recipes/ssr-setup.md CHANGED
@@ -160,3 +160,5 @@ grep -rnE "EVM:\s*\{[^}]*\bssr:\s*true" <user-src>
160
160
  - **Creating `QueryClient` inside the layout component.** Each render creates a new client and React Query loses its cache. Define `queryClient` as a **module-level constant**, or use `useState(() => new QueryClient())` inside a client component.
161
161
  - **Pages Router project.** This recipe assumes App Router. For Pages Router, mount the providers in `_app.tsx` instead — the API is the same.
162
162
  - **Dynamic RPC URLs from env vars.** If `rpcUrl` comes from `process.env.NEXT_PUBLIC_*`, ensure the env var is available at module init time (it is, by Next.js convention). Don't compute the config inside a hook — `SodaxWalletProvider` freezes config on first render, so config must be stable.
163
+
164
+
package/ai-exported/migration/reference/config.md CHANGED
@@ -4,6 +4,36 @@ The biggest single change in v2. v1 spread chain configuration across three prop
4
4
 
5
5
  ---
6
6
 
7
+ ## ⚠️ First, fix the provider stack (silent runtime crash otherwise)
8
+
9
+ **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.
10
+
11
+ ```tsx
12
+ // v1 ❌ — QueryClientProvider was internal
13
+ <SodaxWalletProvider rpcConfig={...} options={...}>{children}</SodaxWalletProvider>
14
+
15
+ // v2 ✅ — caller wraps with QueryClientProvider
16
+ <QueryClientProvider client={queryClient}>
17
+ <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
18
+ </QueryClientProvider>
19
+ ```
20
+
21
+ 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.
22
+
23
+ When dapp-kit is also in use, the full provider stack is:
24
+
25
+ ```tsx
26
+ <SodaxProvider config={sodaxConfig}>
27
+ <QueryClientProvider client={queryClient}> {/* required wrapper */}
28
+ <SodaxWalletProvider config={walletConfig}>
29
+ <YourApp />
30
+ </SodaxWalletProvider>
31
+ </QueryClientProvider>
32
+ </SodaxProvider>
33
+ ```
34
+
35
+ ---
36
+
7
37
  ## Top-level shape
8
38
 
9
39
  ```tsx
@@ -243,19 +273,7 @@ Bumping `configVersion` (e.g. when the user picks a new RPC endpoint) forces a c
243
273
 
244
274
  ## Provider-stack order changed
245
275
 
246
- v1 created `QueryClient` internally; v2 expects the consumer to provide one:
247
-
248
- ```tsx
249
- // v1 ❌ — QueryClientProvider was internal
250
- <SodaxWalletProvider rpcConfig={...} options={...}>{children}</SodaxWalletProvider>
251
-
252
- // v2 ✅ — caller wraps with QueryClientProvider
253
- <QueryClientProvider client={queryClient}>
254
- <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
255
- </QueryClientProvider>
256
- ```
257
-
258
- 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.
276
+ 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.
259
277
 
260
278
  ---
261
279
 
package/ai-exported/migration/reference/hooks.md CHANGED
@@ -16,6 +16,22 @@ Per-hook signature changes for v1 → v2. See [`../breaking-changes.md`](../brea
16
16
 
17
17
  ---
18
18
 
19
+ ## Canonical rule — `xChainId` is non-nullable
20
+
21
+ Hooks that take `xChainId` declare it via overloads as required `SpokeChainKey`. Passing a nullable value (e.g. `token?.chainKey`) does not compile.
22
+
23
+ The exported `UseWalletProviderOptions` (and similar) is the *implementation* type and looks permissive — but calls resolve against the overloads, which are stricter. Casting around the error is unsafe: it either fails to bypass the overload at all, or silently strips the nullable from the type while the runtime value stays `undefined` (some hooks tolerate that and return `undefined`; `useXAccount` throws).
24
+
25
+ Handle the nullable **before** the hook call:
26
+
27
+ ```ts
28
+ // Narrow, default-fallback, or split into a child component — pick the one that fits.
29
+ if (!chainKey) return null;
30
+ const wp = useWalletProvider({ xChainId: chainKey });
31
+ ```
32
+
33
+ ---
34
+
19
35
  ## `useXAccount`
20
36
 
21
37
  ```ts
@@ -113,6 +129,8 @@ const service = useXService({ xChainType: 'EVM' });
113
129
 
114
130
  Return type unchanged.
115
131
 
132
+ > **Need the typed concrete class** (e.g. `EvmXService.publicClient`, `StellarXService.server`, `BitcoinXService` for `instanceof` checks)? The concrete classes (`EvmXService`, `SolanaXService`, `StellarXService`, etc.) are **still exported in v2**, but moved from the package barrel to per-chain sub-paths: `@sodax/wallet-sdk-react/xchains/<chain>`. See [`imports.md` § Concrete chain classes](./imports.md#concrete-chain-classes--moved-behind-sub-path-imports) for the full per-chain table. The TS error `TS2724: '"@sodax/wallet-sdk-react"' has no exported member named 'StellarXService'. Did you mean 'useXService'?` is misleading when you actually need the class — the class is at the sub-path, not the hook.
133
+
116
134
  ---
117
135
 
118
136
  ## `useWalletProvider`
@@ -267,9 +285,36 @@ If you genuinely need the raw EVM chain ID (rare — almost no usage outside the
267
285
 
268
286
  ## Removed in v2
269
287
 
270
- | Hook | Replacement |
288
+ | Hook / symbol | Replacement |
271
289
  |---|---|
272
- | `useXBalances` | Moved to `@sodax/dapp-kit`. See [`../breaking-changes.md`](../breaking-changes.md) §10. |
290
+ | `useXBalances` | Moved to `@sodax/dapp-kit` **AND signature changed**. See note below. |
291
+ | `useXWagmiStore` | Removed entirely — direct store reads are not part of the v2 API. Use public hooks (`useXServices`, `useXConnections`, `useXService({ xChainType })`, `useXConnection({ xChainType })`, etc.). See note below. |
292
+ | Concrete X-service / X-connector classes (`EvmXService`, `SolanaXService`, `StellarXService`, `BitcoinXService`, `IconXService`, `InjectiveXService`, `SuiXService`, `NearXService`, `StacksXService`, `XverseXConnector`, `UnisatXConnector`, `OKXXConnector`, `IconHanaXConnector`, …) | **Not removed — moved to per-chain sub-paths.** TS error `TS2724: '"@sodax/wallet-sdk-react"' has no exported member named 'StellarXService'. Did you mean 'useXService'?` is misleading — the hint points at `useXService` (which returns the abstract `XService \| undefined`), but the typed class itself lives at `@sodax/wallet-sdk-react/xchains/<chain>`. See [`imports.md` § "Concrete chain classes — moved behind sub-path imports"](./imports.md#concrete-chain-classes--moved-behind-sub-path-imports) for the per-chain table. |
293
+
294
+ ### `useXBalances` — moved + reshaped
295
+
296
+ Not a simple package-rename. The v2 hook also wraps params and adds a required `xService` field:
297
+
298
+ ```diff
299
+ - // v1 — flat args from @sodax/wallet-sdk-react
300
+ - import { useXBalances } from '@sodax/wallet-sdk-react';
301
+ - const { data } = useXBalances({ xChainId, xTokens, address });
302
+
303
+ + // v2 — from @sodax/dapp-kit; params wrapped; xService required
304
+ + import { useXBalances } from '@sodax/dapp-kit';
305
+ + import { useXService, getXChainType } from '@sodax/wallet-sdk-react';
306
+ +
307
+ + const xService = useXService({ xChainType: getXChainType(xChainId) });
308
+ + const { data } = useXBalances({
309
+ + params: { xService, xChainId, xTokens, address },
310
+ + });
311
+ ```
312
+
313
+ The `xService` injection is part of dapp-kit's "no implicit wallet-sdk dependency" design — dapp-kit doesn't import from `wallet-sdk-react`, so the consumer wires the service across at the call site. See `@sodax/dapp-kit/ai-exported/integration/architecture.md` § "Decoupling from wallet-sdk-react".
314
+
315
+ ### `useXWagmiStore` — removed (store reads moved to public hooks)
316
+
317
+ The v1 Zustand store hook is gone from the v2 barrel. Direct store access is no longer supported. Every `useXWagmiStore(state => state.X)` selector maps to a public hook — see [`imports.md` § "Store hook removed from the public API"](./imports.md#store-hook-removed-from-the-public-api) for the full field-to-hook map and decision tree (`state.xServices` → `useXServices()`, `state.xConnections[chainType]` → `useXConnection({ xChainType })`, etc.). The localStorage key (`xwagmi-store`) is unchanged, so user connections survive the upgrade.
273
318
 
274
319
  ---
275
320
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sodax/wallet-sdk-react",
3
3
  "license": "MIT",
4
- "version": "2.0.0-rc.2",
4
+ "version": "2.0.0-rc.3",
5
5
  "description": "Wallet SDK of Sodax",
6
6
  "type": "module",
7
7
  "main": "./dist/index.cjs",
@@ -70,8 +70,8 @@
70
70
  "wagmi": "2.16.9",
71
71
  "zustand": "4.5.2",
72
72
  "bs58": "6.0.0",
73
- "@sodax/wallet-sdk-core": "2.0.0-rc.2",
74
- "@sodax/types": "2.0.0-rc.2"
73
+ "@sodax/types": "2.0.0-rc.3",
74
+ "@sodax/wallet-sdk-core": "2.0.0-rc.3"
75
75
  },
76
76
  "devDependencies": {
77
77
  "@testing-library/react": "^16.1.0",
@@ -100,6 +100,7 @@
100
100
  "lint": "biome lint . --write",
101
101
  "check:ai-exported": "bash ./scripts/check-ai-exported.sh",
102
102
  "check:ai-links": "bash ./scripts/check-ai-links.sh",
103
- "check:ai-imports": "bash ./scripts/check-ai-imports.sh"
103
+ "check:ai-imports": "bash ./scripts/check-ai-imports.sh",
104
+ "check:ai": "pnpm run check:ai-exported && pnpm run checkTs:examples && pnpm run check:ai-links && pnpm run check:ai-imports"
104
105
  }
105
106
  }