@sodax/skills 2.0.0-rc.10

package/skills/sodax-sdk/integration/knowledge/chain-specifics.md

@@ -0,0 +1,189 @@
+# Chain specifics — Non-EVM quirks
+
+EVM chains (12 of them) work uniformly through `IEvmWalletProvider`. Non-EVM chains have particularities you need to handle. This file documents each chain family's quirks.
+
+## Section index
+
+1. [Stellar trustline](#1-stellar-trustline) — `STELLAR_MAINNET`. Required before receiving any non-XLM asset.
+2. [Bitcoin PSBT and Radfi](#2-bitcoin-psbt-and-radfi) — `BITCOIN_MAINNET`. PSBT signing; trading wallet; Radfi auth/session.
+3. [Solana PDA derivation](#3-solana-pda-derivation) — `SOLANA_MAINNET`. Deterministic addresses; one-time setup utilities.
+4. [ICON Hana wallet](#4-icon-hana-wallet) — `ICON_MAINNET`. Low-level Hana-extension helpers; chain key string vs numeric ID.
+5. [NEAR connector discovery](#5-near-connector-discovery) — `NEAR_MAINNET`. Account-id semantics; multiple wallet variants.
+
+---
+
+## 1. Stellar trustline
+
+**Requirement:** before a Stellar account can hold or receive a non-XLM asset, it must establish a trustline to the asset issuer. SODAX's bridge / swap / money-market deliver stablecoin assets to Stellar — the destination Stellar account must have an active trustline for the asset, or the operation fails.
+
+### How v2 handles it
+
+`BridgeService` and other feature services delegate Stellar trustline / allowance handling to the Stellar spoke service internally — there is **no** public `checkStellarTrustline` / `requestStellarTrustline` method on `BridgeService`. When you call `sodax.bridge.approve({ params, raw: false, walletProvider })` with a Stellar `walletProvider`, the spoke service handles the trustline operation for you.
+
+For direct trustline interaction outside the standard `approve` flow, reach for the Stellar spoke service:
+
+```ts
+import { ChainKeys, type StellarSpokeService } from '@sodax/sdk';
+
+const stellarSpoke = sodax.spoke.getSpokeService(ChainKeys.STELLAR_MAINNET) as StellarSpokeService;
+// Use the spoke service's typed methods for Stellar-specific operations.
+```
+
+### When to gate
+
+Before any swap / bridge / money-market operation that **delivers** a non-XLM asset to a Stellar destination, the destination wallet must already trust the asset. Failed trustline checks surface as `VALIDATION_FAILED` errors; use `error.context.reason` to disambiguate. The standard pattern for app code is to call `sodax.bridge.approve(...)` (or the matching feature's approve) on the Stellar wallet first, which establishes the trustline as a side effect.
+
+### Pitfall
+
+Stellar accounts that have never held the asset have **no** trustline — receiving will fail. The error surfaces as `VALIDATION_FAILED` with `context.reason: 'trustlineMissing'` (or similar). Treat the missing-trustline state as a one-time setup step gated by the standard `approve` flow.
+
+---
+
+## 2. Bitcoin PSBT and Radfi
+
+Bitcoin support uses Partially Signed Bitcoin Transactions (PSBT) — a different model than EVM tx signing. The wallet provider (`BTCWalletProvider`) handles PSBT construction and signing internally.
+
+### Address types
+
+```ts
+type BtcAddressType = 'P2PKH' | 'P2SH' | 'P2WPKH' | 'P2TR';
+```
+
+`BTCWalletProvider` config takes an `addressType`. `'P2WPKH'` (native SegWit) is the modern default; `'P2TR'` (Taproot) is supported but may have lower compatibility with some on-chain logic.
+
+### Radfi (auth + trading wallet)
+
+SODAX uses the Radfi infrastructure for Bitcoin. Each user gets a derived "trading wallet" funded from their main BTC address. Operations consume UTXOs from the trading wallet rather than directly from the user's main address.
+
+The Radfi provider is owned by `BitcoinSpokeService`. Reach it via the spoke router:
+
+```ts
+import { ChainKeys, type BitcoinSpokeService } from '@sodax/sdk';
+
+const btcSpoke = sodax.spoke.getSpokeService(ChainKeys.BITCOIN_MAINNET) as BitcoinSpokeService;
+const radfi = btcSpoke.radfi;   // RadfiProvider instance
+```
+
+Most consumer flows don't need to touch `radfi` directly — `sodax.bridge.bridge(...)`, `sodax.swaps.createIntent(...)`, etc. handle the Radfi auth + trading-wallet routing internally on the Bitcoin path. For explicit lifecycle management:
+
+```ts
+// Authenticate against Radfi (the wallet signs an auth message):
+await radfi.authenticateWithWallet(/* args per RadfiProvider source */);
+
+// Fetch the trading wallet for an address (creating it if needed):
+const tradingWallet = await radfi.getTradingWallet(personalAddress);
+
+// Read the trading wallet's BTC + token balances:
+const balance = await radfi.getBalance(tradingWallet.address);
+
+// Check whether a trading wallet exists without provisioning one:
+const exists = await radfi.checkIfTradingWalletExists(personalAddress);
+```
+
+Other public methods on `RadfiProvider` you may need: `setRadfiAccessToken`, `refreshAccessToken`, `createTradingWallet`, `createWithdrawTransaction`, `requestRadfiSignature`, `getExpiredUtxos`, `buildRenewUtxoTransaction`, `signAndBroadcastRenewUtxo`, `withdrawToUser`, `signAndBroadcastWithdraw`, `getMaxWithdrawable`. Read `RadfiProvider` source for argument shapes — the API surface is broader than typical chain providers.
+
+### Pitfall
+
+`BitcoinSpokeService.radfi` is what feature services use under the hood. Bypassing the feature services and driving Radfi yourself works but is rarely needed — and you have to wire token balances + UTXO state manually. Prefer the standard feature flows unless you specifically need lifecycle control.
+
+---
+
+## 3. Solana PDA derivation
+
+Program Derived Addresses (PDAs) are deterministic Solana addresses derived from a program ID + seeds. SODAX uses PDAs for the user's spoke-side state on Solana.
+
+The SDK derives PDAs internally — consumers don't usually need to do this manually. For advanced use cases (preflight, off-chain state lookups), reach into the Solana spoke service via the router:
+
+```ts
+import { ChainKeys, type SolanaSpokeService } from '@sodax/sdk';
+
+const solanaSpoke = sodax.spoke.getSpokeService(ChainKeys.SOLANA_MAINNET) as SolanaSpokeService;
+// Use the spoke service's typed methods for any PDA-related read or write.
+```
+
+### `SolanaSpokeService` specifics
+
+- Solana txs are different shape from EVM (multiple instructions per tx; signed once globally).
+- `TxReturnType<typeof ChainKeys.SOLANA_MAINNET, false>` is the base58-encoded signature string (not `0x…`).
+- `SolanaRawTransaction` is the raw-tx return for `raw: true` — base64-encoded message for downstream signing.
+
+### Pitfall
+
+Solana addresses are base58 PublicKey strings, not `0x…` hex. `GetAddressType<typeof ChainKeys.SOLANA_MAINNET>` resolves to a base58-typed string brand; passing a hex address is a TypeScript error.
+
+---
+
+## 4. ICON Hana wallet
+
+ICON uses the Hana browser-extension wallet for dApp signing. The SDK ships low-level helper functions (file: `HanaWalletConnector.ts`) that wrap the Hana extension's JSON-RPC interface; consumers compose them into an `IIconWalletProvider` implementation.
+
+```ts
+import { requestAddress, requestSigning, requestJsonRpc } from '@sodax/sdk';
+
+const result = await requestAddress();   // returns Result<IconAddress>
+if (result.ok) {
+  const address = result.value;          // 'hx…'
+}
+```
+
+ICON spoke calls require an `IIconWalletProvider`. Implementations either compose the helper functions above into a class your app owns, or use the reference implementation that ships in `@sodax/wallet-sdk-core` (separate package, install separately).
+
+### `ChainKeys.ICON_MAINNET` is a string `'0x1.icon'`
+
+The ICON chain key is the **string** `'0x1.icon'`, not the legacy numeric chain id `0x1`. This trips up code that did `Number(chainId)` to coerce — that returns `NaN` for `'0x1.icon'`.
+
+```ts
+ChainKeys.ICON_MAINNET === '0x1.icon';            // true
+Number(ChainKeys.ICON_MAINNET);                   // NaN
+chainKey === ChainKeys.ICON_MAINNET;              // works
+```
+
+### Address types
+
+- `hx…` — externally-owned account (user wallet).
+- `cx…` — contract account.
+
+`GetAddressType<typeof ChainKeys.ICON_MAINNET>` accepts both via a string brand.
+
+### Injective (similar pattern)
+
+Injective is a separate chain family but uses a similar wallet-extension model. Wallet helper: `Injective20Token` (in `@sodax/sdk`'s injective utilities). `IInjectiveWalletProvider` implementations can use Keplr, Leap, or other Cosmos-ecosystem wallets.
+
+---
+
+## 5. NEAR connector discovery
+
+NEAR has multiple wallet variants (NEAR Wallet, MyNearWallet, Meteor, Sender, …). NEAR spoke calls require an `INearWalletProvider`. The interface is exported from `@sodax/sdk`; consumers supply an object satisfying it. A reference implementation ships in `@sodax/wallet-sdk-core` (separate package — install separately); browser-side connector discovery for the multiple NEAR wallet variants happens there, not in `@sodax/sdk` itself.
+
+### Account ID semantics
+
+NEAR addresses come in two forms:
+
+- **Named accounts** — `alice.near`, `mybiz.near`. Human-readable.
+- **Implicit accounts** — 64-character hex strings.
+
+Both are valid. `GetAddressType<typeof ChainKeys.NEAR_MAINNET>` accepts both via a string type.
+
+### Pitfall
+
+`NearWalletProvider` requires the `accountId` field at construction (alongside `privateKey`). Unlike EVM, NEAR can't derive an account from a key alone — keys are scoped to accounts.
+
+---
+
+## Other non-EVM chains
+
+| Chain | Notes |
+|---|---|
+| **Sui** (`SUI_MAINNET`) | Address: 32-byte `0x…` (different from EVM addresses despite the prefix). Wallet provider `ISuiWalletProvider` uses `@mysten/sui` under the hood. |
+| **Stacks** (`STACKS_MAINNET`) | Address: `SP…` (mainnet) / `ST…` (testnet). Uses `@stacks/transactions` for tx construction. |
+| **Injective** (`INJECTIVE_MAINNET`) | Cosmos-ecosystem chain. Address: `inj1…`. Wallet provider uses `@injectivelabs/sdk-ts`. |
+
+Each has its own `I*WalletProvider` interface with chain-specific signing methods. The `chainType` discriminant on every `I*WalletProvider` instance lets you narrow at runtime without `instanceof`.
+
+---
+
+## Cross-references
+
+- `WalletProviderSlot` and chain narrowing: [`architecture.md`](architecture.md) §§ 5, 6.
+- Per-chain wallet provider interfaces: [`reference/`](reference/) § 2.
+- Cast-at-boundary pattern for chain-narrowed providers: [`recipes/`](recipes/) § 5.

package/skills/sodax-sdk/integration/knowledge/features/README.md

@@ -0,0 +1,21 @@
+# Features — `@sodax/sdk` v2
+
+One file per feature service. Each file documents the v2 API surface, common call shapes, return types, and error codes you can expect.
+
+| Feature | Service class | What it does |
+|---|---|---|
+| [`swap.md`](swap.md) | `SwapService` | Intent-based swaps via the solver. Market and limit orders. Cross-chain by default. |
+| [`money-market.md`](money-market.md) | `MoneyMarketService` | Cross-chain lending/borrowing. Supply, borrow, withdraw, repay. Reserves and user-position reads. |
+| [`staking.md`](staking.md) | `StakingService` | SODA → xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel. |
+| [`bridge.md`](bridge.md) | `BridgeService` | Cross-chain token transfer via vault. `bridge` returns `TxHashPair = { srcChainTxHash, dstChainTxHash }`. Bridgeable-amount queries respect vault deposit limits. |
+| [`dex.md`](dex.md) | `ClService` + `AssetService` | Uniswap-V3-style concentrated liquidity positions. Asset deposit/withdraw. Increase/decrease/claim flows. |
+| [`migration.md`](migration.md) | `MigrationService` (the SDK module — not v1→v2 porting) | Legacy ICON ecosystem token migration. ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA with lockup multipliers. |
+| [`partner.md`](partner.md) | `PartnerService` | Partner-fee handling: token approval, auto-swap preferences, fee-claim flows. |
+| [`recovery.md`](recovery.md) | `RecoveryService` | Withdraw stuck hub-wallet assets back to a spoke chain. |
+| [`backend-api.md`](backend-api.md) | `BackendApiService` | HTTP client for backend services: swap-tx submission, intent / orderbook lookups, money-market reads. |
+
+All feature services are constructed and wired by the `Sodax` facade. You don't instantiate them directly — access them via `sodax.swaps`, `sodax.moneyMarket`, etc. See [`../architecture.md`](../architecture.md) for the service graph.
+
+## Cross-references to migration
+
+For the v1 → v2 port playbook on each feature, see the matching file in [`features/`](../../../migration-v1-to-v2/knowledge/features/) — same filename, different angle.

package/skills/sodax-sdk/integration/knowledge/features/backend-api.md

@@ -0,0 +1,81 @@
+# Backend API — `BackendApiService`
+
+HTTP client for backend services. Provides intent lookup, swap-tx submission, solver orderbook queries, money-market position/reserve reads, and (internally) config fetching. Most consumer-side code uses just `submitSwapTx`, `getIntentByHash` / `getIntentByTxHash`, and the money-market read methods.
+
+Access: `sodax.backendApi`. Service class: `BackendApiService`. **Feature tag for errors:** appears under multiple features depending on the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related reads, etc.); errors carry `error.context.api: 'backend'`.
+
+## Methods
+
+```ts
+// Swap-related
+sodax.backendApi.submitSwapTx(request, config?): Promise<Result<SubmitSwapTxResponse>>;
+sodax.backendApi.getSubmitSwapTxStatus(...): Promise<Result<...>>;
+sodax.backendApi.getOrderbook(...): Promise<Result<OrderbookEntry[]>>;
+sodax.backendApi.getIntentByHash(intentHash, config?): Promise<Result<IntentResponse>>;
+sodax.backendApi.getIntentByTxHash(txHash, config?): Promise<Result<IntentResponse>>;
+sodax.backendApi.getUserIntents(...): Promise<Result<IntentResponse[]>>;
+
+// Money-market reads (these are the canonical reads for MM positions/reserves;
+// MoneyMarketService does NOT expose getReservesData / getUserReservesData / etc.)
+sodax.backendApi.getMoneyMarketPosition(...): Promise<Result<...>>;
+sodax.backendApi.getAllMoneyMarketAssets(config?): Promise<Result<MoneyMarketAsset[]>>;
+sodax.backendApi.getMoneyMarketAsset(reserveAddress, config?): Promise<Result<MoneyMarketAsset>>;
+sodax.backendApi.getMoneyMarketAssetBorrowers(...): Promise<Result<...>>;
+sodax.backendApi.getMoneyMarketAssetSuppliers(...): Promise<Result<...>>;
+sodax.backendApi.getAllMoneyMarketBorrowers(...): Promise<Result<...>>;
+
+// Config-API methods (used internally by ConfigService — implements `IConfigApi`)
+sodax.backendApi.getAllConfig(config?): Promise<Result<GetAllConfigApiResponse>>;
+sodax.backendApi.getChains(config?): Promise<Result<GetChainsApiResponse>>;
+sodax.backendApi.getSwapTokens(config?): Promise<Result<GetSwapTokensApiResponse>>;
+sodax.backendApi.getSwapTokensByChainId(...): Promise<Result<XToken[]>>;
+sodax.backendApi.getMoneyMarketTokens(config?): Promise<Result<GetMoneyMarketTokensApiResponse>>;
+sodax.backendApi.getMoneyMarketReserveAssets(...): Promise<Result<...>>;
+sodax.backendApi.getMoneyMarketTokensByChainId(...): Promise<Result<XToken[]>>;
+sodax.backendApi.getRelayChainIdMap(config?): Promise<Result<GetRelayChainIdMapApiResponse>>;
+```
+
+All methods return `Result<T, SodaxError>` where the error carries `feature: 'swap' | 'moneyMarket' | …` (depending on call site) and `error.context.api === 'backend'`.
+
+## Common call shape — `submitSwapTx`
+
+After `sodax.swaps.createIntent({ params, raw: false, walletProvider })` returns:
+
+```ts
+const submitResult = await sodax.backendApi.submitSwapTx({
+  txHash: spokeTxHash as string,
+  srcChainKey: src.chain,
+  walletAddress: '0x…',
+  intent: swapIntentData,
+  relayData: relayData.payload,    // string, not the RelayExtraData object
+});
+
+if (!submitResult.ok) return;
+```
+
+## Custom backend (sandbox / fixtures)
+
+`SodaxConfig` does not expose a typed slot to inject a custom `IConfigApi` implementation at construction. Two supported patterns:
+
+1. **Point at a local mock backend** via `SodaxConfig.api.baseURL`:
+
+   ```ts
+   const sodax = new Sodax({
+     api: { baseURL: 'http://localhost:4000' },
+   });
+   await sodax.config.initialize();
+   ```
+
+   `SodaxConfig.api` is `ApiConfig` (`{ baseURL, timeout, headers }`) — pass any subset via `DeepPartial`.
+
+2. **Inject your own `BackendApiService`-compatible mock at the app layer** (dependency-injected where you control the `Sodax` instance), rather than via the constructor.
+
+The `IConfigApi` interface itself still matters for both patterns — every method returns `Promise<Result<T>>` in v2, so any mock or local server must conform. See [`../architecture.md`](../architecture.md) § 4 "Custom backend" for the authoritative reference.
+
+## Cross-references
+
+- v1 → v2 migration of `BackendApiService` (the load-bearing change: every method now returns `Promise<Result<T>>`): [`features/backend-api.md`](../../../migration-v1-to-v2/knowledge/features/backend-api.md).
+- The full `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) § "Backend submit-tx flow".
+- Partner-fee handling (separate service): [`./partner.md`](partner.md).
+- Stuck-asset recovery (separate service): [`./recovery.md`](recovery.md).
+- Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.

package/skills/sodax-sdk/integration/knowledge/features/bridge.md

@@ -0,0 +1,172 @@
+# Bridge — `BridgeService`
+
+Cross-chain token transfer via the hub-and-spoke vault architecture. Tokens are bridgeable if they share the same hub-side vault. The flow: spoke deposit → relay to hub → vault balance moves → spoke withdrawal on the destination chain.
+
+Access: `sodax.bridge`. Service class: `BridgeService`. Feature tag for errors: `'bridge'`.
+
+## How it works
+
+A bridge call deposits the source token into its vault on the hub, then triggers a withdrawal of the same vault's destination-chain wrapper. Different tokens that share the same vault (e.g. multiple wrappings of the same underlying) are bridgeable to each other; tokens with different vaults are not.
+
+`bridge()` handles the full lifecycle in one call. For custom relay control, use `createBridgeIntent()` (spoke-only) and call the relay layer manually.
+
+## Public methods
+
+```ts
+sodax.bridge.bridge<K>(action: BridgeAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
+sodax.bridge.createBridgeIntent<K, Raw>(action): Promise<Result<CreateBridgeIntentResult<K, Raw>, SodaxError>>;
+sodax.bridge.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+sodax.bridge.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
+
+sodax.bridge.getBridgeableAmount(from: XToken, to: XToken): Promise<Result<BridgeLimit, SodaxError>>;
+sodax.bridge.getBridgeableTokens(from: SpokeChainKey, to: SpokeChainKey, token: string): Result<XToken[], SodaxError>;
+// Plus the sync helper:
+sodax.bridge.isBridgeable({ from: XToken, to: XToken }): boolean;
+sodax.bridge.getFee(inputAmount: bigint): bigint;
+```
+
+## Action params shape
+
+```ts
+type CreateBridgeParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  srcAsset: `0x${string}`;       // source token address (spoke chain)
+  amount: bigint;
+  dstChainKey: SpokeChainKey;
+  dstAddress: string;            // destination wallet (chain-specific format)
+  dstAsset: `0x${string}`;       // destination token address (must share vault with srcAsset)
+};
+```
+
+## Common call shapes
+
+### Full bridge (recommended for most flows)
+
+```ts
+const result = await sodax.bridge.bridge({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    srcAsset: USDC_ARBITRUM.address,
+    amount: parseUnits('100', 6),
+    dstChainKey: ChainKeys.STELLAR_MAINNET,
+    dstAddress: 'G…',
+    dstAsset: USDC_STELLAR.address,
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### Create-intent (custom relay control)
+
+```ts
+const result = await sodax.bridge.createBridgeIntent({
+  params: { /* same as above */ },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+if (!result.ok) return;
+const { tx, intent, relayData } = result.value;
+// Submit relayData.payload via your own relay infrastructure if needed.
+```
+
+### Hub as source (Sonic → spoke)
+
+`srcChainKey` accepts `ChainKeys.SONIC_MAINNET` too — the SDK routes through the user's hub-wallet abstraction (instead of a spoke deposit) and then triggers the destination withdrawal. The call shape is the same; only the chain key changes:
+
+```ts
+const sodaSonic = sodax.config.findSupportedTokenBySymbol(ChainKeys.SONIC_MAINNET, 'SODA');
+const sodaBase  = sodax.config.findSupportedTokenBySymbol(ChainKeys.BASE_MAINNET,  'SODA');
+if (!sodaSonic || !sodaBase) throw new Error('SODA missing from config');
+
+// 1. Confirm the pair is vault-bridgeable (synchronous, config-derived).
+if (!sodax.bridge.isBridgeable({ from: sodaSonic, to: sodaBase })) {
+  // Fall back to swap if needed — different vaults aren't bridgeable.
+  return;
+}
+
+// 2. (Optional) check the vault-side cap.
+const limit = await sodax.bridge.getBridgeableAmount(sodaSonic, sodaBase);
+
+// 3. Execute. srcChainKey is the hub.
+const result = await sodax.bridge.bridge({
+  params: {
+    srcChainKey: ChainKeys.SONIC_MAINNET,
+    srcAddress: (await evmWp.getWalletAddress()) as `0x${string}`,
+    srcAsset: sodaSonic.address,
+    amount: parseUnits('1', sodaSonic.decimals),
+    dstChainKey: ChainKeys.BASE_MAINNET,
+    dstAddress: recipientOnBase,
+    dstAsset: sodaBase.address,
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+Internally `bridge()` branches on `isHubChainKeyType(srcChainKey)` and uses the user's hub wallet abstraction as the spender (the assetManager spoke address is used for non-hub sources). For allowance and approval flows, treat Sonic-as-source the same as any other EVM source — `isAllowanceValid` and `approve` use the same parameter shape.
+
+### Bridgeable-amount check
+
+Respects vault deposit limits (spoke→hub) and asset-manager balance (hub→spoke). Pass the source and destination tokens as full `XToken` objects (each carries its own `chainKey`):
+
+```ts
+const result = await sodax.bridge.getBridgeableAmount(USDC_ARBITRUM, USDC_STELLAR);
+if (result.ok) {
+  const { amount, decimals, type } = result.value;   // BridgeLimit
+  console.log(`Up to ${amount} (${decimals} decimals) can be bridged`);
+}
+```
+
+### Find compatible tokens
+
+Synchronous (config-derived). Pass source-chain key, destination-chain key, and the source token address; the SDK filters the destination's supported tokens by matching vault:
+
+```ts
+const result = sodax.bridge.getBridgeableTokens(
+  ChainKeys.ARBITRUM_MAINNET,
+  ChainKeys.STELLAR_MAINNET,
+  USDC_ARBITRUM.address,
+);
+if (result.ok) {
+  // result.value: XToken[] — Stellar-side tokens that share USDC_ARBITRUM's vault
+  for (const token of result.value) {
+    console.log(token.chainKey, token.symbol);
+  }
+}
+```
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| `bridge` | `TxHashPair` |
+| `createBridgeIntent` | `CreateBridgeIntentResult<K, Raw>` = `{ tx: TxReturnType<K, Raw>, intent, relayData }` |
+| `approve` | `TxReturnType<K, Raw>` |
+| `isAllowanceValid` | `boolean` |
+| `getBridgeableAmount` | `BridgeLimit = { amount, decimals, type }` |
+| `getBridgeableTokens` | `XToken[]` |
+
+## Error codes
+
+`feature: 'bridge'`. Per-method narrow unions:
+
+| Method | Codes | `error.context` |
+|---|---|---|
+| `bridge` | full exec set | `action: 'bridge'` |
+| `createBridgeIntent` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `UNKNOWN` | `action: 'bridge'` |
+| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | n/a |
+| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | n/a |
+| `getBridgeableAmount`, `getBridgeableTokens` | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | `method: 'getBridgeableAmount' \| 'getBridgeableTokens'` |
+
+## Cross-references
+
+- v1 → v2 bridge migration: [`features/bridge.md`](../../../migration-v1-to-v2/knowledge/features/bridge.md).
+- Stellar destinations need a trustline first: [`../chain-specifics.md`](../chain-specifics.md).
+- Hub-and-spoke vault architecture: [`../architecture.md`](../architecture.md) § 1.

package/skills/sodax-sdk/integration/knowledge/features/dex.md

@@ -0,0 +1,182 @@
+# DEX — `DexService` (`AssetService` + `ClService`)
+
+Concentrated liquidity AMM, similar to Uniswap V3 / PancakeSwap V3. Two sub-services:
+
+- **`AssetService`** — wraps/unwraps spoke assets into the hub-side pool tokens. `deposit` (spoke→hub), `withdraw` (hub→spoke).
+- **`ClService`** — full concentrated-liquidity position lifecycle: mint, increase, decrease, claim rewards. Pool / position read methods. (Class lives in `ConcentratedLiquidityService.ts` but the exported class is named `ClService`.)
+
+Access: `sodax.dex.assetService`, `sodax.dex.clService`. Class names: `AssetService`, `ClService`. Feature tag for errors: `'dex'`.
+
+## How it works
+
+To enter a position:
+
+1. **`assetService.deposit({ asset, amount, poolToken, ... })`** — wraps the spoke token into the hub-side pool token (vault).
+2. **`assetService.approve(...)`** — permit the CL contract to spend the wrapped token.
+3. **`clService.supplyLiquidity({ poolKey, ..., liquidity, amount0Max, amount1Max })`** — mints a new position NFT.
+
+To increase / decrease / claim:
+
+- **`clService.increaseLiquidity({ tokenId, ... })`** — adds liquidity to an existing position.
+- **`clService.decreaseLiquidity({ tokenId, liquidity, amount0Min, amount1Min })`** — removes a fraction of liquidity (no NFT burn).
+- **`clService.claimRewards({ tokenId, poolKey, tickLower, tickUpper })`** — collects accrued fees/rewards for a position.
+
+## Public methods
+
+```ts
+// AssetService
+sodax.dex.assetService.deposit<K>(action: AssetDepositAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
+sodax.dex.assetService.withdraw<K>(action: AssetWithdrawAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
+sodax.dex.assetService.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+sodax.dex.assetService.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
+sodax.dex.assetService.getDeposit(poolToken, walletAddress, chainKey): Promise<Result<bigint, SodaxError>>;
+sodax.dex.assetService.executeDeposit<K, Raw>(args): /* spoke-only deposit; no relay */;
+
+// ClService (concentrated liquidity)
+sodax.dex.clService.supplyLiquidity<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.dex.clService.increaseLiquidity<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.dex.clService.decreaseLiquidity<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.dex.clService.claimRewards<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+
+sodax.dex.clService.getPools(): PoolKey[];                 // synchronous in v2
+sodax.dex.clService.getPoolData(poolKey, publicClient): Promise<Result<PoolData, SodaxError>>;
+sodax.dex.clService.getPositionInfo(tokenId, poolKey, publicClient): Promise<Result<PositionInfo, SodaxError>>;
+sodax.dex.clService.getAssetsForPool(srcChainKey, poolKey): { token0, token1 };   // chain-key-first; sync
+
+// Static math helpers (still throw on error — utility class):
+ClService.priceToTick(price): number;
+ClService.calculateAmount0FromAmount1(...): bigint;
+ClService.calculateAmount1FromAmount0(...): bigint;
+```
+
+## Action params shape
+
+```ts
+type CreateAssetDepositParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  asset: `0x${string}`;       // spoke-side token address
+  amount: bigint;
+  poolToken: `0x${string}`;   // hub-side pool token (vault address)
+  dst?: { chainKey: SpokeChainKey; address: string };  // optional cross-chain delivery
+};
+
+type CreateAssetWithdrawParams<K> = { /* same shape */ };
+
+type ClSupplyParams<K> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  poolKey: PoolKey;
+  tickLower: number;
+  tickUpper: number;
+  liquidity: bigint;
+  amount0Max: bigint;
+  amount1Max: bigint;
+  sqrtPriceX96: bigint;
+};
+
+type ClIncreaseLiquidityParams<K> = ClSupplyParams<K> & { tokenId: bigint };
+type ClDecreaseLiquidityParams<K> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  poolKey: PoolKey;
+  tokenId: bigint;
+  liquidity: bigint;
+  amount0Min: bigint;
+  amount1Min: bigint;
+};
+type ClClaimRewardsParams<K> = { srcChainKey, srcAddress, poolKey, tokenId, tickLower, tickUpper };
+```
+
+## Common call shapes
+
+### Deposit (spoke asset → hub pool token)
+
+```ts
+const result = await sodax.dex.assetService.deposit({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    asset: USDC.address,
+    amount: parseUnits('100', 6),
+    poolToken: '0x…',  // the hub-side pool token (XToken.vault)
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### Mint a new concentrated-liquidity position
+
+```ts
+const result = await sodax.dex.clService.supplyLiquidity({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    poolKey: { /* { currency0, currency1, fee, tickSpacing, hooks } */ },
+    tickLower: -887220,
+    tickUpper: 887220,
+    liquidity: 1000000n,
+    amount0Max: parseUnits('100', 6),
+    amount1Max: parseUnits('100', 6),
+    sqrtPriceX96: /* current sqrtPrice */,
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+### Increase liquidity on an existing position
+
+```ts
+await sodax.dex.clService.increaseLiquidity({
+  params: { /* same as supplyLiquidity, plus tokenId: existingPositionTokenId */ },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+### Allowance check (read-only)
+
+```ts
+const allowed = await sodax.dex.assetService.isAllowanceValid({
+  params: { srcChainKey, srcAddress, asset, amount, poolToken },
+  raw: true,    // read-only — no walletProvider required
+});
+```
+
+The underlying read does not consult the wallet provider; pass `raw: true` to satisfy `WalletProviderSlot` without supplying a provider.
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| `deposit`, `withdraw`, `supplyLiquidity`, `increaseLiquidity`, `decreaseLiquidity`, `claimRewards` | `TxHashPair` |
+| `approve` | `TxReturnType<K, Raw>` |
+| `isAllowanceValid` | `boolean` |
+| `getDeposit` | `bigint` (user's balance in the pool's hub wallet) |
+| `getPoolData` | `{ liquidity, sqrtPriceX96, tick, /* … */ }` |
+| `getPositionInfo` | `{ poolKey, tickLower, tickUpper, liquidity, fees0, fees1, /* … */ }` |
+| `getPools` | `PoolKey[]` (synchronous, returns from cached config) |
+| `getAssetsForPool` | `{ token0: XToken, token1: XToken }` (synchronous; takes `srcChainKey` to filter by spoke availability) |
+
+> `getPools()` is **synchronous** in v2 (was `Promise<PoolKey[]>` in v1). v2 reads from cached config — no I/O. `await sodax.dex.clService.getPools()` works (TS allows `await` on non-promise) but `.then(...)` is a runtime error.
+
+## Error codes
+
+`feature: 'dex'`. Per-method narrow unions:
+
+| Method | Codes | Action |
+|---|---|---|
+| `deposit`, `withdraw`, `supplyLiquidity`, `increaseLiquidity`, `decreaseLiquidity`, `claimRewards` | full exec set | matches operation |
+| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | matches operation |
+| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | n/a |
+| `getDeposit`, `getPoolData`, `getPositionInfo` | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | (use `error.context.method`) |
+
+## Cross-references
+
+- v1 → v2 DEX migration: [`features/dex.md`](../../../migration-v1-to-v2/knowledge/features/dex.md).
+- The hub-side `EvmHubProvider.publicClient` is what `getPoolData` / `getPositionInfo` use internally — consumers can pass `sodax.hubProvider.publicClient`.