@sodax/skills 2.0.0-rc.10

package/skills/sodax-sdk/integration/knowledge/reference/glossary.md

@@ -0,0 +1,32 @@
+# Glossary
+
+| Term | Definition |
+|---|---|
+| **Hub** | Sonic. The single chain through which every cross-chain operation routes. Hosts the asset manager, wallet abstraction, and vault contracts. |
+| **Spoke** | Any of the 19 non-hub chains. Cross-chain operations enter and exit the system through spokes. |
+| **Spoke service** | An internal SDK service (e.g. `EvmSpokeService`) that owns the chain-family-specific logic. Owned by `SpokeService` (singular, the router). Consumers never construct one. |
+| **Chain key** | A string identifier for a chain (e.g. `'ethereum'`, `'0xa4b1.arbitrum'`). Type: `ChainKey` (full set) or `SpokeChainKey` (spoke chains only). Listed under `ChainKeys.*`. |
+| **Chain family** | The class of chain (`'EVM'`, `'BITCOIN'`, `'SOLANA'`, …). Resolved via `getChainType(chainKey)`. |
+| **Wallet provider** | A chain-specific signer/broadcaster (`IEvmWalletProvider`, etc.). Constructed by the consumer; passed into SDK calls. |
+| **Intent** | A user-signed declaration of intended cross-chain action. The unit of solver-mediated swap. |
+| **Solver** | An off-chain market maker that fulfills swap intents. The `SwapService` coordinates with the solver via `SolverApiService`. |
+| **Relay** | The off-chain layer that propagates spoke→hub transactions. Public surface: `relayTxAndWaitPacket` and `submitTransaction` top-level functions (re-exported from `@sodax/sdk`). |
+| **Relay chain id** | A bigint identifier used internally by the relay layer. **Different** from `ChainKey`. Convert via `sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(...))`. |
+| **Vault** | Hub-side ERC4626 contract that holds wrapped/unified spoke tokens. Each `XToken` carries its `vault` address directly. |
+| **Hub asset** | Hub-side token address representing a spoke asset on the hub chain. Each `XToken` carries its `hubAsset` address directly. |
+| **Hub wallet abstraction** | A user-specific contract on the hub that holds funds during cross-chain ops. Resolved via `EvmHubProvider.getUserHubWalletAddress(...)`. |
+| **`Result<T>`** | The `{ ok: true; value: T } \| { ok: false; error: E }` discriminated union returned by every async public method. |
+| **`SodaxError<C>`** | The canonical error class. Discriminated by `(feature, code)`. |
+| **Code (`SodaxErrorCode`)** | One of 13 reason-only error codes. See § 3. |
+| **Feature (`SodaxFeature`)** | One of 8 producing features (`'swap'`, `'moneyMarket'`, …). |
+| **Phase (`SodaxPhase`)** | The orchestration step at which an error occurred. See § 3. |
+| **Action (`error.context.action`)** | The user-facing operation that triggered the error (`'supply'`, `'stake'`, `'migrateBaln'`, …). |
+| **`raw: true / false`** | The discriminator on `WalletProviderSlot<K, Raw>`. `true` = build unsigned tx; `false` = sign and broadcast. |
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) — concepts behind these tables.

package/skills/sodax-sdk/integration/knowledge/reference/public-api.md

