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

package/ai-exported/migration/checklist.md

@@ -0,0 +1,61 @@
+# v1 → v2 cross-cutting migration checklist
+
+Work this top-down. Each step is independent enough to land as its own commit; the order minimizes typecheck noise.
+
+```
+[ ] 1.  Replace every *_MAINNET_CHAIN_ID constant with ChainKeys.* (mechanical).
+        See breaking-changes/type-system.md § "Chain IDs".
+[ ] 2.  Replace every SpokeChainId / ChainId type alias with SpokeChainKey.
+        Mechanical rename. Same value union.
+[ ] 3.  Rename XToken.xChainId → XToken.chainKey. Same for any consumer types
+        that mirrored that field.
+[ ] 4.  Remove any direct dependency on @sodax/types from package.json.
+        v2 @sodax/sdk barrel re-exports the entire types surface.
+[ ] 5.  Delete every *SpokeProvider class instantiation. Replace with passing
+        walletProvider (an I*WalletProvider instance) directly into SDK call
+        payloads.
+[ ] 6.  Replace every isXxxSpokeProvider(provider) guard with a chain-key
+        compare: chainKey === ChainKeys.<X>_MAINNET, or use
+        is<Family>ChainKeyType(chainKey) from @sodax/sdk.
+[ ] 7.  Add { raw: false } discriminator to every signed call shape that
+        previously took a positional spoke provider:
+            { intentParams, spokeProvider }   →   { params, raw: false, walletProvider }
+[ ] 8.  Add srcChainKey + srcAddress to every action params object that didn't
+        carry them in v1 (most MM, staking, dex, bridge, migration param shapes).
+[ ] 9.  Convert every await sodax.<service>.<method>(...) call site that previously
+        threw to branch on result.ok / result.error. Use isSodaxError(e) for type
+        narrowing.
+[ ] 10. Delete imports of MoneyMarketError, IntentError, StakingError, BridgeError,
+        MigrationError, AssetServiceError, ConcentratedLiquidityError, RelayError,
+        plus the five Partner error types and their type-guard helpers.
+[ ] 11. Replace any walked global lookup (hubAssets[chainId][address],
+        moneyMarketSupportedTokens[chainId], SodaTokens[...]) with the equivalent
+        sodax.config.* / sodax.moneyMarket.getSupportedTokens*() calls.
+[ ] 12. Initialize ConfigService at app startup: await sodax.config.initialize().
+        Falls back to packaged defaults if the backend is unreachable.
+[ ] 13. Add { raw: true } to any read-only allowance check that previously took
+        a spoke provider but didn't actually consult it (the underlying SDK
+        method now requires WalletProviderSlot).
+[ ] 14. For every CreateIntentResult consumer: stop destructuring as a tuple;
+        the v2 shape is { tx, intent, relayData }. Stop destructuring tx-pair
+        results as arrays — every cross-chain mutation returns
+        TxHashPair = { srcChainTxHash, dstChainTxHash }.
+[ ] 15. For every backend-API call site: every method on IConfigApi now returns
+        Promise<Result<T>>. Wrap or unwrap accordingly.
+[ ] 16. (Optional) Adopt isSodaxError(e) over instanceof SodaxError in cross-bundle
+        / cross-realm contexts.
+[ ] 17. Run pnpm tsc --noEmit and start crossing items off the typecheck output.
+        Use each remaining error category to navigate to the relevant per-feature
+        migration file in features/.
+```
+
+After items 1–17 land, the typecheck should be clean. The remaining work is per-feature behavior (cross-chain borrow / repay deltas, staking action discriminators, etc.) covered in [`features/`](features/).
+
+## Reading order while working the checklist
+
+- Items 1–4: [`breaking-changes/type-system.md`](breaking-changes/type-system.md).
+- Items 5–6, 11–12: [`breaking-changes/architecture.md`](breaking-changes/architecture.md).
+- Items 7–8, 13: [`breaking-changes/architecture.md`](breaking-changes/architecture.md) § "WalletProviderSlot" + per-feature files.
+- Items 9–10, 14, 16: [`breaking-changes/result-and-errors.md`](breaking-changes/result-and-errors.md).
+- Item 15: [`features/auxiliary-services.md`](features/auxiliary-services.md) § "BackendApiService".
+- Item 17 + the long tail: [`features/`](features/), one per feature you use.

package/ai-exported/migration/features/README.md

