@sodax/skills 2.0.0-rc.10

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/recipes/adopt-defaults.md

@@ -0,0 +1,84 @@
+# Recipe: Adopt `defaults` (optional cleanup)
+
+Replace hand-rolled wrappers with provider-level `defaults`. Optional — older per-call style still works.
+
+**Apply when:** the user has a helper like `makeProvider(pk)` or `withDefaults(provider)` that injects fixed options on every call.
+
+---
+
+## Before — hand-rolled wrapper
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import type { EvmRawTransaction } from '@sodax/types';
+import { ChainKeys } from '@sodax/types';
+
+function makeEvmProvider(pk: `0x${string}`) {
+  const provider = new EvmWalletProvider({ privateKey: pk, chainId: ChainKeys.SONIC_MAINNET });
+
+  return {
+    ...provider,
+    sendTransaction(tx: EvmRawTransaction) {
+      // hard-coded gas on every call
+      return provider.sendTransaction(tx, { gas: 3_000_000n });
+    },
+  };
+}
+```
+
+## After — provider-level `defaults`
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const provider = new EvmWalletProvider({
+  privateKey: process.env.EVM_PK as `0x${string}`,
+  chainId: ChainKeys.SONIC_MAINNET,
+  defaults: {
+    sendTransaction: { gas: 3_000_000n },
+  },
+});
+
+// Use directly — defaults apply automatically; per-call override still works.
+await provider.sendTransaction(tx);
+await provider.sendTransaction(tx2, { gas: 5_000_000n });
+```
+
+---
+
+## Steps
+
+1. **Identify the wrapper.** Look for functions that wrap a provider and inject options on every method call.
+2. **Move the injected options into `defaults`.** Pick the right slice — `defaults.sendTransaction` for EVM, `defaults.signAndExecuteTxn` for Sui, flat `defaults` for Bitcoin / Stellar / ICON / Injective / NEAR / Stacks.
+3. **Delete the wrapper.** Replace call sites with direct provider method calls.
+4. **Keep behavior for callers that already pass options.** Per-call options shallow-merge over defaults, so existing call sites that pass `{ gas: 5_000_000n }` still get exactly that gas value.
+
+---
+
+## When NOT to adopt
+
+| Scenario | Why skip |
+|---|---|
+| The wrapper does more than inject defaults (e.g. logging, telemetry, retries) | `defaults` is just a config slice; it can't do behavior wrapping. Keep the wrapper. |
+| The "default" actually changes per call (e.g. dynamic gas estimation) | That's not a default — it's per-call logic. Keep it inline. |
+| The user's code base would gain churn for trivial savings | Migration cost > value. Leave it. |
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Search for remaining hand-rolled wrappers (heuristic)
+grep -rnE "function\s+(make|build|with)(Wallet|Evm|Solana|Sui|Bitcoin|Stellar|Icon|Injective|Near|Stacks)Provider" <user-src>
+# review each — confirm each is justified per the table above
+```
+
+---
+
+## Why
+
+See [`../breaking-changes/defaults-config.md`](../breaking-changes/defaults-config.md) for the model.

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/recipes/adopt-library-exports.md

@@ -0,0 +1,99 @@
+# Recipe: Adopt `library-exports` (optional cleanup)
+
+Re-import types from `@sodax/wallet-sdk-core` instead of upstream chain SDKs. Optionally drop direct chain-SDK deps from `package.json`.
+
+**Apply when:** the user imports type names like `WalletClient`, `PublicClient`, `Networks`, `PostConditionMode`, `NearConnector`, etc. directly from their upstream packages.
+
+For the full list of re-exported types, see [`recipes/library-exports.md`](../../../integration/knowledge/recipes/library-exports.md).
+
+---
+
+## Before
+
+```ts
+import type { WalletClient, PublicClient, TransactionReceipt } from 'viem';
+import { Networks } from '@stellar/stellar-sdk';
+import { PostConditionMode } from '@stacks/transactions';
+import type { WalletAccount, WalletWithFeatures, SuiWalletFeatures } from '@mysten/wallet-standard';
+import type { Commitment, ConnectionConfig, SendOptions } from '@solana/web3.js';
+```
+
+## After
+
+```ts
+import type {
+  WalletClient,
+  PublicClient,
+  TransactionReceipt,
+  WalletAccount,
+  WalletWithFeatures,
+  SuiWalletFeatures,
+  Commitment,
+  ConnectionConfig,
+  SendOptions,
+} from '@sodax/wallet-sdk-core';
+
+import { Networks, PostConditionMode } from '@sodax/wallet-sdk-core';
+```
+
+---
+
+## Steps
+
+1. **Identify candidate imports.** Run the grep below to find type imports from upstream chain SDKs:
+   ```bash
+   grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt|SendTransactionParameters|WaitForTransactionReceiptParameters"
+   grep -rn "from '@stellar/stellar-sdk'" <user-src> | grep "Networks"
+   grep -rn "from '@stacks/transactions'" <user-src> | grep -E "PostConditionMode|ClarityValue|PostConditionModeName"
+   # …see ../../integration/recipes/library-exports.md for the full grep list
+   ```
+
+2. **Replace one import statement at a time.** Switch the `from` clause to `@sodax/wallet-sdk-core`. Re-run `pnpm checkTs` after each file.
+
+3. **Check whether the upstream package is still needed for runtime.** If the consumer's only remaining import from `viem` (etc.) is one of the re-exported types, you can drop the dep from `package.json`. If they also import `createPublicClient`, `Connection`, `Transaction`, etc. — keep the dep.
+
+   ```bash
+   grep -rn "from 'viem'" <user-src>   # confirm nothing remains
+   ```
+
+---
+
+## Trade-offs
+
+| Switch | Trade-off |
+|---|---|
+| Type imports | Lossless. Same symbol, different module. |
+| Dep removal (after switching all imports) | Smaller `node_modules`, faster installs. But you re-add the dep if you later need a runtime helper. |
+| Version pinning | After dep removal, you no longer control the chain-SDK version directly — it's locked to whatever SODAX uses. Acceptable for most apps. |
+
+---
+
+## When NOT to adopt
+
+| Scenario | Why skip |
+|---|---|
+| The user is pinned to a specific chain-SDK version different from SODAX's | Adopting library-exports forces SODAX's version. Keep direct imports. |
+| The user imports many runtime symbols (`createPublicClient`, etc.) not in library-exports | Migration churn for limited benefit — they still need the dep. |
+| The user is mid-migration to another chain SDK and library-exports doesn't cover the new one | Wait until library-exports catches up, or just keep the direct dep. |
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. No remaining direct upstream-SDK type imports
+grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt"
+# expect empty (or kept on purpose with justification)
+
+# 3. Optional: confirm the upstream dep was actually removed
+cat <user>/package.json | jq -r '.dependencies | keys[]'
+```
+
+---
+
+## Why
+
+See [`../breaking-changes/library-exports.md`](../breaking-changes/library-exports.md) for the motivation.

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/README.md