@@ -0,0 +1,138 @@
+# Public API surface
+
+Import everything from `@sodax/sdk`. The barrel re-exports the entire `@sodax/types` surface — you don't need a separate `@sodax/types` dependency.
+
+### Top-level exports
+
+```ts
+import {
+  // Main entry
+  Sodax,
+  type SodaxConfig,
+  type DeepPartial,
+
+  // Chain keys + narrowing
+  ChainKeys,
+  type ChainKey,
+  type SpokeChainKey,
+  type HubChainKey,
+  type EvmChainKey,
+  getChainType,
+  isEvmChainKeyType,
+  isSolanaChainKeyType,
+  isStellarChainKeyType,
+  isSuiChainKeyType,
+  isIconChainKeyType,
+  isInjectiveChainKeyType,
+  isStacksChainKeyType,
+  isNearChainKeyType,
+  isBitcoinChainKeyType,
+  isHubChainKeyType,
+  type GetChainType,
+  type GetWalletProviderType,
+  type GetAddressType,
+
+  // Type system primitives
+  type Result,
+  type WalletProviderSlot,
+  type TxReturnType,
+  type EvmRawTransaction,
+  type SolanaRawTransaction,
+  // …per-chain raw-tx types
+
+  // Errors
+  SodaxError,
+  type SodaxErrorCode,
+  type SodaxFeature,
+  type SodaxPhase,
+  type SodaxErrorContext,
+  type RelayCode,
+  isSodaxError,
+  isFeatureError,
+  isCodeMember,
+  sodaxInvariant,
+  swapInvariant,
+  mmInvariant,
+  bridgeInvariant,
+  stakingInvariant,
+  migrationInvariant,
+  dexInvariant,
+  partnerInvariant,
+  recoveryInvariant,
+  mapRelayFailure,
+
+  // Tokens
+  type XToken,
+  type BtcAddressType,
+
+  // Service classes (constructed by Sodax — usually you don't import these directly)
+  // …
+
+  // Wallet provider interfaces
+  type IWalletProvider,
+  type IEvmWalletProvider,
+  type ISolanaWalletProvider,
+  type ISuiWalletProvider,
+  type IStellarWalletProvider,
+  type IIconWalletProvider,
+  type IInjectiveWalletProvider,
+  type IStacksWalletProvider,
+  type INearWalletProvider,
+  type IBitcoinWalletProvider,
+
+  // Param types (per feature)
+  type CreateIntentParams,
+  type CreateLimitOrderParams,
+  type MoneyMarketSupplyParams,
+  type MoneyMarketBorrowParams,
+  type MoneyMarketWithdrawParams,
+  type MoneyMarketRepayParams,
+  type StakeParams,
+  type UnstakeParams,
+  type InstantUnstakeParams,
+  type ClaimParams,
+  type CancelUnstakeParams,
+  type CreateAssetDepositParams,
+  type CreateAssetWithdrawParams,
+  type ClSupplyParams,
+  type ClIncreaseLiquidityParams,
+  type ClDecreaseLiquidityParams,
+  type ClClaimRewardsParams,
+  type MigrationParams,
+  type UnifiedBnUSDMigrateParams,
+  // …
+
+  // Backend / relay
+  type IConfigApi,
+  type SubmitSwapTxRequest,
+  type SubmitSwapTxResponse,
+  relayTxAndWaitPacket,         // function — runs spoke→hub relay submit + wait
+  submitTransaction,            // function — relay submit ack only
+  type RelayExtraData,
+  type IntentRelayChainId,
+
+  // Read shapes
+  type Intent,
+  type IntentResponse,
+  type SwapResponse,
+  type CreateIntentResult,
+  type TxHashPair,
+} from '@sodax/sdk';
+```
+
+This is a partial list — see `src/index.ts` of the published tarball for the authoritative barrel.
+
+### Rules
+
+- **Import only from `@sodax/sdk` root.** No deep imports from `dist/...`.
+- **Do not depend on `@sodax/types` separately.** It's a transitive of `@sodax/sdk` (force-bundled via tsup `noExternal`); declaring it as a direct dependency invites version skew.
+- **Stable contract:** every export above is part of the public API. Anything not exported from the root barrel is internal — don't reach for it via `dist` paths.
+- **Tarball contents:** `dist/` (compiled JS + types). Nothing else ships. Consumer-facing AI docs (this tree) are shipped separately via [`@sodax/skills`](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills).
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) — concepts behind these tables.

package/skills/sodax-sdk/integration/knowledge/reference/wallet-providers.md

