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

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

@@ -0,0 +1,202 @@
+# Recipe: Staking
+
+SODA token staking via xSODA ERC-4626 vault.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+### Mutations
+
+| Hook | Purpose |
+|------|---------|
+| `useStake` | Stake SODA, receive xSODA |
+| `useStakeApprove` | Approve SODA for staking |
+| `useUnstake` | Request unstake (waiting period) |
+| `useUnstakeApprove` | Approve xSODA for unstaking |
+| `useInstantUnstake` | Instant unstake with slippage |
+| `useInstantUnstakeApprove` | Approve xSODA for instant unstaking |
+| `useClaim` | Claim SODA after waiting period |
+| `useCancelUnstake` | Cancel pending unstake |
+
+### Queries
+
+| Hook | Purpose |
+|------|---------|
+| `useStakeAllowance` | Check SODA approval for staking |
+| `useUnstakeAllowance` | Check xSODA approval for unstaking |
+| `useInstantUnstakeAllowance` | Check xSODA approval for instant unstaking |
+| `useStakingInfo` | Staking position (total staked, xSODA balance, value) |
+| `useUnstakingInfo` | Pending unstake requests |
+| `useUnstakingInfoWithPenalty` | Unstake requests with penalty calcs |
+| `useStakingConfig` | Unstaking period, max penalty |
+| `useStakeRatio` | SODA-to-xSODA exchange rate |
+| `useInstantUnstakeRatio` | Instant unstake rate |
+| `useConvertedAssets` | xSODA to SODA conversion |
+
+## Staking Dashboard
+
+```tsx
+import { useStakingInfo, useStakingConfig, useStakeRatio } from '@sodax/dapp-kit';
+import type { SpokeChainKey } from '@sodax/sdk';
+import { formatUnits } from 'viem';
+
+function StakingDashboard({ srcAddress, srcChainKey }: { srcAddress: `0x${string}`; srcChainKey: SpokeChainKey }) {
+  const { data: info } = useStakingInfo({ params: { srcAddress, srcChainKey } });
+  const { data: config } = useStakingConfig({});
+  const { data: ratio } = useStakeRatio({ params: { amount: 1000000000000000000n } });
+
+  if (!info) return <div>Loading...</div>;
+  return (
+    <div>
+      <p>Total Staked: {formatUnits(info.totalStaked, 18)} SODA</p>
+      <p>Your xSODA: {formatUnits(info.userXSodaBalance, 18)}</p>
+      <p>Your Value: {formatUnits(info.userXSodaValue, 18)} SODA</p>
+      {ratio && <p>Rate: 1 SODA = {formatUnits(ratio[0], 18)} xSODA</p>}
+      {config && <p>Unstaking: {(Number(config.unstakingPeriod) / 86400).toFixed(1)} days</p>}
+    </div>
+  );
+}
+```
+
+## Stake
+
+```tsx
+import { useState } from 'react';
+import { useStake, useStakeAllowance, useStakeApprove, useStakeRatio } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import { parseUnits, formatUnits, type Address } from 'viem';
+
+function StakeForm({ srcAddress }: { srcAddress: Address }) {
+  const [amount, setAmount] = useState('');
+  const chainKey = ChainKeys.BASE_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+  const parsedAmount = amount ? parseUnits(amount, 18) : 0n;
+
+  const { data: ratio } = useStakeRatio({ params: { amount: parsedAmount } });
+
+  const stakeParams = parsedAmount > 0n
+    ? { srcChainKey: chainKey, srcAddress, amount: parsedAmount, minReceive: ratio ? (ratio[0] * 95n) / 100n : 0n, action: 'stake' as const }
+    : undefined;
+
+  // useStakeAllowance wraps `Omit<StakeParams, 'action'>` under params.payload. Read-only,
+  // no walletProvider needed (calls `staking.isAllowanceValid` with `raw: true` internally).
+  const { data: isApproved } = useStakeAllowance({
+    params: stakeParams
+      ? { payload: { srcChainKey: chainKey, srcAddress, amount: parsedAmount, minReceive: stakeParams.minReceive } }
+      : undefined,
+  });
+  const { mutateAsync: approve, isPending: isApproving } = useStakeApprove();
+  const { mutateAsync: stake, isPending: isStaking } = useStake();
+
+  const handleStake = async () => {
+    if (!stakeParams || !walletProvider) return;
+    try {
+      if (!isApproved) await approve({ params: stakeParams, walletProvider });
+      const txHashPair = await stake({ params: stakeParams, walletProvider });
+      console.log('Staked:', txHashPair);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <div>
+      <input placeholder="SODA amount" value={amount} onChange={(e) => setAmount(e.target.value)} />
+      {ratio && <p>~{formatUnits(ratio[0], 18)} xSODA</p>}
+      <button onClick={handleStake} disabled={isStaking || isApproving || !stakeParams || !walletProvider}>
+        {isApproving ? 'Approving...' : isStaking ? 'Staking...' : 'Stake'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Unstake + Claim
+
+```tsx
+import { useUnstakingInfoWithPenalty, useClaim } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import { formatUnits, type Address } from 'viem';
+
+function UnstakePanel({ srcAddress }: { srcAddress: Address }) {
+  const chainKey = ChainKeys.BASE_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+  const { data: info } = useUnstakingInfoWithPenalty({ params: { srcAddress, srcChainKey: chainKey } });
+  const { mutateAsync: claim } = useClaim();
+
+  return (
+    <div>
+      {info?.requestsWithPenalty.map((req, i) => (
+        <div key={i}>
+          <p>{formatUnits(req.claimableAmount, 18)} SODA claimable (penalty: {req.penaltyPercentage}%)</p>
+          <button
+            onClick={() => walletProvider && claim({
+              // req.id is the requestId on the UserUnstakeInfo shape; req.request holds the
+              // original UnstakeSodaRequest. ClaimParams takes the id and the post-penalty amount.
+              params: { srcChainKey: chainKey, srcAddress, requestId: req.id, amount: req.claimableAmount, action: 'claim' },
+              walletProvider,
+            })}
+          >
+            Claim
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Instant Unstake
+
+```tsx
+import { useInstantUnstake, useInstantUnstakeRatio } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import { type Address } from 'viem';
+
+function InstantUnstakeButton({ xSodaAmount, srcAddress }: { xSodaAmount: bigint; srcAddress: Address }) {
+  const chainKey = ChainKeys.BASE_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+  const { data: ratio } = useInstantUnstakeRatio({ params: { amount: xSodaAmount } });
+  const { mutateAsync: instantUnstake, isPending } = useInstantUnstake();
+
+  return (
+    <button
+      disabled={isPending || !walletProvider}
+      onClick={() => walletProvider && instantUnstake({
+        params: {
+          srcChainKey: chainKey,
+          srcAddress,
+          amount: xSodaAmount,
+          minAmount: ratio ? (ratio * 95n) / 100n : 0n,
+          action: 'instantUnstake',
+        },
+        walletProvider,
+      })}
+    >
+      {isPending ? 'Processing...' : 'Instant Unstake'}
+    </button>
+  );
+}
+```
+
+## Types
+
+```typescript
+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: { params: ParamsType, walletProvider }
+```
+
+## Notes
+
+- **Unstaking period**: configurable, check `useStakingConfig`.
+- **Penalty**: linear from `maxPenalty` to 0 over the unstaking period.
+- **Instant unstake**: no waiting, but pays slippage via StakingRouter.
+- Query hooks (`useStakingInfo`, `useUnstakingInfoWithPenalty`, etc.) take `{ params: { srcAddress, srcChainKey } }` — they derive the hub wallet internally.

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

@@ -0,0 +1,272 @@
+# Recipe: Swap
+
+Cross-chain token swaps via the intent-based solver.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useQuote` | Query | Real-time swap quote (auto-refreshes 3s) |
+| `useSwap` | Mutation | Execute a complete cross-chain swap |
+| `useSwapAllowance` | Query | Check if token approval is needed |
+| `useSwapApprove` | Mutation | Approve tokens for the swap contract |
+| `useStatus` | Query | Track intent execution status |
+| `useCancelSwap` | Mutation | Cancel an active swap intent |
+| `useCreateLimitOrder` | Mutation | Create a limit order (no deadline) |
+| `useCancelLimitOrder` | Mutation | Cancel an active limit order |
+
+## Get a Quote
+
+```tsx
+import { useQuote } from '@sodax/dapp-kit';
+import { ChainKeys } from '@sodax/sdk';
+
+function SwapQuote({ inputAmount }: { inputAmount: bigint }) {
+  const { data: quoteResult, isLoading } = useQuote({
+    params: {
+      payload: inputAmount > 0n
+        ? {
+            token_src: '0x2170Ed0880ac9A755fd29B2688956BD959F933F8',
+            token_dst: '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f',
+            token_src_blockchain_id: ChainKeys.BSC_MAINNET,
+            token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
+            amount: inputAmount,
+            quote_type: 'exact_input',
+          }
+        : undefined,
+    },
+  });
+
+  if (isLoading) return <div>Fetching quote...</div>;
+  if (quoteResult?.ok) return <div>Output: {quoteResult.value.quoted_amount}</div>;
+  return null;
+}
+```
+
+## Check Allowance + Approve
+
+```tsx
+import { useSwapAllowance, useSwapApprove } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { CreateIntentParams } from '@sodax/sdk';
+
+function SwapApproval({ intentParams }: { intentParams: CreateIntentParams }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+
+  // useSwapAllowance wraps the request under params.payload and takes walletProvider + srcChainKey
+  // alongside (all under `params`, not at the top level).
+  const { data: isApproved } = useSwapAllowance({
+    params: {
+      payload: intentParams,
+      srcChainKey: ChainKeys.BSC_MAINNET,
+      walletProvider,
+    },
+  });
+  const { mutateAsync: approve, isPending } = useSwapApprove();
+
+  // useSwapAllowance data is `boolean | undefined` (already unwrapped from Result by the hook).
+  if (isApproved) return null;
+  return (
+    <button onClick={() => walletProvider && approve({ params: intentParams, walletProvider })} disabled={isPending}>
+      {isPending ? 'Approving...' : 'Approve Token'}
+    </button>
+  );
+}
+```
+
+## Execute Swap
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { CreateIntentParams } from '@sodax/sdk';
+
+function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+  const { mutateAsync: swap, isPending } = useSwap();
+
+  const handleSwap = async () => {
+    if (!walletProvider) return;
+    try {
+      const { solverExecutionResponse, intent, intentDeliveryInfo } = await swap({
+        params: intentParams,
+        walletProvider,
+      });
+      console.log('Swap successful!', solverExecutionResponse);
+    } catch (e) {
+      // surfaced via mutation.error / onError
+    }
+  };
+
+  return (
+    <button onClick={handleSwap} disabled={isPending || !walletProvider}>
+      {isPending ? 'Swapping...' : 'Swap'}
+    </button>
+  );
+}
+```
+
+## Full Example
+
+```tsx
+import { useState } from 'react';
+import { useQuote, useSwap, useSwapAllowance, useSwapApprove } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { CreateIntentParams, SolverIntentQuoteRequest } from '@sodax/sdk';
+import { parseUnits } from 'viem';
+
+const SRC_TOKEN = '0x2170Ed0880ac9A755fd29B2688956BD959F933F8';
+const DST_TOKEN = '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f';
+
+export function SwapPage() {
+  const [inputAmount, setInputAmount] = useState('');
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
+  const parsedAmount = inputAmount ? parseUnits(inputAmount, 18) : 0n;
+
+  // 1. Quote — useQuote takes { params: { payload: SolverIntentQuoteRequest } }.
+  const { data: quoteResult, isLoading: isQuoting } = useQuote({
+    params: {
+      payload: parsedAmount > 0n
+        ? {
+            token_src: SRC_TOKEN,
+            token_dst: DST_TOKEN,
+            token_src_blockchain_id: ChainKeys.BSC_MAINNET,
+            token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
+            amount: parsedAmount,
+            quote_type: 'exact_input',
+          }
+        : undefined,
+    },
+  });
+
+  // 2. Build intent params. The request-side fields are `srcChainKey` / `dstChainKey`
+  // (distinct from the read-side `Intent.srcChain` / `Intent.dstChain` which are
+  // `IntentRelayChainId` bigints — a separate shape).
+  const intentParams: CreateIntentParams | undefined =
+    quoteResult?.ok
+      ? {
+          inputToken: SRC_TOKEN,
+          outputToken: DST_TOKEN,
+          inputAmount: parsedAmount,
+          minOutputAmount: BigInt(quoteResult.value.quoted_amount),
+          deadline: 0n,
+          allowPartialFill: false,
+          srcChainKey: ChainKeys.BSC_MAINNET,
+          dstChainKey: ChainKeys.ARBITRUM_MAINNET,
+          srcAddress: '0x0000000000000000000000000000000000000000', // connected wallet address
+          dstAddress: '0x0000000000000000000000000000000000000000', // destination address
+          solver: '0x0000000000000000000000000000000000000000',
+          data: '0x',
+        }
+      : undefined;
+
+  // 3. Allowance — useSwapAllowance nests payload + srcChainKey + walletProvider under params.
+  const { data: isApproved } = useSwapAllowance({
+    params: intentParams
+      ? { payload: intentParams, srcChainKey: ChainKeys.BSC_MAINNET, walletProvider }
+      : undefined,
+  });
+
+  // 4. Approve + Swap (using mutateAsyncSafe — no try/catch, no unhandled rejections)
+  const { mutateAsyncSafe: approve, isPending: isApproving } = useSwapApprove();
+  const { mutateAsyncSafe: swap, isPending: isSwapping } = useSwap();
+
+  const handleSwap = async () => {
+    if (!intentParams || !walletProvider) return;
+    if (!isApproved) {
+      const r = await approve({ params: intentParams, walletProvider });
+      if (!r.ok) { alert(r.error instanceof Error ? r.error.message : 'Approve failed'); return; }
+    }
+    const r = await swap({ params: intentParams, walletProvider });
+    if (r.ok) alert('Swap successful!');
+    else alert(r.error instanceof Error ? r.error.message : 'Swap failed');
+  };
+
+  return (
+    <div>
+      <input placeholder="Amount" value={inputAmount} onChange={(e) => setInputAmount(e.target.value)} />
+      {isQuoting && <p>Fetching quote...</p>}
+      {quoteResult?.ok && <p>Output: {quoteResult.value.quoted_amount}</p>}
+      <button onClick={handleSwap} disabled={isSwapping || isApproving || !intentParams}>
+        {isApproving ? 'Approving...' : isSwapping ? 'Swapping...' : 'Swap'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Limit Orders
+
+```tsx
+import { useCreateLimitOrder, useCancelLimitOrder } from '@sodax/dapp-kit';
+import type { Intent } from '@sodax/sdk';
+
+const { mutateAsync: createLimitOrder } = useCreateLimitOrder();
+const { mutateAsync: cancelLimitOrder } = useCancelLimitOrder();
+
+// Limit orders have no deadline, must be cancelled manually.
+// `useCancelLimitOrder` TVars are FLAT: `{ srcChainKey, intent, walletProvider }` (no `params` wrapper).
+async function flow(intent: Intent) {
+  if (!walletProvider) return;
+  await createLimitOrder({ params: limitOrderParams, walletProvider });
+  await cancelLimitOrder({ srcChainKey, intent, walletProvider });
+}
+```
+
+## Customize TanStack Query behavior
+
+Every mutation hook accepts an optional `mutationOptions` slot for consumers to override TanStack Query knobs (`retry`, `onError`, `mutationKey`, etc.). The hook's `mutationFn` throws on SDK failure (so `mutation.error`, `onError`, and `retry` engage natively); its own `onSuccess` invalidations run first on real success, then the consumer's `onSuccess` is awaited.
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+import { useIsMutating } from '@tanstack/react-query';
+
+const { mutateAsync: swap, isError, error } = useSwap({
+  mutationOptions: {
+    retry: 5,
+    onError: err => toast.error(err.message),
+    onSuccess: swapResponse => {
+      // Runs AFTER dapp-kit's xBalances invalidations — only on confirmed success.
+      trackSwap(swapResponse);
+    },
+  },
+});
+
+// Track in-flight swaps anywhere in the app via the default mutationKey
+const swapsInFlight = useIsMutating({ mutationKey: ['swap'] });
+console.log({ swap, isError, error, swapsInFlight });
+```
+
+## Gotchas
+
+### Token list has duplicate addresses
+
+`getSupportedSolverTokens()` can return multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.blockchain_id}` — not `token.address` alone.
+
+### Balance display
+
+Balances come from `@sodax/wallet-sdk-react`, not from dapp-kit. See `wallet-connectivity.md` for `useXBalances`.
+
+## Types
+
+```typescript
+type CreateIntentParams = {
+  inputToken: string;
+  outputToken: string;
+  inputAmount: bigint;
+  minOutputAmount: bigint;
+  deadline: bigint;            // 0n = no deadline
+  allowPartialFill: boolean;
+  srcChain: SpokeChainId;
+  dstChain: SpokeChainId;
+  srcAddress: string;
+  dstAddress: string;
+  solver: Address;             // address(0) = any solver
+  data: Hex;
+};
+```

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

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

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

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