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

package/ai-exported/integration/reference/glossary.md

@@ -0,0 +1,188 @@
+# Glossary — `@sodax/dapp-kit` v2
+
+Type aliases, conventions, and domain terms specific to dapp-kit. SDK-side terms (Hub, Spoke, Intent, ChainKey, SodaxError, etc.) are documented in [`../../../../sdk/ai-exported/integration/reference/glossary.md`](../../../../sdk/ai-exported/integration/reference/glossary.md).
+
+## Hook shape types
+
+### `ReadHookParams<TData, TParams = void>`
+
+Canonical shape for query hook arguments. Single object with `params` and `queryOptions` keys.
+
+```ts
+// @ai-snippets-skip
+type ReadHookParams<TData, TParams = void> = TParams extends void
+  ? { queryOptions?: ReadQueryOptions<TData> }
+  : { params?: TParams; queryOptions?: ReadQueryOptions<TData> };
+```
+
+If a hook has no domain inputs (e.g. `useStakingConfig`), it uses `ReadHookParams<TData>` (no `TParams`) and accepts `({} = {})` for ergonomic no-arg calls.
+
+### `ReadQueryOptions<TData>`
+
+The options slot for query hooks, omitting hook-owned fields.
+
+```ts
+// @ai-snippets-skip
+type ReadQueryOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn' | 'enabled'>;
+```
+
+Hook owns `queryKey`, `queryFn`, and `enabled` — never consumer-overridable. `enabled` is derived from required-input presence.
+
+### `MutationHookParams<TData, TVars>`
+
+Canonical shape for mutation hook arguments. Single object with one key: `mutationOptions`.
+
+```ts
+// @ai-snippets-skip
+type MutationHookParams<TData, TVars> = {
+  mutationOptions?: MutationHookOptions<TData, TVars>;
+};
+```
+
+Domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)` via `TVars`.
+
+### `MutationHookOptions<TData, TVars>`
+
+The options slot for mutation hooks, omitting hook-owned fields.
+
+```ts
+// @ai-snippets-skip
+type MutationHookOptions<TData, TVars> = Omit<UseMutationOptions<TData, Error, TVars>, 'mutationFn'>;
+```
+
+Hook owns `mutationFn`. Consumer can override `mutationKey`, `onSuccess`, `onError`, `retry`, `meta`, etc.
+
+### `SafeUseMutationResult<TData, TError, TVars>`
+
+The return type of every dapp-kit mutation hook. Extends React Query's `UseMutationResult` with `mutateAsyncSafe`.
+
+```ts
+// @ai-snippets-skip
+type SafeUseMutationResult<TData, TError, TVars> = UseMutationResult<TData, TError, TVars> & {
+  mutateAsyncSafe: (vars: TVars) => Promise<Result<TData>>;
+};
+```
+
+`mutateAsyncSafe` never rejects — it packs the rejection into `Result<T>`. Use it for sequenced flows.
+
+### `Result<T>`
+
+```ts
+type Result<T> = { ok: true; value: T } | { ok: false; error: Error | unknown };
+```
+
+Re-exported from `@sodax/sdk`. Used as:
+- The SDK service method return type (which `unwrapResult` translates to throws).
+- The return type of `mutateAsyncSafe`.
+- The `data` of some query hooks (when the underlying SDK method returns Result and we choose to surface it directly to the consumer rather than unwrapping in the hook).
+
+### `TxHashPair`
+
+```ts
+type TxHashPair = {
+  srcChainTxHash: string;
+  dstChainTxHash: string;
+};
+```
+
+Re-exported from `@sodax/sdk`. Universal cross-chain mutation return: spoke chain tx + relayed hub tx. Returned by `useBridge`, all four MM mutations, all five staking mutations, `useDexDeposit`/`useDexWithdraw`, all four migration mutations.
+
+**Always destructure as `{ srcChainTxHash, dstChainTxHash }`, never as `[a, b]`.**
+
+## Hook lifecycle terms
+
+### `mutationFn`
+
+The function React Query invokes for a mutation. In dapp-kit, every `mutationFn` calls `unwrapResult(await sodax.<feature>.<method>(vars))`. Throws on SDK `!ok`. Hook-owned, never consumer-overridable.
+
+### `unwrapResult`
+
+```ts
+// @ai-snippets-skip
+function unwrapResult<T>(result: Result<T>): T;
+```
+
+`{ ok: true; value }` → `value`. `{ ok: false; error }` → throws `error`. The bridge from SDK Result contract to React Query throw contract.
+
+### `toResult`
+
+```ts
+// @ai-snippets-skip
+function toResult<T>(promise: Promise<T>): Promise<Result<T>>;
+```
+
+Inverse of `unwrapResult` for the rejection direction. Used internally by `useSafeMutation` to build `mutateAsyncSafe`.
+
+### `useSafeMutation`
+
+Drop-in for React Query's `useMutation`. Returns `SafeUseMutationResult` (extends `UseMutationResult` with `mutateAsyncSafe`). Every dapp-kit mutation hook calls this — never call React Query's `useMutation` directly.
+
+### `mutateAsyncSafe`
+
+The third call shape on every mutation hook. Returns `Promise<Result<TData>>`. Never rejects. Recommended for imperative sequenced flows.
+
+## Provider terms
+
+### `SodaxProvider`
+
+App-level React component. Provides:
+- A `Sodax` SDK instance (via `useSodaxContext()`)
+- RPC config for all chains
+- Hub provider access (via `useHubProvider()`)
+
+Optional config: `<SodaxProvider config={DeepPartial<SodaxConfig>}>`. Without config, SDK uses packaged defaults.
+
+### `createSodaxQueryClient`
+
+Factory for a `QueryClient` with `MutationCache.onError` pre-wired for global mutation observability. Optional — if you construct your own `QueryClient`, dapp-kit hooks still work; you just don't get the global observability seam.
+
+### `useSodaxContext`
+
+The escape hatch into the SDK from any component under `SodaxProvider`. Returns `{ sodax: Sodax }`. Most hooks use this internally; consumers rarely need it directly.
+
+## Convention terms
+
+### "Single-object params"
+
+Every hook accepts exactly one object argument. No positional args. For mutations: `{ mutationOptions }`. For queries: `{ params, queryOptions }`. Mechanically enforced.
+
+### "Zero-domain-param policy"
+
+The mutation-hook rule that no domain inputs (`params`, `walletProvider`, etc.) live at the hook-init level — they all flow through `mutate(vars)` via `TVars`. This lets a single hook serve many call shapes without remounting.
+
+### "Hook-owned invalidations"
+
+Mutation hooks invalidate the relevant query keys in their own `onSuccess`. Consumer-provided `onSuccess` runs after. Replaces v1's manual `invalidateMmQueries` utilities.
+
+### "Composed `onSuccess`"
+
+The pattern by which a hook's internal `onSuccess` calls invalidations first, then `await mutationOptions?.onSuccess?.(...)` so the consumer's callback still fires.
+
+### "queryKey rule"
+
+Every queryKey/mutationKey starts with the feature directory name (`'swap'`, `'mm'`, `'bridge'`, `'staking'`, `'dex'`, `'bitcoin'`, `'partner'`, `'recovery'`, `'backend'`, `'shared'`, `'migrate'`). camelCase segments. Bigints stringified. See [`querykey-conventions.md`](querykey-conventions.md).
+
+### "Default `mutationKey` before the spread"
+
+<!-- ai-keys-allow -->
+The order inside `useSafeMutation` calls: default `mutationKey: ['feature', 'action']` BEFORE `...mutationOptions`, then `mutationFn` AFTER. This way the consumer can override the default key via `mutationOptions.mutationKey`, but `mutationFn` (hook-owned) always wins.
+
+## v1 → v2 remapping
+
+When porting v1 code, these shifts are pervasive:
+
+| v1 | v2 |
+|---|---|
+| Positional hook args | Single-object params |
+| Hook-level `spokeProvider` | `walletProvider` flows through `mutate(vars)` |
+| `Result<T>` returned via React Query success | Throws in `mutationFn`; use `mutateAsyncSafe` for `Result<T>` flow |
+| Approve hook returns `{ approve, isLoading, error }` | Returns `SafeUseMutationResult` with `mutateAsync` / `isPending` |
+| Consumer-managed invalidations (`invalidateMmQueries`) | Hook-owned in composed `onSuccess` |
+| Ad-hoc queryKey shapes | Feature-prefixed, camelCase, stringified bigints |
+
+## Cross-references
+
+- [`../architecture.md`](../architecture.md) — full design rationale for these types and conventions.
+- [`querykey-conventions.md`](querykey-conventions.md) — queryKey/mutationKey rules.
+- [`public-api.md`](public-api.md) — what's exported.
+- [`../../../../sdk/ai-exported/integration/reference/glossary.md`](../../../../sdk/ai-exported/integration/reference/glossary.md) — SDK-side terms (Hub, Spoke, Intent, ChainKey, SodaxError).

package/ai-exported/integration/reference/hooks-index.md

@@ -0,0 +1,194 @@
+# Hooks index — `@sodax/dapp-kit` v2
+
+Comprehensive hook table. ~95 hooks across 11 feature domains. Use this when you know the feature you're building but don't remember the exact hook name.
+
+## Provider + context
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `SodaxProvider` | Component | Wraps app; provides `Sodax` instance + RPC config |
+| `createSodaxQueryClient` | Factory | Returns `QueryClient` with global mutation observability |
+| `useSodaxContext` | Utility | Access the `Sodax` SDK instance |
+| `useHubProvider` | Utility | Hub chain (Sonic) provider |
+
+## Swap (8)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useQuote` | Query | Real-time swap quote (auto-refreshes 3s) |
+| `useSwap` | Mutation | Execute a complete cross-chain swap |
+| `useSwapAllowance` | Query | Check token approval status |
+| `useSwapApprove` | Mutation | Approve tokens for the swap contract |
+| `useStatus` | Query | Track intent execution status (polls 3s once `intentTxHash` supplied; Result-wrapped data) |
+| `useCancelSwap` | Mutation | Cancel an active swap intent |
+| `useCreateLimitOrder` | Mutation | Create a limit order (no deadline) |
+| `useCancelLimitOrder` | Mutation | Cancel a limit order |
+
+## Money market (13)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useSupply` | Mutation | Supply tokens as collateral |
+| `useWithdraw` | Mutation | Withdraw supplied tokens |
+| `useBorrow` | Mutation | Borrow against collateral |
+| `useRepay` | Mutation | Repay borrowed tokens |
+| `useMMAllowance` | Query | Approval check (`enabled: false` for borrow/withdraw — `data` stays `undefined`) |
+| `useMMApprove` | Mutation | Approve tokens |
+| `useReservesData` | Query | All reserve data (raw) |
+| `useReservesHumanized` | Query | Reserves in decimal-normalized form |
+| `useReservesList` | Query | List of reserve asset addresses |
+| `useReservesUsdFormat` | Query | Reserves with USD overlays |
+| `useUserFormattedSummary` | Query | Health factor, collateral, debt summary |
+| `useUserReservesData` | Query | Per-reserve user position |
+| `useAToken` | Query | aToken metadata |
+| `useATokensBalances` | Query | aToken balances |
+
+## Bridge (5)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useBridge` | Mutation | Execute a cross-chain bridge transfer |
+| `useBridgeAllowance` | Query | Approval check |
+| `useBridgeApprove` | Mutation | Approve tokens for bridge |
+| `useGetBridgeableAmount` | Query | Max bridgeable amount between two `XToken`s |
+| `useGetBridgeableTokens` | Query | Tokens bridgeable to a destination chain |
+
+## Staking (~18)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useStake` | Mutation | Stake SODA, receive xSODA |
+| `useUnstake` | Mutation | Request unstake (waiting period) |
+| `useInstantUnstake` | Mutation | Instant unstake (with slippage) |
+| `useClaim` | Mutation | Claim SODA after waiting period |
+| `useCancelUnstake` | Mutation | Cancel pending unstake |
+| `useStakeApprove` | Mutation | Approve SODA for staking |
+| `useUnstakeApprove` | Mutation | Approve xSODA for unstaking |
+| `useInstantUnstakeApprove` | Mutation | Approve xSODA for instant unstaking |
+| `useStakeAllowance` | Query | Check SODA approval |
+| `useUnstakeAllowance` | Query | Check xSODA approval (unstaking) |
+| `useInstantUnstakeAllowance` | Query | Check xSODA approval (instant) |
+| `useStakingInfo` | Query | User position |
+| `useUnstakingInfo` | Query | Pending unstake requests |
+| `useUnstakingInfoWithPenalty` | Query | Pending requests + penalty calcs |
+| `useStakingConfig` | Query | Unstaking period, max penalty |
+| `useStakeRatio` | Query | SODA-to-xSODA exchange rate (returns tuple) |
+| `useInstantUnstakeRatio` | Query | Instant unstake rate |
+| `useConvertedAssets` | Query | xSODA → SODA conversion |
+
+## DEX (~13)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `usePools` | Query | List available pools (synchronous; no auto-refresh) |
+| `usePoolData` | Query | Pool details (price, tick, liquidity) |
+| `usePoolBalances` | Query | User's pool token balances |
+| `usePositionInfo` | Query | Position details by tokenId |
+| `useLiquidityAmounts` | Query | Token amounts for a tick range |
+| `useDexDeposit` | Mutation | Deposit assets into pool tokens |
+| `useDexWithdraw` | Mutation | Withdraw assets from pool tokens |
+| `useDexAllowance` | Query | Approval check |
+| `useDexApprove` | Mutation | Approve tokens |
+| `useSupplyLiquidity` | Mutation | Supply liquidity (mint or increase) |
+| `useDecreaseLiquidity` | Mutation | Remove liquidity |
+| `useClaimRewards` | Mutation | Claim trading fees |
+| `useCreateDepositParams` | Param builder | Build deposit params with ERC-4626 conversion |
+| `useCreateWithdrawParams` | Param builder | Build withdraw params |
+| `useCreateSupplyLiquidityParams` | Param builder | Build tick-range + liquidity params |
+| `useCreateDecreaseLiquidityParams` | Param builder | Build decrease params from position state |
+
+## Migration (6)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useMigrateIcxToSoda` | Mutation | ICX/wICX (ICON) → SODA (Sonic) |
+| `useRevertMigrateSodaToIcx` | Mutation | SODA (Sonic) → wICX (ICON) |
+| `useMigratebnUSD` | Mutation | Legacy bnUSD ↔ new bnUSD (bidirectional) |
+| `useMigrateBaln` | Mutation | BALN (ICON) → SODA with optional lock period |
+| `useMigrationApprove` | Mutation | Approve before migration (action-discriminated) |
+| `useMigrationAllowance` | Query | Approval check (action-discriminated) |
+
+## Bitcoin / Radfi (~8)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useRadfiAuth` | Mutation | Authenticate via BIP322 signing |
+| `useRadfiSession` | Utility | Manage full session lifecycle |
+| `useTradingWallet` | Utility | Synchronously read trading wallet from localStorage |
+| `useBitcoinBalance` | Query | BTC balance for any address |
+| `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API |
+| `useFundTradingWallet` | Mutation | Fund trading wallet from personal wallet |
+| `useRadfiWithdraw` | Mutation | Withdraw from trading wallet |
+| `useExpiredUtxos` | Query | Expired UTXOs (polls 60s) |
+| `useRenewUtxos` | Mutation | Renew expired UTXOs |
+
+## Backend queries (~13)
+
+### Intents
+
+| Hook | Polling |
+|---|---|
+| `useBackendIntentByTxHash` | 1s (refetchInterval; fires once a `txHash` is set, unconditional) |
+| `useBackendIntentByHash` | none |
+| `useBackendUserIntents` | none |
+
+### Orderbook + swap submission
+
+| Hook | Type / Polling |
+|---|---|
+| `useBackendOrderbook` | Query; `staleTime: 30s` — fresh-window only, no background refetch |
+| `useBackendSubmitSwapTx` | Mutation |
+| `useBackendSubmitSwapTxStatus` | Query; polls until `executed` / `failed` |
+
+### Money market data
+
+| Hook | Purpose |
+|---|---|
+| `useBackendMoneyMarketPosition` | User position |
+| `useBackendMoneyMarketAsset` | Asset details |
+| `useBackendAllMoneyMarketAssets` | All MM assets |
+| `useBackendMoneyMarketAssetSuppliers` | Suppliers for an asset |
+| `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
+| `useBackendAllMoneyMarketBorrowers` | All borrowers |
+
+## Partner (6)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useFetchAssetsBalances` | Query | Fetch partner asset balances |
+| `useGetAutoSwapPreferences` | Query | Get auto-swap preferences |
+| `useIsTokenApproved` | Query | Check token approval |
+| `useApproveToken` | Mutation | Approve token |
+| `useSetSwapPreference` | Mutation | Set swap preference |
+| `useFeeClaimSwap` | Mutation | Claim partner fees via swap |
+
+## Recovery (2)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useHubAssetBalances` | Query | Hub asset balances |
+| `useWithdrawHubAsset` | Mutation | Withdraw hub asset |
+
+## Shared (~9)
+
+| Hook | Type | Purpose |
+|---|---|---|
+| `useXBalances` | Query | Cross-chain token balances |
+| `useDeriveUserWalletAddress` | Query | Derive hub wallet (CREATE3) |
+| `useGetUserHubWalletAddress` | Query | Derive hub wallet (wallet router) |
+| `useEstimateGas` | Mutation | Estimate gas for raw tx |
+| `useStellarTrustlineCheck` | Query | Check Stellar trustline |
+| `useRequestTrustline` | Mutation | Request a Stellar trustline |
+| `useSafeMutation` | Internal | The wrapper every mutation hook calls |
+| `unwrapResult` | Internal | `Result<T>` → throw / return |
+| `toResult` | Internal | `Promise<T>` → `Result<T>` |
+
+## Total
+
+41 mutations + ~50 queries + utilities + provider = **~95 hooks**.
+
+## Cross-references
+
+- [`../features/`](../features/) — per-feature reference docs (params types, return shapes, gotchas).
+- [`../recipes/`](../recipes/) — copy-paste worked examples per feature.
+- [`querykey-conventions.md`](querykey-conventions.md) — queryKey/mutationKey shape rules.

