@sodax/skills 2.0.0-rc.4

package/knowledge/sdk/migration/breaking-changes/type-system.md

@@ -0,0 +1,341 @@
+# 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.
+
+### Exception — partner module read shapes DID rename
+
+The above "read shapes keep `srcChain`/`dstChain`" rule has one exception: **partner module** read shapes also renamed `dstChain` → `dstChainKey`. Specifically:
+
+- `AutoSwapPreferences` (returned by `sodax.partners.getAutoSwapPreferences(queryAddress)`) — field `dstChain` → **`dstChainKey: SpokeChainKey | 'not configured'`**.
+- `SetSwapPreferenceParams` (request type for `setSwapPreference`) — `dstChain` → `dstChainKey: SpokeChainKey`.
+
+```diff
+- // v1
+- const prefs = await partnerFeeClaimService.getAutoSwapPreferences(addr);
+- const destChain: SpokeChainId = prefs.dstChain;
+
++ // v2
++ const result = await sodax.partners.getAutoSwapPreferences(addr);
++ if (!result.ok) return;
++ const destChain: SpokeChainKey | 'not configured' = result.value.dstChainKey;
+```
+
+A blanket grep `dstChain` → `dstChainKey` is safe in the partner module **but** still unsafe in `Intent` / `IntentResponse` reads. Scope grep replacements per file or per import. The general rule for `srcChain` (Intent read field) is unchanged: it remains the relay chain id.
+
+---
+
+## 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/).

package/knowledge/sdk/migration/checklist.md

