@sodax/skills 2.0.0-rc.4

package/knowledge/wallet-sdk-core/migration/checklist.md

@@ -0,0 +1,62 @@
+# Migration checklist
+
+Run through every item before declaring the migration done. Each item is machine-checkable.
+
+---
+
+## Mandatory
+
+- [ ] **No deep imports from `@sodax/wallet-sdk-core/src/…`**
+  ```bash
+  grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+  # expect empty
+  ```
+  v1's flat layout (`wallet-providers/EvmWalletProvider.ts`) no longer resolves under v2's folder-per-chain layout. Only the barrel root is public.
+
+- [ ] **No imports of internal utilities**
+  ```bash
+  grep -rn "shallowMerge" <user-src>
+  # expect empty
+  ```
+  `shallowMerge` is internal in v2 (and didn't exist in v1). Use `defaults` config + per-call options.
+
+- [ ] **`pnpm checkTs` exits clean** with no `@sodax/wallet-sdk-core` symbol errors.
+
+---
+
+## Recommended (optional cleanup)
+
+- [ ] **Drop direct upstream-SDK type imports covered by `library-exports`**
+  ```bash
+  grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt|SendTransactionParameters|WaitForTransactionReceiptParameters|HttpTransportConfig|PublicClientConfig|WalletClientConfig"
+  grep -rn "from '@stellar/stellar-sdk'" <user-src> | grep "Networks"
+  grep -rn "from '@stacks/transactions'" <user-src> | grep -E "PostConditionMode|ClarityValue|PostConditionModeName"
+  grep -rn "from '@mysten/wallet-standard'" <user-src>
+  grep -rn "from '@solana/web3.js'" <user-src> | grep -E "Commitment|ConnectionConfig|SendOptions"
+  grep -rn "from '@injectivelabs/networks'" <user-src> | grep "Network"
+  grep -rn "from '@injectivelabs/ts-types'" <user-src> | grep -E "ChainId|EvmChainId"
+  grep -rn "from '@injectivelabs/wallet-core'" <user-src> | grep "MsgBroadcaster"
+  grep -rn "from '@hot-labs/near-connect'" <user-src> | grep "NearConnector"
+  grep -rn "from '@stacks/network'" <user-src> | grep "StacksNetwork"
+  grep -rn "from '@stacks/connect'" <user-src> | grep "StacksProvider"
+  # if any matches, decide whether to re-import via @sodax/wallet-sdk-core
+  ```
+
+- [ ] **Direct upstream-SDK deps removed from `package.json`** (only if 100% replaced by library-exports)
+  ```bash
+  cat <user>/package.json | jq -r '.dependencies | keys[]' | grep -E '^(viem|@stellar/stellar-sdk|@stacks/transactions|@mysten/sui|@mysten/wallet-standard|@solana/web3.js|@injectivelabs/networks|@injectivelabs/ts-types|@injectivelabs/wallet-core|@hot-labs/near-connect|@stacks/network|@stacks/connect)$'
+  # confirm each remaining entry is genuinely needed for a runtime symbol library-exports doesn't cover
+  ```
+
+- [ ] **`defaults` adopted in places where wrappers were hand-rolled**
+  Look for ad-hoc wrappers (`makeProvider`, `buildProvider`, `withDefaults`) that injected default gas / commitment / timeout values, and replace them with provider-level `defaults` config.
+
+---
+
+## Verification of behavior
+
+- [ ] **Get-address smoke test** passes for every provider the user constructs.
+- [ ] **One signing flow** runs end-to-end against a testnet (or recorded mock).
+- [ ] **CI passes** (`pnpm lint && pnpm checkTs && pnpm test`).
+
+When all mandatory + behavior items above are checked, the migration is done. Optional items are bonus.

package/knowledge/wallet-sdk-core/migration/recipes/README.md

@@ -0,0 +1,12 @@
+# Migration recipes
+
+Paired before/after for each migration task. Apply only what the user's project triggers.
+
+**There are no mandatory migration recipes for wallet-sdk-core.** v1 consumer code drops in unchanged.
+
+| Recipe | When to apply | Mandatory? |
+|---|---|---|
+| [`adopt-defaults.md`](./adopt-defaults.md) | User has hand-rolled wrappers (`makeProvider`, `buildProvider`, `withDefaults`) that injected default options. | No — additive cleanup. |
+| [`adopt-library-exports.md`](./adopt-library-exports.md) | User imports types directly from upstream chain SDKs that `library-exports` now covers. | No — additive cleanup. |
+
+If the user's only signal is "wallet-sdk-core was bumped to v2", **no recipe is needed**. Run `pnpm checkTs`, verify zero `@sodax/wallet-sdk-core` errors, and stop.

package/knowledge/wallet-sdk-core/migration/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/knowledge/wallet-sdk-core/migration/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 [`../../integration/recipes/library-exports.md`](../../integration/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/knowledge/wallet-sdk-core/migration/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/knowledge/wallet-sdk-core/migration/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 [`../../integration/recipes/library-exports.md`](../../integration/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/knowledge/wallet-sdk-core/migration/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/knowledge/wallet-sdk-core/migration/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/knowledge/wallet-sdk-core/migration/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 [`../../integration/reference/interfaces.md`](../../integration/reference/interfaces.md) for the authoritative current shape.

package/knowledge/wallet-sdk-react/AGENTS.md

@@ -0,0 +1,46 @@
+# Knowledge tree — `@sodax/wallet-sdk-react`
+
+Long-form knowledge supporting the `@sodax/wallet-sdk-react` skills under `@sodax/skills`. The action-oriented entry points are the SKILL.md files in the sibling `skills/` directory:
+
+- New code → `packages/skills/skills/sodax-wallet-sdk-react-integration/SKILL.md`
+- Porting v1 → `packages/skills/skills/sodax-wallet-sdk-react-migration/SKILL.md`
+
+**Don't read this tree top-to-bottom.** Load files from the **Workflow** section of the relevant SKILL.md.
+
+## Package summary
+
+`@sodax/wallet-sdk-react` is the React wallet-connectivity layer for SODAX 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.
+
+Audience: dApp builders. Backend / Node code uses `@sodax/wallet-sdk-core` directly instead.
+
+The package name **did not** change between v1 and v2. Migration is detected by import surface (`useXWagmiStore`, positional hook args, removed `rpcConfig` / `options` / `initialState` props on `SodaxWalletProvider`), not by package name.
+
+Peer deps: `react >= 19`, `@tanstack/react-query 5.x`.
+
+## Layout
+
+```
+knowledge/wallet-sdk-react/
+├── AGENTS.md                  # You are here
+├── integration/               # New code
+│   ├── README.md
+│   ├── ai-rules.md
+│   ├── architecture.md        # Provider mount tree, frozen config, EVM single-connection, xChainType vs xChainId
+│   ├── quickstart.md
+│   ├── examples/              # 4 working .tsx app shells (minimal-evm, multi-chain-modal, nextjs-app-router, walletconnect-setup)
+│   ├── recipes/               # 10 recipes (setup, connect-button, multi-chain-modal, walletconnect-setup, bridge-to-sdk, sign-message, switch-chain, batch-operations, chain-detection, sub-path-imports)
+│   └── reference/             # api-surface, chain-support, connectors, hooks, wallet-brands
+└── migration/                 # v1 → v2
+    ├── README.md
+    ├── ai-rules.md
+    ├── checklist.md
+    ├── breaking-changes.md    # Full narrative of every v1 → v2 change
+    ├── recipes/               # connect-button, multi-chain-modal, ssr-setup, walletconnect-migration
+    └── reference/             # imports, hooks, config, components (v1 → v2 mappings)
+```
+
+## Cross-references
+
+- SDK calls: `packages/skills/knowledge/sdk/integration/recipes/signed-tx-flow.md` shows how the connected wallet plugs into SDK payloads via `useWalletProvider`.
+- Lower-level wallet providers: `packages/skills/knowledge/wallet-sdk-core/` (the underlying provider classes that `useWalletProvider` returns).
+- Higher-level feature hooks: `packages/skills/knowledge/dapp-kit/` (React hooks wrapping `@sodax/sdk` — almost every wallet-sdk-react consumer also uses dapp-kit).

package/knowledge/wallet-sdk-react/integration/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 `../migration/`.
+
+---
+
+## 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.