@sodax/skills 2.0.0-rc.4

package/knowledge/dapp-kit/migration/reference/error-shape-crosswalk.md

@@ -0,0 +1,144 @@
+# Error shape crosswalk — v1 → v2
+
+The shape and type of errors flowing through dapp-kit hooks changed in v2. The change is mostly SDK-level (one canonical `SodaxError<C>` replaces 7+ per-feature classes) but it surfaces in dapp-kit at the consumer level — wherever you catch or branch on errors from hooks.
+
+## Where v2 errors appear
+
+| Surface | v1 | v2 |
+|---|---|---|
+| `mutation.error` | Only on actual exceptions | Includes SDK `!ok` errors (now thrown inside `mutationFn`) |
+| `mutation.data` | `Result<T>` (`{ ok, value, error }`) | Unwrapped success type `T`; SDK `!ok` flows to `mutation.error` |
+| `mutateAsync` rejection | Only on exceptions | Includes SDK `!ok` rejections |
+| `mutateAsyncSafe` `result.error` | (didn't exist) | Includes SDK `!ok` errors (re-packed from the throw) |
+| `onError` callback | Fired only for exceptions | Fires for SDK `!ok` too |
+
+The semantic shift is: v1 treated SDK `!ok` as "successful but with an error inside"; v2 treats it as a thrown error. See [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) for the full picture.
+
+## Error class crosswalk (SDK-level — leaks through)
+
+In v1, each SDK feature had its own error class:
+
+```ts
+// @ai-snippets-skip — describes deleted v1 type surface, not runnable
+// v1
+class MoneyMarketError<C extends MoneyMarketErrorCode> extends Error { /* ... */ }
+class IntentError<C extends IntentErrorCode> extends Error { /* ... */ }
+class StakingError<C extends StakingErrorCode> extends Error { /* ... */ }
+class BridgeError<C extends BridgeErrorCode> extends Error { /* ... */ }
+class MigrationError<C extends MigrationErrorCode> extends Error { /* ... */ }
+class AssetServiceError<C extends AssetServiceErrorCode> extends Error { /* ... */ }
+class ConcentratedLiquidityError<C extends ConcentratedLiquidityErrorCode> extends Error { /* ... */ }
+// ...
+```
+
+In v2, all are consolidated:
+
+```ts
+// @ai-snippets-skip — type-shape reference; the real class is exported from @sodax/sdk
+// v2
+class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
+  readonly code: C;                  // closed reason union (no feature prefix)
+  readonly feature: SodaxFeature;    // 'swap' | 'moneyMarket' | 'bridge' | …
+  readonly cause?: unknown;
+  readonly context?: SodaxErrorContext;
+}
+```
+
+Discriminate via `(error.feature, error.code)` instead of class name.
+
+## Error code crosswalk (key examples)
+
+The SDK reduced the per-feature code unions to a unified 13-code reason vocabulary, with feature-specific context on `error.context.action` / `error.context.method`. Examples:
+
+| v1 (per-feature) | v2 |
+|---|---|
+| `MoneyMarketError<'CREATE_SUPPLY_INTENT_FAILED'>` | `SodaxError<'INTENT_CREATION_FAILED'>` with `feature: 'moneyMarket'`, `context.action: 'supply'` |
+| `MoneyMarketError<'SUPPLY_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'moneyMarket'`, `context.action: 'supply'` |
+| `IntentError<'CREATE_INTENT_FAILED'>` | `SodaxError<'INTENT_CREATION_FAILED'>` with `feature: 'swap'`, `context.action: 'createIntent'` |
+| `IntentError<'POST_EXECUTION_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'swap'`, `context.phase: 'postExecution'` |
+| `StakingError<'STAKE_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'staking'`, `context.action: 'stake'` |
+| `BridgeError<'BRIDGE_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'bridge'`, `context.action: 'bridge'` |
+| `MigrationError<'MIGRATE_BNUSD_FORWARD_FAILED'>` | `SodaxError<'EXECUTION_FAILED'>` with `feature: 'migration'`, `context.action: 'migratebnUSD'`, `context.direction: 'forward'` |
+| `*Error<'ALLOWANCE_CHECK_FAILED'>` | `SodaxError<'ALLOWANCE_CHECK_FAILED'>` (unchanged code; new feature/context fields) |
+| `*Error<'APPROVE_FAILED'>` | Same |
+| `*Error<'GAS_ESTIMATION_FAILED'>` | Same |
+| `*Error<'RELAY_TIMEOUT'>` | `SodaxError<'RELAY_TIMEOUT'>` with `relayCode: 'RELAY_TIMEOUT'` on context |
+
+Full crosswalk (per feature): [`@sodax/sdk`: `migration/reference/error-code-crosswalk.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/migration/reference/error-code-crosswalk.md).
+
+## How to migrate error-handling code
+
+### Pattern 1: `instanceof` checks → `isSodaxError`
+
+```diff
+- catch (e) {
+-   if (e instanceof MoneyMarketError) {
+-     handleMmError(e.code);
+-   }
+- }
++ catch (e) {
++   if (isSodaxError(e) && e.feature === 'moneyMarket') {
++     handleMmError(e.code);
++   }
++ }
+```
+
+`isSodaxError` is exported from `@sodax/dapp-kit` (re-exported from `@sodax/sdk`).
+
+### Pattern 2: switch on code
+
+```diff
+  catch (e) {
+-   if (e instanceof IntentError) {
+-     switch (e.code) {
+-       case 'CREATE_INTENT_FAILED': /* ... */ break;
+-       case 'POST_EXECUTION_FAILED': /* ... */ break;
+-       case 'RELAY_TIMEOUT': /* ... */ break;
+-     }
+-   }
++   if (isSodaxError(e) && e.feature === 'swap') {
++     switch (e.code) {
++       case 'INTENT_CREATION_FAILED': /* was CREATE_INTENT_FAILED */ break;
++       case 'EXECUTION_FAILED':       /* was POST_EXECUTION_FAILED — check e.context.phase */ break;
++       case 'RELAY_TIMEOUT':           /* unchanged code */ break;
++     }
++   }
+  }
+```
+
+### Pattern 3: error-text helper
+
+If your v1 code has a helper that maps `error.code` to a UI message, write a small adapter:
+
+```ts
+// adapters/v1ErrorShape.ts
+import { isSodaxError } from '@sodax/dapp-kit';
+
+const V1_CODE_MAP: Record<string, string> = {
+  'INTENT_CREATION_FAILED': 'CREATE_INTENT_FAILED',
+  'EXECUTION_FAILED': 'POST_EXECUTION_FAILED',
+  // ... etc.
+};
+
+export function adaptToV1Code(error: unknown): string | undefined {
+  if (!isSodaxError(error)) return undefined;
+  return V1_CODE_MAP[error.code] ?? error.code;
+}
+```
+
+Plan to delete the adapter once you've ported all error UI.
+
+## Pitfalls
+
+1. **`onError` callbacks fire MORE in v2.** They previously didn't fire for SDK `!ok` (success-path-with-error pattern). Now they do. Audit toasts / logs to make sure they're appropriate.
+2. **`mutation.error` reads MORE in v2.** Same reason — SDK errors flow through it now.
+3. **`isSodaxError(e)` is the cross-bundle-safe check.** Bare `instanceof SodaxError` may break in monorepos with multiple package copies (mixed ESM/CJS, etc.). Use the type guard.
+4. **The `feature` field is your discriminator.** A `SodaxError` from a swap mutation has `feature: 'swap'`. A bridge mutation has `feature: 'bridge'`. The `code` is the reason; `feature` is the source.
+
+## Cross-references
+
+- [`../breaking-changes/result-handling.md`](../breaking-changes/result-handling.md) — semantic shift in `Result<T>` handling.
+- [`../breaking-changes/sdk-leakage.md`](../breaking-changes/sdk-leakage.md) — broader SDK-side migrations.
+- [`@sodax/sdk`: `migration/breaking-changes/result-and-errors.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/migration/breaking-changes/result-and-errors.md) — full SDK error-class consolidation.
+- [`@sodax/sdk`: `migration/reference/error-code-crosswalk.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/sdk/migration/reference/error-code-crosswalk.md) — per-feature error code crosswalks.
+- [`../../integration/architecture.md`](../../integration/architecture.md) § "SDK Result handling" — design rationale.

package/knowledge/dapp-kit/migration/reference/renamed-hooks.md

@@ -0,0 +1,68 @@
+# Renamed hooks — v1 → v2
+
+Hooks whose **name** changed between versions. Most v1 → v2 changes were signature-level (single-object params, `mutateAsyncSafe`, etc.) — actual hook renames are rare. The list below is the small set.
+
+## Hooks renamed
+
+| v1 | v2 | Notes |
+|---|---|---|
+| (none significant) | | Most hook names are stable across v1 → v2 |
+
+### Why this list is short
+
+The v2 canonicalization pass focused on hook **shapes** (single-object params, return-shape consolidation, mutateAsyncSafe), not naming. For most consumer code, the hook name you `import { ... }`'d in v1 is still the right hook in v2 — the breaking change is in the call shape, not the import.
+
+## Hooks whose generic / type shape changed
+
+These keep their name but their TypeScript signature is different. Usually requires per-call-site fixes.
+
+| Hook | v1 → v2 change |
+|---|---|
+| `useSwap` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params } → { params, walletProvider }`. |
+| `useSwapAllowance` | Query params: `(params, spokeProvider) → { params: { payload, srcChainKey, walletProvider } }`. SDK request nested under `params.payload`. Data unwrapped to `boolean`. |
+| `useSwapApprove` | Return: `{ approve, isLoading } → SafeUseMutationResult` (with `mutateAsync` / `isPending`). Vars accept `CreateIntentParams \| CreateLimitOrderParams`. TData is `TxReturnType<K, false>` (chain-keyed receipt union). |
+| `useStatus` | Now `useStatus({ params: { intentTxHash } })` — single-object shape AND key renamed from `intentHash` → `intentTxHash`. Data is `Result<SolverIntentStatusResponse, SolverErrorResponse> \| undefined` (Result-wrapped). Polls 3s. |
+| `useQuote` | Now `useQuote({ params: { payload } })` — SDK request nested under `params.payload` (NOT directly under `params`). Data is `Result<SolverIntentQuoteResponse, SolverErrorResponse> \| undefined`. Polls 3s. |
+| `useCancelSwap` / `useCancelLimitOrder` | TVars are FLAT (no `params` wrapper): `{ srcChainKey, intent, walletProvider }`. |
+| `useCreateLimitOrder` | Hook init: `(spokeProvider) → ({ mutationOptions })`. Vars: `{ params, walletProvider }`. mutationKey is `['swap', 'limitOrder', 'create']`. |
+| All MM mutations (`useSupply`/etc.) | Same as `useSwap`. Plus `srcChainKey` / `srcAddress` required in params (SDK-leakage). All four actions accept optional `dstChainKey`/`dstAddress` for cross-chain delivery (not just borrow/repay). |
+| `useMMAllowance` | Query params: `{ params: { payload: MoneyMarketParams<K> } }`. For `'borrow'` / `'withdraw'` actions: `enabled: false` — `data` stays `undefined`. |
+| `useUserReservesData` | Param key rename: `address → userAddress`; chain key is `spokeChainKey`. |
+| `useUserFormattedSummary` | Same. |
+| `useATokensBalances` | Params: `{ aTokens, spokeProvider, userAddress } → { params: { aTokens, spokeChainKey, userAddress } }`. `spokeProvider` dropped; chain key is **`spokeChainKey`** (NOT `srcChainKey`); user field is **`userAddress`** (NOT `address`). Data: `Map<Address, bigint> \| undefined` (already unwrapped). |
+| `useAToken` | Unaffected by the position-hook renames — takes only `{ aToken }`. Data: `Erc20Token & { chainKey }` (`hubAsset` / `vault` NOT included). |
+| All staking mutations | Same as MM. Plus dedicated approve hooks per token (`useStakeApprove` ↔ `useUnstakeApprove` ↔ `useInstantUnstakeApprove`). |
+| `useStakeRatio` | Return: `Result<bigint> → [xSodaAmount, previewDepositAmount]` (unwrapped tuple — NOT Result-wrapped in v2). |
+| `useStakingInfo` / `useUnstakingInfo` / `useUnstakingInfoWithPenalty` / `useStakingConfig` / `useInstantUnstakeRatio` / `useConvertedAssets` | All unwrapped in v2 (hooks throw on SDK `!ok`). Branch on `isError`/`error`, not `data?.ok`. |
+| `useUnstakingInfo` | Return shape: array → object `{ userUnstakeSodaRequests, totalUnstaking }`. `UserUnstakeInfo` items expose `id` (the requestId) and `request` (original `UnstakeSodaRequest`). |
+| All three staking allowance hooks | Query params: `{ params: { payload: Omit<<Action>Params<K>, 'action'> } }`. Data unwrapped to `boolean`. |
+| `useBridge` | Params: `srcChainId/dstChainId/recipient → srcChainKey/dstChainKey/recipient`. Plus field renames inside `CreateBridgeIntentParams`: `srcAsset → srcToken`, `dstAsset → dstToken`. Return: tuple → `TxHashPair` object (`{ srcChainTxHash, dstChainTxHash }`). |
+| `useBridgeAllowance` | Query params: nested `{ params: { payload, walletProvider } }`. Data unwrapped to `boolean` (queryFn returns `false` on SDK `!ok` — does NOT throw). |
+| `useGetBridgeableAmount` | Params: 4 fields → `{ from: XToken, to: XToken }`. Return: `bigint → BridgeLimit` object (`{ amount, decimals, type: 'DEPOSIT_LIMIT' \| 'WITHDRAWAL_LIMIT' }`). |
+| `useGetBridgeableTokens` | Params: positional → `{ params: { from, to, token } }`. |
+| All DEX mutations | Same as MM. `useSupplyLiquidity` now handles both mint-new and increase-existing — fan-out gated by `params.tokenId` + `params.isValidPosition`. |
+| `useDexAllowance` | Now `{ params: { payload: CreateAssetDepositParams<K> } }`. No `walletProvider` (read-only). |
+| `PoolKey` shape | Real fields are `currency0`, `currency1`, `fee`, `hooks?`, `poolManager`, `parameters` — NOT `poolAddress`/`token0Symbol`/etc. |
+| `useCreate*Params` builders | All take FLAT props object — NOT `{ params }`-wrapped (`useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams`). |
+| `useFeeClaimSwap` (partner) | Same as MM mutation pattern. TData is `IntentAutoSwapResult` (NOT `SwapResponse`). |
+| `useXBalances` | Params: positional → `{ params: { xService, xChainId, xTokens, address } }`. All four required. `xService` injected from `@sodax/wallet-sdk-react`. |
+| `useEstimateGas` | Mutation; vars: `EstimateGasParams<C>` (flat, not `{ params, walletProvider }`-wrapped). |
+| `useDeriveUserWalletAddress`, `useGetUserHubWalletAddress` | Single-object query shape. |
+| `useStellarTrustlineCheck` | Single-object shape with `{ token, amount, chainId, walletProvider }` under `params`. |
+| `useRequestTrustline` | Custom utility hook (NOT a canonical mutation). Takes `(token: string \| undefined)` positionally, returns `{ requestTrustline, isLoading, isRequested, error, data }`. The `requestTrustline` callback takes `{ token, amount, srcChainKey, walletProvider }`. |
+| `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers` | Pagination MUST be nested under `params`: `{ params: { pagination: { offset, limit } } }`. |
+| `useBackendUserIntents` | Data is `UserIntentsResponse = { items: IntentResponse[], total, offset, limit }` — NOT a bare array. Access `data?.items`. |
+| `useBackendSubmitSwapTx` | Mutation. `apiConfig` moved from hook init to `mutate(vars)`. |
+| All migration hooks | **NEW**: 6 per-action hooks replacing v1's single `useMigrate`. See [`deleted-hooks.md`](deleted-hooks.md). |
+| `useMigrationAllowance` | Query params nest under `params` with inner field literally named `params` (NOT `payload`): `{ params: { params: <migration-params>, action: 'migrate' \| 'revert' } }`. |
+| `BalnMigrateParams` (used by `useMigrateBaln`) | NEW required field `stake: boolean`. `lockupPeriod` is the `LockupPeriod` enum (5 members; values in seconds, not months). |
+| `useTradingWalletBalance` | Return is `RadfiWalletBalance = { btcSatoshi, pendingSatoshi, externalPendingSatoshi, totalUtxos }` — NOT `{ confirmed, pending }`. |
+| `useExpiredUtxos` | Return is `RadfiUtxo[]` (with `_id`, `txid`, `vout`, `txidVout`, `satoshi`, `amount`, `address`, `isSpent`, `status`, `source`, optional `runes`). Both this and `useTradingWalletBalance` take `{ params: { walletProvider, tradingAddress } }`. |
+| `useRadfiAuth` | TData is `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields — `publicKey` is persisted to localStorage but NOT returned). |
+| All Bitcoin/Radfi mutations | Standard pattern — drop hook-init args; pass through `mutate(vars)`. |
+
+## Cross-references
+
+- [`deleted-hooks.md`](deleted-hooks.md) — hooks that no longer exist at all.
+- [`../breaking-changes/hook-signatures.md`](../breaking-changes/hook-signatures.md) — shape changes in detail.
+- [`../features/`](../features/) — per-feature porting playbooks.

package/knowledge/sdk/AGENTS.md

@@ -0,0 +1,41 @@
+# Knowledge tree — `@sodax/sdk`
+
+Long-form knowledge supporting the `@sodax/sdk` skills under `@sodax/skills`. The action-oriented entry points are the SKILL.md files in the sibling `skills/` directory:
+
+- New code → `packages/skills/skills/sodax-sdk-integration/SKILL.md`
+- Porting v1 → `packages/skills/skills/sodax-sdk-migration/SKILL.md`
+
+**Don't read this tree top-to-bottom.** Load files from the **Workflow** section of the relevant SKILL.md — token budgets are sized so the right 2–3 files fit in your context.
+
+## Package summary
+
+`@sodax/sdk` is the official SDK for SODAX, a cross-chain DeFi platform built on a hub-and-spoke architecture (Sonic is the hub; 19 spoke chains across EVM and non-EVM ecosystems). The SDK provides cross-chain swaps (intent-based via solver), lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN migration, and partner-fee operations. It is runtime-agnostic and runs in Node.js, browsers, and bundled apps.
+
+This package is **v2**. v2 was a deep architectural reshape of v1 — chain-key driven routing replaced per-chain provider classes; `Result<T>` replaced throwing methods; `SodaxError<C>` replaced module-specific error unions; `WalletProviderSlot<K, Raw>` replaced ad-hoc wallet/raw branching; `ConfigService` replaced static lookup tables. Code written against v1 will not compile against v2.
+
+## Layout
+
+```
+knowledge/sdk/
+├── AGENTS.md                      # You are here
+├── integration/                   # New v2 code
+│   ├── README.md                  # Index for this tree
+│   ├── ai-rules.md                # DO / DO NOT / workflow — read before per-feature docs
+│   ├── quickstart.md              # Install + initialize + first-run troubleshooting
+│   ├── architecture.md            # Every v2 design concept (TOC-navigable)
+│   ├── features/                  # One file per feature service (swap, money-market, staking, bridge, dex, icx-bnusd-baln, auxiliary-services)
+│   ├── recipes/                   # One file per pattern (init, result/errors, raw, signed, narrowing, testing, gas, backend-init)
+│   ├── reference/                 # One file per table (chain keys, wallet providers, error codes, public API, glossary)
+│   └── chain-specifics.md         # Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR)
+└── migration/                     # Port v1 → v2
+    ├── README.md
+    ├── ai-rules.md
+    ├── breaking-changes/          # type-system / architecture / result-and-errors
+    ├── features/                  # Per-feature migration playbooks
+    └── recipes.md                 # Codemods + error-shape adapter + Result adapter
+```
+
+## Cross-references
+
+- Higher-level React layer: `packages/skills/knowledge/dapp-kit/` (the `@sodax/dapp-kit` knowledge tree).
+- Wallet provider impls: `packages/skills/knowledge/wallet-sdk-core/` (Node/script signing) and `packages/skills/knowledge/wallet-sdk-react/` (React).

package/knowledge/sdk/integration/README.md

@@ -0,0 +1,41 @@
+# Integration — `@sodax/sdk` v2
+
+This tree documents v2 of the SDK for **new consumers** building against it. If you're porting v1 code, start at [`../migration/README.md`](../migration/README.md) instead.
+
+## Files in this tree
+
+| File | What's in it |
+|---|---|
+| [`quickstart.md`](quickstart.md) | Install, initialize a `Sodax` instance, and the top init/setup errors and how to fix them. Covers reads (no wallet), raw-tx flows (no wallet), and signed flows (consumer-supplied wallet provider). |
+| [`architecture.md`](architecture.md) | Every v2 design concept the SDK rests on, in a single TOC-navigable file: hub-and-spoke model, `SpokeService` router, `Sodax` facade + `ConfigService`, `ChainKeys`, `WalletProviderSlot<K, Raw>`, `Result<T>`, `SodaxError<C>` + 13-code vocabulary, relay layer (`mapRelayFailure`, `relayTxAndWaitPacket`). |
+| [`features/swap.md`](features/swap.md) | `SwapService`: intent-based swaps via the solver — `createIntent`, `swap`, `postExecution`, limit orders, `cancelIntent`. |
+| [`features/money-market.md`](features/money-market.md) | `MoneyMarketService`: cross-chain lending/borrowing — supply, borrow, withdraw, repay, reserves, allowance. |
+| [`features/staking.md`](features/staking.md) | `StakingService`: SODA → xSoda — stake, unstake, instant unstake, claim, cancel; ratio + info reads. |
+| [`features/bridge.md`](features/bridge.md) | `BridgeService`: cross-chain token transfer via vault — `bridge`, `createBridgeIntent`, `getBridgeableAmount`, `getBridgeableTokens`. |
+| [`features/dex.md`](features/dex.md) | `ClService` (concentrated liquidity) + `AssetService`: position lifecycle (mint/increase/decrease), claim rewards, asset deposit/withdraw. |
+| [`features/icx-bnusd-baln.md`](features/icx-bnusd-baln.md) | `MigrationService` (the SDK module): ICX, bnUSD, BALN sub-services + lock management. |
+| [`features/auxiliary-services.md`](features/auxiliary-services.md) | `PartnerService` + `RecoveryService` + `BackendApiService` — small APIs grouped together. |
+| [`recipes/`](recipes/) | Copy-pasteable patterns: SDK initialization, `Result` + error discrimination, raw-tx flow, signed-tx flow, chain-key narrowing + cast-at-boundary, testing (mocks/stubs), gas estimation, backend-server init. |
+| [`reference/`](reference/) | Lookup tables: 20-chain `ChainKeys` table with family + relay id, `I*WalletProvider` interfaces, 13 `SodaxErrorCode` meanings + per-feature narrow unions, public API surface (incl. `@sodax/types` re-export rule), glossary. |
+| [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT + Radfi auth/session, Solana PDA derivation, ICON Hana wallet + chain-key string, NEAR connector discovery. |
+
+## Reading order for a new integrator
+
+1. `quickstart.md` — get the SDK installed and a `Sodax` instance running.
+2. `architecture.md` — understand the type system (`ChainKeys`, `Result`, `WalletProviderSlot`, `SodaxError`) before writing call sites.
+3. `recipes/` — pick the patterns you need (signed vs raw, error handling, narrowing).
+4. `features/<x>.md` — read the file for the feature you're integrating.
+5. `chain-specifics.md` — only if you target a non-EVM chain; skip otherwise.
+6. `reference/` — keep open while writing for table lookups.
+
+## Cross-references to migration
+
+If your project also has v1 call sites, port them first using:
+
+- [`../migration/README.md`](../migration/README.md) — overview, reading order, and cross-cutting checklist.
+- [`../migration/breaking-changes/type-system.md`](../migration/breaking-changes/type-system.md) — type renames and shape changes you'll hit on import.
+- [`../migration/breaking-changes/architecture.md`](../migration/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService` replacing static lookups, relay flow reshape.
+- [`../migration/breaking-changes/result-and-errors.md`](../migration/breaking-changes/result-and-errors.md) — throws → `Result<T>` and module errors → `SodaxError<C>`, with the v1↔v2 code crosswalk.
+- [`../migration/features/`](../migration/features/) — per-feature playbooks in lockstep with the integration features here.
+
+The naming rule: **every feature in `integration/features/` has a sibling in `migration/features/` with the same filename.** When you're deep in one, the other is one path-swap away.

package/knowledge/sdk/integration/ai-rules.md

@@ -0,0 +1,75 @@
+# AI rules — `@sodax/sdk` integration
+
+DO / DO NOT / workflow / stop conditions for AI agents writing `@sodax/sdk` v2 code. Read this **before** the per-feature docs — these rules are how you avoid the load-bearing v2 traps.
+
+## Workflow (do these in order)
+
+1. **Survey the project before touching code.**
+
+   ```bash
+   pnpm tsc --noEmit           # baseline typecheck
+   grep -rE '@sodax/(sdk|types)' --include='*.ts' --include='*.tsx' src/   # see what's already imported
+   ```
+
+2. **Always initialize first.** `new Sodax()` constructs the facade; `await sodax.config.initialize()` loads chain/token config from the backend (with packaged-defaults fallback). Skipping `initialize()` works but means stale defaults — `findSupportedTokenBySymbol` may return `undefined` for tokens added after the SDK release.
+3. **Pick `raw: true` vs `raw: false` explicitly.** Reads and unsigned-tx-building flows take `raw: true` and don't need a wallet. Signed flows take `raw: false` + a chain-narrowed `walletProvider`. The discriminator is mandatory — without it the type system rejects the call. See [`architecture.md`](architecture.md) § 6.
+4. **Branch on `result.ok` before reading `.value` or `.error`.** Every async public method returns `Promise<Result<T, SodaxError>>`. `try/catch` does **not** catch SDK-level failures — see DO NOT § below.
+5. **Discriminate errors by `(error.feature, error.code)`.** Use `isSodaxError(e)` first, then switch on the pair. Don't string-match `error.message`.
+
+## DO
+
+- **DO** branch on `result.ok` for every SDK call. Forward sub-`Result`s without re-wrapping (`if (!sub.ok) return sub`).
+- **DO** use `isSodaxError(e)` over bare `instanceof SodaxError`. Bundle-safe in cross-realm code (mixed ESM/CJS, monorepos with multiple package copies).
+- **DO** discriminate errors via `(error.feature, error.code)`. The narrow per-method code unions (e.g. `CreateSupplyIntentErrorCode`) enable exhaustive `switch`.
+- **DO** use `ChainKeys.X` constants for chain identifiers. Never hard-code chain-key string values like `'ethereum'` or `'0xa4b1.arbitrum'`.
+- **DO** use `declare const xxxWallet: I*WalletProvider` placeholders in code examples or generated docs. Implementations are not part of `@sodax/sdk`; substitute the consumer's own wallet object at the call site.
+- **DO** import everything from `@sodax/sdk` root. Types from `@sodax/types` are re-exported.
+- **DO** preserve literal chain keys in generic positions where possible (e.g. `srcChainKey: ChainKeys.ETHEREUM_MAINNET as const`) — TypeScript narrowing flows from the literal, including the `walletProvider` parameter type.
+
+## DO NOT
+
+- **DO NOT** wrap `await sodax.<method>(...)` in `try/catch` and expect SDK-level failures (`RELAY_TIMEOUT`, `EXECUTION_FAILED`, etc.) to land there. They don't — the SDK resolves `{ ok: false, error }` instead of throwing. `catch` only fires for synchronous wrapper exceptions.
+- **DO NOT** import from `@sodax/sdk/dist/...`. Deep imports are unstable across releases; only the package root barrel is the public contract.
+- **DO NOT** add `@sodax/types` as a separate dependency. It's bundled / re-exported via `@sodax/sdk`. Adding it independently invites version skew.
+- **DO NOT** destructure cross-chain mutation results as arrays — `[a, b] = result.value` is wrong. The shape is `TxHashPair = { srcChainTxHash, dstChainTxHash }` (object). This applies to `bridge.bridge`, `staking.{stake,unstake,instantUnstake,claim,cancelUnstake}`, `dex.assetService.{deposit,withdraw}`, `dex.clService.{supplyLiquidity,increaseLiquidity,decreaseLiquidity,claimRewards}`, `moneyMarket.{supply,borrow,withdraw,repay}`, `migration.{migratebnUSD,migrateIcxToSoda,revertMigrateSodaToIcx,migrateBaln}` — all of them.
+- **DO NOT** treat method names from `MoneyMarketService` as the source of MM reads. `getReservesData`, `getUserReservesData`, `getATokensBalances`, etc. live on `sodax.backendApi`, not `sodax.moneyMarket`. See [`features/auxiliary-services.md`](features/auxiliary-services.md) § "BackendApiService".
+- **DO NOT** reach for an `intentRelayApi` property on the `Sodax` instance — there is no such property. The relay layer is exposed as two top-level functions, `relayTxAndWaitPacket` and `submitTransaction` (re-exported from `@sodax/sdk`). Call them directly if you need custom relay orchestration.
+- **DO NOT** call `getStakeRatio` and treat its return as `Result<bigint>`. It's `Result<[xSodaAmount, previewDepositAmount]>` — a tuple of two bigints.
+- **DO NOT** assume `BalnSwapService` lock-management methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw on error in v2 — known carve-out. Wrap them in `try/catch`.
+- **DO NOT** call methods that need a wallet provider with `raw: true` — TypeScript rejects `walletProvider` when `raw: true`. Use `raw: false` + `walletProvider`, or stick to read methods.
+
+## Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| User wants a chain not in `ChainKeys.*` | Adding a new chain requires SDK-level changes to `@sodax/types`/`@sodax/sdk` — out of scope for consumer code. |
+| User wants to skip `await sodax.config.initialize()` | Explain consequences: stale defaults, no awareness of new tokens / fee parameters. Don't silently skip. |
+| User code expects sibling-package imports (e.g. `@sodax/wallet-sdk-core` instances) | Out of scope here — consumer owns the wallet-provider implementation. Document the `I*WalletProvider` shape they need to satisfy or instruct them to install `@sodax/wallet-sdk-core` separately and refer to that package's docs. |
+| User wants browser-extension wallet wiring inside SDK code | Not the SDK's concern. Consumer owns the wallet layer. |
+
+## Verification protocol
+
+Before declaring an SDK integration "done":
+
+```bash
+# 1. Type-check the consumer.
+pnpm -C <consumer> tsc --noEmit
+
+# 2. Confirm no leftover v1 patterns (if porting).
+grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b|\bSpokeChainId\b|\bSpokeProvider\b' src/
+
+# 3. Confirm Result branching is in place.
+grep -rE 'await sodax\.\w+\.\w+\([^)]*\)' src/ | grep -v '\.ok\|\.value\|\.error'   # any SDK call without result.ok / value / error in nearby lines
+
+# 4. Smoke-test a read flow before a signed flow.
+#    sodax.config.findSupportedTokenBySymbol(...) etc. — no wallet needed.
+```
+
+## Done criteria
+
+- [ ] `await sodax.config.initialize()` runs at app startup (or before first feature call).
+- [ ] Every `await sodax.<feature>.<method>(...)` is followed by `if (!result.ok)` branching.
+- [ ] No `try/catch` wraps SDK calls expecting to catch `RELAY_TIMEOUT` / `EXECUTION_FAILED`.
+- [ ] No `import` from `@sodax/sdk/dist/...`.
+- [ ] No standalone `@sodax/types` dependency in `package.json`.
+- [ ] Consumer typecheck (`pnpm tsc --noEmit`) is clean.