@@ -0,0 +1,62 @@
+# Wallet provider interfaces
+
+Every chain family has an `I*WalletProvider` interface. Each declares a `readonly chainType: '<NAME>'` literal field for runtime discrimination.
+
+| Family | Interface | `chainType` literal | Implementation |
+|---|---|---|---|
+| EVM | `IEvmWalletProvider` | `'EVM'` | `EvmWalletProvider` (private-key or browser-extension) |
+| Solana | `ISolanaWalletProvider` | `'SOLANA'` | `SolanaWalletProvider` |
+| Sui | `ISuiWalletProvider` | `'SUI'` | `SuiWalletProvider` |
+| Stellar | `IStellarWalletProvider` | `'STELLAR'` | `StellarWalletProvider` |
+| ICON | `IIconWalletProvider` | `'ICON'` | `IconWalletProvider` (uses Hana-extension helper functions for browser; see `../chain-specifics.md` § 4) |
+| Injective | `IInjectiveWalletProvider` | `'INJECTIVE'` | `InjectiveWalletProvider` |
+| Stacks | `IStacksWalletProvider` | `'STACKS'` | `StacksWalletProvider` |
+| NEAR | `INearWalletProvider` | `'NEAR'` | `NearWalletProvider` |
+| Bitcoin | `IBitcoinWalletProvider` | `'BITCOIN'` | `BTCWalletProvider` (PSBT) |
+
+### Common methods
+
+Every `I*WalletProvider` has:
+
+```ts
+getWalletAddress(): Promise<string>;
+// Returns the chain-specific address (typed as `0x${string}` for EVM, base58 for Solana, etc.).
+readonly chainType: '<FAMILY>';
+```
+
+Plus chain-specific signing/broadcasting methods. Each interface declares the methods consumers must implement to satisfy it; consumers usually don't call these methods directly — they pass the provider object to SDK methods. **Implementations are not part of `@sodax/sdk`** — write your own to satisfy the interface, or use `@sodax/wallet-sdk-core` (a separate SODAX package, install separately) which ships ready-made implementations for all 9 chain families with both private-key (Node) and browser-extension (dApp) modes.
+
+### `GetWalletProviderType<K>`
+
+Given a chain key literal `K`, resolves to the exact wallet provider interface for that chain:
+
+```ts
+GetWalletProviderType<typeof ChainKeys.ETHEREUM_MAINNET>  // IEvmWalletProvider
+GetWalletProviderType<typeof ChainKeys.SOLANA_MAINNET>    // ISolanaWalletProvider
+GetWalletProviderType<typeof ChainKeys.BITCOIN_MAINNET>   // IBitcoinWalletProvider
+GetWalletProviderType<SpokeChainKey>                      // IWalletProvider (broad union)
+```
+
+### `IWalletProvider` (broad union)
+
+The discriminated union of all 9 `I*WalletProvider` interfaces. Useful when a function accepts any chain's wallet provider:
+
+```ts
+import type { IWalletProvider } from '@sodax/sdk';
+
+function logChain(wp: IWalletProvider) {
+  console.log(wp.chainType);
+}
+```
+
+### Implementing the interfaces
+
+Each `I*WalletProvider` interface defines the methods consumers must implement; credentials, RPC clients, and browser-extension wiring are implementation concerns and intentionally outside the SDK. The SODAX-provided reference implementations in `@sodax/wallet-sdk-core` (separate package) accept either `{ privateKey, rpcUrl }` for Node / scripts or chain-specific browser-extension shapes (`{ walletClient }` for EVM via viem, `{ adapter }` for Solana, etc.) — refer to that package's documentation for specifics.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) — concepts behind these tables.

