@sodax/skills 2.0.0-rc.10

package/skills/sodax-sdk/migration-v1-to-v2/knowledge/recipes.md

@@ -0,0 +1,350 @@
+# Migration recipes — v1 → v2
+
+Practical patterns for porting consumer code without rewriting everything in one pass.
+
+1. [Codemod patterns](#1-codemod-patterns) — regex find/replace + a small `ts-morph` script for the renames that grep can't safely handle.
+2. [Free-function lookups at module scope](#2-free-function-lookups-at-module-scope) — `getHubChainConfig()` / `getMoneyMarketConfig()` migration for constants/util files where no `Sodax` instance exists yet.
+3. [Error-shape adapter](#3-error-shape-adapter) — adapt v2 `SodaxError` onto v1 `{ code, data }` branches so existing error-formatting helpers keep working.
+4. [Result adapter](#4-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.
+
+The patterns below describe **what** the rewrite needs to do; pick whichever codemod tool fits your project (regex, `ts-morph`, `jscodeshift`, IDE refactor). The example scripts use `ts-morph` for AST-level rewrites where regex is unsafe.
+
+---
+
+## 1. Codemod patterns
+
+### What's safe to grep-replace
+
+| Change | Find | Replace | Notes |
+|---|---|---|---|
+| Chain-id constants | `(\w+)_MAINNET_CHAIN_ID` | `ChainKeys.$1_MAINNET` | Mechanical. **Two-pass — see below.** First-pass rewrites usages; second-pass fixes the broken `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` | |
+
+### Two-pass codemod for chain-id constants
+
+A one-pass `_MAINNET_CHAIN_ID` → `ChainKeys.*_MAINNET` rewrite produces invalid syntax inside `import { ... }` blocks — `ChainKeys.SONIC_MAINNET` is a member-access expression, not a bare identifier, and cannot live inside a named-import list (TS1109).
+
+Split the rewrite into two passes:
+
+1. **Pass 1 — rewrite usages.** Every `<X>_MAINNET_CHAIN_ID` → `ChainKeys.<X>_MAINNET`. Touches expression positions and (incorrectly) named-import positions; the broken imports get fixed in pass 2.
+2. **Pass 2 — sweep imports.** For each `import { … } from '@sodax/{types,sdk}'`, drop the now-broken `ChainKeys.<X>_MAINNET` entries from the named-imports list and ensure `ChainKeys` itself is imported once.
+
+Use the `ts-morph` script from the chain-id section above as a starting point for an AST-aware version, or build the two passes with whatever tooling fits your repo. After pass 2, every chain-id reference compiles.
+
+### Pitfall — duplicate `ChainKeys` imports
+
+If a file imports `<X>_MAINNET_CHAIN_ID` from BOTH `@sodax/types` and `@sodax/sdk` (some legacy code split imports across the two), pass 2 may add `ChainKeys` to both import statements → `TS2300 Duplicate identifier 'ChainKeys'`. Either keep `ChainKeys` only in the first import block, or consolidate to one import — `@sodax/sdk` re-exports the entire `@sodax/types` surface, so a single `import … from '@sodax/sdk'` is sufficient.
+
+### 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. Free-function lookups at module scope
+
+v1 exported free functions like `getHubChainConfig()` and `getMoneyMarketConfig(chainId)` that consumers called at **module-load time** inside constants/util files — *before* any `Sodax` instance exists. The v2 replacement on `Sodax.config.*` is unusable in that context (chicken-and-egg).
+
+The real v2 answer: read directly from the packaged-default const `sodaxConfig`, re-exported from `@sodax/sdk` (and from `@sodax/types`):
+
+| v1 free function | v2 module-scope equivalent |
+|---|---|
+| `getHubChainConfig()` | `sodaxConfig.hub` |
+| `getMoneyMarketConfig(hubChainId)` | `sodaxConfig.moneyMarket` |
+| `getMoneyMarketConfig(hubChainId).supportedTokens` | `sodaxConfig.moneyMarket.supportedTokens` |
+| `getSolverConfig(SONIC_MAINNET_CHAIN_ID)` (read solver endpoints) | `sodaxConfig.solver` |
+| (none — v1 had no module-scope-safe accessor for full hub object) | `sodaxConfig.hub.addresses.hubWallet`, `.assetManager`, etc. |
+
+```diff
+- // v1 — module-scope constants file (no Sodax instance available yet)
+- import { getHubChainConfig, getMoneyMarketConfig } from '@sodax/sdk';
+- import { SONIC_MAINNET_CHAIN_ID } from '@sodax/types';
+-
+- const hubConfig = { hubRpcUrl, chainConfig: getHubChainConfig() };
+- const moneyMarketConfig = getMoneyMarketConfig(SONIC_MAINNET_CHAIN_ID);
+
++ // v2 — read from packaged defaults; no Sodax instance needed
++ import { sodaxConfig } from '@sodax/sdk';
++
++ const hubAddresses = sodaxConfig.hub.addresses;
++ const moneyMarketTokens = sodaxConfig.moneyMarket.supportedTokens;
+```
+
+> **Once you have a `Sodax` instance**, prefer `sodax.config.*` (`sodax.config.getHubChainConfig()`, `sodax.config.getMoneyMarketReserveAssets()`, etc.). The service-API path reflects backend-driven runtime updates after `await sodax.config.initialize()`; `sodaxConfig` is a packaged-default snapshot frozen at SDK release time.
+
+For hub-only module-scope reads, `hubConfig` is also exported directly:
+
+```ts
+import { hubConfig } from '@sodax/sdk';
+
+const HUB_WALLET = hubConfig.addresses.hubWallet;
+const STAKING_ROUTER = hubConfig.addresses.stakingRouter;
+```
+
+See [`reference/sodax-config.md`](reference/sodax-config.md) § "Pitfall — module-scope reads" for the same guidance in the SodaxConfig reshape doc.
+
+---
+
+## 3. 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.
+
+---
+
+## 4. 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*): [`recipes/`](../../integration/knowledge/recipes/).

package/skills/sodax-sdk/migration-v1-to-v2/knowledge/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: [`architecture.md`](../../../integration/knowledge/architecture.md) and [`reference/`](../../../integration/knowledge/reference/).

package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/deleted-exports.md

@@ -0,0 +1,127 @@
+# 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). For module-scope reads (before a `Sodax` instance exists), see [`sodax-config.md`](sodax-config.md) § "Pitfall — module-scope reads". |
+| `EvmWalletAbstraction` (class) | `sodax.hubProvider.getUserHubWalletAddress(...)` (the equivalent functionality lives on `EvmHubProvider`, accessed via the `Sodax` instance). |
+| `HubService` (class) + `HubService.getUserHubWalletAddress(spokeAddress, spokeChainId, hubProvider)` (static method) | `sodax.hubProvider.getUserHubWalletAddress(spokeAddress, spokeChainKey)` (instance method on `EvmHubProvider`; doesn't take `hubProvider` arg — `this` is the hub provider). v1 callers in `dex/AssetService.ts`, `mm/useATokensBalances.ts`, `shared/useGetUserHubWalletAddress.ts` all flatten to this single shape. |
+
+### 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`. **Fully removed — no legacy alias.** `import type { Token } from '@sodax/types'` fails with `TS2305: '"@sodax/types"' has no exported member named 'Token'. Did you mean 'XToken'?`. The shape also changed (added `vault`, `hubAsset`; renamed `xChainId` → `chainKey`) — 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) | **Pick by what you actually use:** (a) **You only declared `window.hanaWallet.ethereum: CustomProvider` for typedecl quietness, never called methods on it** → replace the type with `unknown` (`declare global { interface Window { hanaWallet: { ethereum: unknown } } }`). 1-line fix. (b) **You called `window.hanaWallet.ethereum.request(...)` or built a custom Hana wallet** → import the named helpers `requestAddress`, `requestSigning`, `requestJsonRpc` from `@sodax/sdk` and use them in place of the raw provider calls. These are the same low-level Hana-extension helpers v1 wrapped, now first-class exports. |
+
+### 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.

package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md

@@ -0,0 +1,104 @@
+# v1 ↔ v2 code crosswalk
+
+The widest-impact migration table in this file. v1 had per-module `*ErrorCode` unions; v2 reuses the 13 unified codes plus `feature` discrimination. **Match by intent, not by name** — the v1 `CREATE_SUPPLY_INTENT_FAILED` code is now `INTENT_CREATION_FAILED` with `feature: 'moneyMarket'` and `context.action: 'supply'`.
+
+### Money Market (`MoneyMarketErrorCode` → `feature: 'moneyMarket'`)
+
+| v1 code | v2 code | v2 context |
+|---|---|---|
+| `CREATE_SUPPLY_INTENT_FAILED` | `INTENT_CREATION_FAILED` | `action: 'supply'` |
+| `CREATE_BORROW_INTENT_FAILED` | `INTENT_CREATION_FAILED` | `action: 'borrow'` |
+| `CREATE_WITHDRAW_INTENT_FAILED` | `INTENT_CREATION_FAILED` | `action: 'withdraw'` |
+| `CREATE_REPAY_INTENT_FAILED` | `INTENT_CREATION_FAILED` | `action: 'repay'` |
+| `SUPPLY_FAILED` | `EXECUTION_FAILED` | `action: 'supply'` |
+| `BORROW_FAILED` | `EXECUTION_FAILED` | `action: 'borrow'` |
+| `WITHDRAW_FAILED` | `EXECUTION_FAILED` | `action: 'withdraw'` |
+| `REPAY_FAILED` | `EXECUTION_FAILED` | `action: 'repay'` |
+| `ALLOWANCE_CHECK_FAILED` | `ALLOWANCE_CHECK_FAILED` | (unchanged) |
+| `APPROVE_FAILED` | `APPROVE_FAILED` | (unchanged) |
+| `GAS_ESTIMATION_FAILED` | `GAS_ESTIMATION_FAILED` | (unchanged) |
+
+### Swap (`IntentErrorCode` → `feature: 'swap'`)
+
+| v1 code | v2 code | v2 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'`, `solverCode`/`solverDetail` on context |
+| `SIMULATION_FAILED` | `EXECUTION_FAILED` | `phase: 'execution'` |
+
+### Staking (`StakingErrorCode` → `feature: 'staking'`)
+
+| v1 code | v2 code | v2 context |
+|---|---|---|
+| `STAKE_FAILED` | `EXECUTION_FAILED` | `action: 'stake'` |
+| `UNSTAKE_FAILED` | `EXECUTION_FAILED` | `action: 'unstake'` |
+| `INSTANT_UNSTAKE_FAILED` | `EXECUTION_FAILED` | `action: 'instantUnstake'` |
+| `CLAIM_FAILED` | `EXECUTION_FAILED` | `action: 'claim'` |
+| `CANCEL_UNSTAKE_FAILED` | `EXECUTION_FAILED` | `action: 'cancelUnstake'` |
+| `GET_STAKING_INFO_FAILED` | `LOOKUP_FAILED` | `method: 'getStakingInfo'` |
+| `GET_UNSTAKING_INFO_FAILED` | `LOOKUP_FAILED` | `method: 'getUnstakingInfo'` |
+| `GET_STAKING_CONFIG_FAILED` | `LOOKUP_FAILED` | `method: 'getStakingConfig'` |
+| `GET_STAKE_RATIO_FAILED` | `LOOKUP_FAILED` | `method: 'getStakeRatio'` |
+
+### Bridge (`BridgeErrorCode` → `feature: 'bridge'`)
+
+| v1 code | v2 code | v2 context |
+|---|---|---|
+| `BRIDGE_FAILED` | `EXECUTION_FAILED` | `action: 'bridge'` |
+| `CREATE_BRIDGE_INTENT_FAILED` | `INTENT_CREATION_FAILED` | `action: 'bridge'` |
+| `GET_BRIDGEABLE_AMOUNT_FAILED` | `LOOKUP_FAILED` | `method: 'getBridgeableAmount'` |
+| `GET_BRIDGEABLE_TOKENS_FAILED` | `LOOKUP_FAILED` | `method: 'getBridgeableTokens'` |
+
+### Migration (`MigrationErrorCode` → `feature: 'migration'`)
+
+| v1 code | v2 code | v2 context |
+|---|---|---|
+| `MIGRATE_BNUSD_FORWARD_FAILED` | `EXECUTION_FAILED` | `action: 'migratebnUSD'`, `direction: 'forward'` |
+| `MIGRATE_BNUSD_REVERSE_FAILED` | `EXECUTION_FAILED` | `action: 'migratebnUSD'`, `direction: 'reverse'` |
+| `MIGRATE_ICX_TO_SODA_FAILED` | `EXECUTION_FAILED` | `action: 'migrateIcxToSoda'` |
+| `REVERT_MIGRATE_SODA_TO_ICX_FAILED` | `EXECUTION_FAILED` | `action: 'revertMigrateSodaToIcx'` |
+| `MIGRATE_BALN_FAILED` | `EXECUTION_FAILED` | `action: 'migrateBaln'` |
+| `GET_AVAILABLE_AMOUNT_FAILED` | `LOOKUP_FAILED` | `method: 'getAvailableAmount'` |
+
+### DEX (`AssetServiceErrorCode` + `ConcentratedLiquidityErrorCode` → `feature: 'dex'`)
+
+| v1 code | v2 code | v2 context |
+|---|---|---|
+| `DEPOSIT_FAILED` | `EXECUTION_FAILED` | `action: 'deposit'` |
+| `WITHDRAW_FAILED` | `EXECUTION_FAILED` | `action: 'withdraw'` |
+| `SUPPLY_LIQUIDITY_FAILED` | `EXECUTION_FAILED` | `action: 'supplyLiquidity'` |
+| `INCREASE_LIQUIDITY_FAILED` | `EXECUTION_FAILED` | `action: 'increaseLiquidity'` |
+| `DECREASE_LIQUIDITY_FAILED` | `EXECUTION_FAILED` | `action: 'decreaseLiquidity'` |
+| `CLAIM_REWARDS_FAILED` | `EXECUTION_FAILED` | `action: 'claimRewards'` |
+| `GET_POOL_DATA_FAILED` | `LOOKUP_FAILED` | `method: 'getPoolData'` |
+| `GET_POSITION_INFO_FAILED` | `LOOKUP_FAILED` | `method: 'getPositionInfo'` |
+
+### Relay (`RelayErrorCode` → typically still on `context.relayCode`)
+
+The relay-layer code strings are kept on `context.relayCode` of the surfaced `SodaxError`. They are also a stable public contract used by lower-level relay code:
+
+| v1 code | v2 code on `error.code` | v2 `context.relayCode` |
+|---|---|---|
+| `SUBMIT_TX_FAILED` | `TX_SUBMIT_FAILED` | `'SUBMIT_TX_FAILED'` |
+| `RELAY_TIMEOUT` | `RELAY_TIMEOUT` | `'RELAY_TIMEOUT'` |
+| `RELAY_POLLING_FAILED` | `RELAY_FAILED` | `'RELAY_POLLING_FAILED'` |
+| (any unrecognised) | `RELAY_FAILED` | `'UNKNOWN'` |
+
+### Partner (5 typed errors → `feature: 'partner'`)
+
+All partner typed errors collapse to `EXECUTION_FAILED` with `action` discriminating between the 5 v1 operations.
+
+### Recovery (no v1 typed errors — module is v2-new) → `feature: 'recovery'`
+
+`EXECUTION_FAILED` for the recovery action; `LOOKUP_FAILED` for read methods.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — migration reference index.
+- [`../README.md`](../README.md) — migration overview.
+- [`../checklist.md`](../checklist.md) — top-level migration checklist.

package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/return-shapes.md

@@ -0,0 +1,49 @@
+# Return-shape diffs per method
+
+### `SwapService.createIntent`
+
+```diff
+- const [spokeTxHash, intent, relayData] = result;
++ const { tx, intent, relayData } = result.value;
+```
+
+v1 returned a tuple. v2 returns an object: `{ tx, intent, relayData }` where:
+- `tx` is `TxReturnType<K, false>` (the spoke tx hash for `raw: false`, or the raw tx payload for `raw: true`).
+- `intent` is the intent struct.
+- `relayData` is `RelayExtraData` (`{ payload: string; ... }`).
+
+If you use the backend submit-swap-tx API, the v1 `relayData` field on the request expects the **string**, not the object — pass `relayData.payload`.
+
+### `BridgeService.bridge` and similar full-execution methods
+
+```diff
+- const txHash: string = await sodax.bridge.bridge(...);
++ const result = await sodax.bridge.bridge({ params, raw: false, walletProvider });
++ if (!result.ok) return;
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+v2 cross-chain mutation methods return `TxHashPair = { srcChainTxHash, dstChainTxHash }` so the consumer has both legs of the relay. The same shape applies to `staking.stake`, `staking.unstake`, `staking.instantUnstake`, `staking.claim`, `staking.cancelUnstake`, `dex.assetService.deposit/withdraw`, `dex.clService.supplyLiquidity/increaseLiquidity/decreaseLiquidity/claimRewards`, and the 4 `migration.*` orchestrators (`migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`). Consumers on the hub chain still get both fields populated (with the same hash) for shape consistency.
+
+### `MoneyMarketService.{supply, borrow, withdraw, repay}`
+
+```diff
+- const txHash = await sodax.moneyMarket.supply(...);
++ const result = await sodax.moneyMarket.supply({ params, raw: false, walletProvider });
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+Same `TxHashPair` shape as every other cross-chain mutation in v2.
+
+### Everything else
+
+If a v1 method returned a single `string` tx hash, the v2 return is `Result<TxReturnType<K, false>>` — destructure as `result.value` (which is the hash for `raw: false`, or the chain-specific raw tx payload for `raw: true`).
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — migration reference index.
+- [`../README.md`](../README.md) — migration overview.
+- [`../checklist.md`](../checklist.md) — top-level migration checklist.