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

package/ai-exported/migration/features/staking.md

@@ -1,109 +0,0 @@
-# Staking migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/staking.md`](../../integration/features/staking.md).
-
-## TL;DR
-
-> Cross-cutting conventions (drop `spokeProvider`, single-object hook init, `mutate(vars)` for domain inputs, `mutateAsyncSafe` ergonomics) — see [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) and [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md). Feature-specific deltas below:
-
-1. **All five mutations** (`useStake`, `useUnstake`, `useInstantUnstake`, `useClaim`, `useCancelUnstake`) drop `spokeProvider` from hook init; `walletProvider` flows through `mutate(vars)`.
-2. **Three approve hooks** (`useStakeApprove`, `useUnstakeApprove`, `useInstantUnstakeApprove`) — same shape change. Each approves a different token (SODA for stake; xSODA for unstake/instant).
-3. **`useStakeRatio` return changed.** v2: `Result<[xSodaAmount, previewDepositAmount]>` — a 2-tuple. v1 returned a single bigint.
-4. **`useUnstakingInfo` return shape changed.** v2: `Result<UnstakingInfo>` where `UnstakingInfo = { userUnstakeSodaRequests: UserUnstakeInfo[], totalUnstaking: bigint }`. v1 may have returned just the array — v2 wraps it in an object.
-5. **Action params gained `srcChainKey` + `srcAddress`.** Same SDK-leakage as MM.
-
-## Per-method delta
-
-### `useStake` (template for all five)
-
-```diff
-  function StakeButton({ amount, srcAddress }) {
--   const stake = useStake(spokeProvider);
-+   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
-+   const { mutateAsyncSafe: stake } = useStake();
-
-    const handleStake = async () => {
-+     if (!walletProvider) return;
--     await stake.mutateAsync({ params: { amount, minReceive, action: 'stake' } });
-+     const result = await stake({
-+       params: {
-+         srcChainKey: ChainKeys.BASE_MAINNET,
-+         srcAddress,
-+         amount,
-+         minReceive,
-+         action: 'stake',
-+       },
-+       walletProvider,
-+     });
-+     if (!result.ok) return;
-+     const { srcChainTxHash, dstChainTxHash } = result.value;
-    };
-  }
-```
-
-`useUnstake` / `useInstantUnstake` / `useClaim` / `useCancelUnstake` follow the same pattern with their respective params types.
-
-### Approve hooks
-
-Each of stake / unstake / instantUnstake has its OWN approve hook (different tokens):
-
-```diff
-- const { approve, isLoading } = useStakeApprove(spokeProvider);
-- await approve({ amount, action: 'stake' });
-+ const { mutateAsync: approve, isPending } = useStakeApprove();
-+ await approve({ params: { srcChainKey, srcAddress, amount, action: 'stake' }, walletProvider });
-```
-
-`useUnstakeApprove`, `useInstantUnstakeApprove` — same pattern.
-
-### `useStakeRatio` — return type change
-
-```diff
-- const { data: ratio } = useStakeRatio(amount);
-- if (ratio) {
--   const xSodaAmount = ratio;   // v1 returned single bigint
--   /* ... */
-- }
-+ const { data: ratio } = useStakeRatio({ params: { amount } });
-+ if (ratio?.ok) {
-+   const [xSodaAmount, previewDepositAmount] = ratio.value;   // v2 returns tuple
-+ }
-```
-
-### `useUnstakingInfo` — return shape change
-
-```diff
-- const { data: requests } = useUnstakingInfo(spokeProvider);
-- requests?.map((r) => /* ... */);   // v1 was an array
-+ const { data: result } = useUnstakingInfo({ params: { srcAddress, srcChainKey } });
-+ if (result?.ok) {
-+   const { userUnstakeSodaRequests, totalUnstaking } = result.value;   // v2 is object
-+   userUnstakeSodaRequests.map((r) => /* ... */);
-+ }
-```
-
-### `useUnstakingInfoWithPenalty`
-
-New in v2 — wraps `useUnstakingInfo`'s base shape with a per-request penalty annotation. Skip this section if your v1 codebase didn't compute penalty client-side.
-
-```ts
-// @ai-snippets-skip
-const { data: result } = useUnstakingInfoWithPenalty({ params: { srcAddress, srcChainKey } });
-if (result?.ok) {
-  const { requestsWithPenalty } = result.value;   // each adds penalty, penaltyPercentage, claimableAmount
-}
-```
-
-## Pitfalls
-
-1. **`useStakeRatio` returns a tuple, not a single bigint.** v1 was simpler; v2 returns `[xSodaAmount, previewDepositAmount]`. Adjust render code.
-2. **`useStakingInfo` is unwrapped (not Result), but `useUnstakingInfo` IS Result-wrapped.** Asymmetric — check the integration docs per hook.
-3. **`useUnstakingInfoWithPenalty` returns an object with `requestsWithPenalty` array embedded** — don't `.value.map(...)`, use `.value.requestsWithPenalty.map(...)`.
-4. **Unstake has a waiting period.** Display via `useStakingConfig().unstakingPeriod`. Shows up in v1 too, but the read shape may have changed.
-5. **Instant unstake bypasses the waiting period but pays slippage.** Use `useInstantUnstakeRatio` to preview; set `minAmount` in params for slippage protection.
-
-## Cross-references
-
-- [`../../integration/features/staking.md`](../../integration/features/staking.md) — v2 reference.
-- [`../../integration/recipes/staking.md`](../../integration/recipes/staking.md) — full v2 worked example.
-- [`../../../../sdk/ai-exported/migration/features/staking.md`](../../../../sdk/ai-exported/migration/features/staking.md) — underlying SDK staking migration.