package/skills/sodax-sdk/migration/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: sodax-sdk-migration
+description: 'Granular skill for the @sodax/sdk v2 token-migration feature only — `MigrationService` (`sodax.migration`) covering ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, and BALN → SODA with lockup multipliers. Use when the task is migrating legacy ICON-ecosystem tokens to SODAX (e.g. "migrate ICX to SODA", "revert SODA back to ICX", "swap legacy bnUSD on Sui/Stellar/ICON to new bnUSD", "migrate BALN with lock period for reward multiplier", "claim staked BALN"). IMPORTANT — this is NOT the same as v1 → v2 SDK migration (porting old SDK code). That is a separate cross-cutting concern handled by the broad sodax-sdk skill in migration mode and the migration-v1-to-v2/ knowledge subtree. Same word, different concept. Skill links into the parent sodax-sdk knowledge tree.'
+---
+
+# Token migration (Core SDK granular skill)
+
+Granular skill for `MigrationService` — the SDK module that migrates legacy ICON-ecosystem tokens. Access via `sodax.migration` (with sub-services `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`). Feature tag: `'migration'`.
+
+> **Important disambiguation.** This skill is about the `MigrationService` SDK module. It is **NOT** about porting v1 SDK code to v2 — that lives under the broad `sodax-sdk` skill (migration mode) and the [`../migration-v1-to-v2/knowledge/`](../migration-v1-to-v2/knowledge/) subtree of this package. Same word, different concept.
+
+## Step 0 — Confirm this IS a token-protocol migration
+
+The word "migrate" is overloaded. This skill only handles **legacy ICON-ecosystem token swaps to SODAX assets** (ICX → SODA, legacy bnUSD → new bnUSD, BALN → SODA). If the user phrases the task as:
+
+- *"move / send / transfer SODA from chain A to chain B"* → that's a **bridge** (vault-pair) or a **swap** (solver-routed). Load `sodax-sdk-bridge` or `sodax-sdk-swap` instead.
+- *"migrate my v1 SDK code to v2"* → that's the SDK port. Load the broad `sodax-sdk` skill in migration mode and the `migration-v1-to-v2/` knowledge subtree.
+
+Only continue here if the task involves one of the three legacy-token sources below.
+
+## Step 1 — Clarify with user before coding
+
+1. **Which token are you migrating?**
+   - **ICX / wICX** ↔ SODA → `sodax.migration.icxMigration`.
+   - **Legacy bnUSD** (ICON / Sui / Stellar) ↔ **new bnUSD** (EVM chains) → `sodax.migration.bnUSDMigrationService`.
+   - **BALN** → SODA with optional lockup (0–24 months, multiplier 0.5x–1.5x) → `sodax.migration.balnSwapService`.
+2. **Forward** (legacy → new) **or revert** (new → legacy, ICX only)?
+3. **For BALN: lock period?** No lock = baseline; longer lock = higher reward multiplier.
+4. **Signed or unsigned-tx flow?**
+5. **Need orchestrated full flow** (`migrateXxx`) **or just intent creation** (`createMigrateXxxIntent`)?
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/migration.md`](../integration/knowledge/features/migration.md) — `MigrationService` API surface and the three sub-services.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'migration'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Token-migration-specific anti-patterns
+
+- **Assuming `BalnSwapService.stake/unstake/claim/...` return `Result<T>`.** They still THROW — deliberate tech debt. Wrap them in `try/catch` until cleaned up.
+- **Using `migration` (the SDK module) and `migration-v1-to-v2` (the SDK port) interchangeably.** Different concerns; reading one playbook for the other will produce broken code.
+- **Skipping `getAvailableAmount` for partial ICX migrations.** Tells you how much SODA the user can claim from a partial migration.
+
+## Migration workflow (v1 → v2 of the SDK itself)
+
+If the user is porting v1 `MigrationService` code to v2:
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/migration.md`](../migration-v1-to-v2/knowledge/features/migration.md) — v1 `MigrationError` → v2 `SodaxError<C>` with `feature: 'migration'`. Note the BALN lock-method carve-out (still throws).
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.migration.<method>(...)` (orchestrators + intent creators) has `if (!result.ok)`.
+3. BALN lock-method calls (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) remain wrapped in `try/catch` — they do not return `Result<T>`.
+
+## Related granular skills (same family)
+
+- [`../staking/SKILL.md`](../staking/SKILL.md) — generic SODA staking (different from BALN lockup, which migrates BALN → SODA in one step).
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — recovery for stuck migration assets on the hub.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

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

@@ -0,0 +1,58 @@
+# Migration — `@sodax/sdk` v1 → v2
+
+This tree is the v1 → v2 migration playbook for **existing consumers**. If you're starting fresh on v2 with no v1 code to port, skip to [`README.md`](../../integration/knowledge/README.md).
+
+## What v2 changes (the 30-second version)
+
+v2 was a deep architectural reshape, not a feature release. Five orthogonal changes account for ~95% of the breakage your typecheck will surface:
+
+1. **Per-chain `*SpokeProvider` classes are gone.** Routing is by chain key (`srcChainKey: ChainKeys.ETHEREUM_MAINNET`). The SDK dispatches to the right per-chain spoke service internally; consumers pass `walletProvider` directly into payloads.
+2. **`Result<T>` everywhere.** Every async public method on every service returns `Promise<Result<T, SodaxError<C>>>`. v1 throw-on-error patterns are gone.
+3. **One canonical error class.** `SodaxError<C>` with a closed 13-code vocabulary plus `feature: 'swap' | 'moneyMarket' | …`. The per-module typed error unions (`MoneyMarketError<Code>`, `IntentError<Code>`, `StakingError<Code>`, `BridgeError<Code>`, `MigrationError<Code>`, `AssetServiceError<Code>`, `ConcentratedLiquidityError<Code>`, partner errors, …) are deleted.
+4. **`WalletProviderSlot<K, Raw>` is the discriminated union.** Every signed-execution method takes `{ raw: false, walletProvider }` (chain-narrowed via `GetWalletProviderType<K>`); every raw-tx-building method takes `{ raw: true }` (no wallet provider). Compile-time enforced.
+5. **`ConfigService` is the preferred lookup surface.** `hubAssets` and `*_MAINNET_CHAIN_ID` constants **are deleted** (won't compile). `moneyMarketSupportedTokens`, `SodaTokens`, `supportedSpokeChains` **are still exported** as packaged-default constants (so v1 imports keep compiling), but prefer `sodax.config.*` / `sodax.moneyMarket.getSupportedTokens*()` — those reflect backend-driven runtime updates after `await sodax.config.initialize()`. See [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § 2 for the per-symbol table.
+
+The remainder is per-feature (return shape diffs, field renames, new required params like `srcAddress`).
+
+## Reading order
+
+Read in this order. Each step builds on the last.
+
+1. **[`ai-rules.md`](ai-rules.md)** — DO / DO NOT / workflow / stop-conditions. Read first, then dive in.
+2. **This file.** Cross-cutting glossary below + reference list of breaking-changes / features / checklist.
+3. **[`checklist.md`](checklist.md)** — the 17-step cross-cutting migration checklist. Walk top-down, mark items off as you go.
+4. **[`breaking-changes/type-system.md`](breaking-changes/type-system.md)** — fix every import + type-level error first. Once your imports compile, the rest is tractable.
+5. **[`breaking-changes/architecture.md`](breaking-changes/architecture.md)** — `*SpokeProvider` deletion, `ConfigService` replacing static lookups, relay-flow reshape, `sodaxInvariant` + per-feature aliases.
+6. **[`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md)** — convert call-site error handling, then run the v1↔v2 error-code crosswalk.
+7. **[`features/<x>.md`](features/)** — port the call sites for each feature you use. Pair with [`features/`](../../integration/knowledge/features/) (same filename) when you need the v2 design context.
+8. **[`recipes.md`](recipes.md)** — codemods and adapters when full conversion in one pass isn't realistic.
+
+## v1 ↔ v2 glossary (terms that changed meaning)
+
+Same word, different concept across versions. Skim before reading the breaking-changes files — this dictionary prevents the most common porting confusions.
+
+| Term | v1 meaning | v2 meaning |
+|---|---|---|
+| **spoke provider** | A per-chain class instance (`EvmSpokeProvider`, `SolanaSpokeProvider`, …) consumers constructed and passed into every SDK call. | A per-chain-family service inside the SDK, owned by `SpokeService` and routed to via `getSpokeService(chainKey)`. Consumers never construct one. |
+| **chain id** | Numeric or string identifier varying by chain family. v1 had `*_MAINNET_CHAIN_ID` constants, often unifying as `SpokeChainId`. | A string literal from `ChainKeys.*` (the value union is `SpokeChainKey`). `ChainKeys.ICON_MAINNET` is `'0x1.icon'` (a string), not a number. |
+| **error / `*Error<Code>`** | One typed-error union per module: `MoneyMarketError<MoneyMarketErrorCode>`, `IntentError<IntentErrorCode>`, etc. Discriminated by `error.code`. | One canonical class `SodaxError<C>` for all features. 13-code reason vocabulary. Discriminated by `(error.feature, error.code)`; the producing feature is a first-class field. |
+| **chain narrowing** | A combination of `instanceof EvmSpokeProvider` and string equality on `chainConfig.chain.type`. | Pure type-level narrowing via `GetChainType<K>` and `GetWalletProviderType<K>` flowing from a literal `srcChainKey` generic. Runtime variant: `walletProvider.chainType === 'EVM'` (every `I*WalletProvider` declares a `readonly chainType` literal). |
+| **raw tx** | An ad-hoc method on each spoke provider, sometimes named `executeXxx`, returning a chain-specific payload. | The discriminator `{ raw: true }` on the standard SDK call shape. Return type narrows via `TxReturnType<K, true>` (`EvmRawTransaction`, `SolanaRawTransaction`, …). |
+| **config** | A `SodaxConfig` object passed at construction with hard-coded chain/token tables. Solver endpoints lived under `SodaxConfig.swaps`. | A `Sodax` instance owns a `ConfigService` that loads from the backend API, with packaged defaults as fallback. `sodax.config.*` is the lookup surface. **Solver endpoints moved to `SodaxConfig.solver`** (not `swaps`); `swaps` is `SwapsConfig` (supported tokens). |
+| **`xChainId` field on tokens** | Field name on the `Token` type. | Renamed: `XToken.chainKey`. Type also renamed: `Token` → `XToken`. |
+| **`hubAssets` / `moneyMarketSupportedTokens`** | Static `Record` global maps imported and walked. | `hubAssets` **deleted** — won't compile. `moneyMarketSupportedTokens` **still exported** as a packaged default, but prefer `sodax.config.*` and `sodax.moneyMarket.getSupportedTokens*()` so backend updates take effect. Each `XToken` now carries `vault` and `hubAsset` directly. |
+| **`SubmitSwapTxRequest.srcChainId`** | Numeric chain id field on the backend submit-swap request. | Renamed: `srcChainKey: SpokeChainKey`. |
+| **`Intent.srcChain` / `Intent.dstChain`** | Read shape: `IntentRelayChainId` (bigint). | **Unchanged.** This is the relay chain id, not a spoke chain key. A blanket grep-replace `srcChain`→`srcChainKey` will break this. |
+| **`AddressType`** | Bitcoin-specific address-type union. | Renamed: `BtcAddressType`. (Generic name freed up.) |
+
+## Cross-references to integration
+
+Every breaking-change file in this tree has a v2-design counterpart in [`sodax-sdk` (integration mode)](../../integration/knowledge/). Follow the link when "what does v2 expect instead?" comes up:
+
+- [`breaking-changes/type-system.md`](breaking-changes/type-system.md) ↔ [`architecture.md`](../../integration/knowledge/architecture.md) (§ ChainKeys, WalletProviderSlot, Result, SodaxError) and [`reference/`](../../integration/knowledge/reference/) (chain-key + error-code tables).
+- [`breaking-changes/architecture.md`](breaking-changes/architecture.md) ↔ [`architecture.md`](../../integration/knowledge/architecture.md) (§ SpokeService, Sodax facade, ConfigService, relay layer).
+- [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md) ↔ [`recipes/`](../../integration/knowledge/recipes/) (§ Result handling, error discrimination).
+- [`features/<x>.md`](features/) ↔ [`features/`](../../integration/knowledge/features/) (same filename).
+- [`recipes.md`](recipes.md) ↔ no integration counterpart (migration-only patterns).
+
+The pair-completeness rule: every file in `migration/features/` has a sibling in `integration/features/` with the same filename. Use this when you're stuck in one and want the other view.

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

