@sodax/skills 2.0.0-rc.10

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

@@ -0,0 +1,273 @@
+# 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.getQuote(payload: SolverIntentQuoteRequest): Promise<Result<SolverIntentQuoteResponse, SolverErrorResponse>>;
+//   Preview the output amount before signing — useful for UX confirmations / bot previews.
+
+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
+
+### Quote before signing (preview / confirmation UX)
+
+`getQuote` is a read-only call to the solver — no wallet, no signing. Use it for trading-bot previews, UI confirmations, or to set `minOutputAmount` based on a fresh quote.
+
+```ts
+const quote = await sodax.swaps.getQuote({
+  token_src: USDC_ARBITRUM.address,
+  token_src_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
+  token_dst: XLM.address,
+  token_dst_blockchain_id: ChainKeys.STELLAR_MAINNET,
+  amount: 1_000_000n,        // 1 USDC (6 decimals)
+  quote_type: 'exact_input', // currently the only supported type
+});
+
+if (!quote.ok) {
+  // quote.error: SolverErrorResponse — different shape from SodaxError;
+  // see `error.detail.code` and `error.detail.message`.
+  return;
+}
+
+const { quoted_amount } = quote.value;   // bigint output amount in dst-token units
+// Use `quoted_amount` (with a slippage buffer) as `minOutputAmount` on the swap call.
+```
+
+`SolverIntentQuoteRequest` uses snake_case fields and **`token_src`/`token_dst` are token addresses** (strings), not full `XToken` objects. `quote_type` is currently `'exact_input'` only.
+
+### Signed swap (full flow)
+
+`inputToken` / `outputToken` are full `XToken` objects (with `chainKey`, `address`, `decimals`, `symbol`). Look them up from config — do **not** hand-construct:
+
+```ts
+const inputToken  = sodax.config.findSupportedTokenBySymbol(ChainKeys.ARBITRUM_MAINNET, 'USDC');
+const outputToken = sodax.config.findSupportedTokenBySymbol(ChainKeys.STELLAR_MAINNET,  'XLM');
+if (!inputToken || !outputToken) throw new Error('Token missing from config — did you call sodax.config.initialize()?');
+
+const result = await sodax.swaps.swap({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    dstChainKey: ChainKeys.STELLAR_MAINNET,
+    srcAddress: '0x…',
+    dstAddress: 'G…',
+    inputToken,                                     // XToken; chainKey === srcChainKey
+    outputToken,                                    // XToken; chainKey === dstChainKey
+    inputAmount: parseUnits('1', inputToken.decimals),   // 1 USDC
+    minOutputAmount: parseUnits('50', outputToken.decimals), // 50 XLM floor
+    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.
+```
+
+### Hub as source (Sonic → spoke)
+
+`srcChainKey` accepts `ChainKeys.SONIC_MAINNET` too — same `WalletProviderSlot<K, Raw>` shape, same `Result<T>` return. The SDK routes through the user's hub-wallet abstraction instead of a spoke deposit. The token lookup pattern is identical; 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');
+
+const result = await sodax.swaps.swap({
+  params: {
+    srcChainKey: ChainKeys.SONIC_MAINNET,
+    dstChainKey: ChainKeys.BASE_MAINNET,
+    srcAddress: (await evmWp.getWalletAddress()) as `0x${string}`,
+    dstAddress: recipientOnBase,
+    inputToken: sodaSonic,
+    outputToken: sodaBase,
+    inputAmount: parseUnits('1', sodaSonic.decimals),
+    minOutputAmount: parseUnits('0.99', sodaBase.decimals),   // tighten with getQuote() in production
+    deadline: BigInt(Math.floor(Date.now() / 1000) + 300),
+    allowPartialFill: false,
+    solver: '0x0000000000000000000000000000000000000000',
+    data: '0x',
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+If both `srcChainKey` and `dstChainKey` are spoke chains that share a vault for the token, prefer [`sodax.bridge.bridge`](bridge.md) — it skips the solver and tends to be cheaper. Use `swap` when no vault pair exists or when a solver-routed price improves the 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: [`features/swap.md`](../../../migration-v1-to-v2/knowledge/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/skills/sodax-sdk/integration/knowledge/quickstart.md

@@ -0,0 +1,213 @@
+# 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 20.12+ 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 [`breaking-changes/type-system.md`](../../migration-v1-to-v2/knowledge/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 [`breaking-changes/type-system.md`](../../migration-v1-to-v2/knowledge/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.api.baseURL` 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: [`README.md`](../../migration-v1-to-v2/knowledge/README.md).

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

@@ -0,0 +1,21 @@
+# 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: [`recipes.md`](../../../migration-v1-to-v2/knowledge/recipes.md).

package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md

@@ -0,0 +1,69 @@
+# 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.

package/skills/sodax-sdk/integration/knowledge/recipes/chain-key-narrowing.md

@@ -0,0 +1,65 @@
+# Chain-key narrowing (cast-at-boundary)
+
+When you have a runtime chain key (e.g. user-selected from a UI) and need a chain-narrowed wallet provider, narrow once at the boundary and let the narrowed binding flow downstream.
+
+### Narrowing inside a feature flow
+
+```ts
+import { ChainKeys, type GetWalletProviderType } from '@sodax/sdk';
+
+function isStellar(chainKey: SpokeChainKey): chainKey is typeof ChainKeys.STELLAR_MAINNET {
+  return chainKey === ChainKeys.STELLAR_MAINNET;
+}
+
+const stellarWp = isStellar(srcChainKey)
+  ? (walletProvider as GetWalletProviderType<typeof ChainKeys.STELLAR_MAINNET> | undefined)
+  : undefined;
+
+if (stellarWp) {
+  await checkStellarTrustline({ token, amount, walletProvider: stellarWp });
+}
+```
+
+The cast is local — the `isStellar` guard proves correctness at runtime. **Don't propagate the cast** beyond the narrowed binding; downstream code reads `stellarWp` as the chain-specific type without further casts.
+
+### The `chainType` runtime alternative
+
+Every `I*WalletProvider` has a `readonly chainType: '<CHAIN>'` literal. Use it when you don't have the chain key in scope but do have a wallet provider:
+
+```ts
+if (walletProvider.chainType === 'BITCOIN') {
+  // walletProvider: IBitcoinWalletProvider
+  await checkBitcoinPSBT(walletProvider);
+}
+```
+
+No `as` cast needed — `chainType` is part of the interface.
+
+### Pitfall
+
+Do **not** chain a cast through every helper. The cast belongs at the chain-key guard. Anywhere downstream of the guard, the binding is already typed correctly:
+
+```ts
+// Bad — chained casts:
+async function approveSomething(wp: IWalletProvider) {
+  await sodax.swaps.approve({
+    params,
+    walletProvider: wp as GetWalletProviderType<typeof ChainKeys.BITCOIN_MAINNET>,
+    raw: false,
+  });
+}
+
+// Good — one cast at the boundary, narrowed binding flows:
+const btcWp = isBitcoin(srcChainKey)
+  ? (walletProvider as GetWalletProviderType<typeof ChainKeys.BITCOIN_MAINNET>)
+  : null;
+if (btcWp) await sodax.swaps.approve({ params, walletProvider: btcWp, raw: false });
+```
+
+---
+
+## 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.

package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md

@@ -0,0 +1,33 @@
+# Gas estimation
+
+Pre-flight gas estimation for raw-tx flows. Most signed flows include gas estimation internally; you only need this when building unsigned payloads.
+
+```ts
+const result = await sodax.swaps.estimateGas({
+  params: { /* same as createIntent params */ },
+});
+
+if (!result.ok) {
+  // result.error: SodaxError<'VALIDATION_FAILED' | 'GAS_ESTIMATION_FAILED' | 'UNKNOWN'>
+  if (result.error.code === 'GAS_ESTIMATION_FAILED') {
+    // Retry — gas estimation failures are usually transient.
+  }
+  return;
+}
+
+const { gasLimit, gasPrice } = result.value;
+```
+
+`estimateGas` returns chain-family-specific shapes — EVM gas params, Solana compute units, etc. See per-feature docs in [`../features/`](../features/) for specifics.
+
+### Distinct from `LOOKUP_FAILED`
+
+The SDK keeps `GAS_ESTIMATION_FAILED` as its own code (rather than folding into `LOOKUP_FAILED`) because retry semantics differ. Re-estimation is cheap and almost always the right move on transient failure. Generic `LOOKUP_FAILED` errors typically need user intervention.
+
+---
+
+## 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.