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

package/ai-exported/integration/recipes/wallet-connectivity.md

@@ -1,128 +0,0 @@
-# Recipe: Wallet Connectivity
-
-Connect wallets and pass wallet providers to feature hooks.
-
-**Depends on:** [setup.md](setup.md)
-
-## Hooks
-
-| Hook | Package | Type | Purpose |
-|------|---------|------|---------|
-| `useWalletProvider` | `@sodax/wallet-sdk-react` | Utility | Get wallet provider for a chain from connected wallet |
-| `useHubProvider` | `@sodax/dapp-kit` | Utility | Access the hub chain (Sonic) provider |
-| `useDeriveUserWalletAddress` | `@sodax/dapp-kit` | Query | Derive hub wallet address from spoke address (CREATE3) |
-| `useGetUserHubWalletAddress` | `@sodax/dapp-kit` | Query | Derive hub wallet address via wallet router |
-| `useXBalances` | `@sodax/dapp-kit` | Query | Cross-chain token balances for an address |
-| `useEstimateGas` | `@sodax/dapp-kit` | Mutation | Estimate gas for raw transactions |
-| `useStellarTrustlineCheck` | `@sodax/dapp-kit` | Query | Check if Stellar account has sufficient trustline |
-| `useRequestTrustline` | `@sodax/dapp-kit` | Mutation | Request a Stellar trustline for a token |
-
-## Connect a Wallet
-
-`@sodax/wallet-sdk-react` provides per-chain wallet hooks:
-
-```tsx
-// @ai-snippets-skip
-import { useEvmWallet } from '@sodax/wallet-sdk-react';
-
-function ConnectButton() {
-  const { connect, disconnect, address, isConnected } = useEvmWallet();
-
-  if (isConnected) {
-    return (
-      <div>
-        <span>{address}</span>
-        <button onClick={disconnect}>Disconnect</button>
-      </div>
-    );
-  }
-  return <button onClick={() => connect()}>Connect Wallet</button>;
-}
-```
-
-## Get a Wallet Provider
-
-`useWalletProvider` returns a typed wallet provider for a specific chain. Pass it directly to feature hook mutation calls:
-
-```tsx
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function MyFeature() {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-  // undefined until wallet is connected for that chain
-  // Pass as: useSwap() then swap({ params, walletProvider })
-}
-```
-
-## Fetch Token Balances
-
-`useXBalances` from `@sodax/dapp-kit` fetches on-chain balances for a wallet address:
-
-```tsx
-import { useXBalances } from '@sodax/dapp-kit';
-import { useXService, getXChainType } from '@sodax/wallet-sdk-react';
-import { ChainKeys, type XToken } from '@sodax/sdk';
-
-function TokenBalance({ address, xTokens }: { address: string; xTokens: readonly XToken[] }) {
-  const xChainId = ChainKeys.BSC_MAINNET;
-  // `useXBalances` requires an `xService` from `@sodax/wallet-sdk-react` plus the chain key,
-  // the token list to read, and the user's address — all four fields are part of `params`.
-  const xService = useXService({ xChainType: getXChainType(xChainId) });
-  const { data: balances } = useXBalances({
-    params: { xService, xChainId, xTokens, address },
-  });
-
-  // balances is a map of token address → balance (bigint)
-}
-```
-
-## Use Wallet Provider in Feature Hooks
-
-All mutation hooks accept no arguments at initialization level. The `walletProvider` flows through `mutate(vars)`:
-
-```tsx
-import { useSwap } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function SwapButton() {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-  const { mutateAsync: swap, isPending } = useSwap();
-
-  const handleSwap = async () => {
-    if (!walletProvider) return;
-    const result = await swap({ params: intentParams, walletProvider });
-    // ...
-  };
-}
-```
-
-This pattern is consistent across all features: `useSwap`, `useBridge`, `useSupply`, `useStake`, `useDexDeposit`, etc.
-
-## No type cast is needed — broad-union wiring just works
-
-A common anti-pattern is reaching for `as any` / `as IEvmWalletProvider` when the runtime-typed `walletProvider` from `useWalletProvider({ xChainId })` is passed into a mutation hook. **That cast is not needed.** v2 accepts the broad-union wallet-provider type as long as the chain key on the payload and the wallet provider both come from the same runtime `xChainId` value.
-
-```tsx
-// @ai-snippets-skip — illustrative anti-pattern vs correct
-// ❌ ANTI-PATTERN — unnecessary cast
-const walletProvider = useWalletProvider({ xChainId });
-await swap({ params, walletProvider: walletProvider as any });           // don't
-await swap({ params, walletProvider: walletProvider as IEvmWalletProvider }); // don't
-
-// ✅ CORRECT — pass directly, TypeScript infers the relationship
-const walletProvider = useWalletProvider({ xChainId });
-if (!walletProvider) return;        // narrow undefined first
-await swap({ params, walletProvider });
-```
-
-### Why this works
-
-- `useWalletProvider({ xChainId })` returns `GetWalletProviderType<typeof xChainId> | undefined`. When `xChainId` is a runtime value (e.g. from props/state typed `SpokeChainKey`), the return type is the **broad union** `IWalletProvider | undefined`, not `any`.
-- Mutation hooks like `useSwap<K>()` default `K` to the broad `SpokeChainKey` union. Their `mutate` vars are typed `{ params: SwapParams<SpokeChainKey>, walletProvider: GetWalletProviderType<SpokeChainKey> }` — i.e. `walletProvider` is the same broad union.
-- The two unions are structurally assignable. No cast required.
-
-### When the cast is actually needed
-
-If you've narrowed `xChainId` to a literal (e.g. via `chainKey === ChainKeys.BSC_MAINNET` checks in a branch) and the mutation hook is also generic-narrowed, you'll get narrower types on both sides. Even there, the cast is usually unnecessary — TypeScript propagates the narrowed `K` through the hook's generic. Reach for a cast only when you can produce a real TS error message proving it's needed.

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

