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

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

@@ -1,152 +0,0 @@
-# DEX — `@sodax/dapp-kit`
-
-Concentrated-liquidity DEX (similar to Uniswap V3). Two-step flow: deposit assets to mint pool tokens, then supply liquidity to a position.
-
-Pair: [`../../migration/features/dex.md`](../../migration/features/dex.md).
-
-## Hook surface
-
-```ts
-// @ai-snippets-skip
-// Asset deposit / withdraw (spoke ↔ hub pool tokens)
-useDexDeposit({ mutationOptions });
-useDexWithdraw({ mutationOptions });
-useDexAllowance({ params: { payload: CreateAssetDepositParams<K> }, queryOptions });
-useDexApprove({ mutationOptions });
-usePoolBalances({ params, queryOptions });
-
-// Liquidity (pool tokens ↔ position)
-useSupplyLiquidity({ mutationOptions });           // Mint new or increase existing
-useDecreaseLiquidity({ mutationOptions });
-useClaimRewards({ mutationOptions });
-
-// Reads
-usePools({ queryOptions });
-usePoolData({ params, queryOptions });
-usePositionInfo({ params, queryOptions });
-useLiquidityAmounts({ params, queryOptions });
-
-// Param builders (compute derived params client-side) — these take a FLAT props object,
-// NOT a `{ params }` wrapper. They return memoized derived params that the consumer adds
-// `srcChainKey` + `srcAddress` to at the mutation call site.
-useCreateDepositParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
-useCreateWithdrawParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
-useCreateSupplyLiquidityParams({ poolData, poolKey, minPrice, maxPrice, liquidityToken0Amount, liquidityToken1Amount, slippageTolerance, positionId?, isValidPosition? });
-useCreateDecreaseLiquidityParams({ /* see source for fields */ });
-```
-
-## SDK param types (passed via `mutate({ params, walletProvider })`)
-
-Each dex mutation hook's TVars is `{ params: <SDKParamsType>, walletProvider, timeout? }`. The SDK param types below are what goes INSIDE `params` — they are not the TVars themselves.
-
-```ts
-// @ai-snippets-skip
-// Deposit / withdraw — spoke chain assets → hub pool tokens (or vice versa)
-type CreateAssetDepositParams<K> = {
-  srcChainKey: K;
-  srcAddress: GetAddressType<K>;
-  asset: string;       // spoke-chain asset address
-  amount: bigint;
-  poolToken: string;   // hub-side pool token (vault) address
-  dst?: { chainKey: SpokeChainKey; address: string };
-};
-
-// Supply liquidity — `useSupplyLiquidity` fans out internally to mint-new vs
-// increase-existing based on params.tokenId + params.isValidPosition.
-// The TVars `params` field is `UseCreateSupplyLiquidityParamsResult & { srcChainKey, srcAddress }`
-// (the memoized output of `useCreateSupplyLiquidityParams` + the chain/address pair).
-// Underlying SDK type ClSupplyParams<K> (for mint-new) has NO tokenId field:
-type ClSupplyParams<K> = {
-  srcChainKey: K;
-  srcAddress: GetAddressType<K>;
-  poolKey: PoolKey;
-  tickLower: bigint;
-  tickUpper: bigint;
-  liquidity: bigint;
-  amount0Max: bigint;
-  amount1Max: bigint;
-  sqrtPriceX96: bigint;
-};
-// And ClIncreaseLiquidityParams<K> = ClSupplyParams<K> & { tokenId: bigint }
-// for the increase-existing branch.
-
-// Decrease liquidity
-type ClDecreaseLiquidityParams<K> = {
-  srcChainKey: K;
-  srcAddress: GetAddressType<K>;
-  poolKey: PoolKey;
-  tokenId: bigint;
-  liquidity: bigint;
-  amount0Min: bigint;
-  amount1Min: bigint;
-};
-
-// Claim rewards
-type ClClaimRewardsParams<K> = {
-  srcChainKey: K;
-  srcAddress: GetAddressType<K>;
-  poolKey: PoolKey;
-  tokenId: bigint;
-  tickLower: bigint;
-  tickUpper: bigint;
-};
-```
-
-## Param builders
-
-The `useCreate*Params` hooks compute the right derived params client-side (e.g. ERC-4626 share conversions for deposit, current tick range for liquidity). Spread the result into the mutation:
-
-```ts
-// @ai-snippets-skip — illustrative; `useCreateSupplyLiquidityParams` takes a FLAT props
-// object (not `{ params }`-wrapped). The consumer adds `srcChainKey` + `srcAddress` at
-// the mutation call site.
-const supplyResult = useCreateSupplyLiquidityParams({
-  poolData,
-  poolKey,
-  minPrice,
-  maxPrice,
-  liquidityToken0Amount,
-  liquidityToken1Amount,
-  slippageTolerance,
-  positionId,         // optional, for increase-existing
-  isValidPosition,    // optional, gates the increase-existing branch
-});
-
-const { mutateAsync: supply } = useSupplyLiquidity();
-if (supplyResult && walletProvider) {
-  await supply({
-    params: { ...supplyResult, srcChainKey, srcAddress },
-    walletProvider,
-  });
-}
-```
-
-## Return shapes
-
-| Hook | Returns |
-|---|---|
-| `useDexDeposit` / `useDexWithdraw` | `SafeUseMutationResult<TxHashPair, Error, UseDex(Deposit\|Withdraw)Vars<K>>` (TVars = `{ params, walletProvider, ...optional }`) |
-| `useDexApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, UseDexApproveVars<K>>` — chain-keyed receipt union |
-| `useSupplyLiquidity` (mint or increase) | `SafeUseMutationResult<TxHashPair, Error, UseSupplyLiquidityVars<K>>` — single shape for both branches; fan-out happens inside the hook |
-| `useDecreaseLiquidity` / `useClaimRewards` | `SafeUseMutationResult<TxHashPair, Error, ...>` |
-| `useDexAllowance` | `UseQueryResult<boolean, Error>` (already unwrapped; throws on SDK `!ok`) |
-| `usePools` | `UseQueryResult<PoolKey[], Error>` — `staleTime: Infinity` (no auto-refresh; pools are static config) |
-| `usePoolData` | `UseQueryResult<PoolData, Error>` |
-| `usePositionInfo` | `UseQueryResult<{ positionInfo: ClPositionInfo, isValid: boolean }, Error>` — `tokenId` param is `string \| null` (NOT bigint) |
-| `usePoolBalances` | `UseQueryResult<{ token0Balance: bigint; token1Balance: bigint }, Error>` |
-| `useLiquidityAmounts` | Direct synchronous calculation (memoized via `useMemo`) — not a React Query hook |
-
-## Gotchas
-
-1. **Two-step flow: deposit, then supply.** First `useDexDeposit` brings the spoke asset to the hub as pool-token shares (ERC-4626). Then `useSupplyLiquidity` uses those shares to mint or grow a position. UI flows usually combine them.
-2. **`useSupplyLiquidity` handles both mint-new and increase-existing.** If `params.tokenId` is provided AND that position is valid for the pool, it increases. Otherwise it mints a new position. Use `useCreateSupplyLiquidityParams` to handle the routing.
-3. **Ticks are logarithmic.** `tickLower` / `tickUpper` are not prices — they're indices. Convert with viem's `Q96` math or the SDK's helpers.
-4. **`usePools` never auto-refreshes.** Pools are static config — fetch once. Override `queryOptions.refetchInterval` only if you really know your config changed.
-5. **`useDexAllowance` doesn't take `walletProvider`.** Read-only — derives the user from `srcAddress` in `params`.
-6. **`useClaimRewards` operates per-position.** If you need to claim across multiple positions, call it once per `tokenId`. The hook invalidates the corresponding `usePositionInfo` after success.
-
-## Cross-references
-
-- [`../recipes/dex.md`](../recipes/dex.md) — full worked examples.
-- [`../../migration/features/dex.md`](../../migration/features/dex.md) — v1 → v2 porting.
-- [`../../../../sdk/ai-exported/integration/features/dex.md`](../../../../sdk/ai-exported/integration/features/dex.md) — underlying SDK DEX surface.

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

