@sodax/sdk 1.5.6-beta → 2.0.0-rc.1

package/README.md

@@ -40,41 +40,55 @@ How to setup local development
 
 <a href="https://docs.sodax.com/developers/packages/sdk/swaps" class="button secondary" data-icon="rotate">Swaps (Solver)</a> -  Cross-chain intent-based swaps
 
-* EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, Lightlink) ✅
+* EVM (Sonic, Ethereum, Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, HyperEVM, Lightlink, Redbelly, Kaia) ✅
 * Sui ✅
 * Stellar ✅
 * ICON ✅
 * Solana ✅
 * Injective ✅
+* NEAR ✅
+* Stacks ✅
+* Bitcoin ✅
 
 <a href="https://docs.sodax.com/developers/packages/sdk/money_market" class="button secondary" data-icon="sack-dollar">Lend / Borrow (Money Market)</a>- Cross-chain lending and borrowing
 
-* EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, Lightlink) ✅
+* EVM (Sonic, Ethereum, Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, HyperEVM, Lightlink, Redbelly, Kaia) ✅
 * Sui ✅
 * Stellar ✅
-* ICON ✅
+* ICON ✅ (bnUSD only)
 * Solana ✅
 * Injective ✅
+* NEAR ✅
+* Stacks ✅
+* Bitcoin ✅ (BTC only)
 
 <a href="https://docs.sodax.com/developers/packages/sdk/bridge" class="button secondary" data-icon="bridge-suspension">Bridge</a>- Cross-chain token bridging
 
-* EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, Lightlink) ✅
+* EVM (Sonic, Ethereum, Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, HyperEVM, Lightlink, Redbelly, Kaia) ✅
 * Sui ✅
 * Stellar ✅
 * ICON ✅
 * Solana ✅
 * Injective ✅
+* NEAR ✅
+* Stacks ✅
+* Bitcoin ✅
 
 <a href="https://docs.sodax.com/developers/packages/sdk/migration" class="button secondary" data-icon="truck">Migration</a>- Token migration (ICX, bnUSD, BALN)
 
+* ICX / wICX → SODA: source chain ICON only
+* BALN → SODA: source chain ICON only
+* bnUSD: between legacy chains (ICON, Sui, Stellar) and the new bnUSD on any other supported chain
+
 <a href="https://docs.sodax.com/developers/packages/sdk/staking" class="button secondary" data-icon="seedling">Staking</a>- SODA token staking
 
-* EVM (Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, Sonic, HyperEVM, Lightlink) ✅
+* EVM (Sonic, Ethereum, Arbitrum, Avalanche, Base, BSC, Optimism, Polygon, HyperEVM, Lightlink, Redbelly, Kaia) ✅
 * Sui ✅
 * Stellar ✅
-* ICON ✅
 * Solana ✅
 * Injective ✅
+* NEAR ✅
+* Stacks ✅
 
 ### Tooling Modules inside the SDK
 
@@ -82,6 +96,76 @@ How to setup local development
 
 <a href="https://docs.sodax.com/developers/packages/sdk/intent_relay_api" class="button secondary" data-icon="envelope">Intent Relay API</a>- Relayer API endpoint documentation
 