package/ai-exported/migration/features/swap.md

@@ -1,118 +0,0 @@
-# Swap migration — v1 → v2 (dapp-kit)
-
-Pair: [`../../integration/features/swap.md`](../../integration/features/swap.md).
-
-## TL;DR
-
-> Cross-cutting conventions (drop `spokeProvider`, single-object hook init, `mutate(vars)` for domain inputs, `mutateAsyncSafe` ergonomics) — see [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) and [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md). Feature-specific deltas below:
-
-1. **Drop `spokeProvider` from `useSwap` and `useSwapApprove` hook init.** Pass `walletProvider` (from `useWalletProvider({ xChainId: chainKey })`) into `mutate(vars)`.
-2. **`useSwapAllowance({ params: { payload, srcChainKey, walletProvider } })`** — query inputs all nest under `params` (no top-level `spokeProvider` or `walletProvider`); the SDK request goes under `params.payload`.
-3. **Approve hook return shape changed.** `{ approve, isLoading } = useSwapApprove(...)` → `{ mutateAsync: approve, isPending } = useSwapApprove()`.
-4. **`mutationFn` throws on SDK `!ok`.** Either wrap `mutateAsync` in `try/catch` or use `mutateAsyncSafe` for `Result<T>` branching.
-5. **Field on `Intent` read shape kept its name.** `Intent.srcChain` / `Intent.dstChain` are still `IntentRelayChainId` (bigint) — distinct from request-side `srcChainKey` / `dstChainKey` on action params.
-6. **`useStatus({ params: { intentTxHash } })` — single-object query shape.** v1's positional version is gone. Key was renamed `intentHash → intentTxHash`. Return is `Result<SolverIntentStatusResponse, SolverErrorResponse> | undefined` — branch on `data?.ok` before reading status fields.
-
-## Per-method delta
-
-### `useSwap` — execute swap
-
-```diff
-  function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
--   const swap = useSwap(spokeProvider);
-+   const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-+   const { mutateAsyncSafe: swap, isPending } = useSwap();
-
-    const handleSwap = async () => {
-+     if (!walletProvider) return;
--     const result = await swap.mutateAsync({ params: intentParams });
--     if (result.ok) {
--       const { intent, intentDeliveryInfo } = result.value;
--       /* ... */
--     } else {
--       toast.error(result.error.message);
--     }
-+     const result = await swap({ params: intentParams, walletProvider });
-+     if (!result.ok) {
-+       toast.error(result.error instanceof Error ? result.error.message : 'Swap failed');
-+       return;
-+     }
-+     const { intent, intentDeliveryInfo } = result.value;
-+     /* ... */
-    };
-  }
-```
-
-### `useSwapApprove` — return shape
-
-```diff
-- const { approve, isLoading, error } = useSwapApprove(spokeProvider);
-- await approve(intentParams);
-+ const { mutateAsync: approve, isPending, error } = useSwapApprove();
-+ await approve({ params: intentParams, walletProvider });
-```
-
-`isLoading` → `isPending` (React Query 5 convention).
-
-### `useSwapAllowance` — payload + srcChainKey + walletProvider all under `params`
-
-```diff
-- const { data: allowanceResult } = useSwapAllowance({ params: intentParams, spokeProvider });
-+ const { data: isApproved } = useSwapAllowance({
-+   params: { payload: intentParams, srcChainKey: ChainKeys.BSC_MAINNET, walletProvider },
-+ });
-+ // `data` is `boolean | undefined` (already unwrapped); no `.ok` branch needed.
-```
-
-### `useStatus` — single-object shape + param renamed `intentHash → intentTxHash`
-
-```diff
-- const { data: status } = useStatus(intentHash);
-+ const { data: status } = useStatus({ params: { intentTxHash } });
-+ // `data` is `Result<SolverIntentStatusResponse, SolverErrorResponse> | undefined` —
-+ // branch on `data?.ok` before reading `data.value.<fields>`.
-```
-
-### `useQuote` — single-object shape + SDK request nested under `params.payload`
-
-```diff
-- const { data: quote } = useQuote({
--   token_src: SRC_TOKEN,
--   token_dst: DST_TOKEN,
--   token_src_blockchain_id: BSC_MAINNET_CHAIN_ID,
--   token_dst_blockchain_id: ARBITRUM_MAINNET_CHAIN_ID,
--   amount,
--   quote_type: 'exact_input',
-- });
-+ const { data: quote } = useQuote({
-+   params: {
-+     payload: {
-+       token_src: SRC_TOKEN,
-+       token_dst: DST_TOKEN,
-+       token_src_blockchain_id: ChainKeys.BSC_MAINNET,
-+       token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
-+       amount,
-+       quote_type: 'exact_input',
-+     },
-+   },
-+ });
-```
-
-`SolverIntentQuoteRequest` shape unchanged. Two v2 changes: SDK request is nested under `params.payload` (not directly under `params`); constants renamed (`*_MAINNET_CHAIN_ID` → `ChainKeys.X_MAINNET`).
-
-### `useCreateLimitOrder` / `useCancelLimitOrder` / `useCancelSwap`
-
-Same shape changes as `useSwap` — drop `spokeProvider`, move domain inputs to `mutate(vars)`.
-
-## Pitfalls
-
-1. **`Intent.srcChain` / `Intent.dstChain` look like they should rename.** They didn't. Those are read-shape `IntentRelayChainId` (bigint), distinct from request-side `srcChainKey` / `dstChainKey`. Don't grep-replace.
-2. **`useStatus` polling default.** v2 polls every 3 s unconditionally once `intentTxHash` is supplied (it does not auto-stop on terminal states — your UI should disable rendering when no longer needed, or override `queryOptions.refetchInterval: false`). Port any v1 custom polling to `queryOptions.refetchInterval`.
-3. **`useQuote` data is `Result<T>`** — branch on `data?.ok` before reading `data.value.quoted_amount`.
-
-## Cross-references
-
-- [`../../integration/features/swap.md`](../../integration/features/swap.md) — v2 reference.
-- [`../../integration/recipes/swap.md`](../../integration/recipes/swap.md) — full v2 worked example.
-- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md), [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) — cross-cutting deltas.
-- [`../../../../sdk/ai-exported/migration/features/swap.md`](../../../../sdk/ai-exported/migration/features/swap.md) — underlying SDK swap migration.