@@ -1,118 +0,0 @@
-# Migration — `@sodax/dapp-kit`
-
-Token migration: ICX/wICX → SODA, BALN → SODA, legacy bnUSD ↔ new bnUSD. Six per-action hooks plus shared allowance/approve.
-
-Pair: [`../../migration/features/migration.md`](../../migration/features/migration.md).
-
-## Hook surface
-
-```ts
-// @ai-snippets-skip — hook-surface listing; `<inner>` is a type placeholder, not real code
-// Mutations (one per action)
-useMigrateIcxToSoda({ mutationOptions });
-useRevertMigrateSodaToIcx({ mutationOptions });
-useMigratebnUSD({ mutationOptions });               // Bidirectional (auto-detects direction)
-useMigrateBaln({ mutationOptions });
-
-// Allowance + approve (action-discriminated)
-useMigrationApprove({ mutationOptions });
-// useMigrationAllowance — params nest `{ params: <inner-migration-params>, action }` under the outer `params`
-useMigrationAllowance({ params: { params: <inner>, action: 'migrate' | 'revert' }, queryOptions });
-```
-
-## Mutation params
-
-```ts
-// @ai-snippets-skip
-// useMigrateIcxToSoda — wICX (ICON) → SODA (Sonic)
-type IcxMigrateParams = {
-  srcChainKey: IconChainKey;   // typeof ChainKeys.ICON_MAINNET
-  srcAddress: IconAddress;     // `hx${string}` | `cx${string}`
-  address: IcxTokenType;       // narrow union: wICX address OR native-ICX address
-  amount: bigint;
-  dstAddress: Address;         // `0x${string}` — Sonic recipient
-};
-
-// useRevertMigrateSodaToIcx — SODA (Sonic) → wICX (ICON)
-type IcxCreateRevertMigrationParams = {
-  srcChainKey: SonicChainKey;  // typeof ChainKeys.SONIC_MAINNET
-  srcAddress: Address;         // `0x${string}` — Sonic
-  amount: bigint;
-  dstAddress: IconEoaAddress;  // `hx${string}` — ICON recipient
-};
-
-// useMigratebnUSD — bidirectional, swap srcbnUSD/dstbnUSD + chains for the other direction
-type UnifiedBnUSDMigrateParams<K extends SpokeChainKey> = {
-  srcChainKey: K;
-  srcAddress: string;          // SDK keeps this loose (cross-chain)
-  srcbnUSD: string;            // legacy or new bnUSD
-  dstChainKey: SpokeChainKey;
-  dstbnUSD: string;            // the other one
-  amount: bigint;
-  dstAddress: string;
-};
-
-// useMigrateBaln — BALN (ICON) → SODA with optional lock
-type BalnMigrateParams = {
-  srcChainKey: IconChainKey;
-  srcAddress: IconAddress;
-  amount: bigint;
-  lockupPeriod: LockupPeriod;  // enum (values in SECONDS), see below
-  dstAddress: Address;
-  stake: boolean;              // REQUIRED — auto-stake migrated SODA into xSODA vault
-};
-
-// `LockupPeriod` is an enum with 5 members (values are in seconds, NOT months):
-//   NO_LOCKUP            = 0                       (0.5x reward multiplier)
-//   SIX_MONTHS           = 6  * 30 * 24 * 60 * 60  (0.75x)
-//   TWELVE_MONTHS        = 12 * 30 * 24 * 60 * 60  (1.0x)
-//   EIGHTEEN_MONTHS      = 18 * 30 * 24 * 60 * 60  (1.25x)
-//   TWENTY_FOUR_MONTHS   = 24 * 30 * 24 * 60 * 60  (1.5x)
-
-// All wrapped as TVars: { params: <ParamsType>, walletProvider }
-```
-
-## Allowance / approve
-
-The migration approve/allowance hooks are **action-discriminated** — same hook handles all migrations, with `action` disambiguating which token is being approved:
-
-```ts
-// @ai-snippets-skip
-const { data: isApproved } = useMigrationAllowance({
-  params: { params: bnUSDParams, action: 'migrate' },   // 'migrate' | 'revert'
-});
-const { mutateAsync: approve } = useMigrationApprove();
-await approve({ params: bnUSDParams, walletProvider, action: 'migrate' });
-```
-
-## Migration paths summary
-
-| Migration | Approval needed? | Hook |
-|---|---|---|
-| ICX/wICX (ICON) → SODA | No (ICON has no ERC-20 allowance) | `useMigrateIcxToSoda` |
-| SODA → wICX (revert) | Yes | `useRevertMigrateSodaToIcx` + `useMigrationApprove({ action: 'revert' })` |
-| Legacy bnUSD ↔ new bnUSD (EVM) | Yes | `useMigratebnUSD` + `useMigrationApprove({ action: 'migrate' })` |
-| Legacy bnUSD (Stellar/Sui) ↔ new bnUSD | Maybe (depends on chain) | Same as above |
-| BALN (ICON) → SODA | No | `useMigrateBaln` |
-
-## Return shapes
-
-| Hook | Returns |
-|---|---|
-| `useMigrateIcxToSoda` / `useRevertMigrateSodaToIcx` / `useMigratebnUSD` / `useMigrateBaln` | `SafeUseMutationResult<TxHashPair, Error, ...>` |
-| `useMigrationApprove` | `SafeUseMutationResult<TxReturnType<K, false>, Error, ...>` — chain-keyed receipt union (EVM/Stellar differ) |
-| `useMigrationAllowance` | `UseQueryResult<boolean, Error>` (already unwrapped) |
-
-## Gotchas
-
-1. **`useMigratebnUSD` is bidirectional.** v2 detects direction from `(srcbnUSD, dstbnUSD)` token addresses. To go the other direction, swap the params; no separate hook.
-2. **BALN `lockupPeriod` is the `LockupPeriod` enum, NOT a literal number union.** Use `LockupPeriod.NO_LOCKUP`, `LockupPeriod.SIX_MONTHS`, `LockupPeriod.TWELVE_MONTHS`, `LockupPeriod.EIGHTEEN_MONTHS`, or `LockupPeriod.TWENTY_FOUR_MONTHS`. Enum values are in **seconds** (e.g. `TWELVE_MONTHS = 12 * 30 * 24 * 60 * 60`), not months. Reward multiplier ranges 0.5x (no lockup) → 1.5x (24 months). Also note: `BalnMigrateParams` requires `stake: boolean` — set `true` to auto-stake migrated SODA into the xSODA vault.
-3. **ICON-side migrations don't need approval.** ICON has no ERC-20 allowance mechanism.
-4. **`useRevertMigrateSodaToIcx` requires SODA approval on Sonic.** Use `useMigrationAllowance` + `useMigrationApprove` with `action: 'revert'`.
-5. **`useMigratebnUSD` errors include `direction: 'forward' | 'reverse'` on context.** When surfacing errors, distinguish forward vs reverse for clearer messaging.
-
-## Cross-references
-
-- [`../recipes/migration.md`](../recipes/migration.md) — full worked examples.
-- [`../../migration/features/migration.md`](../../migration/features/migration.md) — v1 → v2 porting (the v1 dapp-kit had a single `useMigrate(spokeProvider)`-style hook; v2 split into 6).
-- [`../../../../sdk/ai-exported/integration/features/icx-bnusd-baln.md`](../../../../sdk/ai-exported/integration/features/icx-bnusd-baln.md) — underlying SDK migration surface.

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

