@sodax/skills 2.0.0-rc.4

package/knowledge/sdk/migration/features/staking.md

@@ -0,0 +1,138 @@
+# Staking migration — v1 → v2
+
+Pure-SDK migration playbook for `StakingService`.
+
+Pair: [`../../integration/features/staking.md`](../../integration/features/staking.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider` from every params object.** Pass `walletProvider` directly into the SDK call.
+2. **Add `srcChainKey` + `srcAddress` to every `*Params<K>`.** `account` field is renamed to `srcAddress`.
+3. **All 5 staking actions are cross-chain.** Even though staking writes happen on the hub, every SDK method (`stake`, `unstake`, `instantUnstake`, `claim`, `cancelUnstake`) accepts `srcChainKey: K extends SpokeChainKey` and relays spoke→hub via `relayTxAndWaitPacket`. **Return shape is always `Result<TxHashPair>`.**
+4. **`approve` is an exception — it returns `Result<TxReturnType<K, false>>` (single hash).** Approve is spoke-only (no relay) — it just spends ERC20 allowance on the source chain.
+5. **Approve and allowance are action-discriminated.** `staking.approve` and `staking.isAllowanceValid` take a `StakingParamsUnion` discriminated by `params.action`. `'stake'` approves SODA; `'unstake'` and `'instantUnstake'` approve xSoda.
+6. **Info getter signatures changed.** v1 took `spokeProvider`; v2 takes `(srcAddress, srcChainKey)`. The SDK derives the hub wallet internally.
+7. **Hub-only / amount-only reads have no chain context.** `getStakingConfig()`, `getStakeRatio(amount)`, `getInstantUnstakeRatio(amount)`, `getConvertedAssets(amount)` — none accept `srcChainKey`. (Take `bigint` amount directly, not an object.) `getStakeRatio` returns `Result<[xSodaAmount, previewDepositAmount]>` (a tuple — both are bigints).
+8. **Errors → `SodaxError` + `Result<T>`.** v1's `StakingError<StakingErrorCode>` is gone.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `StakeParams` | `{ amount, account, minReceive, action: 'stake' }` | `{ srcChainKey, srcAddress, amount, minReceive, action: 'stake' }` | Now generic `<K>`. `account` → `srcAddress`. |
+| `UnstakeParams` | `{ amount, account, action: 'unstake' }` | `{ srcChainKey, srcAddress, amount, action: 'unstake' }` | |
+| `InstantUnstakeParams` | `{ amount, minAmount, account, action: 'instantUnstake' }` | `{ srcChainKey, srcAddress, amount, minAmount, action: 'instantUnstake' }` | |
+| `ClaimParams` | `{ requestId, amount, action: 'claim' }` | `{ srcChainKey, srcAddress, requestId, amount, action: 'claim' }` | Adds chain context. |
+| `CancelUnstakeParams` | `{ requestId, action: 'cancelUnstake' }` | `{ srcChainKey, srcAddress, requestId, action: 'cancelUnstake' }` | Adds chain context. |
+| `getStakingInfo` (read) | `(spokeProvider) => Promise<StakingInfo>` | `(srcAddress, srcChainKey) => Promise<Result<StakingInfo>>` | Renamed to `getStakingInfoFromSpoke` (the v1 `getStakingInfo` was hub-only and is not surfaced now). |
+| `getUnstakingInfo` (read) | `(userAddress, spokeProvider)` | `(srcAddress, srcChainKey)` | v1 ignored `userAddress`; v2 reads it for real. |
+| `getUnstakingInfoWithPenalty` (read) | new (v2) | `(srcAddress, srcChainKey) => Promise<Result<UnstakingInfo & { requestsWithPenalty: UnstakeRequestWithPenalty[] }>>` | Wraps `getUnstakingInfo`'s base shape with a penalty-augmented request list. |
+
+### Deleted symbols
+
+- `StakingError<StakingErrorCode>` and `isStakingError` — replaced by `SodaxError<C>` + `feature: 'staking'`.
+- v1 `getStakingInfo(hubAddress, …)` — not exposed as a public method in v2. Use `getStakingInfoFromSpoke(srcAddress, srcChainKey)`; the SDK derives the hub wallet via `HubService.getUserHubWalletAddress` internally.
+- `spokeProvider instanceof SonicSpokeProvider` runtime checks — replace with `isHubChainKeyType(chainKey)` from `@sodax/sdk`.
+
+### v1 → v2 error code crosswalk (staking-specific)
+
+| v1 `StakingErrorCode` | v2 code + context |
+|---|---|
+| `STAKE_FAILED` | `EXECUTION_FAILED` (`action: 'stake'`) |
+| `UNSTAKE_FAILED` | `EXECUTION_FAILED` (`action: 'unstake'`) |
+| `INSTANT_UNSTAKE_FAILED` | `EXECUTION_FAILED` (`action: 'instantUnstake'`) |
+| `CLAIM_FAILED` | `EXECUTION_FAILED` (`action: 'claim'`) |
+| `CANCEL_UNSTAKE_FAILED` | `EXECUTION_FAILED` (`action: 'cancelUnstake'`) |
+| `GET_STAKING_INFO_FAILED` | `LOOKUP_FAILED` (`method: 'getStakingInfo'` or `'getStakingInfoFromSpoke'`) |
+| `GET_UNSTAKING_INFO_FAILED` | `LOOKUP_FAILED` (`method: 'getUnstakingInfo'`) |
+| `GET_STAKING_CONFIG_FAILED` | `LOOKUP_FAILED` (`method: 'getStakingConfig'`) |
+| `GET_STAKE_RATIO_FAILED` | `LOOKUP_FAILED` (`method: 'getStakeRatio'`) |
+
+## Per-method delta
+
+### `stake`
+
+```diff
+- await sodax.staking.stake({ amount, account, minReceive, action: 'stake' }, spokeProvider);
++ const result = await sodax.staking.stake({
++   params: {
++     srcChainKey: ChainKeys.ARBITRUM_MAINNET,
++     srcAddress: '0x…',
++     amount, minReceive,
++     action: 'stake',
++   },
++   raw: false,
++   walletProvider,
++ });
++ if (!result.ok) return;
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### `unstake` / `instantUnstake` / `claim` / `cancelUnstake`
+
+Same shape as stake. `account` → `srcAddress`. `requestId` (claim, cancelUnstake) is unchanged.
+
+### `approve` / `isAllowanceValid` — action-discriminated
+
+```diff
+- await sodax.staking.approveStake({ amount, account, ... }, spokeProvider);
++ await sodax.staking.approve({
++   params: { srcChainKey, srcAddress, amount, action: 'stake' },
++   raw: false,
++   walletProvider,
++ });
+```
+
+For `isAllowanceValid`:
+
+```ts
+const result = await sodax.staking.isAllowanceValid({
+  params: { srcChainKey, srcAddress, amount, action: 'stake' },
+  raw: true,    // read-only
+});
+```
+
+### Info reads
+
+```diff
+- const info = await sodax.staking.getStakingInfo(spokeProvider);
++ const result = await sodax.staking.getStakingInfoFromSpoke(srcAddress, srcChainKey);
++ if (!result.ok) return;
++ const info = result.value;
+```
+
+For amount-only reads (no chain context):
+
+```ts
+const result = await sodax.staking.getStakeRatio(parseUnits('100', 18));
+if (result.ok) {
+  const [xSodaAmount, previewDepositAmount] = result.value;
+}
+```
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **Wrong return shape for actions.** Treating `stake/unstake/etc.` as returning `Result<TxReturnType<K, false>>` (single hash) is **wrong** — they return `Result<TxHashPair>` because they always relay spoke→hub. Only `approve` returns a single hash.
+2. **Forgetting `raw: true` on the allowance query.** TypeScript error: `Property 'walletProvider' is missing`. `isAllowanceValid` requires `WalletProviderSlot<K, Raw>`; `raw: false` would force a wallet provider. Use `raw: true` for read-only.
+3. **Forgetting to remove the v1 `account` field from params.** v2 uses `srcAddress`. If both are set, TypeScript rejects the literal.
+4. **`getStakingInfo(hubAddress)` is not a public method in v2.** v1 had it for direct hub queries. v2 has `getStakingInfoFromSpoke(srcAddress, srcChainKey)` which derives the hub wallet internally. Use the spoke variant.
+5. **`UnstakingInfo` no longer accepts `userAddress` separately.** v1 took both `spokeProvider` and `userAddress` props but ignored `userAddress` inside. v2 takes `srcAddress` and uses it.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scans:
+grep -rE "spokeProvider:\s*\w+|account:\s*[`'][^`']+['\"`]" src/    # leftover v1 patterns
+grep -rE "isStakingError\b|StakingError\b" src/
+```
+
+## Cross-references
+
+- v2 staking usage: [`../../integration/features/staking.md`](../../integration/features/staking.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).

package/knowledge/sdk/migration/features/swap.md

@@ -0,0 +1,198 @@
+# Swap migration — v1 → v2
+
+Pure-SDK migration playbook for `SwapService`.
+
+Pair: [`../../integration/features/swap.md`](../../integration/features/swap.md).
+
+## TL;DR
+
+1. **Drop the `*SpokeProvider` argument.** Pass `walletProvider` directly into the SDK call payload alongside `params` and `raw: false`.
+2. **Add `raw: false` (or `raw: true`) to every call shape.** Without it, TypeScript can't pick a branch of `WalletProviderSlot` and rejects `walletProvider`.
+3. **Field renames on `CreateIntentParams<K>` and `CreateLimitOrderParams<K>`:**
+   - `srcChain` → `srcChainKey`
+   - `dstChain` → `dstChainKey`
+   - **`Intent.srcChain` / `Intent.dstChain` are unchanged** (read shape) — they're `IntentRelayChainId` (bigint).
+4. **`CreateIntentResult` shape changed.** v1 was a tuple `[spokeTxHash, intent, relayData]`; v2 is an object `{ tx, intent, relayData }`. Destructure accordingly.
+5. **`SubmitSwapTxRequest.srcChainId` → `srcChainKey`.** And `relayData` field on the request expects a **string** (`relayData.payload`), not the `RelayExtraData` object.
+6. **Errors → `SodaxError` + `Result<T>`.** v1's `IntentError<IntentErrorCode>` is gone. Branch on `result.ok`; use `(error.feature, error.code)` for discrimination.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 field | v2 field | Notes |
+|---|---|---|---|
+| `CreateIntentParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | Now generic: `CreateIntentParams<K extends SpokeChainKey>`. |
+| `CreateLimitOrderParams` (request) | `srcChain`, `dstChain` | `srcChainKey`, `dstChainKey` | `Omit<CreateIntentParams<K>, 'deadline'>`. |
+| `SubmitSwapTxRequest` (backend req) | `srcChainId` | `srcChainKey` | And `relayData: string` (was the object in v1). |
+| `Intent` (read shape) | `srcChain`, `dstChain` | **unchanged** | `IntentRelayChainId` (bigint). Don't grep-replace blindly. |
+| `XToken` | `xChainId` | `chainKey` | Type renamed from `Token` → `XToken`. |
+| `CreateIntentResult` | tuple `[spokeTxHash, intent, relayData]` | object `{ tx, intent, relayData }` | Generic: `CreateIntentResult<K, Raw>`. |
+
+### Deleted symbols
+
+- The `SpokeProvider` union and per-chain `*SpokeProvider` classes — gone. v2 takes `walletProvider` directly. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) § 1.
+- `IntentError<IntentErrorCode>` and `isIntentError` / `isIntentPostExecutionFailedError` / `isIntentSubmitTxFailedError` type guards. Replaced by `isSodaxError` + feature/code discrimination.
+- `CustomProvider` (Hana wallet window typedecl) — declare `unknown` or import directly from the wallet vendor.
+- `hubAssets` global — gone. `XToken.vault` and `XToken.hubAsset` baked in.
+
+### v1 → v2 error code crosswalk (swap-specific)
+
+| v1 `IntentErrorCode` | v2 `SodaxErrorCode` + context |
+|---|---|
+| `CREATE_INTENT_FAILED` | `INTENT_CREATION_FAILED` (`action: 'createIntent'`) |
+| `CREATE_LIMIT_ORDER_FAILED` | `INTENT_CREATION_FAILED` (`action: 'createLimitOrder'`) |
+| `POST_EXECUTION_FAILED` | `EXECUTION_FAILED` (`action: 'swap'`, `phase: 'postExecution'`) |
+| `SOLVER_API_ERROR` | `EXTERNAL_API_ERROR` (`api: 'solver'`, with `solverCode`/`solverDetail` on context) |
+| `SIMULATION_FAILED` | `EXECUTION_FAILED` (`phase: 'execution'`) |
+| `SUBMIT_TX_FAILED` (relay) | `TX_SUBMIT_FAILED` (`relayCode: 'SUBMIT_TX_FAILED'`) |
+| `RELAY_TIMEOUT` | `RELAY_TIMEOUT` (unchanged code; still on `relayCode`) |
+
+## Per-method delta
+
+### `swap`
+
+```diff
+- await sodax.swaps.swap({
+-   intentParams,
+-   spokeProvider: sourceSpokeProvider,
+- });
++ const result = await sodax.swaps.swap({
++   params: intentParams,
++   raw: false,
++   walletProvider: sourceWalletProvider,
++ });
++ if (!result.ok) return;
++ const { spokeTxHash, intent, relayData } = result.value;
+```
+
+### `createIntent`
+
+```diff
+- const [spokeTxHash, intent, relayData] = await sodax.swaps.createIntent({
+-   intentParams,
+-   spokeProvider: sourceSpokeProvider,
+- });
++ const result = await sodax.swaps.createIntent({
++   params: intentParams,
++   raw: false,
++   walletProvider: sourceWalletProvider,
++ });
++ if (!result.ok) return;
++ const { tx: spokeTxHash, intent, relayData } = result.value;
+```
+
+### `createLimitOrder`
+
+Same as `createIntent` shape (with `CreateLimitOrderParams`). v1 took `{ limitOrderParams, spokeProvider }`; v2 takes `{ params, raw: false, walletProvider }`.
+
+### `cancelIntent` / `cancelLimitOrder`
+
+```diff
+- await sodax.swaps.cancelIntent({ srcChain, intent, spokeProvider });
++ await sodax.swaps.cancelIntent({
++   params: { srcChainKey, intent },
++   raw: false,
++   walletProvider,
++ });
+```
+
+### `approve` / `isAllowanceValid`
+
+v1: `await sodax.swaps.approve({ intentParams, spokeProvider })`.
+v2: `await sodax.swaps.approve({ params: intentParams, raw: false, walletProvider })`.
+
+For `isAllowanceValid` in **read-only** flows (e.g. UI polling), use `raw: true` to skip the wallet-provider requirement:
+
+```ts
+const result = await sodax.swaps.isAllowanceValid({ params, raw: true });
+```
+
+The underlying read doesn't consult the wallet provider; `raw: true` is the contract for read-only access.
+
+### Backend submit-tx (`SubmitSwapTxRequest`)
+
+```diff
+  const request: SubmitSwapTxRequest = {
+    txHash: spokeTxHash as string,
+-   srcChainId: sourceChain,
++   srcChainKey: src.chain,
+    walletAddress: sourceAccount.address ?? '',
+    intent: swapIntentData,
+-   relayData,                       // was the RelayExtraData object
++   relayData: relayData.payload,    // now a string
+  };
+  const submitResult = await sodax.backendApi.submitSwapTx(request);
+  if (!submitResult.ok) return;
+```
+
+## Worked example — `handleSubmitTxSwap` flow
+
+```diff
+  const handleSubmitTxSwap = async (intentOrderPayload: CreateIntentParams) => {
+-   if (!sourceProvider) return;
++   if (!sourceWalletProvider) return;
+-   const createIntentResult = await sodax.swaps.createIntent({
+-     intentParams: intentOrderPayload,
+-     spokeProvider: sourceProvider,
+-   });
++   const createIntentResult = await sodax.swaps.createIntent({
++     params: intentOrderPayload,
++     raw: false,
++     walletProvider: sourceWalletProvider,
++   });
+    if (!createIntentResult.ok) return;
+-   const [spokeTxHash, intent, relayData] = createIntentResult.value;
++   const { tx: spokeTxHash, intent, relayData } = createIntentResult.value;
+    const swapIntentData: SwapIntentData = {
+      /* … */
+-     srcChain: Number(intent.srcChain),    // Intent.srcChain still on read shape
+-     dstChain: Number(intent.dstChain),    // Intent.dstChain still on read shape
++     srcChain: Number(intent.srcChain),    // unchanged — Intent shape kept these
++     dstChain: Number(intent.dstChain),
+    };
+    const request: SubmitSwapTxRequest = {
+      txHash: spokeTxHash as string,
+-     srcChainId: sourceChain,
++     srcChainKey: src.chain,
+      walletAddress: sourceAccount.address ?? '',
+      intent: swapIntentData,
+-     relayData,
++     relayData: relayData.payload,
+    };
+-   await submitSwapTx(request);
++   const submitResult = await sodax.backendApi.submitSwapTx(request);
++   if (!submitResult.ok) return;
+  };
+```
+
+## Pitfalls
+
+Cross-cutting traps (Result destructuring, error-model migration, srcChain/dstChain renames, etc.) live in [`../ai-rules.md`](../ai-rules.md). The list below is feature-specific — typecheck fingerprints, return-shape diffs, and gotchas unique to this feature.
+
+1. **Over-broad regex on `srcChain` / `dstChain`.** Request types renamed; `Intent` (read shape) didn't. Distinguish "I'm building a request" from "I'm reading an intent."
+2. **`createIntent` success shape changed from tuple to object.** `{ tx, intent, relayData }`, not `[spokeTxHash, intent, relayData]`.
+3. **`relayData` on `SubmitSwapTxRequest` is a `string`.** It's `relayData.payload`, not the full `RelayExtraData` object.
+4. **`spokeTxHash` is `TxReturnType<K, false>`, not necessarily `string`.** For most chains it's a string already, but the SDK type is broader. Cast at the boundary when passing to APIs that strictly want `string`: `txHash: spokeTxHash as string`.
+5. **`Intent.deadline` is `bigint`.** `Math.floor(Date.now() / 1000) + 60 * 5` returns a number; wrap in `BigInt(...)`.
+6. **`IntentResponse.srcChain` / `dstChain` from the backend are `IntentRelayChainId` (number/bigint), not chain keys.** Convert via `sodax.config.getSpokeChainKeyFromIntentRelayChainId(BigInt(intent.dstChain))` when displaying.
+7. **`hubAssets` is gone.** Anything that walked `hubAssets[chainId]` for vault lookup must use `XToken.vault` (now baked in) or `sodax.config.getOriginalAssetAddress()`.
+8. **`SodaxConfig.swaps` vs `.solver`.** v1 mixed solver endpoints under `swaps`; v2 splits — `swaps` for supported tokens, `solver` for endpoints. See [`../breaking-changes/architecture.md`](../breaking-changes/architecture.md) Appendix B.
+
+## Verification
+
+After migrating swap call sites:
+
+```bash
+# Should produce zero errors when the migration is complete:
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scan for leftover v1 patterns:
+grep -rE "spokeProvider:\s*\w+|intentParams:\s*\w+|srcChain:\s*\w+\.[a-z]+ChainId" src/
+grep -rE "isIntentError\b|isIntentPostExecutionFailedError\b|isIntentSubmitTxFailedError\b" src/
+```
+
+## Cross-references
+
+- v2 swap usage: [`../../integration/features/swap.md`](../../integration/features/swap.md).
+- Cross-cutting prerequisites (type-system, architecture, result/errors) listed in [`../README.md`](../README.md).