package/ai-exported/integration/reference/public-api.md

@@ -0,0 +1,110 @@
+# Public API — `@sodax/dapp-kit`
+
+What `@sodax/dapp-kit` exports + import rules.
+
+## Barrel exports
+
+The package's `src/index.ts` re-exports four buckets:
+
+```ts
+// @ai-snippets-skip
+export * from './hooks/index.js';      // ~95 hooks across 11 feature dirs
+export * from './providers/index.js';  // SodaxProvider, createSodaxQueryClient
+export * from './utils/index.js';      // dex-utils param builders
+export * from '@sodax/sdk';            // FULL @sodax/sdk re-export
+```
+
+Practical implications:
+- All ~95 hooks are importable from the root: `import { useSwap, useSupply, ... } from '@sodax/dapp-kit'`.
+- All `@sodax/sdk` types are importable from `@sodax/dapp-kit` directly: `import { ChainKeys, type SodaxConfig, type CreateIntentParams } from '@sodax/dapp-kit'`.
+- You may also import directly from `@sodax/sdk` — both work, both are stable.
+
+## Provider
+
+| Export | Type | Purpose |
+|---|---|---|
+| `SodaxProvider` | Component | App-level wrapper; provides `Sodax` SDK instance + RPC config |
+| `createSodaxQueryClient` | Factory | Returns a `QueryClient` pre-wired with `MutationCache.onError` for global mutation observability |
+
+## Hooks
+
+See [`hooks-index.md`](hooks-index.md) for the comprehensive table.
+
+## Utility types (for writing your own hooks against dapp-kit)
+
+```ts
+// @ai-snippets-skip
+type ReadHookParams<TData, TParams = void> = TParams extends void
+  ? { queryOptions?: ReadQueryOptions<TData> }
+  : { params?: TParams; queryOptions?: ReadQueryOptions<TData> };
+
+type ReadQueryOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn' | 'enabled'>;
+
+type MutationHookParams<TData, TVars> = {
+  mutationOptions?: MutationHookOptions<TData, TVars>;
+};
+
+type MutationHookOptions<TData, TVars> = Omit<UseMutationOptions<TData, Error, TVars>, 'mutationFn'>;
+
+type SafeUseMutationResult<TData, TError, TVars> = UseMutationResult<TData, TError, TVars> & {
+  mutateAsyncSafe: (vars: TVars) => Promise<Result<TData>>;
+};
+```
+
+## Helper functions (exported but mostly internal)
+
+| Export | Purpose |
+|---|---|
+| `useSafeMutation` | Drop-in replacement for React Query's `useMutation` — every dapp-kit mutation hook calls this internally |
+| `unwrapResult` | `Result<T>` → throw on `!ok`, return `value` on `ok` |
+| `toResult` | `Promise<T>` → `Promise<Result<T>>` |
+
+You won't need these unless you're writing a wrapper hook around a dapp-kit mutation hook. See [`../architecture.md`](../architecture.md) § "Mutation hook shape" for the full contract.
+
+## DEX param builders (exported from utils)
+
+```ts
+import {
+  createDepositParamsProps,
+  createWithdrawParamsProps,
+  createSupplyLiquidityParamsProps,
+  createDecreaseLiquidityParamsProps,
+} from '@sodax/dapp-kit';
+```
+
+These are pure functions for assembling DEX feature params from pool data + user input. The hooks `useCreateDepositParams`, etc., wrap them with React Query state.
+
+## Import rules
+
+### DO
+
+- ✓ Import from the package root: `import { useSwap } from '@sodax/dapp-kit'`.
+- ✓ Import SDK types from dapp-kit: `import { ChainKeys, type SodaxConfig } from '@sodax/dapp-kit'`. Re-exported transparently.
+- ✓ Import SDK types from SDK: `import { ChainKeys } from '@sodax/sdk'`. Same outcome.
+- ✓ Import wallet-sdk-react hooks separately: `import { useWalletProvider } from '@sodax/wallet-sdk-react'`. Sibling package, not re-exported.
+
+### DO NOT
+
+- ✗ Deep-import from `dist/`: importing from a path like `@sodax/dapp-kit/dist/...`. Internal paths are not stable; only the package root is the public contract.
+- ✗ Add `@sodax/types` as a separate dependency. It's transitively re-exported via `@sodax/sdk` (which dapp-kit re-exports). Adding it independently invites version skew.
+- ✗ Import from `@sodax/wallet-sdk-core`. That's the Node-side wallet implementations package — irrelevant for React consumers; use `@sodax/wallet-sdk-react`.
+
+## Tarball contents
+
+The published `@sodax/dapp-kit` tarball contains:
+
+```
+dist/                  # Built ESM (.mjs) + CJS (.cjs) + .d.ts
+ai-exported/           # This documentation tree
+package.json
+README.md
+LICENSE
+```
+
+Don't rely on any other path being present.
+
+## Cross-references
+
+- [`../architecture.md`](../architecture.md) — design rationale for the canonical hook shapes.
+- [`hooks-index.md`](hooks-index.md) — full hook list.
+- [`../../../../sdk/ai-exported/integration/reference/public-api.md`](../../../../sdk/ai-exported/integration/reference/public-api.md) — underlying SDK's public API surface.