@@ -1,144 +0,0 @@
-# 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: { aToken }, queryOptions });                                  // aToken metadata (single)
-useATokensBalances({ params: { aTokens, spokeChainKey, userAddress }, queryOptions }); // aToken balances (batched multicall)
-```
-
-### Read-hook param shapes
-
-```ts
-// @ai-snippets-skip
-// useUserFormattedSummary / useUserReservesData — user-position queries
-type UseUserFormattedSummaryParams = ReadHookParams<FormatUserSummaryResponse, {
-  spokeChainKey: SpokeChainKey | undefined;
-  userAddress: string | undefined;
-}>;
-// Same shape on useUserReservesData. The hook derives the hub wallet from (spokeChainKey, userAddress) internally.
-
-// useAToken — single aToken metadata; FLAT (no chain/user fields)
-type UseATokenParams = ReadHookParams<ATokenData, {
-  aToken: Address | string | undefined;
-}>;
-// ATokenData = Erc20Token & { chainKey: ChainKey }
-
-// useATokensBalances — batched aToken balances
-type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
-  aTokens: readonly Address[];
-  spokeChainKey: SpokeChainKey | undefined;
-  userAddress: string | undefined;
-}>;
-// Returns a Map keyed by aToken address. The hook resolves the hub wallet from (spokeChainKey, userAddress).
-```
-
-> **Read-side chain key is `spokeChainKey`, not `srcChainKey`.** Mutation hooks (`useSupply`/`useBorrow`/etc.) use `srcChainKey` because the request crosses chains and needs a source. Read hooks describe a user's position on a single spoke chain — the field is `spokeChainKey`. Applies to `useATokensBalances`, `useUserFormattedSummary`, and `useUserReservesData` (`useAToken` is metadata-only and takes neither). Don't grep-replace one for the other.
-
-## 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

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

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