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

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

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

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