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

package/ai-exported/integration/features/money-market.md

@@ -0,0 +1,116 @@
+# Money Market — `@sodax/dapp-kit`
+
+Cross-chain lending and borrowing.
+
+Pair: [`../../migration/features/money-market.md`](../../migration/features/money-market.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// User mutations (4 actions)
+useSupply({ mutationOptions });
+useWithdraw({ mutationOptions });
+useBorrow({ mutationOptions });
+useRepay({ mutationOptions });
+
+// Allowance + approve — useMMAllowance wraps the MM params under `params.payload`
+useMMAllowance({ params: { payload: MoneyMarketParams<K> }, queryOptions });   // disabled for borrow/withdraw (data is undefined)
+useMMApprove({ mutationOptions });
+
+// Reserves data (read-only)
+useReservesData({ queryOptions });                     // All reserve data
+useReservesHumanized({ queryOptions });                // Decimal-normalized
+useReservesList({ queryOptions });                     // List of reserve asset addresses
+useReservesUsdFormat({ queryOptions });                // With USD values
+
+// User position
+useUserFormattedSummary({ params, queryOptions });     // Health factor, collateral, debt
+useUserReservesData({ params, queryOptions });         // Per-reserve user position
+
+// aTokens
+useAToken({ params, queryOptions });                   // aToken metadata
+useATokensBalances({ params, queryOptions });          // aToken balances
+```
+
+## Mutation params
+
+All four user mutations share the same TVars shape (only the `action` literal differs):
+
+```ts
+// @ai-snippets-skip
+type UseSupplyVars<K extends SpokeChainKey = SpokeChainKey> = {
+  params: MoneyMarketSupplyParams<K>;
+  walletProvider: GetWalletProviderType<K>;
+};
+
+// MoneyMarketSupplyParams<K>:
+// {
+//   srcChainKey: K;
+//   srcAddress: GetAddressType<K>;
+//   token: string;
+//   amount: bigint;
+//   action: 'supply';
+//   dstChainKey?: SpokeChainKey;  // optional cross-chain delivery
+//   dstAddress?: string;
+// }
+```
+
+`borrow`, `withdraw`, `repay` follow the same shape with their respective `action` literals (`'borrow'` / `'withdraw'` / `'repay'`). **All four actions** accept optional `dstChainKey`/`dstAddress` for cross-chain delivery — supply on chain A and credit collateral on chain B, withdraw from chain A into a wallet on chain B, etc.
+
+```ts
+// @ai-snippets-skip
+const { mutateAsyncSafe: supply } = useSupply();
+const result = await supply({
+  params: { srcChainKey: ChainKeys.BASE_MAINNET, srcAddress: '0x...', token: '0x...', amount: 1_000_000n, action: 'supply' },
+  walletProvider,
+});
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair
+```
+
+## Approve / allowance
+
+```ts
+// @ai-snippets-skip
+// useMMAllowance reads `params.payload` (the MM params); no walletProvider — the read calls
+// `isAllowanceValid` with `raw: true` internally. For borrow/withdraw, returns true automatically.
+const { data: isApproved } = useMMAllowance({ params: { payload: supplyParams } });
+const { mutateAsync: approve } = useMMApprove();
+if (!isApproved) await approve({ params: supplyParams, walletProvider });
+```
+
+`useMMAllowance` skips the on-chain check entirely for `'borrow'` / `'withdraw'` actions — the query is `enabled: false` for those, so `data` stays `undefined`. Treat "absent allowance for borrow/withdraw" as "approval not required" at the call site (these actions never need ERC-20 approval).
+
+## Reserves data hooks
+
+| Hook | Returns | When to use |
+|---|---|---|
+| `useReservesData` | `[ReserveData[], ...]` | Raw data for custom rendering |
+| `useReservesHumanized` | `ReserveDataHumanized[]` | Decimal-normalized (most common for UI) |
+| `useReservesList` | `Address[]` | Just the reserve addresses |
+| `useReservesUsdFormat` | `ReserveDataWithUsd[]` | With USD price overlays |
+| `useUserFormattedSummary` | `{ totalCollateralUSD, totalBorrowsUSD, healthFactor, ... }` | Dashboard-ready summary |
+| `useUserReservesData` | `UserReserveData[]` | Per-reserve user position |
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+| `useSupply` / `useBorrow` / `useWithdraw` / `useRepay` | `SafeUseMutationResult<TxHashPair, Error, ...>` (`{ srcChainTxHash, dstChainTxHash }`) |
+| `useMMApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, ...>` — chain-keyed receipt union |
+| `useMMAllowance` | `UseQueryResult<boolean, Error>` — already unwrapped; for `borrow`/`withdraw` actions the query is `enabled: false` and `data` is `undefined` |
+| Reserve / position hooks | `UseQueryResult<TData, Error>` — already unwrapped; queries throw on SDK `!ok` |
+
+## Gotchas
+
+1. **Health factor < 1.0 is liquidation territory.** Always render a warning when `useUserFormattedSummary().healthFactor < 1.05` or whatever margin your UX uses.
+2. **Cross-chain delivery via `dstChainKey`/`dstAddress`** — supported on all four actions (supply / withdraw / borrow / repay). Omit for same-chain operations; don't pass `dstChainKey === srcChainKey` (let the default kick in).
+3. **`useMMAllowance` is `enabled: false` for borrow/withdraw** — `data` stays `undefined` (not `true`). Treat "no allowance result for borrow/withdraw" as "approval not required" — those actions never need ERC-20 approval.
+4. **Position queries take `{ spokeChainKey, userAddress }`** (NOT `srcChainKey`/`srcAddress` — those are mutation-side names). The hub wallet derivation is automatic.
+
+## Cross-references
+
+- [`../recipes/money-market.md`](../recipes/money-market.md) — full worked examples.
+- [`../../migration/features/money-market.md`](../../migration/features/money-market.md) — v1 → v2 porting.
+- [`../../../../sdk/ai-exported/integration/features/money-market.md`](../../../../sdk/ai-exported/integration/features/money-market.md) — underlying SDK MM surface.

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

@@ -0,0 +1,123 @@
+# Staking — `@sodax/dapp-kit`
+
+SODA → xSODA staking via ERC-4626 vault. Five user actions plus reads.
+
+Pair: [`../../migration/features/staking.md`](../../migration/features/staking.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// Mutations
+useStake({ mutationOptions });
+useUnstake({ mutationOptions });                 // Request unstake (waiting period)
+useInstantUnstake({ mutationOptions });          // Instant unstake with slippage
+useClaim({ mutationOptions });                   // Claim SODA after waiting period
+useCancelUnstake({ mutationOptions });           // Cancel pending unstake
+
+// Allowance + approve (one per mutation that needs approval)
+useStakeApprove({ mutationOptions });
+useUnstakeApprove({ mutationOptions });
+useInstantUnstakeApprove({ mutationOptions });
+// Allowance hooks wrap the action params (without `action`) under params.payload.
+// Read-only — no walletProvider needed (the SDK call uses `raw: true`).
+useStakeAllowance({ params: { payload: Omit<StakeParams<K>, 'action'> }, queryOptions });
+useUnstakeAllowance({ params: { payload: Omit<UnstakeParams<K>, 'action'> }, queryOptions });
+useInstantUnstakeAllowance({ params: { payload: Omit<InstantUnstakeParams<K>, 'action'> }, queryOptions });
+
+// Reads
+useStakingInfo({ params, queryOptions });
+useUnstakingInfo({ params, queryOptions });
+useUnstakingInfoWithPenalty({ params, queryOptions });
+useStakingConfig({ queryOptions });
+useStakeRatio({ params, queryOptions });
+useInstantUnstakeRatio({ params, queryOptions });
+useConvertedAssets({ params, queryOptions });
+```
+
+## Mutation TVars
+
+```ts
+// @ai-snippets-skip
+type StakeParams<K> = { srcChainKey: K; srcAddress: Address; amount: bigint; minReceive: bigint; action: 'stake' };
+type UnstakeParams<K> = { srcChainKey: K; srcAddress: Address; amount: bigint; action: 'unstake' };
+type InstantUnstakeParams<K> = { srcChainKey: K; srcAddress: Address; amount: bigint; minAmount: bigint; action: 'instantUnstake' };
+type ClaimParams<K> = { srcChainKey: K; srcAddress: Address; requestId: bigint; amount: bigint; action: 'claim' };
+type CancelUnstakeParams<K> = { srcChainKey: K; srcAddress: Address; requestId: bigint; action: 'cancelUnstake' };
+
+// All wrapped as TVars: { params: <ParamsType>, walletProvider }
+```
+
+## Read shapes (key picks)
+
+```ts
+// @ai-snippets-skip
+// useStakingInfo — user position (data is already unwrapped from Result by the hook)
+useStakingInfo({ params: { srcAddress, srcChainKey } })
+//   → UseQueryResult<StakingInfo>
+//   StakingInfo = { totalStaked: bigint, userXSodaBalance: bigint, userXSodaValue: bigint, ... }
+
+// useUnstakingInfo — pending unstake requests
+useUnstakingInfo({ params: { srcAddress, srcChainKey } })
+//   → UseQueryResult<UnstakingInfo>
+//   UnstakingInfo = { userUnstakeSodaRequests: UserUnstakeInfo[], totalUnstaking: bigint }
+
+// useUnstakingInfoWithPenalty — same with penalty annotations
+useUnstakingInfoWithPenalty({ params: { srcAddress, srcChainKey } })
+//   → UseQueryResult<UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }>
+//   each request adds { penalty, penaltyPercentage, claimableAmount }
+
+// useStakingConfig — protocol params (no `params` input — only `queryOptions`)
+useStakingConfig()
+//   → UseQueryResult<StakingConfig>
+//   StakingConfig = { unstakingPeriod: bigint, minUnstakingPeriod: bigint, maxPenalty: bigint }
+
+// useStakeRatio — ratio with preview (data is a tuple, not a single bigint)
+useStakeRatio({ params: { amount: 1_000_000_000_000_000_000n } })
+//   → UseQueryResult<[xSodaAmount: bigint, previewDepositAmount: bigint]>
+//   data is the tuple directly (unwrapped) — read data?.[0] / data?.[1]
+```
+
+## Approval pattern
+
+Each of stake / unstake / instantUnstake has its OWN approve hook (different tokens):
+
+| Action | Token approved | Hook |
+|---|---|---|
+| `stake` | SODA | `useStakeApprove`, `useStakeAllowance` |
+| `unstake` | xSODA | `useUnstakeApprove`, `useUnstakeAllowance` |
+| `instantUnstake` | xSODA | `useInstantUnstakeApprove`, `useInstantUnstakeAllowance` |
+
+`claim` and `cancelUnstake` don't need approval (operating on hub-side state).
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+All read hooks here are **already unwrapped** — they call `unwrapResult` internally so SDK `!ok` becomes a thrown error (engages `isError` / `error` / `retry`). Read `data` directly; do NOT branch on `data.ok`.
+
+| Hook | Returns |
+|---|---|
+| `useStake` / `useUnstake` / `useInstantUnstake` / `useClaim` / `useCancelUnstake` | `SafeUseMutationResult<TxHashPair, Error, ...>` |
+| `useStakeApprove` etc. | `SafeUseMutationResult<TxReturnType<K, false>, Error, ...>` — chain-keyed receipt union |
+| `useStakingInfo` | `UseQueryResult<StakingInfo, Error>` |
+| `useUnstakingInfo` | `UseQueryResult<UnstakingInfo, Error>` |
+| `useUnstakingInfoWithPenalty` | `UseQueryResult<UnstakingInfoWithPenalty, Error>` (= `UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }`) |
+| `useStakingConfig` | `UseQueryResult<StakingConfig, Error>` |
+| `useStakeRatio` | `UseQueryResult<[bigint, bigint], Error>` (2-tuple: `[xSodaAmount, previewDepositAmount]`) |
+| `useInstantUnstakeRatio` / `useConvertedAssets` | `UseQueryResult<bigint, Error>` |
+| `useStakeAllowance` / `useUnstakeAllowance` / `useInstantUnstakeAllowance` | `UseQueryResult<boolean, Error>` |
+
+## Gotchas
+
+1. **`useStakeRatio` returns a tuple, not a bigint.** `data` is `[xSodaAmount, previewDepositAmount]` (already unwrapped) — index it: `data?.[0]` for the xSODA amount. Don't treat it as a single number.
+2. **Unstake penalty is piecewise, not purely linear.** Penalty is flat `maxPenalty` during the `minUnstakingPeriod`, then decays linearly to 0 by the full `unstakingPeriod`. `useStakingConfig` returns `{ unstakingPeriod, minUnstakingPeriod, maxPenalty }`. Use `useUnstakingInfoWithPenalty` to display per-request `penaltyPercentage` and `claimableAmount`.
+3. **Instant unstake bypasses the waiting period but pays slippage.** Use `useInstantUnstakeRatio` to preview the effective rate, then set `minAmount` for slippage protection.
+4. **`useUnstakingInfoWithPenalty` returns an object with an embedded array.** Access `data?.requestsWithPenalty` directly (already unwrapped) — do NOT chain `.value.` first. Each request is `UserUnstakeInfo & { penalty, penaltyPercentage, claimableAmount }`; the request id lives at `req.id`, NOT `req.request.requestId`.
+5. **All staking reads are unwrapped** (the hook throws on SDK `!ok`). Read `data` fields directly — no `.ok` / `.value` branching. This applies to `useStakingInfo`, `useUnstakingInfo`, `useUnstakingInfoWithPenalty`, `useStakingConfig`, `useStakeRatio`, `useInstantUnstakeRatio`, `useConvertedAssets`, and all three allowance hooks.
+
+## Cross-references
+
+- [`../recipes/staking.md`](../recipes/staking.md) — full worked examples.
+- [`../../migration/features/staking.md`](../../migration/features/staking.md) — v1 → v2 porting.
+- [`../../../../sdk/ai-exported/integration/features/staking.md`](../../../../sdk/ai-exported/integration/features/staking.md) — underlying SDK staking surface.

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

@@ -0,0 +1,101 @@
+# Swap — `@sodax/dapp-kit`
+
+Cross-chain token swaps via the intent-based solver.
+
+Pair: [`../../migration/features/swap.md`](../../migration/features/swap.md).
+
+## Hook surface
+
+```ts
+// @ai-snippets-skip
+// Queries — note the nested `params.payload` shape on useQuote and useSwapAllowance.
+// `payload` is the SDK request value (SolverIntentQuoteRequest, CreateIntentParams, etc.).
+useQuote({ params: { payload }, queryOptions });                                  // Real-time quote (3s)
+useSwapAllowance({ params: { payload, srcChainKey, walletProvider }, queryOptions }); // allowance (2s)
+useStatus({ params: { intentTxHash }, queryOptions });                            // Intent execution status (3s)
+
+// Mutations — domain inputs flow through mutate(vars), see Mutation params below
+useSwap({ mutationOptions });
+useSwapApprove({ mutationOptions });
+useCancelSwap({ mutationOptions });                  // TVars are FLAT: { srcChainKey, intent, walletProvider }
+useCreateLimitOrder({ mutationOptions });           // No deadline; cancel manually
+useCancelLimitOrder({ mutationOptions });           // TVars are FLAT: { srcChainKey, intent, walletProvider }
+```
+
+(In actual code, you import each hook directly: `import { useSwap, useSwapAllowance, ... } from '@sodax/dapp-kit'`.)
+
+## Mutation params
+
+```ts
+// @ai-snippets-skip
+const { mutateAsyncSafe: swap } = useSwap();
+
+// vars shape (TVars):
+type UseSwapVars<K extends SpokeChainKey = SpokeChainKey> = Omit<SwapActionParams<K, false>, 'raw'>;
+// = { params: CreateIntentParams; walletProvider: GetWalletProviderType<K> }
+
+const result = await swap({ params: intentParams, walletProvider });
+```
+
+`useSwapApprove` follows the same `{ params, walletProvider }` shape via `mutate(vars)`, where `params` is `CreateIntentParams<K> | CreateLimitOrderParams<K>` (the union — limit-order params also flow through `useSwapApprove`).
+
+`useCreateLimitOrder` takes `{ params: CreateLimitOrderParams; walletProvider }` (no deadline; the order persists until cancelled).
+
+**Cancel hooks are flat** (no `params` wrapper):
+- `useCancelSwap` takes `{ srcChainKey, intent, walletProvider }`.
+- `useCancelLimitOrder` takes `{ srcChainKey, intent, walletProvider }`.
+
+## Query params
+
+```ts
+// @ai-snippets-skip
+// useQuote — SDK request wrapped under params.payload
+type UseQuoteParams = ReadHookParams<
+  Result<SolverIntentQuoteResponse, SolverErrorResponse> | undefined,
+  { payload: SolverIntentQuoteRequest | undefined }
+>;
+
+// useSwapAllowance — payload + srcChainKey + walletProvider all nested under params
+type UseSwapAllowanceParams<K extends SpokeChainKey> = ReadHookParams<
+  boolean,
+  {
+    payload: CreateIntentParams | CreateLimitOrderParams | undefined;
+    srcChainKey: K | undefined;
+    walletProvider: GetWalletProviderType<K> | undefined;
+  }
+>;
+
+// useStatus — flat (no payload wrapper). Key is `intentTxHash` (NOT `intentHash`).
+// Return is Result-wrapped, like useQuote — branch on data?.ok before reading status fields.
+type UseStatusParams = ReadHookParams<
+  Result<SolverIntentStatusResponse, SolverErrorResponse> | undefined,
+  { intentTxHash: Hex | undefined }
+>;
+```
+
+## Return shapes
+
+| Hook | Returns |
+|---|---|
+| `useSwap` | `SafeUseMutationResult<SwapResponse, Error, UseSwapVars>` where `SwapResponse = { intent, intentDeliveryInfo, solverExecutionResponse }` |
+| `useSwapApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, UseSwapApproveVars<K>>` — chain-keyed receipt union (EVM/Stellar/Sui differ) |
+| `useCancelSwap` | `SafeUseMutationResult<TxHashPair, Error, { srcChainKey, intent, walletProvider }>` — note FLAT TVars |
+| `useCancelLimitOrder` | `SafeUseMutationResult<TxHashPair, Error, { srcChainKey, intent, walletProvider }>` — note FLAT TVars |
+| `useCreateLimitOrder` | `SafeUseMutationResult<{ intent, intentDeliveryInfo, ... }, Error, ...>` |
+| `useQuote` | `UseQueryResult<Result<SolverIntentQuoteResponse, SolverErrorResponse> \| undefined, Error>` — `data?.ok` branching required; polls 3 s |
+| `useSwapAllowance` | `UseQueryResult<boolean, Error>` — `data` is already-unwrapped `boolean \| undefined`; truthy when approved; polls 2 s |
+| `useStatus` | `UseQueryResult<Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined, Error>` — Result-wrapped like `useQuote`; `data?.ok` branching required; polls 3 s |
+
+## Gotchas
+
+1. **`Intent.srcChain` and `Intent.dstChain` keep their v1 names.** Even though request-side params use `srcChainKey`/`dstChainKey`, the read-side `Intent` type didn't rename. Don't blanket-replace these names.
+2. **Default `mutationKey` is `['swap']`.** Use `useIsMutating({ mutationKey: ['swap'] })` to get a global "any swap in flight" state. Override via `mutationOptions.mutationKey` if you want narrower scoping per-call.
+3. **Quotes auto-refresh every 3s** — pause polling by setting `queryOptions.refetchInterval: false` if the quote is in a non-visible UI.
+4. **Token list has duplicate addresses across chains.** `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens that share a contract address (same token deployed on different chains). When rendering a flat token list, use a composite key like `${token.address}-${token.blockchain_id}` — not `token.address` alone.
+
+## Cross-references
+
+- [`../recipes/swap.md`](../recipes/swap.md) — full worked example.
+- [`../recipes/mutation-error-handling.md`](../recipes/mutation-error-handling.md) — call-shape patterns.
+- [`../../migration/features/swap.md`](../../migration/features/swap.md) — v1 → v2 porting.
+- [`../../../../sdk/ai-exported/integration/features/swap.md`](../../../../sdk/ai-exported/integration/features/swap.md) — underlying SDK swap surface.

package/ai-exported/integration/quickstart.md

@@ -0,0 +1,187 @@
+# Quickstart — `@sodax/dapp-kit` v2
+
+Get a React app running with dapp-kit in five minutes. For copy-paste recipes per feature, see [`recipes/`](recipes/). For design rationale, see [`architecture.md`](architecture.md).
+
+## 1. Install
+
+```bash
+# Required
+pnpm add @sodax/dapp-kit @tanstack/react-query
+
+# Wallet connectivity (the canonical companion)
+pnpm add @sodax/wallet-sdk-react
+```
+
+`@sodax/dapp-kit` peers on `react`, `react-dom` (>=18), and `@tanstack/react-query`. It re-exports `@sodax/sdk` — don't add `@sodax/types` separately.
+
+## 2. Wire providers
+
+```tsx
+// providers.tsx
+import { QueryClientProvider } from '@tanstack/react-query';
+import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
+import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+import { ChainKeys, type DeepPartial, type SodaxConfig } from '@sodax/sdk';
+
+const queryClient = createSodaxQueryClient();
+
+const sodaxConfig: DeepPartial<SodaxConfig> = {
+  chains: {
+    [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
+    [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
+    [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
+    [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
+    // Add chains your dApp needs
+  },
+};
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    chains: {
+      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
+      [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
+    },
+  },
+};
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <SodaxProvider config={sodaxConfig}>
+      <QueryClientProvider client={queryClient}>
+        <SodaxWalletProvider config={walletConfig}>
+          {children}
+        </SodaxWalletProvider>
+      </QueryClientProvider>
+    </SodaxProvider>
+  );
+}
+```
+
+`createSodaxQueryClient` gives you a `QueryClient` pre-wired with global mutation observability. Optional — if you construct your own `QueryClient`, nothing changes. See [`recipes/observability.md`](recipes/observability.md).
+
+## 3. Initialize the SDK (optional)
+
+For the latest tokens / chains / fee parameters from the backend:
+
+```tsx
+import { useEffect } from 'react';
+import { useSodaxContext } from '@sodax/dapp-kit';
+
+export function useInitializeSodax() {
+  const { sodax } = useSodaxContext();
+  useEffect(() => {
+    sodax.config.initialize().then((result) => {
+      if (!result.ok) console.error('Failed to initialize Sodax:', result.error);
+    });
+  }, [sodax]);
+}
+```
+
+Skipping this works — feature services fall back to packaged defaults — but you'll miss tokens / chains added after the SDK release.
+
+## 4. Get a wallet provider
+
+```tsx
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function MyFeature() {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+  // undefined until the user connects a BSC wallet
+  return <button disabled={!walletProvider}>...</button>;
+}
+```
+
+`useWalletProvider` returns a chain-specific wallet provider object that satisfies `IEvmWalletProvider` (or `IIconWalletProvider`, `ISolanaWalletProvider`, etc., depending on the chain).
+
+## 5. Run a mutation
+
+The canonical pattern: hook takes `{ mutationOptions }` (optional); domain inputs flow through `mutate(vars)`. Use `mutateAsyncSafe` for explicit `Result<T>` branching:
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { CreateIntentParams } from '@sodax/sdk';
+
+function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+  const { mutateAsyncSafe: swap, isPending } = useSwap();
+
+  const handleSwap = async () => {
+    if (!walletProvider) return;
+    const result = await swap({ params: intentParams, walletProvider });
+    if (!result.ok) {
+      alert(result.error instanceof Error ? result.error.message : 'Swap failed');
+      return;
+    }
+    console.log('Swap submitted!', result.value);
+  };
+
+  return (
+    <button onClick={handleSwap} disabled={isPending || !walletProvider}>
+      {isPending ? 'Swapping...' : 'Swap'}
+    </button>
+  );
+}
+```
+
+The exact same pattern works for every mutation: `useBridge`, `useSupply`, `useStake`, `useDexDeposit`, etc. The only difference is the `params` shape (each feature's reference doc has the type signature).
+
+## 6. Run a query
+
+Queries take `{ params, queryOptions }`. The hook owns `queryKey`, `queryFn`, and `enabled`:
+
+```tsx
+import { useQuote } from '@sodax/dapp-kit';
+import { ChainKeys } from '@sodax/sdk';
+
+function SwapQuote({ amount }: { amount: bigint }) {
+  const { data: quoteResult, isLoading } = useQuote({
+    params: {
+      payload: amount > 0n
+        ? {
+            token_src: '0x0000000000000000000000000000000000000000',
+            token_dst: '0x0000000000000000000000000000000000000000',
+            token_src_blockchain_id: ChainKeys.BSC_MAINNET,
+            token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
+            amount,
+            quote_type: 'exact_input',
+          }
+        : undefined,
+    },
+    queryOptions: { staleTime: 3000 },
+  });
+
+  if (isLoading) return <p>Loading...</p>;
+  if (quoteResult?.ok) return <p>Output: {quoteResult.value.quoted_amount}</p>;
+  return null;
+}
+```
+
+Some query hooks return `Result<T>` as their `data` (the underlying SDK method returns Result and we surface it directly for query hooks; only mutations unwrap). Always check `.ok` before reading `.value`.
+
+## First-time troubleshooting
+
+| Error | Why | Fix |
+|---|---|---|
+| `Module '"@sodax/dapp-kit"' has no exported member 'useSpokeProvider'` | v1 hook deleted in v2. | Drop the import. Pass `walletProvider` (from `useWalletProvider`) into `mutate(vars)` instead. |
+| `Property 'approve' does not exist on type 'SafeUseMutationResult'` | v1 approve hooks returned `{ approve, isLoading, error }`; v2 returns `SafeUseMutationResult`. | Use `mutateAsync` / `mutateAsyncSafe`. `isLoading` → `isPending`. |
+| `Type 'CreateIntentParams' is missing the following properties from ...: walletProvider` | v1 hooks took params at hook-init; v2 takes them via `mutate(vars)`. | Move `params` and `walletProvider` from hook init to `mutate({ params, walletProvider })`. |
+| `Property 'xChainId' does not exist on type 'XToken'` | SDK-leakage rename: `xChainId` → `chainKey` on `XToken` in v2. | Use `xToken.chainKey`. (Note: `useXBalances` params still use `xChainId` for the request shape — that's distinct from the read shape.) |
+| `Type ... is missing the following properties from type 'MoneyMarketSupplyParams': srcChainKey, srcAddress` | SDK-leakage: v2 added required `srcChainKey` + `srcAddress` to action params. | Add both to your `params` payload. See [`features/money-market.md`](features/money-market.md). |
+| `Cannot read properties of undefined (reading 'sodax')` | `useSodaxContext` (or any dapp-kit hook) called outside `<SodaxProvider>`. | Wrap your component tree in `<SodaxProvider>` from this package. |
+
+For broader v1 → v2 migration, see [`../migration/README.md`](../migration/README.md).
+
+## What to read next
+
+- [`recipes/`](recipes/) — copy-paste patterns for each feature and cross-cutting concerns.
+- [`architecture.md`](architecture.md) — full design rationale for `useSafeMutation`, `unwrapResult`, queryKey conventions, etc.
+- [`features/<x>.md`](features/) — per-feature reference (hook tables, types, gotchas).
+- [`reference/hooks-index.md`](reference/hooks-index.md) — full hook table.
+- [`ai-rules.md`](ai-rules.md) — DO / DO NOT for AI agents writing dapp-kit code.
+
+## Cross-references
+
+- [`../../../sdk/ai-exported/AGENTS.md`](../../../sdk/ai-exported/AGENTS.md) — the underlying Core SDK's tree (resolves correctly in `node_modules/@sodax/`-layout). Useful when you hit SDK-level types or behaviors leaking through hook signatures.

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

@@ -0,0 +1,136 @@
+# Recipes — `@sodax/dapp-kit`
+
+Copy-paste patterns for adding SODAX features to a React app. Each recipe is self-contained and shows the canonical v2 hook shape (single-object params, `mutateAsyncSafe` for imperative flows, `Result<T>` handling).
+
+## Reading order
+
+1. **[`setup.md`](setup.md)** — Install packages, wire `SodaxProvider` + `QueryClientProvider`, optional `createSodaxQueryClient` for global mutation observability.
+2. **[`wallet-connectivity.md`](wallet-connectivity.md)** — Connect wallets via `@sodax/wallet-sdk-react`, get a typed `walletProvider` per chain, fetch token balances.
+3. Pick a feature recipe — each one is independent of the others.
+
+## Index
+
+### Foundation
+
+| Recipe | Purpose |
+|---|---|
+| [`setup.md`](setup.md) | Install packages, wire providers, optional `createSodaxQueryClient` |
+| [`wallet-connectivity.md`](wallet-connectivity.md) | Wallet connection, `useWalletProvider`, balance hooks |
+
+### Cross-cutting patterns
+
+| Recipe | Purpose |
+|---|---|
+| [`mutation-error-handling.md`](mutation-error-handling.md) | Pick between `mutate` / `mutateAsync` / `mutateAsyncSafe` |
+| [`observability.md`](observability.md) | Global mutation logging via `createSodaxQueryClient`, per-mutation `meta.silent` |
+| [`invalidations.md`](invalidations.md) | Hook-owned invalidations and how to compose your own `onSuccess` |
+
+### Per-feature
+
+| Recipe | Hooks covered |
+|---|---|
+| [`swap.md`](swap.md) | `useQuote`, `useSwap`, `useSwapAllowance`, `useSwapApprove`, limit orders |
+| [`bridge.md`](bridge.md) | `useBridge`, allowance/approval, bridgeable amounts/tokens |
+| [`money-market.md`](money-market.md) | `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, reserves data |
+| [`staking.md`](staking.md) | `useStake`, `useUnstake`, `useClaim`, staking info, ratios |
+| [`migration.md`](migration.md) | `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln` |
+| [`dex.md`](dex.md) | `useDexDeposit`, `useSupplyLiquidity`, positions, pools |
+| [`bitcoin.md`](bitcoin.md) | `useRadfiSession`, `useFundTradingWallet`, `useRadfiWithdraw`, UTXO management |
+| [`backend-queries.md`](backend-queries.md) | Intent tracking, orderbook, money market position queries (read-only, no wallet) |
+
+## Hook conventions (mandatory)
+
+These rules are enforced across every dapp-kit hook by [`packages/dapp-kit/src/hooks/_mutationContract.test.ts`](../../../src/hooks/_mutationContract.test.ts) and apply to everything you write against this package.
+
+### Single-object params
+
+```tsx
+import { useSwap, useSwapAllowance } from '@sodax/dapp-kit';
+import { ChainKeys } from '@sodax/sdk';
+
+// Query hooks — { params, queryOptions }
+// Note: many query hooks wrap the SDK request under `params.payload`; some nest sibling
+// fields like `walletProvider` or `srcChainKey` under `params` alongside `payload`.
+// `useSwapAllowance` is one such hook — see features/swap.md for the canonical shape.
+const { data: isApproved } = useSwapAllowance({
+  params: { payload: intentParams, srcChainKey: ChainKeys.BSC_MAINNET, walletProvider },
+});
+
+// Mutation hooks — hook takes only mutationOptions; domain inputs flow through mutate(vars)
+const { mutateAsync: swap } = useSwap();
+async function runSwap() {
+  if (!walletProvider) return;
+  await swap({ params: intentParams, walletProvider });
+}
+```
+
+No positional args. No `spokeProvider` at the hook level (that was v1; deleted in v2). All domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)` for mutations and through `params` for queries.
+
+### `mutateAsyncSafe`
+
+Every mutation hook returns three call shapes. `mutateAsyncSafe` is the recommended default for sequenced flows — it returns `Promise<Result<TData>>` and never rejects:
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+
+const { mutateAsyncSafe: swap } = useSwap();
+async function runSwap() {
+  if (!walletProvider) return;
+  const result = await swap({ params: intentParams, walletProvider });
+  if (!result.ok) { toast.error(result.error instanceof Error ? result.error.message : 'failed'); return; }
+  const { intent } = result.value;
+  console.log(intent);
+}
+```
+
+Full comparison in [`mutation-error-handling.md`](mutation-error-handling.md).
+
+### `queryOptions`
+
+All query hooks accept optional `queryOptions` to override React Query defaults. The hook owns `queryKey`, `queryFn`, and `enabled` — those are not consumer-overridable.
+
+```tsx
+import { useQuote } from '@sodax/dapp-kit';
+
+// `useQuote` wraps the SDK request under `params.payload` — don't pass the SDK request
+// directly under `params`. `payload` here is a `SolverIntentQuoteRequest`.
+const { data } = useQuote({
+  params: { payload },
+  queryOptions: { staleTime: 5000, refetchInterval: 10000 },
+});
+```
+
+### `Result<T>` in query hooks
+
+Some query hooks return `Result<T>` as their `data` (the underlying SDK method can fail). Always check `.ok` before accessing `.value`:
+
+```tsx
+import { useQuote } from '@sodax/dapp-kit';
+
+// useQuote nests the SDK request under params.payload. `payload` here is a `SolverIntentQuoteRequest`.
+const { data: quoteResult } = useQuote({ params: { payload } });
+if (quoteResult?.ok) {
+  const quote = quoteResult.value;
+  console.log(quote);
+} else {
+  console.error(quoteResult?.error);
+}
+```
+
+### `bigint` for amounts
+
+Token amounts are `bigint` scaled by decimals. Use `viem`'s `parseUnits` / `formatUnits`:
+
+```tsx
+import { parseUnits, formatUnits } from 'viem';
+const amount = parseUnits('1.5', 18);   // 1500000000000000000n
+const display = formatUnits(amount, 18); // '1.5'
+```
+
+## Backend / non-React consumers
+
+If you're building a backend (API server, bot, script), you don't need `@sodax/dapp-kit` at all — use `@sodax/sdk` directly. The SDK has its own AI-agent docs at `node_modules/@sodax/sdk/ai-exported/AGENTS.md`.
+
+## Migration pointer
+
+If you're porting v1 dapp-kit code to v2, start at [`../../migration/README.md`](../../migration/README.md). It covers: hook signatures (single-arg policy), `Result<T>` handling shift, deleted `useSpokeProvider`, queryKey conventions, and SDK leakage.