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

package/ai-exported/integration/architecture.md

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

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

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

package/ai-exported/integration/features/auxiliary-services.md

@@ -1,169 +0,0 @@
-# Auxiliary services — `@sodax/dapp-kit`
-
-Smaller surfaces grouped together: partner fee claiming, recovery, backend queries (read-only data hooks), and shared utilities.
-
-Pair: [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md).
-
-## Partner
-
-Partner fee claiming and auto-swap preferences.
-
-```ts
-// @ai-snippets-skip
-useFetchAssetsBalances({ params, queryOptions });   // Partner asset balances
-useGetAutoSwapPreferences({ params, queryOptions });
-useIsTokenApproved({ params: { payload: FeeTokenApproveParams }, queryOptions });
-useApproveToken({ mutationOptions });
-useSetSwapPreference({ mutationOptions });
-useFeeClaimSwap({ mutationOptions });               // Claim partner fees via swap
-```
-
-`useFeeClaimSwap` returns `SafeUseMutationResult<IntentAutoSwapResult, Error, UseFeeClaimSwapVars>` — the success value is `IntentAutoSwapResult` (NOT `SwapResponse`). TVars are `Omit<PartnerFeeClaimSwapAction<HubChainKey, false>, 'raw'>`.
-
-## Recovery
-
-Withdraw stuck hub-wallet assets back to a spoke chain.
-
-```ts
-// @ai-snippets-skip
-useHubAssetBalances({ params, queryOptions });      // List assets stuck on hub
-useWithdrawHubAsset({ mutationOptions });
-```
-
-## Backend queries (read-only data)
-
-No wallet connection required.
-
-### Intent tracking
-
-```ts
-// @ai-snippets-skip
-useBackendIntentByTxHash({ params, queryOptions });   // Polls 1s once a txHash is supplied
-useBackendIntentByHash({ params, queryOptions });
-useBackendUserIntents({ params, queryOptions });      // Date-filtered user history; data is { items: IntentResponse[], total, offset, limit }
-```
-
-### Orderbook
-
-```ts
-// @ai-snippets-skip
-// `pagination` MUST be nested under `params` — top-level pagination is invalid.
-useBackendOrderbook({ params: { pagination: { offset, limit } }, queryOptions });   // staleTime 30s; no auto-refresh
-```
-
-### Money market data
-
-```ts
-// @ai-snippets-skip
-useBackendMoneyMarketPosition({ params, queryOptions });
-useBackendMoneyMarketAsset({ params, queryOptions });
-useBackendAllMoneyMarketAssets({ queryOptions });
-useBackendMoneyMarketAssetSuppliers({ params, queryOptions });
-useBackendMoneyMarketAssetBorrowers({ params, queryOptions });
-// Pagination required — without it the query is disabled.
-useBackendAllMoneyMarketBorrowers({ params: { pagination: { offset, limit } }, queryOptions });
-```
-
-### Swap submission
-
-```ts
-// @ai-snippets-skip
-useBackendSubmitSwapTx({ mutationOptions });           // Mutation
-useBackendSubmitSwapTxStatus({ params, queryOptions }); // Query — check submitted status
-```
-
-`useBackendSubmitSwapTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`:
-
-```ts
-// @ai-snippets-skip
-const { mutateAsync: submitSwapTx } = useBackendSubmitSwapTx();
-await submitSwapTx({ request: swapPayload, apiConfig: { baseURL: 'https://...' } });
-```
-
-## Shared utilities
-
-Cross-cutting hooks used by other features.
-
-```ts
-// @ai-snippets-skip
-useSodaxContext();                                  // Access the Sodax SDK instance
-useHubProvider();                                   // Hub chain (Sonic) provider
-useXBalances({ params, queryOptions });             // Cross-chain token balances
-useDeriveUserWalletAddress({ params, queryOptions }); // Hub wallet address (CREATE3)
-useGetUserHubWalletAddress({ params, queryOptions }); // Hub wallet via wallet router
-useEstimateGas({ mutationOptions });                // Gas estimation for raw tx
-useStellarTrustlineCheck({ params, queryOptions });
-useRequestTrustline({ mutationOptions });
-```
-
-### `useXBalances` shape
-
-```ts
-// @ai-snippets-skip
-type UseXBalancesParams = ReadHookParams<Record<string, bigint>, {
-  xService: IXServiceBase | undefined;       // From @sodax/wallet-sdk-react's useXService
-  xChainId: SpokeChainKey | undefined;
-  xTokens: readonly XToken[];                // Tokens to fetch balances for
-  address: string | undefined;
-}>;
-```
-
-Note: the **request-side** field is `xChainId` (kept for the cross-chain abstraction it overlays). This is distinct from the v2-renamed token-side `chainKey` — don't conflate them.
-
-Consumer must supply `xService` from `@sodax/wallet-sdk-react`:
-
-```tsx
-// @ai-snippets-skip
-import { useXService, getXChainType } from '@sodax/wallet-sdk-react';
-const xService = useXService({ xChainType: getXChainType(xChainId) });
-const { data: balances } = useXBalances({ params: { xService, xChainId, xTokens, address } });
-```
-
-### Stellar trustlines
-
-Stellar accounts that have never held an asset have no trustline — receiving will fail. Pre-flight with `useStellarTrustlineCheck`; fix with `useRequestTrustline`:
-
-```ts
-// @ai-snippets-skip — illustrative only; real types pulled into agents below.
-// useStellarTrustlineCheck takes { token, amount, chainId, walletProvider } under params.
-// `chainId` here is a `SpokeChainKey` (typed loosely so consumers can pass any chain key —
-// the hook returns `true` for non-Stellar chains, making it safe to gate on conditionally).
-const { data: hasTrustline } = useStellarTrustlineCheck({
-  params: { token, amount, chainId: ChainKeys.STELLAR_MAINNET, walletProvider },
-});
-
-// useRequestTrustline is NOT a canonical mutation hook — it takes a single positional
-// `token` arg and returns { requestTrustline, isLoading, isRequested, error, data }.
-// The `requestTrustline` callback signature is:
-//   ({ token, amount, srcChainKey, walletProvider }) => Promise<string>
-// NOTE: fields are `token` / `amount` / `srcChainKey` / `walletProvider` — NOT
-// `account` / `asset`. Pass a StellarChainKey for srcChainKey.
-const { requestTrustline, isLoading } = useRequestTrustline(token);
-if (hasTrustline === false) {
-  await requestTrustline({ token, amount, srcChainKey: ChainKeys.STELLAR_MAINNET, walletProvider });
-}
-```
-
-## Default polling intervals
-
-| Hook | Polling | Notes |
-|---|---|---|
-| `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
-| `useBackendSubmitSwapTxStatus` | varies | poll stops on `executed` / `failed` |
-| `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
-| `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
-| `useQuote` (swap) | 3s | refetchInterval |
-| `useStatus` (swap) | 3s | refetchInterval |
-| `useSwapAllowance` (swap) | 2s | refetchInterval |
-| `useMMAllowance` (mm) | 5s | refetchInterval; `enabled: false` for borrow/withdraw actions |
-| Reserves data (mm) | 5s | `useReservesData` / `useReservesHumanized` / user position hooks |
-| Most others | None | |
-
-All overridable via `queryOptions.refetchInterval`.
-
-## Cross-references
-
-- [`../recipes/backend-queries.md`](../recipes/backend-queries.md) — worked examples for intent tracking, orderbook, MM data.
-- [`../recipes/wallet-connectivity.md`](../recipes/wallet-connectivity.md) — `useXBalances` worked example.
-- [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md) — v1 → v2 porting.
-- [`../../../../sdk/ai-exported/integration/features/auxiliary-services.md`](../../../../sdk/ai-exported/integration/features/auxiliary-services.md) — underlying SDK auxiliary surfaces (partner, recovery, backendApi).

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

@@ -1,87 +0,0 @@
-# Bitcoin (Radfi) — `@sodax/dapp-kit`
-
-Bitcoin trading via the Radfi protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
-
-Pair: [`../../migration/features/bitcoin.md`](../../migration/features/bitcoin.md).
-
-## Hook surface
-
-```ts
-// @ai-snippets-skip
-// Session lifecycle
-useRadfiAuth({ mutationOptions });               // Authenticate via BIP322 signing
-useRadfiSession(walletProvider);                 // Manage full lifecycle (login, refresh, auto-refresh)
-useTradingWallet(walletAddress);                 // Synchronous: read persisted session
-
-// Balances
-useBitcoinBalance({ params: { address, rpcUrl? }, queryOptions });             // Personal wallet (default mempool.space)
-useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Radfi API
-
-// Operations
-useFundTradingWallet({ mutationOptions });
-useRadfiWithdraw({ mutationOptions });
-useExpiredUtxos({ params: { walletProvider, tradingAddress }, queryOptions }); // Polls 60s
-useRenewUtxos({ mutationOptions });
-```
-
-## Session flow
-
-Radfi requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
-
-```ts
-// @ai-snippets-skip
-const { walletAddress, isAuthed, tradingAddress, login, isLoginPending } = useRadfiSession(walletProvider);
-```
-
-Lifecycle behavior:
-- On mount: refreshes token to validate existing session
-- Every 5 min: auto-refreshes access token
-- If refresh fails: clears session, sets `isAuthed = false`
-- Session persisted in localStorage (keyed by wallet address)
-
-## Mutation TVars
-
-```ts
-// @ai-snippets-skip
-// useFundTradingWallet
-type FundTradingWalletVars = { amount: bigint; walletProvider: IBitcoinWalletProvider };
-
-// useRadfiWithdraw
-type RadfiWithdrawVars = {
-  amount: string;
-  tokenId: string;       // e.g. '0:0'
-  withdrawTo: string;    // user's personal BTC address
-  walletProvider: IBitcoinWalletProvider;
-};
-
-// useRenewUtxos
-type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvider };
-```
-
-## Return shapes
-
-| Hook | Returns |
-|---|---|
-| `useRadfiAuth` | `SafeUseMutationResult<RadfiAuthResult, Error, UseRadfiAuthVars>` where `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields, NOT `RadfiSession` — the hook persists `publicKey` to localStorage internally but doesn't return it) |
-| `useFundTradingWallet` | `SafeUseMutationResult<TxId, Error, ...>` |
-| `useRadfiWithdraw` | `SafeUseMutationResult<{ txId, fee }, Error, ...>` |
-| `useRenewUtxos` | `SafeUseMutationResult<TxId, Error, ...>` |
-| `useRadfiSession` | `{ walletAddress, isAuthed, tradingAddress, login, isLoginPending }` (utility, not Query/Mutation) |
-| `useTradingWallet` | `{ tradingAddress: string \| undefined }` (synchronous from localStorage) |
-| `useBitcoinBalance` | `UseQueryResult<bigint, Error>` (BTC balance in sats; default Esplora is mempool.space, override via `rpcUrl`) |
-| `useTradingWalletBalance` | `UseQueryResult<RadfiWalletBalance, Error>` where `RadfiWalletBalance = { btcSatoshi: bigint; pendingSatoshi: bigint; externalPendingSatoshi: bigint; totalUtxos: number }` |
-| `useExpiredUtxos` | `UseQueryResult<RadfiUtxo[], Error>` where `RadfiUtxo = { _id, txid, vout, txidVout, satoshi, amount, address, isSpent, status, source, runes? }` |
-
-## Gotchas
-
-1. **Authentication required before any trading operation.** `useRadfiSession` manages this automatically — gate buttons on `isAuthed`.
-2. **Trading wallet is created during first authentication** — not a separate step.
-3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Radfi session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
-4. **PSBT signing flow for withdrawals.** Radfi server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
-5. **Session tokens are for API rate-limiting, not asset access.** Stored in localStorage keyed by wallet address. Compromise of localStorage data doesn't affect funds.
-6. **`useExpiredUtxos` polls every 60s** — set `queryOptions.refetchInterval: false` to disable while UI is hidden.
-
-## Cross-references
-
-- [`../recipes/bitcoin.md`](../recipes/bitcoin.md) — full worked examples (session, fund, withdraw, UTXO management).
-- [`../../migration/features/bitcoin.md`](../../migration/features/bitcoin.md) — v1 → v2 porting (mostly hook signature shape changes; flow stays the same).

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

