@sodax/skills 2.0.0-rc.4

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

@@ -0,0 +1,128 @@
+# Bridge migration — v1 → v2
+
+Pure-SDK migration playbook for `BridgeService`.
+
+Pair: [`../../integration/features/bridge.md`](../../integration/features/bridge.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
+2. **Add `srcChainKey` + `srcAddress` to `CreateBridgeParams<K>`.** Generic added.
+3. **`bridge()` returns `Result<TxHashPair>`.** v1 returned a single `string` tx hash; v2 returns `{ srcChainTxHash, dstChainTxHash }` (the spoke + hub tx hashes) wrapped in `Result`.
+4. **`createBridgeIntent()` is spoke-only — no relay.** Same shape as the swap `createIntent`: returns `{ tx, intent, relayData }` for the spoke transaction. Useful when you need manual relay control.
+5. **Read methods reshaped.** `getBridgeableAmount` returns `Promise<Result<BridgeLimit>>` (was `Promise<bigint>`) and now takes two `XToken` objects. `getBridgeableTokens` is synchronous (was async) and takes `(from, to, token)`.
+6. **Errors → `SodaxError` + `Result<T>`.** v1's `BridgeError<BridgeErrorCode>` is gone.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `CreateBridgeIntentParams` | `{ srcChainId, srcAsset, amount, dstChainId, dstAsset, recipient }` | `{ srcChainKey, srcAddress, srcToken, amount, dstChainKey, dstToken, recipient }` | Now generic `<K>`. Renames: `srcChainId`/`dstChainId` → `srcChainKey`/`dstChainKey`; `srcAsset`/`dstAsset` → `srcToken`/`dstToken`. `recipient` is **unchanged**. NEW required: `srcAddress` (user's spoke-side sender, distinct from `recipient` which is the destination receiver). |
+| Bridge action wrapper | `{ params, spokeProvider }` | `{ params, raw: false, walletProvider }` | Same as every feature. |
+| `bridge` return | `Promise<string>` (tx hash, throws on error) | `Promise<Result<TxHashPair, SodaxError>>` | Tx-pair + Result. |
+| `getBridgeableAmount` | `Promise<bigint>` | `Promise<Result<BridgeLimit, SodaxError>>` where `BridgeLimit = { amount, decimals, type }` | Result-wrapped + richer return shape. Now takes `(from: XToken, to: XToken)` (was `(srcChainId, srcToken, dstChainId, dstToken)`). |
+| `getBridgeableTokens` | `Promise<XToken[]>` | `Result<XToken[], SodaxError>` (synchronous) | Sync now (config-derived). Takes `(from: SpokeChainKey, to: SpokeChainKey, token: string)` — was `(srcToken: XToken)`. |
+
+### Deleted symbols
+
+- `BridgeError<BridgeErrorCode>` and `isBridgeError` — replaced by `SodaxError<C>` + `feature: 'bridge'`.
+
+### v1 → v2 error code crosswalk (bridge-specific)
+
+| v1 `BridgeErrorCode` | v2 code + 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'`) |
+
+## Per-method delta
+
+### `bridge`
+
+```diff
+- const txHash: string = await sodax.bridge.bridge({
+-   params: { srcAsset, amount, dstChainId, dstAsset, recipient },
+-   spokeProvider,
+- });
++ const result = await sodax.bridge.bridge({
++   params: {
++     srcChainKey: ChainKeys.ARBITRUM_MAINNET,
++     srcAddress: '0x…',                          // NEW: required (your spoke-side sender)
++     srcToken,                                    // RENAMED from `srcAsset`
++     amount,
++     dstChainKey: ChainKeys.STELLAR_MAINNET,
++     dstToken,                                    // RENAMED from `dstAsset`
++     recipient: 'G…',                             // UNCHANGED — destination receiver
++   },
++   raw: false,
++   walletProvider,
++ });
++ // Type: Result<TxHashPair, BridgeOrchestrationError>
++ //       where TxHashPair = { srcChainTxHash: string; dstChainTxHash: string }
++ if (!result.ok) return;
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### `createBridgeIntent`
+
+```diff
+- await sodax.bridge.createBridgeIntent({ params, spokeProvider });
++ const result = await sodax.bridge.createBridgeIntent({ params, raw: false, walletProvider });
++ if (!result.ok) return;
++ const { tx, intent, relayData } = result.value;
++ // Submit relayData.payload via your custom relay if needed.
+```
+
+### `getBridgeableAmount` / `getBridgeableTokens`
+
+```diff
+- const amount: bigint = await sodax.bridge.getBridgeableAmount(srcChainId, srcToken.address, dstChainId, dstToken.address);
++ const result = await sodax.bridge.getBridgeableAmount(srcToken, dstToken);   // both are XToken objects (each carries chainKey)
++ // result.value is BridgeLimit = { amount, decimals, type }, not a raw bigint.
++ if (!result.ok) return 0n;
++ const amount = result.value;
+```
+
+### `approve` / `isAllowanceValid`
+
+Standard pattern:
+
+```ts
+await sodax.bridge.approve({
+  params: { srcChainKey, srcAddress, srcAsset, amount },
+  raw: false,
+  walletProvider,
+});
+
+const allowed = await sodax.bridge.isAllowanceValid({
+  params: { srcChainKey, srcAddress, srcAsset, amount },
+  raw: true,    // read-only
+});
+```
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **Treating `bridge` return as a string.** v2 returns `Result<TxHashPair>`. Destructure both elements; cast to string at the boundary if your downstream API expects a string.
+2. **`getBridgeableAmount` reshaped.** Resolves to `Result<BridgeLimit, SodaxError>` (with `BridgeLimit = { amount, decimals, type }`), not raw `Result<bigint>`. UI code that displayed the bigint directly needs `result.value.amount`.
+3. **`getBridgeableTokens` is synchronous now.** It returns `Result<XToken[]>` directly (no `await`). v1 was a `Promise`. `await` still typechecks but `.then(...)` is a runtime error.
+4. **Tokens are bridgeable iff they share the same vault.** Same chain pair, same underlying — but if you bridge USDC.e on chain A and the destination's USDC has a different vault, the call rejects with `VALIDATION_FAILED`. Use `getBridgeableTokens(srcChainKey, dstChainKey, srcAsset.address)` to enumerate compatible destinations.
+4. **`createBridgeIntent` is spoke-only — no relay.** If you call it expecting a finished bridge, you'll have a pending hub-side transfer that never executes. Either use `bridge()` for the full flow, or call the relay layer manually after `createBridgeIntent`.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+grep -rE "spokeProvider:\s*\w+|isBridgeError\b|BridgeError\b" src/
+```
+
+## Cross-references
+
+- v2 bridge usage: [`../../integration/features/bridge.md`](../../integration/features/bridge.md).
+- Stellar destination trustline: [`../../integration/chain-specifics.md`](../../integration/chain-specifics.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).

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

