@sodax/skills 2.0.0-rc.10

package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md

@@ -0,0 +1,145 @@
+# `SodaxConfig` constructor reshape
+
+The v2 `Sodax` constructor accepts a `DeepPartial<SodaxConfig>`. Several config fields renamed, moved, or were added between v1 and v2; if your project passed a custom config, check these.
+
+## v2 `SodaxConfig` shape (source of truth)
+
+Defined in `@sodax/types` (`packages/types/src/sodax-config/sodax-config.ts`):
+
+```ts
+type SodaxConfig = {
+  fee: PartnerFee | undefined;                       // global partner fee (overridable per-feature)
+  chains: Record<SpokeChainKey, SpokeChainConfig>;   // per-spoke-chain config (rpcUrl + tx polling + chain-specific shape)
+  swaps: SwapsConfig;                                // supported swap tokens per chain
+  moneyMarket: MoneyMarketConfig;                    // money market service config
+  bridge: BridgeConfig;                              // bridge partner-fee override
+  dex: DexConfig;                                    // DEX service config
+  hub: HubConfig;                                    // hub-chain (Sonic) provider config
+  api: ApiConfig;                                    // backend API endpoint
+  solver: SolverConfig;                              // intent solver endpoint + contracts
+  relay: RelayConfig;                                // intent-relay endpoint
+};
+```
+
+A matching default `sodaxConfig` const is exported from the same module — `new Sodax()` deep-merges your `DeepPartial<SodaxConfig>` over it.
+
+## v1 shape (for reference)
+
+```ts
+// v1 — packages/sdk/src/shared/entities/Sodax.ts
+type SodaxConfig = {
+  swaps?: SolverConfigParams;                    // { intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }
+  moneyMarket?: MoneyMarketConfigParams;
+  migration?: MigrationServiceConfig;
+  bridge?: BridgeServiceConfig;
+  dex?: DexServiceConfig;
+  hubProviderConfig?: EvmHubProviderConfig;      // { hubRpcUrl, chainConfig }
+  relayerApiEndpoint?: HttpUrl;                  // single URL string
+  backendApiConfig?: BackendApiConfig;
+  partners?: PartnerServiceConfig;
+  sharedConfig?: typeof defaultSharedConfig;
+};
+```
+
+All v1 fields were **optional**. v1 had **no** top-level `rpcConfig` on `SodaxConfig` — RPC URLs were a separate prop accepted by the framework-layer `SodaxProvider` (alongside the `config` prop carrying `SodaxConfig`); the `Sodax` class constructor itself never received `rpcConfig`.
+
+## v1 → v2 field map
+
+| v1 location | v2 location | Notes |
+|---|---|---|
+| `SodaxConfig.swaps` (`SolverConfigParams` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract?, partnerFee? }`) | **Split into two:** `SodaxConfig.solver: SolverConfig` (`{ intentsContract, solverApiEndpoint, protocolIntentsContract }`) and `SodaxConfig.swaps: SwapsConfig` (supported tokens per chain — new in v2). | v1 partner-fee inside `SolverConfigParams` moves to the global `SodaxConfig.fee` slot or per-feature configs. |
+| `SodaxConfig.hubProviderConfig` (`EvmHubProviderConfig` — `{ hubRpcUrl, chainConfig }`) | **`SodaxConfig.hub`** (`HubConfig` — full hub addresses + native token + bnUSD + polling + RPC URL). | Field renamed `hubProviderConfig` → `hub`. Shape expanded: v1 just had RPC URL + chain config; v2 ships the full hub-contract address map. |
+| `SodaxConfig.moneyMarket` (`MoneyMarketConfigParams`) | `SodaxConfig.moneyMarket` (`MoneyMarketConfig` — required, shape changed). | Reshape, see `@sodax/types/src/common/common.ts` MoneyMarketConfig. |
+| `SodaxConfig.bridge` (`BridgeServiceConfig`) | `SodaxConfig.bridge` (`BridgeConfig` — `{ partnerFee }`). | Reshape; smaller. |
+| `SodaxConfig.dex` (`DexServiceConfig`) | `SodaxConfig.dex` (`DexConfig`). | Reshape. |
+| `SodaxConfig.relayerApiEndpoint: HttpUrl` (string) | **`SodaxConfig.relay`** (`RelayConfig` — object with relayer URL + chain-id map). | Renamed + reshaped from string to object. |
+| `SodaxConfig.backendApiConfig` (`BackendApiConfig`) | **`SodaxConfig.api`** (`ApiConfig`). | Renamed. |
+| (Separate `rpcConfig` prop on the framework-layer SodaxProvider, NOT a `SodaxConfig` field) | **`SodaxConfig.chains`** (`Record<SpokeChainKey, SpokeChainConfig>`). | v2 absorbs RPC URLs + polling + chain-specific extras into the `SodaxConfig.chains` mapped type. v1's separate `rpcConfig` provider prop is gone. The standalone `RpcConfig` type still ships from `@sodax/types` for utility use (e.g. the demo's `providers.tsx` declares a local `RpcConfig` then maps values into `chains`), but it is not a `SodaxConfig` field. |
+| `SodaxConfig.migration` (`MigrationServiceConfig`) | **Removed.** Migration service runs with hard-coded defaults. | No replacement on `SodaxConfig`. v2 surfaces customization via per-method params on `sodax.migration.*`, not constructor config — see [`../features/migration.md`](../features/migration.md). |
+| `SodaxConfig.partners` (`PartnerServiceConfig`) | **Removed.** Partner service runs with defaults. | Per-claim partner-fee config now flows via call-level params on `sodax.partners.*` methods. |
+| `SodaxConfig.sharedConfig` (`typeof defaultSharedConfig`) | **Removed.** | Absorbed into `ConfigService` + per-chain `SpokeChainConfig`. Override individual chains via `SodaxConfig.chains[key]`. |
+| (none in v1) | **`SodaxConfig.fee: PartnerFee \| undefined`** (new). | Global partner-fee, applies to all features unless overridden by feature-level config (`bridge.partnerFee`, money market, etc.). |
+| (v1 had no top-level `configService` injection slot on `SodaxConfig` — `ConfigService` was always constructed internally from `backendApiConfig` + `sharedConfig`.) | Same — `ConfigService` is internal. v2 does **not** expose a typed slot to inject a custom `IConfigApi` either. To swap the backend in tests, point `SodaxConfig.api.baseURL` at a mock server. | See Pitfall below. |
+
+Migration:
+
+```diff
+- // v1 — typical SodaxConfig literal
+- const sodaxConfig = {
+-   hubProviderConfig: { hubRpcUrl: 'https://…', chainConfig: getHubChainConfig() },
+-   moneyMarket: getMoneyMarketConfig(hubChainId),
+-   swaps: {
+-     intentsContract: '0x…',
+-     solverApiEndpoint: 'https://…',
+-     protocolIntentsContract: '0x…',
+-     partnerFee: { address: '0x…', percentage: 10 },
+-   },
+-   relayerApiEndpoint: 'https://relay.example.com',
+- } satisfies SodaxConfig;
+- // RPC URLs were passed as a SEPARATE prop on the framework-layer SodaxProvider
+- // (alongside the sodaxConfig). The Sodax constructor itself never saw rpcConfig.
+
++ // v2 — DeepPartial<SodaxConfig> passed directly to new Sodax(...)
++ const sodax = new Sodax({
++   hub: { /* HubConfig — usually omit, default ships full hub addresses */ },
++   solver: {
++     intentsContract: '0x…',
++     solverApiEndpoint: 'https://…',
++     protocolIntentsContract: '0x…',
++   },
++   swaps: {
++     supportedTokens: { /* per-chain table */ },
++   },
++   relay: { /* RelayConfig — relayer URL + chain-id map */ },
++   fee: { address: '0x…', percentage: 10 },  // global partner fee (moved out of swaps)
++   chains: {
++     [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://…' },
++     [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://…' },
++     [ChainKeys.BITCOIN_MAINNET]: { /* BitcoinSpokeChainConfig shape */ },
++     // …
++   },
++ });
++ await sodax.config.initialize();
+```
+
+## Per-chain `SpokeChainConfig` shape
+
+`SodaxConfig.chains` is keyed by `SpokeChainKey`; each entry's value type varies by chain family. The user-overridable surface (`rpcUrl`, polling config, chain-specific extras) is the same set of fields `RpcConfig` covers in v1, but nested inside `SpokeChainConfig` rather than flat. Inspect the type at:
+
+- `packages/types/src/chains/chains.ts` — `SpokeChainConfig` discriminated union
+- `packages/types/src/common/common.ts` — `BitcoinRpcConfig`, `StellarRpcConfig`, `InjectiveRpcConfig` (used inside the EVM-non-EVM branches)
+
+See [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 5 for the chain-family-specific entry shapes.
+
+### Pitfall
+
+If you previously injected a custom `ConfigService` for testing (a v1 escape hatch), v2 doesn't accept one at the top level — and unlike what earlier doc versions claimed, **v2 also doesn't expose a typed slot to inject a custom `IConfigApi`**. The realistic options:
+
+- Point `SodaxConfig.api.baseURL` at a local mock backend server.
+- Construct your own `BackendApiService`-compatible object in your app/test bootstrap and swap it in where you control the `Sodax` instance.
+
+The `SodaxConfig.api` field is `ApiConfig` (`{ baseURL, timeout, headers }`) — there is no `api.api` sub-field for IConfigApi injection.
+
+### Pitfall — module-scope reads
+
+If your code reads hub addresses or default configs **before** the `Sodax` instance exists (module-scope constants), use the re-exported defaults from `@sodax/types` (also flow through `@sodax/sdk` since it re-exports the entire types surface):
+
+```ts
+import { hubConfig, sodaxConfig } from '@sodax/sdk';
+
+const HUB_WALLET = hubConfig.addresses.hubWallet;     // module-scope OK
+const DEFAULT_RELAY = sodaxConfig.relay;              // module-scope OK
+```
+
+`hubConfig` / `sodaxConfig` are the **packaged defaults** — the same values `ConfigService` falls back to if the backend is unreachable. Once you have a `Sodax` instance, prefer `sodax.config.getHubChainConfig()` / `sodax.config.*` so backend-driven updates take effect.
+
+---
+
+
+## Cross-references
+
+- [`README.md`](README.md) — migration reference index.
+- [`../README.md`](../README.md) — migration overview.
+- [`../checklist.md`](../checklist.md) — top-level migration checklist.
+- [`../breaking-changes/type-system.md`](../breaking-changes/type-system.md) § 5 — per-chain config entry shapes.
+- [`deleted-exports.md`](deleted-exports.md) — `getHubChainConfig()` and other deleted symbols.

package/skills/sodax-sdk/money-market/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sodax-sdk-money-market
+description: 'Granular skill for the @sodax/sdk v2 money-market feature only — cross-chain lending and borrowing (supply, borrow, withdraw, repay) and per-position reads. Use when the consumer task is specifically money-market (e.g. "supply on Sodax", "borrow against my position", "Sodax lending", "withdraw collateral", "repay debt", "cross-chain borrow"). Covers BOTH integration (write new v2 code) and migration (port v1 MoneyMarketService to v2). Skill links into the parent sodax-sdk knowledge tree — does NOT duplicate it. For React dapps, prefer the sodax-dapp-kit skill.'
+---
+
+# Money Market (Core SDK granular skill)
+
+Granular skill for the lending/borrowing feature of `@sodax/sdk` v2. Access via `sodax.moneyMarket`. Feature tag for errors: `'moneyMarket'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?** `supply`, `borrow`, `withdraw`, `repay`, or just position reads.
+3. **Same-chain or cross-chain borrow?** `borrow` can deliver funds back to the source chain or to a different spoke chain.
+4. **Signed flow or unsigned-tx (`createXxxIntent`)?**
+5. **Need user-position reads** (aToken balance, reserves data, formatted summaries)? Those come from `sodax.backendApi`, not `MoneyMarketService` — load [`../backend-api/SKILL.md`](../backend-api/SKILL.md) alongside.
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT.
+2. [`../integration/knowledge/features/money-market.md`](../integration/knowledge/features/money-market.md) — `MoneyMarketService` API, action params, hub-asset / aToken mapping.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Backend / unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Gas estimation before action methods → [`../integration/knowledge/recipes/gas-estimation.md`](../integration/knowledge/recipes/gas-estimation.md).
+5. Errors (`feature: 'moneyMarket'`) → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+6. Reading user position → load [`../backend-api/SKILL.md`](../backend-api/SKILL.md) for `BackendApiService.getMoneyMarketPosition`, `getAllMoneyMarketAssets`, etc.
+
+### Money-market-specific anti-patterns
+
+- **Confusing `token` (hub asset address) with the spoke-chain token address.** `MoneyMarketParams<K>.token` is the hub asset (a `0x...` address on Sonic), not the user's spoke-chain ERC20.
+- **Skipping allowance check before `supply` / `repay`.** Use `isAllowanceValid` then `approve` with the action-discriminated args.
+- **Calling reserve-data reads on `MoneyMarketService`.** Those live on `sodax.backendApi`.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/money-market.md`](../migration-v1-to-v2/knowledge/features/money-market.md) — v1 `MoneyMarketError` → v2 `SodaxError<C>` with `feature: 'moneyMarket'`.
+3. Add `srcChainKey` + `srcAddress` to every action params object — these were not in v1 shapes.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.moneyMarket.<method>(...)` has `if (!result.ok)` branching.
+3. `instanceof MoneyMarketError` → `isSodaxError(e) && e.feature === 'moneyMarket'`.
+
+## Related granular skills (same family)
+
+- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — reads (`BackendApiService`) for user position, asset metadata, suppliers/borrowers lists.
+- [`../swap/SKILL.md`](../swap/SKILL.md) — when supplying collateral that requires an upstream swap.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/partner/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: sodax-sdk-partner
+description: 'Granular skill for the @sodax/sdk v2 partner-fee feature only — `PartnerService` (operations on `sodax.partners.feeClaim`). Token approval on the hub, auto-swap preferences, immediate fee-claim swap, intent-driven auto-swap, asset-balance reads. Use when the task is partner-fee work (e.g. "claim partner fee", "configure partner auto-swap preference", "approve partner fee token on Sodax hub", "Sodax PartnerService"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# Partner (Core SDK granular skill)
+
+Granular skill for `PartnerService` — `sodax.partners`. Operations live on `sodax.partners.feeClaim` (the parent only exposes `feeClaim` and `config`). Feature tag for errors: `'partner'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?**
+   - One-time setup: `isTokenApproved` → `approveToken` → `setSwapPreference`.
+   - Recurring: `swap` (immediate) or `createIntentAutoSwap` (intent-driven auto-swap).
+   - Reads: `getAutoSwapPreferences`, `fetchAssetsBalances`.
+3. **Signed flow or unsigned-tx?**
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/partner.md`](../integration/knowledge/features/partner.md) — `PartnerService` API, common call shape (approve → preference → swap).
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'partner'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Partner-specific anti-patterns
+
+- **Calling `sodax.partners.claimFees(...)`.** Method doesn't exist on `sodax.partners` directly — all fee-claim operations live on `sodax.partners.feeClaim`.
+- **Skipping the `isTokenApproved` check before fee claim.** The partner's fee token must be approved on the hub once; subsequent claims reuse the allowance.
+- **Forgetting to `setSwapPreference`.** Without an auto-swap preference, partner-collected fees stay in the original asset.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/partner.md`](../migration-v1-to-v2/knowledge/features/partner.md) — drop `spokeProvider`, add `walletProvider`, `srcChainKey`, `srcAddress`. All 5 v1 typed errors collapse into `SodaxError<C>` with `feature: 'partner'`.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.partners.feeClaim.<method>(...)` has `if (!result.ok)`.
+3. No `instanceof PartnerFeeClaimError` (or the 4 sibling v1 error classes).
+
+## Related granular skills (same family)
+
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — partner-collected funds stuck on the hub.
+- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — backend HTTP client for tracking partner-claim intents.
+- [`../swap/SKILL.md`](../swap/SKILL.md) — partner-fee `swap` and `createIntentAutoSwap` reuse the swap intent layer.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/recovery/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sodax-sdk-recovery
+description: 'Granular skill for the @sodax/sdk v2 recovery feature only — `RecoveryService` for withdrawing stuck hub-wallet assets back to a spoke chain. Use when the task is recovering assets stranded on the hub after a failed cross-chain operation (e.g. "recover stuck assets on Sonic", "Sodax RecoveryService", "fetchHubAssetBalances", "withdrawHubAsset", "stuck-asset withdrawal"). Service is NEW in v2 (no v1 equivalent). Covers BOTH integration and the v2-only migration note. Skill links into the parent sodax-sdk knowledge tree.'
+---
+
+# Recovery (Core SDK granular skill)
+
+Granular skill for `RecoveryService` — `sodax.recovery`. Feature tag for errors: `'recovery'`. Service is **new in v2** — no v1 equivalent.
+
+## Step 1 — Clarify with user before coding
+
+1. **What's the trigger?** Recovery should follow a *known* failed cross-chain operation. If the user can't name the failure, investigate the original op first.
+2. **Which operation?**
+   - `fetchHubAssetBalances` (read; list stuck hub assets for the user).
+   - `withdrawHubAsset` (mutation; withdraw one entry back to a chosen spoke chain).
+3. **Signed flow or unsigned-tx?** `withdrawHubAsset` follows the same `WalletProviderSlot<K, Raw>` pattern as other mutations.
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/recovery.md`](../integration/knowledge/features/recovery.md) — `RecoveryService` API + when-to-use guidance.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'recovery'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Recovery-specific anti-patterns
+
+- **Treating recovery as a routine flow.** It's a workaround for failures; calling it on successfully completed flows wastes gas and confuses users.
+- **Skipping the balance read.** `fetchHubAssetBalances` returns the full set of hub assets for a user; pick the one to withdraw rather than guessing the address.
+- **Ignoring the underlying failure.** Recovery moves the asset but doesn't explain why the original op failed — investigate first (relay timeout? bad params? destination chain issue?).
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/recovery.md`](../migration-v1-to-v2/knowledge/features/recovery.md) — service is new in v2; no port to do. If you have v1 workaround code that walked the hub wallet abstraction manually, replace it with `fetchHubAssetBalances` + `withdrawHubAsset`.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.recovery.<method>(...)` has `if (!result.ok)`.
+3. Any v1 ad-hoc "find stuck assets" workaround code is removed.
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md), [`../bridge/SKILL.md`](../bridge/SKILL.md), [`../money-market/SKILL.md`](../money-market/SKILL.md), etc. — the upstream features whose failures may strand assets.
+- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — intent / tx lookups to diagnose the original failure before recovering.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/staking/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sodax-sdk-staking
+description: 'Granular skill for the @sodax/sdk v2 staking feature only — SODA ↔ xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel unstake. Use when the task is staking (e.g. "stake SODA", "unstake xSoda", "claim Sodax staking rewards", "instant unstake with penalty", "cancel pending unstake", "get staking info from spoke"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# Staking (Core SDK granular skill)
+
+Granular skill for `StakingService` — `sodax.staking`. Feature tag: `'staking'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?** `stake`, `unstake`, `instantUnstake` (penalty), `claim`, `cancelUnstake`.
+3. **Cross-chain** (staking from a spoke chain) **or hub-side** (Sonic)? Staking from a spoke routes through the relay.
+4. **Need user staking info?**
+   - From a **spoke** address (most consumer code): `getStakingInfoFromSpoke(srcAddress, srcChainKey)` — resolves spoke → hub then reads.
+   - From a **hub** address directly (already on Sonic): `getStakingInfo(hubAddress)`. Both are public reads on `StakingService`.
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/staking.md`](../integration/knowledge/features/staking.md) — `StakingService` API, penalty curve, instant-unstake slippage, claim flow.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'staking'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Staking-specific anti-patterns
+
+- **Passing a spoke address to `getStakingInfo`.** It expects a hub address. Use `getStakingInfoFromSpoke(srcAddress, srcChainKey)` if you only have the spoke address — it derives the hub wallet internally.
+- **Forgetting allowance before `stake`.** Like other action services, requires `approve` + `isAllowanceValid` flow.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/staking.md`](../migration-v1-to-v2/knowledge/features/staking.md) — v1 `StakingError` → v2 `SodaxError<C>` with `feature: 'staking'`. If v1 code passed a spoke address into `getStakingInfo`, switch to `getStakingInfoFromSpoke(srcAddress, srcChainKey)` instead (v2 added it as the spoke-side wrapper; the hub-side `getStakingInfo(hubAddress)` is still public).
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.staking.<method>(...)` has `if (!result.ok)`.
+3. `getStakingInfo` call sites pass a hub address (not a spoke address); spoke-side reads use `getStakingInfoFromSpoke`.
+
+## Related granular skills (same family)
+
+- [`../migration/SKILL.md`](../migration/SKILL.md) — BALN → SODA migration also stakes (lockup periods 0–24 months); use it for BALN-specific lock flows.
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — recovery for stuck staking-related assets.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/swap/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sodax-sdk-swap
+description: 'Granular skill for the @sodax/sdk v2 swap feature only — intent-based swaps via solver (market orders + limit orders) and cancel/approve flows. Use when the consumer has decided the task is a swap (e.g. "swap with Sodax", "Sodax intent swap", "limit order on Sodax", "cross-chain swap via Sonic", "cancel a Sodax intent") and you want to skip loading the broad sodax-sdk skill. Covers BOTH integration (write new v2 swap code) and migration (port v1 swap to v2) — picks via Step 1 question. Skill is intentionally short and links into the parent sodax-sdk knowledge tree (../integration/knowledge/, ../migration-v1-to-v2/knowledge/) for full reference. For React dapps doing swaps, prefer the sodax-dapp-kit skill instead.'
+---
+
+# Swap (Core SDK granular skill)
+
+Granular skill for the swap feature of `@sodax/sdk` v2. Source-of-truth reference lives in the parent broad skill's knowledge tree — this file is the focused workflow only.
+
+## Step 1 — Clarify with user before coding
+
+Swap has materially different code paths depending on the answers. Don't skip:
+
+1. **Are you writing new code, or porting v1 code to v2?**
+   - New code → § Integration workflow below.
+   - Port v1 → v2 → § Migration workflow.
+2. **Signed flow (frontend wallet, browser/RN) or unsigned-tx flow (backend / custom relay)?**
+   - Signed → `raw: false` + `walletProvider`.
+   - Unsigned → `raw: true`, you handle relay yourself.
+3. **One-shot `swap()` or step-by-step (`createIntent` → backend submit → `postExecution`)?**
+   - One-shot is the default for frontends. Step-by-step is for backends that already have a relay/orchestration layer.
+4. **Market order or limit order?** Limit orders use a different params shape (no `deadline`).
+
+## Integration workflow (writing new v2 swap code)
+
+Read in order. Skipping `ai-rules.md` is the most common cause of agents reverting to v1 patterns.
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT list.
+2. [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) — `SwapService` API surface, action params, return shapes, error codes (`feature: 'swap'`).
+3. Path-specific recipe:
+   - Signed one-shot → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Backend step-by-step → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md) + [`../integration/knowledge/recipes/backend-server-init.md`](../integration/knowledge/recipes/backend-server-init.md)
+4. Error handling for swap-specific codes (`INTENT_CREATION_FAILED`, `EXECUTION_FAILED`, `RELAY_TIMEOUT`, solver-side `EXTERNAL_API_ERROR`) → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+5. Cross-chain destination quirks (Stellar trustline, BTC PSBT, Solana PDA) → [`../integration/knowledge/chain-specifics.md`](../integration/knowledge/chain-specifics.md).
+
+### Swap-specific anti-patterns
+
+- **`try { await sodax.swaps.swap(...) } catch` for SDK-level failures.** v2 returns `Result<T>` — branch on `result.ok`. `catch` only fires for thrown exceptions (e.g. missing `walletProvider`), not for `RELAY_TIMEOUT` or `EXECUTION_FAILED`.
+- **Forgetting the discriminator.** `raw: false` is required on signed swaps; without it TypeScript rejects `walletProvider`.
+- **Calling `submitSwapTx` with the full `relayData` object.** The backend expects the `payload: string` field, not the wrapper.
+
+## Migration workflow (port v1 swap to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../migration-v1-to-v2/knowledge/features/swap.md`](../migration-v1-to-v2/knowledge/features/swap.md) — v1 → v2 swap port playbook.
+3. Cross-cutting renames (apply repo-wide before swap-specific edits) → [`../migration-v1-to-v2/knowledge/breaking-changes/type-system.md`](../migration-v1-to-v2/knowledge/breaking-changes/type-system.md).
+4. Error code crosswalk (v1 `IntentError` → v2 `SodaxError<C>` with `feature: 'swap'`) → [`../migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md`](../migration-v1-to-v2/knowledge/reference/error-code-crosswalk.md).
+
+## Verification
+
+1. `pnpm tsc --noEmit` from the consumer repo exits clean.
+2. Every `await sodax.swaps.<method>(...)` call site has `if (!result.ok)` branching.
+3. No `xToken.xChainId`, no `*_MAINNET_CHAIN_ID`, no `*SpokeProvider` references (migration only).
+4. `isSodaxError(e)` (not bare `instanceof SodaxError`) in cross-bundle code.
+
+## Related granular skills (same family)
+
+- [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap is followed by a supply/borrow action.
+- [`../partner/SKILL.md`](../partner/SKILL.md) — partner fees on swap.
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — stuck-asset recovery for failed swaps.
+- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `submitSwapTx` and intent / orderbook lookups (step-by-step swap flow + diagnostics).
+
+For tasks spanning multiple features, load the broad [`sodax-sdk` skill](../SKILL.md) instead.
+
+## Wallet provider (different SDK package family)
+
+This skill treats `walletProvider` as a contract (`IEvmWalletProvider` etc.) — it does not instantiate one. For Node bots / scripts / non-React backends that need a wallet implementation (private-key EVM, Solana keypair, Stellar SDK, etc.), **also load the `sodax-wallet-sdk-core` skill (integration mode)**. That package ships ready-made `I*WalletProvider` classes for all 9 chain families.

package/skills/sodax-wallet-sdk-core/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: sodax-wallet-sdk-core
+description: 'INTEGRATION (write NEW code) — @sodax/wallet-sdk-core is the low-level multi-chain wallet layer (one provider class per chain family across 9 chain types: EVM, Solana, Sui, Bitcoin, Stellar, ICON, Injective, NEAR, Stacks). Each class accepts either a private-key config (Node scripts, CI, bots, indexers) or a browser-extension config (custom non-React browser flows) and signs + broadcasts transactions. Use whenever a backend, script, test, or non-React browser flow needs to instantiate a wallet provider directly — `EvmWalletProvider`, `SolanaWalletProvider`, etc. Triggers on "instantiate EvmWalletProvider", "sign a tx from a Node script", "wallet provider for backend", "private-key signing", "wallet-sdk-core setup", any `*WalletProvider` class name. For React dapps prefer `sodax-wallet-sdk-react` instead — most React consumers never touch this package directly and get a typed `IXxxWalletProvider` via `useWalletProvider(...)`. MIGRATION (port v1 → v2) — v1 → v2 changes are additive (same class names, same config-type names, same config shapes). The only mechanical migration is replacing deep imports from v1''s flat `wallet-providers/<chain>.ts` layout with barrel imports, plus optionally adopting the new `defaults` field and re-imported library types. Triggers on imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC, or adopting new additive `defaults` / `*WalletDefaults` / `*Policy` fields. Most projects don''t need a wallet-sdk-core migration — the real migration target is usually `@sodax/sdk` or `@sodax/types`. Load this skill if EITHER applies; the body gates by mode.'
+---
+
+# When to use this skill
+
+AGENTS.md routes you here when you're working with `@sodax/wallet-sdk-core` v2 — either writing new code or upgrading an older project.
+
+**Pick your mode:**
+
+- Writing NEW v2 code (greenfield wallet provider setup, no v1 deep imports)? → § **Integration mode** below.
+- Upgrading EXISTING code (deep imports from `@sodax/wallet-sdk-core/wallet-providers/…`, bumping from an older RC)? → § **Migration mode** below. **Headline: v1 code drops in unchanged at the wallet-sdk-core surface** — if compile errors appear here, the real migration target is almost certainly `@sodax/sdk` or `@sodax/types` (load `sodax-sdk` skill instead).
+
+For React consumers → use `sodax-wallet-sdk-react` (they get the typed wallet provider via `useWalletProvider(...)` and pass it to `@sodax/sdk` calls).
+
+---
+
+## Integration mode (writing new v2 code)
+
+Direct usage of `@sodax/wallet-sdk-core` is the right choice for:
+
+- Backend / Node scripts (CI tests, indexers, bots, server APIs).
+- Custom browser flows that don't use React.
+- Tests that need to sign with a deterministic key.
+
+### Workflow
+
+1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DON'T + workflow + stop conditions.
+2. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — mental model: `BaseWalletProvider`, dual-config discriminants (`{ type: 'PRIVATE_KEY', … }` vs `{ type: 'BROWSER_EXTENSION', … }`), shallow `defaults` merge, library-exports.
+3. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — copy-paste minimal example for the chain you need.
+4. For your chain, read [`integration/knowledge/features/`](./integration/knowledge/features/) — per-chain config table + methods + gotchas (one file per chain family).
+5. Task-specific recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup-private-key.md`, `setup-browser-extension.md`, `sign-and-broadcast.md`, `defaults-and-overrides.md`, `library-exports.md`, `bridge-to-sdk.md` (pass provider to `@sodax/sdk`).
+6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — public API, provider classes, interfaces (`IXxxWalletProvider`), chain support, glossary.
+
+### Conventions to follow (integration)
+
+- **Dual-config discriminant.** Every chain's provider config has a `type` discriminator: `'PRIVATE_KEY'` (Node / scripts) or `'BROWSER_EXTENSION'` (consumer dApps). Pick one — don't merge them.
+- **`defaults` is a shallow merge.** Each provider accepts a `defaults` field for per-method overrides (e.g. `waitForTransactionReceipt`, `gasPrice`). The merge into the per-call options is **shallow**, not deep. Top-level keys overwrite wholesale.
+- **Use barrel imports**, not deep imports. Import classes from `@sodax/wallet-sdk-core`, not from `@sodax/wallet-sdk-core/wallet-providers/<chain>.ts`.
+- **Re-import chain SDK types from the barrel.** `@sodax/wallet-sdk-core` re-exports the types you need (e.g. `WalletClient` from viem, `SuiClient` from `@mysten/sui`). Don't add the underlying SDK as a direct dep — risks version skew.
+- **`IXxxWalletProvider` is the interface to pass into `@sodax/sdk`.** When bridging to the SDK, narrow with `useWalletProvider({ xChainId: ChainKeys.X })` (React) or just construct the provider directly and pass it in the SDK call payload (`{ raw: false, walletProvider }`).
+
+### Top traps to avoid (integration)
+
+1. **Mixing the two config variants.** `PRIVATE_KEY` and `BROWSER_EXTENSION` are mutually exclusive. Each chain's `*WalletProviderConfig` is a discriminated union — TypeScript catches mixing, but only if you don't use `as`.
+2. **Adding viem / `@mysten/sui` / `@solana/web3.js` as a direct dep** when the type was importable from `@sodax/wallet-sdk-core`. See `integration/recipes/library-exports.md`.
+3. **Deep-importing `@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider`**. v1's flat layout is gone; use barrel imports.
+4. **Expecting `defaults` to deep-merge.** It doesn't — top-level keys overwrite wholesale.
+5. **Trying to extend `BaseWalletProvider` directly** in consumer code. That's a maintainer-only path — write a thin wrapper over an existing provider instead.
+
+### Verification (integration)
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+```
+
+If errors mention `@sodax/wallet-sdk-core`, look up the symbol in `integration/knowledge/reference/`. If the symbol isn't there, stop and ask the user — don't invent classes.
+
+---
+
+## Migration mode (v1 → v2 porting)
+
+Pick this mode ONLY if you see one of these patterns:
+
+- Deep imports: `import { … } from '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` (or similar per-chain file).
+- Bumping `@sodax/wallet-sdk-core` from an older RC and wanting to adopt new additive features (`defaults`, `*WalletDefaults`, `*Policy` types).
+
+The package name **did not change** across versions. Class names, config-type names, and config shapes are **identical** v1 → v2. **No mandatory edits** at the wallet-sdk-core surface — v1 code drops in unchanged.
+
+If a project does more than the deep-import cleanup at this surface, the real migration target is almost certainly `@sodax/sdk` (chain-key renames, Result<T>, error model) or `@sodax/types`. Route to the `sodax-sdk` skill (migration mode) instead.
+
+### Workflow
+
+1. Read [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — DO / DON'T + workflow. **The headline: v1 code drops in unchanged.**
+2. Read [`migration-v1-to-v2/knowledge/README.md`](./migration-v1-to-v2/knowledge/README.md) — what (additively) changed, read order, TL;DR.
+3. Read the breaking-change writeups under [`breaking-changes/`](./migration-v1-to-v2/knowledge/breaking-changes/) — `folder-layout.md` (deep-import → barrel), `defaults-config.md`, `base-wallet-provider.md`, `library-exports.md`.
+4. For mechanical changes, apply the recipes in [`recipes/`](./migration-v1-to-v2/knowledge/recipes/) — `adopt-defaults.md`, `adopt-library-exports.md`. **Both are optional** — they're cleanup paths, not requirements.
+5. Confirm no renames / deletions exist by checking [`reference/`](./migration-v1-to-v2/knowledge/reference/) — `renamed-symbols.md` (empty), `deleted-exports.md` (empty), `added-fields.md` (additive new surface).
+6. Verify with [`checklist.md`](./migration-v1-to-v2/knowledge/checklist.md).
+
+### Top mechanical changes
+
+1. **Deep imports → barrel imports.** Replace `import { EvmWalletProvider } from '@sodax/wallet-sdk-core/wallet-providers/EvmWalletProvider'` with `import { EvmWalletProvider } from '@sodax/wallet-sdk-core'`. The flat `wallet-providers/*.ts` layout is gone.
+2. **(Optional) Re-import chain SDK types from the barrel.** Replace direct imports of `WalletClient` (viem), `SuiClient` (@mysten/sui), etc. with re-exports from `@sodax/wallet-sdk-core`. Removes the underlying SDK as a direct dep, eliminates version skew. See `recipes/adopt-library-exports.md`.
+3. **(Optional) Adopt `defaults` field.** New `defaults` (shallow-merge) field on each provider's config lets you set per-method overrides centrally. See `recipes/adopt-defaults.md`.
+
+### Top traps to avoid (migration)
+
+1. **Treating this as a real migration.** It isn't — v1 code drops in unchanged at the wallet-sdk-core surface. If the consumer's compile errors point at this package, look one layer deeper — they're almost certainly `@sodax/types` renames bleeding through (e.g. `xChainId` → `chainKey`) and the real fix is in the `sodax-sdk` skill (migration mode).
+2. **Extending `BaseWalletProvider` in consumer code.** That's a maintainer path. If a project subclasses it, scope confirmation with the user before touching anything.
+
+### Stop conditions (defer to user)
+
+| Signal | Why stop |
+|---|---|
+| Compile errors mention `@sodax/sdk` or `@sodax/types` symbols | Not this migration. Route to `sodax-sdk` skill (migration mode). |
+| Project extends `BaseWalletProvider` with non-trivial logic | Maintainer-only path. Confirm scope first. |
+| User wants a chain family not in `integration/knowledge/reference/chain-support.md` | Adding a new chain is a maintainer task. |
+
+### Verification (migration)
+
+```bash
+pnpm tsc --noEmit   # must exit clean
+# No leftover deep imports from v1's flat layout:
+grep -rE "from '@sodax/wallet-sdk-core/wallet-providers/" src/   # empty
+```
+
+---
+
+# Related skills
+
+- `sodax-sdk` — pass the constructed provider into SDK calls (`{ raw: false, walletProvider }`); SDK-side v1 → v2 work happens there.
+- `sodax-wallet-sdk-react` — for React dapps; this skill is only relevant if NOT using React.