@sodax/dapp-kit 1.5.6-beta → 2.0.0-rc.1

package/ai-exported/AGENTS.md

@@ -0,0 +1,134 @@
+# AGENTS.md — `@sodax/dapp-kit` v2
+
+> Tool-neutral entry point for any AI coding agent assisting a consumer of `@sodax/dapp-kit`. If you're at `node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md`, you are in the right place — everything you need is reachable from here without leaving the npm tarball.
+
+## Project
+
+`@sodax/dapp-kit` is a React hooks library that wraps `@sodax/sdk` with React Query. It provides ~95 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 entire 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.
+
+## When to read what
+
+```
+Are you writing NEW code with v2 dapp-kit?     → integration/ai-rules.md, then integration/
+Are you porting EXISTING v1 code to v2?        → migration/ai-rules.md, then migration/
+Just need a hook table or a queryKey rule?     → integration/reference/
+Need to install + wire providers?              → integration/recipes/setup.md
+Hit a feature you don't know how to scaffold?  → integration/recipes/<feature>.md
+```
+
+If a consumer's repo has both v1 call sites and a request to extend with new code, do migration first. Stale v1 patterns leak into new code if you skip it.
+
+**Always start with `ai-rules.md` for the tree you're working in** — it's the consolidated DO / DO NOT / workflow / stop-conditions guide that prevents the most common v2 traps. Read it once, then dive into the per-feature docs or recipes.
+
+## Top-level layout
+
+```
+ai-exported/
+├── AGENTS.md                       # You are here
+├── integration/                    # How to use v2 dapp-kit (new consumers)
+│   ├── README.md                   # Index for this tree
+│   ├── ai-rules.md                 # DO / DO NOT / workflow — read before per-feature docs
+│   ├── quickstart.md               # Install + wire providers + first feature
+│   ├── architecture.md             # Hook shapes, queryKey conventions, useSafeMutation, unwrapResult, Result<T>
+│   ├── features/                   # Per-feature reference docs (one file per major feature group)
+│   │   ├── README.md
+│   │   ├── swap.md, money-market.md, staking.md, bridge.md, dex.md
+│   │   ├── migration.md            # ICX/bnUSD/BALN migration hooks
+│   │   ├── bitcoin.md              # Radfi (dapp-kit-unique)
+│   │   └── auxiliary-services.md   # partner + recovery + backend queries + shared
+│   ├── recipes/                    # Copy-paste patterns
+│   │   ├── README.md
+│   │   ├── setup.md, wallet-connectivity.md
+│   │   ├── swap.md, money-market.md, staking.md, bridge.md, dex.md
+│   │   ├── migration.md, bitcoin.md, backend-queries.md
+│   │   ├── mutation-error-handling.md     # mutate / mutateAsync / mutateAsyncSafe
+│   │   ├── observability.md               # createSodaxQueryClient, meta.silent
+│   │   └── invalidations.md               # hook-owned vs consumer
+│   └── reference/                  # Lookup tables
+│       ├── README.md
+│       ├── hooks-index.md          # Comprehensive hook table
+│       ├── querykey-conventions.md # camelCase, feature-prefix, default mutationKey
+│       ├── public-api.md           # What @sodax/dapp-kit exports + import rules
+│       └── glossary.md             # ReadHookParams, MutationHookParams, SafeUseMutationResult, etc.
+└── migration/                      # How to port v1 → v2 dapp-kit
+    ├── README.md                   # Overview + reading order + glossary
+    ├── ai-rules.md                 # DO / DO NOT / workflow for porting agents
+    ├── checklist.md                # Top-down cross-cutting steps
+    ├── breaking-changes/
+    │   ├── hook-signatures.md      # Single-arg policy + ReadHookParams/MutationHookParams
+    │   ├── result-handling.md      # Result<T> success-path → throws; mutateAsyncSafe
+    │   ├── querykey-conventions.md # camelCase + default mutationKey
+    │   └── sdk-leakage.md          # Cross-links to SDK ai-exported migration tree
+    ├── features/                   # Per-feature porting playbooks (mirror integration/features/)
+    │   ├── README.md
+    │   ├── swap.md, money-market.md, staking.md, bridge.md, dex.md
+    │   ├── migration.md, bitcoin.md, auxiliary-services.md
+    ├── recipes.md                  # Codemods + adapters for incremental migration
+    └── reference/
+        ├── README.md
+        ├── deleted-hooks.md        # useSpokeProvider, invalidateMmQueries, legacy useMigrate
+        ├── renamed-hooks.md
+        └── error-shape-crosswalk.md
+```
+
+## 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). Use `mutateAsyncSafe` for sequenced flows; `mutateAsync` for try/catch flows; `mutate` for fire-and-forget render-driven flows.
+3. **`mutationFn` throws on SDK `!ok`.** dapp-kit calls `unwrapResult` on the SDK's `Result<T>`, throwing on failure. This makes React Query's native error model engage (`isError`, `error`, `onError`, `retry`, devtools). `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`, derived from `vars`. Consumer-provided `onSuccess` runs after. v1's manual `invalidateMmQueries` utilities are gone.
+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. Mechanically enforced by `_mutationContract.test.ts`.
+
+## Top 5 v1 → v2 traps
+
+1. **Reaching for `useSpokeProvider`.** It's deleted. Pass `walletProvider` from `useWalletProvider({ xChainId: chainKey })` (`@sodax/wallet-sdk-react`) directly into `mutate(vars)`. The chain key on the action params is what routes — there is no provider class to derive.
+2. **Treating mutation `data` as `Result<T>`.** v2's `mutationFn` unwraps before resolving — `data` is the unwrapped success value (e.g. `SwapResponse`, `TxHashPair`). For SDK failures, look at `mutation.error` or use `mutateAsyncSafe` for the `Result<T>` shape.
+3. **Forgetting `try/catch` on `mutateAsync`.** v2's `mutateAsync` rejects on SDK `!ok`. If you don't `try/catch`, you'll leak unhandled rejections on user-rejects. 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 — these were renamed: `XToken.chainKey`, `ChainKeys.X_MAINNET`. The legacy `*_MAINNET_CHAIN_ID` constants are gone. See [`migration/breaking-changes/sdk-leakage.md`](migration/breaking-changes/sdk-leakage.md).
+
+See `migration/README.md` for the complete trap list and `migration/breaking-changes/` for full v1↔v2 detail.
+
+## Public API contract
+
+- Import only from the package root: `import { useSwap, SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit'`.
+- The package re-exports `@sodax/sdk`'s public surface — `ChainKeys`, `SodaxConfig`, types like `CreateIntentParams`, etc., are available from `@sodax/dapp-kit` directly. You may also import them from `@sodax/sdk`.
+- Do **not** add `@sodax/types` to your dependencies — it's re-exported via `@sodax/sdk`.
+- Do **not** deep-import from `dist/...`. Internal paths are not stable across releases.
+- The published tarball ships `dist/` and `ai-exported/`. Do not rely on any other path being present.
+
+## Conventions agents must follow
+
+- **Use `useSafeMutation`-built hooks** (i.e. dapp-kit's exported hooks). Never call React Query's `useMutation` directly inside a wrapper around a dapp-kit hook — consumers depend on `mutateAsyncSafe`.
+- **Branch on `mutateAsyncSafe`'s `Result.ok`** for sequenced flows. The user-reject case is modal, not exceptional.
+- **Use `ChainKeys.*` over hard-coded chain strings.** The set evolves per release.
+- **Drop `spokeProvider`** anywhere it appears. It's not a v2 concept. `walletProvider` flows through `mutate(vars)` for signed flows; queries take it directly when needed (e.g. allowance reads).
+- **Don't recreate hook-owned invalidations** at the call site. Each mutation hook already invalidates the relevant keys; consumer `onSuccess` runs after for any extra logic.
+- **Conventional commits if generating commits** (`feat:`, `fix:`, `chore:`).
+
+## Enforcement — what CI catches (and what it doesn't)
+
+Seven CI guards run on every PR. They catch syntactic + structural drift but NOT prose-level accuracy:
+
+| Guard | What it enforces |
+|---|---|
+| `check:ai-exported` | Every `useFoo` reference resolves to a real export. |
+| `check:ai-scope` | No imports from forbidden packages (`@sodax/wallet-sdk-core`, `@sodax/types` directly). |
+| `check:ai-links` | Every relative link between markdown files resolves. |
+| `check:ai-imports` | Every `import … from '@sodax/dapp-kit'` example typechecks. |
+| `check:ai-snippets` | **Opt-out by default** — every ts/tsx code block is typechecked unless marked `// @ai-snippets-skip`. Catches call-shape drift. |
+| `check:ai-keys` | Every `queryKey: [...]` / `mutationKey: [...]` literal (declarations + backticked-array table cells) matches source. Catches `'stakingInfo'` vs `'info'`-style drift. Opt-out via `<!-- ai-keys-allow -->` or `// ai-keys-allow`. |
+| `check:ai-consistency` | Polling-interval claims (`"polls 3s"`, table cells like `useQuote \| 3s`) match the actual `refetchInterval` in source. Opt-out via `<!-- ai-consistency-allow -->`. |
+
+If you're authoring a new doc page, write code samples that include explicit imports (so `check:ai-snippets` validates them) and source-derived queryKeys (so `check:ai-keys` accepts them). When showing v1 anti-patterns or pseudocode, use the appropriate `*-allow` / `*-skip` marker — these are first-class affordances, not workarounds.
+
+## Pointers
+
+- [`integration/README.md`](integration/README.md) — start here for any new v2 dapp-kit work.
+- [`migration/README.md`](migration/README.md) — start here for any v1 → v2 dapp-kit port.
+- [`integration/recipes/setup.md`](integration/recipes/setup.md) — install + wire providers.
+- [`integration/recipes/mutation-error-handling.md`](integration/recipes/mutation-error-handling.md) — picking call shapes (`mutate` / `mutateAsync` / `mutateAsyncSafe`).
+- [`integration/architecture.md`](integration/architecture.md) — full design rationale + canonical hook shapes.
+- [`../../sdk/ai-exported/AGENTS.md`](../../sdk/ai-exported/AGENTS.md) — the underlying Core SDK's tree (resolves correctly in `node_modules/@sodax/`-layout). Useful for SDK-leakage migration topics.

package/ai-exported/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 ai-exported tree at [`../../../sdk/ai-exported/`](../../../sdk/ai-exported/) (resolves correctly in `node_modules/@sodax/`-layout). 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/ai-exported/integration/ai-rules.md

@@ -0,0 +1,79 @@
+# 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`.
+
+## 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 `@sodax/sdk`'s ai-exported tree 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/ai-exported/integration/architecture.md

@@ -0,0 +1,274 @@
+# 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.
+
+### `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
+
+~95 hooks (41 mutations + ~50 queries + utilities) 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 (13 hooks total)
+├── bridge/     # useBridge, useBridgeAllowance, useBridgeApprove, bridgeable amounts/tokens
+├── staking/    # useStake, useUnstake, useInstantUnstake, useClaim, staking info hooks (~18)
+├── dex/        # usePools, useDexDeposit, useDexWithdraw, liquidity hooks (~13)
+├── bitcoin/    # useRadfiSession, fund/withdraw, UTXO management (~8)
+├── backend/    # Intent tracking, swap submission, orderbook, money market position queries (~13)
+├── partner/    # Partner fee claim, auto-swap preferences, token approval (6)
+├── 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).
+- [`../../../sdk/ai-exported/integration/architecture.md`](../../../sdk/ai-exported/integration/architecture.md) — the underlying SDK architecture (`Result<T>`, `SodaxError<C>`, `WalletProviderSlot<K, Raw>`).

