@sodax/dapp-kit 2.0.0-rc.2 → 2.0.0-rc.4

package/README.md

@@ -117,7 +117,7 @@ function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
 
 ## Requirements
 
-- Node.js >= 18.0.0
+- Node.js >= 20.12.0
 - React >= 18
 - TypeScript
 
@@ -286,75 +286,21 @@ pnpm lint        # Lint code
 
 ## AI agent docs
 
-`@sodax/dapp-kit` ships an AI-ready documentation tree at `node_modules/@sodax/dapp-kit/ai-exported/`. It's tool-neutral: any agent that can read files (Claude Code, Cursor, Aider, Copilot Chat, ChatGPT with file context, etc.) can use it without further setup.
+AI-readable docs for `@sodax/dapp-kit` (and the other `@sodax/*` packages) are shipped via [`@sodax/skills`](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills) — a separate npm package bundling Claude-Code SKILL.md files and a long-form knowledge tree.
 
-### Get started
+**Recommended: [`skills` CLI](https://github.com/vercel-labs/skills)** — from your project root:
 
-Point your agent at `node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md` — it routes to the rest. Three sample prompts covering the typical entry points:
-
-```
-> Read node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md and integrate
-> SODAX cross-chain swaps into my React app.
-
-> Read node_modules/@sodax/dapp-kit/ai-exported/AGENTS.md. My app uses
-> v1 dapp-kit (useSpokeProvider, custom approve return shapes) — port to v2.
-
-> Look up the canonical mutation hook shape in
-> node_modules/@sodax/dapp-kit/ai-exported/integration/architecture.md.
+```bash
+npx skills@latest add icon-project/sodax-sdks/packages/skills
 ```
 
-### What's inside
+**npm + `AGENTS.md` pointer** (fallback for web chats, or when you prefer a devDependency over the CLI):
 
+```bash
+pnpm add -D @sodax/skills
 ```
-ai-exported/
-├── AGENTS.md                          # Tool-neutral entry point — start here
-├── integration/                       # Building NEW v2 dapp-kit code
-│   ├── README.md, ai-rules.md         # Index + DO / DO NOT / workflow for agents
-│   ├── quickstart.md                  # Install + wire providers + first feature
-│   ├── architecture.md                # Hook shapes, queryKey conventions, useSafeMutation, mutateAsyncSafe
-│   ├── features/                      # 8 feature pages: swap, money-market, staking, bridge,
-│   │                                  #   dex, migration, bitcoin (Radfi), auxiliary-services
-│   ├── recipes/                       # 13 patterns: setup, wallet-connectivity, per-feature flows,
-│   │                                  #   mutation error handling, observability, invalidations
-│   └── reference/                     # 4 lookup tables: full hook index, queryKey conventions,
-│                                      #   public API surface, glossary
-└── migration/                         # Porting EXISTING v1 dapp-kit code to v2
-    ├── README.md, ai-rules.md         # Index + workflow for porting agents
-    ├── checklist.md                   # Top-down cross-cutting checklist
-    ├── breaking-changes/              # 4 cross-cutting changes: hook-signatures, result-handling,
-    │                                  #   querykey-conventions, sdk-leakage
-    ├── features/                      # 8 per-feature porting playbooks
-    ├── recipes.md                     # Codemods + adapters
-    └── reference/                     # 3 reference tables: deleted hooks, renamed hooks,
-                                       #   error-shape crosswalk
-```
-
-### Scope
-
-This tree documents `@sodax/dapp-kit` (a React hooks library) only. It assumes:
-
-- **TypeScript + React** (>=18). Examples use TSX.
-- **Framework-agnostic**: works in any React app (Vite, Next.js client components, CRA, Remix, etc.). **No Next.js Server Components content** — dapp-kit is client-side React.
-- **Sibling packages used in examples**: `@sodax/sdk` (peer; types and config; re-exported transparently from dapp-kit), `@sodax/wallet-sdk-react` (sibling; `useWalletProvider` is in every signed-flow example), `@tanstack/react-query` (peer).
-- **`@sodax/types` is re-exported** through `@sodax/sdk` (which dapp-kit re-exports); consumers don't add it as a separate dependency.
-
-The underlying Core SDK has its own ai-exported tree at `node_modules/@sodax/sdk/ai-exported/` (resolves correctly in node_modules). The dapp-kit migration tree links to it for SDK-leakage topics (chain-key terminology, `Result<T>` semantics, `SodaxError<C>`).
-
-### Integrity guarantees
-
-Every release passes seven CI checks against `ai-exported/`:
-
-| Guard | What it catches |
-|---|---|
-| `check:ai-exported` | Each `useFoo` hook reference in markdown matches a real exported hook from `@sodax/dapp-kit` (or an upstream allowlist: React, React Query, wallet-sdk-react). |
-| `check:ai-scope` | No accidental imports from forbidden packages (e.g. `@sodax/wallet-sdk-core` for Node-only flows; `@sodax/types` directly). |
-| `check:ai-links` | Every relative link between markdown files resolves (including cross-package links into `../../../sdk/ai-exported/`). |
-| `check:ai-imports` | Every `import … from '@sodax/dapp-kit'` example in the docs typechecks against the package source. |
-| `check:ai-snippets` | Every fenced `​```ts`/`​```tsx` block is typechecked AS-IS against source (opt-out via `// @ai-snippets-skip` for genuinely illustrative blocks). Catches call-shape drift like wrong `useQuote({ params: <Request> })` vs canonical `useQuote({ params: { payload: <Request> } })`. |
-| `check:ai-keys` | Every `queryKey:` / `mutationKey:` literal in docs (both `kind: [...]` declarations and backticked-array table cells) matches a real source key prefix. Catches drift like `['staking', 'stakingInfo']` in docs when source uses `['staking', 'info']`. |
-| `check:ai-consistency` | Polling-interval claims in docs (e.g. "polls 3s", "auto-refresh every 2s") match the actual `refetchInterval` value in source. Catches drift like docs claiming 1s when source is 3000ms. |
 
-If you're contributing to this repo, run them with `pnpm -C packages/dapp-kit run check:ai-exported` (or `:scope`, `:links`, `:imports`, `:snippets`, `:keys`, `:consistency`).
+Then point your agent at `node_modules/@sodax/skills/AGENTS.md`. See [docs/ai-integration-guide.md](https://github.com/icon-project/sodax-sdks/blob/main/docs/ai-integration-guide.md) for all install modes and per-tool wiring.
 
 ## License
 

package/dist/index.d.ts

@@ -1478,13 +1478,20 @@ declare function useClaimRewards<K extends SpokeChainKey = SpokeChainKey>({ muta
 interface SodaxProviderProps {
     children: ReactNode;
     /**
-     * Sodax config (overrides defaults including rpcUrls). **Read-once at mount** —
-     * changes after first render are ignored to prevent re-instantiating the SDK
-     * from unstable parent references. To switch config (e.g. testnet ↔ mainnet),
-     * unmount/remount the provider.
+     * Sodax SDK config. Tracked by **reference** - a new identity re-instantiates the
+     * SDK. Hoist to a module constant or wrap in `useMemo`; include any value the SDK
+     * should react to (e.g. solver env) in the deps. Inline `{...}` re-creates the SDK
+     * every parent render and resets every `useSodaxContext` consumer.
+     *
+     * @example
+     * ```tsx
+     * const config = useMemo(() => ({ solver: solverMap[env] }), [env]);
+     * <SodaxProvider config={config}>...</SodaxProvider>
+     * ```
      */
     config?: DeepPartial<SodaxConfig>;
 }
+/** Root provider for `@sodax/dapp-kit`. Must be paired with `QueryClientProvider`. */
 declare const SodaxProvider: ({ children, config }: SodaxProviderProps) => ReactElement;
 
 type CreateSodaxQueryClientOptions = {

package/dist/index.mjs

@@ -2483,10 +2483,9 @@ function useClaimRewards({
   });
 }
 var SodaxProvider = ({ children, config }) => {
-  const configRef = useRef(config);
-  const frozen = configRef.current;
-  const sodax = useMemo(() => new Sodax(frozen), [frozen]);
-  return /* @__PURE__ */ jsx(SodaxContext.Provider, { value: { sodax }, children });
+  const sodax = useMemo(() => new Sodax(config), [config]);
+  const contextValue = useMemo(() => ({ sodax }), [sodax]);
+  return /* @__PURE__ */ jsx(SodaxContext.Provider, { value: contextValue, children });
 };
 var defaultOnMutationError = (error) => {
   console.error("[sodax] Mutation error:", error);
@@ -2515,5 +2514,3 @@ function createSodaxQueryClient({
 }
 
 export { SodaxProvider, clearRadfiSession, createDecreaseLiquidityParamsProps, createDepositParamsProps, createSodaxQueryClient, createSupplyLiquidityParamsProps, createWithdrawParamsProps, getXBalancesQueryOptions, loadRadfiSession, saveRadfiSession, toResult, unwrapResult, useAToken, useATokensBalances, useApproveToken, useBackendAllMoneyMarketAssets, useBackendAllMoneyMarketBorrowers, useBackendIntentByHash, useBackendIntentByTxHash, useBackendMoneyMarketAsset, useBackendMoneyMarketAssetBorrowers, useBackendMoneyMarketAssetSuppliers, useBackendMoneyMarketPosition, useBackendOrderbook, useBackendSubmitSwapTx, useBackendSubmitSwapTxStatus, useBackendUserIntents, useBitcoinBalance, useBorrow, useBridge, useBridgeAllowance, useBridgeApprove, useCancelLimitOrder, useCancelSwap, useCancelUnstake, useClaim, useClaimRewards, useConvertedAssets, useCreateDecreaseLiquidityParams, useCreateDepositParams, useCreateLimitOrder, useCreateSupplyLiquidityParams, useCreateWithdrawParams, useDecreaseLiquidity, useDeriveUserWalletAddress, useDexAllowance, useDexApprove, useDexDeposit, useDexWithdraw, useEstimateGas, useExpiredUtxos, useFeeClaimSwap, useFetchAssetsBalances, useFundTradingWallet, useGetAutoSwapPreferences, useGetBridgeableAmount, useGetBridgeableTokens, useGetUserHubWalletAddress, useHubAssetBalances, useHubProvider, useInstantUnstake, useInstantUnstakeAllowance, useInstantUnstakeApprove, useInstantUnstakeRatio, useIsTokenApproved, useLiquidityAmounts, useMMAllowance, useMMApprove, useMigrateBaln, useMigrateIcxToSoda, useMigratebnUSD, useMigrationAllowance, useMigrationApprove, usePoolBalances, usePoolData, usePools, usePositionInfo, useQuote, useRadfiAuth, useRadfiSession, useRadfiWithdraw, useRenewUtxos, useRepay, useRequestTrustline, useReservesData, useReservesHumanized, useReservesList, useReservesUsdFormat, useRevertMigrateSodaToIcx, useSafeMutation, useSetSwapPreference, useSodaxContext, useStake, useStakeAllowance, useStakeApprove, useStakeRatio, useStakingConfig, useStakingInfo, useStatus, useStellarTrustlineCheck, useSupply, useSupplyLiquidity, useSwap, useSwapAllowance, useSwapApprove, useTradingWallet, useTradingWalletBalance, useUnstake, useUnstakeAllowance, useUnstakeApprove, useUnstakingInfo, useUnstakingInfoWithPenalty, useUserFormattedSummary, useUserReservesData, useWithdraw, useWithdrawHubAsset, useXBalances };
-//# sourceMappingURL=index.mjs.map
-//# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,16 +1,32 @@
 {
   "name": "@sodax/dapp-kit",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT",
-  "version": "2.0.0-rc.2",
-  "description": "dapp-kit of New World",
+  "version": "2.0.0-rc.4",
+  "description": "React hooks for building dApps on the SODAX cross-chain DeFi platform",
+  "keywords": [
+    "sodax",
+    "dapp-kit",
+    "react",
+    "react-query",
+    "hooks",
+    "defi"
+  ],
+  "homepage": "https://github.com/icon-project/sodax-sdks/tree/main/packages/dapp-kit",
+  "bugs": {
+    "url": "https://github.com/icon-project/sodax-sdks/issues"
+  },
   "type": "module",
-  "main": "dist/index.cjs",
+  "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "module": "dist/index.mjs",
   "files": [
     "dist",
-    "src",
-    "ai-exported"
+    "!dist/**/*.map",
+    "src"
   ],
   "repository": {
     "type": "git",
@@ -18,29 +34,31 @@
   },
   "dependencies": {
     "viem": "2.29.2",
-    "@sodax/sdk": "2.0.0-rc.2"
+    "@sodax/sdk": "2.0.0-rc.4"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.17.4",
     "@tanstack/react-query": "5.87.4",
     "@types/react": "19.0.8",
     "knip": "5.30.5",
+    "tslib": "2.8.1",
     "tsup": "8.5.0",
     "typescript": "5.5.4",
-    "vitest": "2.1.9"
+    "vitest": "3.2.4"
   },
   "peerDependencies": {
     "@tanstack/react-query": "5.x",
     "react": ">=18"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.12.0"
   },
+  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.mjs"
     }
   },
   "scripts": {
@@ -50,14 +68,8 @@
     "clean": "rm -rf dist && rm -rf node_modules && rm -rf .turbo",
     "pretty": "biome format . --write",
     "checkTs": "tsc --noEmit",
-    "knip": "knip",
-    "lint": "biome lint . --write",
-    "check:ai-exported": "bash ./scripts/check-ai-exported.sh",
-    "check:ai-scope": "bash ./scripts/check-ai-scope.sh",
-    "check:ai-links": "bash ./scripts/check-ai-links.sh",
-    "check:ai-imports": "bash ./scripts/check-ai-imports.sh",
-    "check:ai-snippets": "bash ./scripts/check-ai-snippets.sh",
-    "check:ai-keys": "bash ./scripts/check-ai-keys.sh",
-    "check:ai-consistency": "bash ./scripts/check-ai-consistency.sh"
+    "check-exports": "attw --pack --profile esm-only",
+    "check:knip": "knip",
+    "lint": "biome lint . --write"
   }
 }

package/src/providers/SodaxProvider.tsx

@@ -1,4 +1,4 @@
-import { useMemo, useRef, type ReactNode, type ReactElement } from 'react';
+import { useMemo, type ReactNode, type ReactElement } from 'react';
 import { Sodax, type SodaxConfig } from '@sodax/sdk';
 import { SodaxContext } from '@/contexts/index.js';
 import type { DeepPartial } from '@sodax/sdk';
@@ -6,20 +6,24 @@ import type { DeepPartial } from '@sodax/sdk';
 interface SodaxProviderProps {
   children: ReactNode;
   /**
-   * Sodax config (overrides defaults including rpcUrls). **Read-once at mount** —
-   * changes after first render are ignored to prevent re-instantiating the SDK
-   * from unstable parent references. To switch config (e.g. testnet ↔ mainnet),
-   * unmount/remount the provider.
+   * Sodax SDK config. Tracked by **reference** - a new identity re-instantiates the
+   * SDK. Hoist to a module constant or wrap in `useMemo`; include any value the SDK
+   * should react to (e.g. solver env) in the deps. Inline `{...}` re-creates the SDK
+   * every parent render and resets every `useSodaxContext` consumer.
+   *
+   * @example
+   * ```tsx
+   * const config = useMemo(() => ({ solver: solverMap[env] }), [env]);
+   * <SodaxProvider config={config}>...</SodaxProvider>
+   * ```
    */
   config?: DeepPartial<SodaxConfig>;
 }
 
+/** Root provider for `@sodax/dapp-kit`. Must be paired with `QueryClientProvider`. */
 export const SodaxProvider = ({ children, config }: SodaxProviderProps): ReactElement => {
-  // Freeze config on first render so the SDK instance and consumers share one
-  // snapshot (matches SodaxWalletProvider semantic).
-  const configRef = useRef<DeepPartial<SodaxConfig> | undefined>(config);
-  const frozen = configRef.current;
-  const sodax = useMemo(() => new Sodax(frozen), [frozen]);
+  const sodax = useMemo(() => new Sodax(config), [config]);
+  const contextValue = useMemo(() => ({ sodax }), [sodax]);
 
-  return <SodaxContext.Provider value={{ sodax }}>{children}</SodaxContext.Provider>;
+  return <SodaxContext.Provider value={contextValue}>{children}</SodaxContext.Provider>;
 };

package/ai-exported/AGENTS.md

@@ -1,134 +0,0 @@
-# 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 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

@@ -1,49 +0,0 @@
-# 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

@@ -1,79 +0,0 @@
-# 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.