@@ -0,0 +1,76 @@
+# AI rules — `@sodax/sdk` v1 → v2 migration
+
+DO / DO NOT / workflow / stop conditions for AI agents porting v1 `@sodax/sdk` consumer code to v2. Read this **before** the per-feature migration files — these rules prevent the most common porting mistakes.
+
+## Workflow (do these in order)
+
+1. **Survey the consumer.** Grep for v1 fingerprints to scope the migration:
+
+   ```bash
+   pnpm tsc --noEmit > /tmp/v1-errors.log 2>&1   # baseline error population
+   grep -rE '_MAINNET_CHAIN_ID\b|\bSpokeProvider\b|\bxChainId\b|\bSpokeChainId\b|hubAssets|moneyMarketSupportedTokens' src/
+   grep -rE 'instanceof (MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError)' src/
+   ```
+
+2. **Read the cross-cutting docs first.** [`README.md`](README.md) → [`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). Then [`features/<x>.md`](features/) for each feature you use.
+3. **Apply changes in order: type-level first, runtime second.** Type-level renames don't affect behavior; runtime patterns (Result branching, error model) require thinking. Doing them in the wrong order means the typecheck stays noisy and you can't see the real problems.
+4. **Re-run `pnpm tsc --noEmit` after every step.** Each step should reduce the error count. If errors grow, you've introduced something — back out and try again.
+
+> **v2 cross-cutting rules apply too.** Everything in [`integration/ai-rules.md`](../../integration/knowledge/ai-rules.md) (Result branching, `isSodaxError`, `TxHashPair`, `BalnSwapService` throws, package-root imports, no `@sodax/types` peer dep, …) holds when writing migrated code. The DO / DO NOT below are **migration-specific** rules on top.
+
+## DO (migration-specific)
+
+- **DO** start with mechanical type renames:
+  - `*_MAINNET_CHAIN_ID` → `ChainKeys.*` (regex: `(\w+)_MAINNET_CHAIN_ID` → `ChainKeys.$1_MAINNET`).
+  - `xChainId` → `chainKey` (on `XToken` and tokens-likes).
+  - `SpokeChainId` / `ChainId` → `SpokeChainKey`.
+  - `Token` → `XToken`.
+  - `AddressType` → `BtcAddressType` (only at `@sodax/types` import sites).
+- **DO** add `srcChainKey` + `srcAddress` to every action params object (every `MoneyMarketSupplyParams`, `StakeParams`, `CreateAssetDepositParams`, etc. now requires both).
+- **DO** add the `raw: false` (or `raw: true`) discriminator to every signed call shape that previously took `{ intentParams, spokeProvider }`. Also rename `intentParams` → `params` and drop `spokeProvider` in favor of `walletProvider`.
+- **DO** convert v1 `try/catch` to `result.ok` branching last — touching every call site is the biggest commit, easiest to do once the type-level changes settled.
+- **DO** treat the `Result<T>` ↔ `try/catch` migration as the *highest-leverage* change. If you stop early, ensure result branching is at least in place even if the surrounding error UX is rough.
+
+## DO NOT (migration-specific)
+
+- **DO NOT** grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` *read* shape (returned from `createIntent` / `getIntentByHash` / etc.) keeps `srcChain` and `dstChain` as `IntentRelayChainId` (bigint) — those did **not** rename. Only **request** types changed (`CreateIntentParams`, `CreateLimitOrderParams`, `SubmitSwapTxRequest`).
+- **DO NOT** treat `instanceof MoneyMarketError` (or any other module-error class) as still working. Those classes are deleted. Replace with `isSodaxError(e) && e.feature === 'moneyMarket'`.
+- **DO NOT** pass v1 spoke-side state into `getStakingInfo(hubAddress)`. The method is still public in v2 but expects a *hub* address. v1 call sites that used `spokeProvider`-derived data should switch to `getStakingInfoFromSpoke(srcAddress, srcChainKey)` which derives the hub wallet internally.
+- **DO NOT** keep `try { await sodax.swaps.createIntent(...) } catch` and expect to inspect `e.code === 'CREATE_INTENT_FAILED'`. The v2 code is `INTENT_CREATION_FAILED` and lives on `result.error.code` (Result branch), not on a thrown error. See [`reference/error-code-crosswalk.md`](reference/error-code-crosswalk.md) for the full v1 → v2 code crosswalk.
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| v1 code uses framework-layer wrapper hooks (any `use*` identifier that wraps SDK calls rather than calling `@sodax/sdk` directly) | This migration tree covers Core SDK call sites only. Framework-layer migrations live in their own skills under `@sodax/skills` (e.g. `sodax-dapp-kit` (migration mode), `sodax-wallet-sdk-react` (migration mode)). Tell the user to load those. |
+| v1 code uses `@sodax/wallet-sdk-core` classes | Those classes still exist in v2 of that separate package. Their constructor shapes may have changed — refer to that package's docs, not this tree. |
+| Consumer wants to skip the `Result<T>` migration | Explain that v2 SDK calls don't throw for SDK-level failures; without `result.ok` branching the consumer silently swallows errors. Don't silently skip. |
+| Consumer maintains a `*SpokeProvider` wrapper / shim | Don't try to recreate a v1-shaped wrapper in v2 — pass `walletProvider` directly into call payloads. The wrapper isn't doing useful work in v2's design. |
+
+## Verification protocol
+
+```bash
+# 1. Typecheck must reach zero errors.
+pnpm tsc --noEmit
+
+# 2. No leftover v1 fingerprints.
+grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b|\bSpokeChainId\b|\bSpokeProvider\b|hubAssets|moneyMarketSupportedTokens' src/   # should be empty
+
+# 3. No leftover v1 error type imports.
+grep -rE 'MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError' src/   # should be empty
+
+# 4. No leftover try/catch around SDK calls expecting to catch SDK-level failures.
+#    (Manual review — heuristic, not mechanical.)
+grep -rB1 -A3 'try {' src/ | grep -A2 'await sodax\.'   # eyeball each match
+```
+
+## Done criteria
+
+- [ ] `pnpm tsc --noEmit` returns 0 errors.
+- [ ] No `*_MAINNET_CHAIN_ID` references remain.
+- [ ] No `xChainId` field accesses remain.
+- [ ] No `SpokeProvider` / `*SpokeProvider` references remain.
+- [ ] No imports of `MoneyMarketError`, `IntentError`, `StakingError`, etc.
+- [ ] Every `await sodax.<feature>.<method>(...)` call site has `if (!result.ok)` branching.
+- [ ] `instanceof SodaxError` is replaced with `isSodaxError(e)` in cross-bundle code.
+- [ ] `BalnSwapService` lock methods are wrapped in `try/catch` (still-throws carve-out).