@@ -1,91 +0,0 @@
-# Bridge — `@sodax/dapp-kit`
-
-Cross-chain token transfers via the hub-and-spoke vault architecture.
-
-Pair: [`../../migration/features/bridge.md`](../../migration/features/bridge.md).
-
-## Hook surface
-
-```ts
-// @ai-snippets-skip
-// Mutation
-useBridge({ mutationOptions });
-useBridgeApprove({ mutationOptions });
-
-// Queries
-// useBridgeAllowance nests payload + walletProvider under params (NOT at top level)
-useBridgeAllowance({ params: { payload: CreateBridgeIntentParams<K>, walletProvider }, queryOptions });
-useGetBridgeableAmount({ params: { from: XToken, to: XToken }, queryOptions });
-useGetBridgeableTokens({ params: { from: SpokeChainKey, to: SpokeChainKey, token: string }, queryOptions });
-```
-
-## Mutation params
-
-```ts
-// @ai-snippets-skip
-type CreateBridgeIntentParams<K extends SpokeChainKey = SpokeChainKey> = {
-  srcChainKey: K;
-  srcAddress: string;
-  srcToken: string;
-  amount: bigint;
-  dstChainKey: SpokeChainKey;
-  dstToken: string;
-  recipient: string;   // non-encoded recipient address on the destination chain
-};
-
-const { mutateAsyncSafe: bridge } = useBridge();
-const result = await bridge({ params, walletProvider });
-if (!result.ok) return;
-const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair
-```
-
-## Query params
-
-```ts
-// @ai-snippets-skip
-// useBridgeAllowance — payload + walletProvider nested under params
-type UseBridgeAllowanceParams<K extends SpokeChainKey> = ReadHookParams<
-  boolean,
-  {
-    payload: CreateBridgeIntentParams<K> | undefined;
-    walletProvider: GetWalletProviderType<K> | undefined;
-  }
->;
-
-// useGetBridgeableAmount — flat: pair of XToken objects
-type UseGetBridgeableAmountParams = ReadHookParams<BridgeLimit, {
-  from: XToken | undefined;
-  to: XToken | undefined;
-}>;
-// BridgeLimit = { amount: bigint; decimals: number; type: 'DEPOSIT_LIMIT' | 'WITHDRAWAL_LIMIT' }
-
-// useGetBridgeableTokens — flat: (from, to, token)
-type UseGetBridgeableTokensParams = ReadHookParams<XToken[], {
-  from: SpokeChainKey | undefined;
-  to: SpokeChainKey | undefined;
-  token: string | undefined;
-}>;
-```
-
-## Return shapes
-
-| Hook | Returns |
-|---|---|
-| `useBridge` | `SafeUseMutationResult<TxHashPair, Error, ...>` (`{ srcChainTxHash, dstChainTxHash }`) |
-| `useBridgeApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, UseBridgeApproveVars<K>>` — chain-keyed receipt union (EVM/Stellar/Sui differ) |
-| `useBridgeAllowance` | `UseQueryResult<boolean, Error>` — already unwrapped; on SDK `!ok` the queryFn returns `false` (does NOT throw), so `isError` stays clean |
-| `useGetBridgeableAmount` | `UseQueryResult<BridgeLimit, Error>` (richer than v1's bare `bigint`) |
-| `useGetBridgeableTokens` | `UseQueryResult<XToken[], Error>` |
-
-## Gotchas
-
-1. **`useGetBridgeableAmount` takes XToken objects, not addresses + chain ids.** Each `XToken` carries its own `chainKey`. v1 took 4 separate args; v2 takes 2 objects.
-2. **`useGetBridgeableAmount` value is `BridgeLimit`, not a bare bigint.** Access `result.value.amount` and `result.value.decimals` for the limit + scale.
-3. **Tokens are bridgeable iff they share the same vault on the hub.** Use `useGetBridgeableTokens` to enumerate compatible destinations for a given source — passing an incompatible pair to `bridge()` rejects with `VALIDATION_FAILED`.
-4. **`bridge()` returns `TxHashPair`, not a tuple.** Destructure as `{ srcChainTxHash, dstChainTxHash }` — never `[a, b]`.
-
-## Cross-references
-
-- [`../recipes/bridge.md`](../recipes/bridge.md) — full worked example.
-- [`../../migration/features/bridge.md`](../../migration/features/bridge.md) — v1 → v2 porting.
-- [`../../../../sdk/ai-exported/integration/features/bridge.md`](../../../../sdk/ai-exported/integration/features/bridge.md) — underlying SDK bridge surface.