@sodax/sdk 1.5.7-beta → 2.0.0-rc.2

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

@@ -0,0 +1,198 @@
+# Swap migration — v1 → v2
+
+Pure-SDK migration playbook for `SwapService`.
+
+Pair: [`../../integration/features/swap.md`](../../integration/features/swap.md).
+
+## TL;DR
+
+1. **Drop the `*SpokeProvider` argument.** Pass `walletProvider` directly into the SDK call payload alongside `params` and `raw: false`.
+2. **Add `raw: false` (or `raw: true`) to every call shape.** Without it, TypeScript can't pick a branch of `WalletProviderSlot` and rejects `walletProvider`.
+3. **Field renames on `CreateIntentParams<K>` and `CreateLimitOrderParams<K>`:**
+   - `srcChain` → `srcChainKey`
+   - `dstChain` → `dstChainKey`
+   - **`Intent.srcChain` / `Intent.dstChain` are unchanged** (read shape) — they're `IntentRelayChainId` (bigint).
+4. **`CreateIntentResult` shape changed.** v1 was a tuple `[spokeTxHash, intent, relayData]`; v2 is an object `{ tx, intent, relayData }`. Destructure accordingly.
+5. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field on the request expects a **string** (`relayData.payload`), not the `RelayExtraData` object.
+6. **Errors → `SodaxError` + `Result<T>`.** v1's `IntentError<IntentErrorCode>` is gone. Branch on `result.ok`; use `(error.feature, error.code)` for discrimination.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 field | v2 field | Notes |
+|---|---|---|---|
+| `CreateIntentParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | Now generic: `CreateIntentParams<K extends SpokeChainKey>`. |
+| `CreateLimitOrderParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | `Omit<CreateIntentParams<K>, 'deadline'>`. |
+| `SubmitSwapTxRequest` (backend req) | `srcChainId` | `srcChainKey` | And `relayData: string` (was the object in v1). |
+| `Intent` (read shape) | `srcChain`, `dstChain` | **unchanged** | `IntentRelayChainId` (bigint). Don't grep-replace blindly. |
+| `XToken` | `xChainId` | `chainKey` | Type renamed from `Token` → `XToken`. |
+| `CreateIntentResult` | tuple `[spokeTxHash, intent, relayData]` | object `{ tx, intent, relayData }` | Generic: `CreateIntentResult<K, Raw>`. |
+
+### Deleted symbols
+
+- The `SpokeProvider` union and per-chain `*SpokeProvider` classes — gone. v2 takes `walletProvider` directly. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 1.
+- `IntentError<IntentErrorCode>` and `isIntentError` / `isIntentPostExecutionFailedError` / `isIntentSubmitTxFailedError` type guards. Replaced by `isSodaxError` + feature/code discrimination.
+- `CustomProvider` (Hana wallet window typedecl) — declare `unknown` or import directly from the wallet vendor.
+- `hubAssets` global — gone. `XToken.vault` and `XToken.hubAsset` baked in.
+
+### v1 → v2 error code crosswalk (swap-specific)
+
+| v1 `IntentErrorCode` | v2 `SodaxErrorCode` + context |
+|---|---|
+| `CREATE_INTENT_FAILED` | `INTENT_CREATION_FAILED` (`action: 'createIntent'`) |
+| `CREATE_LIMIT_ORDER_FAILED` | `INTENT_CREATION_FAILED` (`action: 'createLimitOrder'`) |
+| `POST_EXECUTION_FAILED` | `EXECUTION_FAILED` (`action: 'swap'`, `phase: 'postExecution'`) |
+| `SOLVER_API_ERROR` | `EXTERNAL_API_ERROR` (`api: 'solver'`, with `solverCode`/`solverDetail` on context) |
+| `SIMULATION_FAILED` | `EXECUTION_FAILED` (`phase: 'execution'`) |
+| `SUBMIT_TX_FAILED` (relay) | `TX_SUBMIT_FAILED` (`relayCode: 'SUBMIT_TX_FAILED'`) |
+| `RELAY_TIMEOUT` | `RELAY_TIMEOUT` (unchanged code; still on `relayCode`) |
+
+## Per-method delta
+
+### `swap`
+
+```diff
+- await sodax.swaps.swap({
+-   intentParams,
+-   spokeProvider: sourceSpokeProvider,
+- });
++ const result = await sodax.swaps.swap({
++   params: intentParams,
++   raw: false,
++   walletProvider: sourceWalletProvider,
++ });
++ if (!result.ok) return;
++ const { spokeTxHash, intent, relayData } = result.value;
+```
+
+### `createIntent`
+
+```diff
+- const [spokeTxHash, intent, relayData] = await sodax.swaps.createIntent({
+-   intentParams,
+-   spokeProvider: sourceSpokeProvider,
+- });
++ const result = await sodax.swaps.createIntent({
++   params: intentParams,
++   raw: false,
++   walletProvider: sourceWalletProvider,
++ });
++ if (!result.ok) return;
++ const { tx: spokeTxHash, intent, relayData } = result.value;
+```
+
+### `createLimitOrder`
+
+Same as `createIntent` shape (with `CreateLimitOrderParams`). v1 took `{ limitOrderParams, spokeProvider }`; v2 takes `{ params, raw: false, walletProvider }`.
+
+### `cancelIntent` / `cancelLimitOrder`
+
+```diff
+- await sodax.swaps.cancelIntent({ srcChain, intent, spokeProvider });
++ await sodax.swaps.cancelIntent({
++   params: { srcChainKey, intent },
++   raw: false,
++   walletProvider,
++ });
+```
+
+### `approve` / `isAllowanceValid`
+
+v1: `await sodax.swaps.approve({ intentParams, spokeProvider })`.
+v2: `await sodax.swaps.approve({ params: intentParams, raw: false, walletProvider })`.
+
+For `isAllowanceValid` in **read-only** flows (e.g. UI polling), use `raw: true` to skip the wallet-provider requirement:
+
+```ts
+const result = await sodax.swaps.isAllowanceValid({ params, raw: true });
+```
+
+The underlying read doesn't consult the wallet provider; `raw: true` is the contract for read-only access.
+
+### Backend submit-tx (`SubmitSwapTxRequest`)
+
+```diff
+  const request: SubmitSwapTxRequest = {
+    txHash: spokeTxHash as string,
+-   srcChainId: sourceChain,
++   srcChainKey: src.chain,
+    walletAddress: sourceAccount.address ?? '',
+    intent: swapIntentData,
+-   relayData,                       // was the RelayExtraData object
++   relayData: relayData.payload,    // now a string
+  };
+  const submitResult = await sodax.backendApi.submitSwapTx(request);
+  if (!submitResult.ok) return;
+```
+
+## Worked example — `handleSubmitTxSwap` flow
+
+```diff
+  const handleSubmitTxSwap = async (intentOrderPayload: CreateIntentParams) => {
+-   if (!sourceProvider) return;
++   if (!sourceWalletProvider) return;
+-   const createIntentResult = await sodax.swaps.createIntent({
+-     intentParams: intentOrderPayload,
+-     spokeProvider: sourceProvider,
+-   });
++   const createIntentResult = await sodax.swaps.createIntent({
++     params: intentOrderPayload,
++     raw: false,
++     walletProvider: sourceWalletProvider,
++   });
+    if (!createIntentResult.ok) return;
+-   const [spokeTxHash, intent, relayData] = createIntentResult.value;
++   const { tx: spokeTxHash, intent, relayData } = createIntentResult.value;
+    const swapIntentData: SwapIntentData = {
+      /* … */
+-     srcChain: Number(intent.srcChain),    // Intent.srcChain still on read shape
+-     dstChain: Number(intent.dstChain),    // Intent.dstChain still on read shape
++     srcChain: Number(intent.srcChain),    // unchanged — Intent shape kept these
++     dstChain: Number(intent.dstChain),
+    };
+    const request: SubmitSwapTxRequest = {
+      txHash: spokeTxHash as string,
+-     srcChainId: sourceChain,
++     srcChainKey: src.chain,
+      walletAddress: sourceAccount.address ?? '',
+      intent: swapIntentData,
+-     relayData,
++     relayData: relayData.payload,
+    };
+-   await submitSwapTx(request);
++   const submitResult = await sodax.backendApi.submitSwapTx(request);
++   if (!submitResult.ok) return;
+  };
+```
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **Over-broad regex on `srcChain` / `dstChain`.** Request types renamed; `Intent` (read shape) didn't. Distinguish "I'm building a request" from "I'm reading an intent."
+2. **`createIntent` success shape changed from tuple to object.** `{ tx, intent, relayData }`, not `[spokeTxHash, intent, relayData]`.
+3. **`relayData` on `SubmitSwapTxRequest` is a `string`.** It's `relayData.payload`, not the full `RelayExtraData` object.
+4. **`spokeTxHash` is `TxReturnType<K, false>`, not necessarily `string`.** For most chains it's a string already, but the SDK type is broader. Cast at the boundary when passing to APIs that strictly want `string`: `txHash: spokeTxHash as string`.
+5. **`Intent.deadline` is `bigint`.** `Math.floor(Date.now() / 1000) + 60 * 5` returns a number; wrap in `BigInt(...)`.
+6. **`IntentResponse.srcChain` / `dstChain` from the backend are `IntentRelayChainId` (number/bigint), not chain keys.** Convert via `sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(intent.dstChain))` when displaying.
+7. **`hubAssets` is gone.** Anything that walked `hubAssets[chainId]` for vault lookup must use `XToken.vault` (now baked in) or `sodax.config.getOriginalAssetAddress()`.
+8. **`SodaxConfig.swaps` vs `.solver`.** v1 mixed solver endpoints under `swaps`; v2 splits — `swaps` for supported tokens, `solver` for endpoints. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) Appendix B.
+
+## Verification
+
+After migrating swap call sites:
+
+```bash
+# Should produce zero errors when the migration is complete:
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scan for leftover v1 patterns:
+grep -rE "spokeProvider:\s*\w+|intentParams:\s*\w+|srcChain:\s*\w+\.[a-z]+ChainId" src/
+grep -rE "isIntentError\b|isIntentPostExecutionFailedError\b|isIntentSubmitTxFailedError\b" src/
+```
+
+## Cross-references
+
+- v2 swap usage: [`../../integration/features/swap.md`](../../integration/features/swap.md).
+- Cross-cutting prerequisites (type-system, architecture, result/errors) listed in [`../README.md`](../README.md).

