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

package/ai-exported/integration/recipes/backend-queries.md

@@ -0,0 +1,157 @@
+# Recipe: Backend Queries
+
+Read-only data hooks. No wallet connection required.
+
+**Depends on:** [setup.md](setup.md)
+
+## Hooks
+
+### Intents
+
+| Hook | Purpose |
+|------|---------|
+| `useBackendIntentByTxHash` | Intent by hub chain tx hash (polls 1s) |
+| `useBackendIntentByHash` | Intent by intent hash |
+| `useBackendUserIntents` | All intents for a user with date filtering |
+
+### Orderbook
+
+| Hook | Purpose |
+|------|---------|
+| `useBackendOrderbook` | Solver orderbook with pagination (cached 30s, no auto-refetch) |
+
+### Money Market
+
+| Hook | Purpose |
+|------|---------|
+| `useBackendMoneyMarketPosition` | User's money market position |
+| `useBackendMoneyMarketAsset` | Specific asset details |
+| `useBackendAllMoneyMarketAssets` | All money market assets |
+| `useBackendMoneyMarketAssetSuppliers` | Suppliers for an asset |
+| `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
+| `useBackendAllMoneyMarketBorrowers` | All borrowers |
+
+### Swap Submission
+
+| Hook | Purpose |
+|------|---------|
+| `useBackendSubmitSwapTx` | Submit swap tx to backend |
+| `useBackendSubmitSwapTxStatus` | Check submitted swap status |
+
+## Track Intent
+
+```tsx
+import { useBackendIntentByTxHash } from '@sodax/dapp-kit';
+
+function IntentTracker({ txHash }: { txHash: string }) {
+  const { data: intent, isLoading } = useBackendIntentByTxHash({
+    params: { txHash },
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  return <pre>{JSON.stringify(intent, null, 2)}</pre>;
+}
+```
+
+## User Intent History
+
+```tsx
+import { useBackendUserIntents } from '@sodax/dapp-kit';
+
+function IntentHistory({ userAddress }: { userAddress: `0x${string}` }) {
+  const { data: intents } = useBackendUserIntents({
+    params: {
+      userAddress,
+      startDate: Date.now() - 7 * 24 * 60 * 60 * 1000,
+      endDate: Date.now(),
+    },
+  });
+
+  return (
+    <div>
+      {intents?.items.map((intent, i) => (
+        <div key={i}>
+          <p>{intent.intentHash} -- {intent.open ? 'open' : 'closed'}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Orderbook
+
+```tsx
+import { useBackendOrderbook } from '@sodax/dapp-kit';
+
+function Orderbook() {
+  // `pagination` is nested under `params` per the canonical query-hook shape.
+  const { data: orderbook } = useBackendOrderbook({
+    params: { pagination: { offset: '0', limit: '20' } },
+  });
+  return <pre>{JSON.stringify(orderbook, null, 2)}</pre>;
+}
+```
+
+## Money Market Dashboard
+
+```tsx
+// @ai-snippets-skip — uses example field name supplyAPY not in MoneyMarketAsset type
+import { useBackendMoneyMarketPosition, useBackendAllMoneyMarketAssets } from '@sodax/dapp-kit';
+
+function MMDashboard({ userAddress }: { userAddress: string }) {
+  const { data: position } = useBackendMoneyMarketPosition({ params: { userAddress } });
+  const { data: assets } = useBackendAllMoneyMarketAssets({});
+
+  return (
+    <div>
+      {position && <pre>{JSON.stringify(position, null, 2)}</pre>}
+      {assets?.map((a, i) => <p key={i}>{a.symbol}: Supply {a.supplyAPY}%</p>)}
+    </div>
+  );
+}
+```
+
+## Custom Query Options
+
+All read hooks accept `queryOptions` to override defaults:
+
+```tsx
+// @ai-snippets-skip
+const { data } = useBackendIntentByTxHash({
+  params: { txHash },
+  queryOptions: { staleTime: 5000, refetchInterval: 2000, retry: 3 },
+});
+```
+
+## Submit a Swap Tx
+
+`useBackendSubmitSwapTx` is a mutation hook. Per-call config (e.g. backend base URL) flows through `mutate(vars)`; TanStack Query knobs flow through the optional `mutationOptions` slot:
+
+```tsx
+import { useBackendSubmitSwapTx } from '@sodax/dapp-kit';
+
+function SubmitButton({ swapPayload, baseURL }) {
+  const { mutateAsync: submitSwapTx, isPending } = useBackendSubmitSwapTx({
+    mutationOptions: { retry: 5 }, // overrides default retry: 3
+  });
+
+  const handleSubmit = async () => {
+    const response = await submitSwapTx({
+      request: swapPayload,
+      apiConfig: { baseURL }, // per-call backend override
+    });
+    console.log('Submitted:', response);
+  };
+
+  return <button onClick={handleSubmit} disabled={isPending}>Submit</button>;
+}
+```
+
+## Default Polling
+
+| Hook | Interval |
+|------|---------|
+| `useBackendIntentByTxHash` | 1s |
+| `useBackendOrderbook` | none (`staleTime: 30s`, no auto-refetch) |
+| Others | No auto-refresh |

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

@@ -0,0 +1,193 @@
+# Recipe: Bitcoin (Radfi)
+
+Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+### Session
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useRadfiAuth` | Mutation | Authenticate with Radfi via BIP322 signing |
+| `useRadfiSession` | Utility | Manage full session lifecycle (login, refresh, auto-refresh) |
+| `useTradingWallet` | Utility | Get trading wallet address from persisted session (synchronous) |
+
+### Balance
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useBitcoinBalance` | Query | BTC balance for any address (sums UTXOs from mempool.space) |
+| `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API (confirmed + pending) |
+
+### Operations
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useFundTradingWallet` | Mutation | Send BTC from personal wallet to trading wallet |
+| `useRadfiWithdraw` | Mutation | Withdraw BTC from trading wallet to personal wallet |
+| `useExpiredUtxos` | Query | Fetch UTXOs that need renewal (polls every 60s) |
+| `useRenewUtxos` | Mutation | Renew expired UTXOs in trading wallet |
+
+## Session Flow
+
+Radfi requires authentication before any trading operation. The typical flow:
+
+```tsx
+import { useRadfiSession } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function BitcoinAuth() {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
+  const { isAuthed, tradingAddress, login, isLoginPending } = useRadfiSession(walletProvider);
+
+  if (isAuthed) {
+    return <p>Authenticated. Trading wallet: {tradingAddress}</p>;
+  }
+
+  return (
+    <button onClick={login} disabled={isLoginPending}>
+      {isLoginPending ? 'Signing...' : 'Login to Radfi'}
+    </button>
+  );
+}
+```
+
+`useRadfiSession` handles the full lifecycle:
+- On mount: refreshes token to validate existing session
+- Every 5 min: auto-refreshes access token
+- If refresh fails: clears session, sets `isAuthed = false`
+- Session persisted in localStorage (keyed by wallet address)
+
+## Check Balances
+
+```tsx
+import { useBitcoinBalance, useTradingWalletBalance, useTradingWallet } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function BitcoinBalances({ walletAddress }: { walletAddress: string }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
+  const { tradingAddress } = useTradingWallet(walletAddress);
+
+  // Personal wallet balance (from mempool.space)
+  const { data: personalBalance } = useBitcoinBalance({
+    params: { address: walletAddress },
+  });
+
+  // Trading wallet balance (from Radfi API). `RadfiWalletBalance` fields:
+  // `btcSatoshi`, `pendingSatoshi`, `externalPendingSatoshi`, `totalUtxos`.
+  const { data: tradingBalance } = useTradingWalletBalance({
+    params: { walletProvider, tradingAddress },
+  });
+
+  return (
+    <div>
+      <p>Personal: {personalBalance?.toString() ?? '...'} sats</p>
+      <p>Trading: {tradingBalance?.btcSatoshi?.toString() ?? '...'} sats</p>
+    </div>
+  );
+}
+```
+
+## Fund Trading Wallet
+
+```tsx
+import { useFundTradingWallet } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function FundButton() {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
+  const { mutateAsyncSafe: fundWallet, isPending } = useFundTradingWallet();
+
+  const handleFund = async () => {
+    if (!walletProvider) return;
+    const result = await fundWallet({ amount: 100_000n, walletProvider }); // 100,000 satoshis
+    if (result.ok) console.log('Funded:', result.value);
+    else console.error('Fund failed:', result.error);
+  };
+
+  return (
+    <button onClick={handleFund} disabled={isPending || !walletProvider}>
+      {isPending ? 'Funding...' : 'Fund Trading Wallet'}
+    </button>
+  );
+}
+```
+
+## Withdraw from Trading Wallet
+
+```tsx
+import { useRadfiWithdraw } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function WithdrawButton({ withdrawTo }: { withdrawTo: string }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
+  const { mutateAsync: withdraw, isPending } = useRadfiWithdraw();
+
+  const handleWithdraw = async () => {
+    if (!walletProvider) return;
+    const result = await withdraw({
+      amount: '10000',
+      tokenId: '0:0',
+      withdrawTo, // user's personal BTC address
+      walletProvider,
+    });
+    console.log('Withdrawn:', result.txId, 'Fee:', result.fee);
+  };
+
+  return (
+    <button onClick={handleWithdraw} disabled={isPending || !walletProvider}>
+      {isPending ? 'Withdrawing...' : 'Withdraw'}
+    </button>
+  );
+}
+```
+
+## Manage Expired UTXOs
+
+UTXOs in the trading wallet can expire. Check and renew them:
+
+```tsx
+import { useExpiredUtxos, useRenewUtxos } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function UtxoManager({ tradingAddress }: { tradingAddress: string }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
+  const { data: expiredUtxos } = useExpiredUtxos({
+    params: { walletProvider, tradingAddress },
+  });
+  const { mutateAsync: renewUtxos, isPending } = useRenewUtxos();
+
+  if (!expiredUtxos?.length) return <p>No expired UTXOs</p>;
+
+  const handleRenew = async () => {
+    if (!walletProvider) return;
+    const txIdVouts = expiredUtxos.map((u) => u.txidVout);
+    const txId = await renewUtxos({ txIdVouts, walletProvider });
+    console.log('Renewed:', txId);
+  };
+
+  return (
+    <div>
+      <p>{expiredUtxos.length} expired UTXOs</p>
+      <button onClick={handleRenew} disabled={isPending || !walletProvider}>
+        {isPending ? 'Renewing...' : 'Renew UTXOs'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Notes
+
+- **Authentication required** before any trading operation. `useRadfiSession` manages this automatically.
+- **Trading wallet** is created during first authentication — not a separate step.
+- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Radfi session from localStorage.
+- **PSBT signing flow**: withdraw and renew operations build an unsigned PSBT server-side, user signs it locally, then submits back for co-signing and broadcast.
+- **Session tokens** are stored in localStorage keyed by wallet address. They're for API rate-limiting, not for accessing user assets.

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

@@ -0,0 +1,174 @@
+# 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
+};
+```