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

package/ai-exported/integration/reference/error-codes.md

@@ -0,0 +1,165 @@
+# Error codes
+
+All 13 codes the SDK can emit. Each error is `SodaxError<C>` where `C` is one of these. The producing feature is on `error.feature`.
+
+| Code | Meaning | Common `error.context` fields | Retry advice |
+|---|---|---|---|
+| `VALIDATION_FAILED` | Pre-flight invariant tripped (input shape, unsupported chain, etc.). | `field`, `reason`, `phase: 'validate'` | No — fix the input. |
+| `INTENT_CREATION_FAILED` | Building the intent / payload failed. | `phase: 'intentCreation'`, `action` | Sometimes — depends on root cause (`error.cause`). |
+| `EXECUTION_FAILED` | Orchestrator-level catch-all (multi-step op didn't complete). | `action`, `phase: 'execution'` or `'postExecution'` | Sometimes — inspect cause. |
+| `TX_VERIFICATION_FAILED` | Spoke `verifyTxHash` returned false / threw. | `phase: 'verify'`, `srcChainKey` | Sometimes — RPC / indexer issue is transient. |
+| `TX_SUBMIT_FAILED` | Spoke tx landed; relay POST submit failed. | `phase: 'submit'`, `relayCode: 'SUBMIT_TX_FAILED'` | Yes — relay submit is retryable; backoff and re-run with the same payload. |
+| `RELAY_TIMEOUT` | Destination packet didn't reach `executed` within timeout. | `phase: 'relay'`, `srcChainKey`, `dstChainKey`, `relayCode: 'RELAY_TIMEOUT'` | Yes — increase timeout or re-poll; the spoke tx already landed. |
+| `RELAY_FAILED` | Relay polling outage / unrecognised relay error. | `phase: 'relay'`, `relayCode` | Yes — exponential backoff. |
+| `APPROVE_FAILED` | Token approval call failed. | `phase: 'approve'` | Sometimes — gas / RPC issues are retryable. |
+| `ALLOWANCE_CHECK_FAILED` | Reading on-chain allowance failed. | `phase: 'allowanceCheck'` | Yes — read-only retry is cheap. |
+| `GAS_ESTIMATION_FAILED` | Gas estimation returned an error. | `phase: 'gasEstimation'` | Yes — re-estimate is the norm. |
+| `LOOKUP_FAILED` | Read-only on-chain query / off-chain config fetch. | `method`, `phase: 'lookup'` | Yes — read-only retry is cheap. |
+| `EXTERNAL_API_ERROR` | Upstream API call failed (solver, backend). | `api: 'solver' \| 'backend'`; for solver: `solverCode`, `solverDetail` | Sometimes — depends on `solverCode`. |
+| `UNKNOWN` | Last-resort catch in an outer `try`. | (none guaranteed) | Treat as unrecoverable; surface the underlying cause. |
+
+### Features
+
+```ts
+type SodaxFeature =
+  | 'swap'
+  | 'moneyMarket'
+  | 'bridge'
+  | 'staking'
+  | 'migration'
+  | 'dex'
+  | 'partner'
+  | 'recovery';
+```
+
+The `(feature, code)` pair is the canonical discriminator. Loggers tag both fields; switch statements branch on both.
+
+### Phase tags (`error.context.phase`)
+
+```ts
+type SodaxPhase =
+  | 'validate'           // pre-flight invariant
+  | 'intentCreation'     // building intent / payload
+  | 'verify'             // spoke verifyTxHash
+  | 'submit'             // spoke→relay submit
+  | 'relay'              // primary relayTxAndWaitPacket wait
+  | 'destinationExecution' // secondary watcher (migration's bnUSD waitUntilIntentExecuted)
+  | 'execution'          // orchestrator-level catch
+  | 'postExecution'      // swap-only post-relay solver step
+  | 'approve'            // ERC20 approval call
+  | 'allowanceCheck'     // on-chain allowance read
+  | 'gasEstimation'      // gas-estimation read
+  | 'lookup';            // generic read-only query
+```
+
+### `RelayCode` (`error.context.relayCode`)
+
+```ts
+type RelayCode =
+  | 'SUBMIT_TX_FAILED'
+  | 'RELAY_TIMEOUT'
+  | 'RELAY_POLLING_FAILED'
+  | 'UNKNOWN';
+```
+
+This is the lower-level relay-layer code that `mapRelayFailure` maps from. Surfaces on `error.context.relayCode` when the error originated in `IntentRelayApiService`.
+
+---
+
+
+## Per-method error codes
+
+Narrow code unions per public method. Use these for exhaustive `switch` discrimination.
+
+### Common helper unions (used across features)
+
+```ts
+// 'create*Intent' methods
+type CreateIntentErrorCode = 'VALIDATION_FAILED' | 'INTENT_CREATION_FAILED' | 'UNKNOWN';
+
+// 'approve' methods
+type ApproveErrorCode = 'VALIDATION_FAILED' | 'APPROVE_FAILED' | 'UNKNOWN';
+
+// 'isAllowanceValid' methods
+type AllowanceCheckErrorCode = 'VALIDATION_FAILED' | 'ALLOWANCE_CHECK_FAILED' | 'UNKNOWN';
+
+// 'estimateGas' methods
+type GasEstimationErrorCode = 'VALIDATION_FAILED' | 'GAS_ESTIMATION_FAILED' | 'UNKNOWN';
+
+// All read-only lookups
+type LookupErrorCode = 'VALIDATION_FAILED' | 'LOOKUP_FAILED' | 'UNKNOWN';
+```
+
+### Swap (`feature: 'swap'`)
+
+| Method | Narrow code union |
+|---|---|
+| `createIntent` | `CreateIntentErrorCode` |
+| `swap` | All of {`VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN`} |
+| `postExecution` | `EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` (with `phase: 'postExecution'`) |
+| `createLimitOrder`, `createLimitOrderIntent` | `CreateIntentErrorCode` |
+| `cancelIntent`, `cancelLimitOrder` | `EXECUTION_FAILED \| VALIDATION_FAILED \| UNKNOWN` |
+
+### Money Market (`feature: 'moneyMarket'`)
+
+| Method | Narrow code union |
+|---|---|
+| `supply`, `borrow`, `withdraw`, `repay` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN` (with `action` discriminator) |
+| `createSupplyIntent`, `createBorrowIntent`, `createWithdrawIntent`, `createRepayIntent` | `CreateIntentErrorCode` |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `estimateGas` | `GasEstimationErrorCode` |
+| Read-only methods (reserves, user data, etc.) | `LookupErrorCode` |
+
+### Staking (`feature: 'staking'`)
+
+| Method | Narrow code union |
+|---|---|
+| `stake` | All exec codes including `TX_VERIFICATION_FAILED` (only stake calls verifyTxHash). |
+| `unstake`, `instantUnstake`, `claim`, `cancelUnstake` | All exec codes minus `TX_VERIFICATION_FAILED`. |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `getStakingInfo`, `getUnstakingInfo`, `getStakingConfig`, `getStakeRatio`, `getInstantUnstakeRatio`, `getConvertedAssets`, `getUnstakingInfoWithPenalty`, `getStakingInfoFromSpoke` | `LookupErrorCode` (with `method` discriminator) |
+
+### Bridge (`feature: 'bridge'`)
+
+| Method | Narrow code union |
+|---|---|
+| `bridge` | All exec codes. |
+| `createBridgeIntent` | `CreateIntentErrorCode` |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `getBridgeableAmount`, `getBridgeableTokens` | `LookupErrorCode` (with `method` discriminator) |
+
+### DEX (`feature: 'dex'`)
+
+| Method | Narrow code union |
+|---|---|
+| `assetService.deposit`, `assetService.withdraw` | All exec codes. |
+| `clService.supplyLiquidity`, `clService.increaseLiquidity`, `clService.decreaseLiquidity`, `clService.claimRewards` | All exec codes. |
+| `assetService.approve` | `ApproveErrorCode` |
+| `assetService.isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `clService.getPoolData`, `clService.getPositionInfo`, `assetService.getDeposit` | `LookupErrorCode` |
+
+### Migration (`feature: 'migration'`)
+
+| Method | Narrow code union |
+|---|---|
+| `migratebnUSD` | All exec codes; `direction: 'forward' \| 'reverse'` on context. |
+| `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln` | All exec codes. |
+| `createXxxIntent` (4 of these) | `CreateIntentErrorCode` |
+| `approve` | `ApproveErrorCode` |
+| `isAllowanceValid` | `AllowanceCheckErrorCode` |
+| `getAvailableAmount` | `LookupErrorCode` |
+
+### Partner (`feature: 'partner'`) and Recovery (`feature: 'recovery'`)
+
+Both follow the same shape: action methods get the full exec union (`'EXECUTION_FAILED' \| 'INTENT_CREATION_FAILED' \| ...`), read methods get `LookupErrorCode`, approve methods get `ApproveErrorCode`.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) § 7–8 — error model concepts.