package/ai-exported/migration/recipes.md

@@ -0,0 +1,288 @@
+# Migration recipes — v1 → v2
+
+Practical patterns for porting consumer code without rewriting everything in one pass. Three recipes:
+
+1. [Codemod patterns](#1-codemod-patterns) — regex find/replace + a small `ts-morph` script for the renames that grep can't safely handle.
+2. [Error-shape adapter](#2-error-shape-adapter) — adapt v2 `SodaxError` onto v1 `{ code, data }` branches so existing error-formatting helpers keep working.
+3. [Result adapter](#3-result-adapter) — wrap v2 `Result<T>` in a v1-style throw shim for incremental conversion of call sites.
+
+These are migration-only — once the port is complete, delete them. They're not patterns for new code.
+
+---
+
+## 1. Codemod patterns
+
+### What's safe to grep-replace
+
+| Change | Find | Replace | Notes |
+|---|---|---|---|
+| Chain-id constants | `(\w+)_MAINNET_CHAIN_ID` | `ChainKeys.$1_MAINNET` | Mechanical. After: fix `import` statements. |
+| `xChainId` field on `XToken` | `\.xChainId\b` | `.chainKey` | Token field rename. Audit first — some non-token types may use `xChainId` differently. |
+| `Token` type rename | `\bimport(.*)\bToken\b(.*)\bfrom 'sodax/types'` | `import$1XToken$2from '@sodax/sdk'` | Best done with `ts-morph` to avoid touching unrelated `Token` identifiers. |
+| `SpokeChainId` → `SpokeChainKey` | `\b(SpokeChainId\|ChainId)\b` (in type positions) | `SpokeChainKey` | Audit — `ChainId` is also used by 3rd-party libs (viem, etc.). Limit to `@sodax/types` imports. |
+| `AddressType` → `BtcAddressType` | `\bAddressType\b` (in `@sodax/types` import positions) | `BtcAddressType` | |
+
+### What's not safe to grep-replace
+
+- `srcChain` → `srcChainKey` on **request** types only. Read shapes (`Intent.srcChain`, `IntentResponse.srcChain`) keep `srcChain` as the relay chain id. Use a `ts-morph` script keyed by parameter type.
+- `spokeProvider` → `walletProvider`. The replacement isn't 1-to-1 (`spokeProvider` was a class instance; `walletProvider` is a separate field). You're better off doing this manually per call site.
+- `instanceof EvmSpokeProvider` → chain-key check. Chain-specific replacement varies (some need `chainKey === ChainKeys.X`, some `getChainType(chainKey) === 'EVM'`).
+
+### `ts-morph` script for chain-id imports
+
+When you have many files, a one-shot script for the chain-id rename. Run from the root of your consumer repo with `tsx codemod-chain-ids.ts`:
+
+```ts
+// codemod-chain-ids.ts
+import { Project, SyntaxKind } from 'ts-morph';
+
+const project = new Project({ tsConfigFilePath: 'tsconfig.json' });
+const sodaxImports = ['@sodax/types', '@sodax/sdk'];
+const renamed = new Set<string>();
+
+for (const file of project.getSourceFiles('src/**/*.{ts,tsx}')) {
+  let edited = false;
+
+  for (const decl of file.getImportDeclarations()) {
+    if (!sodaxImports.includes(decl.getModuleSpecifierValue())) continue;
+
+    const named = decl.getNamedImports();
+    const toRemove: typeof named = [];
+    let needsChainKeysImport = false;
+
+    for (const imp of named) {
+      const name = imp.getName();
+      const m = name.match(/^(.+)_MAINNET_CHAIN_ID$/);
+      if (!m) continue;
+      const newName = `ChainKeys.${m[1]}_MAINNET`;
+      // Replace usages inside the file
+      file.forEachDescendant(node => {
+        if (node.isKind(SyntaxKind.Identifier) && node.getText() === name) {
+          node.replaceWithText(newName);
+          edited = true;
+          renamed.add(name);
+        }
+      });
+      toRemove.push(imp);
+      needsChainKeysImport = true;
+    }
+
+    for (const imp of toRemove) imp.remove();
+    if (needsChainKeysImport) {
+      const existing = decl.getNamedImports().find(i => i.getName() === 'ChainKeys');
+      if (!existing) decl.addNamedImport('ChainKeys');
+    }
+    if (decl.getNamedImports().length === 0 && !decl.getNamespaceImport() && !decl.getDefaultImport()) {
+      decl.remove();
+      edited = true;
+    }
+  }
+
+  if (edited) await file.save();
+}
+
+console.log('Renamed constants:', [...renamed].join(', '));
+```
+
+Exit codes and post-run checks:
+
+- **Run `tsc --noEmit` after** — confirm imports resolve. The script doesn't touch `ChainKey` type imports (which you may also need to add manually in some files).
+- **Re-run with `--dry-run`** semantics by commenting out `file.save()` to preview the diff.
+
+### Pitfall
+
+The `ts-morph` script above edits in-place. Commit your tree before running.
+
+---
+
+## 2. Error-shape adapter
+
+If your consumer code has `getMmErrorText`, `getSwapErrorText`, or similar helpers that branch on a v1 error object's `.code` and `.data.error`, the minimal-change migration is to wrap incoming v2 `SodaxError` instances at the entry point of each helper:
+
+```ts
+// shared/error-shape-adapter.ts
+import { isSodaxError } from '@sodax/sdk';
+
+export type V1ErrorShape = {
+  code?: string;
+  message?: string;
+  data?: { error?: unknown };
+};
+
+/**
+ * Adapt v2 SodaxError onto the v1 `{ code, message, data: { error } }` shape so
+ * existing v1-style error helpers keep working without rewriting every branch.
+ *
+ * Migration only — replace with `(error.feature, error.code)` branching once the
+ * helper is rewritten.
+ */
+export function adaptToV1ErrorShape(error: unknown): V1ErrorShape | null {
+  if (error == null) return null;
+
+  // v2 SodaxError → v1-shaped object with code on top level.
+  if (isSodaxError(error)) {
+    return {
+      code: error.code,
+      message: error.message,
+      data: { error: error.cause },
+    };
+  }
+
+  // Plain Error (no code) — fall back to message.
+  if (error instanceof Error) {
+    return { code: error.message, message: error.message };
+  }
+
+  // Already v1 shape — pass through.
+  if (typeof error === 'object') {
+    return error as V1ErrorShape;
+  }
+
+  return null;
+}
+```
+
+### Usage
+
+```ts
+// Before:
+function getMmErrorText(error: unknown): string {
+  if (error instanceof MoneyMarketError) {
+    if (error.code === 'CREATE_SUPPLY_INTENT_FAILED') return 'Could not build supply';
+    if (error.code === 'SUPPLY_FAILED') return 'Supply failed';
+  }
+  return 'Unknown error';
+}
+
+// After (adapter at the top, branches keep working):
+function getMmErrorText(error: unknown): string {
+  const sdkError = adaptToV1ErrorShape(error);
+  if (sdkError?.code === 'INTENT_CREATION_FAILED') return 'Could not build supply';   // v2 code
+  if (sdkError?.code === 'EXECUTION_FAILED') return 'Supply failed';                   // v2 code
+  return 'Unknown error';
+}
+```
+
+### Final-form (recommended)
+
+After the adapter is in place, gradually rewrite each helper to use `(feature, code)` directly. The adapter is a stepping stone, not the destination:
+
+```ts
+import { isSodaxError } from '@sodax/sdk';
+
+function getMmErrorText(error: unknown): string {
+  if (!isSodaxError(error) || error.feature !== 'moneyMarket') return 'Unknown error';
+  switch (error.code) {
+    case 'INTENT_CREATION_FAILED':
+      return error.context?.action === 'supply' ? 'Could not build supply' : 'Could not build operation';
+    case 'EXECUTION_FAILED':
+      return `${error.context?.action ?? 'operation'} failed`;
+    case 'RELAY_TIMEOUT':
+      return 'Cross-chain relay timed out';
+    case 'TX_VERIFICATION_FAILED':
+      return 'Transaction could not be verified on the source chain';
+    default:
+      return 'Unexpected error';
+  }
+}
+```
+
+See [`reference/error-code-crosswalk.md`](reference/error-code-crosswalk.md) for the full v1 → v2 code crosswalk and [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md) § 6 for the discrimination patterns this snippet uses.
+
+---
+
+## 3. Result adapter
+
+If converting every call site to branch on `result.ok` in one pass isn't realistic, use a `throwIfError` shim during migration. Then convert call sites at your own pace.
+
+```ts
+// shared/result-adapter.ts
+import { isSodaxError } from '@sodax/sdk';
+import type { Result } from '@sodax/sdk';
+
+/**
+ * Throw on { ok: false }. v1-shape callers can `await throwIfError(result)` and
+ * keep their existing try/catch blocks during migration.
+ *
+ * The thrown value is the original error from the Result — typically a SodaxError.
+ * Existing instanceof / .code branches will still work via adaptToV1ErrorShape.
+ *
+ * Migration only — once the call site is converted to branch on result.ok directly,
+ * remove the throwIfError wrap.
+ */
+export function throwIfError<T>(result: Result<T, unknown>): T {
+  if (!result.ok) {
+    if (isSodaxError(result.error)) throw result.error;
+    if (result.error instanceof Error) throw result.error;
+    throw new Error(`unwrap failed: ${String(result.error)}`);
+  }
+  return result.value;
+}
+
+/**
+ * Same as throwIfError, but coerces non-Error errors to a thrown Error
+ * (useful when downstream code only catches Error).
+ */
+export function throwAsError<T>(result: Result<T, unknown>, fallbackMessage = 'operation failed'): T {
+  if (!result.ok) {
+    const e = result.error;
+    if (e instanceof Error) throw e;
+    throw new Error(typeof e === 'string' ? e : fallbackMessage);
+  }
+  return result.value;
+}
+```
+
+### Usage during migration
+
+```ts
+// Before (v1):
+try {
+  const txHash = await sodax.moneyMarket.supply({ params, spokeProvider });
+  /* … */
+} catch (e) {
+  if (e instanceof MoneyMarketError && e.code === 'SUPPLY_FAILED') /* … */
+}
+
+// During migration (with shim):
+try {
+  const { srcChainTxHash } = await throwIfError(
+    await sodax.moneyMarket.supply({ params, raw: false, walletProvider }),
+  );
+  /* … */
+} catch (e) {
+  // existing v1-shape branches keep working via adaptToV1ErrorShape;
+  // SodaxError instances satisfy the same checks once you migrate them
+  if (e instanceof Error && /* … */) /* … */
+}
+```
+
+### Final-form (recommended)
+
+Once the call site is converted, drop `throwIfError`:
+
+```ts
+const result = await sodax.moneyMarket.supply({ params, raw: false, walletProvider });
+if (!result.ok) {
+  setError(getMmErrorText(result.error));
+  return;
+}
+const { srcChainTxHash } = result.value;
+```
+
+### Pitfall — the v1-style `try { await sodax.<method>(...) } catch` does not work
+
+A common mistake during migration: keeping the `try/catch` block but updating the inner call to v2 shape, expecting it to still throw. **It won't.** v2 `Result<T>` resolves on failure — the `catch` only fires for synchronous wrapper exceptions (e.g. missing `walletProvider`). Either:
+
+- Wrap the call in `throwIfError` (this recipe), so failures throw.
+- Branch on `result.ok` (preferred end state).
+
+Don't leave the `try/catch` in place expecting it to catch SDK-level failures — it can't.
+
+---
+
+## Cross-references
+
+- The breaking changes that motivate these recipes: [`breaking-changes/type-system.md`](breaking-changes/type-system.md), [`breaking-changes/architecture.md`](breaking-changes/architecture.md), [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md).
+- Per-feature playbooks (which assume these recipes are in your toolkit): [`features/`](features/).
+- v2 design context (the patterns you're migrating *to*): [`../integration/recipes/`](../integration/recipes/).

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

@@ -0,0 +1,18 @@
+# Migration reference — `@sodax/sdk` v1 → v2
+
+Tables. Each file is a focused lookup; the prose explanations live in `../breaking-changes/` and `../features/`.
+
+| File | Contents |
+|---|---|
+| [`deleted-exports.md`](deleted-exports.md) | Comprehensive table of every removed v1 export with its v2 replacement: spoke-provider classes & guards, static lookup tables, type aliases, constants, error types, per-feature param-shape changes. |
+| [`sodax-config.md`](sodax-config.md) | `SodaxConfig` constructor reshape: `swaps` vs `solver` field split, `rpcConfig` keying change, `hubProviderConfig` → `hubConfig` rename, `configService` injection point gone. |
+| [`error-code-crosswalk.md`](error-code-crosswalk.md) | Per-feature v1 module-error code → v2 `(feature, code, context)` tuple. Money market, swap, staking, bridge, migration, DEX, relay, partner, recovery. |
+| [`return-shapes.md`](return-shapes.md) | Per-method return-shape diffs. `CreateIntentResult` tuple→object, every cross-chain mutation now returns `TxHashPair`, `getBridgeableAmount` returns `BridgeLimit`, `getStakeRatio` returns a tuple, etc. |
+
+## Cross-references
+
+- [`../README.md`](../README.md) — migration overview.
+- [`../checklist.md`](../checklist.md) — top-level migration checklist.
+- [`../ai-rules.md`](../ai-rules.md) — DO / DO NOT / workflow.
+- [`../breaking-changes/`](../breaking-changes/) — the prose that explains what these tables tabulate.
+- v2 design context: [`../../integration/architecture.md`](../../integration/architecture.md) and [`../../integration/reference/`](../../integration/reference/).

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

@@ -0,0 +1,126 @@
+# Deleted / replaced exports inventory
+
+Every v1 export that's gone or repurposed in v2 — and its v2 successor. If you see `error TS2305: Module '"@sodax/sdk"' has no exported member '<X>'`, find `<X>` in the left column.
+
+Two categories worth distinguishing:
+- **Truly deleted** — the v1 symbol is gone; an import will fail compile (`TS2305`).
+- **Name preserved, shape replaced** — a v1 `import` still compiles, but the runtime shape changed. Silent breakage if you read v1-only fields.
+
+> Scope note: This doc only lists symbols that **don't import anymore** or **silently changed shape**. For v1 static constants that are still exported in v2 but should yield to the dynamic service API, see [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 2.
+
+### Spoke-provider classes + guards
+
+| v1 export | v2 replacement |
+|---|---|
+| `EvmSpokeProvider` (class) | None — pass `walletProvider` + `srcChainKey` to SDK calls. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 1. |
+| `SonicSpokeProvider` (class) | Same. |
+| `SolanaSpokeProvider` (class) | Same. |
+| `SuiSpokeProvider` (class) | Same. |
+| `IconSpokeProvider` (class) | Same. |
+| `InjectiveSpokeProvider` (class) | Same. |
+| `StellarSpokeProvider` / `StellarBaseSpokeProvider` (classes) | Same. |
+| `StacksSpokeProvider` (class) | Same. |
+| `BitcoinSpokeProvider` (class) | Same. |
+| `NearSpokeProvider` (class) | Same. |
+| `SpokeProvider` (union type) | None — broad-union typing replaced by `srcChainKey: SpokeChainKey` + `walletProvider: GetWalletProviderType<K>`. |
+| `isEvmSpokeProvider`, `isSolanaSpokeProvider`, `isBitcoinSpokeProvider`, `isStellarSpokeProvider`, `isIconSpokeProvider`, `isSuiSpokeProvider`, `isInjectiveSpokeProvider`, `isStacksSpokeProvider`, `isNearSpokeProvider`, `isSonicSpokeProvider` | `getChainType(chainKey) === '<FAMILY>'`, or family-level `is<Family>ChainKeyType(chainKey)` from `@sodax/sdk`. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 1. |
+
+### Static lookup tables and helpers
+
+| v1 export | v2 replacement |
+|---|---|
+| `hubAssets` | `XToken.vault` / `XToken.hubAsset` baked in; or `sodax.config.getOriginalAssetAddress(...)`. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 2. |
+| `getHubChainConfig()` (free function) | `sodax.config.getHubChainConfig()` (now a method on `ConfigService`, accessed via the `Sodax` instance). |
+| `EvmWalletAbstraction` (class) | `sodax.hubProvider.getUserHubWalletAddress(...)` (the equivalent functionality lives on `EvmHubProvider`, accessed via the `Sodax` instance). |
+
+### Type aliases
+
+| v1 export | v2 replacement |
+|---|---|
+| `ChainId` (type) | `SpokeChainKey` (or `ChainKey` for the broader union including the hub). |
+| `SpokeChainId` (type) | `SpokeChainKey`. |
+| `EvmChainId` (type) | `EvmChainKey` (subset of `SpokeChainKey`). |
+| `HubChainId` (type) | `HubChainKey` (literal `'sonic'`). |
+| `Token` (type) | `XToken`. See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 4. |
+| `AddressType` (type — `'P2PKH' \| 'P2SH' \| 'P2WPKH' \| 'P2TR'`) | `BtcAddressType` (renamed; same shape). See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 7. |
+
+> Note: `BtcWalletAddressType` (`'taproot' | 'segwit'`, wallet-UI choice) is preserved in v2 with the same shape — it is **not** the same thing as `BtcAddressType` (on-chain address format). They coexist; do not blindly rename one to the other.
+
+### Constants
+
+| v1 export | v2 replacement |
+|---|---|
+| `*_MAINNET_CHAIN_ID` (20 constants) | `ChainKeys.*` (single namespace). See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 1 for the full table. |
+
+### Wallet shims
+
+| v1 export | v2 replacement |
+|---|---|
+| `CustomProvider` (Hana-wallet window typedecl) | None. Window declaration becomes `unknown` or imports directly from the wallet vendor. Low-level Hana-extension helper functions (`requestAddress`, `requestSigning`, `requestJsonRpc`) ship from `@sodax/sdk` for consumers building their own Hana-based `IIconWalletProvider`. |
+
+### Error types and guards
+
+#### Error types — name preserved, shape replaced
+
+The following v1 error types were **plain object literals** `{ code: T; data: GetXxxError<T> }`. v2 keeps the same export names but redefines them as type aliases for the canonical `SodaxError<NarrowCode>` class instance. **A v1 `import { MoneyMarketError } from '@sodax/sdk'` still compiles** — but reading `err.data` will silently fail at runtime because the v2 shape is `{ name, code, feature, message, stack, context, cause }`. Treat these as "shape replaced" rather than deleted.
+
+| v1 shape | v2 shape | What to read |
+|---|---|---|
+| `MoneyMarketError<MoneyMarketErrorCode> = { code, data }` | `MoneyMarketError = SodaxError<MoneyMarketErrorCode>` (class instance) | `err.code`, `err.feature === 'moneyMarket'`, `err.context`, `err.cause`. See [`error-code-crosswalk.md`](error-code-crosswalk.md) for code crosswalk. |
+| `BridgeError<BridgeErrorCode> = { code, data }` | `BridgeError = SodaxError<BridgeErrorCode>` | Same pattern; `err.feature === 'bridge'`. |
+| `StakingError<StakingErrorCode> = { code, data }` | `StakingError = SodaxError<StakingErrorCode>` | Same pattern; `err.feature === 'staking'`. |
+| `MigrationError<MigrationErrorCode> = { code, data }` | `MigrationError = SodaxError<MigrationErrorCode>` | Same pattern; `err.feature === 'migration'`. |
+
+#### Error types — fully deleted
+
+| v1 export | v2 replacement |
+|---|---|
+| `IntentError<IntentErrorCode>`, plus `IntentErrorCode`, `IntentErrorData` | `SwapError = SodaxError<SwapErrorCode>` (renamed). `feature: 'swap'`. |
+| `AssetServiceError<AssetServiceErrorCode>`, plus the union | `DexError = SodaxError<DexErrorCode>`. `feature: 'dex'`. |
+| `ConcentratedLiquidityError<ConcentratedLiquidityErrorCode>`, plus the union | `DexError = SodaxError<DexErrorCode>` (asset + CL collapsed into one feature). |
+| `RelayError<RelayErrorCode>`, plus the union | `SodaxError<C>` with the lower-level relay code on `error.context.relayCode`. |
+| `SetSwapPreferenceError`, `CreateIntentAutoSwapError`, `WaitIntentAutoSwapError`, `UnknownIntentAutoSwapError`, `ExecuteIntentAutoSwapError` (5 distinct partner error types in `PartnerFeeClaimService.ts`) | `PartnerError = SodaxError<PartnerErrorCode>`. `feature: 'partner'`. |
+
+#### Type guards — deleted
+
+v1 only exposed **specific per-failure-mode guards**. v2 deleted all of these and instead ships **feature-level guards** + helper builders (`isFeatureError('<feature>')`, `isCodeMember(codeSet)`).
+
+| v1 deleted guard | v2 replacement |
+|---|---|
+| `isIntentCreationFailedError(e)` | `isSwapCreateIntentError(e)` or `isSodaxError(e) && e.code === 'INTENT_CREATION_FAILED' && e.feature === 'swap'`. |
+| `isIntentSubmitTxFailedError(e)` | `isSodaxError(e) && e.code === 'TX_SUBMIT_FAILED'`. |
+| `isIntentPostExecutionFailedError(e)` | `isSodaxError(e) && e.feature === 'swap' && e.code === 'EXECUTION_FAILED' && e.context?.phase === 'postExecution'`. |
+| `isWaitUntilIntentExecutedFailed(e)` | `isSodaxError(e) && e.feature === 'swap' && e.code === 'RELAY_TIMEOUT'`. The v1 guard fired when the destination packet never reached `executed`; in v2 that surfaces as the unified `RELAY_TIMEOUT` code (with the underlying relay code on `error.context.relayCode`). |
+| `isIntentCreationUnknownError(e)` | `isSodaxError(e) && e.code === 'UNKNOWN' && e.feature === 'swap'`. |
+| `isMoneyMarketSubmitTxFailedError`, `isMoneyMarketRelayTimeoutError`, `isMoneyMarketCreate{Supply,Borrow,Withdraw,Repay}IntentFailedError`, `isMoneyMarket{Supply,Borrow,Withdraw,Repay}UnknownError` (10 specific guards) | `isMoneyMarketError(e)` (new in v2) for the feature-level check, then narrow on `e.code` / `e.context.action`. |
+| `isCreateIntentAutoSwapError`, `isWaitIntentAutoSwapError`, `isUnknownIntentAutoSwapError`, `isSetSwapPreferenceError` (4 partner guards) | `isPartnerError(e)` (new in v2) for the feature-level check, then narrow on `e.code` / `e.context.action`. |
+
+> Note: `isMoneyMarketError`, `isBridgeError`, `isStakingError`, `isMigrationError`, `isSwapError`, `isDexError`, `isPartnerError`, `isRecoveryError` did **not** exist in v1 — v2 added them as new feature-level guards alongside `isSodaxError` and the `isFeatureError('<feature>')` factory. See [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md) § 6 for migration patterns.
+
+### Per-feature param shape
+
+These types changed shape (typically: gained a generic `<K extends SpokeChainKey>`, gained `srcChainKey` and `srcAddress` required fields). The v1 names still exist but with a different signature — fixing imports won't compile, you also need to update construction.
+
+| v1 type | v2 type | Required additions in v2 |
+|---|---|---|
+| `MoneyMarketSupplyParams` | `MoneyMarketSupplyParams<K extends SpokeChainKey>` | `srcChainKey: K`, `srcAddress: GetAddressType<K>` |
+| `MoneyMarketBorrowParams` | `MoneyMarketBorrowParams<K>` | Same; plus optional `dstChainKey`, `dstAddress` for cross-chain. |
+| `MoneyMarketWithdrawParams` | `MoneyMarketWithdrawParams<K>` | Same. |
+| `MoneyMarketRepayParams` | `MoneyMarketRepayParams<K>` | Same; plus optional `dstChainKey`/`dstAddress` (debt chain). |
+| `StakeParams`, `UnstakeParams`, `InstantUnstakeParams`, `ClaimParams`, `CancelUnstakeParams` | All gained `<K>` generic | `srcChainKey: K`, `srcAddress: GetAddressType<K>`. v1 `account` field renamed to `srcAddress`. |
+| `MigrationParams` | `MigrationParams<K>` | Same. |
+| `UnifiedBnUSDMigrateParams` | `UnifiedBnUSDMigrateParams<K>` | Same. |
+| `CreateAssetDepositParams`, `CreateAssetWithdrawParams`, `ClSupplyParams`, `ClIncreaseLiquidityParams`, `ClDecreaseLiquidityParams`, `ClClaimRewardsParams` | All gained `<K>` generic | `srcChainKey`, `srcAddress`. |
+| `CreateIntentParams`, `CreateLimitOrderParams` | All gained `<K>` generic | Field renames `srcChain` → `srcChainKey`, `dstChain` → `dstChainKey` (v1 `srcChain` was a chain id type, now `srcChainKey: K`). |
+
+The [`error TS1360`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-2.html#smarter-type-alias-preservation) pattern (`Type '{ token, amount, action }' does not satisfy the expected type 'MoneyMarketSupplyParams'`) is the typecheck signature: a literal that matches v1's shape but missing v2's required `srcChainKey` and `srcAddress`. Add both.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — migration reference index.
+- [`../README.md`](../README.md) — migration overview.
+- [`../checklist.md`](../checklist.md) — top-level migration checklist.
+- [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 2 — guidance for v1 static constants that are still exported in v2.