+## AI agent docs
+
+`@sodax/sdk` ships an AI-ready documentation tree at `node_modules/@sodax/sdk/ai-exported/`. It's tool-neutral: any agent that can read files (Claude Code, Cursor, Aider, Copilot Chat, ChatGPT with file context, etc.) can use it without further setup.
+
+### Get started
+
+Point your agent at `node_modules/@sodax/sdk/ai-exported/AGENTS.md` — it routes to the rest. Three sample prompts covering the typical entry points:
+
+```
+> Read node_modules/@sodax/sdk/ai-exported/AGENTS.md and integrate
+> SODAX cross-chain swaps from Arbitrum to Stellar into my Node service.
+
+> Read node_modules/@sodax/sdk/ai-exported/AGENTS.md. My code uses
+> @sodax/sdk v1 — port my call sites to v2.
+
+> Look up the v2 SodaxError code for a relay timeout in
+> node_modules/@sodax/sdk/ai-exported/integration/reference/error-codes.md.
+```
+
+### What's inside
+
+```
+ai-exported/
+├── AGENTS.md                          # Tool-neutral entry point — start here
+├── integration/                       # Building NEW v2 code
+│   ├── README.md, ai-rules.md         # Index + DO / DO NOT / workflow for agents
+│   ├── quickstart.md                  # Install + initialize + first-run troubleshooting
+│   ├── architecture.md                # Type system + design concepts (Result, ChainKeys, …)
+│   ├── chain-specifics.md             # Non-EVM quirks (Stellar, BTC, Solana, ICON, NEAR)
+│   ├── features/                      # 7 feature pages: swap, money-market, staking, bridge,
+│   │                                  #   dex, icx-bnusd-baln, auxiliary-services
+│   ├── recipes/                       # 8 copy-pasteable patterns: init, signed-/raw-tx flow,
+│   │                                  #   error handling, narrowing, testing, gas, backend init
+│   └── reference/                     # 5 lookup tables: chain keys, wallet providers,
+│                                      #   error codes, public API surface, glossary
+└── migration/                         # Porting EXISTING v1 code to v2
+    ├── README.md, ai-rules.md         # Index + workflow for porting agents
+    ├── checklist.md                   # 17-step cross-cutting checklist
+    ├── breaking-changes/              # 3 cross-cutting changes: type-system, architecture,
+    │                                  #   result-and-errors
+    ├── features/                      # 7 per-feature porting playbooks (same names as
+    │                                  #   integration/features/)
+    ├── recipes.md                     # Codemods + error-shape and Result adapters
+    └── reference/                     # 4 reference tables: deleted exports, sodax-config
+                                       #   reshape, error-code crosswalk, return-shape diffs
+```
+
+### Scope
+
+This tree documents `@sodax/sdk` (the Core SDK) only. It assumes:
+
+- **TypeScript** — examples are TS; the SDK ships dual ESM/CJS.
+- **Runtime-agnostic** — Node.js, browsers, bundled apps. **No React or Next.js content** — the SDK is UI-framework-agnostic and the docs reflect that.
+- **`@sodax/types` is re-exported** through `@sodax/sdk`'s barrel; consumers don't add it as a separate dependency.
+
+`@sodax/wallet-sdk-core` is **mentioned** in a few places as a pointer — it's a separate SODAX package that ships ready-made `I*WalletProvider` implementations for all 9 chain families. Consumers can install it separately or implement the wallet-provider interfaces themselves. React-layer packages (`@sodax/wallet-sdk-react`, `@sodax/dapp-kit`) are **out of scope here** and may have their own `ai-exported/` trees in their respective packages.
+
+### Integrity guarantees
+
+Every release passes four CI checks against `ai-exported/`:
+
+| Guard | What it catches |
+|---|---|
+| `check:ai-exported` | Each top-level `sodax.X` reference matches a real public member of the `Sodax` class in `src/shared/entities/Sodax.ts`. (Shallow — `sodax.partners.invented` would still pass.) |
+| `check:ai-scope` | No accidental sibling-package, React, or Next.js content leaks in. |
+| `check:ai-links` | Every relative link between markdown files resolves. |
+| `check:ai-imports` | Every `import … from '@sodax/sdk'` example in the docs typechecks against the SDK source. |
+
+If you're contributing to this repo, run them with `pnpm -C packages/sdk run check:ai-exported` (or `:scope`, `:links`, `:imports`).
+
 ***
 
 ## Contributing
@@ -122,5 +206,5 @@ pnpm lint
 
 ## Support
 
