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

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

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

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

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

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

package/ai-exported/migration/reference/error-shape-crosswalk.md

@@ -0,0 +1,144 @@
+# Error shape crosswalk — v1 → v2
+
+The shape and type of errors flowing through dapp-kit hooks changed in v2. The change is mostly SDK-level (one canonical `SodaxError<C>` replaces 7+ per-feature classes) but it surfaces in dapp-kit at the consumer level — wherever you catch or branch on errors from hooks.
+
+## Where v2 errors appear
+
+| Surface | v1 | v2 |
+|---|---|---|
+| `mutation.error` | Only on actual exceptions | Includes SDK `!ok` errors (now thrown inside `mutationFn`) |
+| `mutation.data` | `Result<T>` (`{ ok, value, error }`) | Unwrapped success type `T`; SDK `!ok` flows to `mutation.error` |
+| `mutateAsync` rejection | Only on exceptions | Includes SDK `!ok` rejections |
+| `mutateAsyncSafe` `result.error` | (didn't exist) | Includes SDK `!ok` errors (re-packed from the throw) |
+| `onError` callback | Fired only for exceptions | Fires for SDK `!ok` too |
+
+The semantic shift is: v1 treated SDK `!ok` as "successful but with an error inside"; v2 treats it as a thrown error. See [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) for the full picture.
+
+## Error class crosswalk (SDK-level — leaks through)
+
+In v1, each SDK feature had its own error class:
+
+```ts
+// @ai-snippets-skip — describes deleted v1 type surface, not runnable
+// v1
+class MoneyMarketError<C extends MoneyMarketErrorCode> extends Error { /* ... */ }
+class IntentError<C extends IntentErrorCode> extends Error { /* ... */ }
+class StakingError<C extends StakingErrorCode> extends Error { /* ... */ }
+class BridgeError<C extends BridgeErrorCode> extends Error { /* ... */ }
+class MigrationError<C extends MigrationErrorCode> extends Error { /* ... */ }
+class AssetServiceError<C extends AssetServiceErrorCode> extends Error { /* ... */ }
+class ConcentratedLiquidityError<C extends ConcentratedLiquidityErrorCode> extends Error { /* ... */ }
+// ...
+```
+
+In v2, all are consolidated:
+
+```ts
+// @ai-snippets-skip — type-shape reference; the real class is exported from @sodax/sdk
+// v2
+class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
+  readonly code: C;                  // closed reason union (no feature prefix)
+  readonly feature: SodaxFeature;    // 'swap' | 'moneyMarket' | 'bridge' | …
+  readonly cause?: unknown;
+  readonly context?: SodaxErrorContext;
+}
+```
+
+Discriminate via `(error.feature, error.code)` instead of class name.
+
+## Error code crosswalk (key examples)
+
+The SDK reduced the per-feature code unions to a unified 13-code reason vocabulary, with feature-specific context on `error.context.action` / `error.context.method`. Examples:
+
+| v1 (per-feature) | v2 |
+|---|---|
+| `MoneyMarketError<'CREATE_SUPPLY_INTENT_FAILED'>` | `SodaxError<'INTENT_CREATION_FAILED'>` with `feature: 'moneyMarket'`, `context.action: 'supply'` |
+| `MoneyMarketError<'SUPPLY_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'moneyMarket'`, `context.action: 'supply'` |
+| `IntentError<'CREATE_INTENT_FAILED'>` | `SodaxError<'INTENT_CREATION_FAILED'>` with `feature: 'swap'`, `context.action: 'createIntent'` |
+| `IntentError<'POST_EXECUTION_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'swap'`, `context.phase: 'postExecution'` |
+| `StakingError<'STAKE_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'staking'`, `context.action: 'stake'` |
+| `BridgeError<'BRIDGE_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'bridge'`, `context.action: 'bridge'` |
+| `MigrationError<'MIGRATE_BNUSD_FORWARD_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'migration'`, `context.action: 'migratebnUSD'`, `context.direction: 'forward'` |
+| `*Error<'ALLOWANCE_CHECK_FAILED'>` | `SodaxError<'ALLOWANCE_CHECK_FAILED'>` (unchanged code; new feature/context fields) |
+| `*Error<'APPROVE_FAILED'>` | Same |
+| `*Error<'GAS_ESTIMATION_FAILED'>` | Same |
+| `*Error<'RELAY_TIMEOUT'>` | `SodaxError<'RELAY_TIMEOUT'>` with `relayCode: 'RELAY_TIMEOUT'` on context |
+
+Full crosswalk (per feature): [`../../../../sdk/ai-exported/migration/reference/error-code-crosswalk.md`](../../../../sdk/ai-exported/migration/reference/error-code-crosswalk.md).
+
+## How to migrate error-handling code
+
+### Pattern 1: `instanceof` checks → `isSodaxError`
+
+```diff
+- catch (e) {
+-   if (e instanceof MoneyMarketError) {
+-     handleMmError(e.code);
+-   }
+- }
++ catch (e) {
++   if (isSodaxError(e) && e.feature === 'moneyMarket') {
++     handleMmError(e.code);
++   }
++ }
+```
+
+`isSodaxError` is exported from `@sodax/dapp-kit` (re-exported from `@sodax/sdk`).
+
+### Pattern 2: switch on code
+
+```diff
+  catch (e) {
+-   if (e instanceof IntentError) {
+-     switch (e.code) {
+-       case 'CREATE_INTENT_FAILED': /* ... */ break;
+-       case 'POST_EXECUTION_FAILED': /* ... */ break;
+-       case 'RELAY_TIMEOUT': /* ... */ break;
+-     }
+-   }
++   if (isSodaxError(e) && e.feature === 'swap') {
++     switch (e.code) {
++       case 'INTENT_CREATION_FAILED': /* was CREATE_INTENT_FAILED */ break;
++       case 'EXECUTION_FAILED':       /* was POST_EXECUTION_FAILED — check e.context.phase */ break;
++       case 'RELAY_TIMEOUT':           /* unchanged code */ break;
++     }
++   }
+  }
+```
+
+### Pattern 3: error-text helper
+
+If your v1 code has a helper that maps `error.code` to a UI message, write a small adapter:
+
+```ts
+// adapters/v1ErrorShape.ts
+import { isSodaxError } from '@sodax/dapp-kit';
+
+const V1_CODE_MAP: Record<string, string> = {
+  'INTENT_CREATION_FAILED': 'CREATE_INTENT_FAILED',
+  'EXECUTION_FAILED': 'POST_EXECUTION_FAILED',
+  // ... etc.
+};
+
+export function adaptToV1Code(error: unknown): string | undefined {
+  if (!isSodaxError(error)) return undefined;
+  return V1_CODE_MAP[error.code] ?? error.code;
+}
+```
+
+Plan to delete the adapter once you've ported all error UI.
+
+## Pitfalls
+
+1. **`onError` callbacks fire MORE in v2.** They previously didn't fire for SDK `!ok` (success-path-with-error pattern). Now they do. Audit toasts / logs to make sure they're appropriate.
+2. **`mutation.error` reads MORE in v2.** Same reason — SDK errors flow through it now.
+3. **`isSodaxError(e)` is the cross-bundle-safe check.** Bare `instanceof SodaxError` may break in monorepos with multiple package copies (mixed ESM/CJS, etc.). Use the type guard.
+4. **The `feature` field is your discriminator.** A `SodaxError` from a swap mutation has `feature: 'swap'`. A bridge mutation has `feature: 'bridge'`. The `code` is the reason; `feature` is the source.
+
+## Cross-references
+
+- [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) — semantic shift in `Result<T>` handling.
+- [`../breaking-changes/sdk-leakage.md`](../breaking-changes/sdk-leakage.md) — broader SDK-side migrations.
+- [`../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md`](../../../../sdk/ai-exported/migration/breaking-changes/result-and-errors.md) — full SDK error-class consolidation.
+- [`../../../../sdk/ai-exported/migration/reference/error-code-crosswalk.md`](../../../../sdk/ai-exported/migration/reference/error-code-crosswalk.md) — per-feature error code crosswalks.
+- [`../../integration/architecture.md`](../../integration/architecture.md) § "SDK Result handling" — design rationale.

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

@@ -0,0 +1,66 @@
+# Renamed hooks — v1 → v2
+
+Hooks whose **name** changed between versions. Most v1 → v2 changes were signature-level (single-object params, `mutateAsyncSafe`, etc.) — actual hook renames are rare. The list below is the small set.
+
+## Hooks renamed
+
+| v1 | v2 | Notes |
+|---|---|---|
+| (none significant) | | Most hook names are stable across v1 → v2 |
+
+### Why this list is short
+
+The v2 canonicalization pass focused on hook **shapes** (single-object params, return-shape consolidation, mutateAsyncSafe), not naming. For most consumer code, the hook name you `import { ... }`'d in v1 is still the right hook in v2 — the breaking change is in the call shape, not the import.
+
+## Hooks whose generic / type shape changed
+
+These keep their name but their TypeScript signature is different. Usually requires per-call-site fixes.
+
+| Hook | v1 → v2 change |
+|---|---|
+| `useSwap` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params } → { params, walletProvider }`. |
+| `useSwapAllowance` | Query params: `(params, spokeProvider) → { params: { payload, srcChainKey, walletProvider } }`. SDK request nested under `params.payload`. Data unwrapped to `boolean`. |
+| `useSwapApprove` | Return: `{ approve, isLoading } → SafeUseMutationResult` (with `mutateAsync` / `isPending`). Vars accept `CreateIntentParams \| CreateLimitOrderParams`. TData is `TxReturnType<K, false>` (chain-keyed receipt union). |
+| `useStatus` | Now `useStatus({ params: { intentTxHash } })` — single-object shape AND key renamed from `intentHash` → `intentTxHash`. Data is `Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined` (Result-wrapped). Polls 3s. |
+| `useQuote` | Now `useQuote({ params: { payload } })` — SDK request nested under `params.payload` (NOT directly under `params`). Data is `Result<SolverIntentQuoteResponse, SolverErrorResponse> \| undefined`. Polls 3s. |
+| `useCancelSwap` / `useCancelLimitOrder` | TVars are FLAT (no `params` wrapper): `{ srcChainKey, intent, walletProvider }`. |
+| `useCreateLimitOrder` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params, walletProvider }`. mutationKey is `['swap', 'limitOrder', 'create']`. |
+| All MM mutations (`useSupply`/etc.) | Same as `useSwap`. Plus `srcChainKey` / `srcAddress` required in params (SDK-leakage). All four actions accept optional `dstChainKey`/`dstAddress` for cross-chain delivery (not just borrow/repay). |
+| `useMMAllowance` | Query params: `{ params: { payload: MoneyMarketParams<K> } }`. For `'borrow'` / `'withdraw'` actions: `enabled: false` — `data` stays `undefined`. |
+| `useUserReservesData` | Param key rename: `address → userAddress`; chain key is `spokeChainKey`. |
+| `useUserFormattedSummary` | Same. |
+| All staking mutations | Same as MM. Plus dedicated approve hooks per token (`useStakeApprove` ↔ `useUnstakeApprove` ↔ `useInstantUnstakeApprove`). |
+| `useStakeRatio` | Return: `Result<bigint> → [xSodaAmount, previewDepositAmount]` (unwrapped tuple — NOT Result-wrapped in v2). |
+| `useStakingInfo` / `useUnstakingInfo` / `useUnstakingInfoWithPenalty` / `useStakingConfig` / `useInstantUnstakeRatio` / `useConvertedAssets` | All unwrapped in v2 (hooks throw on SDK `!ok`). Branch on `isError`/`error`, not `data?.ok`. |
+| `useUnstakingInfo` | Return shape: array → object `{ userUnstakeSodaRequests, totalUnstaking }`. `UserUnstakeInfo` items expose `id` (the requestId) and `request` (original `UnstakeSodaRequest`). |
+| All three staking allowance hooks | Query params: `{ params: { payload: Omit<<Action>Params<K>, 'action'> } }`. Data unwrapped to `boolean`. |
+| `useBridge` | Params: `srcChainId/dstChainId/recipient → srcChainKey/dstChainKey/recipient`. Plus field renames inside `CreateBridgeIntentParams`: `srcAsset → srcToken`, `dstAsset → dstToken`. Return: tuple → `TxHashPair` object (`{ srcChainTxHash, dstChainTxHash }`). |
+| `useBridgeAllowance` | Query params: nested `{ params: { payload, walletProvider } }`. Data unwrapped to `boolean` (queryFn returns `false` on SDK `!ok` — does NOT throw). |
+| `useGetBridgeableAmount` | Params: 4 fields → `{ from: XToken, to: XToken }`. Return: `bigint → BridgeLimit` object (`{ amount, decimals, type: 'DEPOSIT_LIMIT' \| 'WITHDRAWAL_LIMIT' }`). |
+| `useGetBridgeableTokens` | Params: positional → `{ params: { from, to, token } }`. |
+| All DEX mutations | Same as MM. `useSupplyLiquidity` now handles both mint-new and increase-existing — fan-out gated by `params.tokenId` + `params.isValidPosition`. |
+| `useDexAllowance` | Now `{ params: { payload: CreateAssetDepositParams<K> } }`. No `walletProvider` (read-only). |
+| `PoolKey` shape | Real fields are `currency0`, `currency1`, `fee`, `hooks?`, `poolManager`, `parameters` — NOT `poolAddress`/`token0Symbol`/etc. |
+| `useCreate*Params` builders | All take FLAT props object — NOT `{ params }`-wrapped (`useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams`). |
+| `useFeeClaimSwap` (partner) | Same as MM mutation pattern. TData is `IntentAutoSwapResult` (NOT `SwapResponse`). |
+| `useXBalances` | Params: positional → `{ params: { xService, xChainId, xTokens, address } }`. All four required. `xService` injected from `@sodax/wallet-sdk-react`. |
+| `useEstimateGas` | Mutation; vars: `EstimateGasParams<C>` (flat, not `{ params, walletProvider }`-wrapped). |
+| `useDeriveUserWalletAddress`, `useGetUserHubWalletAddress` | Single-object query shape. |
+| `useStellarTrustlineCheck` | Single-object shape with `{ token, amount, chainId, walletProvider }` under `params`. |
+| `useRequestTrustline` | Custom utility hook (NOT a canonical mutation). Takes `(token: string \| undefined)` positionally, returns `{ requestTrustline, isLoading, isRequested, error, data }`. The `requestTrustline` callback takes `{ token, amount, srcChainKey, walletProvider }`. |
+| `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers` | Pagination MUST be nested under `params`: `{ params: { pagination: { offset, limit } } }`. |
+| `useBackendUserIntents` | Data is `UserIntentsResponse = { items: IntentResponse[], total, offset, limit }` — NOT a bare array. Access `data?.items`. |
+| `useBackendSubmitSwapTx` | Mutation. `apiConfig` moved from hook init to `mutate(vars)`. |
+| All migration hooks | **NEW**: 6 per-action hooks replacing v1's single `useMigrate`. See [`deleted-hooks.md`](deleted-hooks.md). |
+| `useMigrationAllowance` | Query params nest under `params` with inner field literally named `params` (NOT `payload`): `{ params: { params: <migration-params>, action: 'migrate' \| 'revert' } }`. |
+| `BalnMigrateParams` (used by `useMigrateBaln`) | NEW required field `stake: boolean`. `lockupPeriod` is the `LockupPeriod` enum (5 members; values in seconds, not months). |
+| `useTradingWalletBalance` | Return is `RadfiWalletBalance = { btcSatoshi, pendingSatoshi, externalPendingSatoshi, totalUtxos }` — NOT `{ confirmed, pending }`. |
+| `useExpiredUtxos` | Return is `RadfiUtxo[]` (with `_id`, `txid`, `vout`, `txidVout`, `satoshi`, `amount`, `address`, `isSpent`, `status`, `source`, optional `runes`). Both this and `useTradingWalletBalance` take `{ params: { walletProvider, tradingAddress } }`. |
+| `useRadfiAuth` | TData is `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields — `publicKey` is persisted to localStorage but NOT returned). |
+| All Bitcoin/Radfi mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
+
+## Cross-references
+
+- [`deleted-hooks.md`](deleted-hooks.md) — hooks that no longer exist at all.
+- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) — shape changes in detail.
+- [`../features/`](../features/) — per-feature porting playbooks.