package/ai-exported/integration/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/ai-exported/integration/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` (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) and `ai-exported/` (this docs tree). Nothing else ships.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — reference index.
+- [`../architecture.md`](../architecture.md) — concepts behind these tables.

package/ai-exported/integration/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/ai-exported/migration/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 [`../integration/README.md`](../integration/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` replaces static lookups.** Globals like `hubAssets`, `moneyMarketSupportedTokens`, `SodaTokens`, and the `*_MAINNET_CHAIN_ID` constants are gone. Lookups go through `sodax.config.*` (which loads from the backend API with a packaged-defaults fallback).
+
+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 [`../integration/features/<x>.md`](../integration/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. | Gone. Use `sodax.config.*` and `sodax.moneyMarket.getSupportedTokens*()`. 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 `../integration/`. Follow the link when "what does v2 expect instead?" comes up:
+
+- [`breaking-changes/type-system.md`](breaking-changes/type-system.md) ↔ [`../integration/architecture.md`](../integration/architecture.md) (§ ChainKeys, WalletProviderSlot, Result, SodaxError) and [`../integration/reference/`](../integration/reference/) (chain-key + error-code tables).
+- [`breaking-changes/architecture.md`](breaking-changes/architecture.md) ↔ [`../integration/architecture.md`](../integration/architecture.md) (§ SpokeService, Sodax facade, ConfigService, relay layer).
+- [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md) ↔ [`../integration/recipes/`](../integration/recipes/) (§ Result handling, error discrimination).
+- [`features/<x>.md`](features/) ↔ [`../integration/features/<x>.md`](../integration/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/ai-exported/migration/ai-rules.md

@@ -0,0 +1,80 @@
+# 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.
+
+## DO
+
+- **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** use `isSodaxError(e)` over bare `instanceof SodaxError` in the new error-handling branches. `instanceof` is fragile across bundle copies.
+- **DO** branch on `(error.feature, error.code)` for fine-grained UX. The narrow per-method code unions enable exhaustive `switch`.
+
+## DO NOT
+
+- **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** destructure cross-chain mutation results as arrays. v1 had `bridge()` returning a string and others returning tuples; v2 returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for **every** cross-chain mutation (bridge, staking, dex, MM, migration). Destructure as `{ srcChainTxHash, dstChainTxHash } = result.value`.
+- **DO NOT** assume `BalnSwapService` lock-management methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw — known carve-out. Keep `try/catch` for those specific calls.
+- **DO NOT** keep `try/catch` blocks expecting them to catch SDK-level failures from non-Baln methods. v2 mutation methods resolve `{ ok: false, error }` rather than throwing — `catch` only fires for synchronous wrapper exceptions (e.g. missing `walletProvider`).
+- **DO NOT** call `getStakingInfo(hubAddress)` in v2. It's `getStakingInfoFromSpoke(srcAddress, srcChainKey)` now. `getStakingInfo` is not a public method.
+- **DO NOT** import `@sodax/types` as a peer dependency. It's bundled into `@sodax/sdk`'s public surface; declaring it separately invites version skew.
+- **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 belong to separate ai-exported trees in their own packages. Tell the user to consult 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).