@@ -1,12 +0,0 @@
-# Reference — `@sodax/dapp-kit` v2
-
-Lookup tables. Read while writing code; not a tutorial.
-
-| File | What's in it |
-|---|---|
-| [`hooks-index.md`](hooks-index.md) | Comprehensive hook table (organized by feature, with hook type and purpose). |
-| [`querykey-conventions.md`](querykey-conventions.md) | Mandatory queryKey/mutationKey shape rules + per-feature key tables. |
-| [`public-api.md`](public-api.md) | What `@sodax/dapp-kit` exports + import rules. |
-| [`glossary.md`](glossary.md) | Type aliases (`ReadHookParams`, `MutationHookParams`, `SafeUseMutationResult`, `MutationHookOptions`, etc.). |
-
-For full SDK reference (chain keys, error codes, `Sodax` class surface, wallet provider interfaces), see [`../../../../sdk/ai-exported/integration/reference/`](../../../../sdk/ai-exported/integration/reference/) — `@sodax/dapp-kit` re-exports the SDK's public surface, so those types are reachable from `@sodax/dapp-kit` directly.

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

@@ -1,190 +0,0 @@
-# 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.
-
-Config is tracked by **reference** - see [`recipes/setup.md § Config reactivity`](../recipes/setup.md#config-reactivity) for module-const vs `useMemo` patterns.
-
-### `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

@@ -1,190 +0,0 @@
-# Hooks index — `@sodax/dapp-kit` v2
-
-Comprehensive hook table 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
-
-| 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
-
-| 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
-
-| 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
-
-| 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
-
-| 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
-
-| 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
-
-| 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
-
-### 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
-
-| 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
-
-| Hook | Type | Purpose |
-|---|---|---|
-| `useHubAssetBalances` | Query | Hub asset balances |
-| `useWithdrawHubAsset` | Mutation | Withdraw hub asset |
-
-## Shared
-
-| 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>` |
-
-## 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

@@ -1,110 +0,0 @@
-# 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';      // 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 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.