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

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

@@ -1,174 +0,0 @@
-# Recipe: Bridge
-
-Cross-chain token transfers via the hub-and-spoke vault architecture.
-
-**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
-
-## Hooks
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useBridge` | Mutation | Execute a cross-chain bridge transfer |
-| `useBridgeAllowance` | Query | Check if token approval is needed |
-| `useBridgeApprove` | Mutation | Approve tokens for bridge |
-| `useGetBridgeableAmount` | Query | Available bridgeable amount between two tokens |
-| `useGetBridgeableTokens` | Query | Tokens bridgeable to a destination chain |
-
-## Check Bridgeable Tokens
-
-```tsx
-import { useGetBridgeableTokens } from '@sodax/dapp-kit';
-import { ChainKeys } from '@sodax/sdk';
-
-function BridgeableTokensList() {
-  // `data` is `XToken[] | undefined` — the hook throws on SDK `!ok` so we get the unwrapped value.
-  const { data: tokens } = useGetBridgeableTokens({
-    params: { from: ChainKeys.BASE_MAINNET, to: ChainKeys.POLYGON_MAINNET, token: '0x0000000000000000000000000000000000000000' },
-  });
-
-  if (tokens) {
-    return <ul>{tokens.map((t) => <li key={t.address}>{t.symbol}</li>)}</ul>;
-  }
-  return null;
-}
-```
-
-## Check Allowance + Approve
-
-```tsx
-import { useBridgeAllowance, useBridgeApprove } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import type { CreateBridgeIntentParams } from '@sodax/sdk';
-
-function BridgeApproval({ params }: { params: CreateBridgeIntentParams }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-  // useBridgeAllowance wraps payload + walletProvider under params (not at top level).
-  const { data: isApproved } = useBridgeAllowance({
-    params: { payload: params, walletProvider },
-  });
-  const { mutateAsync: approve, isPending } = useBridgeApprove();
-
-  if (isApproved) return null;
-  return (
-    <button onClick={() => walletProvider && approve({ params, walletProvider })} disabled={isPending}>
-      {isPending ? 'Approving...' : 'Approve for Bridge'}
-    </button>
-  );
-}
-```
-
-## Execute Bridge
-
-```tsx
-import { useBridge } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function BridgeButton({ srcAddress }: { srcAddress: `0x${string}` }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-  const { mutateAsync: bridge, isPending } = useBridge();
-
-  const handleBridge = async () => {
-    if (!walletProvider) return;
-    try {
-      const { srcChainTxHash, dstChainTxHash } = await bridge({
-        params: {
-          srcChainKey: ChainKeys.BASE_MAINNET,
-          srcAddress,
-          srcToken: '0x0000000000000000000000000000000000000000',
-          amount: 1000000000000000000n,
-          dstChainKey: ChainKeys.POLYGON_MAINNET,
-          dstToken: '0x0000000000000000000000000000000000000000',
-          recipient: '0x0000000000000000000000000000000000000000',
-        },
-        walletProvider,
-      });
-      console.log('Bridge successful:', { srcChainTxHash, dstChainTxHash });
-    } catch (e) {
-      console.error(e);
-    }
-  };
-
-  return (
-    <button onClick={handleBridge} disabled={isPending}>
-      {isPending ? 'Bridging...' : 'Bridge'}
-    </button>
-  );
-}
-```
-
-## Full Example
-
-```tsx
-import { useState } from 'react';
-import { useBridge, useBridgeAllowance, useBridgeApprove, useGetBridgeableAmount } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys, type XToken } from '@sodax/sdk';
-import type { CreateBridgeIntentParams } from '@sodax/sdk';
-import { parseUnits, formatUnits } from 'viem';
-
-export function BridgePage({ srcXToken, dstXToken, srcAddress }: { srcXToken: XToken; dstXToken: XToken; srcAddress: `0x${string}` }) {
-  const [amount, setAmount] = useState('');
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-  const parsedAmount = amount ? parseUnits(amount, 6) : 0n;
-
-  const bridgeParams: CreateBridgeIntentParams<typeof ChainKeys.BASE_MAINNET> | undefined = parsedAmount > 0n
-    ? {
-        srcChainKey: ChainKeys.BASE_MAINNET,
-        srcAddress,
-        srcToken: srcXToken.address,
-        amount: parsedAmount,
-        dstChainKey: ChainKeys.POLYGON_MAINNET,
-        dstToken: dstXToken.address,
-        recipient: '0x0000000000000000000000000000000000000000',
-      }
-    : undefined;
-
-  // useGetBridgeableAmount in v2 takes a pair of XToken objects (each carries chainKey).
-  // `data` is `BridgeLimit | undefined` (already unwrapped; hook throws on SDK !ok).
-  const { data: bridgeableAmount } = useGetBridgeableAmount({
-    params: { from: srcXToken, to: dstXToken },
-  });
-  const { data: isApproved } = useBridgeAllowance({
-    params: bridgeParams ? { payload: bridgeParams, walletProvider } : undefined,
-  });
-  const { mutateAsyncSafe: approve, isPending: isApproving } = useBridgeApprove();
-  const { mutateAsyncSafe: bridge, isPending: isBridging } = useBridge();
-
-  const handleBridge = async () => {
-    if (!bridgeParams || !walletProvider) return;
-    if (!isApproved) {
-      const r = await approve({ params: bridgeParams, walletProvider });
-      if (!r.ok) { alert(r.error instanceof Error ? r.error.message : 'Approve failed'); return; }
-    }
-    const r = await bridge({ params: bridgeParams, walletProvider });
-    if (r.ok) alert(`Bridge complete! src=${r.value.srcChainTxHash}`);
-    else alert(r.error instanceof Error ? r.error.message : 'Bridge failed');
-  };
-
-  return (
-    <div>
-      <input placeholder="Amount" value={amount} onChange={(e) => setAmount(e.target.value)} />
-      {bridgeableAmount && <p>Max: {formatUnits(bridgeableAmount.amount, bridgeableAmount.decimals)}</p>}
-      <button onClick={handleBridge} disabled={isBridging || isApproving || !bridgeParams || !walletProvider}>
-        {isApproving ? 'Approving...' : isBridging ? 'Bridging...' : 'Bridge'}
-      </button>
-    </div>
-  );
-}
-```
-
-## Types
-
-```typescript
-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
-};
-```

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

@@ -1,204 +0,0 @@
-# Recipe: DEX
-
-Concentrated liquidity positions and asset management.
-
-**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
-
-## Hooks
-
-### Assets
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useDexDeposit` | Mutation | Deposit assets into pool tokens |
-| `useDexWithdraw` | Mutation | Withdraw assets from pool tokens |
-| `useDexAllowance` | Query | Check approval for deposit |
-| `useDexApprove` | Mutation | Approve tokens |
-| `usePoolBalances` | Query | User's pool token balances |
-
-### Liquidity
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useSupplyLiquidity` | Mutation | Supply liquidity to a position |
-| `useDecreaseLiquidity` | Mutation | Remove liquidity |
-| `useClaimRewards` | Mutation | Claim trading fees |
-| `usePools` | Query | List available pools |
-| `usePoolData` | Query | Pool details (price, tick, liquidity) |
-| `usePositionInfo` | Query | Position details |
-| `useLiquidityAmounts` | Query | Token amounts for a tick range |
-
-### Param Builders
-
-| Hook | Purpose |
-|------|---------|
-| `useCreateDepositParams` | Build deposit params with ERC-4626 conversion |
-| `useCreateWithdrawParams` | Build withdraw params |
-| `useCreateSupplyLiquidityParams` | Build tick range + liquidity params |
-| `useCreateDecreaseLiquidityParams` | Build decrease params from position state |
-
-## List Pools
-
-```tsx
-import { usePools } from '@sodax/dapp-kit';
-
-function PoolsList() {
-  // `usePools` returns `PoolKey[]` — pool keys carry `currency0`, `currency1`, `fee`,
-  // `hooks`, `poolManager`, and `parameters`. Resolve token symbols via your own
-  // token-list lookup (e.g. config-derived).
-  const { data: pools } = usePools({});
-  return (
-    <div>
-      {pools?.map((pool, i) => (
-        <div key={`${pool.currency0}-${pool.currency1}-${pool.fee}-${i}`}>
-          <h3>{pool.currency0} / {pool.currency1}</h3>
-          <p>Fee: {pool.fee / 10000}%</p>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Deposit Assets
-
-```tsx
-import { useDexDeposit, useDexAllowance, useDexApprove } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys, type CreateAssetDepositParams } from '@sodax/sdk';
-
-function DepositToPool({ srcAddress }: { srcAddress: `0x${string}` }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-  const depositParams: CreateAssetDepositParams<typeof ChainKeys.BASE_MAINNET> = {
-    srcChainKey: ChainKeys.BASE_MAINNET,
-    srcAddress,
-    asset: '0x0000000000000000000000000000000000000000',
-    amount: 1_000_000_000_000_000_000n,
-    poolToken: '0x0000000000000000000000000000000000000000',
-  };
-
-  // useDexAllowance wraps CreateAssetDepositParams under params.payload. Read-only;
-  // no walletProvider needed (the SDK call uses `raw: true`).
-  const { data: isApproved } = useDexAllowance({
-    params: { payload: depositParams },
-  });
-  const { mutateAsync: approve, isPending: isApproving } = useDexApprove();
-  const { mutateAsync: deposit, isPending: isDepositing } = useDexDeposit();
-
-  const handleDeposit = async () => {
-    if (!walletProvider) return;
-    try {
-      if (!isApproved) await approve({ params: depositParams, walletProvider });
-      const txHashPair = await deposit({ params: depositParams, walletProvider });
-      console.log('Deposited:', txHashPair);
-    } catch (e) {
-      console.error(e);
-    }
-  };
-
-  return (
-    <button onClick={handleDeposit} disabled={isDepositing || isApproving || !walletProvider}>
-      {isApproving ? 'Approving...' : isDepositing ? 'Depositing...' : 'Deposit'}
-    </button>
-  );
-}
-```
-
-## Supply Liquidity
-
-```tsx
-// @ai-snippets-skip — illustrative flow only; `useCreateSupplyLiquidityParams` takes
-// a flat shape `{ poolData, poolKey, minPrice, maxPrice, liquidityToken0Amount,
-// liquidityToken1Amount, slippageTolerance }` and the consumer must add
-// `srcChainKey` + `srcAddress` at the mutation call site. Real consumers should
-// reference `useCreateSupplyLiquidityParams` source for the full param set.
-import { useSupplyLiquidity, useCreateSupplyLiquidityParams } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function SupplyLiquidity() {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-  const supplyParams = useCreateSupplyLiquidityParams({
-    params: {
-      poolKey: { /* ... */ },
-      tickLower: -60000n,
-      tickUpper: 60000n,
-      amount0: 1_000_000_000_000_000_000n,
-      amount1: 1_000_000_000_000_000_000n,
-    },
-  });
-  const { mutateAsync: supplyLiquidity, isPending } = useSupplyLiquidity();
-
-  return (
-    <button
-      disabled={isPending || !supplyParams || !walletProvider}
-      onClick={async () => {
-        if (!supplyParams || !walletProvider) return;
-        try {
-          const txHashPair = await supplyLiquidity({ params: supplyParams, walletProvider });
-          console.log('Supplied:', txHashPair);
-        } catch (e) {
-          console.error(e);
-        }
-      }}
-    >
-      {isPending ? 'Supplying...' : 'Supply Liquidity'}
-    </button>
-  );
-}
-```
-
-## Position + Claim Rewards
-
-```tsx
-// @ai-snippets-skip — illustrative flow only. Real call-shape notes:
-//   - `usePositionInfo` params.tokenId is `string | null`, not bigint
-//   - `usePositionInfo` data is `{ positionInfo: ClPositionInfo, isValid: boolean }` —
-//     access `position.positionInfo.liquidity` etc.
-//   - `useClaimRewards` params shape: `{ srcChainKey, srcAddress, poolKey, tokenId,
-//     tickLower, tickUpper }` — far richer than shown.
-// See `features/dex.md` for the canonical param types.
-import { usePositionInfo, useClaimRewards } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import type { PoolKey } from '@sodax/sdk';
-
-function Position({ positionId, poolKey }: { positionId: bigint; poolKey: PoolKey }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-  const { data: position } = usePositionInfo({ params: { tokenId: positionId, poolKey } });
-  const { mutateAsync: claimRewards, isPending } = useClaimRewards();
-
-  if (!position) return null;
-  return (
-    <div>
-      <p>Liquidity: {position.liquidity.toString()}</p>
-      <p>Range: [{position.tickLower}, {position.tickUpper}]</p>
-      <button
-        onClick={() => walletProvider && claimRewards({ params: { srcChainKey: ChainKeys.BASE_MAINNET, positionId }, walletProvider })}
-        disabled={isPending || !walletProvider}
-      >
-        Claim Fees
-      </button>
-    </div>
-  );
-}
-```
-
-## Remove Liquidity
-
-```tsx
-// @ai-snippets-skip
-const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-const { mutateAsync: decreaseLiquidity } = useDecreaseLiquidity();
-
-await decreaseLiquidity({
-  params: { srcChainKey: ChainKeys.BASE_MAINNET, positionId, liquidity: 500_000n, amount0Min: 0n, amount1Min: 0n },
-  walletProvider,
-});
-```
-
-## Notes
-
-- **Two-step flow**: deposit assets (spoke → hub pool tokens) then supply liquidity (pool tokens → position).
-- **Ticks**: logarithmic price units (like Uniswap V3). Wider range = more trades, less capital efficiency.
-- **ERC-4626**: pool tokens are vault shares. Use `useCreateDepositParams` to handle the conversion.

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

@@ -1,115 +0,0 @@
-# Recipe: Invalidations — hook-owned, composable
-
-Every dapp-kit mutation hook owns its own query invalidations. After a successful mutation, the hook's `onSuccess` fires invalidation calls against the relevant query keys; **then** your consumer-provided `onSuccess` runs.
-
-## Default — invalidations just work
-
-```tsx
-import { useSwap } from '@sodax/dapp-kit';
-import type { CreateIntentParams, IEvmWalletProvider } from '@sodax/sdk';
-
-function SwapButton({ params, walletProvider }: { params: CreateIntentParams; walletProvider: IEvmWalletProvider }) {
-  const { mutateAsync: swap } = useSwap();
-
-  const handleClick = async () => {
-    // After this resolves successfully, dapp-kit invalidates `xBalances`
-    // for the source and destination chains automatically.
-    await swap({ params, walletProvider });
-  };
-
-  return <button onClick={handleClick}>Swap</button>;
-}
-```
-
-You don't need to call `queryClient.invalidateQueries` yourself. Each mutation hook knows what queries it can invalidate (e.g. `useSwap` invalidates `xBalances` for `srcChainKey` and `dstChainKey` from the variables).
-
-## Composing your own `onSuccess`
-
-Pass `mutationOptions.onSuccess` to run logic AFTER dapp-kit's invalidations:
-
-```tsx
-import { useSwap } from '@sodax/dapp-kit';
-
-const { mutateAsync: swap } = useSwap({
-  mutationOptions: {
-    onSuccess: (data, vars) => {
-      // Runs AFTER dapp-kit's xBalances invalidations.
-      // `data` is the unwrapped success value (SwapResponse).
-      trackSwap(data);
-      console.log('swap_complete', { from: vars.params.srcChainKey });
-    },
-  },
-});
-console.log(swap);
-```
-
-The order is fixed:
-
-1. `mutationFn` resolves successfully (SDK returned `{ ok: true }`).
-2. dapp-kit's hook-internal `onSuccess` runs the invalidations.
-3. Your `mutationOptions.onSuccess` runs.
-4. Per-call `mutate(vars, { onSuccess })` runs (if provided).
-
-Failed mutations never trigger any of steps 2–4 — invalidations are correctness logic, not "always run."
-
-## What gets invalidated, by feature
-
-Each feature mutation hook invalidates the related read keys. Common patterns:
-
-| Mutation | Invalidates |
-|---|---|
-| `useSwap` | `['shared', 'xBalances', srcChainKey]`, `['shared', 'xBalances', dstChainKey]` |
-| `useBridge` | Same as `useSwap` (xBalances on both chains). |
-| `useSupply`, `useWithdraw`, `useBorrow`, `useRepay` | `['mm', 'userReservesData']`, `['shared', 'xBalances', srcChainKey]`, plus reserves data on the affected token. |
-| `useStake`, `useUnstake`, `useClaim`, `useCancelUnstake`, `useInstantUnstake` | `['staking', 'info']`, `['staking', 'unstakingInfo']`, `['shared', 'xBalances', srcChainKey]`. |
-| `useDexDeposit`, `useDexWithdraw` | `['dex', 'poolBalances']`, `['shared', 'xBalances', srcChainKey]`. |
-| `useSupplyLiquidity`, `useDecreaseLiquidity`, `useClaimRewards` | `['dex', 'positionInfo', tokenId]`, `['dex', 'poolBalances']`. |
-| `useMigrateIcxToSoda`, etc. | `['shared', 'xBalances']` for source + destination chains. |
-| Approve hooks (`useSwapApprove`, etc.) | The corresponding allowance read (`['swap', 'allowance']`, etc.). |
-
-The exact keys are derived from `vars` at success time — so a successful supply on Base only invalidates Base-side reserves, not Arbitrum's.
-
-## Adding cross-feature invalidations
-
-If you operate across multiple features (e.g. you have a custom hook that does `swap → migrate`), invalidate the cross-feature keys yourself in the consumer `onSuccess`:
-
-```tsx
-import { useQueryClient } from '@tanstack/react-query';
-import { useSwap } from '@sodax/dapp-kit';
-
-const qc = useQueryClient();
-const { mutateAsync: swap } = useSwap({
-  mutationOptions: {
-    onSuccess: async (data, vars) => {
-      // dapp-kit invalidates xBalances. We additionally want to refresh a
-      // custom analytics view that tracks completed swap volume.
-      await qc.invalidateQueries({ queryKey: ['my-app', 'swap-volume'] });
-    },
-  },
-});
-```
-
-## Per-call invalidation
-
-For one-off invalidations (only on this specific click), pass `onSuccess` to `mutate`:
-
-```tsx
-// @ai-snippets-skip
-await swap.mutateAsync(
-  { params, walletProvider },
-  { onSuccess: () => navigate(`/swap/${data.intent.intentHash}`) }
-);
-```
-
-The order is unchanged: hook invalidations → consumer `onSuccess` → per-call `onSuccess`.
-
-## v1 → v2
-
-In v1 dapp-kit, consumers managed invalidations themselves — most apps had a `lib/invalidate*Queries.ts` utility that fired `queryClient.invalidateQueries(...)` after each mutation. Those utilities are no longer needed in v2; delete them.
-
-If you're migrating v1 code, see [`../../migration/breaking-changes/hook-signatures.md`](../../migration/breaking-changes/hook-signatures.md) for the full delta.
-
-## Cross-references
-
-- [`mutation-error-handling.md`](mutation-error-handling.md) — picking call shapes.
-- [`../architecture.md`](../architecture.md) — `_mutationContract.test.ts` enforces the canonical `onSuccess` composition pattern.