@@ -0,0 +1,12 @@
+# Migration reference
+
+Lookup tables. Use these to answer "what was renamed / added / removed" without reading the breaking-change narratives.
+
+| File | Use for |
+|---|---|
+| [`renamed-symbols.md`](./renamed-symbols.md) | Old name → new name. |
+| [`deleted-exports.md`](./deleted-exports.md) | Symbols removed; what to use instead. |
+| [`added-fields.md`](./added-fields.md) | New optional fields you can adopt. |
+| [`return-shapes.md`](./return-shapes.md) | Method return shapes that changed (none currently — placeholder for future). |
+
+For narrative WHY behind each change, see [`../breaking-changes/`](../breaking-changes/).

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/added-fields.md

@@ -0,0 +1,71 @@
+# Added fields and types
+
+Additive changes that older code does not use. All optional — no migration required.
+
+---
+
+## New types
+
+| Type | Chain(s) | Purpose |
+|---|---|---|
+| `EvmWalletDefaults` | EVM | `defaults` slice shape |
+| `EvmSendTransactionPolicy` | EVM | Per-call options shape for `sendTransaction` |
+| `EvmWaitForTransactionReceiptPolicy` | EVM | Per-call options shape for `waitForTransactionReceipt` |
+| `SolanaWalletDefaults` | Solana | `defaults` slice shape |
+| `SuiWalletDefaults` | Sui | `defaults` slice shape |
+| `SuiSignAndExecutePolicy` | Sui | Per-call options for `signAndExecuteTxn` |
+| `SuiGetCoinsPolicy` | Sui | Per-call options for `getCoins` |
+| `BitcoinWalletDefaults` | Bitcoin | `defaults` slice shape |
+| `StellarWalletDefaults` | Stellar | `defaults` slice shape |
+| `IconWalletDefaults` | ICON | `defaults` slice shape |
+| `InjectiveWalletDefaults` | Injective | `defaults` slice shape |
+| `NearWalletDefaults` | NEAR | `defaults` slice shape |
+| `NearTxExecutionStatus` | NEAR | Status union for `waitUntil` default |
+| `StacksWalletDefaults` | Stacks | `defaults` slice shape |
+| `BaseWalletProvider<TDefaults>` | all | Abstract base class (consumers do not subclass) |
+
+---
+
+## New optional fields on existing configs
+
+| Config | Field | Default if omitted |
+|---|---|---|
+| `PrivateKeyEvmWalletConfig` | `defaults?: EvmWalletDefaults` | `{}` |
+| `BrowserExtensionEvmWalletConfig` | `defaults?: EvmWalletDefaults` | `{}` (note: transport/clients in defaults are no-ops here) |
+| `PrivateKeySolanaWalletConfig` | `defaults?: SolanaWalletDefaults` | `{}` |
+| `BrowserExtensionSolanaWalletConfig` | `defaults?: SolanaWalletDefaults` | `{}` |
+| `PrivateKeySuiWalletConfig` | `defaults?: SuiWalletDefaults` | `{}` |
+| `BrowserExtensionSuiWalletConfig` | `defaults?: SuiWalletDefaults` | `{}` |
+| `PrivateKeyBitcoinWalletConfig` | `defaults?: BitcoinWalletDefaults` | `{}` |
+| `BrowserExtensionBitcoinWalletConfig` | `defaults?: BitcoinWalletDefaults` | `{}` |
+| `PrivateKeyStellarWalletConfig` | `defaults?: StellarWalletDefaults` | `{}` |
+| `BrowserExtensionStellarWalletConfig` | `defaults?: StellarWalletDefaults` | `{}` |
+| `PrivateKeyIconWalletConfig` | `defaults?: IconWalletDefaults` | `{}` |
+| `BrowserExtensionIconWalletConfig` | `defaults?: IconWalletDefaults` | `{}` |
+| `SecretInjectiveWalletConfig` | `defaults?: InjectiveWalletDefaults` | `{}` |
+| `BrowserExtensionInjectiveWalletConfig` | `defaults?: InjectiveWalletDefaults` | `{}` |
+| `PrivateKeyNearWalletConfig` | `defaults?: NearWalletDefaults` | `{}` |
+| `BrowserExtensionNearWalletConfig` | `defaults?: NearWalletDefaults` | `{}` |
+| `PrivateKeyStacksWalletConfig` | `defaults?: StacksWalletDefaults` | `{}` |
+| `BrowserExtensionStacksWalletConfig` | `defaults?: StacksWalletDefaults` | `{}` |
+
+---
+
+## New library-exports re-exports
+
+See [`recipes/library-exports.md`](../../../integration/knowledge/recipes/library-exports.md) for the full table. Re-exporting these means consumers can drop direct deps on upstream chain SDKs for type-only usage.
+
+Summary:
+
+- **viem** — `Account`, `Address`, `Chain`, `Transport`, `PublicClient`, `WalletClient`, `HttpTransportConfig`, `PublicClientConfig`, `WalletClientConfig`, `SendTransactionParameters`, `WaitForTransactionReceiptParameters`, `TransactionReceipt`
+- **@mysten/sui** — `SuiTransactionBlockResponseOptions`, `Transaction`, `TransactionArgument`
+- **@mysten/wallet-standard** — `SuiWalletFeatures`, `WalletAccount`, `WalletWithFeatures`
+- **@solana/web3.js** — `Commitment`, `ConnectionConfig`, `SendOptions`
+- **@injectivelabs/*** — `Network`, `ChainId`, `EvmChainId`, `MsgBroadcaster`
+- **@stellar/stellar-sdk** — `Networks` (runtime value)
+- **@stacks/transactions** — `PostConditionMode` (runtime enum), `ClarityValue`, `PostConditionModeName`
+- **@stacks/network** — `StacksNetwork`
+- **@stacks/connect** — `StacksProvider`
+- **near-api-js** — `KeyPairString`
+- **@hot-labs/near-connect** — `NearConnector`
+- **bitcoinjs-lib** — `Network as BitcoinJsNetwork`

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/deleted-exports.md

@@ -0,0 +1,35 @@
+# Deleted exports
+
+**No symbols were deleted from the public surface between v1 and v2.** Every v1 named export is still available on v2's barrel.
+
+If a v1 import does not compile against v2, the cause is most likely:
+
+| Symptom | Likely cause |
+|---|---|
+| `Cannot find module '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` | Deep import from v1's flat layout. Replace with barrel: `from '@sodax/wallet-sdk-core'`. See [`../breaking-changes/folder-layout.md`](../breaking-changes/folder-layout.md). |
+| `'X' has no exported member 'Y'` against `@sodax/sdk` or `@sodax/types` | Not this package. See the corresponding package's migration docs. |
+| Symbol `shallowMerge` not found | Internal in both v1 and v2 (v1 didn't even have it). Use `defaults` config + per-call options. |
+
+---
+
+## Internal symbols (never publicly exported, in any version)
+
+| Symbol | Where it lives | Replacement |
+|---|---|---|
+| `shallowMerge` | `src/utils/merge.ts` (v2 only — did not exist in v1) | Use the `defaults` config + per-call options. Merge is automatic. |
+| `serializeReceipt` | private static on `EvmWalletProvider` | `waitForTransactionReceipt` already returns the serialised shape. |
+| Anything under `src/utils/` | — | Internal. |
+
+If user code deep-imports one of these, it must be replaced with a public API call.
+
+---
+
+## How to verify
+
+```bash
+grep -rn "shallowMerge" <user-src>
+# expect empty
+
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty
+```

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/renamed-symbols.md

@@ -0,0 +1,31 @@
+# Renamed symbols
+
+**None.** No symbol exported from `@sodax/wallet-sdk-core` was renamed between v1 and v2.
+
+This file exists so AI agents and humans can look up "what was renamed" and get a definitive **nothing**. If you suspect a rename, you are almost certainly looking at the wrong package:
+
+- `@sodax/sdk` — has real v1→v2 renames (e.g. `EvmSpokeProvider` → `EvmSpokeService`).
+- `@sodax/types` — has real v1→v2 renames (e.g. `SONIC_MAINNET_CHAIN_ID` removed in favor of `ChainKeys.SONIC_MAINNET`).
+- `@sodax/wallet-sdk-react` — has real v1→v2 renames (e.g. `useXWagmiStore` removed; `rpcConfig` prop → `config`).
+
+For wallet-sdk-core itself, v1 and v2 share **identical** public type names:
+
+- `EvmWalletConfig`, `PrivateKeyEvmWalletConfig`, `BrowserExtensionEvmWalletConfig`
+- `SolanaWalletConfig`, `PrivateKeySolanaWalletConfig`, `BrowserExtensionSolanaWalletConfig`
+- `SuiWalletConfig`, `PrivateKeySuiWalletConfig`, `BrowserExtensionSuiWalletConfig`
+- `BitcoinWalletConfig`, `PrivateKeyBitcoinWalletConfig`, `BrowserExtensionBitcoinWalletConfig`
+- `StellarWalletConfig`, `PrivateKeyStellarWalletConfig`, `BrowserExtensionStellarWalletConfig`
+- `IconWalletConfig`, `PrivateKeyIconWalletConfig`, `BrowserExtensionIconWalletConfig`
+- `InjectiveWalletConfig`, **`SecretInjectiveWalletConfig`** (note: not `PrivateKey*` — same in v1), `BrowserExtensionInjectiveWalletConfig`
+- `NearWalletConfig`, `PrivateKeyNearWalletConfig`, `BrowserExtensionNearWalletConfig`
+- `StacksWalletConfig`, `PrivateKeyStacksWalletConfig`, `BrowserExtensionStacksWalletConfig`
+
+…and the corresponding provider class names (`EvmWalletProvider`, …).
+
+If a v1 codebase compiles against v2 with no symbol-not-found errors, that is the expected outcome.
+
+---
+
+## What WAS added
+
+See [`added-fields.md`](./added-fields.md) for new types (`*WalletDefaults`, `*Policy` types, `BaseWalletProvider`) and new optional fields (`defaults?`, Stellar's `rpcUrl?`).

package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/reference/return-shapes.md

@@ -0,0 +1,23 @@
+# Return shapes
+
+Method return shapes that changed between RC versions.
+
+---
+
+## Currently: no breaking return-shape changes
+
+All provider method return types are stable across the RC series. This file is a placeholder — future return-shape changes will be documented here in the same format used by `@sodax/sdk`'s migration docs (paired before/after shapes per method).
+
+---
+
+## What to check anyway
+
+If you suspect a return shape issue:
+
+```bash
+pnpm checkTs
+```
+
+Any TypeScript error mentioning a `@sodax/wallet-sdk-core` method's return type is most likely (a) propagated from `@sodax/sdk` / `@sodax/types` (which **did** change between v1 and v2), or (b) the consumer is reading a method that **never had** the shape they expect.
+
+For (a), open an issue with the version delta — we'll add it to this file. For (b), see [`reference/interfaces.md`](../../../integration/knowledge/reference/interfaces.md) for the authoritative current shape.

package/skills/sodax-wallet-sdk-react/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: sodax-wallet-sdk-react
+description: 'INTEGRATION (write NEW code) — @sodax/wallet-sdk-react is the React wallet connectivity layer for multi-chain dapps. Covers `SodaxWalletProvider` setup, hook-based connect/disconnect/account/signing UX across 9 chain types (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks), headless wallet-modal primitives, WalletConnect for non-injected wallets (Fireblocks/Ledger/mobile), and `useWalletProvider` for bridging the connected wallet into `@sodax/sdk` calls. Use whenever a React dapp needs SODAX wallet connectivity. Triggers on "add wallet connect", "set up SodaxWalletProvider", "useXConnect", "useXAccount", "useWalletProvider", "useWalletModal", "wallet modal", "connect button", "multi-chain wallet UI", "WalletConnect for Fireblocks". Peer deps: `react >= 19`, `@tanstack/react-query 5.x`. MIGRATION (port v1 → v2) — the v2 reshape removed `useXWagmiStore` from the public API (each selector must be replaced with a public hook like `useXServices` / `useXService({ xChainType })` / `useXConnections` / `useXConnection({ xChainType })`; do NOT rename to `useXWalletStore` — the v2 barrel does not export it), unified hook signatures to single-object params, reshaped `SodaxWalletProvider` props (removed `rpcConfig` / `options` / `initialState` in favor of `config: SodaxWalletConfig`), and flattened the chain-slot wrapper (`chains: { EVM, SOLANA, ... }` → top-level slots on `SodaxWalletConfig`). Triggers on "useXWagmiStore is gone", "SodaxWalletProvider props broke", "old wallet-sdk-react hooks", "upgrade @sodax/wallet-sdk-react". Load this skill if EITHER applies; the body gates by mode.'
+---
+
+# When to use this skill
+
+AGENTS.md routes you here when you're working with `@sodax/wallet-sdk-react` v2 — either writing new code or porting from v1.
+
+**Pick your mode:**
+
+- Writing NEW v2 code (greenfield, no v1 imports)? → § **Integration mode** below.
+- Porting EXISTING v1 code to v2 (grep finds `useXWagmiStore`, `rpcConfig`, `initialState`, or positional-args hooks)? → § **Migration mode** below.
+- Both? → migration first, then integration.
+
+For backend / non-React → use `sodax-wallet-sdk-core` instead.
+For React dapps with hooks wrapping the SDK → also load `sodax-dapp-kit`.
+
+---
+
+## Integration mode (writing new v2 code)
+
+Pick this mode when the consumer is a React dapp that needs SODAX wallet connectivity. Common signals:
+
+- "I need a wallet connect button" — `useXConnect`, `useXAccount`.
+- "Multi-chain modal UI" — `useWalletModal`, `useChainGroups`, `useConnectedChains`.
+- "Pass the connected wallet to a `@sodax/sdk` swap" — `useWalletProvider({ xChainId })`.
+- "Add WalletConnect for enterprise custody (Fireblocks, mobile)" — `walletConnect` field on `SodaxWalletConfig.EVM`.
+- "SSR with Next.js" — `ssr: true` flag on the EVM slot.
+
+### Workflow
+
+1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow.
+2. **Always start with setup** → [`integration/knowledge/recipes/setup.md`](./integration/knowledge/recipes/setup.md). Mount `SodaxWalletProvider`, declare chain-type slots, wire `@tanstack/react-query`.
+3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — provider mount tree, frozen config, EVM single-connection model, `xChainType` vs `xChainId`.
+4. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `connect-button.md`, `multi-chain-modal.md`, `walletconnect-setup.md`, `bridge-to-sdk.md`, `sign-message.md`, `switch-chain.md`, `batch-operations.md`, `chain-detection.md`, `sub-path-imports.md`.
+5. Working examples → [`integration/knowledge/examples/`](./integration/knowledge/examples/) — 4 working `.tsx` app shells (`01-minimal-evm`, `02-multi-chain-modal`, `03-nextjs-app-router`, `04-walletconnect-setup`).
+6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — hooks, connectors, chain-support, wallet-brands, api-surface.
+
+### Conventions to follow (integration)
+
+- **Single object parameter on every hook.** `useXConnectors({ xChainType: 'EVM' })`, `useXAccount({ xChainId: ChainKeys.BSC_MAINNET })`, `useWalletProvider({ xChainType: 'EVM' })`. `useXAccount` and `useWalletProvider` take **either** `xChainId` (chain key) **or** `xChainType` (family) — never both.
+- **`useXConnect` is a React Query mutation.** Pass an `IXConnector` to `mutate` / `mutateAsync`. For provider-managed chains (EVM/Solana/Sui), the resolved value is `undefined` — read the connected account via `useXAccount` after the mutation lands.
+- **Persisted connections.** Connections survive page reloads via `localStorage` (key `xwagmi-store`). Gate UI on hydration with `useConnectedChains().status === 'ready'` to avoid flicker.
+- **EVM is one connection across all networks.** wagmi covers every configured EVM network under one connector — `useChainGroups` / `useConnectedChains` report a single `EVM` row.
+- **Configurable chain opt-in.** `SodaxWalletProvider config` accepts a `SodaxWalletConfig` where top-level keys are `ChainType` slots (`EVM`, `SOLANA`, `SUI`, `BITCOIN`, `STELLAR`, `INJECTIVE`, `ICON`, `NEAR`, `STACKS`). Omit a slot to skip mounting that adapter; pass `{}` to mount with SDK defaults.
+- **Don't import concrete chain classes from the barrel.** `EvmXService`, `XverseXConnector`, etc. are **deep-import only** (`@sodax/wallet-sdk-react/xchains/<chain>`). The barrel only exports hooks, types, interfaces, and `SodaxWalletProvider`.
+
+### Wallet modal primitives
+
+Headless building blocks (render-agnostic, wallet-agnostic):
+
+| Hook | Purpose |
+|---|---|
+| `useWalletModal({ onConnected })` | State machine: `closed → chainSelect → walletSelect → connecting → success \| error`. |
+| `useConnectionFlow()` | `connect + status + retry` without a modal. |
+| `useBatchConnect({ connectors, skipConnected })` | Sequential connect across every chain a wallet identifier covers. |
+| `useBatchDisconnect({ connectors? })` | Mirror of `useBatchConnect`; omit `connectors` to disconnect all. |
+| `useChainGroups({ order? })` | One entry per enabled chain; EVM collapses to one group. |
+| `useConnectedChains({ order? })` | Aggregate connected view; `status: 'loading' \| 'ready'`. |
+| `useIsWalletInstalled({ connectors?, chainType? })` | Cross-chain install check; filters AND. |
+| `sortConnectors(xs, { preferred })` | Preferred first, then installed, then original. |
+
+Reference app: `apps/wallet-modal-example` in the SODAX monorepo.
+
+### Top traps to avoid (integration)
+
+1. **Passing both `xChainId` and `xChainType`** to `useXAccount` / `useWalletProvider`. They're mutually exclusive.
+2. **Casting the return value of `useWalletProvider`.** Use the chain-key narrowing pattern (passing a specific `xChainId`) to get the typed `IXxxWalletProvider` without `as`.
+3. **Importing concrete classes from the barrel.** `EvmXService`, `XverseXConnector`, etc. live behind `@sodax/wallet-sdk-react/xchains/<chain>` deep imports.
+4. **Ignoring the persist-hydration gate.** Render UI before `useConnectedChains().status === 'ready'` and you get a flicker / stale-state.
+5. **Forgetting WalletConnect setup for enterprise custody.** Default EVM discovery is EIP-6963 (browser extensions only). Fireblocks / Ledger / mobile-only wallets need the `walletConnect` field on the `EVM` slot.
+
+### Verification (integration)
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+```
+
+Manually verify in browser:
+- Connect / disconnect flows work for at least one wallet per enabled chain.
+- Page reload preserves the connection (until `useXDisconnect`).
+- `useWalletProvider({ xChainId: ChainKeys.X })` returns the chain-narrowed `IXxxWalletProvider`, ready to pass into `@sodax/sdk` calls (with `raw: false`).
+
+---
+
+## Migration mode (v1 → v2 porting)
+
+Pick this mode if the consumer has v1 wallet-sdk-react patterns. Grep signals:
+
+```bash
+grep -rE 'useXWagmiStore|rpcConfig|initialState' src/
+grep -rE 'SodaxWalletProvider.*(options|rpcConfig|initialState)' src/
+```
+
+The package name **did not change** between v1 and v2 — both versions publish as `@sodax/wallet-sdk-react`. Migration is detected by import surface, not by package name.
+
+If a project has both v1 patterns AND a request for new features: **migration first, then integration**.
+
+### Workflow
+
+1. Read [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — DO / DON'T + workflow + stop conditions.
+2. Read [`migration-v1-to-v2/knowledge/breaking-changes.md`](./migration-v1-to-v2/knowledge/breaking-changes.md) — full narrative of every v1 → v2 change.
+3. Apply per-task recipes from [`migration-v1-to-v2/knowledge/recipes/`](./migration-v1-to-v2/knowledge/recipes/) — `connect-button.md`, `multi-chain-modal.md`, `ssr-setup.md`, `walletconnect-migration.md`.
+4. Use [`reference/`](./migration-v1-to-v2/knowledge/reference/) lookups when symbols don't match — `imports.md`, `hooks.md`, `config.md`, `components.md`.
+5. Verify with [`checklist.md`](./migration-v1-to-v2/knowledge/checklist.md).
+
+### Top mechanical changes
+
+1. **`useXWagmiStore` removed from the public API.** v2 does **not** export the store hook at all — neither `useXWagmiStore` nor `useXWalletStore` is available from the package barrel. Replace each `useXWagmiStore(state => state.X)` selector with the matching public hook (`useXServices`, `useXService({ xChainType })`, `useXConnections`, `useXConnection({ xChainType })`, etc.). See [`migration-v1-to-v2/knowledge/reference/imports.md`](./migration-v1-to-v2/knowledge/reference/imports.md) § "Store hook removed from the public API" for the full field-to-hook map and a STOP decision tree for selectors hitting v2-internal fields. The localStorage persistence key `'xwagmi-store'` is unchanged, so user connections survive the upgrade.
+2. **Hook args unified to a single object.** v1 hooks took positional args; v2 hooks take `{ xChainType }` or `{ xChainId }` (mutually exclusive on `useXAccount` / `useWalletProvider`).
+3. **`SodaxWalletProvider` props.** v1's `rpcConfig`, `options`, `initialState` props are removed. v2 takes one `config: SodaxWalletConfig` prop where top-level keys are `ChainType` slots (`EVM`, `SOLANA`, `SUI`, …). The old `chains: { EVM, SOLANA, ... }` wrapper is also gone — chain-type slots are now top-level.
+4. **Per-chain entry shape varies.** EVM/SOLANA/SUI/ICON/NEAR use `{ rpcUrl?, defaults? }`; BITCOIN/STELLAR/INJECTIVE extend their `*RpcConfig` with `{ defaults? }`; STACKS accepts a preset name or `StacksNetworkLike & { defaults? }`.
+
+### Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| User wants a chain family not in `integration/knowledge/reference/chain-support.md` | Adding a new chain is a maintainer task. |
+| User has a custom `XService` / `XConnector` subclass with non-trivial logic | Custom subclasses are a maintainer-only path. Confirm scope first. |
+| User mixes v1 and v2 patterns in new code being written | Do migration first, then integration. |
+
+### DO (migration)
+
+- Replace every `useXWagmiStore(state => state.X)` selector with the matching v2 public hook (`useXServices`, `useXService({ xChainType })`, `useXConnections`, `useXConnection({ xChainType })`, …) — drop the `useXWagmiStore` import entirely. See `migration-v1-to-v2/knowledge/reference/imports.md` § "Store hook removed" for the field-to-hook map.
+- Reshape `SodaxWalletProvider` props to the single `config` object.
+- Move RPC config from old `rpcConfig` prop to per-chain `{ rpcUrl }` under the relevant slot.
+- For EVM-only WalletConnect setup (Fireblocks etc.), add `walletConnect: { projectId: '…' }` to the EVM slot — see `recipes/walletconnect-migration.md`.
+
+### DO NOT (migration)
+
+- **Rename `useXWagmiStore` to `useXWalletStore`.** The v2 barrel does not export either name. The store implementation file is named `useXWalletStore.ts` internally, but the hook is private — every consumer call site must move to a public hook.
+- Keep destructuring positional args from hooks — every v2 hook takes one object.
+- Use `rpcConfig` / `options` / `initialState` props on `SodaxWalletProvider` — they're gone.
+- Pass both `xChainId` and `xChainType` to `useXAccount` / `useWalletProvider` — mutually exclusive.
+- Forget about persist hydration. `useConnectedChains().status === 'ready'` gates UI; render too early and you get flicker.
+
+### Verification (migration)
+
+```bash
+pnpm tsc --noEmit                                      # must exit clean
+grep -rE 'useXWagmiStore|useXWalletStore' src/         # empty — v2 exports neither
+grep -rE 'SodaxWalletProvider.*(rpcConfig|initialState)' src/   # empty
+```
+
+Manual: connections still survive page reload (localStorage key `xwagmi-store` was preserved for backward compat).
+
+---
+
+# Related skills
+
+- `sodax-dapp-kit` — React hooks wrapping `@sodax/sdk`. Use `useWalletProvider` to bridge.
+- `sodax-sdk` — for any direct SDK call from the React app (or for the SDK-level v1 → v2 work that often runs alongside this one).
+- `sodax-wallet-sdk-core` — the underlying provider classes that `useWalletProvider` returns.

package/skills/sodax-wallet-sdk-react/integration/knowledge/README.md

@@ -0,0 +1,103 @@
+# Integration: First-time setup (Human-readable overview)
+
+This folder helps you integrate `@sodax/wallet-sdk-react` into a fresh React app. It is the **human-facing** entry point for new integrations. If you are a coding agent, read [`ai-rules.md`](./ai-rules.md) first.
+
+If you are migrating from v1 instead, see [`sodax-wallet-sdk-react` (migration mode)](../../migration-v1-to-v2/knowledge/).
+
+---
+
+## What this package does
+
+`@sodax/wallet-sdk-react` is the React layer over `@sodax/wallet-sdk-core`. It gives you:
+
+- **Multi-chain wallet connect** across 9 chain types (EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks).
+- **Hooks** (`useXConnect`, `useXAccount`, `useXDisconnect`, `useXSignMessage`, etc.) backed by a Zustand store — composable and SSR-safe.
+- **Headless modal primitives** (`useWalletModal`, `useChainGroups`, `useBatchConnect`) — bring your own UI.
+- **Typed wallet providers** for hand-off to `@sodax/sdk` calls (`useWalletProvider`).
+
+---
+
+## Recommended path (in order)
+
+If this is your first time using the package:
+
+1. [`recipes/setup.md`](./recipes/setup.md) — install, wire `SodaxWalletProvider`, pick chain slots. **Always do this first**.
+2. Pick a connect UX (one, not both):
+   - [`recipes/connect-button.md`](./recipes/connect-button.md) — single chain, simplest UX.
+   - [`recipes/multi-chain-modal.md`](./recipes/multi-chain-modal.md) — chain picker + connector picker, headless.
+3. [`recipes/sign-message.md`](./recipes/sign-message.md) — sign messages cross-chain (auth flows).
+4. [`recipes/bridge-to-sdk.md`](./recipes/bridge-to-sdk.md) — pass `walletProvider` to `@sodax/sdk` calls (swaps, lending, staking, etc.).
+5. [`recipes/switch-chain.md`](./recipes/switch-chain.md) — switch the active EVM network when source chain doesn't match.
+6. [`recipes/chain-detection.md`](./recipes/chain-detection.md) — list enabled chains, render connected list with hydration gate, install detection.
+7. Add advanced features as needed:
+   - [`recipes/walletconnect-setup.md`](./recipes/walletconnect-setup.md) — enable WalletConnect for enterprise-custody / mobile-only wallets.
+   - [`recipes/batch-operations.md`](./recipes/batch-operations.md) — batch connect / disconnect across multiple chains.
+   - [`recipes/sub-path-imports.md`](./recipes/sub-path-imports.md) — deep imports from `xchains/<chain>` for `instanceof` checks or custom connector lists.
+8. Reference docs (lookup as needed):
+   - [`reference/hooks.md`](./reference/hooks.md) — full hook surface with signatures.
+   - [`reference/connectors.md`](./reference/connectors.md) — available wallet connectors per chain.
+   - [`reference/chain-support.md`](./reference/chain-support.md) — supported chains, slots, and adapter notes.
+9. Copy-paste examples (runnable code, minimal narrative):
+   - [`examples/`](./examples/) — 4 self-contained `.tsx` files: minimal EVM setup, multi-chain modal, Next.js App Router, WalletConnect setup.
+
+---
+
+## Install
+
+```bash
+pnpm add @sodax/wallet-sdk-react @tanstack/react-query
+```
+
+Peer dependencies:
+
+```json
+{
+  "react": ">=19",
+  "@tanstack/react-query": "5.x"
+}
+```
+
+---
+
+## Pair with `@sodax/sdk` and `@sodax/dapp-kit`
+
+Most apps integrate this package together with the SDK and dapp-kit:
+
+```
+@sodax/sdk            ← business logic (swaps, lending, staking, etc.)
+@sodax/dapp-kit       ← high-level React hooks combining SDK + wallet-sdk
+@sodax/wallet-sdk-react  ← wallet connectivity (this package)
+```
+
+If you are using all three, mount providers in this order at the app root:
+
+```tsx
+// @ai-snippets-skip
+<SodaxProvider config={sodaxConfig}>            {/* @sodax/dapp-kit */}
+  <QueryClientProvider client={queryClient}>
+    <SodaxWalletProvider config={walletConfig}>  {/* this package */}
+      {children}
+    </SodaxWalletProvider>
+  </QueryClientProvider>
+</SodaxProvider>
+```
+
+`SodaxProvider` (from dapp-kit) wraps the lot. `QueryClientProvider` must wrap `SodaxWalletProvider` because hooks inside use React Query.
+
+---
+
+## Conventions worth knowing
+
+- **Hooks use a single options object.** `useXConnectors({ xChainType: 'EVM' })`, not positional args.
+- **`xChainId` (chain key) and `xChainType` (family) are both accepted** by `useXAccount` and `useWalletProvider`. Pass one, not both.
+- **`useXConnect` is a React Query mutation.** Pass an `IXConnector` to `mutateAsync`.
+- **Persisted connections.** Connections survive reload via `localStorage` key `xwagmi-store`. Gate UI on `useConnectedChains().status === 'ready'` to avoid hydration flicker.
+- **EVM is one connection across all networks.** wagmi treats every configured EVM chain as part of one connector — there is no per-network connect/disconnect.
+
+---
+
+## Getting help
+
+- API surface lookup: [`reference/`](./reference/).
+- Bug or missing feature: [open an issue](https://github.com/icon-project/sodax-sdks/issues).
+- Internal architecture (only relevant for SODAX maintainers): `../CLAUDE.md` in the package root.