@sodax/sdk 2.0.0-rc.2 → 2.0.0-rc.4

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

@@ -1,166 +0,0 @@
-# Staking — `StakingService`
-
-SODA token staking via an ERC4626 vault (xSoda). Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel-unstake. All operations are cross-chain — staking writes happen on the hub even when the user is on a spoke chain.
-
-Access: `sodax.staking`. Service class: `StakingService`. Feature tag for errors: `'staking'`.
-
-## How it works
-
-- **SODA** (the staked asset) → **xSoda** (ERC4626 vault shares, proportional to current exchange rate).
-- **Unstake** has a configurable waiting period with linear penalty (max 1–100%).
-- **Instant unstake** bypasses the waiting period but pays slippage (via `StakingRouter`).
-- **Claim** redeems SODA after the unstaking period expires.
-- **Cancel unstake** restores xSoda from a pending unstake request before claim.
-
-## Public methods
-
-```ts
-sodax.staking.stake<K>(action: StakeAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
-sodax.staking.unstake<K>(action: UnstakeAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
-sodax.staking.instantUnstake<K>(action: InstantUnstakeAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
-sodax.staking.claim<K>(action: ClaimAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
-sodax.staking.cancelUnstake<K>(action: CancelUnstakeAction<K, false>): Promise<Result<TxHashPair, SodaxError>>;
-
-sodax.staking.createStakeIntent<K, Raw>(...): Promise<Result<...>>;
-// + the 4 other createXxxIntent methods
-
-sodax.staking.approve<K, Raw>(args): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
-sodax.staking.isAllowanceValid<K, Raw>(args): Promise<Result<boolean, SodaxError>>;
-
-// Reads (hub-only — no chain context needed):
-sodax.staking.getStakingConfig(): Promise<Result<StakingConfig, SodaxError>>;
-sodax.staking.getStakeRatio(amount): Promise<Result<[bigint, bigint], SodaxError>>;
-//   value: [xSodaAmount, previewDepositAmount]
-sodax.staking.getInstantUnstakeRatio(amount): Promise<Result<bigint, SodaxError>>;
-sodax.staking.getConvertedAssets(amount): Promise<Result<bigint, SodaxError>>;
-
-// Reads (cross-chain — derive hub wallet from src chain):
-sodax.staking.getStakingInfoFromSpoke(srcAddress, srcChainKey): Promise<Result<StakingInfo, SodaxError>>;
-sodax.staking.getUnstakingInfo(srcAddress, srcChainKey): Promise<Result<UnstakingInfo, SodaxError>>;
-//   value: { userUnstakeSodaRequests: UserUnstakeInfo[]; totalUnstaking: bigint }
-sodax.staking.getUnstakingInfoWithPenalty(srcAddress, srcChainKey): Promise<Result<UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }, SodaxError>>;
-//   each request adds penalty, penaltyPercentage, claimableAmount
-```
-
-## Action params shape
-
-```ts
-type StakeParams<K extends SpokeChainKey> = {
-  srcChainKey: K;
-  srcAddress: GetAddressType<K>;
-  amount: bigint;
-  minReceive: bigint;       // min xSoda after slippage; gate against bad rates
-  action: 'stake';
-};
-
-type UnstakeParams<K> = { srcChainKey: K; srcAddress; amount: bigint; action: 'unstake' };
-type InstantUnstakeParams<K> = { srcChainKey: K; srcAddress; amount: bigint; minAmount: bigint; action: 'instantUnstake' };
-type ClaimParams<K> = { srcChainKey: K; srcAddress; requestId: bigint; amount: bigint; action: 'claim' };
-type CancelUnstakeParams<K> = { srcChainKey: K; srcAddress; requestId: bigint; action: 'cancelUnstake' };
-```
-
-`StakingParamsUnion<K, Raw>` is the union of all 5; consumed by `staking.approve` and `staking.isAllowanceValid` (action-discriminated).
-
-## Common call shapes
-
-### Stake
-
-```ts
-const result = await sodax.staking.stake({
-  params: {
-    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-    srcAddress: '0x…',
-    amount: parseUnits('100', 18),    // 100 SODA
-    minReceive: parseUnits('99', 18), // expect ~1% slippage tolerance
-    action: 'stake',
-  },
-  raw: false,
-  walletProvider: evmWp,
-});
-
-if (!result.ok) return;
-const { srcChainTxHash, dstChainTxHash } = result.value;
-```
-
-### Unstake (with penalty curve)
-
-```ts
-await sodax.staking.unstake({
-  params: { srcChainKey, srcAddress, amount: xSodaAmount, action: 'unstake' },
-  raw: false,
-  walletProvider,
-});
-```
-
-Creates a pending unstake request. After the staking period expires, call `claim`. Use `getUnstakingInfoWithPenalty` to see the current penalty for early withdrawal.
-
-### Instant unstake
-
-```ts
-await sodax.staking.instantUnstake({
-  params: {
-    srcChainKey, srcAddress,
-    amount: xSodaAmount,
-    minAmount: minSodaAfterSlippage,
-    action: 'instantUnstake',
-  },
-  raw: false,
-  walletProvider,
-});
-```
-
-Bypasses the waiting period; pays slippage via `StakingRouter`.
-
-### Approve / allowance — action-discriminated
-
-The `approve` method routes by `params.action` to approve the right token (SODA for `stake`, xSoda for `unstake` and `instantUnstake`):
-
-```ts
-await sodax.staking.approve({
-  params: { srcChainKey, srcAddress, amount, action: 'stake' /* or 'unstake' or 'instantUnstake' */ },
-  raw: false,
-  walletProvider,
-});
-
-const allowed = await sodax.staking.isAllowanceValid({
-  params: { srcChainKey, srcAddress, amount, action: 'stake' },
-  raw: true,    // read-only
-});
-```
-
-## Return shapes
-
-| Method | Success type |
-|---|---|
-| `stake`, `unstake`, `instantUnstake`, `claim`, `cancelUnstake` | `TxHashPair` |
-| `create*Intent` | `CreateIntentResult<K, Raw>` |
-| `approve` | `TxReturnType<K, Raw>` |
-| `isAllowanceValid` | `boolean` |
-| `getStakingConfig` | `{ unstakingPeriod, maxPenalty, minPenalty, /* … */ }` |
-| `getStakeRatio` | `[xSodaAmount: bigint, previewDepositAmount: bigint]` (estimated xSoda shares + vault's `previewDeposit` preview) |
-| `getInstantUnstakeRatio` | `bigint` |
-| `getConvertedAssets` | `bigint` (SODA per xSoda) |
-| `getStakingInfoFromSpoke` | `StakingInfo` (xSoda balance, accrued, etc.) |
-| `getUnstakingInfo` | `UnstakingInfo` (object; carries `userUnstakeSodaRequests` array + aggregate amount) |
-| `getUnstakingInfoWithPenalty` | `UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }` (each entry adds `penalty`, `penaltyPercentage`, `claimableAmount`) |
-
-> All 5 mutation methods return `TxHashPair = { srcChainTxHash, dstChainTxHash }` because the SDK relays spoke→hub internally. When the user is already on the hub, both fields hold the same hash.
-
-## Error codes
-
-`feature: 'staking'`. Per-method narrow unions:
-
-| Method | Codes | Action |
-|---|---|---|
-| `stake` | full exec set incl. `TX_VERIFICATION_FAILED` (only stake calls verifyTxHash) | `'stake'` |
-| `unstake`, `instantUnstake`, `claim`, `cancelUnstake` | full exec set minus `TX_VERIFICATION_FAILED` | matches action |
-| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` | matches action |
-| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` | matches action |
-| Read methods (8 of them) | `VALIDATION_FAILED`, `LOOKUP_FAILED`, `UNKNOWN` | (use `error.context.method`) |
-
-`StakingLogic` (a static utility class for contract encoding and on-chain reads) keeps its throw-on-error contract — wrapping happens only in `StakingService` public methods.
-
-## Cross-references
-
-- v1 → v2 staking migration: [`../../migration/features/staking.md`](../../migration/features/staking.md).
-- ERC4626 vault concept (xSoda): see SODAX docs site or `@sodax/sdk` source.

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

@@ -1,207 +0,0 @@
-# Swap — `SwapService`
-
-Intent-based swaps via a solver. Cross-chain by default.
-
-Access: `sodax.swaps`. Service class: `SwapService`. Feature tag for errors: `'swap'`.
-
-## How it works
-
-1. **Build an intent** — `createIntent` signs a spoke transaction encoding the swap declaration.
-2. **Relay to hub** — handled internally; the spoke tx propagates to Sonic.
-3. **Solver fulfillment** — an off-chain solver picks up the intent and fills it on the destination chain.
-4. **Post-execution settlement** — `postExecution` finalizes the user's side once the solver completes.
-
-Two execution paths:
-
-- **`swap`** — full flow in one call. Wraps `createIntent` + relay + `postExecution`. Returns `SwapResponse` on success.
-- **`createIntent` + backend submit** — break it apart for custom relay handling. `createIntent` returns `{ tx, intent, relayData }`; submit `relayData.payload` to the backend swap-tx endpoint via `BackendApiService.submitSwapTx`.
-
-## Public methods
-
-```ts
-sodax.swaps.swap<K extends SpokeChainKey>(action: SwapActionParams<K, false>): Promise<Result<SwapResponse, SodaxError>>;
-
-sodax.swaps.createIntent<K extends SpokeChainKey, Raw extends boolean>(
-  action: SwapActionParams<K, Raw>,
-): Promise<Result<CreateIntentResult<K, Raw>, SodaxError>>;
-
-sodax.swaps.postExecution(
-  args: { intent, relayData },
-): Promise<Result<SwapResponse, SodaxError>>;
-
-sodax.swaps.createLimitOrder<K, Raw>(
-  action: LimitOrderActionParams<K, Raw>,
-): Promise<Result<CreateIntentResult<K, Raw>, SodaxError>>;
-
-sodax.swaps.createLimitOrderIntent<K, Raw>(/* same as createIntent shape with limit-order params */): /* same return */;
-
-sodax.swaps.cancelIntent<K, Raw>(/* … */): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
-sodax.swaps.cancelLimitOrder<K, Raw>(/* … */): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
-
-sodax.swaps.approve<K, Raw>(/* … */): Promise<Result<TxReturnType<K, Raw>, SodaxError>>;
-sodax.swaps.isAllowanceValid<K, Raw>(/* … */): Promise<Result<boolean, SodaxError>>;
-```
-
-## Action params shape
-
-Generic `K extends SpokeChainKey` carries the literal source chain key. `WalletProviderSlot<K, Raw>` is intersected:
-
-```ts
-type SwapActionParams<K extends SpokeChainKey, Raw extends boolean> = {
-  params: CreateIntentParams<K>;
-  skipSimulation?: boolean;
-  timeout?: number;
-  fee?: PartnerFee;
-} & WalletProviderSlot<K, Raw>;
-```
-
-`CreateIntentParams<K>`:
-
-```ts
-type CreateIntentParams<K extends SpokeChainKey> = {
-  srcChainKey: K;
-  dstChainKey: SpokeChainKey;
-  srcAddress: GetAddressType<K>;
-  dstAddress: string;       // chain-specific format on the destination side
-  inputToken: XToken;       // must have chainKey === srcChainKey
-  outputToken: XToken;      // must have chainKey === dstChainKey
-  inputAmount: bigint;
-  minOutputAmount: bigint;
-  deadline: bigint;         // unix seconds
-  allowPartialFill: boolean;
-  solver: `0x${string}`;    // solver address; '0x0…0' for default
-  data: `0x${string}`;      // arbitrary calldata; '0x' for default
-};
-```
-
-`CreateLimitOrderParams<K>` is `Omit<CreateIntentParams<K>, 'deadline'>` (limit orders have a different expiry mechanism).
-
-## Common call shapes
-
-### Signed swap (full flow)
-
-```ts
-const result = await sodax.swaps.swap({
-  params: {
-    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-    dstChainKey: ChainKeys.STELLAR_MAINNET,
-    srcAddress: '0x…',
-    dstAddress: 'G…',
-    inputToken: USDC_ARBITRUM,    // XToken with chainKey === ARBITRUM_MAINNET
-    outputToken: XLM,             // XToken with chainKey === STELLAR_MAINNET
-    inputAmount: 1_000_000n,      // 1 USDC (6 decimals)
-    minOutputAmount: 500_0000000n, // 50 XLM (7 decimals)
-    deadline: BigInt(Math.floor(Date.now() / 1000) + 300),
-    allowPartialFill: false,
-    solver: '0x0000000000000000000000000000000000000000',
-    data: '0x',
-  },
-  raw: false,
-  walletProvider: evmWp,
-});
-
-if (!result.ok) return;
-const { solverExecutionResponse, intent, intentDeliveryInfo } = result.value;
-// SwapResponse: { solverExecutionResponse, intent, intentDeliveryInfo }
-// Use `intentDeliveryInfo` for spoke / hub tx hashes; `solverExecutionResponse` for solver-side outcome.
-```
-
-### Create intent only (custom relay)
-
-```ts
-const result = await sodax.swaps.createIntent({
-  params: { /* … */ },
-  raw: false,
-  walletProvider: evmWp,
-});
-if (!result.ok) return;
-
-const { tx: spokeTxHash, intent, relayData } = result.value;
-//   tx is the spoke tx hash (TxReturnType<K, false>) for raw: false
-//   relayData is { payload: string }; submit relayData.payload to your backend
-```
-
-### Backend submit-tx flow
-
-```ts
-const submitResult = await sodax.backendApi.submitSwapTx({
-  txHash: spokeTxHash as string,
-  srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-  walletAddress: '0x…',
-  intent: /* SwapIntentData built from CreateIntentResult.value.intent */,
-  relayData: relayData.payload,   // string (not the object)
-});
-
-if (!submitResult.ok) {
-  // submitResult.error.code: 'EXTERNAL_API_ERROR' with context.api: 'backend'
-  return;
-}
-```
-
-### Raw-tx flow
-
-```ts
-const result = await sodax.swaps.createIntent({
-  params: { /* … */ },
-  raw: true,
-  // walletProvider is forbidden here
-});
-if (!result.ok) return;
-const { tx, intent, relayData } = result.value;
-// tx: chain-specific raw-tx payload (EvmRawTransaction, SolanaRawTransaction, …)
-```
-
-### Cancel intent
-
-```ts
-await sodax.swaps.cancelIntent({
-  params: { srcChainKey, intent /* the full Intent struct */ },
-  raw: false,
-  walletProvider: evmWp,
-});
-```
-
-## Return shapes
-
-| Method | Success type |
-|---|---|
-| `swap` | `SwapResponse` = `{ solverExecutionResponse, intent, intentDeliveryInfo }` |
-| `createIntent` | `CreateIntentResult<K, Raw>` = `{ tx: TxReturnType<K, Raw>, intent: Intent & FeeAmount, relayData: RelayExtraData }` |
-| `postExecution` | `SwapResponse` |
-| `createLimitOrder` / `createLimitOrderIntent` | Same as `createIntent` |
-| `cancelIntent` / `cancelLimitOrder` | `TxReturnType<K, Raw>` |
-| `approve` | `TxReturnType<K, Raw>` |
-| `isAllowanceValid` | `boolean` |
-
-`RelayExtraData`:
-
-```ts
-type RelayExtraData = {
-  payload: string;     // pass this string to backend submit-tx as `relayData`
-};
-```
-
-## Error codes
-
-`feature: 'swap'`. Per-method narrow unions:
-
-| Method | Codes |
-|---|---|
-| `createIntent`, `createLimitOrderIntent` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `UNKNOWN` |
-| `swap`, `createLimitOrder` | `VALIDATION_FAILED`, `INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `TX_VERIFICATION_FAILED`, `TX_SUBMIT_FAILED`, `RELAY_TIMEOUT`, `RELAY_FAILED`, `EXTERNAL_API_ERROR`, `UNKNOWN` |
-| `postExecution` | `EXECUTION_FAILED` (with `phase: 'postExecution'`), `EXTERNAL_API_ERROR` (with `api: 'solver'`), `UNKNOWN` |
-| `cancelIntent`, `cancelLimitOrder` | `VALIDATION_FAILED`, `EXECUTION_FAILED`, `UNKNOWN` |
-| `approve` | `VALIDATION_FAILED`, `APPROVE_FAILED`, `UNKNOWN` |
-| `isAllowanceValid` | `VALIDATION_FAILED`, `ALLOWANCE_CHECK_FAILED`, `UNKNOWN` |
-
-Solver-specific context on `EXTERNAL_API_ERROR`:
-
-- `error.context.api === 'solver'`
-- `error.context.solverCode` — the solver's own error code (e.g. `'INSUFFICIENT_LIQUIDITY'`)
-- `error.context.solverDetail` — the solver's human-readable message
-
-## Cross-references
-
-- v1 → v2 swap migration: [`../../migration/features/swap.md`](../../migration/features/swap.md).
-- Error model: [`../architecture.md`](../architecture.md) § 8 and [`../reference/`](../reference/) § 3.
-- Stellar destinations require a trustline first: [`../chain-specifics.md`](../chain-specifics.md) § "Stellar trustline".

package/ai-exported/integration/quickstart.md

@@ -1,213 +0,0 @@
-# Quickstart — `@sodax/sdk` v2
-
-Get a `Sodax` instance running in your project. This guide is **`@sodax/sdk`-only**: no other SODAX packages are imported. Where the SDK needs an `I*WalletProvider` instance, examples use a TypeScript `declare` placeholder so the surface stays Core-SDK-clean.
-
-## Section index
-
-1. [Installation](#1-installation)
-2. [TypeScript](#2-typescript)
-3. [The wallet-provider contract](#3-the-wallet-provider-contract)
-4. [Where to get wallet-provider implementations](#4-where-to-get-wallet-provider-implementations)
-5. [Construct + initialize](#5-construct--initialize)
-6. [Reads without a wallet](#6-reads-without-a-wallet)
-7. [Build raw transactions (no wallet)](#7-build-raw-transactions-no-wallet)
-8. [Calling methods that sign](#8-calling-methods-that-sign)
-9. [First-time troubleshooting](#9-first-time-troubleshooting)
-
----
-
-## 1. Installation
-
-```bash
-pnpm add @sodax/sdk
-# or
-npm install @sodax/sdk
-# or
-yarn add @sodax/sdk
-```
-
-**Don't add `@sodax/types` separately.** `@sodax/sdk` re-exports the entire types surface from its barrel. Adding `@sodax/types` as a direct dependency invites version skew on the next minor bump.
-
-## 2. TypeScript
-
-Targets Node 18+ and modern browsers. The package ships dual ESM (`.mjs`) + CJS (`.cjs`) + DTS, with `"type": "module"`. No additional TypeScript config needed — the package's `exports` field handles resolution for both `tsc` and `bundler` `moduleResolution` modes.
-
-If you're on `moduleResolution: 'node'` (legacy), upgrade to `'bundler'` or `'node16'` / `'nodenext'` — `'node'` doesn't read the `exports` field and will fall back to `main` / `module` (which still work, but you may see resolution warnings).
-
-## 3. The wallet-provider contract
-
-Methods that sign and broadcast take a `walletProvider` parameter typed as the chain-specific `I*WalletProvider` interface (`IEvmWalletProvider`, `ISolanaWalletProvider`, `ISuiWalletProvider`, `IStellarWalletProvider`, `IIconWalletProvider`, `IInjectiveWalletProvider`, `IStacksWalletProvider`, `INearWalletProvider`, `IBitcoinWalletProvider`). All nine interfaces are exported from `@sodax/sdk`.
-
-`@sodax/sdk` does **not** ship implementations of these interfaces. Read methods (`sodax.config.*`, `sodax.bridge.getBridgeableAmount`, `sodax.staking.getStakingConfig`, etc.) and `raw: true` flows do not require a `walletProvider`.
-
-## 4. Where to get wallet-provider implementations
-
-Two options:
-
-1. **Implement the interface yourself.** Each `I*WalletProvider` is a small set of methods (`getWalletAddress`, plus chain-specific signing / broadcasting). Wrap whatever wallet abstraction your app already owns (`viem`'s `WalletClient` for EVM, `@solana/web3.js` keypairs for Solana, `@stellar/stellar-sdk` for Stellar, etc.) in an object literal that satisfies the interface.
-2. **Use `@sodax/wallet-sdk-core`** — a separate SODAX package (not part of `@sodax/sdk`, not a transitive dependency — install it separately) that ships ready-made `I*WalletProvider` implementations for all 9 chain families with both private-key (Node / scripts) and browser-extension (dApp) modes. Refer to that package's own documentation for usage.
-
-Examples in this guide use TypeScript `declare const` placeholders so the surface stays Core-SDK-only — substitute your own object regardless of which option you chose.
-
-## 5. Construct + initialize
-
-```ts
-import { Sodax } from '@sodax/sdk';
-
-const sodax = new Sodax();
-await sodax.config.initialize();   // load fresh config from backend; falls back to packaged defaults
-
-// All feature services are wired and ready:
-//   sodax.swaps, sodax.moneyMarket, sodax.bridge, sodax.staking,
-//   sodax.dex, sodax.migration, sodax.partners, sodax.recovery,
-//   sodax.config, sodax.backendApi, sodax.hubProvider, sodax.spoke
-```
-
-`new Sodax()` accepts an optional `DeepPartial<SodaxConfig>` for custom RPC endpoints, solver / backend URLs, etc. — see [`recipes/`](recipes/) § "Initialize Sodax". `initialize()` is idempotent.
-
-## 6. Reads without a wallet
-
-Many SDK calls are pure reads — no wallet provider, no signing. They're the cheapest path to verifying an integration:
-
-```ts
-import { Sodax, ChainKeys } from '@sodax/sdk';
-
-const sodax = new Sodax();
-await sodax.config.initialize();
-
-// Config / token lookups
-const usdc = sodax.config.findSupportedTokenBySymbol(ChainKeys.ARBITRUM_MAINNET, 'USDC');
-const isValid = sodax.config.isValidSpokeChainKey(ChainKeys.ARBITRUM_MAINNET);
-
-// Money market
-const supplyTokens = sodax.moneyMarket.getSupportedTokensByChainId(ChainKeys.ARBITRUM_MAINNET);
-
-// Bridge
-const limit = await sodax.bridge.getBridgeableAmount(USDC_ARBITRUM, USDC_STELLAR);
-//   limit.value: BridgeLimit = { amount, decimals, type }
-
-// Staking (hub-only reads — no chain context needed)
-const stakingConfig = await sodax.staking.getStakingConfig();
-
-// DEX
-const pools = sodax.dex.clService.getPools();   // synchronous in v2
-```
-
-## 7. Build raw transactions (no wallet)
-
-For sign-elsewhere flows (gnosis safe, hardware wallet, custom multi-sig), use `raw: true`. The SDK builds the unsigned payload; your application signs and broadcasts:
-
-```ts
-import { Sodax, ChainKeys } from '@sodax/sdk';
-
-const sodax = new Sodax();
-await sodax.config.initialize();
-
-const result = await sodax.swaps.createIntent({
-  params: {
-    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-    dstChainKey: ChainKeys.STELLAR_MAINNET,
-    /* … rest of intent params */
-  },
-  raw: true,
-  // walletProvider is FORBIDDEN when raw: true — TypeScript rejects it.
-});
-
-if (!result.ok) {
-  console.error(result.error.toJSON());
-  return;
-}
-const { tx, intent, relayData } = result.value;
-// tx: chain-specific raw-tx payload (EvmRawTransaction, SolanaRawTransaction, …)
-// Sign and broadcast `tx` with whatever signer your application owns.
-```
-
-## 8. Calling methods that sign
-
-For signed flows, supply an `I*WalletProvider`. The example uses a TypeScript `declare` placeholder — at runtime, substitute an object your application owns (one you implemented to satisfy the interface, or one constructed via `@sodax/wallet-sdk-core`).
-
-```ts
-import { Sodax, ChainKeys, type IEvmWalletProvider } from '@sodax/sdk';
-
-declare const evmWallet: IEvmWalletProvider;
-//   ↑ At runtime, replace with your application's wallet-provider object.
-//     Any object that satisfies IEvmWalletProvider works.
-
-const sodax = new Sodax();
-await sodax.config.initialize();
-
-const result = await sodax.swaps.createIntent({
-  params: {
-    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-    dstChainKey: ChainKeys.STELLAR_MAINNET,
-    srcAddress: (await evmWallet.getWalletAddress()) as `0x${string}`,
-    /* … rest of intent params */
-  },
-  raw: false,
-  walletProvider: evmWallet,
-});
-
-if (!result.ok) {
-  console.error(result.error.toJSON());
-  return;
-}
-
-console.log('intent created:', result.value.tx);
-```
-
-The chain key on the payload (`ChainKeys.ARBITRUM_MAINNET`) is what TypeScript narrows the wallet-provider parameter against — passing a Solana wallet would be a compile-time error. See [`architecture.md`](architecture.md) § 6 for the `WalletProviderSlot<K, Raw>` mechanism.
-
-## 9. First-time troubleshooting
-
-The errors most likely to hit on a fresh install or first port.
-
-### "Cannot find module '@sodax/sdk' or its corresponding type declarations"
-
-- TypeScript `moduleResolution` is `'node'` (legacy). Switch to `'bundler'` or `'node16'`/`'nodenext'`.
-- Or: clear `node_modules` and reinstall. `@sodax/sdk` ships dual exports; resolution should be automatic.
-
-### "Module '\"@sodax/sdk\"' has no exported member 'SONIC_MAINNET_CHAIN_ID'"
-
-- v1 constant name. Use `ChainKeys.SONIC_MAINNET`. See [`../migration/breaking-changes/type-system.md`](../migration/breaking-changes/type-system.md) § 1.
-
-### "Object literal may only specify known properties, and 'walletProvider' does not exist in type ..."
-
-- Forgot `raw: false` (or `raw: true`) discriminator on the call. Add it. See [`architecture.md`](architecture.md) § 6.
-
-### "Property 'tx' does not exist on type 'SwapResponse'" or similar
-
-- You're treating the return as the success value directly instead of unpacking `result.value`. v2 returns `Promise<Result<T>>` — branch on `result.ok` first. See [`architecture.md`](architecture.md) § 7.
-
-### `sodax.config.findSupportedTokenBySymbol` returns `undefined`
-
-- `await sodax.config.initialize()` wasn't called. Add it after `new Sodax()`.
-
-### "Property 'xChainId' does not exist on type 'XToken'"
-
-- `XToken.xChainId` was renamed to `XToken.chainKey`. See [`../migration/breaking-changes/type-system.md`](../migration/breaking-changes/type-system.md) § 4.
-
-### "Type '{ token, amount, action }' does not satisfy the expected type 'MoneyMarketSupplyParams'"
-
-- Missing `srcChainKey` and `srcAddress` (required in v2). See [`features/money-market.md`](features/money-market.md).
-
-### "Argument of type 'string' is not assignable to parameter of type 'GetAddressType<K>'"
-
-- For EVM chains, `GetAddressType<K>` is `` `0x${string}` ``. Cast at the boundary: `(await walletProvider.getWalletAddress()) as \`0x${string}\``. See [`recipes/`](recipes/) § "Chain-key narrowing".
-
-### `sodax.config.initialize()` hangs / errors
-
-- The backend API is unreachable. The SDK should fall back to packaged defaults silently — check your network, then check that `SodaxConfig.backendApi.url` is correct (or omit it for the default).
-
-### Stellar bridge / swap fails with `'Trustline missing'`
-
-- Stellar destinations require a trustline for the destination asset before they can receive it. See [`chain-specifics.md`](chain-specifics.md) § "Stellar trustline".
-
----
-
-## Cross-references
-
-- v2 architecture: [`architecture.md`](architecture.md).
-- Recipes for common patterns: [`recipes/`](recipes/).
-- Per-feature usage: [`features/`](features/).
-- Lookup tables (chain keys, error codes, public API): [`reference/`](reference/).
-- v1 → v2 porting: [`../migration/README.md`](../migration/README.md).

package/ai-exported/integration/recipes/README.md

@@ -1,21 +0,0 @@
-# Recipes — `@sodax/sdk` v2
-
-Copy-pasteable patterns for the most common Core SDK consumer tasks. Each file is self-contained — drop the snippet into your code, swap in your specifics, done.
-
-| Recipe | When |
-|---|---|
-| [`initialize-sodax.md`](initialize-sodax.md) | App startup. `new Sodax()` + `await sodax.config.initialize()`, with and without config override. |
-| [`result-and-errors.md`](result-and-errors.md) | Branching on `result.ok`, switching on `(error.feature, error.code)`, `isSodaxError` over `instanceof`, sub-Result propagation, logger integration. |
-| [`signed-tx-flow.md`](signed-tx-flow.md) | `raw: false` + chain-narrowed `walletProvider`. Returns tx hash (or `TxHashPair` for cross-chain mutations). |
-| [`raw-tx-flow.md`](raw-tx-flow.md) | `raw: true`. Builds an unsigned chain-specific payload; you sign elsewhere. |
-| [`chain-key-narrowing.md`](chain-key-narrowing.md) | Cast-at-boundary pattern; runtime `chainType` discriminant. |
-| [`testing.md`](testing.md) | Mocking the `Sodax` instance, stubbing the relay layer, `Result<T>` assertions. |
-| [`gas-estimation.md`](gas-estimation.md) | Pre-flight gas estimation for raw-tx flows. |
-| [`backend-server-init.md`](backend-server-init.md) | Node script / bot / partner backend pattern with `declare const` wallet placeholders. |
-
-## Cross-references
-
-- v2 architectural concepts: [`../architecture.md`](../architecture.md).
-- Lookup tables (chain keys, error codes, public API): [`../reference/`](../reference/).
-- DO / DO NOT / workflow: [`../ai-rules.md`](../ai-rules.md).
-- v1 → v2 migration: [`../../migration/recipes.md`](../../migration/recipes.md).

package/ai-exported/integration/recipes/backend-server-init.md

@@ -1,69 +0,0 @@
-# Backend-server initialization (private-key)
-
-Node script / bot / partner backend pattern. The `Sodax` instance holds no wallet itself — your application owns the `I*WalletProvider` object and passes it into each call.
-
-```ts
-import { Sodax, ChainKeys, type IEvmWalletProvider, type SpokeChainKey } from '@sodax/sdk';
-
-declare const evmWallet: IEvmWalletProvider;
-//   ↑ Your application's wallet-provider object. Implement IEvmWalletProvider yourself,
-//     or install `@sodax/wallet-sdk-core` (separate package) which ships an `EvmWalletProvider`
-//     class you can construct with `{ privateKey, rpcUrl }`.
-
-const sodax = new Sodax({
-  rpcConfig: {
-    [ChainKeys.ARBITRUM_MAINNET]: process.env.ARBITRUM_RPC_URL!,
-    [ChainKeys.SONIC_MAINNET]: process.env.SONIC_RPC_URL!,
-    // …
-  },
-});
-await sodax.config.initialize();
-
-const result = await sodax.swaps.createIntent({
-  params: {
-    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
-    dstChainKey: ChainKeys.STELLAR_MAINNET,
-    srcAddress: (await evmWallet.getWalletAddress()) as `0x${string}`,
-    /* … */
-  },
-  raw: false,
-  walletProvider: evmWallet,
-});
-```
-
-### Multi-chain bots
-
-If your bot operates on multiple source chains, hold one wallet provider per chain family and pick the right one at call time:
-
-```ts
-declare const wallets: {
-  readonly [ChainKeys.ARBITRUM_MAINNET]: IEvmWalletProvider;
-  readonly [ChainKeys.SONIC_MAINNET]: IEvmWalletProvider;
-  readonly [ChainKeys.SOLANA_MAINNET]: ISolanaWalletProvider;
-};
-
-function getWallet(chainKey: SpokeChainKey) {
-  const wp = wallets[chainKey as keyof typeof wallets];
-  if (!wp) throw new Error(`No wallet configured for ${chainKey}`);
-  return wp;
-}
-
-await sodax.swaps.createIntent({
-  params: { srcChainKey: ChainKeys.ARBITRUM_MAINNET, /* … */ },
-  raw: false,
-  walletProvider: getWallet(ChainKeys.ARBITRUM_MAINNET),
-});
-```
-
-### Pitfall
-
-Hold one wallet-provider instance per chain family for the lifetime of your process; don't recreate them per request. Implementations typically own an RPC client connection that's expensive to set up.
-
----
-
-
-## Cross-references
-
-- [`README.md`](README.md) — recipe index.
-- [`../architecture.md`](../architecture.md) — concepts behind these patterns.
-- [`../reference/`](../reference/) — chain keys, error codes, public API surface.