package/ai-exported/integration/features/README.md

@@ -0,0 +1,29 @@
+# Features — `@sodax/dapp-kit` v2
+
+Per-feature reference docs. Each file documents the hooks, params types, return types, and feature-specific gotchas — but doesn't include extended worked examples (those live in [`../recipes/`](../recipes/)).
+
+| File | Hook count | What's covered |
+|---|---|---|
+| [`swap.md`](swap.md) | 8 | Cross-chain swaps via the intent solver: `useQuote`, `useSwap`, allowance/approve, status polling, limit orders. |
+| [`money-market.md`](money-market.md) | 13 | Lending/borrowing on the cross-chain MM: `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, allowance/approve, reserves data hooks. |
+| [`staking.md`](staking.md) | ~18 | SODA → xSODA staking: `useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`, allowance/approve, info/ratio reads. |
+| [`bridge.md`](bridge.md) | 5 | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
+| [`dex.md`](dex.md) | ~13 | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
+| [`migration.md`](migration.md) | 6 | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
+| [`bitcoin.md`](bitcoin.md) | ~8 | Radfi (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`auxiliary-services.md`](auxiliary-services.md) | ~30 | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
+
+## Reference vs recipes
+
+- **Files in this directory (`features/`)** are reference: hook tables, type signatures, return shapes, feature-specific gotchas. Read when you need to know "what's this hook's exact shape" or "what does this method return."
+- **Files in [`../recipes/`](../recipes/)** are how-to: complete worked examples, end-to-end flows, opinionated patterns. Read when you want to copy-paste working code.
+
+## Pair-completeness
+
+Every file in this directory has a sibling in [`../../migration/features/`](../../migration/features/) with the same filename — the v1→v2 porting playbook for that feature. When you're deep in one, the other is one path-swap away.
+
+## Cross-references
+
+- [`../architecture.md`](../architecture.md) — design concepts that span every feature (hook shapes, queryKey conventions, `useSafeMutation`, `mutateAsyncSafe`, `unwrapResult`).
+- [`../recipes/`](../recipes/) — copy-paste flows.
+- [`../reference/hooks-index.md`](../reference/hooks-index.md) — full hook table at one glance.