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

package/ai-exported/migration/breaking-changes/result-and-errors.md

@@ -0,0 +1,363 @@
+# Result and error model breaking changes — v1 → v2
+
+The runtime contract of every async method changed. v1 threw on failure; v2 resolves `{ ok: false, error }`. v1 had per-module typed-error unions; v2 has a single canonical `SodaxError<C>` with a closed 13-code vocabulary.
+
+This is the largest behavioral change in v2. A consumer that ignores it will compile against v2 (with help from the type system) but silently swallow failures — a v1-style `try { await sodax.<method>(...) } catch` does **not** catch SDK-level failures, because they don't throw.
+
+Read after [`type-system.md`](type-system.md) and [`architecture.md`](architecture.md).
+
+## Section index
+
+1. [`Result<T>` — the new return contract](#1-resultt--the-new-return-contract)
+2. [`SodaxError<C>` — the canonical error class](#2-sodaxerrorc--the-canonical-error-class)
+3. [The 13-code vocabulary](#3-the-13-code-vocabulary)
+4. [Reference tables — moved](#4-reference-tables--moved) (v1 ↔ v2 code crosswalk and per-method return-shape diffs)
+5. [Carve-out: `BalnSwapService` still throws](#5-carve-out-balnswapservice-still-throws)
+6. [Migration patterns](#6-migration-patterns)
+
+---
+
+## 1. `Result<T>` — the new return contract
+
+### Shape
+
+`Result<T, E = Error | unknown>` is defined in `@sodax/types` (re-exported from `@sodax/sdk`):
+
+```ts
+type Result<T, E = Error | unknown> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+```
+
+Every async public method on every feature service in v2 returns `Promise<Result<T, SodaxError<C>>>`. There is no `throw` across a service boundary.
+
+### Where it applies
+
+The **complete list** of services whose public methods return `Result<T>`:
+
+- `SwapService` (every async method)
+- `MoneyMarketService` (every async method)
+- `BridgeService` (every async method)
+- `StakingService` (every async method except `StakingLogic.*` static helpers — see § 5)
+- `MigrationService` (every async method except `BalnSwapService` lock-management methods — see § 5)
+- `DexService` / `ClService` / `AssetService` (every async method)
+- `PartnerService`
+- `RecoveryService`
+- `BackendApiService`
+- `SpokeService` (router-level helpers)
+- `IConfigApi` implementations (every method)
+
+Private helpers may still throw; the outer `try/catch` at each public method's boundary absorbs those and converts them to `{ ok: false, error }`.
+
+### Propagation pattern
+
+The canonical pattern across the SDK:
+
+```ts
+// Forward a sub-Result without re-wrapping.
+// (TypeScript narrows the error union — narrower codes are structurally
+// assignable to wider ones, so this typechecks even if `sub` returns a smaller
+// code union than the outer method.)
+const sub = await this.subOperation();
+if (!sub.ok) return sub;
+
+// Success
+return { ok: true, value: /* … */ };
+
+// Outer catch at every public method's boundary
+catch (error) {
+  if (isMethodError(error)) return { ok: false, error };
+  return {
+    ok: false,
+    error: new SodaxError('EXECUTION_FAILED', '<short message>', {
+      feature: 'swap',
+      cause: error,
+      context: { action: 'createIntent', phase: 'execution' },
+    }),
+  };
+}
+```
+
+There is **no** `toResult` / `tryCatch` / `safeCall` helper. Explicit `try/catch` at each method boundary is the deliberate convention.
+
+### Branching
+
+```ts
+const result = await sodax.swaps.createIntent({ params, raw: false, walletProvider });
+if (!result.ok) {
+  if (isSodaxError(result.error)) {
+    if (result.error.code === 'RELAY_TIMEOUT') { /* retry */ }
+    if (result.error.code === 'INTENT_CREATION_FAILED') { /* show input error */ }
+  }
+  return;
+}
+const { tx, intent, relayData } = result.value;
+```
+
+### Migration mechanics
+
+```diff
+- try {
+-   const result = await sodax.swaps.createIntent({ intentParams, spokeProvider });
+-   const [spokeTxHash, intent, relayData] = result;
+-   /* … */
+- } catch (e) {
+-   if (e instanceof IntentError && e.code === 'CREATE_INTENT_FAILED') { /* … */ }
+- }
+
++ const result = await sodax.swaps.createIntent({ params, raw: false, walletProvider });
++ if (!result.ok) {
++   if (isSodaxError(result.error) && result.error.code === 'INTENT_CREATION_FAILED') { /* … */ }
++   return;
++ }
++ const { tx: spokeTxHash, intent, relayData } = result.value;  // object, not tuple — see ../reference/return-shapes.md
+```
+
+### Pitfall
+
+A `try { await sodax.<method>(...) } catch` block in v2 only catches **exceptions** thrown from inside the call (e.g. a bug, a missing argument, a synchronous validation thrown from the wrapper). It does **not** catch SDK-level failures like `RELAY_TIMEOUT` — those resolve to `{ ok: false, error }` and skip your `catch` entirely. The legacy `try/catch` can stay as defense-in-depth, but you **must** also branch on `result.ok`.
+
+---
+
+## 2. `SodaxError<C>` — the canonical error class
+
+### Shape
+
+```ts
+class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
+  readonly code: C;                 // closed 13-code reason union
+  readonly feature: SodaxFeature;   // 'swap' | 'moneyMarket' | 'bridge' | 'staking' | 'migration' | 'dex' | 'partner' | 'recovery'
+  readonly cause?: unknown;
+  readonly context?: SodaxErrorContext;
+
+  toJSON(): SodaxErrorJSON<C>;      // canonical logger surface (Sentry/Pino/Datadog)
+}
+```
+
+### Discrimination contract
+
+The `(feature, code)` pair is the canonical discriminator. Loggers emit it as a tag pair; consumer switch statements branch on it. **Do not** string-match on `error.message` — messages are short prose and may change between releases. Codes are closed and stable.
+
+### `isSodaxError` over `instanceof`
+
+```ts
+import { isSodaxError } from '@sodax/sdk';
+
+if (isSodaxError(e)) {
+  // e: SodaxError<SodaxErrorCode>
+}
+```
+
+`isSodaxError` walks `e.name === 'SodaxError'` + a `code: string` + `feature: string` shape check. Prefer it over bare `instanceof SodaxError` — `instanceof` returns `false` when `@sodax/sdk` is loaded twice in the same bundle (a real-world hazard with monorepos and dual ESM/CJS, especially in apps with mixed package resolution).
+
+### `error.context`
+
+A free-form metadata bag with reserved fields:
+
+```ts
+type SodaxErrorContext = {
+  action?: string;            // feature operation (e.g. 'supply', 'stake', 'migrateBaln')
+  phase?: SodaxPhase;         // 'validate' | 'intentCreation' | 'verify' | 'submit' | 'relay' | 'destinationExecution' | 'execution' | 'postExecution' | 'approve' | 'allowanceCheck' | 'gasEstimation' | 'lookup'
+  srcChainKey?: string;
+  dstChainKey?: string;
+  relayCode?: 'SUBMIT_TX_FAILED' | 'RELAY_TIMEOUT' | 'RELAY_POLLING_FAILED' | 'UNKNOWN';
+  api?: 'solver' | 'backend';
+  method?: string;            // names the read-only method on LOOKUP_FAILED
+  direction?: 'forward' | 'reverse';  // migration's bnUSD-only
+  field?: string;             // VALIDATION_FAILED specifics
+  reason?: string;
+  [key: string]: unknown;     // open at the index signature
+};
+```
+
+### `error.toJSON()` for logging
+
+`JSON.stringify(error)` invokes `toJSON()` automatically. The serializer:
+
+- Coerces `bigint` to string anywhere in `context`.
+- Walks `cause` chains up to depth 3.
+- Stringifies `Date`, `Map`, `Set`, `Error`, and class instances safely.
+- Handles cycles (depth-bounded at 5).
+
+Consumer-side logging integration:
+
+```ts
+// Sentry
+Sentry.captureException(error, { tags: { feature: error.feature, code: error.code, action: error.context?.action } });
+
+// Pino / Winston
+logger.error({ err: error }, 'sodax operation failed');
+```
+
+---
+
+## 3. The 13-code vocabulary
+
+| Code | Meaning | Common context fields |
+|---|---|---|
+| `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` |
+| `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'` |
+| `EXECUTION_FAILED` | Orchestrator-level catch-all (post-relay business logic). | `action`, `phase: 'execution'` or `'postExecution'` |
+| `TX_VERIFICATION_FAILED` | Spoke-side `verifyTxHash` returned false / threw. | `phase: 'verify'`, `srcChainKey` |
+| `TX_SUBMIT_FAILED` | Spoke tx landed; relay POST submit failed. | `phase: 'submit'`, `relayCode: 'SUBMIT_TX_FAILED'` |
+| `RELAY_TIMEOUT` | Destination packet didn't reach `executed` within timeout. | `phase: 'relay'`, `srcChainKey`, `dstChainKey`, `relayCode: 'RELAY_TIMEOUT'` |
+| `RELAY_FAILED` | Relay polling outage / unrecognised relay error. | `phase: 'relay'`, `relayCode` |
+| `APPROVE_FAILED` | Token approval call failed. | `phase: 'approve'` |
+| `ALLOWANCE_CHECK_FAILED` | Reading on-chain allowance failed. (Distinct from `LOOKUP_FAILED` for retry semantics.) | `phase: 'allowanceCheck'` |
+| `GAS_ESTIMATION_FAILED` | Gas estimation returned an error. (Distinct for retry semantics.) | `phase: 'gasEstimation'` |
+| `LOOKUP_FAILED` | Read-only on-chain query / off-chain config fetch. | `method`, `phase: 'lookup'` |
+| `EXTERNAL_API_ERROR` | Upstream API call failed (solver, backend). | `api: 'solver' \| 'backend'`, plus `solverCode`/`solverDetail` for solver |
+| `UNKNOWN` | Last-resort catch in an outer `try`. Should be rare in production. | (none guaranteed) |
+
+### Per-method narrow unions
+
+Every public method declares a `<MethodName>ErrorCode` narrow union built via `Extract<SodaxErrorCode, ...>`. Switch exhaustively over the narrow union when you know the method:
+
+```ts
+type CreateSupplyIntentErrorCode = Extract<
+  SodaxErrorCode,
+  'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN'
+>;
+
+// In the queryFn or call site:
+const result = await sodax.moneyMarket.createSupplyIntent({ params, raw: true });
+if (!result.ok) {
+  switch (result.error.code) {
+    case 'VALIDATION_FAILED':      /* show input error */ break;
+    case 'INTENT_CREATION_FAILED': /* show "couldn't build supply intent" */ break;
+    case 'UNKNOWN':                /* fallback */ break;
+  }
+}
+```
+
+The narrow unions are exported from each feature's `errors.ts` (e.g. `@sodax/sdk` re-exports `SupplyErrorCode`, `BorrowErrorCode`, `BridgeErrorCode`, `StakeErrorCode`, etc.). See [`../../integration/reference/`](../../integration/reference/) § "Error codes" for the full catalogue.
+
+### Read-method partition
+
+`LOOKUP_FAILED` is the catch-all for read-only methods. Its partition lives on `error.context.method`:
+
+```ts
+if (result.error.code === 'LOOKUP_FAILED') {
+  switch (result.error.context?.method) {
+    case 'getStakingInfo': /* … */ break;
+    case 'getBridgeableAmount': /* … */ break;
+    case 'getUnstakingInfoWithPenalty': /* … */ break;
+  }
+}
+```
+
+This avoids inflating the global code count (`getStakingInfoFailed`, `getBridgeableAmountFailed`, …) while keeping per-method retry semantics inspectable.
+
+---
+
+## 4. Reference tables — moved
+
+The two reference-grade tables that used to live in this file (the **v1 ↔ v2 code crosswalk** and the **per-method return-shape diffs**) have moved into `../reference/`:
+
+- [`../reference/error-code-crosswalk.md`](../reference/error-code-crosswalk.md) — every v1 module-error code → v2 `(feature, code, context)` mapping, per feature.
+- [`../reference/return-shapes.md`](../reference/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.).
+
+The prose on shape semantics stays here; the lookup tables live in `../reference/`.
+
+## 5. Carve-out: `BalnSwapService` still throws
+
+The lock-management methods on `BalnSwapService` (a sub-service of `MigrationService`) **do not** return `Result<T>` in v2. They keep the v1 throw-on-error contract:
+
+- `BalnSwapService.claim()`
+- `BalnSwapService.claimUnstaked()`
+- `BalnSwapService.stake()`
+- `BalnSwapService.unstake()`
+- `BalnSwapService.cancelUnstake()`
+- `BalnSwapService.getDetailedUserLocks()`
+
+This is **technical debt**, marked for cleanup in a future release. Until then, your code must `try/catch` these specific calls. Every other public async method on every other service in v2 returns `Result<T>`.
+
+---
+
+## 6. Migration patterns
+
+### Convert one call site (the typical pattern)
+
+```diff
+  try {
+-   const result = await sodax.moneyMarket.supply({ params: supplyParams, spokeProvider });
+-   const txHash = result;
++   const result = await sodax.moneyMarket.supply({ params: supplyParams, raw: false, walletProvider });
++   if (!result.ok) {
++     setError(getMmErrorText(result.error));
++     return;
++   }
++   const { srcChainTxHash } = result.value;
++   /* … */
+  } catch (e) {
+    /* keep as defense-in-depth net for unexpected throws */
+  }
+```
+
+### Adapt a `getXxxErrorText` helper
+
+If your v1 code has a helper that branches on `error.code`, the minimal change is to map v2 shape onto the v1 shape at the boundary:
+
+```ts
+// Module-scope helper
+function adaptToV1Shape(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: error.message, message: error.message };
+  if (typeof error === 'object') return error as { code?: string; message?: string; data?: { error?: unknown } };
+  return null;
+}
+
+// Existing branches (sdkError.code === 'SUPPLY_FAILED') keep working — until you migrate
+// them properly to (feature, code) tuples per ../reference/error-code-crosswalk.md.
+```
+
+### Use the per-feature guard factory for routing
+
+```ts
+const isSwapError = isFeatureError('swap');
+const isMmError = isFeatureError('moneyMarket');
+const isBridgeError = isFeatureError('bridge');
+
+if (!result.ok) {
+  if (isSwapError(result.error)) router.push('/swap-error');
+  else if (isMmError(result.error)) router.push('/loan-error');
+  else if (isBridgeError(result.error)) router.push('/bridge-error');
+  else router.push('/error');
+}
+```
+
+### A `throwIfError` shim for incremental migration
+
+If you can't refactor every call site in one pass:
+
+```ts
+// Drop into a shared lib
+export function throwIfError<T>(result: Result<T, unknown>): T {
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+// Use at call sites where you haven't migrated the surrounding error handling yet:
+const { tx, intent } = throwIfError(
+  await sodax.swaps.createIntent({ params, raw: false, walletProvider }),
+);
+```
+
+This is **transitional**. Once your error-handling tree is updated, remove `throwIfError` and branch on `result.ok` directly. See [`../recipes.md`](../recipes.md) § "Result adapter" for a fuller version.
+
+---
+
+## Cross-references
+
+- Type-level renames (deleted error types, return-type renames): [`type-system.md`](type-system.md) §§ 6, 10.
+- Architecture reshape (relay layer, mapRelayFailure, sodaxInvariant, isSodaxError): [`architecture.md`](architecture.md) §§ 3, 4.
+- v2 design context (Result propagation, error model): [`../../integration/architecture.md`](../../integration/architecture.md) and [`../../integration/recipes/`](../../integration/recipes/) § "Result handling".
+- Per-feature narrow code unions: [`../../integration/reference/`](../../integration/reference/) § "Error codes".
+- Per-feature playbooks (with `getXxxErrorText` adapters in context): [`../features/`](../features/).

package/ai-exported/migration/breaking-changes/type-system.md

@@ -0,0 +1,321 @@
+# Type-system breaking changes — v1 → v2
+
+Every type-level rename and shape change introduced by v2. Fix these first — once your imports compile, every other migration step is tractable. The errors you'll see during this phase live in three buckets: **import resolution** (a symbol moved or was deleted), **field access** (a field renamed), and **shape mismatch** (a generic added a required parameter, a return type changed).
+
+> v1 source the comparisons below cite: `github.com/icon-project/sodax-frontend` (branch `sdk-v1-main`), `packages/sdk` and `packages/types`. v2 source: this package's `src/`.
+
+## Section index
+
+1. [Chain identifiers](#1-chain-identifiers) — `*_MAINNET_CHAIN_ID` → `ChainKeys.*`. The single biggest mechanical migration.
+2. [`@sodax/types` package surface](#2-sodaxtypes-package-surface) — what to import, what got renamed, what got deleted.
+3. [Wallet-provider typing](#3-wallet-provider-typing) — `GetWalletProviderType<K>` and `WalletProviderSlot<K, Raw>` replace ad-hoc spoke-provider classes.
+4. [`Token` / `XToken` field renames](#4-token--xtoken-field-renames) — `xChainId` → `chainKey`; `Token` → `XToken`.
+5. [`RpcConfig` reshape](#5-rpcconfig-reshape) — now keyed by `ChainKey` values; chain-family-specific shapes for Bitcoin and Stellar.
+6. [`IConfigApi` Result-wrapping](#6-iconfigapi-result-wrapping) — every method returns `Promise<Result<T>>`.
+7. [Address-type rename](#7-address-type-rename) — `AddressType` → `BtcAddressType`.
+8. [Wallet-provider `chainType` discriminant](#8-wallet-provider-chaintype-discriminant) — every `I*WalletProvider` declares a literal field.
+9. [`ChainId` / `SpokeChainId` → `SpokeChainKey`](#9-chainid--spokechainid--spokechainkey) — type alias rename.
+10. [Deleted module-error types](#10-deleted-module-error-types) — covered structurally here, semantics in [`result-and-errors.md`](result-and-errors.md).
+
+---
+
+## 1. Chain identifiers
+
+v1 exported one constant per chain (`SONIC_MAINNET_CHAIN_ID`, `ARBITRUM_MAINNET_CHAIN_ID`, …). v2 collapses them into a single `ChainKeys` object whose values are the same string union exposed as the `ChainKey` type. The constants and their old union (`SpokeChainId` / `ChainId`) are deleted.
+
+### Import migration
+
+```diff
+- import {
+-   SONIC_MAINNET_CHAIN_ID,
+-   ARBITRUM_MAINNET_CHAIN_ID,
+-   AVALANCHE_MAINNET_CHAIN_ID,
+-   // ...
+- } from '@sodax/types';
++ import { ChainKeys } from '@sodax/sdk'; // re-exported from @sodax/types
+```
+
+> Prefer importing `ChainKeys` from `@sodax/sdk` — see [§2](#2-sodaxtypes-package-surface). Importing from `@sodax/types` still works but adds an unnecessary peer dependency.
+
+### Full mapping table
+
+| v1 constant | v2 `ChainKeys.*` | String value |
+|---|---|---|
+| `SONIC_MAINNET_CHAIN_ID` | `ChainKeys.SONIC_MAINNET` | `'sonic'` |
+| `ARBITRUM_MAINNET_CHAIN_ID` | `ChainKeys.ARBITRUM_MAINNET` | `'0xa4b1.arbitrum'` |
+| `AVALANCHE_MAINNET_CHAIN_ID` | `ChainKeys.AVALANCHE_MAINNET` | `'0xa86a.avax'` |
+| `BASE_MAINNET_CHAIN_ID` | `ChainKeys.BASE_MAINNET` | `'0x2105.base'` |
+| `BSC_MAINNET_CHAIN_ID` | `ChainKeys.BSC_MAINNET` | `'0x38.bsc'` |
+| `ETHEREUM_MAINNET_CHAIN_ID` | `ChainKeys.ETHEREUM_MAINNET` | `'ethereum'` |
+| `HYPEREVM_MAINNET_CHAIN_ID` | `ChainKeys.HYPEREVM_MAINNET` | `'hyper'` |
+| `ICON_MAINNET_CHAIN_ID` | `ChainKeys.ICON_MAINNET` | `'0x1.icon'` |
+| `INJECTIVE_MAINNET_CHAIN_ID` | `ChainKeys.INJECTIVE_MAINNET` | `'injective-1'` |
+| `KAIA_MAINNET_CHAIN_ID` | `ChainKeys.KAIA_MAINNET` | `'0x2019.kaia'` |
+| `LIGHTLINK_MAINNET_CHAIN_ID` | `ChainKeys.LIGHTLINK_MAINNET` | `'lightlink'` |
+| `NEAR_MAINNET_CHAIN_ID` | `ChainKeys.NEAR_MAINNET` | `'near'` |
+| `OPTIMISM_MAINNET_CHAIN_ID` | `ChainKeys.OPTIMISM_MAINNET` | `'0xa.optimism'` |
+| `POLYGON_MAINNET_CHAIN_ID` | `ChainKeys.POLYGON_MAINNET` | `'0x89.polygon'` |
+| `REDBELLY_MAINNET_CHAIN_ID` | `ChainKeys.REDBELLY_MAINNET` | `'redbelly'` |
+| `SOLANA_MAINNET_CHAIN_ID` | `ChainKeys.SOLANA_MAINNET` | `'solana'` |
+| `STACKS_MAINNET_CHAIN_ID` | `ChainKeys.STACKS_MAINNET` | `'stacks'` |
+| `STELLAR_MAINNET_CHAIN_ID` | `ChainKeys.STELLAR_MAINNET` | `'stellar'` |
+| `SUI_MAINNET_CHAIN_ID` | `ChainKeys.SUI_MAINNET` | `'sui'` |
+| `BITCOIN_MAINNET_CHAIN_ID` | `ChainKeys.BITCOIN_MAINNET` | `'bitcoin'` |
+
+### Bulk codemod
+
+```bash
+# Find — preserves capture group
+grep -rE '(\w+)_MAINNET_CHAIN_ID' src/
+
+# Sed (one-shot)
+find src -type f -name '*.ts' -o -name '*.tsx' | xargs sed -i '' -E 's/([A-Z_]+)_MAINNET_CHAIN_ID/ChainKeys.\1_MAINNET/g'
+```
+
+After replacement, fix import statements: remove the individual constants, add `ChainKeys`. See [`../recipes.md`](../recipes.md) § "Codemod patterns" for a more robust `ts-morph` variant.
+
+### Pitfalls
+
+1. **`ChainKeys.ICON_MAINNET` is a string `'0x1.icon'`, not the legacy numeric ID.** Anywhere v1 did `Number(chainId)` for ICON, the v2 result is `NaN`. Use string equality (`chainKey === ChainKeys.ICON_MAINNET`) and audit numeric coercions.
+2. **`SONIC_MAINNET` is `'sonic'`, not `'0x92.sonic'`** — it's the simple string `'sonic'` because Sonic is the hub chain and treated specially by routing.
+3. **Don't confuse `ChainKey` with relay chain IDs.** Read shapes like `Intent.srcChain` and `Intent.dstChain` are still `IntentRelayChainId` (bigint) — those did **not** rename. A blanket `srcChain` → `srcChainKey` grep-replace will break Intent reads. Use `sodax.config.getSpokeChainKeyFromIntentRelayChainId(...)` to convert.
+
+---
+
+## 2. `@sodax/types` package surface
+
+### Export reorganization
+
+v1 had a single `packages/types/src/constants/index.ts` barrel exporting all chain IDs and ad-hoc tables. That file is **deleted**. Symbols now live in domain-organized modules: `chains/`, `swap/`, `wallet/`, `bitcoin/`, etc.
+
+| v1 import path | v2 home |
+|---|---|
+| `@sodax/types/btc/...` | `@sodax/types/bitcoin` (path renamed) |
+| `*_MAINNET_CHAIN_ID` from `@sodax/types` constants index | `ChainKeys.*` (single barrel) |
+| `Token` | `XToken` (renamed; see [§4](#4-token--xtoken-field-renames)) |
+| `SpokeChainId` / `ChainId` | `SpokeChainKey` (see [§9](#9-chainid--spokechainid--spokechainkey)) |
+
+### Re-export from `@sodax/sdk`
+
+`@sodax/sdk` v2 barrel re-exports the entire `@sodax/types` surface (`export * from '@sodax/types'` from `src/index.ts`). For consumers, this means:
+
+- **Recommended:** import everything from `@sodax/sdk`. You don't need a separate `@sodax/types` dependency.
+- **Tolerated:** keep importing from `@sodax/types` directly. v2 guarantees type identity (since SDK bundles `@sodax/types` via `noExternal`), but you'll pin two versions instead of one.
+
+### Pitfall
+
+If your `package.json` lists `@sodax/types` as a direct dependency in v2, **remove it**. Letting it float independent of `@sodax/sdk` invites silent version skew on the next minor bump.
+
+---
+
+## 3. Wallet-provider typing
+
+v1 modeled "the wallet to use for chain X" as a class instance: `EvmSpokeProvider`, `SolanaSpokeProvider`, etc. Consumers constructed one and passed it positionally to every SDK call. v2 deletes these classes (see [`architecture.md`](architecture.md) § "Spoke-provider deletion") and replaces the typing with two parameterised aliases:
+
+```ts
+GetChainType<K extends ChainKey>            // 'EVM' | 'BITCOIN' | 'SOLANA' | …
+GetWalletProviderType<K extends ChainKey>   // IEvmWalletProvider | IBitcoinWalletProvider | …
+```
+
+When the caller passes a literal chain key (e.g. `ChainKeys.ETHEREUM_MAINNET`), TypeScript preserves the literal in the generic `K`. From that one literal:
+
+- `GetChainType<K>` resolves to `'EVM'`.
+- `GetWalletProviderType<K>` resolves to `IEvmWalletProvider` (the exact interface, not a broad union).
+
+This is what allows v2 to demand the chain-correct wallet provider at compile time without a runtime check.
+
+### `WalletProviderSlot<K, Raw>` — the discriminator
+
+```ts
+// Conceptual; lives in @sodax/types/common
+export type WalletProviderSlot<K extends ChainKey, Raw extends boolean> =
+  Raw extends true
+    ? { raw: true; walletProvider?: never }
+    : { raw: false; walletProvider: GetWalletProviderType<K> };
+```
+
+Three rules enforced at compile time:
+
+1. **`raw: true`** — `walletProvider` is **forbidden** (`?: never` rejects any value). The method returns a raw, unsigned tx payload. Use for sign-elsewhere flows.
+2. **`raw: false`** — `walletProvider` is **required** and chain-narrowed. The method signs and broadcasts; returns a tx hash.
+3. **No overlap** — TypeScript can't pick a branch unless the discriminator field is present. Forgetting `raw: false` is the #1 v2 typecheck error after migration.
+
+### Migration mechanics
+
+```diff
+  await sodax.swaps.createIntent({
+-   intentParams,
+-   spokeProvider: sourceProvider,
++   params: intentParams,
++   raw: false,
++   walletProvider: sourceWalletProvider,
+  });
+```
+
+For raw-tx building:
+
+```diff
+- // v1 had a separate executeXxx method per chain
+- const tx = await sourceProvider.executeCreateIntent(intentParams);
++ const result = await sodax.swaps.createIntent({ params: intentParams, raw: true });
++ // result.value: { tx: EvmRawTransaction | SolanaRawTransaction | ..., intent, relayData }
+```
+
+### Pitfall
+
+If your wallet provider variable is typed as the broad `IWalletProvider | undefined` union (the typical case when the variable is keyed by a runtime chain-key value rather than a literal), v2 still accepts it — `K` defaults to the broad `SpokeChainKey` union, so `GetWalletProviderType<K>` resolves to the `IWalletProvider` union. For tighter narrowing on a literal chain branch, see [`../recipes.md`](../recipes.md) § "Cast-at-boundary".
+
+---
+
+## 4. `Token` / `XToken` field renames
+
+| v1 | v2 |
+|---|---|
+| `Token` (type name) | `XToken` |
+| `Token.xChainId` | `XToken.chainKey` |
+| `Token.symbol`, `decimals`, `address`, `name` | unchanged |
+| (n/a) | `XToken.vault` — added; the hub-side ERC4626 vault for this token |
+| (n/a) | `XToken.hubAsset` — added; the hub-side wrapped/unified asset address |
+
+Migration:
+
+```diff
+- import type { Token } from '@sodax/types';
++ import type { XToken } from '@sodax/sdk';
+- token.xChainId
++ token.chainKey
+```
+
+### Why `vault` / `hubAsset` matter
+
+v1 consumers reached into a global `hubAssets[chainId][address]` map to get the vault address for a token. **v2 deletes that global** and bakes the data directly into every supported `XToken`. Anywhere v1 walked `hubAssets`, v2 reads `token.vault` or `token.hubAsset` directly. See [`architecture.md`](architecture.md) § "ConfigService replaces static lookups" for the full lookup migration.
+
+### Pitfall
+
+Read shapes like `Intent` and `IntentResponse` from the backend keep `srcChain` / `dstChain` as the **relay** chain id (numeric, `IntentRelayChainId`). They are **not** chain keys and were **not** renamed to `srcChainKey`/`dstChainKey`. Only **request** types (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitSwapTxRequest`) gained the `*ChainKey` field names.
+
+---
+
+## 5. `RpcConfig` reshape
+
+v1 modeled `RpcConfig` as a flat object with one optional URL field per chain. v2 makes it a mapped type keyed by `ChainKey` values, with chain-family-specific shapes:
+
+```ts
+type RpcConfig = {
+  [K in ChainKey]:
+    K extends typeof ChainKeys.BITCOIN_MAINNET ? BitcoinRpcConfig :
+    K extends typeof ChainKeys.STELLAR_MAINNET ? StellarRpcConfig :
+    string  // RPC URL for every other chain
+};
+```
+
+Migration:
+
+```diff
+- rpcConfig.sonic
++ rpcConfig[ChainKeys.SONIC_MAINNET]
+- rpcConfig.btc
++ rpcConfig[ChainKeys.BITCOIN_MAINNET]   // BitcoinRpcConfig (shape, not string)
+```
+
+### Pitfall
+
+Bitcoin and Stellar have richer RPC needs than other chains (multiple endpoints, network params). Their entries in `RpcConfig` are objects, not strings. If your config builder did `rpcConfig.btc = 'https://…'` in v1, that's a type error in v2 — you need the full `BitcoinRpcConfig` shape.
+
+---
+
+## 6. `IConfigApi` Result-wrapping
+
+Every method on the `IConfigApi` contract changed signature in v2. v1 returned plain `Promise<T>` and threw on failure; v2 returns `Promise<Result<T>>` and never throws.
+
+| Method | v1 return | v2 return |
+|---|---|---|
+| `getChains` | `Promise<ChainConfig[]>` | `Promise<Result<GetChainsApiResponse>>` |
+| `getSwapTokens` | `Promise<SwapTokenConfig>` | `Promise<Result<GetSwapTokensApiResponse>>` |
+| `getSwapTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
+| `getMoneyMarketTokens` | `Promise<MMTokenConfig>` | `Promise<Result<GetMoneyMarketTokensApiResponse>>` |
+| `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
+| `getRelayChainIdMap` | (n/a in v1) | `Promise<Result<GetRelayChainIdMapApiResponse>>` (v2-new) |
+
+If you implemented a custom `IConfigApi` (e.g. for a sandbox or test fixture), update every method signature. If you only consumed the default implementation through `Sodax.config`, the SDK already uses `Result` internally — your consumer-side code doesn't see the wrapping.
+
+---
+
+## 7. Address-type rename
+
+The Bitcoin-specific address-type union changed name to free up the generic `AddressType` identifier:
+
+```diff
+- import type { AddressType } from '@sodax/types';
++ import type { BtcAddressType } from '@sodax/sdk';
+```
+
+Value union is unchanged: `'P2PKH' | 'P2SH' | 'P2WPKH' | 'P2TR'`. Custom Bitcoin wallet provider implementations must update the import.
+
+---
+
+## 8. Wallet-provider `chainType` discriminant
+
+Every `I*WalletProvider` interface in v2 declares a `readonly chainType: '<CHAIN>'` literal field. Custom implementations must add the field; consumers can use it for runtime narrowing without `instanceof`:
+
+```ts
+if (walletProvider.chainType === 'EVM') {
+  // walletProvider: IEvmWalletProvider
+}
+if (walletProvider.chainType === 'SOLANA') {
+  // walletProvider: ISolanaWalletProvider
+}
+```
+
+Supported values: `'EVM'`, `'BITCOIN'`, `'SOLANA'`, `'STELLAR'`, `'SUI'`, `'ICON'`, `'INJECTIVE'`, `'STACKS'`, `'NEAR'`.
+
+This replaces v1's `provider instanceof EvmSpokeProvider` discrimination. Cross-bundle `instanceof` is fragile (different `@sodax/sdk` copies in dual ESM/CJS bundles can return false); the literal `chainType` field works regardless.
+
+---
+
+## 9. `ChainId` / `SpokeChainId` → `SpokeChainKey`
+
+Type alias rename. Same value union (the chain-key strings).
+
+```diff
+- import type { ChainId, SpokeChainId } from '@sodax/types';
++ import type { SpokeChainKey } from '@sodax/sdk';
+- function pickChain(id: ChainId): boolean { ... }
++ function pickChain(key: SpokeChainKey): boolean { ... }
+```
+
+Function bodies that compared `chainId === SONIC_MAINNET_CHAIN_ID` need [§1](#1-chain-identifiers)'s constant rename in addition to the type rename.
+
+---
+
+## 10. Deleted module-error types
+
+These types were exported from v1 but are deleted in v2. Replace with `SodaxError<C>` (see [`result-and-errors.md`](result-and-errors.md) for full semantics):
+
+- `MoneyMarketError<MoneyMarketErrorCode>`
+- `IntentError<IntentErrorCode>`
+- `StakingError<StakingErrorCode>`
+- `BridgeError<BridgeErrorCode>`
+- `MigrationError<MigrationErrorCode>`
+- `AssetServiceError<AssetServiceErrorCode>`
+- `ConcentratedLiquidityError<ConcentratedLiquidityErrorCode>`
+- `RelayError<RelayErrorCode>`
+- 5 partner error types (`PartnerFeeClaimError<...>`, etc.) and their `is<Module>Error()` type-guard helpers.
+
+The replacement contract:
+
+```diff
+- if (error instanceof MoneyMarketError && error.code === 'CREATE_SUPPLY_INTENT_FAILED') { … }
++ if (isSodaxError(error) && error.feature === 'moneyMarket' && error.code === 'INTENT_CREATION_FAILED') { … }
+```
+
+The full v1 → v2 code crosswalk lives in [`result-and-errors.md`](result-and-errors.md) § "v1 ↔ v2 code crosswalk".
+
+---
+
+## Cross-references
+
+- Architectural changes (spoke-provider deletion, ConfigService, relay flow): [`architecture.md`](architecture.md).
+- Result/error model details (propagation patterns, code crosswalk, return shapes): [`result-and-errors.md`](result-and-errors.md).
+- v2 design context (what to use instead of each deleted symbol): [`../../integration/architecture.md`](../../integration/architecture.md).
+- Lookup tables (full chain-key list, `I*WalletProvider` interfaces, public API surface): [`../../integration/reference/`](../../integration/reference/).