package/ai-exported/migration/recipes.md

@@ -1,188 +0,0 @@
-# Migration recipes — `@sodax/dapp-kit` v1 → v2
-
-Codemods, adapters, and incremental migration patterns. Use these when full conversion in one pass isn't realistic or when you want to mechanize the boring parts.
-
-## Codemod 1: chain-id constants → ChainKeys
-
-```bash
-# From your consumer's repo root:
-find src -type f \( -name '*.ts' -o -name '*.tsx' \) | xargs sed -i '' -E 's/\b([A-Z_]+)_MAINNET_CHAIN_ID\b/ChainKeys.\1_MAINNET/g'
-```
-
-Then add `import { ChainKeys } from '@sodax/sdk'` (or `'@sodax/dapp-kit'` — both work) where needed. tsc will flag missing imports.
-
-For more sophisticated automation across many files, use ts-morph:
-
-```ts
-// @ai-snippets-skip
-// codemod-chain-ids.ts — run with `tsx codemod-chain-ids.ts`
-import { Project, SyntaxKind } from 'ts-morph';
-
-const project = new Project({ tsConfigFilePath: './tsconfig.json' });
-
-for (const file of project.getSourceFiles('src/**/*.{ts,tsx}')) {
-  let needsImport = false;
-
-  file.forEachDescendant((node) => {
-    if (node.getKind() === SyntaxKind.Identifier) {
-      const text = node.getText();
-      const m = text.match(/^([A-Z_]+)_MAINNET_CHAIN_ID$/);
-      if (m) {
-        node.replaceWithText(`ChainKeys.${m[1]}_MAINNET`);
-        needsImport = true;
-      }
-    }
-  });
-
-  if (needsImport && !file.getImportDeclaration('@sodax/sdk')?.getNamedImports().some(n => n.getName() === 'ChainKeys')) {
-    file.addImportDeclaration({ moduleSpecifier: '@sodax/sdk', namedImports: ['ChainKeys'] });
-  }
-}
-
-await project.save();
-```
-
-## Codemod 2: useSpokeProvider deletion
-
-`useSpokeProvider` is gone in v2. Delete the import + usage; replace with `useWalletProvider` from `@sodax/wallet-sdk-react`.
-
-```bash
-# 1. Find all usages first.
-grep -rE '\buseSpokeProvider\b' src/
-
-# 2. Manual delete + rewrite each (no safe sed for this — context varies).
-```
-
-Per call site, the rewrite:
-
-```diff
-- import { useSpokeProvider } from '@sodax/dapp-kit';
-- const spokeProvider = useSpokeProvider({ chainId: BSC_MAINNET_CHAIN_ID });
-+ import { useWalletProvider } from '@sodax/wallet-sdk-react';
-+ import { ChainKeys } from '@sodax/sdk';
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-```
-
-Then update consumers of `spokeProvider` to use `walletProvider` instead — usually inside `mutate(vars)` payloads, sometimes inside query hook params.
-
-## Codemod 3: invalidate*Queries utilities deletion
-
-Most v1 consumers had `lib/invalidate*Queries.ts` files. Hook-owned invalidations make these obsolete:
-
-```bash
-# Find them.
-grep -rE '(invalidateMmQueries|invalidateSwapQueries|invalidateBridgeQueries|invalidate\w+Queries)' src/
-
-# For each call site, delete the call. The mutation hook handles invalidation.
-```
-
-If you have a custom invalidation that dapp-kit's hooks don't know about (e.g. your own analytics view), move it into `mutationOptions.onSuccess`:
-
-```diff
-  const { mutateAsync: supply } = useSupply({
-+   mutationOptions: {
-+     onSuccess: async (data, vars) => {
-+       await queryClient.invalidateQueries({ queryKey: ['my-app', 'analytics'] });
-+     },
-+   },
-  });
-- await supply({ params, spokeProvider });
-- invalidateMmQueries(queryClient, ...);   // delete
-- await queryClient.invalidateQueries({ queryKey: ['my-app', 'analytics'] });   // delete
-+ await supply({ params, walletProvider });
-```
-
-## Adapter: Result<T>-shape adapter for legacy error consumers
-
-If your consumer code has a helper that branches on a v1 error shape (e.g. `error.code` from old per-feature classes), the minimal change is to map v2 onto v1 at the boundary:
-
-```ts
-// adapters/v1ErrorShape.ts
-import { isSodaxError } from '@sodax/dapp-kit';
-
-// V1 shape: { code, message, data?: { error } }
-export function adaptToV1ErrorShape(error: unknown): { code?: string; message?: string; data?: { error?: unknown } } | null {
-  if (!error) return null;
-  if (isSodaxError(error)) {
-    return {
-      code: error.code,
-      message: error.message,
-      data: { error: error.cause },
-    };
-  }
-  if (error instanceof Error) return { code: 'UNKNOWN', message: error.message };
-  if (typeof error === 'object') return error as { code?: string; message?: string };
-  return null;
-}
-```
-
-Then your existing v1-shape error handlers keep working:
-
-```ts
-// @ai-snippets-skip
-const { mutateAsync: swap } = useSwap();
-try {
-  await swap({ params, walletProvider });
-} catch (e) {
-  const adapted = adaptToV1ErrorShape(e);
-  if (adapted?.code === 'INTENT_CREATION_FAILED' /* etc. */) { /* ... */ }
-}
-```
-
-Plan to delete the adapter once you've converted error-handling code site-by-site.
-
-## Incremental migration: feature-by-feature
-
-If the codebase is too large for a single-pass migration, you can convert one feature at a time. The pattern:
-
-1. **Pick a low-traffic feature first** (e.g. recovery, partner). It limits blast radius if something breaks.
-2. **Convert that feature's call sites and approve hooks**.
-3. **Run the app, smoke-test the feature**.
-4. **Move on to the next feature**.
-
-The catch: SDK-level changes are global (e.g. chain-key terminology). You can't do `xChainId` on `XToken` for swap and `chainKey` for staking — both run on the same SDK. Plan to do all SDK-level migrations in one pass first (Phase 1 + 2 of [`checklist.md`](checklist.md)), then per-feature hook-call-site work in any order (Phase 3+).
-
-## Incremental migration: keeping v1 wrappers temporarily
-
-If you have many call sites that share a custom wrapper hook (e.g. one your codebase named `useLegacySwap` calling v1 dapp-kit underneath), you can rewrite the wrapper's body to call v2 internally while keeping the wrapper's name and surface intact. Call sites stay unchanged.
-
-```tsx
-// Custom wrapper that your codebase already has (with a project-specific name).
-// Rewrite its body to call v2 dapp-kit internally; preserve the surface so
-// existing call sites don't change yet.
-
-import { useSwap } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import type { CreateIntentParams } from '@sodax/sdk';
-
-// Function name starts with `use` because it calls React hooks (`useWalletProvider`,
-// `useSwap`). Inside a component, call it like any other hook.
-export function useLegacySwapAdapter(spokeProvider: unknown, params: CreateIntentParams) {
-  const walletProvider = useWalletProvider(/* derive chainKey from spokeProvider */);
-  const m = useSwap();
-  return {
-    swap: async () => {
-      if (!walletProvider) throw new Error('wallet not connected');
-      // Adapt v2 throw-on-fail back to v1 success-with-Result shape:
-      try {
-        const value = await m.mutateAsync({ params, walletProvider });
-        return { ok: true, value };
-      } catch (e) {
-        return { ok: false, error: e };
-      }
-    },
-    isLoading: m.isPending,
-    error: m.error,
-  };
-}
-```
-
-Then convert call sites at your own pace. Delete the wrapper once you're done.
-
-## Cross-references
-
-- [`README.md`](README.md) — overview + glossary.
-- [`checklist.md`](checklist.md) — top-down migration checklist.
-- [`ai-rules.md`](ai-rules.md) — DO / DO NOT for the agent doing the migration.
-- [`breaking-changes/`](breaking-changes/) — cross-cutting deltas in detail.
-- [`features/`](features/) — per-feature porting playbooks.

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

