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

package/ai-exported/integration/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: [`../../migration/features/dex.md`](../../migration/features/dex.md).
+- The hub-side `EvmHubProvider.publicClient` is what `getPoolData` / `getPositionInfo` use internally — consumers can pass `sodax.hubProvider.publicClient`.

package/ai-exported/integration/features/icx-bnusd-baln.md

@@ -0,0 +1,181 @@
+# Token migration — `MigrationService`
+
+Migration of legacy ICON ecosystem tokens to the SODAX hub. Three sub-services:
+
+- **`IcxMigrationService`** — ICX/wICX → SODA (forward) and SODA → ICX (revert).
+- **`BnUSDMigrationService`** — legacy bnUSD (ICON / Sui / Stellar) ↔ new bnUSD (EVM chains) via vault transformations.
+- **`BalnSwapService`** — BALN → SODA with lockup periods (0–24 months) that multiply rewards (0.5x–1.5x).
+
+Access: `sodax.migration`. Service class: `MigrationService` (with sub-services `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`). Feature tag for errors: `'migration'`.
+
+> Don't confuse this feature (the `MigrationService` SDK module) with the v1 → v2 SDK port itself. They share the word "migration" but are independent concerns. The v1 → v2 port playbook lives at [`../../migration/features/icx-bnusd-baln.md`](../../migration/features/icx-bnusd-baln.md).
+
+## How it works
+
+All three sub-services follow the same pattern: deposit on a spoke chain → relay to hub → execute hub-side migration contract → deliver new token.
+
+`MigrationService` exposes 11 async public methods:
+
+- 4 orchestrators (full execution): `migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`.
+- 4 intent creators (raw or signed spoke tx, no full lifecycle): `createMigrateBnUSDIntent`, `createMigrateIcxToSodaIntent`, `createRevertMigrateSodaToIcxIntent`, `createMigrateBalnIntent`.
+- `approve`, `isAllowanceValid` (action-discriminated like staking and money market).
+- `getAvailableAmount` (read-only; `IcxMigrationService` only — checks how much SODA the user can claim from a partial migration).
+
+`BalnSwapService` has additional lock-management methods that **still throw** (do not return `Result<T>`): `claim`, `claimUnstaked`, `stake`, `unstake`, `cancelUnstake`, `getDetailedUserLocks`. This is deliberate tech debt; future cleanup. Wrap them in `try/catch` until then.
+
+## Public methods
+
+```ts
+sodax.migration.migratebnUSD<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.migration.migrateIcxToSoda<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.migration.revertMigrateSodaToIcx<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.migration.migrateBaln<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+
+sodax.migration.createMigrateBnUSDIntent<K, Raw>(...): Promise<Result<...>>;
+// + 3 other createXxxIntent methods
+
+sodax.migration.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+sodax.migration.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
+
+sodax.migration.icxMigration.getAvailableAmount(): Promise<Result<bigint, SodaxError>>;
+
+// BalnSwapService — STILL THROW (tech debt; not Result-wrapped):
+sodax.migration.balnSwapService.claim(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.claimUnstaked(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.stake(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.unstake(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.cancelUnstake(...): Promise<TxReturnType<K, false>>;
+sodax.migration.balnSwapService.getDetailedUserLocks(...): Promise<DetailedUserLocks>;
+```
+
+## Action params shape
+
+```ts
+type MigrationParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  amount: bigint;
+  dstAddress?: string;
+};
+
+type UnifiedBnUSDMigrateParams<K> = MigrationParams<K> & {
+  srcToken: `0x${string}`;       // legacy or new bnUSD; SDK detects direction from address
+  dstToken: `0x${string}`;       // the other side
+};
+
+type IcxToSodaMigrateParams<K> = MigrationParams<K>;
+type RevertSodaToIcxParams<K> = MigrationParams<K>;
+type BalnSwapParams<K> = MigrationParams<K> & {
+  lockPeriodMonths: 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24;  // reward multiplier 0.5x – 1.5x
+};
+```
+
+## Common call shapes
+
+### bnUSD migrate (forward — legacy → new, e.g. ICON → BASE)
+
+```ts
+const result = await sodax.migration.migratebnUSD({
+  params: {
+    srcChainKey: ChainKeys.ICON_MAINNET,
+    srcAddress: 'hx…',
+    srcToken: '0x…',  // legacy bnUSD on ICON
+    dstToken: '0x…',  // new bnUSD on BASE
+    amount: parseUnits('100', 18),
+    dstAddress: '0x…',
+  },
+  raw: false,
+  walletProvider: iconWp,
+});
+
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+The SDK auto-detects direction from `(srcToken, dstToken)` addresses; the `direction` field surfaces on `error.context` if it fails (`'forward' | 'reverse'`).
+
+### ICX → SODA
+
+```ts
+await sodax.migration.migrateIcxToSoda({
+  params: { srcChainKey: ChainKeys.ICON_MAINNET, srcAddress: 'hx…', amount },
+  raw: false,
+  walletProvider: iconWp,
+});
+```
+
+### Revert SODA → ICX
+
+```ts
+await sodax.migration.revertMigrateSodaToIcx({
+  params: { srcChainKey: ChainKeys.SONIC_MAINNET, srcAddress: '0x…', amount },
+  raw: false,
+  walletProvider: sonicWp,
+});
+```
+
+### BALN → SODA with lockup
+
+```ts
+await sodax.migration.migrateBaln({
+  params: {
+    srcChainKey: ChainKeys.ICON_MAINNET,
+    srcAddress: 'hx…',
+    amount: parseUnits('1000', 18),
+    lockPeriodMonths: 12,    // 1.0x base; 24 is 1.5x; 0 is 0.5x
+  },
+  raw: false,
+  walletProvider: iconWp,
+});
+```
+
+### Approve / allowance — action-discriminated
+
+```ts
+await sodax.migration.approve({
+  params: { srcChainKey, srcAddress, amount, action: 'migratebnUSD' /* or 'migrateIcxToSoda' | 'revertMigrateSodaToIcx' | 'migrateBaln' */ },
+  raw: false,
+  walletProvider,
+});
+```
+
+### BALN lock management (carve-out — still throws)
+
+```ts
+try {
+  const tx = await sodax.migration.balnSwapService.stake({ /* … */ });
+} catch (e) {
+  // Handle as v1-style throw. Result wrapping for these methods is on the roadmap.
+}
+```
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| 4 orchestrators (`migratebnUSD`, `migrateIcxToSoda`, `revertMigrateSodaToIcx`, `migrateBaln`) | `TxHashPair` |
+| 4 intent creators | `CreateIntentResult<K, Raw>` |
+| `approve` | `TxReturnType<K, Raw>` |
+| `isAllowanceValid` | `boolean` |
+| `getAvailableAmount` | `bigint` |
+| `BalnSwapService.claim` etc. | `TxReturnType<K, false>` (raw, not `Result`-wrapped) |
+
+## Error codes
+
+`feature: 'migration'`. Per-method narrow unions:
+
+| Method | Codes | `error.context.action` | Notes |
+|---|---|---|---|
+| `migratebnUSD` | full exec set incl. `TX_VERIFICATION_FAILED` | `'migratebnUSD'` | `error.context.direction: 'forward' \| 'reverse'`. Has secondary `phase: 'destinationExecution'` for the bnUSD `waitUntilIntentExecuted` watcher. |
+| `migrateIcxToSoda` | full exec set | `'migrateIcxToSoda'` | |
+| `revertMigrateSodaToIcx` | full exec set | `'revertMigrateSodaToIcx'` | |
+| `migrateBaln` | full exec set | `'migrateBaln'` | |
+| `create*Intent` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `UNKNOWN` | matches | |
+| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | matches | |
+| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | n/a | |
+| `getAvailableAmount` | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | n/a | `method: 'getAvailableAmount'` |
+
+## Cross-references
+
+- v1 → v2 migration of this feature: [`../../migration/features/icx-bnusd-baln.md`](../../migration/features/icx-bnusd-baln.md).
+- Architecture (relay layer's `phase: 'destinationExecution'` for bnUSD): [`../architecture.md`](../architecture.md) § 9.

package/ai-exported/integration/features/money-market.md

@@ -0,0 +1,198 @@
+# Money Market — `MoneyMarketService`
+
+Cross-chain lending and borrowing. Supply, borrow, withdraw, repay across 19 spoke chains. Position state lives on the hub.
+
+Access: `sodax.moneyMarket`. Service class: `MoneyMarketService`. Feature tag for errors: `'moneyMarket'`.
+
+## How it works
+
+A user supplies on a spoke chain; the SDK relays the deposit to the hub, where the position is recorded against the user's hub wallet abstraction. Borrow can deliver funds back to the same chain (same-chain borrow) or to a different spoke chain (cross-chain borrow). Withdraw and repay reverse the flow.
+
+aTokens (ERC4626 receipt tokens) live on the hub and represent the user's share of each reserve. Use `sodax.moneyMarket.getAToken(...)` to look them up.
+
+## Public methods
+
+```ts
+// Mutations
+sodax.moneyMarket.supply<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.moneyMarket.borrow<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.moneyMarket.withdraw<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+sodax.moneyMarket.repay<K>(action): Promise<Result<TxHashPair, SodaxError>>;
+
+// Intent creators (raw-tx variant)
+sodax.moneyMarket.createSupplyIntent<K, Raw>(...): Promise<Result<...>>;
+sodax.moneyMarket.createBorrowIntent<K, Raw>(...): Promise<Result<...>>;
+sodax.moneyMarket.createWithdrawIntent<K, Raw>(...): Promise<Result<...>>;
+sodax.moneyMarket.createRepayIntent<K, Raw>(...): Promise<Result<...>>;
+
+// Approve + allowance (action-discriminated)
+sodax.moneyMarket.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+sodax.moneyMarket.isAllowanceValid<K>(args): Promise<Result<boolean, SodaxError>>;
+
+// Estimation
+sodax.moneyMarket.estimateGas<K>(params): Promise<Result<GetEstimateGasReturnType<K>, SodaxError>>;
+
+// Reads (sync — config-derived, no I/O)
+sodax.moneyMarket.getSupportedTokens(): GetMoneyMarketTokensApiResponse;
+sodax.moneyMarket.getSupportedTokensByChainId(chainKey): readonly XToken[];
+sodax.moneyMarket.getSupportedReserves(): readonly Address[];
+
+// Hub-side calldata builders (Hex outputs; pre-flight inspection / custom orchestration)
+sodax.moneyMarket.buildSupplyData(srcChainKey, fromToken, amount, toHubAddress): Hex;
+sodax.moneyMarket.buildBorrowData(...): Hex;
+sodax.moneyMarket.buildWithdrawData(...): Hex;
+sodax.moneyMarket.buildRepayData(...): Hex;
+```
+
+For per-position user reads (reserves data, user reserves data, formatted summaries, aToken balances, etc.) the entrypoint is `sodax.backendApi`, not `MoneyMarketService` — see `auxiliary-services.md` § "BackendApiService" for `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
+
+## Action params shape
+
+`MoneyMarketParams<K>` is the shared base:
+
+```ts
+type MoneyMarketParams<K extends SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: GetAddressType<K>;
+  token: `0x${string}`;     // hub asset address
+  amount: bigint;
+};
+```
+
+Per-action params:
+
+```ts
+type MoneyMarketSupplyParams<K> = MoneyMarketParams<K> & { action: 'supply' };
+type MoneyMarketWithdrawParams<K> = MoneyMarketParams<K> & { action: 'withdraw' };
+
+type MoneyMarketBorrowParams<K> = MoneyMarketParams<K> & {
+  action: 'borrow';
+  dstChainKey?: SpokeChainKey;   // delivery chain; defaults to srcChainKey
+  dstAddress?: string;
+};
+type MoneyMarketRepayParams<K> = MoneyMarketParams<K> & {
+  action: 'repay';
+  dstChainKey?: SpokeChainKey;   // debt chain; defaults to srcChainKey
+  dstAddress?: string;
+};
+```
+
+## Common call shapes
+
+### Supply (same-chain)
+
+```ts
+const result = await sodax.moneyMarket.supply({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    token: USDC.address,
+    amount: parseUnits('100', 6),
+    action: 'supply',
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+if (!result.ok) return;
+const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### Borrow (cross-chain)
+
+Borrow on Arbitrum, deliver USDC to Stellar:
+
+```ts
+await sodax.moneyMarket.borrow({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress: '0x…',
+    token: USDC_ARBITRUM.address,
+    amount: parseUnits('50', 6),
+    action: 'borrow',
+    dstChainKey: ChainKeys.STELLAR_MAINNET,
+    dstAddress: 'G…',
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+Same-chain borrow: omit `dstChainKey` and `dstAddress`.
+
+### Repay (cross-chain — pay from a different chain than the debt)
+
+```ts
+await sodax.moneyMarket.repay({
+  params: {
+    srcChainKey: ChainKeys.BASE_MAINNET,            // funds come from here
+    srcAddress: '0x…',
+    token: USDC_BASE.address,
+    amount: parseUnits('50', 6),
+    action: 'repay',
+    dstChainKey: ChainKeys.ARBITRUM_MAINNET,        // debt lives here
+    dstAddress: '0x…',
+  },
+  raw: false,
+  walletProvider: baseWp,    // wallet signs on the FROM chain (BASE)
+});
+```
+
+### Approve / allowance check
+
+```ts
+await sodax.moneyMarket.approve({
+  params: { srcChainKey, srcAddress, token, amount, action: 'supply' },
+  raw: false,
+  walletProvider: evmWp,
+});
+
+const allowed = await sodax.moneyMarket.isAllowanceValid({
+  params: { srcChainKey, srcAddress, token, amount, action: 'supply' },
+});
+```
+
+The `action` field routes to the right token under the hood — relevant for repay where the spent token may differ from the supplied token.
+
+## Return shapes
+
+| Method | Success type |
+|---|---|
+| `supply`, `borrow`, `withdraw`, `repay` | `TxHashPair` = `{ srcChainTxHash, dstChainTxHash }` |
+| `create*Intent` | `CreateIntentResult<K, Raw>` |
+| `approve` | `TxReturnType<K, Raw>` |
+| `isAllowanceValid` | `boolean` |
+| `estimateGas` | `GetEstimateGasReturnType<K>` (chain-family-specific) |
+| `getSupportedTokens` | `GetMoneyMarketTokensApiResponse` (record of chains → token arrays) |
+| `getSupportedTokensByChainId` | `readonly XToken[]` |
+| `getSupportedReserves` | `readonly Address[]` |
+| `buildSupplyData` / `buildBorrowData` / `buildWithdrawData` / `buildRepayData` | `Hex` (calldata for hub-side calls) |
+
+> Every cross-chain mutation across the SDK (bridge, staking, dex, migration, MM) returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` — there is no array-form variant in v2.
+
+## Error codes
+
+`feature: 'moneyMarket'`. Per-method narrow unions:
+
+| Method | Codes | `error.context.action` |
+|---|---|---|
+| `supply` | full exec set | `'supply'` |
+| `borrow` | full exec set | `'borrow'` |
+| `withdraw` | full exec set | `'withdraw'` |
+| `repay` | full exec set | `'repay'` |
+| `create*Intent` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `UNKNOWN` | matches action |
+| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | matches action |
+| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | matches action |
+| Read methods | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | (use `error.context.method`) |
+
+"Full exec set" = `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| EXECUTION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| UNKNOWN`.
+
+## RAY precision math
+
+Aave's RAY precision (27 decimals) is used for interest calculations under the hood. Raw RAY values flow through `BackendApiService.getMoneyMarketAsset` / `getMoneyMarketPosition` (via `sodax.backendApi`); pre-formatted user-facing values come from the same backend service. Don't simplify the precision handling — porting Aave's `RayMath`/`PercentageMath` losslessly is a load-bearing requirement.
+
+## Cross-references
+
+- v1 → v2 money market migration: [`../../migration/features/money-market.md`](../../migration/features/money-market.md).
+- Architecture (hub-side wallet abstraction, ConfigService): [`../architecture.md`](../architecture.md) §§ 3, 4.
+- Stellar destinations need a trustline: [`../chain-specifics.md`](../chain-specifics.md).