package/ai-exported/integration/reference/querykey-conventions.md

@@ -0,0 +1,179 @@
+# queryKey / mutationKey conventions — `@sodax/dapp-kit`
+
+Mandatory shape rules for every `queryKey` and `mutationKey`. Mechanically enforced on mutation keys by [`packages/dapp-kit/src/hooks/_mutationContract.test.ts`](../../../src/hooks/_mutationContract.test.ts); reviewer-enforced on query keys.
+
+## The five rules
+
+### Rule 1 — first segment is the feature directory name
+
+| 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'` |
+
+No exceptions. A hook in `swap/` whose key starts with `'intent'` is wrong.
+
+### Rule 2 — camelCase for all segments
+
+No kebab-case (`'btc-balance'`), no ad-hoc casing, no `snake_case`. Identifiers are camelCase string literals (`'tradingWalletBalance'`, `'submitSwapTx'`).
+
+### Rule 3 — shape is `[feature, action, ...identifiers]`
+
+Stable order: chain → token/asset → user → amount.
+
+```ts
+// @ai-snippets-skip
+queryKey: ['mm', 'allowance', srcChainKey, token, action]
+// not ['mm', 'allowance', token, srcChainKey, action]
+```
+
+### Rule 4 — bigints stringify
+
+React Query's hash uses `JSON.stringify` which throws on raw bigints. Always coerce:
+
+```ts
+queryKey: ['staking', 'stakeRatio', amount.toString()]   // ✓
+queryKey: ['staking', 'stakeRatio', amount]              // ✗ — runtime crash
+```
+
+Exception: query keys that pass bigint via the read hook's typed params and the corresponding invalidations use the same raw value — match the read hook's shape exactly. New code should always stringify.
+
+### Rule 5 — invalidate the narrowest key that could change
+
+If the mutation knows the affected `tokenId` / user / chain, scope the invalidation to it. Bare keys (no segments past the action) are reserved for "we don't know which variant changed" cases and should be commented.
+
+```ts
+// Good — narrow scope
+queryClient.invalidateQueries({ queryKey: ['dex', 'positionInfo', tokenId, poolKey] });
+
+// Acceptable — when the mutation can't scope further
+queryClient.invalidateQueries({ queryKey: ['swap', 'allowance'] }); // wipe all allowance variants on approve
+```
+
+## Worked examples
+
+```ts
+// @ai-snippets-skip
+// Cross-feature pattern: allowance reads. Shapes vary per feature (each carries
+// the inputs that actually scope the allowance). Match the read hook's shape exactly
+// from invalidations.
+queryKey: ['mm', 'allowance', srcChainKey, token, action]
+queryKey: ['swap', 'allowance', srcChainKey, srcAddress, inputToken, inputAmount.toString()]
+queryKey: ['bridge', 'allowance', srcChainKey, srcAddress, srcToken, amount.toString()]
+queryKey: ['dex', 'allowance', srcChainKey, asset, amount.toString()]
+queryKey: ['staking', 'allowance', srcChainKey, action, srcAddress, amount.toString()]
+//   ^^ action is a fixed literal per hook: 'stake' / 'unstake' / 'instantUnstake'
+
+// User position reads
+queryKey: ['mm', 'userReservesData', spokeChainKey, userAddress]
+queryKey: ['staking', 'info', srcChainKey, srcAddress]              // useStakingInfo — second segment is 'info', not 'stakingInfo'
+queryKey: ['shared', 'xBalances', xChainId, tokens, address]
+
+// Mutation default keys
+mutationKey: ['swap']                                                // useSwap
+mutationKey: ['swap', 'approve']                                     // useSwapApprove
+mutationKey: ['swap', 'cancel']                                      // useCancelSwap
+mutationKey: ['swap', 'limitOrder', 'create']                        // useCreateLimitOrder
+mutationKey: ['swap', 'limitOrder', 'cancel']                        // useCancelLimitOrder
+mutationKey: ['mm', 'supply']
+mutationKey: ['staking', 'stake']
+mutationKey: ['staking', 'approve', 'stake']                         // useStakeApprove (action discriminator inside the key)
+mutationKey: ['bridge']                                              // useBridge — single segment (no 'execute' suffix)
+mutationKey: ['migrate', 'icxToSoda']
+mutationKey: ['dex', 'supplyLiquidity']
+```
+
+## Per-feature key tables
+
+Skip if you're writing a feature hook for the first time and want to align with existing conventions.
+
+### Swap
+
+| Key | Hook |
+|---|---|
+| `['swap', 'quote', { ...payload, amount: payload.amount.toString() }]` | `useQuote` (object segment with bigint stringified) |
+| `['swap', 'allowance', srcChainKey, srcAddress, inputToken, inputAmount.toString()]` | `useSwapAllowance` |
+| `['swap', 'status', intentTxHash]` | `useStatus` |
+| `['swap']` | `useSwap` mutation key |
+| `['swap', 'approve']` | `useSwapApprove` |
+| `['swap', 'cancel']` | `useCancelSwap` |
+| `['swap', 'limitOrder', 'create']` | `useCreateLimitOrder` |
+| `['swap', 'limitOrder', 'cancel']` | `useCancelLimitOrder` |
+
+### Money market
+
+| Key | Hook |
+|---|---|
+| `['mm', 'reservesData']` | `useReservesData` |
+| `['mm', 'reservesHumanized']` | `useReservesHumanized` |
+| `['mm', 'reservesList']` | `useReservesList` |
+| `['mm', 'reservesUsdFormat']` | `useReservesUsdFormat` |
+| `['mm', 'userReservesData', spokeChainKey, userAddress]` | `useUserReservesData` |
+| `['mm', 'userFormattedSummary', spokeChainKey, userAddress]` | `useUserFormattedSummary` |
+| `['mm', 'allowance', srcChainKey, token, action]` | `useMMAllowance` |
+| `['mm', 'aToken', aToken]` | `useAToken` |
+| `['mm', 'aTokensBalances', aTokens, spokeChainKey, userAddress]` | `useATokensBalances` |
+| `['mm', 'supply']` | `useSupply` mutation |
+| `['mm', 'borrow']` | `useBorrow` |
+| `['mm', 'withdraw']` | `useWithdraw` |
+| `['mm', 'repay']` | `useRepay` |
+| `['mm', 'approve']` | `useMMApprove` |
+
+### Staking
+
+| Key | Hook |
+|---|---|
+| `['staking', 'info', srcChainKey, srcAddress]` | `useStakingInfo` (second segment is `'info'`, NOT `'stakingInfo'`) |
+| `['staking', 'unstakingInfo', srcChainKey, srcAddress]` | `useUnstakingInfo` |
+| `['staking', 'unstakingInfoWithPenalty', srcChainKey, srcAddress]` | `useUnstakingInfoWithPenalty` |
+| `['staking', 'config']` | `useStakingConfig` |
+| `['staking', 'stakeRatio', amount.toString()]` | `useStakeRatio` |
+| `['staking', 'instantUnstakeRatio', amount.toString()]` | `useInstantUnstakeRatio` |
+| `['staking', 'convertedAssets', amount.toString()]` | `useConvertedAssets` |
+| `['staking', 'allowance', srcChainKey, action, srcAddress, amount.toString()]` | `useStakeAllowance` / `useUnstakeAllowance` / `useInstantUnstakeAllowance` — `action` is a fixed literal per hook |
+| `['staking', 'stake']` | `useStake` mutation |
+| `['staking', 'unstake']` | `useUnstake` |
+| `['staking', 'instantUnstake']` | `useInstantUnstake` |
+| `['staking', 'claim']` | `useClaim` |
+| `['staking', 'cancelUnstake']` | `useCancelUnstake` |
+| `['staking', 'approve', 'stake' \| 'unstake' \| 'instantUnstake']` | `useStakeApprove` / `useUnstakeApprove` / `useInstantUnstakeApprove` |
+
+### Bridge / DEX / Migration / Bitcoin / etc.
+
+Follow the same shape. See the source hook files (`packages/dapp-kit/src/hooks/<feature>/`) for current keys.
+
+## v1 → v2
+
+In v1 dapp-kit, queryKey conventions were ad-hoc:
+
+```ts
+// @ai-snippets-skip — queryKey-shape examples; `...` is a placeholder, not real code
+// ai-keys-allow — v1 keys shown for migration context; not real v2 source keys
+// v1 examples
+queryKey: ['xBalances', ...]                  // missing feature prefix
+queryKey: ['btc-balance', ...]                // kebab-case
+queryKey: ['api', 'mm', ...]                  // wrong feature prefix
+mutationKey: undefined                         // many hooks had no default
+
+// v2
+queryKey: ['shared', 'xBalances', ...]        // feature-prefixed
+queryKey: ['bitcoin', 'balance', ...]         // camelCase
+queryKey: ['backend', 'mm', ...]              // correctly nested under 'backend'
+mutationKey: ['mm', 'supply']                 // every hook has a default; consumer can override via mutationOptions.mutationKey
+```
+
+For migration code grafting onto dapp-kit's cache invalidation, see [`../../migration/breaking-changes/querykey-conventions.md`](../../migration/breaking-changes/querykey-conventions.md).
+
+## Cross-references
+
+- [`../architecture.md`](../architecture.md) § "queryKey / mutationKey conventions" — full design rationale.
+- [`hooks-index.md`](hooks-index.md) — full hook table.