@@ -0,0 +1,35 @@
+# Per-feature migration playbooks — v1 → v2
+
+One file per feature, paired with the v2 design counterpart in [`../../integration/features/`](../../integration/features/) (same filename).
+
+| Feature | Migration file |
+|---|---|
+| Swap | [`swap.md`](swap.md) |
+| Money Market | [`money-market.md`](money-market.md) |
+| Staking | [`staking.md`](staking.md) |
+| Bridge | [`bridge.md`](bridge.md) |
+| DEX | [`dex.md`](dex.md) |
+| ICX/bnUSD/BALN | [`icx-bnusd-baln.md`](icx-bnusd-baln.md) |
+| Auxiliary services | [`auxiliary-services.md`](auxiliary-services.md) — `PartnerService` + `RecoveryService` + `BackendApiService`. The backend-API one is the load-bearing change: every method now returns `Promise<Result<T>>`. |
+
+## Reading order within a feature
+
+Each per-feature file follows the same shape:
+
+1. **TL;DR** — the load-bearing changes in 5–10 bullets.
+2. **Type / symbol cheat sheet** — exact renames and shape diffs.
+3. **Per-method delta** — call shape v1 vs v2, return type v1 vs v2, error model v1 vs v2.
+4. **Worked example** — a representative migration of one call site, before / after.
+5. **Pitfalls** — the things that look right but compile or run wrong.
+6. **Verification** — what to run to confirm the port is complete.
+
+## Cross-cutting prerequisites
+
+Before reading any feature file, finish the cross-cutting work in:
+
+- [`../README.md`](../README.md) — top-level checklist (chain-id rename, type renames, `walletProvider` extraction).
+- [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) — type imports must compile first.
+- [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`.
+- [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md) — `Result<T>` and `SodaxError<C>`.
+
+Per-feature work assumes those are done.

package/ai-exported/migration/features/auxiliary-services.md

@@ -0,0 +1,156 @@
+# Auxiliary services migration — v1 → v2
+
+Pure-SDK migration playbook for `PartnerService`, `RecoveryService`, and `BackendApiService`. Three small services grouped because each has a small surface area.
+
+Pair: [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
+
+## TL;DR
+
+1. **`PartnerService`:** standard pattern. Drop `spokeProvider`; pass `walletProvider`. Add `srcChainKey` + `srcAddress` to claim params. v1's 5 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`.
+2. **`RecoveryService`:** **new in v2.** No v1 equivalent — there's no migration to do for code that didn't exist before. Just integration: see [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
+3. **`BackendApiService`:** the load-bearing change. **Every method now returns `Promise<Result<T>>`** (v1 returned plain `Promise<T>` and threw on failure). `IConfigApi` implementations must update method signatures.
+4. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field is `string` (`relayData.payload`), not the `RelayExtraData` object. (Cross-cutting detail; covered in detail in [`swap.md`](swap.md).)
+
+## `PartnerService`
+
+### Type / symbol cheat sheet
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| Partner action params | non-generic | now generic `<K>` with `srcChainKey`, `srcAddress` | |
+| Partner errors (5 types) | `PartnerFeeClaimError<...>` and 4 siblings | `SodaxError<C>` with `feature: 'partner'` | All 5 v1 typed errors collapse. |
+
+### v1 → v2 error code crosswalk
+
+All 5 v1 partner error codes map to `EXECUTION_FAILED` with `error.context.action` discriminating between the operations.
+
+### Per-method delta
+
+Partner operations live on `sodax.partners.feeClaim` (a `PartnerFeeClaimService`), not directly on `sodax.partners`. v1 method names also changed:
+
+```diff
+- await sodax.partners.claimFees({ /* … */ }, spokeProvider);
++ // Approve once, then configure auto-swap preference, then run swaps.
++ // Full method list lives in integration/features/auxiliary-services.md.
++ const approved = await sodax.partners.feeClaim.isTokenApproved({ token, srcAddress });
++ if (approved.ok && !approved.value) {
++   await sodax.partners.feeClaim.approveToken({
++     params: { token, amount },
++     raw: false,
++     walletProvider,
++   });
++ }
+```
+
+### Pitfalls
+
+1. **Partner methods moved.** They live on `sodax.partners.feeClaim`, not `sodax.partners` directly. The parent only exposes `feeClaim` and `config` as public fields.
+2. **All 5 v1 partner errors collapse to `feature: 'partner'`.** Even though they share the `EXECUTION_FAILED` code with every other feature.
+
+---
+
+## `RecoveryService`
+
+**No v1 equivalent.** v1 didn't have a public recovery service. Failed cross-chain operations had to be handled ad-hoc.
+
+If you have v1 code that worked around this (e.g. manually walked the hub wallet abstraction to find stuck assets), replace it with `fetchHubAssetBalances` + `withdrawHubAsset`:
+
+```ts
+const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
+if (balances.ok && balances.value.length > 0) {
+  await sodax.recovery.withdrawHubAsset({
+    params: { /* hub-asset address, amount, destination spoke chain + address */ },
+    raw: false,
+    walletProvider: sonicWp,
+  });
+}
+```
+
+See [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md) § "RecoveryService".
+
+---
+
+## `BackendApiService`
+
+The load-bearing v1 → v2 change here is **`Result`-wrapping every method**.
+
+### Type / symbol cheat sheet
+
+| Method | v1 return | v2 return |
+|---|---|---|
+| `submitSwapTx` | `Promise<SubmitSwapTxResponse>` | `Promise<Result<SubmitSwapTxResponse>>` |
+| `getIntentByHash` | `Promise<IntentResponse>` | `Promise<Result<IntentResponse>>` |
+| `getIntentByTxHash` | (n/a in v1) | `Promise<Result<IntentResponse>>` (v2-new) |
+| `getOrderbook` (was `getSolverOrderbook`) | `Promise<OrderbookEntry[]>` | `Promise<Result<OrderbookEntry[]>>` |
+| `getUserIntents` (was `getUserSwapHistory`) | `Promise<IntentResponse[]>` | `Promise<Result<IntentResponse[]>>` |
+| `getChains` | `Promise<ChainConfig[]>` | `Promise<Result<GetChainsApiResponse>>` |
+| `getSwapTokens` | `Promise<SwapTokenConfig>` | `Promise<Result<GetSwapTokensApiResponse>>` |
+| `getSwapTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
+| `getMoneyMarketTokens` | `Promise<MMTokenConfig>` | `Promise<Result<GetMoneyMarketTokensApiResponse>>` |
+| `getMoneyMarketTokensByChainId` | `Promise<XToken[]>` | `Promise<Result<XToken[]>>` |
+| `SubmitSwapTxRequest.srcChainId` | numeric chain id | renamed → `srcChainKey: SpokeChainKey` |
+| `SubmitSwapTxRequest.relayData` | `RelayExtraData` object | now `string` (use `relayData.payload`) |
+
+### Per-method delta
+
+```diff
+- const response: SubmitSwapTxResponse = await sodax.backendApi.submitSwapTx(request);
+- // throws on failure
++ const result = await sodax.backendApi.submitSwapTx({
++   txHash: spokeTxHash as string,
++   srcChainKey: src.chain,                  // was: srcChainId
++   walletAddress: '0x…',
++   intent: swapIntentData,
++   relayData: relayData.payload,            // was: relayData (object)
++ });
++ if (!result.ok) {
++   // result.error: SodaxError with feature: 'swap', context.api: 'backend'
++   return;
++ }
++ const response = result.value;
+```
+
+### Custom `IConfigApi` (sandbox / test fixtures)
+
+If you implemented `IConfigApi` for a sandbox or test fixture:
+
+```diff
+  const sandboxApi: IConfigApi = {
+-   async getChains(): Promise<ChainConfig[]> {
+-     return [/* fixture */];
+-   },
+-   async getSwapTokens(): Promise<SwapTokenConfig> { /* … */ },
++   async getChains(): Promise<Result<ChainConfig[], unknown>> {
++     return { ok: true, value: [/* fixture */] };
++   },
++   async getSwapTokens(): Promise<Result<SwapTokenConfig, unknown>> { /* … */ },
+    // …5 methods total
+  };
+```
+
+Every method on the contract returns `Promise<Result<T>>` in v2.
+
+### Pitfalls
+
+1. **`SubmitSwapTxRequest.relayData` is `string`, not the `RelayExtraData` object.** v1 took the object; v2 takes the `payload` field as a string.
+2. **Backend errors carry `error.context.api === 'backend'`** but the `feature` reflects the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related backend calls, etc.). Use both for logger tag pairs.
+3. **Custom `IConfigApi` implementations must return `Result<T>`** — old throw-on-error implementations will compile-error against the v2 interface.
+
+---
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scans:
+grep -rE "spokeProvider:\s*\w+|isPartnerError\b|PartnerFeeClaimError\b" src/
+grep -rE "srcChainId:\s*\w+|\.relayData(?!\s*\.payload)" src/   # legacy field name + non-string relayData
+```
+
+## Cross-references
+
+- v2 auxiliary services usage: [`../../integration/features/auxiliary-services.md`](../../integration/features/auxiliary-services.md).
+- `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) (the swap migration covers the request-shape changes in detail).
+- Result/error model: [`../breaking-changes/result-and-errors.md`](../breaking-changes/result-and-errors.md).
+- `IConfigApi` Result-wrapping cross-cutting note: [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 6.

package/ai-exported/migration/features/bridge.md

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

package/ai-exported/migration/features/dex.md

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