@@ -0,0 +1,143 @@
+# DEX migration — v1 → v2
+
+Pure-SDK migration playbook for `DexService` (`AssetService` + `ClService`).
+
+Pair: [`../../integration/features/dex.md`](../../integration/features/dex.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider`. Pass `walletProvider` directly.** Same as every other feature.
+2. **Add `srcChainKey` + `srcAddress` to every action params.** All 6 DEX param types (`CreateAssetDepositParams`, `CreateAssetWithdrawParams`, `ClSupplyParams`, `ClIncreaseLiquidityParams`, `ClDecreaseLiquidityParams`, `ClClaimRewardsParams`) gained both fields and a `<K extends SpokeChainKey>` generic.
+3. **`getPools()` is synchronous in v2.** Was `Promise<PoolKey[]>`; now plain `PoolKey[]`. `.then(...)` is a runtime error.
+4. **`getAssetsForPool` is chain-key-first.** Was `getAssetsForPool(spokeProvider, poolKey)`; now `getAssetsForPool(srcChainKey, poolKey)`.
+5. **`getDeposit` is `Result`-wrapped.** Was `(token, spokeProvider) => Promise<bigint>`; now `(poolToken, walletAddress, chainKey) => Promise<Result<bigint>>`.
+6. **Read-only allowance checks pass `raw: true`.** `assetService.isAllowanceValid` requires the `WalletProviderSlot<K, Raw>` discriminator; the read doesn't actually consult the wallet provider, so `raw: true` is the contract for read-only access.
+7. **`getPoolData` and `getPositionInfo` use the hub publicClient.** Consumers can pass `sodax.hubProvider.publicClient` when needed.
+8. **Errors → `SodaxError` + `Result<T>`.** v1's `ConcentratedLiquidityError`, `AssetServiceError` and their type guards are gone.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `CreateAssetDepositParams` | `{ asset, amount, poolToken, dst? }` | `{ srcChainKey, srcAddress, asset, amount, poolToken, dst? }` | Now generic `<K>`. |
+| `CreateAssetWithdrawParams` | same | same with `srcChainKey, srcAddress` | |
+| `ClSupplyParams` | `{ poolKey, tickLower, tickUpper, liquidity, amount0Max, amount1Max, sqrtPriceX96 }` | + `srcChainKey, srcAddress` | |
+| `ClIncreaseLiquidityParams` | `+ tokenId` | + `srcChainKey, srcAddress` | |
+| `ClDecreaseLiquidityParams` | `{ poolKey, tokenId, liquidity, amount0Min, amount1Min }` | + `srcChainKey, srcAddress` | |
+| `ClClaimRewardsParams` | `{ poolKey, tokenId, tickLower, tickUpper }` | + `srcChainKey, srcAddress` | |
+| `getAssetsForPool` | `(spokeProvider, poolKey)` | `(srcChainKey, poolKey)` | Chain-key-first. Sync. |
+| `getPools` | `Promise<PoolKey[]>` | `PoolKey[]` | Sync now. |
+| `getDeposit` | `(token, spokeProvider) => Promise<bigint>` | `(poolToken, walletAddress, chainKey) => Promise<Result<bigint>>` | Result-wrapped. |
+
+### Deleted symbols
+
+- `ConcentratedLiquidityError<ConcentratedLiquidityErrorCode>` and `AssetServiceError<AssetServiceErrorCode>` plus their type guards — replaced by `SodaxError<C>` + `feature: 'dex'`.
+- v1 `getDeposit(token, spokeProvider)` overload — replaced by the chain-key-first signature.
+
+### v1 → v2 error code crosswalk (DEX-specific)
+
+| v1 code | v2 code + 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'`) |
+
+## Per-method delta
+
+### `deposit` / `withdraw`
+
+```diff
+- await sodax.dex.assetService.deposit({ params, spokeProvider });
++ const result = await sodax.dex.assetService.deposit({
++   params: { srcChainKey, srcAddress, asset, amount, poolToken },
++   raw: false,
++   walletProvider,
++ });
++ if (!result.ok) return;
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### `supplyLiquidity` (mint new) and `increaseLiquidity` (existing)
+
+The pure-helper `createSupplyLiquidityParamsProps` returns the helper-relevant subset (no `srcChainKey`/`srcAddress`). Spread it at the call site:
+
+```diff
+- const params = createSupplyLiquidityParamsProps({ /* … */ });
+- await sodax.dex.clService.supplyLiquidity({ params, spokeProvider });
++ const helperOutput = createSupplyLiquidityParamsProps({ /* … */ });
++ const srcAddress = (await walletProvider.getWalletAddress()) as `0x${string}`;
++ const params = { ...helperOutput, srcChainKey, srcAddress };
++ const result = await sodax.dex.clService.supplyLiquidity({ params, raw: false, walletProvider });
++ if (!result.ok) return;
++ const { dstChainTxHash } = result.value;
+```
+
+### `getAssetsForPool`
+
+```diff
+- const { token0, token1 } = sodax.dex.clService.getAssetsForPool(spokeProvider, poolKey);
++ const { token0, token1 } = sodax.dex.clService.getAssetsForPool(srcChainKey, poolKey);
+```
+
+### `getPools`
+
+```diff
+- const pools = await sodax.dex.clService.getPools();
++ const pools = sodax.dex.clService.getPools();   // sync
+```
+
+The `await` form still compiles (TS allows `await` on non-promises) but `.then(...)` is a runtime error.
+
+### `getDeposit`
+
+```diff
+- const balance: bigint = await sodax.dex.assetService.getDeposit(poolToken, spokeProvider);
++ const result = await sodax.dex.assetService.getDeposit(poolToken, walletAddress, chainKey);
++ if (!result.ok) return 0n;
++ const balance = result.value;
+```
+
+### Allowance (read-only `raw: true`)
+
+```diff
+- const allowed = await sodax.dex.assetService.isAllowanceValid({ params, spokeProvider });
++ const result = await sodax.dex.assetService.isAllowanceValid({ params, raw: true });
++ if (!result.ok) return false;
++ const allowed = result.value;
+```
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **Forgetting `raw: true` on `isAllowanceValid`.** TypeScript error: `Property 'walletProvider' is missing`.
+2. **Passing `spokeProvider` to `getAssetsForPool`.** Type error — pass `srcChainKey` instead.
+3. **`getPools().then(...)` runtime error** — sync now.
+4. **Reading `spokeProvider.chainConfig.chain.name` for display.** Gone. Use `baseChainInfo[chainKey]?.name` from `@sodax/sdk`.
+5. **Reading `spokeProvider.walletProvider.getWalletAddress()`.** Gone. The wallet provider you passed is the same one you read from — call its `.getWalletAddress()` directly.
+6. **`walletProvider.getWalletAddress()` returns `Promise<string>`, not the EVM-branded `` `0x${string}` ``.** SDK params want `GetAddressType<K>`, which for EVM resolves to `` `0x${string}` ``. Cast at the boundary: `(await walletProvider.getWalletAddress()) as \`0x${string}\``.
+7. **Mint-new vs increase-existing are two distinct SDK methods.** v2 has `clService.supplyLiquidity` (mint) and `clService.increaseLiquidity` (existing tokenId). Pick the right one at the call site based on whether you have an existing position id.
+8. **`assetService.deposit` and `withdraw` always relay to hub.** If you need spoke-only execution (custom orchestration), use `assetService.executeDeposit` directly — but it's not surfaced through the higher-level wrappers.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scans:
+grep -rE "spokeProvider:\s*\w+|getAssetsForPool\([^,]*Provider" src/
+grep -rE "isConcentratedLiquidityError\b|ConcentratedLiquidityError\b|AssetServiceError\b" src/
+grep -rE "getPools\(\)\.then\b" src/
+```
+
+## Cross-references
+
+- v2 DEX usage: [`../../integration/features/dex.md`](../../integration/features/dex.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).

package/knowledge/sdk/migration/features/icx-bnusd-baln.md

@@ -0,0 +1,151 @@
+# Token migration (ICX/bnUSD/BALN) — v1 → v2
+
+Pure-SDK migration playbook for `MigrationService` (the SDK module — not v1→v2 SDK porting).
+
+Pair: [`../../integration/features/icx-bnusd-baln.md`](../../integration/features/icx-bnusd-baln.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
+2. **Add `srcChainKey` + `srcAddress` to every action params.** All migration param types (`MigrationParams<K>`, `UnifiedBnUSDMigrateParams<K>`, `IcxToSodaMigrateParams<K>`, `RevertSodaToIcxParams<K>`, `BalnSwapParams<K>`) gained both fields and a `<K>` generic.
+3. **All 4 orchestrator methods return `Result<TxHashPair>`.** v1 returned a string tx hash and threw on error.
+4. **`migratebnUSD` carries `direction` on error context** — `'forward'` (legacy → new) or `'reverse'` (new → legacy). The SDK detects direction from `(srcToken, dstToken)` addresses.
+5. **`BalnSwapService` lock-management methods STILL THROW.** `claim`, `claimUnstaked`, `stake`, `unstake`, `cancelUnstake`, `getDetailedUserLocks` — these 6 methods preserve the v1 throw-on-error contract. Wrap in `try/catch` until a future cleanup release converts them to `Result`.
+6. **Errors → `SodaxError` + `Result<T>`.** v1's `MigrationError<MigrationErrorCode>` is gone.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `MigrationParams` | non-generic | `MigrationParams<K extends SpokeChainKey>` with `srcChainKey`, `srcAddress`, `amount`, `dstAddress?` | Generic added. |
+| `UnifiedBnUSDMigrateParams` | non-generic | `UnifiedBnUSDMigrateParams<K>` extends `MigrationParams<K>` with `srcToken`, `dstToken` | Generic added. |
+| `BalnSwapParams` | `{ amount, lockPeriodMonths }` | `MigrationParams<K> & { lockPeriodMonths }` | Adds chain context. |
+
+### Deleted symbols
+
+- `MigrationError<MigrationErrorCode>` and `isMigrationError` — replaced by `SodaxError<C>` + `feature: 'migration'`.
+- The 6 v1 separate-method-per-direction names (`migrateBnUSDForward`, `migrateBnUSDReverse`, …) — collapsed into `migratebnUSD` with auto-direction detection on `error.context.direction`.
+
+### v1 → v2 error code crosswalk
+
+| v1 `MigrationErrorCode` | v2 code + 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'`) |
+
+`migratebnUSD` additionally has `phase: 'destinationExecution'` on errors from its secondary `waitUntilIntentExecuted` watcher (after the primary relay completes, bnUSD waits for the destination contract to finalize).
+
+## Per-method delta
+
+### `migratebnUSD` (replaces v1 forward + reverse methods)
+
+```diff
+- // v1 had two methods:
+- await sodax.migration.migrateBnUSDForward({ amount, /* … */ }, spokeProvider);
+- await sodax.migration.migrateBnUSDReverse({ amount, /* … */ }, spokeProvider);
+
++ // v2 has one method; SDK detects direction from (srcToken, dstToken):
++ const result = await sodax.migration.migratebnUSD({
++   params: {
++     srcChainKey, srcAddress,
++     srcToken,    // legacy or new bnUSD
++     dstToken,    // the other one
++     amount,
++     dstAddress,
++   },
++   raw: false,
++   walletProvider,
++ });
++ if (!result.ok) {
++   const dir = result.error.context?.direction;  // 'forward' | 'reverse'
++   /* … */
++ }
+```
+
+### `migrateIcxToSoda` / `revertMigrateSodaToIcx` / `migrateBaln`
+
+Standard pattern:
+
+```diff
+- await sodax.migration.migrateIcxToSoda({ amount }, spokeProvider);
++ const result = await sodax.migration.migrateIcxToSoda({
++   params: { srcChainKey: ChainKeys.ICON_MAINNET, srcAddress: 'hx…', amount },
++   raw: false,
++   walletProvider: iconWp,
++ });
++ if (!result.ok) return;
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+`migrateBaln` adds `lockPeriodMonths: 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24` to the params. Reward multiplier ranges 0.5x (0 months) – 1.5x (24 months).
+
+### Approve / allowance — action-discriminated
+
+```ts
+await sodax.migration.approve({
+  params: { srcChainKey, srcAddress, amount, action: 'migrateBaln' /* or migratebnUSD | migrateIcxToSoda | revertMigrateSodaToIcx */ },
+  raw: false,
+  walletProvider,
+});
+
+const allowed = await sodax.migration.isAllowanceValid({
+  params: { srcChainKey, srcAddress, amount, action: 'migrateBaln' },
+  raw: true,    // read-only
+});
+```
+
+### `getAvailableAmount` (claimable from partial migration)
+
+```diff
+- const amount: bigint = await sodax.migration.icx.getAvailableAmount(spokeProvider);
++ const result = await sodax.migration.icxMigration.getAvailableAmount();   // sub-service renamed; takes no args in v2
++ if (!result.ok) return 0n;
++ const amount = result.value;
+```
+
+### BALN lock management — STILL THROWS
+
+```diff
+  try {
+-   const tx = await sodax.migration.balnSwapService.stake({ amount, lockPeriod }, spokeProvider);
++   const tx = await sodax.migration.balnSwapService.stake({
++     params: { srcChainKey, srcAddress, amount, lockPeriodMonths },
++     raw: false,
++     walletProvider,
++   });
+    /* … */
+  } catch (e) {
+    /* still v1-style: catch the throw */
+  }
+```
+
+`claim`, `claimUnstaked`, `unstake`, `cancelUnstake`, `getDetailedUserLocks` follow the same pattern. They preserve the throw-on-error contract for now — future cleanup will Result-wrap them.
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **`migratebnUSD` direction detection.** v1 had explicit forward/reverse methods; v2 detects from `(srcToken, dstToken)`. If both are on the same side (both legacy or both new), the SDK rejects with `VALIDATION_FAILED`. Use the `direction` field on `error.context` to disambiguate in error messaging.
+2. **BALN lock methods don't return `Result`.** Be careful migrating wrappers — if your wrapper assumes Result-shape, lock methods will produce `undefined.ok` runtime errors. Keep the `try/catch` shape.
+3. **`lockPeriodMonths` is a literal union, not arbitrary `number`.** TypeScript rejects `lockPeriodMonths: 7`. Allowed values: `0 | 1 | 2 | 3 | 6 | 12 | 18 | 24`.
+4. **`getAvailableAmount` lives on the sub-service `sodax.migration.icxMigration` and takes no arguments.** v1 expected `(spokeProvider)`; v2 reads on-chain SODA liquidity directly from the hub provider, so the method needs no chain context. Sub-service field names: `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`.
+5. **`destinationExecution` phase on bnUSD errors** — these errors land **after** the relay succeeds. The spoke and hub txs may already exist; the destination-side finalization is what failed. Distinguish from primary relay errors (`phase: 'relay'`) when surfacing UX.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+grep -rE "spokeProvider:\s*\w+|migrateBnUSDForward\b|migrateBnUSDReverse\b|isMigrationError\b|MigrationError\b" src/
+```
+
+## Cross-references
+
+- v2 token migration usage: [`../../integration/features/icx-bnusd-baln.md`](../../integration/features/icx-bnusd-baln.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).