@@ -1,15 +0,0 @@
-# Migration reference — `@sodax/dapp-kit` v1 → v2
-
-Lookup tables for the v1 → v2 delta. Skim during migration to confirm specific renames or removals.
-
-| File | What's in it |
-|---|---|
-| [`deleted-hooks.md`](deleted-hooks.md) | v1 hooks that no longer exist in v2 (`useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`-style API). |
-| [`renamed-hooks.md`](renamed-hooks.md) | Hooks whose name or signature changed (rare — most renames are field-level). |
-| [`error-shape-crosswalk.md`](error-shape-crosswalk.md) | v1 error class names → v2 `SodaxError<C>` mapping; how thrown errors look at the consumer level. |
-
-For SDK-level reference (deleted exports, renames, error code crosswalk), see [`../../../../sdk/ai-exported/migration/reference/`](../../../../sdk/ai-exported/migration/reference/) — the underlying SDK has its own reference tree.
-
-## Pair
-
-This `migration/reference/` tree mirrors [`../../integration/reference/`](../../integration/reference/) (which documents v2 directly). When you need both "what does v2 do" and "what changed from v1" — open both.

package/ai-exported/migration/reference/deleted-hooks.md

@@ -1,110 +0,0 @@
-# Deleted hooks — v1 → v2
-
-Hooks that existed in v1 dapp-kit (or v1-style consumer-side utilities) and have no v2 equivalent.
-
-## `useSpokeProvider`
-
-| | |
-|---|---|
-| v1 path | `import { useSpokeProvider } from '@sodax/dapp-kit'` |
-| v2 status | **DELETED** |
-| v2 alternative | Use `useWalletProvider({ xChainId: chainKey })` from `@sodax/wallet-sdk-react`, then pass `walletProvider` directly into `mutate(vars)` for mutations or as a query-hook param. |
-
-```diff
-- import { useSpokeProvider } from '@sodax/dapp-kit';
-- const spokeProvider = useSpokeProvider({ chainId: BSC_MAINNET_CHAIN_ID });
-+ import { useWalletProvider } from '@sodax/wallet-sdk-react';
-+ import { ChainKeys } from '@sodax/sdk';
-+ const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-```
-
-The chain key on the action params is what routes to the right per-chain spoke service inside the SDK; there's no "spoke provider" object for consumers to construct or hold.
-
-## `useMigrate(spokeProvider)` (and any v1 single-migration-hook variant)
-
-| | |
-|---|---|
-| v1 path | A single `useMigrate(spokeProvider)` hook (often commented out by the time consumers tried to use it) |
-| v2 status | **DELETED** |
-| v2 alternative | Six per-action hooks: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, `useMigrationApprove`, `useMigrationAllowance`. |
-
-See [`../features/migration.md`](../features/migration.md) for the full split.
-
-## Consumer-side `invalidate*Queries` utilities
-
-| | |
-|---|---|
-| v1 path | Often a `lib/invalidateMmQueries.ts` (or similar per-feature) file in the consumer codebase |
-| v2 status | **No longer needed — DELETE** |
-| v2 alternative | Hook-owned invalidations. Each mutation hook invalidates the relevant query keys in its own `onSuccess`. |
-
-```diff
-- // lib/invalidateMmQueries.ts — DELETE this file
-- export function invalidateMmQueries(qc, srcChainKey, userAddress, token) {
--   qc.invalidateQueries({ queryKey: ['mm', 'userReservesData', srcChainKey, userAddress] });
--   qc.invalidateQueries({ queryKey: ['shared', 'xBalances', srcChainKey] });
--   /* ... */
-- }
-
-- // call site — DROP the manual invalidation
-- await supply({ params, spokeProvider });
-- invalidateMmQueries(queryClient, srcChainKey, userAddress, token);
-+ // v2 — supply hook invalidates xBalances + userReservesData itself
-+ await supply({ params, walletProvider });
-```
-
-For cross-feature invalidations the hook can't know about (e.g. your custom analytics view), use `mutationOptions.onSuccess`:
-
-```ts
-// @ai-snippets-skip
-const { mutateAsync: supply } = useSupply({
-  mutationOptions: {
-    onSuccess: async (data, vars) => {
-      await queryClient.invalidateQueries({ queryKey: ['my-app', 'analytics'] });
-    },
-  },
-});
-```
-
-## Approve hook return shape (`{ approve, isLoading, error }`)
-
-| | |
-|---|---|
-| v1 shape | Per-feature: `useFooApprove(spokeProvider) → { approve, isLoading, error }` |
-| v2 status | **DELETED** (return shape, not the hooks themselves) |
-| v2 alternative | Standard `SafeUseMutationResult` — `mutateAsync` / `mutateAsyncSafe`, `isPending`, `error`. |
-
-```diff
-- const { approve, isLoading } = useSwapApprove(spokeProvider);
-- await approve(params);
-+ const { mutateAsync: approve, isPending } = useSwapApprove();
-+ await approve({ params, walletProvider });
-```
-
-`isLoading` → `isPending` (React Query 5 convention).
-
-## v1 individual chain-id constants (SDK-leakage)
-
-Not strictly hooks, but they used to be importable from `@sodax/sdk` (or `@sodax/dapp-kit` re-export):
-
-| Constant | v1 value | v2 alternative |
-|---|---|---|
-| `BSC_MAINNET_CHAIN_ID` | `'0x38.bsc'` | `ChainKeys.BSC_MAINNET` |
-| `ARBITRUM_MAINNET_CHAIN_ID` | `'0xa4b1.arbitrum'` | `ChainKeys.ARBITRUM_MAINNET` |
-| `BASE_MAINNET_CHAIN_ID` | `'0x2105.base'` | `ChainKeys.BASE_MAINNET` |
-| `POLYGON_MAINNET_CHAIN_ID` | `'0x89.polygon'` | `ChainKeys.POLYGON_MAINNET` |
-| `ETHEREUM_MAINNET_CHAIN_ID` | `'0x1.ethereum'` | `ChainKeys.ETHEREUM_MAINNET` |
-| ... 11 more | ... | All under `ChainKeys.*` namespace |
-
-Codemod with sed:
-
-```bash
-find src -type f \( -name '*.ts' -o -name '*.tsx' \) | xargs sed -i '' -E 's/\b([A-Z_]+)_MAINNET_CHAIN_ID\b/ChainKeys.\1_MAINNET/g'
-```
-
-## Cross-references
-
-- [`renamed-hooks.md`](renamed-hooks.md) — hooks whose name/signature changed (different from deletions).
-- [`error-shape-crosswalk.md`](error-shape-crosswalk.md) — error class consolidation.
-- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) — broader hook-shape changes.
-- [`../breaking-changes/sdk-leakage.md`](../breaking-changes/sdk-leakage.md) — SDK-level migrations leaking through.