-* [GitHub Issues](https://github.com/icon-project/sodax-frontend/issues)
+* [GitHub Issues](https://github.com/icon-project/sodax-sdks/issues)
 * [Discord Community](https://discord.gg/xM2Nh4S6vN)

package/ai-exported/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md — `@sodax/sdk` v2
+
+> Tool-neutral entry point for any AI coding agent assisting a consumer of `@sodax/sdk`. If you're at `node_modules/@sodax/sdk/ai-exported/AGENTS.md`, you are in the right place — everything you need is reachable from here without leaving the npm tarball.
+
+## Project
+
+`@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.
+
+## When to read what
+
+```
+Are you writing NEW code against v2?           → integration/ai-rules.md, then integration/
+Are you porting EXISTING v1 code to v2?        → migration/ai-rules.md, then migration/
+Just need a chain key / error code / type?     → integration/reference/
+Need to install + initialize the SDK?           → integration/quickstart.md
+Hit a non-EVM chain quirk (Stellar, BTC, …)?   → integration/chain-specifics.md
+```
+
+If a consumer's repo has both v1 call sites and a request to extend with new code, do migration first. Stale v1 patterns leak into new code if you skip it.
+
+**Always start with the `ai-rules.md` for the tree you're working in** — it's the consolidated DO / DO NOT / workflow / stop-conditions guide that prevents the most common v2 traps. Read it once, then dive into the per-feature docs.
+
+## Top-level layout
+
+```
+ai-exported/
+├── AGENTS.md                       # You are here
+├── integration/                    # How to use v2 (new consumers)
+│   ├── 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
+│   │   ├── README.md
+│   │   ├── swap.md
+│   │   ├── money-market.md
+│   │   ├── staking.md
+│   │   ├── bridge.md
+│   │   ├── dex.md
+│   │   ├── icx-bnusd-baln.md       # MigrationService (the SDK module, not the v1→v2 port)
+│   │   └── auxiliary-services.md   # PartnerService + RecoveryService + BackendApiService
+│   ├── 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/                      # How to port v1 → v2
+    ├── README.md                   # Overview + reading order + cross-cutting checklist + v1↔v2 glossary
+    ├── ai-rules.md                 # DO / DO NOT / workflow for porting agents
+    ├── breaking-changes/           # Cross-cutting v1→v2 changes
+    │   ├── type-system.md          # @sodax/types renames + ChainKeys + WalletProviderSlot + RpcConfig + IConfigApi Result
+    │   ├── architecture.md         # *SpokeProvider deletion + ConfigService + relay reshape + invariants
+    │   └── result-and-errors.md    # Throws → Result<T>; module errors → SodaxError<C>; v1↔v2 code crosswalk; return shapes
+    ├── features/                   # Per-feature pure-SDK migration playbooks
+    │   ├── README.md
+    │   ├── swap.md, money-market.md, staking.md, bridge.md, dex.md, icx-bnusd-baln.md, auxiliary-services.md
+    └── recipes.md                  # Codemods + error-shape adapter + result adapter
+```
+
+## v2 in one minute
+
+1. **Chain key drives everything.** Pass `srcChainKey: ChainKeys.ETHEREUM_MAINNET` (or any of 20 keys) on the request payload. The SDK routes to the correct per-chain spoke service internally and TypeScript narrows the wallet-provider parameter to the chain-specific interface via `GetWalletProviderType<K>`. There are **no** `*SpokeProvider` classes to construct.
+2. **Every async public method returns `Result<T>`.** Branch on `result.ok`. No throws across service boundaries. Sub-Result forwarding is the default: `if (!sub.ok) return sub`.
+3. **Errors are `SodaxError<C>`.** A single class with a closed 13-code reason vocabulary (`VALIDATION_FAILED`, `RELAY_TIMEOUT`, `EXECUTION_FAILED`, …) plus a `feature` field (`'swap' | 'moneyMarket' | …`). The pair `(feature, code)` is your discriminator. Use `isSodaxError(e)` (not bare `instanceof`).
+4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider: <chain-narrowed> }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
+5. **Config is dynamic.** `await sodax.config.initialize()` fetches current chain/token config from the backend, with a safe fallback to packaged defaults. Lookups go through `sodax.config.*` — there is no `hubAssets`, no `moneyMarketSupportedTokens` global map, no static registry to import.
+
+## Top 5 v1 → v2 traps
+
+1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass an object satisfying the chain-specific `I*WalletProvider` interface (e.g. `IEvmWalletProvider`) directly into the SDK call payload. Implementations come from your application — write your own to satisfy the interface, or install `@sodax/wallet-sdk-core` (a separate SODAX package, not bundled into `@sodax/sdk`) for ready-made implementations. The chain key on the payload is what routes — there is no provider class for `@sodax/sdk` consumers to instantiate.
+2. **Forgetting `raw: false`.** Without the discriminator, `walletProvider` is rejected with "Object literal may only specify known properties, and 'walletProvider' does not exist in type". Add `raw: false` for signed flows; `raw: true` for unsigned-tx building.
+3. **Importing from `@sodax/types` directly.** `@sodax/sdk` re-exports the entire `@sodax/types` surface via its barrel. Add `@sodax/sdk` as your only dependency; importing `@sodax/types` separately risks version skew.
+4. **Treating `Result<T>` as throw-on-failure.** v2 mutation methods do **not** throw on SDK-level failure — they resolve `{ ok: false, error }`. A `try { await sodax.<method>(...) } catch` only catches *exceptions* from inside `mutationFn` (e.g. missing `walletProvider`); it will **not** catch `RELAY_TIMEOUT` or `EXECUTION_FAILED`. Branch on `.ok`.
+5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** Renamed: `XToken.chainKey` and `ChainKeys.*`. v1 numeric/string chain-id constants are gone. `ChainKeys.ICON_MAINNET` is `'0x1.icon'` (a string), not the legacy numeric ID — `Number(chainKey)` returns `NaN`.
+
+See `migration/README.md` for the complete trap list and `migration/breaking-changes/` for full v1↔v2 detail.
+
+## Public API contract
+
+- Import only from the package root: `import { Sodax, ChainKeys, type SpokeChainKey } from '@sodax/sdk'`.
+- Do **not** add `@sodax/types` to your dependencies — `@sodax/sdk` re-exports the full types surface (`export * from '@sodax/types'` from the barrel). Importing `@sodax/types` separately is unsupported and may silently version-skew.
+- Do **not** deep-import from `dist/...`. Internal paths are not stable across releases. Anything intended for consumer use is exported from the root.
+- The published tarball ships `dist/` and `ai-exported/`. Do not rely on any other path being present.
+
+## Conventions agents must follow
+
+- **`Result<T>` discrimination on `.ok`.** Always branch on `result.ok` before reading `.value` or `.error`. Forward sub-Results without re-wrapping (`if (!sub.ok) return sub`).
+- **`(feature, code)` for error switching.** Use `isSodaxError(e)`, then `e.feature` and `e.code` for routing logic. Don't string-match on `e.message`.
+- **`ChainKeys.*` over hard-coded strings.** Use `ChainKeys.ETHEREUM_MAINNET`, not `'eth'` / `'0xa86a.fuji'`. The set of supported chains evolves per release.
+- **No `as unknown as <Type>` double-casts.** v2 type narrowing makes them unnecessary in 99% of cases — chain-key generic flow + `GetWalletProviderType<K>` resolves to the exact interface. If a cast feels needed, look for the chain-key narrowing pattern in `integration/recipes/` first.
+- **Conventional commits if generating commits** in the consumer repo (`feat:`, `fix:`, `chore:`). Many SODAX-adjacent repos enforce this via commitlint.
+- **Don't generate `try { await sodax.<method>(...) } catch` for SDK-level failures.** That catch never fires for `Result` `!ok`. Branch on `result.ok`.
+
+## Pointers
+
+- `integration/README.md` — start here for any new v2 work.
+- `migration/README.md` — start here for any v1 → v2 port.
+- `integration/quickstart.md` — install, initialize, first-run troubleshooting.
+- `integration/reference/` — chain key table, error code table, public API surface, glossary.

package/ai-exported/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/ai-exported/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.