@@ -0,0 +1,67 @@
+# v1 → v2 cross-cutting migration checklist
+
+Work this top-down. Each step is independent enough to land as its own commit; the order minimizes typecheck noise.
+
+```
+[ ] 1.  Replace every *_MAINNET_CHAIN_ID constant with ChainKeys.* (mechanical).
+        See breaking-changes/type-system.md § "Chain IDs".
+[ ] 2.  Replace every SpokeChainId / ChainId type alias with SpokeChainKey.
+        Mechanical rename. Same value union.
+[ ] 3.  Rename XToken.xChainId → XToken.chainKey. Same for any consumer types
+        that mirrored that field.
+[ ] 4.  Remove any direct dependency on @sodax/types from package.json.
+        v2 @sodax/sdk barrel re-exports the entire types surface.
+[ ] 5.  Delete every *SpokeProvider class instantiation. Replace with passing
+        walletProvider (an I*WalletProvider instance) directly into SDK call
+        payloads.
+[ ] 6.  Replace every isXxxSpokeProvider(provider) guard with a chain-key
+        compare: chainKey === ChainKeys.<X>_MAINNET, or use
+        is<Family>ChainKeyType(chainKey) from @sodax/sdk.
+[ ] 7.  Add { raw: false } discriminator to every signed call shape that
+        previously took a positional spoke provider:
+            { intentParams, spokeProvider }   →   { params, raw: false, walletProvider }
+[ ] 7b. Cross-cutting rename: every payload field named `spokeProvider:` (incl.
+        approve/allowance/utility methods that aren't signed-execution shapes)
+        → `walletProvider:`. Mechanical for the OBJECT-LITERAL field key; don't
+        blindly rename variable names of the same spelling. See
+        [`recipes.md`](recipes.md) § 1 "What's not safe to grep-replace".
+[ ] 8.  Add srcChainKey + srcAddress to every action params object that didn't
+        carry them in v1 (most MM, staking, dex, bridge, migration param shapes).
+[ ] 9.  Convert every await sodax.<service>.<method>(...) call site that previously
+        threw to branch on result.ok / result.error. Use isSodaxError(e) for type
+        narrowing.
+[ ] 10. Delete imports of MoneyMarketError, IntentError, StakingError, BridgeError,
+        MigrationError, AssetServiceError, ConcentratedLiquidityError, RelayError,
+        plus the five Partner error types and their type-guard helpers.
+[ ] 11. Replace any walked global lookup (hubAssets, moneyMarketSupportedTokens,
+        SodaTokens, supportedSpokeChains) with the equivalent sodax.config.* /
+        sodax.moneyMarket.getSupportedTokens*() call. Per-symbol deleted-vs-
+        still-exported status: see breaking-changes/architecture.md § 2.
+[ ] 12. Initialize ConfigService at app startup: await sodax.config.initialize().
+        Falls back to packaged defaults if the backend is unreachable.
+[ ] 13. Add { raw: true } to any read-only allowance check that previously took
+        a spoke provider but didn't actually consult it (the underlying SDK
+        method now requires WalletProviderSlot).
+[ ] 14. For every CreateIntentResult consumer: stop destructuring as a tuple;
+        the v2 shape is { tx, intent, relayData }. Stop destructuring tx-pair
+        results as arrays — every cross-chain mutation returns
+        TxHashPair = { srcChainTxHash, dstChainTxHash }.
+[ ] 15. For every backend-API call site: every method on IConfigApi now returns
+        Promise<Result<T>>. Wrap or unwrap accordingly.
+[ ] 16. (Optional) Adopt isSodaxError(e) over instanceof SodaxError in cross-bundle
+        / cross-realm contexts.
+[ ] 17. Run pnpm tsc --noEmit and start crossing items off the typecheck output.
+        Use each remaining error category to navigate to the relevant per-feature
+        migration file in features/.
+```
+
+After items 1–17 land, the typecheck should be clean. The remaining work is per-feature behavior (cross-chain borrow / repay deltas, staking action discriminators, etc.) covered in [`features/`](features/).
+
+## Reading order while working the checklist
+
+- Items 1–4: [`breaking-changes/type-system.md`](breaking-changes/type-system.md).
+- Items 5–6, 11–12: [`breaking-changes/architecture.md`](breaking-changes/architecture.md).
+- Items 7–8, 13: [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § "WalletProviderSlot" + per-feature files.
+- Items 9–10, 14, 16: [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md).
+- Item 15: [`features/auxiliary-services.md`](features/auxiliary-services.md) § "BackendApiService".
+- Item 17 + the long tail: [`features/`](features/), one per feature you use.

package/knowledge/sdk/migration/features/README.md

@@ -0,0 +1,35 @@
+# Per-feature migration playbooks — v1 → v2
+
+One file per feature, paired with the v2 design counterpart in [`../../integration/features/`](../../integration/features/) (same filename).
+
+| Feature | Migration file |
+|---|---|
+| Swap | [`swap.md`](swap.md) |
+| Money Market | [`money-market.md`](money-market.md) |
+| Staking | [`staking.md`](staking.md) |
+| Bridge | [`bridge.md`](bridge.md) |
+| DEX | [`dex.md`](dex.md) |
+| ICX/bnUSD/BALN | [`icx-bnusd-baln.md`](icx-bnusd-baln.md) |
+| Auxiliary services | [`auxiliary-services.md`](auxiliary-services.md) — `PartnerService` + `RecoveryService` + `BackendApiService`. The backend-API one is the load-bearing change: every method now returns `Promise<Result<T>>`. |
+
+## Reading order within a feature
+
+Each per-feature file follows the same shape:
+
+1. **TL;DR** — the load-bearing changes in 5–10 bullets.
+2. **Type / symbol cheat sheet** — exact renames and shape diffs.
+3. **Per-method delta** — call shape v1 vs v2, return type v1 vs v2, error model v1 vs v2.
+4. **Worked example** — a representative migration of one call site, before / after.
+5. **Pitfalls** — the things that look right but compile or run wrong.
+6. **Verification** — what to run to confirm the port is complete.
+
+## Cross-cutting prerequisites
+
+Before reading any feature file, finish the cross-cutting work in:
+
+- [`../README.md`](../README.md) — top-level checklist (chain-id rename, type renames, `walletProvider` extraction).
+- [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) — type imports must compile first.
+- [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`.
+- [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md) — `Result<T>` and `SodaxError<C>`.
+
+Per-feature work assumes those are done.

package/knowledge/sdk/migration/features/auxiliary-services.md

@@ -0,0 +1,156 @@
+# Auxiliary services migration — v1 → v2
+
+Pure-SDK migration playbook for `PartnerService`, `RecoveryService`, and `BackendApiService`. Three small services grouped because each has a small surface area.
+
+Pair: [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
+
+## TL;DR
+
+1. **`PartnerService`:** standard pattern. Drop `spokeProvider`; pass `walletProvider`. Add `srcChainKey` + `srcAddress` to claim params. v1's 5 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`.
+2. **`RecoveryService`:** **new in v2.** No v1 equivalent — there's no migration to do for code that didn't exist before. Just integration: see [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
+3. **`BackendApiService`:** the load-bearing change. **Every method now returns `Promise<Result<T>>`** (v1 returned plain `Promise<T>` and threw on failure). `IConfigApi` implementations must update method signatures.
+4. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field is `string` (`relayData.payload`), not the `RelayExtraData` object. (Cross-cutting detail; covered in detail in [`swap.md`](swap.md).)
+
+## `PartnerService`
+
+### Type / symbol cheat sheet
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| Partner action params | non-generic | now generic `<K>` with `srcChainKey`, `srcAddress` | |
+| Partner errors (5 types) | `PartnerFeeClaimError<...>` and 4 siblings | `SodaxError<C>` with `feature: 'partner'` | All 5 v1 typed errors collapse. |
+
+### v1 → v2 error code crosswalk
+
+All 5 v1 partner error codes map to `EXECUTION_FAILED` with `error.context.action` discriminating between the operations.
+
+### Per-method delta
+
+Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`), not directly on `sodax.partners`. v1 method names also changed:
+
+```diff
+- await sodax.partners.claimFees({ /* … */ }, spokeProvider);
++ // Approve once, then configure auto-swap preference, then run swaps.
++ // Full method list lives in integration/features/auxiliary-services.md.
++ const approved = await sodax.partners.feeClaim.isTokenApproved({ token, srcAddress });
++ if (approved.ok && !approved.value) {
++   await sodax.partners.feeClaim.approveToken({
++     params: { token, amount },
++     raw: false,
++     walletProvider,
++   });
++ }
+```
+
+### Pitfalls
+
+1. **Partner methods moved.** They live on `sodax.partners.feeClaim`, not `sodax.partners` directly. The parent only exposes `feeClaim` and `config` as public fields.
+2. **All 5 v1 partner errors collapse to `feature: 'partner'`.** Even though they share the `EXECUTION_FAILED` code with every other feature.
+
+---
+
+## `RecoveryService`
+
+**No v1 equivalent.** v1 didn't have a public recovery service. Failed cross-chain operations had to be handled ad-hoc.
+
+If you have v1 code that worked around this (e.g. manually walked the hub wallet abstraction to find stuck assets), replace it with `fetchHubAssetBalances` + `withdrawHubAsset`:
+
+```ts
+const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
+if (balances.ok && balances.value.length > 0) {
+  await sodax.recovery.withdrawHubAsset({
+    params: { /* hub-asset address, amount, destination spoke chain + address */ },
+    raw: false,
+    walletProvider: sonicWp,
+  });
+}
+```
+
+See [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md) § "RecoveryService".
+
+---
+
+## `BackendApiService`
+
+The load-bearing v1 → v2 change here is **`Result`-wrapping every method**.
+
+### Type / symbol cheat sheet
+
+| Method | v1 return | v2 return |
+|---|---|---|
+| `submitSwapTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitSwapTxResponse>>` |
+| `getIntentByHash` | `Promise<IntentResponse>` | `Promise<Result<IntentResponse>>` |
+| `getIntentByTxHash` | (n/a in v1) | `Promise<Result<IntentResponse>>` (v2-new) |
+| `getOrderbook` (was `getSolverOrderbook`) | `Promise<OrderbookEntry[]>` | `Promise<Result<OrderbookEntry[]>>` |
+| `getUserIntents` (was `getUserSwapHistory`) | `Promise<IntentResponse[]>` | `Promise<Result<IntentResponse[]>>` |
+| `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[]>>` |
+| `SubmitSwapTxRequest.srcChainId` | numeric chain id | renamed → `srcChainKey: SpokeChainKey` |
+| `SubmitSwapTxRequest.relayData` | `RelayExtraData` object | now `string` (use `relayData.payload`) |
+
+### Per-method delta
+
+```diff
+- const response: SubmitSwapTxResponse = await sodax.backendApi.submitSwapTx(request);
+- // throws on failure
++ const result = await sodax.backendApi.submitSwapTx({
++   txHash: spokeTxHash as string,
++   srcChainKey: src.chain,                  // was: srcChainId
++   walletAddress: '0x…',
++   intent: swapIntentData,
++   relayData: relayData.payload,            // was: relayData (object)
++ });
++ if (!result.ok) {
++   // result.error: SodaxError with feature: 'swap', context.api: 'backend'
++   return;
++ }
++ const response = result.value;
+```
+
+### Custom `IConfigApi` (sandbox / test fixtures)
+
+If you implemented `IConfigApi` for a sandbox or test fixture:
+
+```diff
+  const sandboxApi: IConfigApi = {
+-   async getChains(): Promise<ChainConfig[]> {
+-     return [/* fixture */];
+-   },
+-   async getSwapTokens(): Promise<SwapTokenConfig> { /* … */ },
++   async getChains(): Promise<Result<ChainConfig[], unknown>> {
++     return { ok: true, value: [/* fixture */] };
++   },
++   async getSwapTokens(): Promise<Result<SwapTokenConfig, unknown>> { /* … */ },
+    // …5 methods total
+  };
+```
+
+Every method on the contract returns `Promise<Result<T>>` in v2.
+
+### Pitfalls
+
+1. **`SubmitSwapTxRequest.relayData` is `string`, not the `RelayExtraData` object.** v1 took the object; v2 takes the `payload` field as a string.
+2. **Backend errors carry `error.context.api === 'backend'`** but the `feature` reflects the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related backend calls, etc.). Use both for logger tag pairs.
+3. **Custom `IConfigApi` implementations must return `Result<T>`** — old throw-on-error implementations will compile-error against the v2 interface.
+
+---
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scans:
+grep -rE "spokeProvider:\s*\w+|isPartnerError\b|PartnerFeeClaimError\b" src/
+grep -rE "srcChainId:\s*\w+|\.relayData(?!\s*\.payload)" src/   # legacy field name + non-string relayData
+```
+
+## Cross-references
+
+- v2 auxiliary services usage: [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
+- `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
+- Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
+- `IConfigApi` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.