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

package/ai-exported/migration/features/icx-bnusd-baln.md

@@ -0,0 +1,151 @@
+# Token migration (ICX/bnUSD/BALN) — v1 → v2
+
+Pure-SDK migration playbook for `MigrationService` (the SDK module — not v1→v2 SDK porting).
+
+Pair: [`../../integration/features/icx-bnusd-baln.md`](../../integration/features/icx-bnusd-baln.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider`. Pass `walletProvider` directly.**
+2. **Add `srcChainKey` + `srcAddress` to every action params.** All migration param types (`MigrationParams<K>`, `UnifiedBnUSDMigrateParams<K>`, `IcxToSodaMigrateParams<K>`, `RevertSodaToIcxParams<K>`, `BalnSwapParams<K>`) gained both fields and a `<K>` generic.
+3. **All 4 orchestrator methods return `Result<TxHashPair>`.** v1 returned a string tx hash and threw on error.
+4. **`migratebnUSD` carries `direction` on error context** — `'forward'` (legacy → new) or `'reverse'` (new → legacy). The SDK detects direction from `(srcToken, dstToken)` addresses.
+5. **`BalnSwapService` lock-management methods STILL THROW.** `claim`, `claimUnstaked`, `stake`, `unstake`, `cancelUnstake`, `getDetailedUserLocks` — these 6 methods preserve the v1 throw-on-error contract. Wrap in `try/catch` until a future cleanup release converts them to `Result`.
+6. **Errors → `SodaxError` + `Result<T>`.** v1's `MigrationError<MigrationErrorCode>` is gone.
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `MigrationParams` | non-generic | `MigrationParams<K extends SpokeChainKey>` with `srcChainKey`, `srcAddress`, `amount`, `dstAddress?` | Generic added. |
+| `UnifiedBnUSDMigrateParams` | non-generic | `UnifiedBnUSDMigrateParams<K>` extends `MigrationParams<K>` with `srcToken`, `dstToken` | Generic added. |
+| `BalnSwapParams` | `{ amount, lockPeriodMonths }` | `MigrationParams<K> & { lockPeriodMonths }` | Adds chain context. |
+
+### Deleted symbols
+
+- `MigrationError<MigrationErrorCode>` and `isMigrationError` — replaced by `SodaxError<C>` + `feature: 'migration'`.
+- The 6 v1 separate-method-per-direction names (`migrateBnUSDForward`, `migrateBnUSDReverse`, …) — collapsed into `migratebnUSD` with auto-direction detection on `error.context.direction`.
+
+### v1 → v2 error code crosswalk
+
+| v1 `MigrationErrorCode` | v2 code + context |
+|---|---|
+| `MIGRATE_BNUSD_FORWARD_FAILED` | `EXECUTION_FAILED` (`action: 'migratebnUSD'`, `direction: 'forward'`) |
+| `MIGRATE_BNUSD_REVERSE_FAILED` | `EXECUTION_FAILED` (`action: 'migratebnUSD'`, `direction: 'reverse'`) |
+| `MIGRATE_ICX_TO_SODA_FAILED` | `EXECUTION_FAILED` (`action: 'migrateIcxToSoda'`) |
+| `REVERT_MIGRATE_SODA_TO_ICX_FAILED` | `EXECUTION_FAILED` (`action: 'revertMigrateSodaToIcx'`) |
+| `MIGRATE_BALN_FAILED` | `EXECUTION_FAILED` (`action: 'migrateBaln'`) |
+| `GET_AVAILABLE_AMOUNT_FAILED` | `LOOKUP_FAILED` (`method: 'getAvailableAmount'`) |
+
+`migratebnUSD` additionally has `phase: 'destinationExecution'` on errors from its secondary `waitUntilIntentExecuted` watcher (after the primary relay completes, bnUSD waits for the destination contract to finalize).
+
+## Per-method delta
+
+### `migratebnUSD` (replaces v1 forward + reverse methods)
+
+```diff
+- // v1 had two methods:
+- await sodax.migration.migrateBnUSDForward({ amount, /* … */ }, spokeProvider);
+- await sodax.migration.migrateBnUSDReverse({ amount, /* … */ }, spokeProvider);
+
++ // v2 has one method; SDK detects direction from (srcToken, dstToken):
++ const result = await sodax.migration.migratebnUSD({
++   params: {
++     srcChainKey, srcAddress,
++     srcToken,    // legacy or new bnUSD
++     dstToken,    // the other one
++     amount,
++     dstAddress,
++   },
++   raw: false,
++   walletProvider,
++ });
++ if (!result.ok) {
++   const dir = result.error.context?.direction;  // 'forward' | 'reverse'
++   /* … */
++ }
+```
+
+### `migrateIcxToSoda` / `revertMigrateSodaToIcx` / `migrateBaln`
+
+Standard pattern:
+
+```diff
+- await sodax.migration.migrateIcxToSoda({ amount }, spokeProvider);
++ const result = await sodax.migration.migrateIcxToSoda({
++   params: { srcChainKey: ChainKeys.ICON_MAINNET, srcAddress: 'hx…', amount },
++   raw: false,
++   walletProvider: iconWp,
++ });
++ if (!result.ok) return;
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+`migrateBaln` adds `lockPeriodMonths: 0 | 1 | 2 | 3 | 6 | 12 | 18 | 24` to the params. Reward multiplier ranges 0.5x (0 months) – 1.5x (24 months).
+
+### Approve / allowance — action-discriminated
+
+```ts
+await sodax.migration.approve({
+  params: { srcChainKey, srcAddress, amount, action: 'migrateBaln' /* or migratebnUSD | migrateIcxToSoda | revertMigrateSodaToIcx */ },
+  raw: false,
+  walletProvider,
+});
+
+const allowed = await sodax.migration.isAllowanceValid({
+  params: { srcChainKey, srcAddress, amount, action: 'migrateBaln' },
+  raw: true,    // read-only
+});
+```
+
+### `getAvailableAmount` (claimable from partial migration)
+
+```diff
+- const amount: bigint = await sodax.migration.icx.getAvailableAmount(spokeProvider);
++ const result = await sodax.migration.icxMigration.getAvailableAmount();   // sub-service renamed; takes no args in v2
++ if (!result.ok) return 0n;
++ const amount = result.value;
+```
+
+### BALN lock management — STILL THROWS
+
+```diff
+  try {
+-   const tx = await sodax.migration.balnSwapService.stake({ amount, lockPeriod }, spokeProvider);
++   const tx = await sodax.migration.balnSwapService.stake({
++     params: { srcChainKey, srcAddress, amount, lockPeriodMonths },
++     raw: false,
++     walletProvider,
++   });
+    /* … */
+  } catch (e) {
+    /* still v1-style: catch the throw */
+  }
+```
+
+`claim`, `claimUnstaked`, `unstake`, `cancelUnstake`, `getDetailedUserLocks` follow the same pattern. They preserve the throw-on-error contract for now — future cleanup will Result-wrap them.
+
+## 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. **`migratebnUSD` direction detection.** v1 had explicit forward/reverse methods; v2 detects from `(srcToken, dstToken)`. If both are on the same side (both legacy or both new), the SDK rejects with `VALIDATION_FAILED`. Use the `direction` field on `error.context` to disambiguate in error messaging.
+2. **BALN lock methods don't return `Result`.** Be careful migrating wrappers — if your wrapper assumes Result-shape, lock methods will produce `undefined.ok` runtime errors. Keep the `try/catch` shape.
+3. **`lockPeriodMonths` is a literal union, not arbitrary `number`.** TypeScript rejects `lockPeriodMonths: 7`. Allowed values: `0 | 1 | 2 | 3 | 6 | 12 | 18 | 24`.
+4. **`getAvailableAmount` lives on the sub-service `sodax.migration.icxMigration` and takes no arguments.** v1 expected `(spokeProvider)`; v2 reads on-chain SODA liquidity directly from the hub provider, so the method needs no chain context. Sub-service field names: `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`.
+5. **`destinationExecution` phase on bnUSD errors** — these errors land **after** the relay succeeds. The spoke and hub txs may already exist; the destination-side finalization is what failed. Distinguish from primary relay errors (`phase: 'relay'`) when surfacing UX.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+grep -rE "spokeProvider:\s*\w+|migrateBnUSDForward\b|migrateBnUSDReverse\b|isMigrationError\b|MigrationError\b" src/
+```
+
+## Cross-references
+
+- v2 token migration usage: [`../../integration/features/icx-bnusd-baln.md`](../../integration/features/icx-bnusd-baln.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).

package/ai-exported/migration/features/money-market.md

@@ -0,0 +1,214 @@
+# Money Market migration — v1 → v2
+
+Pure-SDK migration playbook for `MoneyMarketService`.
+
+Pair: [`../../integration/features/money-market.md`](../../integration/features/money-market.md).
+
+## TL;DR
+
+1. **Drop `spokeProvider` from every params object.** Pass `walletProvider` directly into the SDK call payload alongside `params` and `raw: false`.
+2. **Add `srcChainKey` + `srcAddress` to every action params object.** v2's `MoneyMarketParams<K>` requires both; v1 didn't have them at all.
+3. **Mutations resolve `Result<TxHashPair>`, not throw.** v1 mutation methods threw; v2 returns `{ ok: false, error }` on SDK-level failure. Branch on `result.ok`.
+4. **`MoneyMarketSupplyParams` etc. are now generic** (`MoneyMarketSupplyParams<K extends SpokeChainKey>`). Add a chain-key generic to your params variables, or let TS infer from a literal `srcChainKey`.
+5. **Replace `moneyMarketSupportedTokens[chainId]` with `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)`.**
+6. **Replace `hubAssets[chainId][address]?.vault` with `token.vault`** (now baked into `XToken`). Same for `token.hubAsset`.
+7. **`sodax.moneyMarket.getAToken(...)` returns `Erc20Token & { chainKey }`, not a full `XToken`.** No `hubAsset` / `vault` on the result — look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` if needed.
+8. **Errors → `SodaxError` + `Result<T>`.** v1's `MoneyMarketError<MoneyMarketErrorCode>` is gone. The CODE moved from `error.code` to `error.message`-style? **No** — it's still on `error.code`, but the union changed (see crosswalk below).
+
+## Type / symbol cheat sheet
+
+### Field-level renames
+
+| Type | v1 shape | v2 shape | Notes |
+|---|---|---|---|
+| `MoneyMarketSupplyParams` | `{ token, amount, action }` | `{ srcChainKey, srcAddress, token, amount, action, dstChainKey?, dstAddress? }` | Same template for borrow / withdraw / repay. Now generic in `K extends SpokeChainKey`. |
+| `MoneyMarketBorrowParams` | non-generic | `MoneyMarketBorrowParams<K>` | Optional `dstChainKey`/`dstAddress` for cross-chain delivery. |
+| `MoneyMarketRepayParams` | non-generic | `MoneyMarketRepayParams<K>` | Optional `dstChainKey`/`dstAddress` for paying off debt on a different chain. |
+| `XToken` | `xChainId` | `chainKey` | Type renamed `Token` → `XToken`. New fields `vault`, `hubAsset` baked in. |
+
+### Deleted symbols
+
+- `moneyMarketSupportedTokens` — `Record<SpokeChainKey, XToken[]>` global. Use `sodax.moneyMarket.getSupportedTokensByChainId(chainKey)` / `getSupportedTokens()`.
+- `hubAssets` — vault address lookup global. Use `XToken.vault` / `XToken.hubAsset` directly.
+- `SodaTokens` — vault-validation registry. Use `sodax.config.getMoneyMarketReserveAssets()`.
+- `MoneyMarketError<MoneyMarketErrorCode>` and `isMoneyMarketError` — replaced by `SodaxError<C>` + `isSodaxError(e) && e.feature === 'moneyMarket'`.
+
+### v1 → v2 error code crosswalk (money-market-specific)
+
+| v1 `MoneyMarketErrorCode` | v2 code + context |
+|---|---|
+| `CREATE_SUPPLY_INTENT_FAILED` | `INTENT_CREATION_FAILED` (`action: 'supply'`) |
+| `CREATE_BORROW_INTENT_FAILED` | `INTENT_CREATION_FAILED` (`action: 'borrow'`) |
+| `CREATE_WITHDRAW_INTENT_FAILED` | `INTENT_CREATION_FAILED` (`action: 'withdraw'`) |
+| `CREATE_REPAY_INTENT_FAILED` | `INTENT_CREATION_FAILED` (`action: 'repay'`) |
+| `SUPPLY_FAILED` | `EXECUTION_FAILED` (`action: 'supply'`) |
+| `BORROW_FAILED` | `EXECUTION_FAILED` (`action: 'borrow'`) |
+| `WITHDRAW_FAILED` | `EXECUTION_FAILED` (`action: 'withdraw'`) |
+| `REPAY_FAILED` | `EXECUTION_FAILED` (`action: 'repay'`) |
+| `ALLOWANCE_CHECK_FAILED` | `ALLOWANCE_CHECK_FAILED` (unchanged) |
+| `APPROVE_FAILED` | `APPROVE_FAILED` (unchanged) |
+| `GAS_ESTIMATION_FAILED` | `GAS_ESTIMATION_FAILED` (unchanged) |
+
+## Per-method delta
+
+### `supply`
+
+```diff
+- const params: MoneyMarketSupplyParams = {
+-   token: token.address,
+-   amount: parseUnits('100', 6),
+-   action: 'supply',
+- };
+- const result = await sodax.moneyMarket.supply({ params, spokeProvider });
+- // result throws on failure, or returns the tx hash
++ const params: MoneyMarketSupplyParams<typeof srcChainKey> = {
++   srcChainKey: ChainKeys.ARBITRUM_MAINNET,
++   srcAddress: '0x…',
++   token: token.address,
++   amount: parseUnits('100', 6),
++   action: 'supply',
++ };
++ const result = await sodax.moneyMarket.supply({ params, raw: false, walletProvider });
++ if (!result.ok) {
++   // result.error: SodaxError with feature: 'moneyMarket'
++   return;
++ }
++ const { srcChainTxHash, dstChainTxHash } = result.value;
+```
+
+### `borrow` — gain cross-chain delivery
+
+If you ported a same-chain borrow, no new fields needed — just `srcChainKey` + `srcAddress`. For cross-chain delivery (which v1 didn't expose this cleanly), add `dstChainKey` and `dstAddress`:
+
+```ts
+await sodax.moneyMarket.borrow({
+  params: {
+    srcChainKey: ChainKeys.ARBITRUM_MAINNET,
+    srcAddress,
+    token: USDC.address,
+    amount,
+    action: 'borrow',
+    dstChainKey: ChainKeys.STELLAR_MAINNET,    // NEW in v2
+    dstAddress: 'G…',                           // NEW in v2
+  },
+  raw: false,
+  walletProvider,
+});
+```
+
+### `repay` — pay from a different chain than the debt
+
+Similar: v2 lets the spender chain (`srcChainKey`) differ from the debt chain (`dstChainKey`):
+
+```ts
+await sodax.moneyMarket.repay({
+  params: {
+    srcChainKey: fromChain,
+    srcAddress: fromAddress,
+    token: tokenOnFromChain.address,
+    amount,
+    action: 'repay',
+    dstChainKey: debtChain,
+    dstAddress: debtAddress,
+  },
+  raw: false,
+  walletProvider: walletOnFromChain,
+});
+```
+
+### `approve` / `isAllowanceValid`
+
+```diff
+- const allowed = await sodax.moneyMarket.isAllowanceValid({ params, spokeProvider });
++ const allowed = await sodax.moneyMarket.isAllowanceValid({
++   params,           // includes srcChainKey, srcAddress, action
++   raw: true,        // read-only — walletProvider not needed
++ });
++ if (!allowed.ok) return false;
++ if (!allowed.value) await sodax.moneyMarket.approve({ params, raw: false, walletProvider });
+```
+
+The `params.action` field discriminates which token gets approved (relevant for repay where the spent token may differ).
+
+## Replacing the static lookups
+
+```diff
+- import { moneyMarketSupportedTokens, hubAssets } from '@sodax/types';
+- const supplyTokens = moneyMarketSupportedTokens[chainId];
++ const supplyTokens = sodax.moneyMarket.getSupportedTokensByChainId(chainKey);
+
+- const allTokens = Object.entries(moneyMarketSupportedTokens)
+-   .flatMap(([chainId, tokens]) => tokens.map(t => ({ ...t, xChainId: chainId })));
++ const allTokens = Object.entries(sodax.moneyMarket.getSupportedTokens())
++   .flatMap(([_chainKey, tokens]) => tokens);   // tokens already carry chainKey in v2
+```
+
+```diff
+- const vault = hubAssets[chainId]?.[token.address]?.vault;
++ const vault = token.vault;   // baked into XToken
+```
+
+## Worked example — supply flow
+
+A single supply call site, before and after. Shows every change in one place: spoke-provider drop, params shape, return shape, field rename.
+
+```diff
+- const params: MoneyMarketSupplyParams = {
+-   token: token.address,
+-   amount: parseUnits(amount, token.decimals),
+-   action: 'supply',
+- };
+- const txHash = await sodax.moneyMarket.supply({ params, spokeProvider });
+- // throws on failure
++ const params: MoneyMarketSupplyParams<typeof srcChainKey> = {
++   srcChainKey,                                   // NEW: required
++   srcAddress,                                    // NEW: required (GetAddressType<K>)
++   token: token.address,
++   amount: parseUnits(amount, token.decimals),
++   action: 'supply',
++ };
++ const result = await sodax.moneyMarket.supply({
++   params,
++   raw: false,                                    // NEW: discriminator
++   walletProvider,                                // NEW: was inside spokeProvider in v1
++ });
++ if (!result.ok) {
++   // result.error: SodaxError with feature: 'moneyMarket', context.action: 'supply'
++   return;
++ }
++ const { srcChainTxHash, dstChainTxHash } = result.value;   // TxHashPair, not single hash
+
+  const successData: ActionSuccessData = {
+    /* … */
+-   destinationChainId: token.xChainId,            // OLD field name
++   destinationChainId: token.chainKey,            // RENAMED
+    txHash: srcChainTxHash,
+  };
+```
+
+## 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. **Forgetting `srcChainKey` + `srcAddress` in params.** TypeScript surfaces this as `error TS1360: Type '{ token, amount, action }' does not satisfy the expected type 'MoneyMarketSupplyParams'`. Add both required fields.
+2. **Borrow/repay default delivery to source.** Omit `dstChainKey`/`dstAddress` if you want same-chain. Don't pass them as the same value as `srcChainKey` / `srcAddress` — let the default kick in.
+3. **`sodax.moneyMarket.getAToken(...)` returns a partial token.** `Erc20Token & { chainKey }`, not a full `XToken` — no `vault` / `hubAsset` on the result. Look up the full `XToken` via `sodax.config.getMoneyMarketToken(chainKey, address)` separately if you need those fields.
+4. **`hubAssets` is gone.** Anything that walked it for vault lookup must use `token.vault` directly.
+5. **`baseChainInfo[chain].id` is gone — entries have `.key`.** Common in `ChainSelector`-style components.
+6. **`spokeProvider.chainConfig.chain.type === 'EVM'`** is gone. Use `getChainType(chainKey) === 'EVM'` from `@sodax/sdk`.
+7. **`Number(chainKey)` returns `NaN` for non-numeric keys.** `ChainKeys.ICON_MAINNET` is `'0x1.icon'`; numeric coercions break.
+
+## Verification
+
+```bash
+pnpm -C <your-app-dir> checkTs
+
+# Targeted scans:
+grep -rE "spokeProvider:\s*\w+|moneyMarketSupportedTokens|\bhubAssets\b" src/
+grep -rE "isMoneyMarketError\b|MoneyMarketError\b" src/
+```
+
+## Cross-references
+
+- v2 money market usage: [`../../integration/features/money-market.md`](../../integration/features/money-market.md).
+- Cross-cutting prerequisites listed in [`../README.md`](../README.md).

package/ai-exported/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).