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

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

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

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

@@ -1,207 +0,0 @@
-# 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';
-  dstChainKey?: SpokeChainKey;
-  dstAddress?: string;
-};
-
-// Borrow / Withdraw / Repay follow the same shape with their respective `action` literal
-// (`'borrow'` / `'withdraw'` / `'repay'`) and the same `src*` / `dst*` field names.
-```
-
-## Notes
-
-- **Borrow/withdraw skip approval** — `useMMAllowance` returns `true` automatically for these actions.
-- **Health factor < 1.0** means liquidation risk.
-- All four operations (supply / borrow / withdraw / repay) accept optional `dstChainKey` / `dstAddress` for cross-chain delivery — omit both for same-chain. There are no `from*` / `to*` field variants on any action.
-- Mutations throw on SDK failure — use `mutateAsyncSafe` for `Result<T>` ergonomics without `try/catch`.

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

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

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