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

package/ai-exported/integration/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/ai-exported/integration/features/README.md

@@ -0,0 +1,19 @@
+# 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. |
+| [`icx-bnusd-baln.md`](icx-bnusd-baln.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. |
+| [`auxiliary-services.md`](auxiliary-services.md) | `PartnerService` + `RecoveryService` + `BackendApiService` | Three small APIs grouped together: partner-fee claiming, hub-wallet asset recovery, backend HTTP client. |
+
+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 [`../../migration/features/`](../../migration/features/) — same filename, different angle.

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

@@ -0,0 +1,189 @@
+# Auxiliary services — `PartnerService`, `RecoveryService`, `BackendApiService`
+
+Three small services grouped together. None has the surface area of the major features (swap, money market, etc.), but they're load-bearing in real consumer flows.
+
+## `PartnerService` — `sodax.partners`
+
+Partner-fee handling. `PartnerService` itself only exposes `feeClaim: PartnerFeeClaimService` and `config: ConfigService` as public fields. Every operation lives on `sodax.partners.feeClaim`.
+
+**Feature tag for errors:** `'partner'`.
+
+### Methods (all on `sodax.partners.feeClaim`)
+
+```ts
+// Token approval
+sodax.partners.feeClaim.isTokenApproved({ token, srcAddress }): Promise<Result<boolean, Error>>;
+sodax.partners.feeClaim.approveToken<Raw>(args): Promise<Result<TxReturnType, Error>>;
+
+// Auto-swap preferences (whether partner-collected fees auto-swap into a target asset)
+sodax.partners.feeClaim.getAutoSwapPreferences(queryAddress): Promise<Result<AutoSwapPreferences, Error>>;
+sodax.partners.feeClaim.setSwapPreference<K, Raw>(args): Promise<Result<TxReturnType, Error>>;
+
+// Fee claim flows
+sodax.partners.feeClaim.swap(args): Promise<Result<...>>;                           // immediate fee swap
+sodax.partners.feeClaim.createIntentAutoSwap<Raw>(args): Promise<Result<...>>;       // intent-driven auto-swap
+
+// Reads
+sodax.partners.feeClaim.fetchAssetsBalances(args): Promise<Result<...>>;
+sodax.partners.feeClaim.getOriginalAssetAddress(chainId, hubAsset): OriginalAssetAddress | undefined;
+sodax.partners.feeClaim.getSpokeTokenFromOriginalAssetAddress(...): /* … */;
+```
+
+### Common call shape
+
+```ts
+// 1. Check whether the partner's fee token is approved on the hub:
+const approved = await sodax.partners.feeClaim.isTokenApproved({
+  token: '0x…',         // hub asset address
+  srcAddress: partnerAddress,
+});
+
+// 2. Approve once if not:
+if (approved.ok && !approved.value) {
+  await sodax.partners.feeClaim.approveToken({
+    params: { token: '0x…', amount: 2n ** 256n - 1n },
+    raw: false,
+    walletProvider: sonicWp,
+  });
+}
+
+// 3. Configure auto-swap preference (one-time):
+await sodax.partners.feeClaim.setSwapPreference({
+  params: { /* preference fields */ },
+  raw: false,
+  walletProvider: sonicWp,
+});
+```
+
+### Error codes
+
+`feature: 'partner'`. Action methods get the full exec set; reads get `LookupErrorCode` partitioned by `error.context.method`.
+
+---
+
+## `RecoveryService` — `sodax.recovery`
+
+Withdraw stuck assets from a user's hub wallet abstraction back to a spoke chain. Useful when a cross-chain operation deposited to the hub but the destination step failed (e.g. relay timeout after the spoke tx landed).
+
+**Feature tag for errors:** `'recovery'`.
+
+### Methods
+
+```ts
+// Read: list balances of all known hub assets in a user's hub wallet abstraction.
+sodax.recovery.fetchHubAssetBalances(args): Promise<Result<HubAssetBalance[], SodaxError>>;
+
+// Mutation: withdraw a single hub asset back to a spoke chain.
+// Returns a tx-pair when raw: false (the hub-side spend + the relayed spoke-side receive).
+sodax.recovery.withdrawHubAsset<K extends SpokeChainKey, Raw extends boolean>(
+  action: WithdrawHubAssetAction<K, Raw>,
+): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
+```
+
+### Common call shape
+
+```ts
+// 1. Find what's stuck on the hub for this user:
+const balances = await sodax.recovery.fetchHubAssetBalances({ /* user / hub-wallet args */ });
+if (!balances.ok || balances.value.length === 0) return;
+
+// 2. Withdraw one entry back to a spoke chain:
+const result = await sodax.recovery.withdrawHubAsset({
+  params: {
+    /* hub-asset address, amount, destination spoke chain key, destination address */
+  },
+  raw: false,
+  walletProvider: sonicWp,
+});
+```
+
+### Error codes
+
+`feature: 'recovery'`. The mutation method returns the full exec set (including relay codes); the read method returns `LookupErrorCode` partitioned by `error.context.method`.
+
+### When to use
+
+Recovery is a workaround for failed cross-chain operations. Best used **after** investigating why the original operation failed — relay timeouts may resolve on retry; structural failures need fixing first.
+
+---
+
+## `BackendApiService` — `sodax.backendApi`
+
+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.
+
+**Feature tag for errors:** appears under multiple features depending on the call site (`'swap'` for `submitSwapTx`); 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' | …` (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)
+
+Inject an `IConfigApi` implementation via `SodaxConfig.backendApi.api`:
+
+```ts
+const sandboxApi: IConfigApi = {
+  async getChains() { return { ok: true, value: [/* fixture */] }; },
+  // …
+};
+
+const sodax = new Sodax({
+  backendApi: { url: 'unused', api: sandboxApi },
+});
+await sodax.config.initialize();
+```
+
+Every method on `IConfigApi` returns `Promise<Result<T>>` in v2.
+
+---
+
+## Cross-references
+
+- v1 → v2 migration of these auxiliary services: [`../../migration/features/auxiliary-services.md`](../../migration/features/auxiliary-services.md).
+- The full `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) § "Backend submit-tx flow".
+- Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.

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

@@ -0,0 +1,136 @@
+# 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.
+```
+
+### 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: [`../../migration/features/bridge.md`](../../migration/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.