@sodax/skills 2.0.0-rc.4

package/skills/sodax-dapp-kit-migration/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: sodax-dapp-kit-migration
+description: 'Port EXISTING v1 `@sodax/dapp-kit` React hooks to v2 — a deep canonicalization pass: single-object hook params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). v1 dapp-kit code will not compile against v2. Use whenever a React dapp imports v1 hooks (positional args, hook-init `spokeProvider`, `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`). Triggers on "migrate @sodax/dapp-kit", "useSpokeProvider gone", "dapp-kit v1 → v2", "invalidateMmQueries broken", "dapp-kit hook signatures changed".'
+---
+
+# When to use this skill
+
+Pick this skill when the consumer has v1 dapp-kit patterns. Grep signals:
+
+```bash
+grep -rE 'useSpokeProvider|invalidateMmQueries|useMigrate\b' src/
+grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b' src/
+```
+
+If the project has both v1 patterns AND wants new features: **migration first, then integration**. Stale v1 patterns leak into new code if you skip it.
+
+For new v2 code with no v1 history → use `sodax-dapp-kit-integration` instead.
+
+The SDK underneath also changed — load `sodax-sdk-migration` alongside this one (the migration trees cross-link).
+
+# Workflow
+
+1. Read [`../../knowledge/dapp-kit/migration/ai-rules.md`](../../knowledge/dapp-kit/migration/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
+2. Read [`../../knowledge/dapp-kit/migration/README.md`](../../knowledge/dapp-kit/migration/README.md) — overview, reading order, glossary.
+3. Walk [`checklist.md`](../../knowledge/dapp-kit/migration/checklist.md) — top-down cross-cutting steps.
+4. **Cross-cutting breaking changes** in order:
+   - [`breaking-changes/hook-signatures.md`](../../knowledge/dapp-kit/migration/breaking-changes/hook-signatures.md) — single-arg policy + `ReadHookParams` / `MutationHookParams`.
+   - [`breaking-changes/result-handling.md`](../../knowledge/dapp-kit/migration/breaking-changes/result-handling.md) — `Result<T>` success-path → throws; `mutateAsyncSafe`.
+   - [`breaking-changes/querykey-conventions.md`](../../knowledge/dapp-kit/migration/breaking-changes/querykey-conventions.md) — camelCase + default mutationKey.
+   - [`breaking-changes/sdk-leakage.md`](../../knowledge/dapp-kit/migration/breaking-changes/sdk-leakage.md) — cross-links to SDK migration tree.
+5. **Per-feature playbooks** under [`features/`](../../knowledge/dapp-kit/migration/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md`, `auxiliary-services.md`.
+6. **Codemods + adapters** → [`recipes.md`](../../knowledge/dapp-kit/migration/recipes.md).
+7. **Reference** → [`reference/`](../../knowledge/dapp-kit/migration/reference/) — `deleted-hooks.md` (e.g. `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`), `renamed-hooks.md`, `error-shape-crosswalk.md`.
+
+# Top traps to avoid
+
+1. **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` from `useWalletProvider({ xChainId: chainKey })` (`@sodax/wallet-sdk-react`) directly into `mutate(vars)`.
+2. **Treating mutation `data` as `Result<T>`.** v2's `mutationFn` unwraps before resolving — `data` is the unwrapped success value.
+3. **Forgetting `try/catch` on `mutateAsync`.** v2's `mutateAsync` rejects on SDK `!ok`. Prefer `mutateAsyncSafe` (never rejects).
+4. **Hook-level `spokeProvider` / `params`.** v1 hooks took these positionally or at hook-init. v2 hooks take only `{ mutationOptions }` (mutations) or `{ params, queryOptions }` (queries). All domain inputs live in `mutate(vars)` for mutations.
+5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** SDK leakage. Renamed: `XToken.chainKey`, `ChainKeys.X_MAINNET`.
+
+# Verification
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+grep -rE 'useSpokeProvider|invalidateMmQueries\b' src/   # empty
+```
+
+Manual:
+- Sequenced flows use `mutateAsyncSafe` and branch on `result.ok`.
+- React Query devtools show hook-owned invalidations on success (consumer `onSuccess` runs after, doesn't duplicate them).
+
+# Related skills
+
+- `sodax-dapp-kit-integration` — write new v2 code (after migration completes).
+- `sodax-sdk-migration` — the SDK-side migration runs in lockstep (chain-key renames, Result, error model).
+- `sodax-wallet-sdk-react-migration` — if the wallet layer also has v1 patterns.

package/skills/sodax-sdk-integration/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: sodax-sdk-integration
+description: 'Build NEW code against @sodax/sdk v2 — the SODAX cross-chain DeFi SDK (hub-and-spoke architecture, Sonic hub + 19 spoke chains across EVM and non-EVM). Covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN migration, partner fees, and stuck-asset recovery. Use this skill whenever a non-React or backend codebase calls `@sodax/sdk` directly (Node scripts, indexers, bots, server APIs, custom non-React browser flows). Triggers on "use @sodax/sdk", "swap with Sodax", "Sodax bridge", "Sodax money market", "Sodax staking", "cross-chain DeFi", "Sonic hub", any `Sodax` / `ChainKeys` / `Result<T>` / `SodaxError` symbol, or any cross-chain DeFi operation in a backend context. For React dapps, prefer `sodax-dapp-kit-integration` instead.'
+---
+
+# When to use this skill
+
+Pick this skill when the consumer is **writing new v2 code** that calls `@sodax/sdk` directly (no React wrapper). Common signals:
+
+- Node.js server, script, indexer, bot, or CI test that uses `Sodax`.
+- Custom browser flow without `@sodax/dapp-kit`.
+- Any cross-chain DeFi action: swap, bridge, money market (supply/borrow/withdraw/repay), staking, DEX (concentrated liquidity), migration (ICX/bnUSD/BALN), partner fees, recovery.
+
+For React dapps using hooks → use `sodax-dapp-kit-integration` instead (this skill is still relevant for any unwrapped SDK call).
+
+For porting v1 code → use `sodax-sdk-migration` first.
+
+# Workflow
+
+Follow in order. Skipping `ai-rules.md` is the most common cause of agents reverting to v1 patterns.
+
+1. Read [`../../knowledge/sdk/integration/ai-rules.md`](../../knowledge/sdk/integration/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
+2. Read [`../../knowledge/sdk/integration/quickstart.md`](../../knowledge/sdk/integration/quickstart.md) — install, initialize, first-run troubleshooting.
+3. For your feature, read [`../../knowledge/sdk/integration/features/`](../../knowledge/sdk/integration/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `icx-bnusd-baln.md`, `auxiliary-services.md`.
+4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors), read [`../../knowledge/sdk/integration/recipes/`](../../knowledge/sdk/integration/recipes/).
+5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`../../knowledge/sdk/integration/reference/`](../../knowledge/sdk/integration/reference/).
+6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`../../knowledge/sdk/integration/chain-specifics.md`](../../knowledge/sdk/integration/chain-specifics.md).
+
+# v2 in one minute
+
+1. **Chain key drives everything.** Pass `srcChainKey: ChainKeys.ETHEREUM_MAINNET` on the request payload — the SDK routes internally and TypeScript narrows `walletProvider` to the chain-specific interface via `GetWalletProviderType<K>`. There are **no** `*SpokeProvider` classes to construct.
+2. **Every async public method returns `Result<T>`.** Branch on `result.ok`. No throws across service boundaries. Sub-Result forwarding is the default: `if (!sub.ok) return sub`.
+3. **Errors are `SodaxError<C>`.** A single class with a closed 13-code reason vocabulary plus a `feature` field. The pair `(feature, code)` is your discriminator. Use `isSodaxError(e)` (not bare `instanceof`).
+4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
+5. **Config is dynamic; overrides only land on `sodax.config`.** Always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`). Direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss both `await sodax.config.initialize()` updates and `new Sodax(config)` overrides.
+
+# Top traps to avoid
+
+1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass an object satisfying the chain-specific `I*WalletProvider` interface directly into the SDK call payload. Implementations come from your application — write your own or install `@sodax/wallet-sdk-core`.
+2. **Forgetting `raw: false`.** Without the discriminator, `walletProvider` is rejected with "Object literal may only specify known properties." Add `raw: false` for signed flows; `raw: true` for unsigned-tx building.
+3. **Importing from `@sodax/types` directly.** `@sodax/sdk` re-exports the entire `@sodax/types` surface. Add `@sodax/sdk` as your only dependency; importing `@sodax/types` separately risks version skew.
+4. **Treating `Result<T>` as throw-on-failure.** v2 mutation methods do **not** throw on SDK-level failure — they resolve `{ ok: false, error }`. A `try/catch` only catches *exceptions* from inside `mutationFn` (e.g. missing `walletProvider`); it will **not** catch `RELAY_TIMEOUT` or `EXECUTION_FAILED`. Branch on `.ok`.
+5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** Renamed: `XToken.chainKey` and `ChainKeys.*`. v1 numeric/string chain-id constants are gone.
+
+# Conventions agents must follow
+
+- **`Result<T>` discrimination on `.ok`.** Always branch on `result.ok` before reading `.value` or `.error`. Forward sub-Results without re-wrapping (`if (!sub.ok) return sub`).
+- **`(feature, code)` for error switching.** Use `isSodaxError(e)`, then `e.feature` and `e.code` for routing logic. Don't string-match on `e.message`.
+- **`ChainKeys.*` over hard-coded strings.** The set of supported chains evolves per release.
+- **No `as unknown as <Type>` double-casts.** v2 type narrowing makes them unnecessary — chain-key generic flow + `GetWalletProviderType<K>` resolves to the exact interface.
+- **Don't generate `try { await sodax.<method>(...) } catch` for SDK-level failures.** That catch never fires for `Result.!ok`. Branch on `result.ok`.
+- Import only from the package root: `import { Sodax, ChainKeys, type SpokeChainKey } from '@sodax/sdk'`. Don't deep-import from `dist/...`.
+
+# Verification
+
+1. `pnpm tsc --noEmit` from the consumer repo — must exit clean.
+2. Every `await sodax.<feature>.<method>(...)` call site has `if (!result.ok)` branching.
+3. No `xToken.xChainId`, no `*_MAINNET_CHAIN_ID`, no `*SpokeProvider` references.
+4. `isSodaxError(e)` (not bare `instanceof SodaxError`) in cross-bundle code.
+
+# Related skills
+
+- `sodax-sdk-migration` — port v1 SDK call sites to v2.
+- `sodax-wallet-sdk-core-integration` — set up a wallet provider for signing flows.
+- `sodax-dapp-kit-integration` — React hooks wrapping this SDK.
+- `sodax-wallet-sdk-react-integration` — React wallet connectivity layer.

package/skills/sodax-sdk-migration/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: sodax-sdk-migration
+description: 'Port EXISTING v1 `@sodax/sdk` consumer code to v2 — the deep architectural reshape (chain-key-driven routing replaced `*SpokeProvider` classes; `Result<T>` replaced throwing methods; `SodaxError<C>` replaced module-specific error unions; `WalletProviderSlot<K, Raw>` replaced ad-hoc wallet/raw branching; `ConfigService` replaced static lookup tables). Use whenever a codebase has v1 fingerprints — `_MAINNET_CHAIN_ID`, `*SpokeProvider`, `xChainId`, `SpokeChainId`, `MoneyMarketError`/`IntentError`/`StakingError`/`BridgeError`/`MigrationError`/`AssetServiceError`/`ConcentratedLiquidityError`/`RelayError` — and the consumer wants to compile against v2. Triggers on "migrate Sodax v1", "upgrade @sodax/sdk", "v1 → v2", "port to new Sodax", "useSpokeProvider broken", "Sodax error types changed". v1 code will not compile against v2.'
+---
+
+# When to use this skill
+
+Pick this skill when the consumer has **existing v1 SDK code** that needs to compile against v2. Common signals (grep for these):
+
+```bash
+grep -rE '_MAINNET_CHAIN_ID\b|\bSpokeProvider\b|\bxChainId\b|\bSpokeChainId\b|hubAssets|moneyMarketSupportedTokens' src/
+grep -rE 'instanceof (MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError)' src/
+```
+
+If the consumer has v1 fingerprints AND also wants new features: **do migration first**. Stale v1 patterns leak into new code if you skip it.
+
+For new v2 code with no v1 history → use `sodax-sdk-integration` instead.
+
+# Workflow
+
+1. Read [`../../knowledge/sdk/migration/ai-rules.md`](../../knowledge/sdk/migration/ai-rules.md) — DO / DO NOT / workflow / stop conditions. **Read first** — prevents the most common porting mistakes.
+2. Read [`../../knowledge/sdk/migration/README.md`](../../knowledge/sdk/migration/README.md) — overview, reading order, cross-cutting checklist, v1↔v2 glossary.
+3. **Cross-cutting first.** In order:
+   - [`breaking-changes/type-system.md`](../../knowledge/sdk/migration/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `IConfigApi` Result.
+   - [`breaking-changes/architecture.md`](../../knowledge/sdk/migration/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`, relay reshape.
+   - [`breaking-changes/result-and-errors.md`](../../knowledge/sdk/migration/breaking-changes/result-and-errors.md) — throws → `Result<T>`; module errors → `SodaxError<C>`; v1↔v2 code crosswalk.
+4. **Per-feature playbooks** under [`features/`](../../knowledge/sdk/migration/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `icx-bnusd-baln.md`, `auxiliary-services.md` — read only the ones the consumer uses.
+5. **Codemods + adapters** for mechanical replacement → [`recipes.md`](../../knowledge/sdk/migration/recipes.md).
+6. **Cross-check** symbols in [`reference/`](../../knowledge/sdk/migration/reference/) — `deleted-exports.md`, `error-code-crosswalk.md`, `return-shapes.md`, `sodax-config.md`.
+
+# Mechanical type renames (do these first)
+
+Apply in this order — type-level changes don't affect behavior; runtime patterns require thinking.
+
+| v1 | v2 | Codemod |
+|---|---|---|
+| `*_MAINNET_CHAIN_ID` | `ChainKeys.*_MAINNET` | regex `(\w+)_MAINNET_CHAIN_ID` → `ChainKeys.$1_MAINNET` |
+| `XToken.xChainId` (and tokens-likes) | `XToken.chainKey` | field rename |
+| `SpokeChainId` / `ChainId` | `SpokeChainKey` | type rename |
+| `Token` | `XToken` | type rename |
+| `AddressType` (BTC) | `BtcAddressType` | only at `@sodax/types` import sites |
+
+Then on every signed-call payload: drop `spokeProvider`, add `walletProvider`, add `raw: false` discriminator, rename `intentParams` → `params`. Plus add `srcChainKey` + `srcAddress` to every action params object (MM, staking, deposit, …).
+
+# Top traps to avoid
+
+1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass `walletProvider` (an `I*WalletProvider` impl) directly in the call payload.
+2. **`instanceof MoneyMarketError` (and other module error classes).** Deleted. Replace with `isSodaxError(e) && e.feature === 'moneyMarket'`.
+3. **Destructuring cross-chain results as arrays.** v1 had `bridge()` returning a string and others returning tuples; v2 returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for **every** cross-chain mutation. Destructure as `{ srcChainTxHash, dstChainTxHash } = result.value`.
+4. **Keeping `try/catch` to inspect v1 error codes.** v2 returns `Result<T>` — failure lives on `result.error.code`, not on a thrown error. The v2 code names changed too — see `reference/error-code-crosswalk.md`.
+5. **Calling `getStakingInfo(hubAddress)`.** Renamed to `getStakingInfoFromSpoke(srcAddress, srcChainKey)`. `getStakingInfo` is not a public method anymore.
+
+# DO NOT
+
+- Grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` read shape keeps `srcChain` / `dstChain` as `IntentRelayChainId` (bigint). Only **request** types changed.
+- Assume `BalnSwapService` lock methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw — known carve-out. Keep `try/catch` for those specific calls.
+- Add `@sodax/types` as a peer dependency. It's bundled into `@sodax/sdk`'s public surface.
+
+# Verification
+
+```bash
+pnpm tsc --noEmit    # must exit clean
+# No leftover v1 fingerprints:
+grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b|\bSpokeChainId\b|\bSpokeProvider\b|hubAssets|moneyMarketSupportedTokens' src/   # empty
+grep -rE 'MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError' src/   # empty
+```
+
+Every `await sodax.<feature>.<method>(...)` call site must have `if (!result.ok)` branching (highest-leverage change — if you stop early, ensure result branching is at least in place).
+
+# Related skills
+
+- `sodax-sdk-integration` — write new v2 code (use after migration completes).
+- `sodax-wallet-sdk-core-migration` — also additively upgrade the wallet-sdk-core surface (renames are minimal there; mostly deep-import → barrel-import).
+- `sodax-dapp-kit-migration` — if the consumer also uses React hooks.
+- `sodax-wallet-sdk-react-migration` — if the consumer also has v1 wallet-sdk-react.

package/skills/sodax-wallet-sdk-core-integration/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: sodax-wallet-sdk-core-integration
+description: 'Build NEW code with `@sodax/wallet-sdk-core` — the low-level multi-chain wallet layer (one provider class per chain family across 9 chain types: EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). Each class accepts either a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows) and signs + broadcasts transactions. Use whenever a backend, script, test, or non-React browser flow needs to instantiate a wallet provider directly — `EvmWalletProvider`, `SolanaWalletProvider`, etc. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react-integration` instead — most React consumers never touch this package directly and get a typed `IXxxWalletProvider` via `useWalletProvider(...)`.'
+---
+
+# When to use this skill
+
+Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
+
+- Backend / Node scripts (CI tests, indexers, bots, server APIs).
+- Custom browser flows that don't use React.
+- Tests that need to sign with a deterministic key.
+
+For React consumers → use `sodax-wallet-sdk-react-integration` (they get the typed wallet provider via `useWalletProvider(...)` and pass it to `@sodax/sdk` calls).
+
+For upgrades from older versions → use `sodax-wallet-sdk-core-migration` (but note: v1 → v2 changes are **additive** — all v1 surface still exists, mostly just a deep-import → barrel-import cleanup).
+
+# Workflow
+
+1. Read [`../../knowledge/wallet-sdk-core/integration/ai-rules.md`](../../knowledge/wallet-sdk-core/integration/ai-rules.md) — DO / DON'T + workflow + stop conditions.
+2. Read [`../../knowledge/wallet-sdk-core/integration/architecture.md`](../../knowledge/wallet-sdk-core/integration/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (`{ type: 'PRIVATE_KEY', … }` vs `{ type: 'BROWSER_EXTENSION', … }`), shallow `defaults` merge, library-exports.
+3. Read [`../../knowledge/wallet-sdk-core/integration/quickstart.md`](../../knowledge/wallet-sdk-core/integration/quickstart.md) — copy-paste minimal example for the chain you need.
+4. For your chain, read [`../../knowledge/wallet-sdk-core/integration/features/`](../../knowledge/wallet-sdk-core/integration/features/) — per-chain config table + methods + gotchas (one file per chain family).
+5. Task-specific recipes → [`../../knowledge/wallet-sdk-core/integration/recipes/`](../../knowledge/wallet-sdk-core/integration/recipes/) — `setup-private-key.md`, `setup-browser-extension.md`, `sign-and-broadcast.md`, `defaults-and-overrides.md`, `library-exports.md`, `bridge-to-sdk.md` (pass provider to `@sodax/sdk`).
+6. Lookups → [`../../knowledge/wallet-sdk-core/integration/reference/`](../../knowledge/wallet-sdk-core/integration/reference/) — public API, provider classes, interfaces (`IXxxWalletProvider`), chain support, glossary.
+
+# Conventions to follow
+
+- **Dual-config discriminant.** Every chain's provider config has a `type` discriminator: `'PRIVATE_KEY'` (Node / scripts) or `'BROWSER_EXTENSION'` (consumer dApps). Pick one — don't merge them.
+- **`defaults` is a shallow merge.** Each provider accepts a `defaults` field for per-method overrides (e.g. `waitForTransactionReceipt`, `gasPrice`). The merge into the per-call options is **shallow**, not deep. Top-level keys overwrite wholesale.
+- **Use barrel imports**, not deep imports. Import classes from `@sodax/wallet-sdk-core`, not from `@sodax/wallet-sdk-core/wallet-providers/<chain>.ts`.
+- **Re-import chain SDK types from the barrel.** `@sodax/wallet-sdk-core` re-exports the types you need (e.g. `WalletClient` from viem, `SuiClient` from `@mysten/sui`). Don't add the underlying SDK as a direct dep — risks version skew.
+- **`IXxxWalletProvider` is the interface to pass into `@sodax/sdk`.** When bridging to the SDK, narrow with `useWalletProvider({ xChainId: ChainKeys.X })` (React) or just construct the provider directly and pass it in the SDK call payload (`{ raw: false, walletProvider }`).
+
+# Top traps to avoid
+
+1. **Mixing the two config variants.** `PRIVATE_KEY` and `BROWSER_EXTENSION` are mutually exclusive. Each chain's `*WalletProviderConfig` is a discriminated union — TypeScript catches mixing, but only if you don't use `as`.
+2. **Adding viem / `@mysten/sui` / `@solana/web3.js` as a direct dep** when the type was importable from `@sodax/wallet-sdk-core`. See `integration/recipes/library-exports.md`.
+3. **Deep-importing `@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider`**. v1's flat layout is gone; use barrel imports.
+4. **Expecting `defaults` to deep-merge.** It doesn't — top-level keys overwrite wholesale.
+5. **Trying to extend `BaseWalletProvider` directly** in consumer code. That's a maintainer-only path — write a thin wrapper over an existing provider instead.
+
+# Verification
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+```
+
+If errors mention `@sodax/wallet-sdk-core`, look up the symbol in `integration/reference/`. If the symbol isn't there, stop and ask the user — don't invent classes.
+
+# Related skills
+
+- `sodax-wallet-sdk-core-migration` — additive v1 → v2 upgrade (mostly deep-import → barrel cleanup).
+- `sodax-sdk-integration` — pass the constructed provider into SDK calls (`{ raw: false, walletProvider }`).
+- `sodax-wallet-sdk-react-integration` — for React dapps; this skill is only relevant if NOT using React.

package/skills/sodax-wallet-sdk-core-migration/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: sodax-wallet-sdk-core-migration
+description: 'Port EXISTING `@sodax/wallet-sdk-core` consumer code across versions. v1 → v2 changes are additive — same class names, same config-type names, same config shapes. The only mechanical migration is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Use when a project imports from `@sodax/wallet-sdk-core/wallet-providers/…`, when bumping from an older RC, or when adopting the new additive `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects don''t need this — if a project does anything more than the deep-import cleanup at the wallet-sdk-core surface, the real migration target is probably `@sodax/sdk` or `@sodax/types`.'
+---
+
+# When to use this skill
+
+Pick this skill ONLY if you see one of these patterns:
+
+- Deep imports: `import { … } from '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` (or similar per-chain file).
+- Bumping `@sodax/wallet-sdk-core` from an older RC and wanting to adopt new additive features (`defaults`, `*WalletDefaults`, `*Policy` types).
+
+The package name **did not change** across versions. Class names, config-type names, and config shapes are **identical** v1 → v2. **No mandatory edits** at the wallet-sdk-core surface — v1 code drops in unchanged.
+
+If a project does more than the deep-import cleanup at this surface, the real migration target is almost certainly `@sodax/sdk` (chain-key renames, Result<T>, error model) or `@sodax/types`. Route to `sodax-sdk-migration` instead.
+
+# Workflow
+
+1. Read [`../../knowledge/wallet-sdk-core/migration/ai-rules.md`](../../knowledge/wallet-sdk-core/migration/ai-rules.md) — DO / DON'T + workflow. **The headline: v1 code drops in unchanged.**
+2. Read [`../../knowledge/wallet-sdk-core/migration/README.md`](../../knowledge/wallet-sdk-core/migration/README.md) — what (additively) changed, read order, TL;DR.
+3. Read the breaking-change writeups under [`breaking-changes/`](../../knowledge/wallet-sdk-core/migration/breaking-changes/) — `folder-layout.md` (deep-import → barrel), `defaults-config.md`, `base-wallet-provider.md`, `library-exports.md`.
+4. For mechanical changes, apply the recipes in [`recipes/`](../../knowledge/wallet-sdk-core/migration/recipes/) — `adopt-defaults.md`, `adopt-library-exports.md`. **Both are optional** — they're cleanup paths, not requirements.
+5. Confirm no renames / deletions exist by checking [`reference/`](../../knowledge/wallet-sdk-core/migration/reference/) — `renamed-symbols.md` (empty), `deleted-exports.md` (empty), `added-fields.md` (additive new surface).
+6. Verify with [`checklist.md`](../../knowledge/wallet-sdk-core/migration/checklist.md).
+
+# Top mechanical changes
+
+1. **Deep imports → barrel imports.** Replace `import { EvmWalletProvider } from '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` with `import { EvmWalletProvider } from '@sodax/wallet-sdk-core'`. The flat `wallet-providers/*.ts` layout is gone.
+2. **(Optional) Re-import chain SDK types from the barrel.** Replace direct imports of `WalletClient` (viem), `SuiClient` (@mysten/sui), etc. with re-exports from `@sodax/wallet-sdk-core`. Removes the underlying SDK as a direct dep, eliminates version skew. See `recipes/adopt-library-exports.md`.
+3. **(Optional) Adopt `defaults` field.** New `defaults` (shallow-merge) field on each provider's config lets you set per-method overrides centrally. See `recipes/adopt-defaults.md`.
+
+# Top traps to avoid
+
+1. **Treating this as a real migration.** It isn't — v1 code drops in unchanged at the wallet-sdk-core surface. If the consumer's compile errors point at this package, look one layer deeper — they're almost certainly `@sodax/types` renames bleeding through (e.g. `xChainId` → `chainKey`) and the real fix is in `@sodax/sdk`'s migration.
+2. **Extending `BaseWalletProvider` in consumer code.** That's a maintainer path. If a project subclasses it, scope confirmation with the user before touching anything.
+
+# Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| Compile errors mention `@sodax/sdk` or `@sodax/types` symbols | Not this migration. Route to `sodax-sdk-migration`. |
+| Project extends `BaseWalletProvider` with non-trivial logic | Maintainer-only path. Confirm scope first. |
+| User wants a chain family not in `integration/reference/chain-support.md` | Adding a new chain is a maintainer task. |
+
+# Verification
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+# No leftover deep imports from v1's flat layout:
+grep -rE "from '@sodax/wallet-sdk-core/wallet-providers/" src/   # empty
+```
+
+# Related skills
+
+- `sodax-wallet-sdk-core-integration` — write new code (more relevant than this skill for most projects).
+- `sodax-sdk-migration` — the SDK-side migration is where the real v1 → v2 work happens.

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

@@ -0,0 +1,80 @@
+---
+name: sodax-wallet-sdk-react-integration
+description: 'Build NEW code with `@sodax/wallet-sdk-react` — 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 connection. 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`.'
+---
+
+# When to use this skill
+
+Pick this skill 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.
+
+For backend / non-React → use `sodax-wallet-sdk-core-integration` instead.
+
+For React dapps with hooks wrapping the SDK → also load `sodax-dapp-kit-integration`.
+
+For porting v1 wallet-sdk-react code → use `sodax-wallet-sdk-react-migration` first.
+
+# Workflow
+
+1. Read [`../../knowledge/wallet-sdk-react/integration/ai-rules.md`](../../knowledge/wallet-sdk-react/integration/ai-rules.md) — DO / DON'T + workflow.
+2. **Always start with setup** → [`../../knowledge/wallet-sdk-react/integration/recipes/setup.md`](../../knowledge/wallet-sdk-react/integration/recipes/setup.md). Mount `SodaxWalletProvider`, declare chain-type slots, wire `@tanstack/react-query`.
+3. Read [`../../knowledge/wallet-sdk-react/integration/architecture.md`](../../knowledge/wallet-sdk-react/integration/architecture.md) — provider mount tree, frozen config, EVM single-connection model, `xChainType` vs `xChainId`.
+4. Task-specific recipes → [`../../knowledge/wallet-sdk-react/integration/recipes/`](../../knowledge/wallet-sdk-react/integration/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 → [`../../knowledge/wallet-sdk-react/integration/examples/`](../../knowledge/wallet-sdk-react/integration/examples/) — 4 working `.tsx` app shells (`01-minimal-evm`, `02-multi-chain-modal`, `03-nextjs-app-router`, `04-walletconnect-setup`).
+6. Lookups → [`../../knowledge/wallet-sdk-react/integration/reference/`](../../knowledge/wallet-sdk-react/integration/reference/) — hooks, connectors, chain-support, wallet-brands, api-surface.
+
+# Conventions to follow
+
+- **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
+
+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
+
+```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`).
+
+# Related skills
+
+- `sodax-wallet-sdk-react-migration` — port v1 wallet-sdk-react code (deleted `useXWagmiStore`, removed `rpcConfig`/`options`/`initialState` props, etc.).
+- `sodax-dapp-kit-integration` — React hooks wrapping `@sodax/sdk`. Use `useWalletProvider` to bridge.
+- `sodax-sdk-integration` — for any direct SDK call from the React app.

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

@@ -0,0 +1,71 @@
+---
+name: sodax-wallet-sdk-react-migration
+description: 'Port EXISTING v1 `@sodax/wallet-sdk-react` consumer code to v2 — the store hook was removed from the public API (each `useXWagmiStore(state => state.X)` 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), hook signatures unified to single-object params, `SodaxWalletProvider` props reshaped (the old `rpcConfig` / `options` / `initialState` were removed in favor of a single `config: SodaxWalletConfig` object), and the chain-slot wrapper (`chains: { EVM, SOLANA, ... }`) was flattened so chain-type slots are top-level on `SodaxWalletConfig`. Use whenever a React dapp imports `useXWagmiStore`, calls hooks with positional args, or sets `rpcConfig` / `options` / `initialState` on `SodaxWalletProvider`. Triggers on "useXWagmiStore is gone", "SodaxWalletProvider props broke", "old wallet-sdk-react hooks", "upgrade @sodax/wallet-sdk-react".'
+---
+
+# When to use this skill
+
+Pick this skill 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 [`../../knowledge/wallet-sdk-react/migration/ai-rules.md`](../../knowledge/wallet-sdk-react/migration/ai-rules.md) — DO / DON'T + workflow + stop conditions.
+2. Read [`../../knowledge/wallet-sdk-react/migration/breaking-changes.md`](../../knowledge/wallet-sdk-react/migration/breaking-changes.md) — full narrative of every v1 → v2 change.
+3. Apply per-task recipes from [`../../knowledge/wallet-sdk-react/migration/recipes/`](../../knowledge/wallet-sdk-react/migration/recipes/) — `connect-button.md`, `multi-chain-modal.md`, `ssr-setup.md`, `walletconnect-migration.md`.
+4. Use [`reference/`](../../knowledge/wallet-sdk-react/migration/reference/) lookups when symbols don't match — `imports.md`, `hooks.md`, `config.md`, `components.md`.
+5. Verify with [`checklist.md`](../../knowledge/wallet-sdk-react/migration/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 [`../../knowledge/wallet-sdk-react/migration/reference/imports.md`](../../knowledge/wallet-sdk-react/migration/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/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
+
+- 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 `../../knowledge/wallet-sdk-react/migration/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
+
+- **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
+
+```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-wallet-sdk-react-integration` — write new code (use after migration completes).
+- `sodax-dapp-kit-migration` — if the consumer also uses React hooks wrapping the SDK.
+- `sodax-sdk-migration` — the SDK-level v1 → v2 work that often runs alongside this one.