@sodax/skills 2.0.0-rc.4

package/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "sodax-skills",
+  "skills": [
+    "./skills/sodax-sdk-migration",
+    "./skills/sodax-sdk-integration",
+    "./skills/sodax-wallet-sdk-core-migration",
+    "./skills/sodax-wallet-sdk-core-integration",
+    "./skills/sodax-wallet-sdk-react-migration",
+    "./skills/sodax-wallet-sdk-react-integration",
+    "./skills/sodax-dapp-kit-migration",
+    "./skills/sodax-dapp-kit-integration"
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md — `@sodax/skills` router
+
+> Tool-neutral entry point. You are looking at the consumer-facing AI material for the `@sodax/*` SDKs. If you can read multiple `SKILL.md` files, load **2–3 skills** based on what the user is building (table below). Then follow each skill's internal workflow.
+
+## What's here
+
+This package ships **eight skills** (`skills/<name>/SKILL.md`) and a **knowledge** tree (`knowledge/<pkg>/<mode>/`) split per SODAX package. Skills are action-oriented: when to use, workflow, anti-patterns, links into knowledge. Knowledge is the reference material your workflow points at.
+
+| SDK package | Skill (write new code) | Skill (port v1 → v2) |
+|---|---|---|
+| `@sodax/sdk` | `sodax-sdk-integration` | `sodax-sdk-migration` |
+| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core-integration` | `sodax-wallet-sdk-core-migration` |
+| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react-integration` | `sodax-wallet-sdk-react-migration` |
+| `@sodax/dapp-kit` | `sodax-dapp-kit-integration` | `sodax-dapp-kit-migration` |
+
+> **What about `@sodax/types`?** No skill. The package has no consumer-facing surface — it's pure TypeScript types, re-exported through `@sodax/sdk`. Importing `@sodax/types` directly invites version skew. The SDK skills cover all `@sodax/types` symbols you need.
+
+## Route by consumer intent
+
+Pick the consumer's situation, load the listed skills in order:
+
+| Consumer is… | Load skills |
+|---|---|
+| **Building a NEW React dapp** | `sodax-wallet-sdk-react-integration` → `sodax-dapp-kit-integration` → (`sodax-sdk-integration` only if dropping below dapp-kit) |
+| **Building a NEW React app, no dapp-kit** (calling the SDK directly) | `sodax-wallet-sdk-react-integration` → `sodax-sdk-integration` |
+| **Building a NEW Node / backend service or script** | `sodax-sdk-integration` → `sodax-wallet-sdk-core-integration` (only if it signs) |
+| **Building a NEW non-React browser flow** | `sodax-wallet-sdk-core-integration` → `sodax-sdk-integration` |
+| **Porting an EXISTING v1 React dapp** | `sodax-wallet-sdk-react-migration` → `sodax-dapp-kit-migration` → `sodax-sdk-migration` (then the matching `*-integration` skills for any new code) |
+| **Porting an EXISTING v1 backend** | `sodax-sdk-migration` → `sodax-wallet-sdk-core-migration` (often no-op — additive only) |
+
+If you don't know which situation applies, **ask the user** rather than guessing. Two signals to listen for:
+
+- "Migrate / upgrade / port" + v1 fingerprints (`useSpokeProvider`, `*_MAINNET_CHAIN_ID`, `xChainId`, `useXWagmiStore`, `MoneyMarketError`/`IntentError`/etc.) → migration first.
+- "Add / build / integrate" + no existing SODAX code → integration only.
+
+If both: do migration first. Stale v1 patterns leak into new code if you skip it.
+
+## How to use a skill
+
+Each `SKILL.md` is short on purpose. Follow it like a procedure:
+
+1. The skill's frontmatter `description` tells you the trigger conditions.
+2. The body's **Workflow** section links into knowledge files. Read them in order — token budgets are sized so the right 2–3 files fit in your context.
+3. The **Top traps** + **Conventions** sections are the consolidated DO / DO NOT list. Skipping them is the most common cause of generating v1 code.
+4. The **Verification** section is the done-criteria. Run those checks before reporting the task complete.
+
+## Layout reference
+
+```
+packages/skills/
+├── AGENTS.md                                   # You are here
+├── .claude-plugin/plugin.json                  # Skill registry (8 entries)
+├── skills/
+│   ├── sodax-sdk-{integration,migration}/SKILL.md
+│   ├── sodax-wallet-sdk-core-{integration,migration}/SKILL.md
+│   ├── sodax-wallet-sdk-react-{integration,migration}/SKILL.md
+│   └── sodax-dapp-kit-{integration,migration}/SKILL.md
+└── knowledge/
+    ├── sdk/{migration,integration}/            # ai-rules, quickstart, architecture, features/, recipes/, reference/, chain-specifics
+    ├── wallet-sdk-core/{migration,integration}/
+    ├── wallet-sdk-react/{migration,integration}/   # includes 4 working .tsx example apps
+    └── dapp-kit/{migration,integration}/
+```
+
+## Conventions you can rely on
+
+- **`ai-rules.md` first.** Each `<mode>/ai-rules.md` is the consolidated DO / DO NOT list. Skipping it is the top cause of stale v1 patterns.
+- **`README.md`** at every level is the tree index — useful when the skill points you at a directory rather than a file.
+- **Reference tables** under `<mode>/reference/` are for lookup, not narrative — chain keys, error codes, public API surface, hook signatures.
+- **Recipes** under `<mode>/recipes/` are self-contained — a recipe contains before/after code, steps, and verification. Don't jump between recipes for one task.
+- **Token budget**: if you're loading more than 3 files for a single task, you're probably off-route — re-check the workflow.
+
+## When SODAX is the wrong tool
+
+If the user is doing **non-SODAX work** (UI styling, unrelated DOM, unrelated backend), this package has nothing to add. Don't load skills from here.
+
+If the user is doing **DeFi work but explicitly NOT with SODAX** (e.g. "use Uniswap"), defer to the user's stated tool. The integration skills' descriptions all say: "do not substitute with other SDKs unless explicitly asked."
+
+## Feedback
+
+If an agent generates wrong code despite following a skill, that's a doc bug — file an issue at https://github.com/icon-project/sodax-sdks/issues with the prompt and the incorrect output. The package is structurally CI-guarded (frontmatter + link resolution); prose-level claims benefit from real-world feedback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Sodax]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @sodax/skills
+
+AI-agent skills and knowledge for building on the **SODAX** cross-chain DeFi platform. Drop this into your repo and your AI coding agent writes v2-correct `@sodax/*` SDK code on the first try.
+
+**Full setup** (skills CLI, npm, monorepo/local install, wiring agents to `AGENTS.md`): [docs/ai-integration-guide.md](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md).
+
+## Install
+
+Using the [`skills` CLI](https://github.com/vercel-labs/skills) from Vercel Labs — the open agent-skills ecosystem CLI (supports Claude Code, Cursor, Codex, GitHub Copilot, and 50+ other agents):
+
+```bash
+# From the root of your consumer repo
+npx skills@latest add icon-project/sodax-sdks/packages/skills
+```
+
+Eight skills land in your repo (under `.claude/skills/` or wherever the CLI installs them), one knowledge tree per SODAX SDK package, and a router `AGENTS.md`. Re-running the command picks up the latest content.
+
+> **npm fallback** (web chats or when you prefer a devDependency): `pnpm add -D @sodax/skills`, then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See the [integration guide](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md#wire-your-agent).
+
+## What you get
+
+| Bundle | Contains |
+|---|---|
+| **8 skills** under `skills/sodax-<pkg>-<mode>/SKILL.md` | One skill per (package, mode). `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. `<mode>` ∈ `migration` (port v1 → v2), `integration` (write new v2 code). |
+| **Knowledge** under `knowledge/<pkg>/<mode>/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Skills link into these. |
+| **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right set of skills. |
+
+Skills are short and action-oriented (workflow + anti-patterns + links). Knowledge is the lookup material. Don't read knowledge files top-to-bottom — the skill tells the agent which file is relevant for the current task.
+
+## Which skill applies?
+
+After install, your agent picks based on what you're building. Quick guide:
+
+| You're building | Load these skills |
+|---|---|
+| Backend / Node app (no React) using `@sodax/sdk` | `sodax-sdk-integration` (always) + `sodax-wallet-sdk-core-integration` (if signing) |
+| React dapp using `@sodax/dapp-kit` | `sodax-dapp-kit-integration` + `sodax-wallet-sdk-react-integration` (always) + `sodax-sdk-integration` (for any unwrapped operations) |
+| React app calling the SDK directly (no `dapp-kit`) | `sodax-sdk-integration` + `sodax-wallet-sdk-react-integration` |
+| **Porting v1 code** | Add the corresponding `*-migration` skill alongside each `*-integration` you'd use. |
+
+`AGENTS.md` says the same thing in router form — your agent reads it first and picks.
+
+## Why this exists
+
+LLM training data drifts: snippets from chat often use stale method names, reshaped types, or outdated error codes. Public docs help humans, not agents — an agent only reads what's in its context window. This package ships the right material in agent-native form so the agent reads it before generating code. The content is version-locked to the SDK — upgrade `@sodax/skills`, the docs upgrade with it.
+
+## Feedback
+
+If your agent generates wrong code despite reading the docs, that's a doc bug — please open an issue on the [Sodax SDKs repo](https://github.com/icon-project/sodax-sdks/issues) with the prompt and the incorrect output. The `knowledge/` tree is structurally CI-guarded (frontmatter, link resolution); prose claims benefit from real-world feedback.

package/knowledge/dapp-kit/AGENTS.md

@@ -0,0 +1,50 @@
+# Knowledge tree — `@sodax/dapp-kit`
+
+Long-form knowledge supporting the `@sodax/dapp-kit` 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-dapp-kit-integration/SKILL.md`
+- Porting v1 → `packages/skills/skills/sodax-dapp-kit-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/dapp-kit` is a React hooks library that wraps `@sodax/sdk` with React Query. It provides hooks across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Radfi, backend queries, shared) for consumer dApps. It is **React-only** — Node.js scripts and backend services use `@sodax/sdk` directly.
+
+This package is **v2**. v2 was a deep canonicalization pass over v1's hook shapes — single-object 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>`). Code written against v1 dapp-kit will not compile against v2.
+
+## v2 in one minute
+
+1. **Hooks accept a single object with one or two top-level keys.** Mutation hooks take only `{ mutationOptions }` at hook-init; query hooks take `{ params, queryOptions }`. ALL domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)` for mutations.
+2. **Every mutation hook returns `SafeUseMutationResult`** — extends React Query's `UseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>` (never rejects).
+3. **`mutationFn` throws on SDK `!ok`.** dapp-kit calls `unwrapResult` on the SDK's `Result<T>`, throwing on failure. React Query's native error model (`isError`, `error`, `onError`, `retry`, devtools) engages. `mutateAsyncSafe` packages the throw back into `Result<T>` for ergonomic branching.
+4. **Hook-owned invalidations.** Each mutation hook invalidates the relevant query keys in its `onSuccess`. Consumer-provided `onSuccess` runs after.
+5. **Canonical queryKey shape.** `[feature, action, ...identifiers]`. First segment matches the directory name (`swap`, `mm`, `bridge`, `staking`, `dex`, `bitcoin`, `partner`, `recovery`, `backend`, `shared`, `migrate`). camelCase. Bigints stringified.
+
+## Layout
+
+```
+knowledge/dapp-kit/
+├── AGENTS.md                  # You are here
+├── integration/               # New code
+│   ├── README.md
+│   ├── ai-rules.md
+│   ├── quickstart.md          # Install + wire providers + first feature
+│   ├── architecture.md        # Hook shapes, queryKey conventions, useSafeMutation, unwrapResult
+│   ├── features/              # Per-feature reference (swap, money-market, staking, bridge, dex, migration, bitcoin, auxiliary-services)
+│   ├── recipes/               # 13 patterns (setup, wallet-connectivity, per-feature, mutation-error-handling, observability, invalidations, backend-queries)
+│   └── reference/             # hooks-index, querykey-conventions, public-api, glossary
+└── migration/                 # v1 → v2 port
+    ├── README.md
+    ├── ai-rules.md
+    ├── checklist.md
+    ├── breaking-changes/      # hook-signatures, result-handling, querykey-conventions, sdk-leakage
+    ├── features/              # Per-feature porting playbooks
+    ├── recipes.md             # Codemods + adapters
+    └── reference/             # deleted-hooks, renamed-hooks, error-shape-crosswalk
+```
+
+## Cross-references
+
+- The underlying SDK: `packages/skills/knowledge/sdk/` (for any direct SDK call from a React app, or to understand how dapp-kit's hooks wrap SDK methods).
+- The wallet layer: `packages/skills/knowledge/wallet-sdk-react/` (every dapp-kit consumer needs wallet connectivity; `useWalletProvider` bridges into `mutate(vars)`).

package/knowledge/dapp-kit/integration/README.md

@@ -0,0 +1,49 @@
+# Integration — `@sodax/dapp-kit` v2
+
+This tree documents v2 of the dapp-kit React hooks for **new consumers** building against it. If you're porting v1 code, start at [`../migration/README.md`](../migration/README.md) instead.
+
+## Files in this tree
+
+| File | What's in it |
+|---|---|
+| [`ai-rules.md`](ai-rules.md) | **Read first.** DO / DO NOT / workflow / stop-conditions for AI agents writing v2 dapp-kit code. |
+| [`quickstart.md`](quickstart.md) | Install, wire providers, get a wallet provider, run your first mutation. |
+| [`architecture.md`](architecture.md) | Every v2 design concept the hooks rest on: ReadHookParams / MutationHookParams, useSafeMutation, unwrapResult, queryKey conventions, mutateAsyncSafe semantics, createSodaxQueryClient. |
+| [`features/swap.md`](features/swap.md) | Swap hooks: `useQuote`, `useSwap`, `useSwapAllowance`, `useSwapApprove`, limit orders, status polling. |
+| [`features/money-market.md`](features/money-market.md) | Money market hooks: `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, allowance/approve, reserves data. |
+| [`features/staking.md`](features/staking.md) | Staking hooks: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, info/ratio reads. |
+| [`features/bridge.md`](features/bridge.md) | Bridge hooks: `useBridge`, allowance/approve, bridgeable amount/tokens. |
+| [`features/dex.md`](features/dex.md) | DEX hooks: deposit/withdraw, supply/decrease liquidity, claim rewards, position info, pools. |
+| [`features/migration.md`](features/migration.md) | Migration hooks: ICX/bnUSD/BALN forward + reverse, allowance/approve. |
+| [`features/bitcoin.md`](features/bitcoin.md) | Radfi hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`features/auxiliary-services.md`](features/auxiliary-services.md) | Partner, recovery, backend queries, shared (xBalances, gas estimation, trustlines). |
+| [`recipes/`](recipes/) | Copy-paste patterns: setup, wallet connectivity, per-feature flows, mutation error handling, observability, invalidations. |
+| [`reference/`](reference/) | Lookup tables: full hook index, queryKey conventions, public API surface, glossary. |
+
+## Reading order for a new integrator
+
+1. **[`ai-rules.md`](ai-rules.md)** — agent rules, before any code.
+2. **[`quickstart.md`](quickstart.md)** — get providers wired and a button rendering.
+3. **[`architecture.md`](architecture.md)** — understand `useSafeMutation` / `mutateAsyncSafe` / hook shapes before writing call sites.
+4. **[`recipes/`](recipes/)** — pick the patterns you need (mutation error handling, observability, invalidations).
+5. **[`features/<x>.md`](features/)** — read the file for the feature you're integrating (reference shape; pair with the matching recipe in `recipes/<x>.md` for working examples).
+6. **[`reference/`](reference/)** — keep open while writing for table lookups.
+
+## Cross-references to migration
+
+If your project also has v1 dapp-kit call sites, port them first using:
+
+- [`../migration/README.md`](../migration/README.md) — overview, reading order, and v1↔v2 glossary.
+- [`../migration/checklist.md`](../migration/checklist.md) — top-down cross-cutting checklist.
+- [`../migration/breaking-changes/`](../migration/breaking-changes/) — the four cross-cutting changes (hook-signatures, result-handling, queryKey-conventions, sdk-leakage).
+- [`../migration/features/`](../migration/features/) — per-feature playbooks in lockstep with `integration/features/` here.
+
+The naming rule: **every file in `integration/features/` has a sibling in `migration/features/` with the same filename.** When you're deep in one, the other is one path-swap away.
+
+## Cross-references to the underlying SDK
+
+`@sodax/dapp-kit` re-exports `@sodax/sdk` at the package root, so most types you'd reach for (`ChainKeys`, `SodaxConfig`, `CreateIntentParams`, `XToken`, `Result`, `SodaxError`) are available from `@sodax/dapp-kit` directly. The Core SDK has its own knowledge tree at [`@sodax/sdk` knowledge tree](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills/knowledge/sdk/) (sibling under `@sodax/skills`). Useful for:
+
+- The full SDK migration playbook for v1→v2 (chain-key terminology, `Result<T>` semantics, ConfigService) — referenced from [`../migration/breaking-changes/sdk-leakage.md`](../migration/breaking-changes/sdk-leakage.md).
+- Architectural concepts that surface through hook signatures (`SodaxError<C>` vocabulary, `WalletProviderSlot<K, Raw>` discriminator semantics).
+- Backend / Node.js usage patterns (where dapp-kit isn't applicable).

package/knowledge/dapp-kit/integration/ai-rules.md

@@ -0,0 +1,80 @@
+# AI rules — `@sodax/dapp-kit` integration
+
+DO / DO NOT / workflow / stop conditions for AI agents writing v2 dapp-kit code. Read this **before** the per-feature docs — these rules prevent the most common load-bearing v2 traps.
+
+## Workflow (do these in order)
+
+1. **Survey the project before touching code.**
+
+   ```bash
+   pnpm tsc --noEmit                                                          # baseline typecheck
+   grep -rE '@sodax/(dapp-kit|sdk|wallet-sdk-react)' --include='*.ts' --include='*.tsx' src/   # see what's already imported
+   ```
+
+2. **Wire providers first if not already wired.** [`recipes/setup.md`](recipes/setup.md). Provider stack: `SodaxProvider > QueryClientProvider > SodaxWalletProvider > YourApp`.
+3. **Pick `mutate` / `mutateAsync` / `mutateAsyncSafe` deliberately.** See [`recipes/mutation-error-handling.md`](recipes/mutation-error-handling.md). Default to `mutateAsyncSafe` for sequenced flows.
+4. **Branch on `result.ok` for `mutateAsyncSafe` results, or on `mutation.isError` / `mutation.error`** for fire-and-forget. Never assume mutation success.
+5. **Use `useWalletProvider({ xChainId: chainKey })` from `@sodax/wallet-sdk-react` for every signed flow.** Pass the result into `mutate(vars).walletProvider`. Don't create or import any `*SpokeProvider` class — those don't exist in v2.
+
+## DO
+
+- **DO** call dapp-kit's exported hooks (which wrap `useSafeMutation`). Never call React Query's `useMutation` directly inside a wrapper around a dapp-kit hook — consumers depend on `mutateAsyncSafe`.
+- **DO** branch on `mutateAsyncSafe`'s `Result.ok` for sequenced flows (`if (!hasAllowance) await approve(...); await action(...);`). User-rejects are modal, not exceptional.
+- **DO** use `ChainKeys.X_MAINNET` constants for chain identifiers. Never hard-code chain key strings (`'sonic'`, `'0xa4b1.arbitrum'`).
+- **DO** import everything from `@sodax/dapp-kit` (or `@sodax/sdk` for SDK-only types and constants — `@sodax/dapp-kit` re-exports them anyway).
+- **DO** preserve literal chain keys in generic positions where possible (e.g. `srcChainKey: ChainKeys.ETHEREUM_MAINNET as const`) — TypeScript narrowing flows from the literal, including the `walletProvider` parameter type.
+- **DO** use the canonical hook shape: queries take `{ params, queryOptions }`; mutations take only `{ mutationOptions }` and flow domain inputs through `mutate(vars)`.
+- **DO** compose `onSuccess` instead of replacing it: `mutationOptions: { onSuccess: (data, vars, ctx) => myExtra(...) }` runs AFTER dapp-kit's hook-owned invalidations.
+
+## DO NOT
+
+- **DO NOT** call `useSpokeProvider` — it's deleted. v1 React consumers got a `SpokeProvider` from this hook; v2 has no such concept. Pass `walletProvider` directly into `mutate(vars)`.
+- **DO NOT** treat mutation `data` as `Result<T>`. `mutationFn` calls `unwrapResult` and throws on `!ok`; `data` is the unwrapped success value (e.g. `SwapResponse`, `TxHashPair`). For SDK failures, look at `mutation.error` or use `mutateAsyncSafe`.
+- **DO NOT** call `mutateAsync` without `try/catch`. It rejects on SDK `!ok`; an unhandled rejection lands in the global handler. Prefer `mutateAsyncSafe` for sequenced flows.
+- **DO NOT** put `params`, `walletProvider`, or per-call config at the hook-init level. They go in `mutate(vars)` for mutations and in `params` for queries.
+- **DO NOT** override `queryKey`, `queryFn`, or `enabled` via `queryOptions` — the hook owns those. The `queryOptions` slot is typed `Omit<UseQueryOptions, 'queryKey' | 'queryFn' | 'enabled'>`.
+- **DO NOT** override `mutationFn` via `mutationOptions` — the hook owns it. Type prevents this.
+- **DO NOT** import from `@sodax/dapp-kit/dist/...`. Deep-imports unstable; only the package root barrel is the public contract.
+- **DO NOT** add `@sodax/types` as a separate dependency. It's re-exported transitively via `@sodax/sdk` (which dapp-kit re-exports). Adding it independently invites version skew.
+- **DO NOT** recreate the v1 `invalidateMmQueries(...)` utility or anything similar. Each mutation hook invalidates the relevant keys in its own `onSuccess`. Add cross-feature invalidations via consumer `onSuccess`.
+- **DO NOT** destructure cross-chain mutation results as arrays — `[a, b] = result.value` is wrong. The shape is `TxHashPair = { srcChainTxHash, dstChainTxHash }` (object). This applies to `useBridge`, `useStake`/`useUnstake`/etc., `useDexDeposit`/`useDexWithdraw`, all four MM mutations, and all four migration mutations.
+- **DO NOT** use legacy chain-id constants (`BSC_MAINNET_CHAIN_ID`, etc.). They're gone in v2 — use `ChainKeys.X_MAINNET`.
+- **DO NOT** reach for `as any` / `as IEvmWalletProvider` casts when wiring `useWalletProvider({ xChainId })` into mutation `mutate(vars)`. v2 supports the broad-union case structurally; the cast is not needed. See `recipes/wallet-connectivity.md` § "No type cast is needed".
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| User wants a chain not in `ChainKeys.*` | Adding a new chain requires SDK-level changes — out of scope for consumer code. |
+| User wants to use React Server Components / RSC patterns | dapp-kit is client-side React (uses React Query, hooks, browser APIs). Server Components don't run hooks. Tell the user the dapp-kit code goes in client components. |
+| User wants to skip the wallet-sdk-react integration | If they have their own wallet abstraction, it's possible — they need to construct objects satisfying `I*WalletProvider` interfaces from `@sodax/sdk`. Refer them to the `sodax-sdk-integration` skill (sibling under `@sodax/skills`) for non-React patterns. |
+| User wants to use v1 dapp-kit (positional args, `useSpokeProvider`, `Result<T>` in success path) | Tell them to either upgrade or stay on v1. The shapes are not compatible. |
+
+## Verification protocol
+
+Before declaring a dapp-kit integration "done":
+
+```bash
+# 1. Type-check the consumer.
+pnpm -C <consumer> tsc --noEmit
+
+# 2. Confirm no leftover v1 patterns (if porting).
+grep -rE '\buseSpokeProvider\b|\binvalidateMmQueries\b|_MAINNET_CHAIN_ID\b|\bxChainId\b' src/
+
+# 3. Confirm all SDK-level mutation results are handled (either mutateAsyncSafe + result.ok branch
+#    or mutateAsync wrapped in try/catch).
+grep -rE 'mutateAsync\(' src/ | grep -v 'try\|catch\|mutateAsyncSafe'
+
+# 4. Confirm all hooks are imported from @sodax/dapp-kit, not deep paths.
+#    (matches `'@sodax/dapp-kit/dist'` and similar deep-import patterns)
+grep -rE "@sodax/dapp-kit/[a-z]" src/   # zero hits expected (only the root path is public)
+```
+
+## Done criteria
+
+- [ ] `SodaxProvider` + `QueryClientProvider` (preferably `createSodaxQueryClient()`) wired at the app root.
+- [ ] Every mutation invocation uses `mutateAsyncSafe` (preferred), `mutateAsync` wrapped in `try/catch`, or fire-and-forget `mutate` with state read in render.
+- [ ] No `useSpokeProvider`, no `invalidateMmQueries`, no `*_MAINNET_CHAIN_ID` constants, no `xChainId` outside known v2 hooks (e.g. `useXBalances` still uses `xChainId`).
+- [ ] No `import` from `@sodax/dapp-kit/dist/...` or any other deep path.
+- [ ] No standalone `@sodax/types` dependency in `package.json`.
+- [ ] Consumer typecheck (`pnpm tsc --noEmit`) is clean.

package/knowledge/dapp-kit/integration/architecture.md

@@ -0,0 +1,276 @@
+# Architecture — `@sodax/dapp-kit` v2
+
+Every v2 design concept the hooks rest on, in one TOC-navigable file. Read it once before writing call sites — most of the v1→v2 breakage and most of the new-code traps come from misunderstanding one of these.
+
+## Five pieces hold it together
+
+1. **Two canonical hook shapes.**
+   - Read hooks accept `{ params, queryOptions }` typed via `ReadHookParams<TData, TParams>`.
+   - Mutation hooks accept `{ mutationOptions }` typed via `MutationHookParams<TData, TVars>` and return `SafeUseMutationResult<TData, Error, TVars>`.
+   - All domain inputs (params, walletProvider, apiConfig) flow through `mutate(vars)`, never the hook arg.
+2. **`useSafeMutation` foundation.** Every mutation hook calls `useSafeMutation(...)` (drop-in for React Query's `useMutation`), which augments the result with `mutateAsyncSafe(vars): Promise<Result<TData>>` — never rejects.
+3. **`unwrapResult` translation.** SDK service methods return `Result<T>`. `unwrapResult` converts to thrown errors inside `mutationFn` so React Query's native error model engages (`isError`, `error`, `onError`, `retry`, devtools) for SDK failures.
+4. **`createSodaxQueryClient`** (optional). Factory that returns a `QueryClient` with a `MutationCache.onError` hook giving consumers a single observability seam, plus a `meta.silent` per-mutation opt-out.
+5. **Mechanical enforcement.** `_mutationContract.test.ts` asserts the canonical shape on every mutation hook (`useSafeMutation` not `useMutation`, default `mutationKey` before the spread, `mutationFn` after, `unwrapResult` translation, feature-prefix queryKey rule).
+
+## Provider stack
+
+`SodaxProvider` wraps the app and provides:
+- The `Sodax` SDK instance
+- RPC configuration for all chains
+- Hub provider access
+
+```tsx
+// @ai-snippets-skip
+<SodaxProvider config={sodaxConfig}>            {/* SDK instance + RPC config */}
+  <QueryClientProvider client={queryClient}>    {/* prefer createSodaxQueryClient() */}
+    <SodaxWalletProvider config={walletConfig}> {/* from @sodax/wallet-sdk-react (optional) */}
+      <YourApp />
+    </SodaxWalletProvider>
+  </QueryClientProvider>
+</SodaxProvider>
+```
+
+`SodaxProvider` does **not** depend on `@sodax/wallet-sdk-react` — wallet state is wired side-by-side. Backend / non-React consumers (Node scripts, bots) bypass dapp-kit entirely and use `@sodax/sdk` directly with their own wallet implementation.
+
+**Config reactivity.** `config` is tracked by reference - see [`recipes/setup.md § Config reactivity`](recipes/setup.md#config-reactivity) for the module-const vs `useMemo` patterns.
+
+### `createSodaxQueryClient`
+
+Returns a `QueryClient` pre-wired with a `MutationCache.onError` hook for global mutation observability. Default behavior: logs every mutation failure to console as `[sodax] Mutation error: <error>`.
+
+```tsx
+import { createSodaxQueryClient } from '@sodax/dapp-kit';
+
+// Default
+const queryClientDefault = createSodaxQueryClient();
+
+// Wire to your own logger
+const queryClientWithSentry = createSodaxQueryClient({
+  onMutationError: (e) => Sentry.captureException(e),
+});
+
+// Disable entirely
+const queryClientSilent = createSodaxQueryClient({ onMutationError: () => {} });
+```
+
+Per-mutation opt-out via `meta.silent`:
+
+```tsx
+// @ai-snippets-skip
+const swap = useSwap({
+  mutationOptions: {
+    meta: { silent: true },
+    onError: (e) => toast.error(e.message),
+  },
+});
+```
+
+This is **observability**, not prevention. It does NOT detect "unhandled" rejections — it fires for **every** mutation failure regardless of whether the consumer caught the rejection or registered a per-hook `onError`. To prevent unhandled rejections, use `mutateAsyncSafe`.
+
+## Read hook shape (mandatory)
+
+All read-only hooks accept a single object with exactly two top-level keys: `params` (SDK-feature-domain inputs — the *what* being fetched) and `queryOptions` (React Query knobs — the *how*).
+
+Rules:
+
+- **Single params object with two top-level keys.** `{ params, queryOptions }`. Nothing else at the top level.
+- **Use the shared types.** Params type MUST be `ReadHookParams<TData, TParams>`; the `queryOptions` slot is typed `ReadQueryOptions<TData>` (which is `Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn' | 'enabled'>`). Hook owns `queryKey`, `queryFn`, `enabled` — never consumer-overridable.
+- **Hierarchical query keys.** `[feature, action, ...inputs]`. Stringify bigints with `.toString()`.
+- **No-input hooks.** Type as `ReadHookParams<TData>` (no `TParams` generic) and accept the whole arg as optional, defaulting to `{}` for ergonomic no-arg calls (`useStakingConfig({})`).
+
+Canonical example:
+
+```ts
+// @ai-snippets-skip — definition-shape illustration; function body elided with `// ...`
+import type { PoolData, PoolKey } from '@sodax/sdk';
+import { useQuery, type UseQueryResult } from '@tanstack/react-query';
+import type { ReadHookParams } from '@sodax/dapp-kit';
+
+export type UsePoolDataParams = ReadHookParams<PoolData, { poolKey: PoolKey | null }>;
+
+export function usePoolData({ params, queryOptions }: UsePoolDataParams = {}): UseQueryResult<PoolData, Error> {
+  // ... uses sodax.dex.clService.getPoolData internally
+}
+```
+
+Call site:
+
+```ts
+// @ai-snippets-skip
+const { data } = usePoolData({ params: { poolKey } });
+```
+
+## Mutation hook shape (mandatory)
+
+All mutation hooks follow the **zero-domain-param** policy: the hook function takes a single optional argument with exactly one top-level key — `mutationOptions` — and ALL domain inputs (`params`, `walletProvider`, per-call config, etc.) flow through `mutate(vars)` via the typed `TVars` payload.
+
+Three shared utilities underpin every mutation hook:
+
+- **`useSafeMutation(options)`** — drop-in for React Query's `useMutation`. Returns `SafeUseMutationResult<TData, Error, TVars>` (extends `UseMutationResult` with `mutateAsyncSafe`).
+- **`unwrapResult(result)`** — `Result<T>` → throw `error` on `!ok`, return `value` on `ok`. Use inside `mutationFn`.
+- **`toResult(promise)`** — pure helper that catches `Promise<T>` rejection and packs into `Result<T>`. Used internally by `useSafeMutation`.
+
+Rules:
+
+- **Use `useSafeMutation`, not `useMutation`.** Every dapp-kit mutation hook MUST call `useSafeMutation`. The wrapper augments the result with `mutateAsyncSafe`, which consumers depend on.
+- **One optional top-level arg.** `useFoo({ mutationOptions } = {}): SafeUseMutationResult<TData, Error, TVars>`.
+- **Use the shared types.** `MutationHookParams<TData, TVars>`; return `SafeUseMutationResult<TData, Error, TVars>`; `mutationOptions` typed `MutationHookOptions<TData, TVars>` (which is `Omit<UseMutationOptions<TData, Error, TVars>, 'mutationFn'>`).
+- **Hook owns `mutationFn`.** Never consumer-overridable.
+- **`mutationFn` throws on SDK `!ok`.** Use `unwrapResult` from `@sodax/dapp-kit`. SDK returns `Result<T>`; the hook unwraps to `T` so React Query's native error model engages. `TData` is the unwrapped success type, NOT `Result<T>`.
+- **Default `mutationKey` BEFORE the spread**, then spread `...mutationOptions`, then `mutationFn` last. Order matters: default key is overridable by consumer (spread wins), but `mutationFn` is hook-owned.
+- **Compose `onSuccess` (and any other callbacks the hook itself defines).** Invalidations are correctness logic owned by the hook. Inside the hook's `onSuccess`, run invalidations first, then `await mutationOptions?.onSuccess?.(...)` so consumer hooks still fire.
+- **Derive invalidation keys from `vars`, not closures.** `(data, vars, ctx) => ...` and read `vars.params.srcChainKey`.
+- **All domain inputs go in `TVars`.** No `params`, `walletProvider`, `apiConfig` at the hook level. Pushing inputs into `mutate(vars)` lets a single hook serve many call shapes without remounting.
+
+Canonical example:
+
+```ts
+import type { SwapActionParams, SwapResponse, SpokeChainKey } from '@sodax/sdk';
+import { useQueryClient } from '@tanstack/react-query';
+import {
+  useSodaxContext,
+  useSafeMutation,
+  unwrapResult,
+  type MutationHookParams,
+  type SafeUseMutationResult,
+} from '@sodax/dapp-kit';
+
+export type UseSwapVars<K extends SpokeChainKey = SpokeChainKey> = Omit<SwapActionParams<K, false>, 'raw'>;
+
+export function useSwap<K extends SpokeChainKey = SpokeChainKey>({
+  mutationOptions,
+}: MutationHookParams<SwapResponse, UseSwapVars<K>> = {}): SafeUseMutationResult<SwapResponse, Error, UseSwapVars<K>> {
+  const { sodax } = useSodaxContext();
+  const queryClient = useQueryClient();
+
+  return useSafeMutation<SwapResponse, Error, UseSwapVars<K>>({
+    mutationKey: ['swap'],
+    ...mutationOptions,
+    mutationFn: async vars => unwrapResult(await sodax.swaps.swap({ ...vars, raw: false })),
+    onSuccess: async (data, vars, ctx) => {
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.srcChainKey] });
+      queryClient.invalidateQueries({ queryKey: ['shared', 'xBalances', vars.params.dstChainKey] });
+      await mutationOptions?.onSuccess?.(data, vars, ctx);
+    },
+  });
+}
+```
+
+## Choosing `mutate` / `mutateAsync` / `mutateAsyncSafe`
+
+| Method | Returns | Rejects? | When to use |
+|---|---|---|---|
+| `mutate(vars)` | `void` (fire-and-forget) | Never | Button-click handlers reading `isPending` / `isError` / `error` in render. Consumer-supplied `onError` fires; React Query owns state. |
+| `mutateAsync(vars)` | `Promise<TData>` | **Yes** on `!ok` | Imperative chains where you want exception flow. **MUST be inside `try/catch`.** |
+| `mutateAsyncSafe(vars)` | `Promise<Result<TData>>` | **Never** | Imperative chains with explicit branching, no exception flow. Same React Query state under the hood. |
+
+`mutateAsyncSafe` is the **recommended default** for sequenced flows — the user-reject case is the modal failure mode in dApps, not exceptional, and `Result<T>`-style branching reads cleaner than exception flow control.
+
+```tsx
+// @ai-snippets-skip
+// fire-and-forget — read state in render
+const m = useSwap();
+<button onClick={() => m.mutate({ params, walletProvider })}>Swap</button>
+
+// throws — for chains where you want exception flow
+const { mutateAsync } = useSwap();
+try { const r = await mutateAsync({ params, walletProvider }); /* … */ }
+catch (e) { toast(e instanceof Error ? e.message : 'Swap failed'); }
+
+// safe — for chains where you want explicit branching, no try/catch
+const { mutateAsyncSafe } = useSwap();
+const result = await mutateAsyncSafe({ params, walletProvider });
+if (!result.ok) { toast(result.error.message); return; }
+const { intent, intentDeliveryInfo } = result.value;
+```
+
+## SDK Result handling
+
+Every public SDK service method returns `Result<T> = { ok: true; value: T } | { ok: false; error: Error | unknown }` and never throws. dapp-kit translates that contract into the React Query contract by **throwing `result.error` on `!ok` inside `mutationFn`.**
+
+Why throw?
+- React Query's `isError`, `error`, `onError`, `retry`, `throwOnError`, devtools all key off `mutationFn` throwing.
+- Consumers had to remember to branch on `data.ok` inside every `onSuccess` to avoid running success logic on a failed swap. Forgetting was easy and silent.
+- Hook-owned invalidations (in `onSuccess`) used to fire on SDK failure too, burning RPC traffic on every failed click.
+
+After translating, the public hook signature is `SafeUseMutationResult<T, Error, TVars>`. `data` is the unwrapped success value (e.g. `SwapResponse`, `TxHashPair`); SDK failures arrive via `mutation.error` exactly like any other thrown error. Call sites pick from three call shapes (above).
+
+The dual API means consumers never have to choose between React Query's error model and `Result<T>` ergonomics — both are exposed by the same hook.
+
+## queryKey / mutationKey conventions (mandatory)
+
+Every `queryKey` and `mutationKey` follows the same structural rule. Enforced by `_mutationContract.test.ts` for mutation keys; reviewer-enforced for query keys.
+
+**Rule 1 — first segment is the feature directory name.** No exceptions.
+
+| Hook directory | First segment |
+|---|---|
+| `backend/` | `'backend'` |
+| `bitcoin/` | `'bitcoin'` |
+| `bridge/` | `'bridge'` |
+| `dex/` | `'dex'` |
+| `mm/` | `'mm'` |
+| `partner/` | `'partner'` |
+| `recovery/` | `'recovery'` |
+| `shared/` | `'shared'` |
+| `staking/` | `'staking'` |
+| `swap/` | `'swap'` |
+| `migrate/` | `'migrate'` |
+
+**Rule 2 — camelCase for all segments.** No kebab-case (`'btc-balance'`), no ad-hoc casing. Identifiers are camelCase string literals (`'tradingWalletBalance'`, `'submitSwapTx'`).
+
+**Rule 3 — shape is `[feature, action, ...identifiers]`** in stable order: chain → token/asset → user → amount. Example: `['mm', 'allowance', srcChainKey, token, action]`.
+
+**Rule 4 — bigints stringify** via `.toString()` before going into a key (React Query's hash uses `JSON.stringify`, which throws on raw bigints).
+
+**Rule 5 — invalidate the narrowest key that could change.** If the mutation knows the affected `tokenId` / user / chain, scope the invalidation to it.
+
+Worked examples:
+
+```ts
+// @ai-snippets-skip
+queryKey: ['mm', 'userReservesData', spokeChainKey, userAddress]
+queryKey: ['mm', 'allowance', srcChainKey, token, action]
+queryKey: ['shared', 'xBalances', xChainId, tokens, address]
+mutationKey: ['mm', 'supply']
+queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo', tokenId, poolKey] });
+```
+
+## Hook organization
+
+Hooks organized by feature domain in `src/hooks/`:
+
+```
+hooks/
+├── shared/     # useSodaxContext, useSafeMutation, unwrapResult, useEstimateGas,
+│               # useDeriveUserWalletAddress, useGetUserHubWalletAddress, useXBalances,
+│               # useStellarTrustlineCheck, useRequestTrustline
+├── provider/   # useHubProvider
+├── swap/       # useQuote, useSwap, useStatus, useSwapAllowance, useSwapApprove,
+│               # useCancelSwap, useCreateLimitOrder, useCancelLimitOrder
+├── mm/         # useSupply, useWithdraw, useBorrow, useRepay, useMMAllowance, useMMApprove,
+│               # reserves data hooks
+├── bridge/     # useBridge, useBridgeAllowance, useBridgeApprove, bridgeable amounts/tokens
+├── staking/    # useStake, useUnstake, useInstantUnstake, useClaim, staking info hooks
+├── dex/        # usePools, useDexDeposit, useDexWithdraw, liquidity hooks
+├── bitcoin/    # useRadfiSession, fund/withdraw, UTXO management
+├── backend/    # Intent tracking, swap submission, orderbook, money market position queries
+├── partner/    # Partner fee claim, auto-swap preferences, token approval
+├── recovery/   # useHubAssetBalances, useWithdrawHubAsset
+└── migrate/    # useMigrateIcxToSoda, useRevertMigrateSodaToIcx, useMigratebnUSD,
+                # useMigrateBaln, useMigrationApprove, useMigrationAllowance
+```
+
+Every mutation hook returns `SafeUseMutationResult` and is registered in `_mutationContract.test.ts`'s manifest. Adding a non-conformant hook is a CI failure.
+
+## Cross-references
+
+- [`recipes/setup.md`](recipes/setup.md) — install + wire providers (worked example).
+- [`recipes/wallet-connectivity.md`](recipes/wallet-connectivity.md) — `useWalletProvider`, balances.
+- [`recipes/mutation-error-handling.md`](recipes/mutation-error-handling.md) — picking call shapes (worked examples).
+- [`recipes/observability.md`](recipes/observability.md) — `createSodaxQueryClient` deep-dive.
+- [`recipes/invalidations.md`](recipes/invalidations.md) — composing your own `onSuccess`.
+- [`reference/querykey-conventions.md`](reference/querykey-conventions.md) — full key tables.
+- [`features/`](features/) — per-feature reference (hook tables, types, gotchas).
+- [`@sodax/sdk`: `integration/architecture.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/integration/architecture.md) — the underlying SDK architecture (`Result<T>`, `SodaxError<C>`, `WalletProviderSlot<K, Raw>`).