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

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

@@ -0,0 +1,206 @@
+# Recipe: Money Market
+
+Cross-chain lending (supply) and borrowing.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useSupply` | Mutation | Supply tokens as collateral |
+| `useBorrow` | Mutation | Borrow against collateral |
+| `useWithdraw` | Mutation | Withdraw supplied tokens |
+| `useRepay` | Mutation | Repay borrowed tokens |
+| `useMMAllowance` | Query | Check approval (auto-skips for borrow/withdraw) |
+| `useMMApprove` | Mutation | Approve tokens |
+| `useReservesData` | Query | All reserve data |
+| `useReservesHumanized` | Query | Reserves in human-readable (decimal-normalized) format |
+| `useReservesList` | Query | List of reserve asset addresses |
+| `useReservesUsdFormat` | Query | Reserves with USD values |
+| `useUserFormattedSummary` | Query | User portfolio summary (health factor, collateral, debt) |
+| `useUserReservesData` | Query | User reserve positions |
+| `useAToken` | Query | aToken metadata |
+| `useATokensBalances` | Query | aToken balances |
+
+## Hook shape
+
+All mutation hooks follow the **zero-domain-param** policy — the hook itself takes only an optional `mutationOptions` slot; ALL domain inputs (`params`, `walletProvider`, etc.) flow through `mutate(vars)`:
+
+```ts
+// @ai-snippets-skip
+const { mutateAsync: supply } = useSupply();
+await supply({ params: { srcChainKey, srcAddress, token, amount, action: 'supply' }, walletProvider });
+```
+
+On SDK failure, `mutationFn` throws — `mutation.error` and `onError` engage natively. Use `mutateAsyncSafe` to get `Promise<Result<T>>` that never rejects.
+
+## Display Reserves
+
+```tsx
+import { useReservesData } from '@sodax/dapp-kit';
+
+function ReservesList() {
+  const { data, isLoading } = useReservesData();
+  if (isLoading || !data) return <div>Loading...</div>;
+  const [reserves] = data;
+  return (
+    <table>
+      <thead><tr><th>Asset</th><th>Supply Rate</th><th>Borrow Rate</th></tr></thead>
+      <tbody>
+        {reserves.map((r) => (
+          <tr key={r.underlyingAsset}>
+            <td>{r.symbol}</td>
+            <td>{r.liquidityRate.toString()}</td>
+            <td>{r.variableBorrowRate.toString()}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+```
+
+## User Position
+
+```tsx
+import { useUserFormattedSummary } from '@sodax/dapp-kit';
+import type { SpokeChainKey } from '@sodax/sdk';
+
+function UserPosition({ spokeChainKey, userAddress }: { spokeChainKey: SpokeChainKey; userAddress: string }) {
+  const { data: summary } = useUserFormattedSummary({ params: { spokeChainKey, userAddress } });
+  if (!summary) return null;
+  return (
+    <div>
+      <p>Collateral: ${summary.totalCollateralUSD}</p>
+      <p>Debt: ${summary.totalBorrowsUSD}</p>
+      <p>Health Factor: {summary.healthFactor}</p>
+    </div>
+  );
+}
+```
+
+## Check Allowance + Approve
+
+```tsx
+import { useMMAllowance, useMMApprove } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys, type MoneyMarketSupplyParams } from '@sodax/sdk';
+
+function MMApproval({ params }: { params: MoneyMarketSupplyParams<typeof ChainKeys.BASE_MAINNET> }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
+  // useMMAllowance wraps the request under params.payload.
+  // Auto-returns true for borrow/withdraw — no unnecessary RPC calls.
+  const { data: isApproved } = useMMAllowance({ params: { payload: params } });
+  const { mutateAsync: approve, isPending } = useMMApprove();
+
+  if (isApproved) return null;
+  return (
+    <button
+      onClick={() => walletProvider && approve({ params, walletProvider })}
+      disabled={isPending || !walletProvider}
+    >
+      {isPending ? 'Approving...' : 'Approve'}
+    </button>
+  );
+}
+```
+
+## Supply
+
+```tsx
+import { useSupply } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function SupplyButton({ srcAddress }: { srcAddress: string }) {
+  const chainKey = ChainKeys.BASE_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+  const { mutateAsync: supply, isPending } = useSupply();
+
+  const handleSupply = async () => {
+    if (!walletProvider) return;
+    try {
+      const txHashPair = await supply({
+        params: { srcChainKey: chainKey, srcAddress, token: '0x...', amount: 1_000_000n, action: 'supply' },
+        walletProvider,
+      });
+      console.log('Supplied (spoke, hub):', txHashPair);
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <button onClick={handleSupply} disabled={isPending || !walletProvider}>
+      {isPending ? 'Supplying...' : 'Supply'}
+    </button>
+  );
+}
+```
+
+## Borrow / Withdraw / Repay
+
+```tsx
+import { useBorrow, useWithdraw, useRepay } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function MMActions({ srcAddress }: { srcAddress: `0x${string}` }) {
+  const chainKey = ChainKeys.BASE_MAINNET;
+  const walletProvider = useWalletProvider({ xChainId: chainKey });
+
+  const { mutateAsync: borrow } = useBorrow();
+  const { mutateAsync: withdraw } = useWithdraw();
+  const { mutateAsync: repay } = useRepay();
+
+  const handleBorrow = async () => {
+    if (!walletProvider) return;
+    await borrow({
+      params: { srcChainKey: chainKey, srcAddress, token: '0x0000000000000000000000000000000000000000', amount: 500_000n, action: 'borrow' },
+      walletProvider,
+    });
+  };
+
+  const handleWithdraw = async () => {
+    if (!walletProvider) return;
+    await withdraw({
+      params: { srcChainKey: chainKey, srcAddress, token: '0x0000000000000000000000000000000000000000', amount: 1_000_000n, action: 'withdraw' },
+      walletProvider,
+    });
+  };
+
+  const handleRepay = async () => {
+    if (!walletProvider) return;
+    await repay({
+      params: { srcChainKey: chainKey, srcAddress, token: '0x0000000000000000000000000000000000000000', amount: 500_000n, action: 'repay' },
+      walletProvider,
+    });
+  };
+
+  return null;
+}
+```
+
+## Types
+
+```typescript
+type MoneyMarketSupplyParams<K extends SpokeChainKey = SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: string;
+  token: string;
+  amount: bigint;
+  action: 'supply';
+  toChainId?: SpokeChainKey;
+  toAddress?: string;
+};
+
+// Borrow / Withdraw / Repay follow the same shape with their respective `action` literal.
+```
+
+## Notes
+
+- **Borrow/withdraw skip approval** — `useMMAllowance` returns `true` automatically for these actions.
+- **Health factor < 1.0** means liquidation risk.
+- All operations support optional `toChainId` / `toAddress` (and `fromChainId` / `fromAddress` on borrow) for cross-chain delivery.
+- Mutations throw on SDK failure — use `mutateAsyncSafe` for `Result<T>` ergonomics without `try/catch`.

package/ai-exported/integration/recipes/mutation-error-handling.md

@@ -0,0 +1,118 @@
+# Recipe: Mutation error handling
+
+Every dapp-kit mutation hook returns three ways to invoke the mutation. Pick by call shape — they all share the same React Query state under the hood (`isError`, `error`, `data`, devtools all work).
+
+## The three call shapes
+
+| Method | Returns | Rejects on `!ok`? | When to use |
+|---|---|---|---|
+| `mutate(vars)` | `void` (fire-and-forget) | Never | Button-click handlers where you read `isPending` / `isError` / `error` from the hook in render. |
+| `mutateAsync(vars)` | `Promise<TData>` | **Yes** | Imperative chains where you only need the success value. **MUST be wrapped in `try/catch`** or you'll leak unhandled rejections on user-rejects. |
+| `mutateAsyncSafe(vars)` | `Promise<Result<TData>>` | **Never** | Imperative chains where you want explicit branching without exception flow. |
+
+`mutateAsyncSafe` is the **recommended default** for sequenced flows like `if (!hasAllowance) await approve(); await action();` — the user-reject case is the modal failure mode in dApps, not exceptional, and `Result<T>`-style branching reads cleaner than exception flow.
+
+## fire-and-forget — `mutate`
+
+Best for buttons that just kick off a mutation and let render reflect state.
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+
+function SwapButton({ params, walletProvider }) {
+  const m = useSwap();
+
+  return (
+    <>
+      <button onClick={() => m.mutate({ params, walletProvider })} disabled={m.isPending}>
+        {m.isPending ? 'Swapping...' : 'Swap'}
+      </button>
+      {m.isError && <p>Error: {m.error.message}</p>}
+      {m.isSuccess && <p>Done!</p>}
+    </>
+  );
+}
+```
+
+## throws — `mutateAsync`
+
+Use when you want exception flow control. **Always wrap in `try/catch`.**
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+
+function MyFlow({ params, walletProvider }) {
+  const { mutateAsync: swap } = useSwap();
+
+  const handleClick = async () => {
+    try {
+      const result = await swap({ params, walletProvider });
+      navigate('/done');
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : 'Swap failed');
+    }
+  };
+}
+```
+
+If you forget `try/catch`, an unhandled rejection lands in the global handler — most apps treat that as a fatal error.
+
+## safe — `mutateAsyncSafe`
+
+Recommended. Branches on `Result<T>`. Never rejects.
+
+```tsx
+// @ai-snippets-skip — Intent.intentHash placeholder
+import { useSwap } from '@sodax/dapp-kit';
+
+function MyFlow({ params, walletProvider }) {
+  const { mutateAsyncSafe: swap } = useSwap();
+
+  const handleClick = async () => {
+    const result = await swap({ params, walletProvider });
+    if (!result.ok) {
+      toast.error(result.error instanceof Error ? result.error.message : 'Swap failed');
+      return;
+    }
+    const { intent, intentDeliveryInfo } = result.value;
+    navigate(`/done?intent=${intent.intentHash}`);
+  };
+}
+```
+
+Pairs well with sequenced flows:
+
+```tsx
+// @ai-snippets-skip — illustrative sequenced-flow pattern; `approve`, `swap`, `hasAllowance`
+// are assumed from enclosing context (see recipes/swap.md for the full flow).
+const handleSwap = async () => {
+  if (!hasAllowance) {
+    const a = await approve({ params, walletProvider });
+    if (!a.ok) { toast.error('Approve failed'); return; }
+  }
+  const r = await swap({ params, walletProvider });
+  if (!r.ok) { toast.error('Swap failed'); return; }
+  // success
+};
+```
+
+## Why `mutationFn` throws on SDK `!ok`
+
+Inside the hook, `mutationFn` calls `unwrapResult` on the SDK's `Result<T>`:
+
+- On `Result.ok === true` → returns the unwrapped `value` (TData).
+- On `Result.ok === false` → throws `result.error`.
+
+Why throw? Because React Query's error model (`isError`, `error`, `onError`, `retry`, `throwOnError`, devtools) keys off `mutationFn` throwing. With `Result<T>` returned as success, none of those engaged on SDK failure. Throwing makes them work out of the box.
+
+The `mutateAsyncSafe` shim re-packs the throw back into a `Result<T>` so you can have it both ways: React Query's native error machinery in render + `Result<T>` ergonomics imperatively.
+
+## Common pitfall — never call `useMutation` directly
+
+Every dapp-kit mutation hook calls `useSafeMutation` (a thin wrapper). When you write your own wrapper hooks around dapp-kit mutations, do the same — call dapp-kit's hooks, not React Query's `useMutation`. Otherwise consumers won't get `mutateAsyncSafe`.
+
+## Cross-references
+
+- [`observability.md`](observability.md) — global `onMutationError` for logging/Sentry.
+- [`invalidations.md`](invalidations.md) — composing your own `onSuccess` after dapp-kit's hook-owned invalidations.
+- [`../architecture.md`](../architecture.md) — full design rationale for `useSafeMutation` / `unwrapResult`.

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

@@ -0,0 +1,93 @@
+# Recipe: Observability — global mutation error hook
+
+`createSodaxQueryClient` returns a `QueryClient` pre-wired with a `MutationCache.onError` hook that gives you a single observability seam for every mutation failure across the app. Optional opt-in — if you construct your own `QueryClient`, nothing changes.
+
+## Default behavior
+
+Logs every mutation failure to console as `[sodax] Mutation error: <error>`:
+
+```tsx
+import { createSodaxQueryClient } from '@sodax/dapp-kit';
+
+const queryClient = createSodaxQueryClient();
+```
+
+## Wire to your own logger
+
+Sentry, Datadog, Pino — any error sink:
+
+```tsx
+// @ai-snippets-skip — Sentry 3rd-party import
+import { createSodaxQueryClient } from '@sodax/dapp-kit';
+import * as Sentry from '@sentry/react';
+
+const queryClient = createSodaxQueryClient({
+  onMutationError: (error) => Sentry.captureException(error),
+});
+```
+
+## Disable the default
+
+If you wire per-hook `onError` callbacks plus a React error boundary, you may not want a duplicated console log:
+
+```tsx
+import { createSodaxQueryClient } from '@sodax/dapp-kit';
+
+const queryClient = createSodaxQueryClient({ onMutationError: () => {} });
+console.log(queryClient);
+```
+
+## Per-mutation opt-out — `meta.silent`
+
+When a single mutation handles its error locally (e.g. its own toast in `onError`) and you don't want a duplicate `[sodax] Mutation error:` log, pass `meta: { silent: true }` on that mutation:
+
+```tsx
+import { useSwap } from '@sodax/dapp-kit';
+
+const swap = useSwap({
+  mutationOptions: {
+    meta: { silent: true },
+    onError: (e) => toast.error(e.message),
+  },
+});
+console.log(swap);
+```
+
+The global `onMutationError` skips this mutation; everything else still fires through it.
+
+## Bring your own `MutationCache`
+
+If you pass `config.mutationCache`, the factory keeps your cache instance (preserving any `onError` you set on it) and *additionally* subscribes to its event stream to dispatch `onMutationError`. Both handlers fire — neither replaces the other. `meta.silent` is honored in both branches.
+
+```tsx
+import { MutationCache } from '@tanstack/react-query';
+import { createSodaxQueryClient } from '@sodax/dapp-kit';
+
+const myCache = new MutationCache({ onError: myOwnErrorHandler });
+const queryClient = createSodaxQueryClient({ config: { mutationCache: myCache } });
+// myOwnErrorHandler runs; sodax onMutationError ALSO runs (unless meta.silent).
+```
+
+## Important: this is observability, not prevention
+
+The global hook fires for **every** mutation failure regardless of:
+- Whether the consumer caught the rejection with `try/catch`
+- Whether the consumer branched on `mutateAsyncSafe`'s `Result.ok`
+- Whether the consumer registered a per-hook `onError`
+
+It does **not** detect "unhandled" rejections. If you want to prevent unhandled rejections at the call site, use `mutateAsyncSafe` (see [`mutation-error-handling.md`](mutation-error-handling.md)).
+
+## When to use
+
+- **Sentry/Datadog integration** — single point of capture for all SDK mutation failures.
+- **Global error toast** — render-side error toast on top of per-hook handling. Simpler than per-hook `onError`.
+- **Debug console mode** — keep the default during local dev for quick visibility.
+
+## When NOT to use
+
+- **You only handle errors per-hook.** The global hook adds noise (duplicate logs). Either disable it entirely or use `meta.silent`.
+
+## Cross-references
+
+- [`mutation-error-handling.md`](mutation-error-handling.md) — call-site error handling (preventing unhandled rejections).
+- [`../architecture.md`](../architecture.md) — full design notes on `createSodaxQueryClient`.

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

@@ -0,0 +1,144 @@
+# Recipe: Setup
+
+Install and wire `@sodax/dapp-kit` into a React project.
+
+**Depends on:** None
+
+## Install
+
+```bash
+# Required
+pnpm add @sodax/dapp-kit @tanstack/react-query
+
+# Optional (only if you want built-in wallet connectivity hooks + providers)
+pnpm add @sodax/wallet-sdk-react
+```
+
+## Wire Providers
+
+RPC URLs are injected via `config.chains` — each chain entry takes `{ rpcUrl: string }`.
+
+```tsx
+// providers.tsx
+import { QueryClientProvider } from '@tanstack/react-query';
+import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
+import { ChainKeys, type DeepPartial, type SodaxConfig } from '@sodax/sdk';
+
+const queryClient = createSodaxQueryClient();
+
+const sodaxConfig: DeepPartial<SodaxConfig> = {
+  chains: {
+    [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
+    [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
+    [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
+    [ChainKeys.POLYGON_MAINNET]: { rpcUrl: 'https://polygon-rpc.com' },
+    // Add chains your dApp needs
+  },
+};
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <SodaxProvider config={sodaxConfig}>
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    </SodaxProvider>
+  );
+}
+```
+
+### Optional: Add Wallet Provider
+
+If you want to use `@sodax/wallet-sdk-react` for wallet connectivity, wrap `SodaxWalletProvider` inside `QueryClientProvider`:
+
+```tsx
+// @ai-snippets-skip
+import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
+
+const walletConfig: SodaxWalletConfig = {
+  EVM: {
+    chains: {
+      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
+      [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
+    },
+  },
+};
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <SodaxProvider config={sodaxConfig}>
+      <QueryClientProvider client={queryClient}>
+        <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
+      </QueryClientProvider>
+    </SodaxProvider>
+  );
+}
+```
+
+## `createSodaxQueryClient` (optional)
+
+`createSodaxQueryClient` returns a `QueryClient` pre-wired with a `MutationCache.onError` hook for global mutation observability. Use it instead of `new QueryClient()`:
+
+```tsx
+// @ai-snippets-skip — illustrative — multiple createSodaxQueryClient variations
+import { createSodaxQueryClient } from '@sodax/dapp-kit';
+
+// Default: logs every mutation failure as `[sodax] Mutation error: <error>`
+const queryClient = createSodaxQueryClient();
+
+// Wire to your own logger
+const queryClient = createSodaxQueryClient({
+  onMutationError: (e) => Sentry.captureException(e),
+});
+
+// Silence a specific mutation locally via meta.silent
+const swap = useSwap({
+  mutationOptions: { meta: { silent: true }, onError: (e) => toast.error(e.message) },
+});
+```
+
+## Initialize SDK (Optional)
+
+For dynamic config (latest tokens/chains from backend API):
+
+```tsx
+import { useEffect } from 'react';
+import { useSodaxContext } from '@sodax/dapp-kit';
+
+export function useInitializeSodax() {
+  const { sodax } = useSodaxContext();
+
+  useEffect(() => {
+    sodax.initialize().then((result) => {
+      if (!result.ok) console.error('Failed to initialize Sodax:', result.error);
+    });
+  }, [sodax]);
+}
+```
+
+## Chain Key Constants
+
+```tsx
+import { ChainKeys } from '@sodax/sdk';
+
+// Examples (full list lives in @sodax/sdk's reference):
+ChainKeys.SONIC_MAINNET;       // 'sonic'           (hub)
+ChainKeys.ARBITRUM_MAINNET;    // '0xa4b1.arbitrum'
+ChainKeys.BASE_MAINNET;        // '0x2105.base'
+ChainKeys.BSC_MAINNET;         // '0x38.bsc'
+ChainKeys.ETHEREUM_MAINNET;    // '0x1.ethereum'
+ChainKeys.POLYGON_MAINNET;     // '0x89.polygon'
+ChainKeys.OPTIMISM_MAINNET;    // '0xa.optimism'
+ChainKeys.AVALANCHE_MAINNET;   // '0xa86a.avax'
+ChainKeys.SUI_MAINNET;         // 'sui'
+ChainKeys.STELLAR_MAINNET;     // 'stellar'
+ChainKeys.SOLANA_MAINNET;      // 'solana'
+ChainKeys.ICON_MAINNET;        // '0x1.icon'
+ChainKeys.INJECTIVE_MAINNET;   // 'injective-1'
+ChainKeys.NEAR_MAINNET;        // 'near'
+ChainKeys.STACKS_MAINNET;      // 'stacks'
+ChainKeys.BITCOIN_MAINNET;     // 'bitcoin'
+// HyperEVM, Lightlink, Redbelly, Kaia also available.
+```
+
+**v1 → v2:** the legacy `*_MAINNET_CHAIN_ID` constants (e.g. `BSC_MAINNET_CHAIN_ID`) are gone. Use `ChainKeys.X_MAINNET` namespace access.