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

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

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

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

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

@@ -0,0 +1,212 @@
+# Recipe: Migration
+
+Legacy token migration (ICX, bnUSD, BALN) from the ICON ecosystem to SODAX.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useMigrateIcxToSoda` | Mutation | ICX/wICX (ICON) → SODA (Sonic) |
+| `useRevertMigrateSodaToIcx` | Mutation | SODA (Sonic) → wICX (ICON) |
+| `useMigratebnUSD` | Mutation | Legacy bnUSD ↔ new bnUSD (bidirectional, any spoke chain) |
+| `useMigrateBaln` | Mutation | BALN (ICON) → SODA (Sonic) with optional lock period |
+| `useMigrationApprove` | Mutation | Approve token spending before migration |
+| `useMigrationAllowance` | Query | Check if approval is needed |
+
+## Migration Paths
+
+| From | To | Reversible | Approval needed |
+|------|----|-----------|----------------|
+| ICX/wICX (ICON) | SODA (Sonic) | Yes (use `useRevertMigrateSodaToIcx`) | No (ICON has no ERC-20 allowance) |
+| BALN (ICON) | SODA (Sonic) | No | No |
+| Legacy bnUSD (EVM/Stellar/ICON) | New bnUSD | Yes (same hook, swap src/dst) | Yes (EVM/Stellar sources) |
+
+## ICX to SODA
+
+```tsx
+import { useMigrateIcxToSoda } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys, type IconAddress } from '@sodax/sdk';
+
+function IcxMigration({ srcAddress, dstAddress }: { srcAddress: IconAddress; dstAddress: `0x${string}` }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.ICON_MAINNET });
+  const { mutateAsync: migrate, isPending } = useMigrateIcxToSoda();
+
+  const handleMigrate = async () => {
+    if (!walletProvider) return;
+    try {
+      const txHashPair = await migrate({
+        params: {
+          srcChainKey: ChainKeys.ICON_MAINNET,
+          srcAddress,
+          // `address` must be the wICX or native-ICX token address — typed as the
+          // narrow IcxTokenType union from @sodax/sdk's ICON chain config.
+          address: 'cx3975b43d260fb8ec802cef6e60c2f4d07486f11d', // wICX on ICON mainnet
+          amount: 1_000_000_000_000_000_000n,
+          dstAddress, // Sonic recipient address
+        },
+        walletProvider,
+      });
+      console.log('Migrated:', txHashPair);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <button onClick={handleMigrate} disabled={isPending || !walletProvider}>
+      {isPending ? 'Migrating...' : 'Migrate ICX to SODA'}
+    </button>
+  );
+}
+```
+
+## Revert SODA → wICX
+
+Requires approval — SODA is an EVM token on Sonic.
+
+```tsx
+import { useMigrationAllowance, useMigrationApprove, useRevertMigrateSodaToIcx } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { IcxCreateRevertMigrationParams } from '@sodax/sdk';
+
+function RevertMigration({ srcAddress }: { srcAddress: `0x${string}` }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.SONIC_MAINNET });
+
+  const revertParams: IcxCreateRevertMigrationParams = {
+    srcChainKey: ChainKeys.SONIC_MAINNET,
+    srcAddress,
+    amount: 1_000_000_000_000_000_000n,
+    dstAddress: 'hx...', // ICON recipient address
+  };
+
+  const { data: isApproved } = useMigrationAllowance({
+    params: { params: revertParams, action: 'revert' },
+  });
+  const { mutateAsync: approve, isPending: isApproving } = useMigrationApprove();
+  const { mutateAsync: revert, isPending: isReverting } = useRevertMigrateSodaToIcx();
+
+  const handleRevert = async () => {
+    if (!walletProvider) return;
+    try {
+      if (!isApproved) {
+        await approve({ params: revertParams, walletProvider, action: 'revert' });
+      }
+      const txHashPair = await revert({ params: revertParams, walletProvider });
+      console.log('Reverted:', txHashPair);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <button onClick={handleRevert} disabled={isReverting || isApproving || !walletProvider}>
+      {isApproving ? 'Approving...' : isReverting ? 'Reverting...' : 'Revert to wICX'}
+    </button>
+  );
+}
+```
+
+## BALN to SODA (with optional lock period)
+
+BALN migration does not require approval (ICON chain, no ERC-20 allowance). Longer lock period = higher SODA reward multiplier.
+
+```tsx
+import { useMigrateBaln } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys, LockupPeriod, type IconAddress } from '@sodax/sdk';
+
+function BalnMigration({ srcAddress, dstAddress }: { srcAddress: IconAddress; dstAddress: `0x${string}` }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.ICON_MAINNET });
+  const { mutateAsync: migrateBaln, isPending } = useMigrateBaln();
+
+  const handleMigrate = async () => {
+    if (!walletProvider) return;
+    try {
+      const txHashPair = await migrateBaln({
+        params: {
+          srcChainKey: ChainKeys.ICON_MAINNET,
+          srcAddress,
+          amount: 100_000_000_000_000_000_000n,
+          // LockupPeriod is an enum in seconds: NO_LOCKUP (0.5x reward),
+          // SIX_MONTHS (0.75x), TWELVE_MONTHS (1.0x), EIGHTEEN_MONTHS (1.25x),
+          // TWENTY_FOUR_MONTHS (1.5x).
+          lockupPeriod: LockupPeriod.TWELVE_MONTHS,
+          dstAddress,
+          stake: true, // Auto-stake the migrated SODA into the xSODA vault
+        },
+        walletProvider,
+      });
+      console.log('BALN migrated:', txHashPair);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <button onClick={handleMigrate} disabled={isPending || !walletProvider}>
+      {isPending ? 'Migrating...' : 'Migrate BALN to SODA'}
+    </button>
+  );
+}
+```
+
+## bnUSD Migration (bidirectional)
+
+Works for legacy ↔ new bnUSD across spoke chains. May require approval on EVM/Stellar sources.
+
+```tsx
+import { useMigratebnUSD, useMigrationAllowance, useMigrationApprove } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { UnifiedBnUSDMigrateParams } from '@sodax/sdk';
+
+function BnUSDMigration({ srcAddress }: { srcAddress: string }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
+
+  const bnUSDParams: UnifiedBnUSDMigrateParams<typeof ChainKeys.BASE_MAINNET> = {
+    srcChainKey: ChainKeys.BASE_MAINNET,
+    srcAddress,
+    srcbnUSD: '0x...', // legacy bnUSD address on Base
+    dstChainKey: ChainKeys.ARBITRUM_MAINNET,
+    dstbnUSD: '0x...', // new bnUSD address on Arbitrum
+    amount: 1_000_000n, // 6 decimals
+    dstAddress: srcAddress,
+  };
+
+  const { data: isApproved } = useMigrationAllowance({
+    params: { params: bnUSDParams, action: 'migrate' },
+  });
+  const { mutateAsync: approve, isPending: isApproving } = useMigrationApprove();
+  const { mutateAsync: migratebnUSD, isPending: isMigrating } = useMigratebnUSD();
+
+  const handleMigrate = async () => {
+    if (!walletProvider) return;
+    try {
+      if (!isApproved) {
+        await approve({ params: bnUSDParams, walletProvider, action: 'migrate' });
+      }
+      const txHashPair = await migratebnUSD({ params: bnUSDParams, walletProvider });
+      console.log('bnUSD migrated:', txHashPair);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <button onClick={handleMigrate} disabled={isMigrating || isApproving || !walletProvider}>
+      {isApproving ? 'Approving...' : isMigrating ? 'Migrating...' : 'Migrate bnUSD'}
+    </button>
+  );
+}
+```
+
+## Notes
+
+- **ICX and BALN forward migrations** don't require approval — ICON has no ERC-20 allowance mechanism.
+- **SODA → ICX revert** and **EVM/Stellar bnUSD sources** require approval before migrating.
+- **BALN lock periods**: `0` = 0.5x reward, `6` = 0.75x, `12` = 1.0x, `24` = 1.5x (months).
+- `useMigratebnUSD` is bidirectional — swap `srcbnUSD`/`dstbnUSD` and `srcChainKey`/`dstChainKey` to go the other direction.