package/knowledge/sdk/migration/features/money-market.md

@@ -0,0 +1,214 @@
+# Money Market migration — v1 → v2
+
+Pure-SDK migration playbook for `MoneyMarketService`.
+
+Pair: [`../../integration/features/money-market.md`](../../integration/features/money-market.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider` from every params object.** Pass `walletProvider` directly into the SDK call payload alongside `params` and `raw: false`.
+2. **Add `srcChainKey` + `srcAddress` to every action params object.** v2's `MoneyMarketParams<K>` requires both; v1 didn't have them at all.
+3. **Mutations resolve `Result<TxHashPair>`, not throw.** v1 mutation methods threw; v2 returns `{ ok: false, error }` on SDK-level failure. Branch on `result.ok`.
+4. **`MoneyMarketSupplyParams` etc. are now generic** (`MoneyMarketSupplyParams<K extends SpokeChainKey>`). Add a chain-key generic to your params variables, or let TS infer from a literal `srcChainKey`.
+5. **Replace `moneyMarketSupportedTokens[chainId]` with `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)`.**
+6. **Replace `hubAssets[chainId][address]?.vault` with `token.vault`** (now baked into `XToken`). Same for `token.hubAsset`.
+7. **`sodax.moneyMarket.getAToken(...)` returns `Erc20Token & { chainKey }`, not a full `XToken`.** No `hubAsset` / `vault` on the result — look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` if needed.
+8. **Errors → `SodaxError` + `Result<T>`.** v1's `MoneyMarketError<MoneyMarketErrorCode>` is gone. The CODE moved from `error.code` to `error.message`-style? **No** — it's still on `error.code`, but the union changed (see crosswalk below).
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `MoneyMarketSupplyParams` | `{ token, amount, action }` | `{ srcChainKey, srcAddress, token, amount, action, dstChainKey?, dstAddress? }` | Same template for borrow / withdraw / repay. Now generic in `K extends SpokeChainKey`. |
+| `MoneyMarketBorrowParams` | non-generic | `MoneyMarketBorrowParams<K>` | Optional `dstChainKey`/`dstAddress` for cross-chain delivery. |
+| `MoneyMarketRepayParams` | non-generic | `MoneyMarketRepayParams<K>` | Optional `dstChainKey`/`dstAddress` for paying off debt on a different chain. |
+| `XToken` | `xChainId` | `chainKey` | Type renamed `Token` → `XToken`. New fields `vault`, `hubAsset` baked in. |
+
+### Deleted symbols
+
+- `moneyMarketSupportedTokens` — `Record<SpokeChainKey, XToken[]>` global. Use `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)` / `getSupportedTokens()`.
+- `hubAssets` — vault address lookup global. Use `XToken.vault` / `XToken.hubAsset` directly.
+- `SodaTokens` — vault-validation registry. Use `sodax.config.getMoneyMarketReserveAssets()`.
+- `MoneyMarketError<MoneyMarketErrorCode>` and `isMoneyMarketError` — replaced by `SodaxError<C>` + `isSodaxError(e) && e.feature === 'moneyMarket'`.
+
+### v1 → v2 error code crosswalk (money-market-specific)
+
+| v1 `MoneyMarketErrorCode` | v2 code + 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) |
+
+## Per-method delta
+
+### `supply`
+
+```diff
+- const params: MoneyMarketSupplyParams = {
+-   token: token.address,
+-   amount: parseUnits('100', 6),
+-   action: 'supply',
+- };
+- const result = await sodax.moneyMarket.supply({ params, spokeProvider });
+- // result throws on failure, or returns the tx hash
++ const params: MoneyMarketSupplyParams<typeof srcChainKey> = {
++   srcChainKey: ChainKeys.ARBITRUM_MAINNET,
++   srcAddress: '0x…',
++   token: token.address,
++   amount: parseUnits('100', 6),
++   action: 'supply',
++ };
++ const result = await sodax.moneyMarket.supply({ params, raw: false, walletProvider });
++ if (!result.ok) {
++   // result.error: SodaxError with feature: 'moneyMarket'
++   return;
++ }
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### `borrow` — gain cross-chain delivery
+
+If you ported a same-chain borrow, no new fields needed — just `srcChainKey` + `srcAddress`. For cross-chain delivery (which v1 didn't expose this cleanly), add `dstChainKey` and `dstAddress`:
+
+```ts
+await sodax.moneyMarket.borrow({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress,
+    token: USDC.address,
+    amount,
+    action: 'borrow',
+    dstChainKey: ChainKeys.STELLAR_MAINNET,    // NEW in v2
+    dstAddress: 'G…',                           // NEW in v2
+  },
+  raw: false,
+  walletProvider,
+});
+```
+
+### `repay` — pay from a different chain than the debt
+
+Similar: v2 lets the spender chain (`srcChainKey`) differ from the debt chain (`dstChainKey`):
+
+```ts
+await sodax.moneyMarket.repay({
+  params: {
+    srcChainKey: fromChain,
+    srcAddress: fromAddress,
+    token: tokenOnFromChain.address,
+    amount,
+    action: 'repay',
+    dstChainKey: debtChain,
+    dstAddress: debtAddress,
+  },
+  raw: false,
+  walletProvider: walletOnFromChain,
+});
+```
+
+### `approve` / `isAllowanceValid`
+
+```diff
+- const allowed = await sodax.moneyMarket.isAllowanceValid({ params, spokeProvider });
++ const allowed = await sodax.moneyMarket.isAllowanceValid({
++   params,           // includes srcChainKey, srcAddress, action
++   raw: true,        // read-only — walletProvider not needed
++ });
++ if (!allowed.ok) return false;
++ if (!allowed.value) await sodax.moneyMarket.approve({ params, raw: false, walletProvider });
+```
+
+The `params.action` field discriminates which token gets approved (relevant for repay where the spent token may differ).
+
+## Replacing the static lookups
+
+```diff
+- import { moneyMarketSupportedTokens, hubAssets } from '@sodax/types';
+- const supplyTokens = moneyMarketSupportedTokens[chainId];
++ const supplyTokens = sodax.moneyMarket.getSupportedTokensByChainId(chainKey);
+
+- const allTokens = Object.entries(moneyMarketSupportedTokens)
+-   .flatMap(([chainId, tokens]) => tokens.map(t => ({ ...t, xChainId: chainId })));
++ const allTokens = Object.entries(sodax.moneyMarket.getSupportedTokens())
++   .flatMap(([_chainKey, tokens]) => tokens);   // tokens already carry chainKey in v2
+```
+
+```diff
+- const vault = hubAssets[chainId]?.[token.address]?.vault;
++ const vault = token.vault;   // baked into XToken
+```
+
+## Worked example — supply flow
+
+A single supply call site, before and after. Shows every change in one place: spoke-provider drop, params shape, return shape, field rename.
+
+```diff
+- const params: MoneyMarketSupplyParams = {
+-   token: token.address,
+-   amount: parseUnits(amount, token.decimals),
+-   action: 'supply',
+- };
+- const txHash = await sodax.moneyMarket.supply({ params, spokeProvider });
+- // throws on failure
++ const params: MoneyMarketSupplyParams<typeof srcChainKey> = {
++   srcChainKey,                                   // NEW: required
++   srcAddress,                                    // NEW: required (GetAddressType<K>)
++   token: token.address,
++   amount: parseUnits(amount, token.decimals),
++   action: 'supply',
++ };
++ const result = await sodax.moneyMarket.supply({
++   params,
++   raw: false,                                    // NEW: discriminator
++   walletProvider,                                // NEW: was inside spokeProvider in v1
++ });
++ if (!result.ok) {
++   // result.error: SodaxError with feature: 'moneyMarket', context.action: 'supply'
++   return;
++ }
++ const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair, not single hash
+
+  const successData: ActionSuccessData = {
+    /* … */
+-   destinationChainId: token.xChainId,            // OLD field name
++   destinationChainId: token.chainKey,            // RENAMED
+    txHash: srcChainTxHash,
+  };
+```
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **Forgetting `srcChainKey` + `srcAddress` in params.** TypeScript surfaces this as `error TS1360: Type '{ token, amount, action }' does not satisfy the expected type 'MoneyMarketSupplyParams'`. Add both required fields.
+2. **Borrow/repay default delivery to source.** Omit `dstChainKey`/`dstAddress` if you want same-chain. Don't pass them as the same value as `srcChainKey` / `srcAddress` — let the default kick in.
+3. **`sodax.moneyMarket.getAToken(...)` returns a partial token.** `Erc20Token & { chainKey }`, not a full `XToken` — no `vault` / `hubAsset` on the result. Look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` separately if you need those fields.
+4. **`hubAssets` is gone.** Anything that walked it for vault lookup must use `token.vault` directly.
+5. **`baseChainInfo[chain].id` is gone — entries have `.key`.** Common in `ChainSelector`-style components.
+6. **`spokeProvider.chainConfig.chain.type === 'EVM'`** is gone. Use `getChainType(chainKey) === 'EVM'` from `@sodax/sdk`.
+7. **`Number(chainKey)` returns `NaN` for non-numeric keys.** `ChainKeys.ICON_MAINNET` is `'0x1.icon'`; numeric coercions break.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scans:
+grep -rE "spokeProvider:\s*\w+|moneyMarketSupportedTokens|\bhubAssets\b" src/
+grep -rE "isMoneyMarketError\b|MoneyMarketError\b" src/
+```
+
+## Cross-references
+
+- v2 money market usage: [`../../integration/features/money-market.md`](../../integration/features/money-market.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).